---
title: Company Brain Context API
description: "The internal Context Engine contract behind Company Brain source routing: `query_context`, provider families, statuses, and MCP/runtime behavior."
---

Company Brain is the product surface. **Context Engine** is the internal API/service boundary that powers its source routing. Developer-facing docs keep the exact names because clients, runtimes, and MCP tools still call `query_context`.

## 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 agent-specific knowledge-base attachments.
- provider options: optional source-specific settings, currently including Hindsight `recall` vs `reflect`.

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

## Provider Families

- `memory`: user-scoped Hindsight/managed memory recall.
- `brain`: tenant-shared ontology-shaped Company Brain pages and facets.
- `wiki`: compiled Company Brain pages.
- `workspace`: permissioned workspace files for the active target.
- `knowledge-base`: tenant/agent Bedrock Knowledge Bases.
- `mcp`: tenant-approved, read-only, search-safe MCP tools.
- `sub-agent`: read-only sub-agent providers, when enabled by the Company Brain v0 work.

## Brain Provider

The `brain` family is the business/domain Company Brain provider. It searches tenant-shared pages and facets materialized from approved [Business Ontology](/concepts/knowledge/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, and the ontology version or reprocess context that shaped the materialized output.

Brain is intentionally separate from:

- `memory`, which reads raw retained observations through Hindsight or the configured memory backend;
- `wiki`, which reads owner-scoped compiled pages;
- authored `knowledge-base` sources, which read operator-uploaded documents.

## 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 dropdown on Company Brain → Sources. For agent-facing use, `reflect` is the preferred default when the caller wants concise answer-like memory output; `recall` is useful for diagnostics and record-level inspection.

## ThinkWork Brain MCP

External MCP-capable agents connect to ThinkWork Brain at `/mcp/context-engine`. The MCP server exposes `query_context` and `list_context_providers` only. It does not expose mutation tools 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 Company Brain can query it by default. Missing declarations are treated as ineligible.

## Runtime Tools

Strands and Pi register `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 Company Brain is enabled for an agent template, runtimes may also expose specialized split tools such as `query_memory_context`, `query_wiki_context`, and `query_brain_context`. These are still Context Engine tools at the API layer: Hindsight memory, compiled pages, and ontology-shaped Brain remain providers behind the Context Engine boundary rather than separate peer tools in normal agent configuration.

`query_brain_context` should be the model's first choice for governed business/domain context. Raw ontology admin APIs are not runtime tools.

## Admin Verification

Admin operators verify source routing from **Company Brain → 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 Bedrock KB, unavailable MCP adapter, or empty Brain 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.
