Track E.2 — brain_context MCP tool #28

New Issue

mathias · 2026-05-25T16:45:28Z

mathias commented

2026-05-25 16:45:28 +00:00

Part of mathias/infra Track E umbrella. Closes the brain↔Claude loop: every session both consumes + feeds the brain.

Goal

New MCP tool brain_context that Claude Code calls at session start (or on demand) to load relevant prior brain knowledge for the current project.

Scope

Tool signature

{
  "name": "brain_context",
  "description": "Return top-N relevant brain entries for the current project context. Use at session start or before a complex task to load prior decisions, corrections, and surprises that apply.",
  "inputSchema": {
    "type": "object",
    "required": ["project_root"],
    "properties": {
      "project_root": {"type": "string"},
      "recent_files": {"type": "array", "items": {"type": "string"}},
      "limit": {"type": "integer", "description": "default 10"}
    }
  }
}

Logic

Extract project name from project_root basename (e.g. /home/mathias/dev/AGENTS/hyperguild → hyperguild).
Run BM25 query on the project name to seed candidates.
For top-3 BM25 hits, call graphstore.Subgraph(slug, 2) to expand neighbours.
Optionally weight neighbours by appearance in recent_files paths (e.g. file internal/graphstore/pg.go boosts graph-related entries).
Rerank merged set (BM25 + graph neighbours, deduped), return top-N as [{slug, title, doc_path, excerpt}].
Excerpt = first 200 chars of body after frontmatter.

Files

ingestion/internal/mcp/tools_context.go — new handler
ingestion/internal/mcp/handlers.go — add tool descriptor in tools()
ingestion/internal/mcp/server.go — add dispatch case in handleCall
Tests: tools_context_test.go exercising no-graph + with-graph paths

Acceptance

tools/call brain_context {project_root: "/home/mathias/dev/AGENTS/hyperguild"} returns ≥3 relevant entries on a populated brain
With Track A graph enabled, 2-hop neighbours surface entries BM25 alone misses (test: query for litellm returns litellm-config-drift even when BM25 doesn't rank it top-3)
task check green

Companion: `claude-context-bootstrap` skill

New skill in mathias/skills repo that documents: at session start, call brain_context with the project root, attach result to the session's working context. Skill author is responsible for shape; this issue ships the tool, not the skill.

Branch policy

If Track E.1 worked on simultaneously, use branch agent/track-e2-brain-context. Merge to main when complete + task check green.

infra Track E umbrella
hyperguild#NN E.1 (parallel: claudewatcher ingestion)
Track A graph (already shipped, this consumes it)

Part of mathias/infra Track E umbrella. Closes the brain↔Claude loop: every session both consumes + feeds the brain. ## Goal New MCP tool `brain_context` that Claude Code calls at session start (or on demand) to load relevant prior brain knowledge for the current project. ## Scope ### Tool signature ```json { "name": "brain_context", "description": "Return top-N relevant brain entries for the current project context. Use at session start or before a complex task to load prior decisions, corrections, and surprises that apply.", "inputSchema": { "type": "object", "required": ["project_root"], "properties": { "project_root": {"type": "string"}, "recent_files": {"type": "array", "items": {"type": "string"}}, "limit": {"type": "integer", "description": "default 10"} } } } ``` ### Logic 1. Extract project name from `project_root` basename (e.g. `/home/mathias/dev/AGENTS/hyperguild` → `hyperguild`). 2. Run BM25 query on the project name to seed candidates. 3. For top-3 BM25 hits, call `graphstore.Subgraph(slug, 2)` to expand neighbours. 4. Optionally weight neighbours by appearance in `recent_files` paths (e.g. file `internal/graphstore/pg.go` boosts `graph-related` entries). 5. Rerank merged set (BM25 + graph neighbours, deduped), return top-N as `[{slug, title, doc_path, excerpt}]`. 6. Excerpt = first 200 chars of body after frontmatter. ### Files - `ingestion/internal/mcp/tools_context.go` — new handler - `ingestion/internal/mcp/handlers.go` — add tool descriptor in `tools()` - `ingestion/internal/mcp/server.go` — add dispatch case in `handleCall` - Tests: `tools_context_test.go` exercising no-graph + with-graph paths ### Acceptance - `tools/call brain_context {project_root: "/home/mathias/dev/AGENTS/hyperguild"}` returns ≥3 relevant entries on a populated brain - With Track A graph enabled, 2-hop neighbours surface entries BM25 alone misses (test: query for `litellm` returns `litellm-config-drift` even when BM25 doesn't rank it top-3) - `task check` green ## Companion: `claude-context-bootstrap` skill New skill in `mathias/skills` repo that documents: at session start, call `brain_context` with the project root, attach result to the session's working context. Skill author is responsible for shape; this issue ships the tool, not the skill. ## Branch policy If Track E.1 worked on simultaneously, use branch `agent/track-e2-brain-context`. Merge to main when complete + task check green. ## Related - infra Track E umbrella - hyperguild#NN E.1 (parallel: claudewatcher ingestion) - Track A graph (already shipped, this consumes it)

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: mathias/hyperguild#28

Track E.2 — brain_context MCP tool #28