local-brain-mcp
Local Brain MCP gives AI coding agents a persistent, local-first shared memory over your repo's Git history and engineering decisions.
brain_recall: semantically search memories with filters for category, file path, agent, confidence, and deprecated items, token-capped to 250 tokens.brain_learn: store durable lessons, architecture decisions, bug root causes, fixes, and conventions with attribution, confidence, importance, file scope, and supersession.brain_validate: confirm an existing memory was helpful, record the validating agent, and boost confidence.brain_status: inspect diagnostics, memory statistics, agent breakdown, validation health, contradictions, and storage path.brain_trace: view chronological memory history and agent attribution for a specific file.brain_forget: deprecate or hard-delete memories by ID, text query, or file path.brain_prune: clean stale or deprecated memories and optionally run Git-diff invalidation after refactors.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@local-brain-mcp what recurring bugs have we fixed in the auth module?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shared, local-first memory for AI coding agents.
Local Brain is a Model Context Protocol (MCP) server that indexes your repository's Git history and engineering decisions into an embedded SQLite vector database. Every recall runs in ~3 ms (p50, local benchmark). No network calls. No cloud dependencies.
Claude Code ─┐
Cursor ─┼── Local Brain ── Shared Project Memory
Antigravity ─┤
Copilot ─┘
Windsurf ───┘
Zed ─┘When multiple coding assistants collaborate on the same repository, they share, validate, and evolve the same durable engineering memory — 100% offline, zero cloud egress, zero external database dependencies.
Problem
Standard AI memory tools have fundamental limitations:
Network latency: 150-800ms per recall when memory lives on a remote server
Privacy: Source code sent to foreign servers
Context bloat: Every session floods the context window
Agent isolation: Claude and Cursor operate in silos, each starting from zero
Memory decay: Outdated context from refactored code is never invalidated
Noise: WIP commits and typos pollute the knowledge base
Related MCP server: ProjectMind MCP
Solution
Local Brain MCP addresses each limitation:
Problem | How Local Brain MCP solves it |
150-800ms network latency per recall | ~3 ms p50 (5.7 ms p95, local 1k-memory benchmark) |
Source code sent to foreign servers | 100% on-device, zero egress, total privacy |
Context bloat on every session | Hard 250-token budget cap per recall |
Agent isolation (Claude vs Cursor silos) | Shared multi-agent memory with provenance |
Outdated context from refactored code | Git-diff invalidation marks old memories STALE |
Conflicting or outdated guidelines | Contradiction detection with 0.60x ranking penalty |
WIP/typo commits pollute memory | Quality filter keeps only high-signal lessons |
Monorepo noise across packages | Path-scoped queries, per-package namespacing |
Duplicate memories waste tokens | Smart deduplication and merge on ingest |
Decisions lost over time | Full memory lineage and trace across agents |
Installation
Requires Node.js >= 22.0.0.
# Install globally from npm
npm install -g local-brain-mcp
# Verify
local-brain --versionThen continue with Quick Start below (local-brain init -> ingest -> status).
Quick Start
# 1. Navigate to your Git repository
cd /path/to/your-project
# 2. Auto-detect installed AI editors and link MCP configuration
local-brain init
# 3. Ingest your Git history into the local brain database
local-brain ingest
# 4. Check multi-agent memory statistics
local-brain status
# 5. Start collaborating with Claude Code, Cursor, Antigravity, Copilot, Windsurf, or ZedCLI Experience
╭────────────────────────────────────────────────────╮
│ │
│ ╭────────────╮ │
│ │ ● ● │ │
│ │ >_ │ │
│ │ ● ● ● │ │
│ ╰────────────╯ │
│ │
│ Local Brain MCP │
│ Shared Memory for AI Coding Agents │
│ │
╰────────────────────────────────────────────────────╯
✓ Local Brain initialized successfully
PROJECT retail-gem-quest
MEMORY STORE .git/brain.db
STATUS ● ACTIVE
VERSION 1.3.1
MEMORIES 0
LESSONS 0
AGENTS 0
Ready for AI memory.MCP Tools Reference (7 Tools)
All tools carry complete MCP annotations (readOnlyHint, destructiveHint, idempotentHint) for full protocol compliance.
1. brain_recall
Semantically search your codebase memory across all agents with multi-factor ranking and strict token capping.
Annotations:
readOnly: true,idempotent: trueFormula: Semantic similarity (45%) + File scope (20%) + Recency decay (10%) + Confidence (10%) + Importance (5%) + Cross-agent validation (5%) + Quality score (5%) x Status multiplier x Contradiction penalty.
Parameters:
Parameter | Type | Required | Description |
|
| Yes | Natural language search query (e.g. |
|
| No | Repo-relative file path to focus search scope (e.g. |
|
| No | Maximum memories to return (1-10, default: |
|
| No | Filter by category: |
|
| No | Minimum confidence threshold ( |
|
| No | Include stale and deprecated memories (default: |
|
| No | Optional: restrict to memories created by a specific agent (e.g. |
2. brain_learn
Store a durable lesson, architecture decision, bug root-cause, or team convention with automatic quality filtering, multi-agent attribution, and contradiction checks.
Annotations:
readOnly: false,idempotent: false
Parameters:
Parameter | Type | Required | Description |
|
| Yes | Actionable engineering rule or decision. |
|
| No |
|
|
| No | Primary file this lesson applies to. |
|
| No | Array of related file paths. |
|
| No | Confidence score |
|
| No | Importance multiplier |
|
| No |
|
|
| No | Creating agent identifier (auto-detected if omitted). |
|
| No | ID of older memory replaced by this lesson. |
3. brain_validate
Confirm that an existing memory was helpful and correct during the current coding session. Increments validation count, records the validating agent, and boosts retrieval confidence.
Annotations:
readOnly: false,idempotent: false
Parameters:
Parameter | Type | Required | Description |
|
| Yes | Memory ID to validate. |
|
| No | Validating agent identifier (auto-detected if omitted). |
4. brain_status
Returns brain health, storage diagnostics, multi-agent breakdown, and validation metrics.
Annotations:
readOnly: true,idempotent: true
5. brain_trace
Show complete chronological memory history and agent attribution for a specific file.
Annotations:
readOnly: true,idempotent: true
6. brain_forget
Deprecate or permanently purge specific memories by ID, path, or text query.
Annotations:
readOnly: false,destructive: true,idempotent: true
7. brain_prune
Clean up stale or deprecated memories from the brain after major refactors.
Annotations:
readOnly: false,destructive: true
CLI Commands
local-brain init # Auto-detect AI editors and install MCP configs
local-brain ingest [--commits 500] # Ingest repository git history
local-brain query "<text>" # Test semantic recall directly in terminal
local-brain learn "<lesson>" # Store a manual lesson with optional --agent flag
local-brain validate <id> # Validate and reinforce a memory ID
local-brain memories [--agent <ag>] # List stored memories with filters
local-brain trace <filePath> # Show chronological history for a file
local-brain status # Diagnostics and multi-agent breakdown
local-brain doctor # System and editor configuration checker
local-brain prune [--status stale] # Remove stale or deprecated records
local-brain forget [--id <id>] # Delete or deprecate memories
local-brain --no-color # Disable color output (global option)Multi-Agent Architecture
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Claude Code │ │ Cursor │ │ Antigravity │ │ Copilot │
└───────┬──────┘ └───────┬──────┘ └───────┬──────┘ └───────┬──────┘
│ │ │ │
└──────────────────┼──────────────────┼──────────────────┘
▼
┌─────────────────────────┐
│ Local Brain MCP │
│ (stdio / WAL SQLite) │
└────────────┬────────────┘
▼
┌───────────────────────────────────┐
│ Shared Memory DB │
│ • Multi-factor deterministic rank│
│ • Cross-agent validation boost │
│ • Contradiction detection & penalty │
│ • Project & agent provenance │
└───────────────────────────────────┘For detailed multi-agent documentation, see docs/multi-agent.md and docs/architecture.md.
Memory is local. Vercel does not host the local memory database. Each project's memory is scoped to its repository root under .git/brain.db (or ~/.config/local-brain/brain.db when no repository root applies).
Agent identity is provenance. Agents do not automatically share context unless Local Brain tools (brain_learn, brain_recall, brain_validate) are invoked via MCP.
Supported agents: Claude Code, Cursor, Antigravity, GitHub Copilot, Windsurf, Zed. local-brain init auto-detects all six and writes their MCP configuration. Agents not found on the system are skipped.
Node Version Requirements
Local Brain MCP requires Node.js >= 22.0.0 (matching the better-sqlite3 engine requirement). CI tests Node 22.x and 24.x.
Testing & Evaluation
npm run test # Run complete test suite (unit, integration, multi-agent, concurrency)
npm run typecheck # Validate TypeScript types without emit
npm run benchmark # Measure retrieval latency and SQLite WAL throughput
npm run eval # Evaluate MRR@5 and Precision@3 against benchmark datasetTroubleshooting
Stuck? See docs/troubleshooting.md for installation,
editor integration, recall, and git-hook fixes — or run with DEBUG=local-brain:*
for namespaced debug output.
Contributing
Contributions are welcome — from first-time documentation fixes to code, tests, integrations, and performance improvements.
Browse open issues and look for issues marked
good first issueorhelp wanted.For a substantial change, open an issue first to discuss the approach.
Read the contributor guide, make a focused branch, and include tests where appropriate.
Open a pull request against
mainand describe how you verified the change.
Please also read our Code of Conduct. To report a security vulnerability privately, follow SECURITY.md.
License
MIT © cosmiccoder200x-sys
Available Tools
7 toolsbrain_forgetADestructiveIdempotent
Remove or deprecate specific memories from Local Brain. Can target a memory by ID, file path, or search query. By default deprecates the memory to maintain audit trail; pass hard_delete: true to purge.
Inputs: id, query, file_path, memory_id, +1 more.
brain_learnA
Store a new durable lesson, architecture decision, bug root-cause, or team convention. Includes automatic multi-agent attribution, quality evaluation, deduplication, contradiction detection, and supersession tracking. Examples: "Never use RS256 in dev", "JWT refresh token expires in 7d; rotate on each use".
Inputs: lesson (required), agent, files, category, +5 more.
brain_pruneADestructive
Clean up stale or deprecated memories from the brain. Run this after major refactors to prevent outdated context from polluting recalls. Optionally runs the full git-diff invalidation pass to detect modified/deleted files.
Inputs: status, run_invalidation.
brain_recallARead-onlyIdempotent
Semantically search your local codebase memory across all agents. Returns the most relevant lessons, bug fixes, architecture decisions, and conventions from your git history and AI sessions — filtered to current file and package scope. Results are ranked deterministically with validation boost and contradiction penalties, token-capped to stay within 250 tokens.
Inputs: query (required), category, file_path, max_items, +3 more.
brain_statusARead-onlyIdempotent
Get system diagnostics, memory statistics, multi-agent breakdown, and validation health. Returns total memory count, breakdown by agent, validation counts, contradiction flags, and database storage path.
Inputs: no named parameters.
brain_traceARead-onlyIdempotent
Show all memory entries associated with a specific file across all agents. Returns the full fix history, architecture decisions, past bugs, and agent attribution for that file in chronological order. Includes confidence and status flags.
Inputs: file_path (required).
brain_validateA
Validate that an existing memory was helpful and correct in the current session. Increments the memory validation count, records the validating agent, and boosts confidence.
Inputs: id (required), agent.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have clearly distinct purposes: learn, recall, validate, status, and trace are easy to tell apart. However, brain_prune and brain_forget both involve removing memories, and brain_recall and brain_trace both retrieve memories, so an agent could occasionally hesitate between them.
All tool names follow the same brain_ prefix plus a lowercase verb pattern, such as brain_learn, brain_recall, and brain_forget. The naming is highly consistent and predictable.
Seven tools is a well-scoped size for a local memory management server. Each tool covers a meaningful operation without bloat, and the count feels appropriate for the domain.
The tool set covers the core memory lifecycle: create (brain_learn), read (brain_recall, brain_trace, brain_status), validate (brain_validate), and delete/deprecate (brain_forget, brain_prune). There is no direct way to edit an existing memory's content, but forgetting and relearning can work around that gap.
Maintenance
Related MCP Connectors
Shared memory for coding agents. Stop re-explaining your codebase every session.
Your own memory for every AI: Claude, ChatGPT, Cursor, Zed and more. Brings in 20+ sources.
Codebase intelligence for AI coding agents: graph, git history, docs, decisions, code health.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides AI coding assistants with persistent, context-rich memory of a codebase, including documentation and git history, enabling recall across sessions.105Apache 2.0
- AlicenseCqualityBmaintenanceGives AI coding assistants persistent project memory and semantic code search, running fully locally with no API keys required.56MIT
- AlicenseNot gradedqualityBmaintenanceProvides persistent long-term memory (semantic RAG) for AI coding assistants, enabling them to store and semantically search code and documentation across chat sessions without token limits.5MIT
- AlicenseAqualityCmaintenanceEnables AI coding assistants to query and store a team's historical development experience through semantic search, so lessons and decisions persist across conversations.9153 PyPI1MIT