Skip to main content
Glama
README.md
# mcp-brain

<p align="center">
  <img src="assets/banner.svg" width="900" alt="mcp-brain banner"/>
</p>

<p align="center">
  <a href="#-benchmark-results"><img src="https://img.shields.io/badge/SWE--bench-Hit%4010%3A%2063.4%25-success?style=for-the-badge" alt="SWE-bench Hit@10"/></a>
  <a href="#-token-efficiency"><img src="https://img.shields.io/badge/token%20saving-65%25%20avg-blue?style=for-the-badge" alt="Token saving"/></a>
  <a href="#-quick-start"><img src="https://img.shields.io/badge/zero%20LLM%20cost-βœ“-purple?style=for-the-badge" alt="Zero LLM cost"/></a>
  <a href="#-quick-start"><img src="https://img.shields.io/badge/local--first-βœ“-22c55e?style=for-the-badge" alt="Local-first"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=for-the-badge" alt="MIT License"/></a>
  <img src="https://img.shields.io/badge/python-3.10+-yellow?style=for-the-badge" alt="Python 3.10+"/>
</p>

<p align="center">
  <b>The repo-aware, team-aware, token-efficient memory layer for Claude Code.</b>
</p>

<p align="center">
  <i>Claude Code doesn't fail because it lacks intelligence.<br/>
  It fails because it has zero awareness of your repo and your team.</i>
</p>

---

## πŸš€ TL;DR

**mcp-brain** is a Model Context Protocol (MCP) server that gives Claude Code persistent, structured awareness of your project β€” without burning tokens on context rebuilding.

|  🧠 | **Compressed awareness** in ~100 tokens instead of ~2000                       |
| :-: | :----------------------------------------------------------------------------- |
|  🎯 | **63.4% Hit@10** on SWE-bench Full (2294 real GitHub issues) β€” zero LLM cost   |
|  ⚑  | **Sub-100ms** file prediction (BM25 + code graph + optional semantic reranker) |
|  πŸ‘₯ | **Team-aware**: soft claims, conflict detection, ownership tracking            |
|  πŸ”„ | **Self-healing**: decision lifecycle, automatic staleness, feedback loop       |
| πŸ›‘οΈ | **Local-first**: SQLite, no cloud, no embeddings required, GDPR-friendly       |

---

## πŸ“‘ Table of Contents

* [The Problem](#-the-problem)
* [What mcp-brain Changes](#-what-mcp-brain-changes)
* [In 60 seconds](#️-in-60-seconds)
* [How It Works](#-how-it-works)
* [Memory Hierarchy](#-memory-hierarchy)
* [Prediction Pipeline](#-prediction-pipeline)
* [Decision Lifecycle](#-decision-lifecycle)
* [Architecture](#️-architecture)
* [Benchmark Results](#-benchmark-results)
* [Token Efficiency](#-token-efficiency)
* [Quick Start](#-quick-start)
* [MCP Tools](#-mcp-tools)
* [Use Cases](#-use-cases)
* [FAQ](#-faq)
* [Trade-offs](#️-trade-offs)
* [Roadmap](#️-roadmap)
* [License](#-license)

---

## 🚨 The Problem

<p align="center">
  <img src="assets/workflow.svg" width="850" alt="Workflow comparison: without mcp-brain Claude explores blindly; with mcp-brain Claude starts from structured repo and team awareness"/>
</p>

Without persistent awareness, Claude Code operates **blindly** at the start of every session:

| Without mcp-brain                         | With mcp-brain                        |
| ----------------------------------------- | ------------------------------------- |
| ❌ No idea which files matter              | βœ… Predicted files in top-K            |
| ❌ Re-explores the repo every session      | βœ… Compressed context in ~100 tokens   |
| ❌ No visibility into teammates' WIP       | βœ… Soft claims + conflict detection    |
| ❌ Acts on outdated decisions              | βœ… Decision lifecycle (active β†’ stale) |
| ❌ Burns 2000–5000 tokens just to "orient" | βœ… One YAML block, ready to act        |

**Result without mcp-brain:** wrong file exploration β†’ outdated suggestions β†’ merge conflicts β†’ massive token waste.

---

## ⚑ What mcp-brain Changes

```
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                                                      β”‚
β”‚   Without:  Claude β†’ explores β†’ guesses β†’ retries    β”‚
β”‚             β†’ conflicts β†’ high token usage           β”‚
β”‚                                                      β”‚
β”‚   With:     Claude β†’ predicts β†’ verifies β†’ acts      β”‚
β”‚             β†’ aligned β†’ low token usage              β”‚
β”‚                                                      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
```

### 🧬 Core idea

> Instead of giving Claude **more context**, we give it **structured awareness of reality**.

We track:

* πŸ“Œ what changed (signal extraction from git)
* 🎯 what matters (scoring + lifecycle)
* πŸ‘₯ who's working on what (team claims)
* 🧭 where to act (issue β†’ file prediction)

…and we deliver it **in ~100 tokens**.

---

## ⏱️ In 60 seconds

You drop a one-line ticket into Claude Code:

```
> work on ticket #42 β€” JWT login broken
```

**Without mcp-brain**, Claude starts grep-walking the repo, reading directory listings, opening README, sampling files β€” burning 2000+ tokens before producing the first useful sentence.

**With mcp-brain**, in <100ms Claude receives:

```yaml
predictions:
  - file: src/auth.py
    confidence: high
    why: "path + symbol match: login, jwt"
  - file: src/middleware.py
    confidence: medium
    why: "imports auth (hop 1)"
  - file: src/jwt_utils.py
    confidence: medium
    why: "called_by auth.login"
team_claims:
  - { ticket: 39, author: dev-B, files: [middleware.py] }   # ⚠️ overlap
avoid:
  - "HS256 β€” vulnerable to key confusion. Migrated to RS256 in commit a1b2c3."
decisions:
  - "tokens stored in httpOnly cookie, never localStorage"
```

It's **structured reality**, not regenerated context. Claude can act on the first turn.

---

## πŸ”‘ How It Works

```mermaid
flowchart TD
    subgraph Capture[Capture signals]
        A[Git commit] -->|filtered signals| B[mcp-brain memory]
        C[Session end] -->|structured snapshot| B
    end

    subgraph Predict[Predict where to act]
        E[Ticket opened] --> F[File predictor]
        F -->|top-K files + confidence + why| D[Claude Code]
    end

    subgraph Coordinate[Coordinate team work]
        F -->|overlap check| G[Team claims]
        G -->|conflict warnings| D
    end

    subgraph Learn[Learn from outcomes]
        H[Outcome recorded] -->|precision / recall| I[Feedback loop]
        I -->|demote noisy memories| B
        I -->|supersede stale decisions| B
    end

    B -->|~100-token YAML context| D
```

1. **Capture** β€” git hooks promote only high-signal events (decisions, patterns, things to avoid). Ignored: docs, chore, tests, CI noise.
2. **Compress** β€” three-level memory (L1/L2/L3) auto-assigned by a scoring function (recency 35% + frequency 30% + impact 20% + explicit 15%).
3. **Predict** β€” issue title/body β†’ ranked file list via BM25 + code graph expansion + optional semantic reranker.
4. **Coordinate** β€” soft claims warn before two devs touch the same files.
5. **Self-correct** β€” every closed ticket feeds precision/recall stats; noisy memories are auto-demoted.

---

## 🧠 Memory Hierarchy

<p align="center">
  <img src="assets/memory-levels.svg" width="900" alt="Three-level memory hierarchy: L1 hot context, L2 warm context, L3 cold archive"/>
</p>

Memories aren't dumped into one bag. They're **scored and tiered**, so the high-token slot in your prompt only carries what's signal-dense for *this* moment:

* **L1 β€” hot context** loads automatically every session. Stack, conventions, current branch, recent commits, team claims, active high-confidence decisions. Capped at ~70 tokens.
* **L2 β€” warm context** loads only on demand (`brain_get_decisions`). Historical reasoning, superseded patterns, the *why* behind a past trade-off.
* **L3 β€” cold archive** is never sent to the model. Kept for audit, transparency, and the lifecycle's "undo" path.

The score is a transparent linear formula β€” no black-box embedding similarity. Every memory's level is reproducible and explainable.

---

## πŸ” Prediction Pipeline

<p align="center">
  <img src="assets/prediction-pipeline.svg" width="950" alt="Prediction pipeline: BM25 and IDF scoring, graph expansion, optional semantic rerank"/>
</p>

The predictor is **three deterministic stages**:

| Stage                               | What it does                                                                                    | Cost   |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- | ------ |
| **1. BM25 + IDF**                   | Tokenize issue, match against symbols / identifiers / paths in an inverted index                | ~5 ms  |
| **2. Graph expansion**              | Walk `imports` / `imported_by` / `called_by` from seeds. Score decays per hop (`Γ—0.5`, `Γ—0.25`) | ~10 ms |
| **3. Semantic rerank** *(optional)* | MiniLM (80 MB, CPU/GPU) embeds query + candidates, blends 30% cosine sim with 70% BM25          | ~50 ms |

Every prediction comes back with a `why` field and a full `breakdown`, so you can audit *why* a file was suggested β€” no opaque ranking.

> πŸ’‘ **Default ON.** To run lean (CI / containers without PyTorch), set `MCP_BRAIN_SEMANTIC=0` and the pipeline degrades gracefully to BM25 + graph.

---

## πŸ”„ Decision Lifecycle

<p align="center">
  <img src="assets/decision-lifecycle.svg" width="950" alt="Decision lifecycle: active memories become suspect, stale, or superseded over time and through feedback"/>
</p>

Memories aren't immortal. mcp-brain **assumes you'll change your mind** and bakes the lifecycle in:

* **Age-based decay** β€” after `SUSPECT_DAYS` a memory gets flagged for re-verification. After `STALE_DAYS` it's hidden from prompts.
* **Semantic supersession** β€” write a new memory similar (cosine β‰₯ 0.85) to an old one and the old one is auto-marked `superseded`.
* **Feedback loop** β€” when a memory is shown 3+ times before a *reverted* ticket, it gets demoted automatically. Noisy memories die fast.

This is what makes mcp-brain **safe to leave running for months** without manual cleanup. The L1 stays small and trustworthy; the L3 archives the audit trail.

---

## πŸ—οΈ Architecture

<p align="center">
  <img src="assets/architecture.svg" width="850" alt="mcp-brain architecture: Claude Code talks to the MCP tools layer, which uses memory retrieval, file prediction, feedback, observability, and local SQLite storage"/>
</p>

```mermaid
flowchart TB
    subgraph Client
        CC[Claude Code]
    end
    subgraph Server[mcp-brain server]
        T[MCP Tools layer<br/>brain_init, brain_get_context,<br/>brain_predict_files, ...]
        R[Retriever<br/>+ Compressor]
        P[File Predictor<br/>BM25 + Graph + Semantic]
        F[Feedback Reconciler]
        O[Observability<br/>p50/p95/p99]
    end
    subgraph Storage[Local storage ~/.mcp-brain/]
        DB[(SQLite<br/>memories, sessions,<br/>projects, feedback)]
        IDX[Inverted Index<br/>BM25]
        G[Code Graph<br/>imports/calls]
        Y[YAML claims]
    end
    CC <-->|MCP/stdio| T
    T --> R
    T --> P
    T --> F
    T --> O
    R --> DB
    P --> IDX
    P --> G
    F --> DB
    O --> DB
```

### Repo layout

```
mcp-brain/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ brain/         # core logic: retriever, compressor, scorer, predictor
β”‚   β”‚                  # code_graph, file_indexer, semantic_reranker,
β”‚   β”‚                  # staleness, similarity, feedback loop, observability
β”‚   β”œβ”€β”€ capture/       # git hook signal extraction
β”‚   β”œβ”€β”€ storage/       # SQLite layer
β”‚   └── tools/         # MCP tool definitions (FastMCP)
β”œβ”€β”€ benchmark/         # SWE-bench Lite/Full, Bench4BL, BugLocator harness
β”œβ”€β”€ tests/             # pytest suite (predictor, feedback, observability, ...)
└── assets/            # SVG diagrams used in this README
```

---

## πŸ“Š Benchmark Results

<p align="center">
  <img src="assets/benchmark-results.svg" width="950" alt="SWE-bench Full benchmark results: Hit@K, Recall@K, MAP@K, and comparison vs literature"/>
</p>

We benchmark **file localization** β€” *given a real GitHub issue, can mcp-brain rank the production files the accepted patch actually modified?*

### Dataset: SWE-bench Full

* **2294 real Python bug-fix tasks** from major OSS projects (astropy, django, flask, matplotlib, pandas, pytest, requests, scikit-learn, sphinx, sympy, xarray)
* Ground truth = files modified in the accepted reference patch (test files **excluded** by default β€” strict production-file evaluation)

### Results β€” `mcp-brain` v1.4.0 (BM25 + graph + semantic)

| Metric     |    @1 |    @3 |    @5 |       @10 |
| ---------- | ----: | ----: | ----: | --------: |
| **Hit**    | 24.5% | 43.4% | 53.7% | **63.4%** |
| **Recall** | 20.1% | 36.6% | 46.1% |     55.8% |
| **MAP**    | 24.5% | 28.4% | 30.4% |     31.8% |

* **Instances evaluated**: 2294
* **Errors**: 5 (0.2% failure rate)
* **Avg gold files per issue**: 1.66
* **Avg predicted files**: 9.98 (top-10)

### Honest comparison vs. literature

| System                  | Hit@10 (file loc.) | Cost per query | Notes                             |
|-------------------------| ------------------ | -------------- | --------------------------------- |
| BM25 baseline (vanilla) | ~45–55%            | free           | symbol search only                |
| **mcp-brain v1.4.0**    | **63.4%**          | **free**       | BM25 + graph + semantic, zero LLM |
| Agentless / SWE-agent   | ~70–85%            | $0.10–$2       | LLM-based, multi-step             |

**Reading the numbers:**

* `Hit@5 = 53.7%` β†’ in **more than half** of real issues, the right production file is in top-5 *before Claude reads a single byte*.
* `Hit@10 = 63.4%` β†’ expanded to top-10, almost **2 issues out of 3** have the right file ranked.
* `MAP@1 = 24.5%` β†’ the very first prediction is dead-on for **1 issue out of 4**.
* `0.2% error rate` over 2294 runs β†’ robust pipeline.

### Reproduce it yourself

```bash
# One-time online setup
pip install -e .
pip install -r benchmark/requirements-benchmark.txt
python -m benchmark.adapters.swebench --dataset-name princeton-nlp/SWE-bench \
  --output benchmark/datasets/cache/swebench_full.jsonl
python -m benchmark.prepare_repos \
  --dataset benchmark/datasets/cache/swebench_full.jsonl \
  --repo-cache benchmark/repos

# Offline evaluation (full)
python -m benchmark.run_eval \
  --dataset benchmark/datasets/cache/swebench_full.jsonl \
  --repo-cache benchmark/repos \
  --out benchmark/results/swebench_full.json \
  --report-dir benchmark/reports \
  --top-k 10 --max-hops 2 --use-semantic
```

Reports are emitted as Markdown + HTML in `benchmark/reports/`.

The harness also supports SWE-bench Lite (300 instances), SWE-bench Verified, Bench4BL, and BugLocator β€” see [`benchmark/README.md`](benchmark/README.md).

---

## πŸ’° Token Efficiency

<p align="center">
  <img src="assets/cost-optimization.svg" width="950" alt="Cost optimization: from 2000-5500 orientation tokens per session to roughly 650 tokens with mcp-brain"/>
</p>

### The math

A typical Claude Code session **without** mcp-brain spends thousands of tokens just to orient itself:

| Phase (no mcp-brain)  | Action                                          | ~Tokens       |
| --------------------- | ----------------------------------------------- | ------------- |
| Session start         | List directory, read README, sample files       | 800–2000      |
| Issue handling        | Grep symbols, follow imports, retry wrong files | 1000–3000     |
| Context restore       | Re-explain project conventions                  | 200–500       |
| **Total per session** |                                                 | **2000–5500** |

A session **with** mcp-brain:

| Phase (with mcp-brain) | Action                                           | ~Tokens  |
| ---------------------- | ------------------------------------------------ | -------- |
| Session start          | `brain_get_context` returns compressed L1 YAML   | **~100** |
| Issue handling         | `brain_predict_files` returns ranked top-K + why | **~250** |
| Decision recall        | `brain_get_decisions` (only when needed)         | ~300     |
| **Total per session**  |                                                  | **~650** |

### Estimated saving

```
                        Without          With mcp-brain     Saving
  Session start:    2000 ─────────►       100 tokens        ~95%
  Per session:      2000–5500 ──►       450–950 tokens      40–80%
  Per developer*:   ~1.2M/month ──►    ~400k/month          ~65%
```

<sub>*assuming 100 sessions/month/dev</sub>

### Why this works

* βœ… **No embeddings required** for retrieval (BM25 + code graph)
* βœ… **No vector DB** to query (zero round-trip cost)
* βœ… **No history replay** β€” context is *reconstructed*, not *re-scrolled*
* βœ… **YAML compression** with `default_flow_style=True` and empty-key stripping
* βœ… **L1/L2 split** β€” heavy memory only loaded on demand

> πŸ’‘ The semantic reranker (`use_semantic=True`) is **on by default** and runs locally on CPU/GPU. It does not add LLM cost. Disable with `MCP_BRAIN_SEMANTIC=0` for lean CI.

---

## πŸš€ Quick Start

### Install β€” one command, batteries included

```bash
git clone https://github.com/PierfrancescoLijoi/mcp-brain.git
cd mcp-brain
pip install -e ".[all]"
```

The `[all]` extra installs:

* **language parsers** (Python, JS, TS, Go, Rust, Java, C#) for the code graph
* **semantic reranker** (sentence-transformers + numpy)
* **dev tooling** (pytest, pytest-cov)

### Lean install paths

If you want a smaller footprint, you can pick exactly what you need:

```bash
pip install -e .                      # core only β€” BM25 + graph (no semantic, no parsers)
pip install -e ".[parsers]"           # + multi-language parsers
pip install -e ".[semantic]"          # + semantic reranker (~700 MB w/ PyTorch)
pip install -e ".[dev]"               # + dev tooling
```

### Register with Claude Code

```bash
claude mcp add mcp-brain python /absolute/path/to/run.py
```

On Windows PowerShell:

```powershell
claude mcp add mcp-brain python "C:\path\to\mcp-brain\run.py"
```

### Initialize your project

```bash
mcp-brain init
```

That's it. Open Claude Code in your repo and the L1 context is automatically available via `brain_get_context`.

---

## 🧠 MCP Tools

| Tool                   | Purpose                                     | When Claude calls it           |
| ---------------------- | ------------------------------------------- | ------------------------------ |
| `brain_init`           | Register project, stack, conventions        | Once per repo                  |
| `brain_get_context`    | Load L1 context (~70 tokens)                | Every session start            |
| `brain_get_decisions`  | Load L2 decisions on demand                 | When historical context needed |
| `brain_remember`       | Store a memory; level auto-assigned         | When user makes a decision     |
| `brain_save_session`   | Save end-of-session snapshot                | At session end                 |
| `brain_predict_files`  | Issue β†’ ranked file list with `why`         | When opening a ticket          |
| `brain_start_ticket`   | Start ticket workflow + conflict check      | Workflow orchestration         |
| `brain_record_outcome` | Log ticket outcome (completed/reverted/...) | After ticket closed            |
| `brain_feedback_stats` | Precision/recall window                     | Health checks                  |
| `brain_memory_health`  | Surface noisy memories                      | Debugging                      |
| `brain_observability`  | Full unified dashboard (YAML)               | Ops / CI                       |

### Example L1 context output (~100 tokens)

```yaml
p: {name: my-api, stack: [FastAPI, PostgreSQL]}
s: {branch: feat/auth, wip: "JWT refactor", next: "add refresh token"}

git:
  recent: ["refactor: JWT moved to RS256"]
  changed: [auth.py, middleware.py]

team_claims:
  - {ticket: 42, author: dev-B, files: [middleware.py]}

avoid:
  - "avoid: HS256 β€” vulnerable to key confusion"

decisions:
  - "decision: tokens stored httpOnly cookie, never localStorage"
```

πŸ‘‰ Claude **already knows where to act** before reading a single source file.

---

## πŸ’Ό Use Cases

### 🎯 Solo developer

* Cuts session-start exploration: **βˆ’90% tokens** on the first turn
* Remembers your "I always do it this way" patterns
* Auto-supersedes decisions when you change your mind

### πŸ‘₯ Small team (3–10 devs)

* **Conflict detection** before two devs touch the same files
* Shared decision log with lifecycle (no more "wait, didn't we decide…?")
* File ownership inference from git history

### 🏒 Enterprise (with caveats)

* Local-first, no data leaves the machine β†’ **GDPR / SOC2-friendly**
* Compatible with Managed Identity / on-prem deployments (no cloud calls)
* Token saving compounds: 65% Γ— 100 devs Γ— 100 sessions/month β†’ **measurable infra savings**

---

## ❓ FAQ

<details>
<summary><b>Is this a RAG system or a vector DB?</b></summary>

**No, and on purpose.** mcp-brain is a *structured awareness layer*, not a retrieval-over-embeddings layer. The core retrieval is BM25 + code graph expansion β€” fully deterministic, sub-100ms, no vector DB to maintain. The semantic reranker is an optional 30% blend on top, used only as a tiebreaker. This is why token cost stays predictable and infra is local-first.

</details>

<details>
<summary><b>Why not just use Claude's native context window? It's huge now.</b></summary>

A long context window doesn't fix the problem β€” it makes it cheaper to *waste*. The bottleneck isn't capacity, it's **signal density**. Pasting your whole repo into the context still leaves Claude searching for the right file linearly. mcp-brain pre-ranks reality so the model spends its attention on the right 3 files, not the wrong 30.

</details>

<details>
<summary><b>Will it leak my code or memories anywhere?</b></summary>

No. Storage is SQLite under `~/.mcp-brain/` (local) and `<repo>/.brain/shared/` (versioned with git if you choose). No outbound network calls, no telemetry, no cloud component. The semantic model runs on your CPU/GPU. This makes mcp-brain compatible with GDPR-restricted and air-gapped environments.

</details>

<details>
<summary><b>What if I disagree with a decision mcp-brain remembers?</b></summary>

Write a new memory that contradicts it. Semantic supersession (cosine β‰₯ 0.85) will auto-mark the old one as `superseded`. You can also manually demote via `brain_memory_health` or wait for age-based decay (`SUSPECT_DAYS` / `STALE_DAYS`). The lifecycle assumes you'll change your mind.

</details>

<details>
<summary><b>Does it work with languages other than Python?</b></summary>

Yes for indexing/predicting (BM25 is language-agnostic). The code graph currently supports **Python, JavaScript, TypeScript, Go, Rust, Java, C#** via tree-sitter parsers. Adding a new language is a single registry entry β€” see `src/brain/parsers.py`.

</details>

<details>
<summary><b>How does it compare to SWE-agent / Aider / Cursor?</b></summary>

Different layer of the stack. SWE-agent and similar tools are **autonomous coders** β€” they read, plan, and patch via LLM calls. mcp-brain is the **awareness layer underneath** them. You could pair it with Aider or any MCP-compatible client; it makes whatever LLM you use start from a smarter zero.

</details>

<details>
<summary><b>What's the catch?</b></summary>

Honest answer: file prediction is heuristic. `Hit@1 = 24.5%` means 3 issues out of 4 still need Claude to validate the prediction before acting. mcp-brain *orients*, it doesn't *replace* exploration. That's also why it's free β€” it's a force multiplier, not an oracle.

</details>

---

## ⚠️ Trade-offs

I'm honest about what this is and isn't.

| Strength                                      | Limitation                                                             |
| --------------------------------------------- | ---------------------------------------------------------------------- |
| βœ… Zero LLM cost for retrieval                 | ⚠️ Heuristic-based: edge cases with no symbol/path overlap can miss    |
| βœ… Sub-100ms predictions                       | ⚠️ Requires good commit hygiene (semantic commit messages help)        |
| βœ… Local-first, no cloud                       | ⚠️ No cross-machine sync out of the box (use git for `.brain/shared/`) |
| βœ… Deterministic (replays produce same output) | ⚠️ Hit@1 = 24.5% β†’ orients, doesn't replace exploration                |
| βœ… Works on any size repo                      | ⚠️ Best on medium/large repos (small repos don't benefit much)         |

**This is NOT**:

* ❌ a vector DB memory
* ❌ a RAG system
* ❌ an SWE-agent / autonomous coder
* ❌ a checkpoint / replay tool

**This IS**:

* βœ… a repo-aware, team-aware, **token-efficient awareness layer**
* βœ… a force multiplier for Claude Code, not a replacement

---

## πŸ›£οΈ Roadmap

* [x] BM25 + code graph + semantic reranker
* [x] Decision lifecycle with semantic supersession
* [x] Feedback loop with precision/recall reconciliation
* [x] Observability dashboard
* [x] SWE-bench Full benchmark (2294 instances)
* [x] Multi-language code graph (Python, JS, TS, Go, Rust, Java, C#)
* [ ] Cross-repo memory federation (opt-in)
* [ ] Real-time conflict push (currently pull-based)
* [ ] VS Code extension companion
* [ ] Hosted shared `.brain/` for distributed teams (still local-first per dev)

---

## πŸ§ͺ Run the test suite

```bash
pip install -e ".[dev]"
pytest tests/ -v
```

Expected: full pass on Python 3.10, 3.11, 3.12.

---

## 🀝 Contributing

PRs welcome. Before opening one:

1. `pytest tests/ -v` must pass
2. New behavior needs new tests
3. New MCP tools must be wrapped with `@observed("brain_<name>")`
4. Avoid heavy dependencies for the default install path β€” anything ML-flavored goes behind an optional extra

---

## πŸ“„ License

MIT β€” see [LICENSE](LICENSE).

---

<p align="center">
  <b>Built for Claude Code β€” but the architecture is MCP-standard, so any MCP-compatible client works.</b>
</p>

<p align="center">
  <sub>If mcp-brain saved you tokens, ⭐ the repo. That's the only payment I ask for.</sub>
</p>