MCP The Brain

A Model Context Protocol (MCP) server and VS Code Agent Plugin for structured project memory — semantic search over outcomes, patterns, and module knowledge, with automatic lifecycle hook injection.

What It Does

The Brain gives your AI coding assistant (Copilot, Claude, Cursor) access to structured project memory:

• Outcomes — "X worked/failed because Y"
• Patterns — "When doing A, prefer approach B"
• Module Knowledge — "Module M is sensitive to N"
• Bugs — "Non-obvious bug X was caused by Y"
• Agent Workflows — "Agent A produced insight B during run C"
• Quality Metrics — "Metric X measured at Y, target is Z"

Memory entries are stored as .md files in your repo (Git-versioned, diffable), with optional semantic search via Ollama embeddings + LanceDB.

Installation

Option A: VS Code Copilot Agent Plugin (Recommended)

The Brain ships as a host-neutral plugin bundle (.claude-plugin/plugin.json + hooks/ + skills/ + agents/) that VS Code Copilot Chat consumes through two experimental settings. Both Claude Desktop and VS Code read the same files.

1. Clone this repo:

git clone https://github.com/HITM4N84/mcp-the-brain.git

2. Register the plugin in your VS Code settings (user or workspace):

// settings.json — BOTH entries are required
{
  "chat.useCustomAgentHooks": true,
  "chat.pluginLocations": {
    "C:\\path\\to\\mcp-the-brain": true
  }
}

Without chat.useCustomAgentHooks: true, hooks will not fire even with a valid chat.pluginLocations. Both settings are currently marked experimental but are working in VS Code Copilot Chat 0.44.2+.

3. Reload VS Code. The plugin auto-activates and provides:

• MCP Server — brain tools available in chat
• Lifecycle Hooks — SessionStart and UserPromptSubmit fire in VS Code; SubagentStart fires in Claude Desktop only (see Hook Support Matrix below)
• Skills — brain-init, memory-extraction, brain-review
• Agent — brain-reviewer for hygiene audits

4. Initialize your project: Ask Copilot: "Use the brain-init skill to set up brain in this project"

This creates .brain.json and the memory directory structure.

5. Verify the plugin is live: Ask Copilot: "Call brain_status". A healthy response shows totalFires > 0 and lastFire.hook: "SessionStart" after a fresh session. Raw log lives at ~/.brain/logs/hooks.log (JSONL, one line per hook fire).

Hook Support Matrix

| Hook | Claude Desktop | VS Code Copilot 0.44.2+ | |------|----------------|-------------------------| | SessionStart | ✅ fires | ✅ fires | | UserPromptSubmit | ✅ fires | ✅ fires | | SubagentStart | ✅ fires | ❌ not fired |

In VS Code, per-subagent context injection is the orchestrator's responsibility (embed recall_knowledge results into subagent prompts). The SubagentStart script still executes in tests and in Claude Desktop.

Option B: MCP Server Only (without plugin)

If you only want the MCP tools (no hooks, skills, or agents):

1. Add to .vscode/mcp.json:

{
  "servers": {
    "the-brain": {
      "command": "npx",
      "args": ["-y", "@borntorecycle/mcp-the-brain"],
      "cwd": "${workspaceFolder}"
    }
  }
}

2. Create .brain.json in your project root:

{
  "schema": 2,
  "projectName": "Your-Project",
  "memoryRoot": "memories/project",
  "sharedMemoryRoot": "~/.brain/shared",
  "embedding": {
    "provider": "ollama",
    "model": "nomic-embed-text"
  }
}

3. Create memory directories:

appended to `~/.brain/logs/hooks.log` for observability — inspect via the
`brain_status` MCP tool or `Get-Content ~/.brain/logs/hooks.log -Tail 20`.

| Hook | Event | What it does | VS Code | Claude Desktop |
|------|-------|--------------|:-------:|:--------------:|
| **Session Briefing** | `SessionStart` | Injects top 3 most recent validated entries + a one-line plugin-status footer | ✅ | ✅ |
| **Prompt Advisor** | `UserPromptSubmit` | Keyword-matches your prompt against entry titles/tags, injects relevant entries | ✅ | ✅ |
| **Subagent Context** | `SubagentStart` | Filters entries by agent→subsystem mapping from `.brain.json` | ❌ | ✅ |

All hooks are sub-second (local file reads only, no MCP calls, no network).
Logging is fail-soft — a log-write error never blocks hook output

### Optional: Semantic Search

Install Ollama for embedding-powered semantic search:

ollama pull nomic-embed-text

Without Ollama, The Brain works in text-only mode (keyword matching).

---

## Plugin Features

### Lifecycle Hooks

The plugin automatically injects brain context at key moments:

| Hook | Event | What it does |
|------|-------|--------------|
| **Session Briefing** | `SessionStart` | Injects top 3 most recent validated entries |
| **Prompt Advisor** | `UserPromptSubmit` | Keyword-matches your prompt against entry titles/tags, injects relevant entries |
| **Subagent Context** | `SubagentStart` | Filters entries by agent→subsystem mapping from `.brain.json` |

All hooks are sub-second (local file reads only, no MCP calls, no network).

### Skills

| Skill | Purpose |
|-------|---------|
| `brain-init` | Bootstrap a new project for brain usage (creates `.brain.json` + directories) |
| `memory-extraction` | Extract structured knowledge from ADRs and design sessions |
| `brain-review` | Audit brain health: staleness, contradictions, orphans, broken chains |

### Agent

| Agent | Purpose |
|-------|---------|
| `brain-reviewer` | Run brain hygiene checks and produce actionable recommendations (read-only) |

---

## .brain.json Configuration

```jsonc
{
  "schema": 2,
  "projectName": "My-Project",
  "memoryRoot": "memories/project",
  "sharedMemoryRoot": "~/.brain/shared",
  "adrPaths": ["Design_Sessions/"],   // Optional: for scan_uningested_adrs
  "embedding": {
    "provider": "ollama",
    "model": "nomic-embed-text"
  },
  "agentSubsystemMap": {               // Optional: for SubagentStart hook
    "Orchestrator": ["agenticWorkflow"],
    "Debug": ["runtime", "bugs"],
    "Ui-Writer": ["ui", "components"]
  }
}

agentSubsystemMap

Maps agent names to subsystem tags. The SubagentStart hook uses this to filter entries — each agent only sees brain entries relevant to its domain.

If an agent is not in the map (or the field is absent), the hook falls back to showing the 3 most recent entries.

MCP Tools

| Tool | Description | |------|-------------| | recall_knowledge | Search memories by query, subsystem, tags, type | | record_entry | Create a new memory entry | | update_entry | Update or supersede an existing entry | | list_by_subsystem | List entries for a specific module/subsystem | | promote_to_shared | Copy entry to cross-project shared memory | | rebuild_index | Regenerate index + embeddings from .md files | | add_relation | Create a graph edge between two entries | | query_graph | Query the knowledge graph | | memory_stats | Get brain health statistics | | scan_uningested_adrs | Find ADRs not yet extracted into brain | | suggest_from_adr | Generate brain entry suggestions from an ADR |

Architecture

.brain.json                    # Per-project config (in your repo root)
memories/project/              # Project-scoped memory entries (.md + index.json)
~/.brain/shared/               # Cross-project shared memory

Plugin layout (in this repo):

.claude-plugin/plugin.json     # Plugin manifest (VS Code Agent Plugin)
.mcp.json                      # Plugin MCP server definition
hooks/
  hooks.json                   # Hook event → script mapping
  scripts/                     # Hook scripts (local reads, sub-second)
skills/                        # Plugin skills
agents/                        # Plugin agents
src/                           # MCP server source (TypeScript)
dist/                          # Built MCP server (published to npm)

Cross-Tool Compatibility

The plugin uses Claude format (.claude-plugin/plugin.json) which VS Code auto-detects. It works with:

• GitHub Copilot in VS Code
• Claude Code (native Claude plugin format)
• GitHub Copilot CLI

The ${CLAUDE_PLUGIN_ROOT} token is expanded by VS Code at runtime regardless of which AI backend you use.

License

MIT