---
url: /sibyl/api/mcp-context.md
---
# MCP Tool: context

Compile a precise context pack for an agent goal. Context packs are structured for action, not for
generic search browsing.

## Overview

The `context` tool retrieves the memory that matters for a specific goal and groups it into facets
such as active work, decisions, plans, ideas, constraints, artifacts, procedures, gotchas, and
recent sessions. Use it before dispatching or resuming an agent so the agent starts with the working
set it needs.

The `context` tool is the retrieval companion to [`remember`](./mcp-remember.md): `remember` stores
what future agents should not have to relearn, and `context` pulls that material back into a goal.

## Input Schema

```typescript
interface ContextInput {
  // Required
  goal: string; // What the agent is trying to accomplish

  // Retrieval Shaping
  intent?: ContextIntent; // Goal mode (default "build")
  layer?: "wake" | "recall" | "deep_search"; // Retrieval depth (default "recall")
  domain?: string; // Domain/category to scope context
  project?: string; // Project ID to scope the pack; required unless all_projects is true
  all_projects?: boolean; // Read every accessible project on purpose (default false)
  agent_id?: string; // Agent diary identity to include

  // Limits
  limit?: number; // Max total context items, clamped 1-50 (default 24)
  include_related?: boolean; // Include one-hop related graph context (default true)
  related_limit?: number; // Related items per context item (default 3)

  // Output Shaping
  audit?: boolean; // Include full retrieval metadata per item (default false)
  markdown_token_budget?: number; // Size rendered markdown to ~this many tokens (default 4000, max 32000; null renders count-bounded)
}
```

### Intent Values

| Intent     | Use For                              |
| ---------- | ------------------------------------ |
| `build`    | Implementation work (default)        |
| `plan`     | Sequencing, milestones, roadmap work |
| `ideate`   | Brainstorming and idea exploration   |
| `research` | Investigation and evidence gathering |
| `debug`    | Diagnosing failures                  |
| `decide`   | Weighing options, making decisions   |
| `learn`    | Studying unfamiliar territory        |
| `general`  | Unscoped retrieval                   |

Intent shapes which facets are emphasized in the resulting pack. Note that `review` is accepted by
the REST endpoint and the CLI (`sibyl context --intent review`) but is not an MCP intent; the MCP
tool rejects it.

### Retrieval Layers

| Layer         | Behavior                                     |
| ------------- | -------------------------------------------- |
| `wake`        | Compact retrieval for session start          |
| `recall`      | Working context for an active goal (default) |
| `deep_search` | Broad retrieval for research-grade context   |

## Response Schema

```typescript
interface ContextPackResponse {
  goal: string;
  intent: string;
  query: string; // Derived retrieval query
  domain: string | null;
  project: string | null;
  scope: "project" | "all_projects"; // Whether one project bounded the read
  layer: string;
  sections: ContextSection[];
  total_items: number;
  usage_metadata: Record<string, any>; // Exposure-recording metadata
  usage_hint: string;
  markdown: string; // Rendered Markdown view of the pack
}

interface ContextSection {
  facet: string; // active_work, decisions, planning, ideation, ...
  title: string;
  items: ContextItem[];
}

interface ContextItem {
  id: string;
  type: string;
  name: string;
  content: string;
  score: number;
  facet: string;
  reason: string; // Why this item was selected
  source: string | null;
  quality: {
    origin: string | null;
    source: string | null;
    url: string | null;
    created_at: string | null;
    updated_at: string | null;
    valid_at: string | null;
    project_id: string | null;
  };
  metadata: Record<string, any>;
  related: ContextRelatedItem[];
}

interface ContextRelatedItem {
  id: string;
  type: string;
  name: string;
  relationship: string;
  direction: "outgoing" | "incoming";
  distance: number;
  content: string | null; // Neighbor content, when available
  metadata: Record<string, any>;
}
```

### Context Facets

Sections are keyed by facet:

```
active_work, artifacts, constraints, decisions, domain, gotchas,
ideation, planning, procedures, recent_memory, verification
```

## Usage Examples

### Compile Context for a Build Goal

```json
{
  "name": "context",
  "arguments": {
    "goal": "Add refresh-token rotation to the auth service",
    "intent": "build",
    "project": "proj_abc123"
  }
}
```

### Compact Session Start

```json
{
  "name": "context",
  "arguments": {
    "goal": "Resume work on the crawler import adapter",
    "layer": "wake",
    "project": "proj_abc123",
    "limit": 12
  }
}
```

### Deep Research Context

```json
{
  "name": "context",
  "arguments": {
    "goal": "Evaluate vector index options for document search",
    "intent": "research",
    "layer": "deep_search",
    "domain": "retrieval",
    "all_projects": true,
    "limit": 40
  }
}
```

### Include an Agent Diary

```json
{
  "name": "context",
  "arguments": {
    "goal": "Continue the migration rehearsal",
    "intent": "plan",
    "project": "proj_abc123",
    "agent_id": "migration-runner"
  }
}
```

When `agent_id` is set, the pack includes that agent's diary memory alongside normal private and
project raw memory.

## Workflow Patterns

### Dispatch an Agent with Context

```
1. context(goal="<task goal>", project="<project_id>")  --> Compile the pack
2. Hand the pack (or its markdown field) to the agent
3. As the agent works, capture new memory with remember(...)
```

### Context Then Synthesis

```
1. context(goal="...", project="<project_id>", layer="deep_search")  --> Gather working context
2. synthesis_plan(goal="...")                --> Plan a source-grounded artifact
```

## Notes

* `limit` is clamped to the range 1-50 regardless of the value supplied.
* A pack reads one project. Pass `project`, or set `all_projects: true` to read every project the
  caller can access; a call with neither is refused rather than widened. A cross-project pack
  reports `scope: "all_projects"` and its Markdown carries a `Scope: all accessible projects` line.
* Project scope is enforced against the caller's accessible projects. Requesting a project the
  credential cannot access raises a project-access error.
* The `markdown` field is a rendered view of the same pack, convenient for direct prompt injection.
* Context pack compilation is audited per call.
* Enhanced evidence retrieval (`evidence` request field with `retrieval_mode`,
  `reserve_distilled_notes`, and diagnostics) is a REST-only surface on `POST /api/context/pack`;
  the MCP tool does not accept it. See [rest-memory.md](./rest-memory.md#compile-context-pack).

## Error Handling

| Error                              | Cause                                          | Resolution                                              |
| ---------------------------------- | ---------------------------------------------- | ------------------------------------------------------- |
| `Organization context required`    | No org-scoped token                            | Authenticate with an org-scoped token                   |
| `Project access denied: <id>`      | Caller cannot access the project               | Use an accessible project ID                            |
| `A context pack reads one project` | Neither `project` nor `all_projects` was given | Pass `project=<id>`, or `all_projects: true` on purpose |

## Related

* [mcp-remember.md](./mcp-remember.md) - Capture durable memory for later context
* [mcp-reflect.md](./mcp-reflect.md) - Reflect raw notes into memory candidates
* [mcp-search.md](./mcp-search.md) - Unstructured semantic search
* [rest-memory.md](./rest-memory.md) - REST context pack endpoint (`/api/context/pack`)