Context Derivation

Context derivation is the process by which Rensei extracts structured facts from an agent's tool calls in real time, making them available in the Session Inspector's Context Browser tab, the session topology overlay, and future session context budgets.

How It Works

A post-tool-use hook fires after every successful tool invocation during a session. The hook calls deriveContext(toolName, toolInput) - a pure function that applies a heuristic table to the tool name and input, returning zero or more DerivedContextEntry values. Each entry is posted as a type: 'context' activity through the standard activity-ingest path.

export interface DerivedContextEntry {
  contextKey: string
  contextValue: unknown
}

The function is pure - no I/O, no side effects. It can be called on any tool call without risk. If no heuristic matches, it returns an empty array (a no-op).

MCP Tool Name Normalization

MCP tools arrive with a qualified name like mcp__af-code__af_code_search_symbols. The derivation function strips the MCP prefix before matching, leaving the leaf name af_code_search_symbols. This means platform-specific MCP tools match the same heuristic rules as built-in tools.

Heuristic Table

Each row describes which tool name pattern triggers an extraction and what contextKey / contextValue is produced.

Matching Rules by Tool

Viewing Derived Context

The Context Browser tab in the Session Inspector shows the current values of all derived context keys for a live or completed session. Values update in near-real-time via the SSE connection while the session is active.

Example context browser output:

{
  "currentFile": "/src/auth/index.ts",
  "lastEditedFile": "/src/auth/middleware.ts",
  "lastSearch": { "tool": "Grep", "pattern": "requireOrgAccess" },
  "lastGitOp": "git add src/auth/",
  "workingDirectory": "/workspace/platform",
  "lastTestRun": { "command": "pnpm test -- auth" },
  "lastMemoryOp": { "op": "recall", "detail": "auth cookie pattern" },
  "lastSubAgentDispatch": "Write integration tests for checkout"
}

Adding a New Facet

If you need to capture a new context signal from a tool call, add a case to deriveContext in platform/src/lib/sessions/derive-context.ts. The conventions are:

1. Match on the leaf tool name (after MCP prefix stripping) to keep rules portable.
2. Return a JSON-serializable contextValue - no circular references, no class instances.
3. Document the use case in a comment above the case.
4. Keep contextKey names camelCase and scoped to what the facet represents (not what tool produced it).

The function is unit-tested; add test cases in derive-context.test.ts covering the new tool name and at least one edge case (missing input field, empty string, unexpected type).

Relationship to Architecture Context

Context facets derived here feed the platform's graph context injection system. The lastEditedFile and currentFile facets are used to scope knowledge-graph queries to the files the agent is actively working on, so relevant architecture observations are surfaced at the start of the next turn.

Related Pages

• Session Inspector - Context Browser tab displays derived facets live
• Activities API - context entries appear as type: 'context' activities in the feed
• Linear Agent Session - context facets feed into the Linear thought activity body