mathias/hyperguild
1
0
Fork 0
Code Issues 30 Pull Requests 3 Actions Packages Projects Releases Wiki Activity

Track E.2 — brain_context MCP tool #28

New Issue
Closed
opened 2026-05-25 16:45:28 +00:00 by mathias · 1 comment
mathias commented 2026-05-25 16:45:28 +00:00
Owner
Copy Link
Copy Source

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

  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)
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)
mathias commented 2026-05-26 17:24:01 +00:00
Author
Owner
Copy Link
Copy Source

Closed by merge 2726896 + production deploy via image bad0581. brain_context tool callable, BM25 seed + 2-hop graph expansion working. Test fake satisfies both graphsync.Store and graphReader interfaces; no postgres required for unit tests.

Closed by merge 2726896 + production deploy via image bad0581. brain_context tool callable, BM25 seed + 2-hop graph expansion working. Test fake satisfies both graphsync.Store and graphReader interfaces; no postgres required for unit tests.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
agent/ready
Meets the agent-ready contract; authorizes unattended execution
 blocked/client
Waiting on the client
 blocked/supplier
Waiting on a supplier
 blocked/upstream
Waiting on an upstream project or vendor
 risk/high
Irreversible, security-relevant, or control plane
 risk/low
Reversible, local, test-covered
 risk/medium
Touches shared state, deploys or data
 size/l
Too big - split it
 size/m
Under two days
 size/s
Under half a day
 size/xs
Under an hour
 status:dispatch
status:dispatched
status:review
status:reviewing
type/chore
Maintenance, no behaviour change
 type/decision
Human decision required; never agent/ready
 type/docs
Documentation only
 type/feat
New capability
 type/fix
Corrects broken behaviour
 type/ops
Infrastructure, deploy, runtime
 type/research
Investigate; output is a finding, not code
 type/test
Test coverage only
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
renovate-bot mathias
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mathias/hyperguild#28