$ claude    # fresh session, zero context given

> where did I leave off on the payments service?

⏺ brain · get_state(payments-service)
  You were mid-migration to the new ledger API. Decided on Tuesday to keep
  idempotency keys in Postgres (not Redis) — see the outbox pattern note.
  Two TODOs open: retry policy for webhooks, and the staging credentials
  rotation you postponed.

> why did we drop Redis for idempotency?

⏺ brain · search_context("idempotency keys Redis vs Postgres")
  Decision (3 weeks ago): Redis eviction under memory pressure could drop
  keys mid-flight → double-charges. Postgres keeps them transactional with
  the write itself. You benchmarked it: +4ms p99, considered acceptable.

No re-explaining. No re-discovering. No "as I mentioned in another chat".

💡 Why Brain-RAG exists

Every day, AI coding agents start from zero:

• 🔁 You re-explain the architecture you already explained last week
• 🐛 Your agent re-discovers the bug you fixed together a month ago
• ❓ Nobody remembers why a decision was made — only that the code looks like this
• 📉 The context you build in every session — hundreds of hours of it — evaporates

Here's the thing: that context already exists. Claude Code and Codex save every session as a transcript on your machine. Hundreds of conversations documenting every decision, every fix, every dead end — sitting in a folder, unused.

Brain-RAG turns that archive into long-term memory your agents actually use — automatically, from any project, in any session, with any agent.

Brain-RAG is not another chatbot memory, not another vector database, not another RAG demo. It's the memory layer your AI coding workflow is missing — built for real engineering work: decisions with their why, knowledge that gets outdated, projects that span months, and privacy that isn't negotiable.

✨ Features

🎬 Real examples

Things you can ask in a brand-new session, in any project, that Brain-RAG answers from your history:

"How did we solve the 502 on large document uploads?"
 → the fix, the root cause (payload limit mismatch between services), and the date

"What did we decide about tenant isolation in the shared database?"
 → row-level security via entity_id, plus the alternatives you rejected and why

"Have I dealt with this EventBridge → Lambda permission error before?"
 → yes: the exact recurring deploy failure and the ARN fix, from two months ago

"¿Qué reglas disparan la auditoría VCO?"  🇪🇸
 → works in Spanish and English, even mixed in the same history

📦 Installation

Requires Node 22.5+.

npx -y brain-rag install

That's it. The installer registers the memory server with Claude Code and Codex (if present), installs the /brain, /state and /distill commands in both, and prints the optional automation hooks.

{ "mcpServers": { "brain": { "command": "npx", "args": ["-y", "brain-rag", "serve"] } } }

# just the memory server, no commands or hooks
claude mcp add brain --scope user -- npx -y brain-rag serve
codex mcp add brain -- npx -y brain-rag serve

# from source
git clone https://github.com/dasportillo/brain-rag.git && cd brain-rag && ./install.sh

🚀 Quick start

1 · Give your agent its memory back — import the conversations you already have:

npx -y brain-rag import          # index your existing history (runs locally)
npx -y brain-rag import --dry    # preview first

2 · Ask. Open your agent in any project and ask "where did I leave off?", "what do we know about this repo?", "how did I solve X?". The agent queries the brain on its own.

3 · Keep it growing:

"SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "npx -y brain-rag mark-keep", "timeout": 20 }] }],
"SessionEnd":   [{ "matcher": "", "hooks": [{ "type": "command", "command": "nohup npx -y brain-rag ingest >> \"$HOME/.claude/brain/ingest.log\" 2>&1 &", "timeout": 30 }] }]

{ "type": "command", "command": "nohup npx -y brain-rag distill --hook >> \"$HOME/.claude/brain/distill.log\" 2>&1 &", "timeout": 30 }

🏗️ Architecture

Two layers, one principle: raw history is never lost, distilled knowledge is never untraceable.

flowchart LR
    A["📜 Claude Code transcripts<br/>~/.claude/projects"] --> C
    B["📜 Codex rollouts<br/>~/.codex/sessions"] --> C
    C["Ingest<br/><i>opt-in · redact secrets · index</i>"] --> D[("🧠 brain.db<br/><i>one local file</i>")]
    D --> E["Layer 1 · Raw archive<br/><i>every conversation, searchable</i>"]
    D --> F["Layer 2 · Distilled memories<br/><i>decisions · bugs · solutions<br/>+ provenance + lifecycle</i>"]
    E --> G["MCP server"]
    F --> G
    G --> H["🤖 Claude Code · Codex · Cursor ·<br/>any MCP agent, in any project"]

• Layer 1 — the archive. Every opted-in conversation, chunked and indexed. Immutable, complete, the source of truth.
• Layer 2 — the memory. Typed, self-contained knowledge distilled from sessions (decision, bug, solution, architecture, …) with confidence, a temporal lifecycle (active → superseded), and links back to the exact source conversation. Nothing is generated without evidence.
• Retrieval fuses semantic search (paraphrases, cross-language) with exact-term search (error strings, identifiers) and recency — because "the groups-claim bug" and "why is RBAC broken" should both find the same fix.

📊 Benchmarks

Retrieval quality is measured, not eyeballed — a labeled eval of real known-item questions runs against the real corpus, and every retrieval change must beat the previous baseline to ship (method & history).

Ablation on the same set: vector-only search scores Recall@8 0.87 — the exact-term leg is worth ~10 points, which is precisely the class of query (error strings, function names, resource ids) that matters in engineering work.

🔒 Privacy

Your conversations contain API keys, internal architecture, unreleased plans. Brain-RAG is built around that fact:

• ✅ Local by default — local embedding model, local database, zero external calls; works offline. The only data that ever leaves is the optional Brain Teams sync: distilled Layer-2 memories (never raw transcripts), and only after you brain-rag cloud login.
• ✅ Secrets are scrubbed at ingest — JWTs, AWS keys, GitHub/Slack tokens, private keys, password=-style values are redacted before anything is stored.
• ✅ Opt-in by default — no session is indexed unless you opt it in (/brain, BRAIN=1, or an explicit import). Prefer the inverse? brain-rag default on captures every session (opt-out), and brain-rag never add excludes a repo.
• ✅ Right to forget — brain-rag forget <filter> removes sessions from the index; uninstall --purge deletes everything.
• ✅ Retrieved memory is evidence, not instructions — wrapped so past content can never override your agent's current behavior.

❓ FAQ

🗺️ Roadmap

Brain-RAG is evolving from searchable history into a full long-term memory system — the plan and its principles live in docs/ROADMAP.md:

• ✅ Hybrid retrieval (semantic + exact-term + recency), measured by a growing eval suite
• ✅ Layer 2: distilled, typed memories with provenance and temporal lifecycle
• ✅ Multi-agent: Claude Code + Codex sharing one brain
• 🔜 Automatic distillation at session end — knowledge extraction with zero manual steps
• 🔜 get_context: a ready-made project briefing (state + decisions + open TODOs + conflicts) injected when a session starts
• 🔜 Entity graph (services ↔ databases ↔ projects) complementing search
• 🔜 Local reranker — ships only if the benchmark says it earns its latency

🤝 Contributing

Contributions are welcome — and the bar is refreshingly objective: retrieval changes must beat the eval baseline (docs/EVAL-BASELINE.md), everything else needs tests (npm test, no model download required).

Great places to start:

• 🧪 Grow the eval: more case kinds, more languages
• 🔌 Adapters: transcript formats for more agents (Cursor, Windsurf, VS Code agent mode)
• 🧹 The roadmap 🔜 items above

git clone https://github.com/dasportillo/brain-rag.git && cd brain-rag
npm install && npm test