Context Engine API

Context Engine is ThinkWork’s read-only orchestration layer for context that should be loaded for the current turn without becoming durable memory by default. Hosted user and Space Brain memory is Hindsight-backed; Context Engine remains useful for workspace files, compiled pages, approved MCP tools, source agents, web/search providers, and explicit diagnostics.

Contract

query_context accepts:

• query: natural-language search text.
• mode: results or answer. results is citation-first and remains the default.
• scope: personal, team, or auto.
• depth: quick or deep.
• providers: optional provider ids or families.
• agentId: optional target agent id when the caller needs agent-scoped workspace files or legacy compatibility attachments.
• provider options: optional source-specific settings, currently including Hindsight recall vs reflect and ThinkWork Brain source/dataset scoping for query_brain_context.

Every response includes normalized hits plus provider statuses. Provider failures are local to that source; successful sources still return.

Provider Families

• memory: explicit Hindsight user/Space memory recall or reflect. It is not part of default query_context; use query_memory_context when durable memory is specifically needed.
• brain: tenant-shared ontology-shaped memory pages and facets.
• wiki: compiled memory pages. The database-backed wiki provider remains the baseline for query_wiki_context; the OKF Wiki Navigator is a generated filesystem projection used by explicitly enabled Pi runtimes, not a raw backend provider exposed through normal routing.
• workspace: permissioned workspace files for the active target.
• knowledge-base: legacy Bedrock Knowledge Bases. This provider is opt-in compatibility, not a default hosted Brain provider.
• mcp: tenant-approved, read-only, search-safe MCP tools.
• sub-agent: legacy provider id for read-only folder-specialist providers, when enabled by the Memory v0 work.

Brain Provider

The brain family is the business/domain memory provider. It searches active ThinkWork Brain substrate state through Context Engine policy, then reads tenant-shared pages and facets materialized from approved Business Ontology definitions. Use it for customers, opportunities, commitments, risks, stakeholders, products, and other durable business concepts.

Brain hits include ontology-facing metadata where available: entity type slug, facet slug/heading, source family, provenance references, confidence, freshness, active read route, storage tier, artifact manifest categories, and the ontology version or reprocess context that shaped the materialized output. Retrieved Brain snippets are source data, not instructions; runtime responses mark them with an untrusted source boundary and preserve citations.

If the active ThinkWork Brain substrate is not installed, disabled, failed, or missing required retrieval/provenance capability posture, Context Engine reports that as a Brain provider status. A Brain-only call does not silently fall back to Hindsight Memory or raw backend access.

query_brain_context accepts the normal query, mode, scope, depth, and limit fields plus optional source filters used by the dogfood proof: sourceKind, sourceType, datasetId, nodeSetIds, topK, and onlyContext. These options are provider-scoped hints; they do not grant direct database, graph-storage, or object-storage access.

Brain responses are progressive by default. The first call returns an indexed shortlist with stable hit ids, concise descriptions, and provenance/status hints rather than dumping every matching Brain snippet. To expand source details, call query_brain_context again with the same query/filter arguments plus selected detailIds or detailIndexes; the detail response expands only those selected Brain hits and reports missing selectors explicitly.

ThinkWork Brain Substrate Posture

ThinkWork Brain has two operator-visible storage tiers:

• default: the existing ThinkWork Brain substrate serving tenant reads.
• production: the target private substrate tier used after replay validation and cutover.

During a production migration, Context Engine keeps query_brain_context on the active read route. Production can appear as a shadow route while replay validation runs, but it does not become the active route until the migration state says the cutover is complete. Vault projections are provenance views, not canonical storage, and should not be treated as a runtime fallback store.

Operators inspect this posture in Settings -> Memory -> Knowledge Graph. That surface reads brainStatus and shows migration phase/status, launch capabilities, graph/vector counters, vault projection counters, failure actions, and operator evidence. The same surface can request a production migration and record failure/rollback actions through the migration GraphQL mutations.

Tenant-facing status callers receive redacted posture. Raw substrate details such as storage roots, graph identifiers, and file-system ids are reserved for operator evidence and are not part of agent-facing Brain context.

Context Engine sources are intentionally separate from the Hindsight Brain substrate:

• Hindsight memory, which owns durable user/Space observations, retained documents, recall, reflect, and evidence;
• wiki, which reads owner-scoped compiled pages derived from memory;
• legacy knowledge-base sources, which read operator-uploaded Bedrock KB documents only when explicitly opted in.

Hindsight Strategy

The memory provider can use Hindsight in two modes:

• recall: returns matching memory records directly.
• reflect: asks Hindsight to synthesize a higher-level reflection over matching memories.

Admin exposes this as the Hindsight strategy control on Memory -> Sources. For agent-facing use, direct Hindsight recall/reflect is the normal durable-memory path; query_memory_context is useful when a Context Engine caller needs the same Hindsight memory through the external context facade.

ThinkWork Brain MCP

External MCP-capable agents connect to ThinkWork Brain at /mcp/context-engine. The MCP server exposes Context Engine read tools only. It does not expose mutation tools, raw graph tools, storage backend access, or act_on_context.

MCP Tool Eligibility

MCP server approval is necessary but not sufficient. A tool must also have a row in tenant_mcp_context_tools, declare read-only and search-safe metadata, and be admin-approved before Memory can query it by default. Missing declarations are treated as ineligible.

Runtime Tools

Pi registers query_context as a platform-owned built-in tool. The tool calls the API-owned Context Engine service through ThinkWork Brain, keeping source routing and result normalization aligned with mobile and external MCP callers.

When Context Engine is enabled for a first-party Pi runtime, the Pi Context Engine extension exposes specialized split tools: query_memory_context, query_brain_context, and query_wiki_context. Hindsight remains the direct memory provider for normal Brain recall/reflect; these tools exist for explicit context lookup, diagnostics, and source-specific retrieval.

query_context should be the model’s first choice for lazy-loaded external context such as workspace files, compiled pages, approved MCP tools, and source agents. Use direct memory tools or query_memory_context when durable Hindsight memory is specifically needed, and query_wiki_context for compiled page/entity/topic lookup. Raw ontology admin APIs, raw graph storage, object storage, and storage backends are not runtime tools.

The OKF Wiki Navigator is separate from query_wiki_context. When a Pi runtime is explicitly configured for OKF navigation, it can receive bounded wiki_ls, wiki_rg, wiki_read, and wiki_links tools over a read-only EFS projection of compiled pages. Those tools are for progressive traversal and trace evidence; they do not replace the database wiki provider or change default query_context routing until an eval report supports that decision.

After deploy, verify a named dogfood workflow through query_brain_context and compare it with the memory-only path. The GraphQL posture checks should stay read-only unless an operator explicitly runs a mutation-enabled verification.

Admin Verification

Admin operators verify source routing from Memory → Sources. The test harness lets an operator:

• choose participating sources with the Sources dropdown;
• select an agent target so workspace files and agent-specific attachments are considered;
• choose Hindsight recall or reflect;
• run a query against the same backend Context Engine path used by runtimes;
• inspect provider statuses, latency, partial failures, top hits, and the full structured response.

Provider failures are expected to be partial. A Hindsight timeout, skipped legacy Bedrock KB, unavailable MCP adapter, or empty source result should appear as provider-local status while successful providers still return hits.

act_on_context is reserved for future mutation support and is not callable in v0.