Skip to main content
Glama

M8ven Score local-brain-mcp MCP server License: MIT Node Version Website CI npm version npm downloads


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 --version

Then 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 Zed

CLI 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: true

  • Formula: 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

query

string

Yes

Natural language search query (e.g. "JWT refresh token rotation").

file_path

string

No

Repo-relative file path to focus search scope (e.g. "src/auth/jwt.ts").

max_items

number

No

Maximum memories to return (1-10, default: 5).

category

string

No

Filter by category: fix, architecture, convention, bug, manual.

min_confidence

number

No

Minimum confidence threshold (0.0 to 1.0).

include_deprecated

boolean

No

Include stale and deprecated memories (default: false).

agent_filter

string

No

Optional: restrict to memories created by a specific agent (e.g. "cursor").


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

lesson

string

Yes

Actionable engineering rule or decision.

category

string

No

fix, architecture, convention, bug, manual (default: manual).

file_path

string

No

Primary file this lesson applies to.

files

array

No

Array of related file paths.

confidence

number

No

Confidence score 0.0 to 1.0 (default: 1.0).

importance

number

No

Importance multiplier 0.1 to 2.0 (default: 1.0).

importance_level

string

No

low, medium, high, critical (auto-inferred if omitted).

agent

string

No

Creating agent identifier (auto-detected if omitted).

supersedes_id

number

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

id

number

Yes

Memory ID to validate.

agent

string

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 dataset

Troubleshooting

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.

  1. Browse open issues and look for issues marked good first issue or help wanted.

  2. For a substantial change, open an issue first to discuss the approach.

  3. Read the contributor guide, make a focused branch, and include tests where appropriate.

  4. Open a pull request against main and 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 tools
brain_forgetA
DestructiveIdempotent

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_pruneA
Destructive

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_recallA
Read-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_statusA
Read-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_traceA
Read-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

    A4.1/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers