🧠 local-brain-mcp

# 1. Navigate to your Git repository
cd /path/to/your-project

# 2. Auto-detect installed AI editors and link MCP configuration
npx local-brain init

# 3. Ingest your Git history into the local brain database
npx local-brain ingest

# 4. Check memory database statistics
npx local-brain status

# 5. Restart your AI editor (Claude Code, Cursor, Copilot, Windsurf, Zed)

{
  "mcpServers": {
    "local-brain": {
      "command": "node",
      "args": ["/absolute/path/to/local-brain-mcp/dist/mcp-server.js"],
      "env": {}
    }
  }
}

┌─────────────────────────┐
│   AI Coding Assistant   │
└───────────┬─────────────┘
            │ Tool Invocation (JSON-RPC over stdio)
            ▼
┌─────────────────────────┐
│     Local Brain MCP     │
└───────────┬─────────────┘
            │ Parameterized SQL
            ▼
┌─────────────────────────┐
│  Embedded SQLite DB     │
└─────────────────────────┘

{
  "query": "JWT token expiration bug",
  "file_path": "src/auth/jwt.ts",
  "max_items": 3
}

## Brain Recall: "JWT token expiration bug"
• [src/auth/jwt.ts @ 8a4f12] (fix): JWT refresh race condition — RS256 cert rotates every 24h. Cache public keys with 1h TTL.
• [src/auth/session.ts @ c31d04] (bug): Sessions expire silently on Tuesday UTC maintenance window.

{
  "lesson": "Always use parameterized prepared statements in better-sqlite3 to prevent injection.",
  "category": "convention",
  "file_path": "src/db/queries.ts",
  "importance": 1.5
}

{
  "file_path": "src/db.ts"
}

{
  "id": 42,
  "hard_delete": false
}

{
  "status": "stale",
  "run_invalidation": true
}

{}

local-brain init              # setup wizard — writes MCP config for all detected editors
local-brain ingest            # scan git history and build the brain DB
local-brain ingest --since "6 months ago" --verbose
local-brain status            # show DB memory counts and diagnostics
local-brain prune --invalidate  # detect + remove stale memories
local-brain learn "lesson text" --category convention --file src/db/client.ts
local-brain trace --file src/db/client.ts
local-brain forget --id 42

git history
    ↓
[git-ingest.ts] — filters WIP/typo/format commits + quality assessment
    ↓ duplicate?
[db.ts] — findDuplicateMemory → smart merge (preserves richest summary)
    ↓
[embeddings.ts] — pure-JS TF-IDF feature hashing (384-dim, sub-1ms, zero network)
    ↓
[db.ts] — stores in .git/brain.db (provenance: author, branch, confidence, importance)
    ↓ (on file change)
[invalidation.ts] — marks stale if file changed > 30% (multi-file array support)
    ↓ (on MCP tool call)
[recall.ts] — cosine similarity + multi-factor ranking, scoped to package, capped to 250 tokens
    ↓
Claude Code / Cursor / Copilot / Windsurf / Zed

rank_score = (similarity × 0.45)
           + (scope_boost × 0.20)
           + (recency × 0.10)
           + (confidence × 0.10)
           + (importance × 0.10)
           + (quality × 0.05)
           × status_multiplier   (active=1.0, stale=0.25, deprecated=0.05)

inserted (active)
    → stale   (git-diff invalidation if file changed > 30%)
    → deprecated  (superseded by newer memory or manual forget)
    → deleted (hard prune)

local-brain-mcp/
├── src/
│   ├── cli.ts              # Command-line interface and setup wizard
│   ├── db.ts               # SQLite database management and migrations
│   ├── embeddings.ts       # Code-aware TF-IDF feature hashing vectorizer
│   ├── git-ingest.ts       # Commit filtering and git ingestion pipeline
│   ├── invalidation.ts     # Git-diff staleness detection engine
│   ├── mcp-server.ts       # MCP server definition and tool handlers
│   ├── recall.ts           # Multi-factor ranking and token-capped search
│   ├── schema.sql          # Core SQLite table schemas and triggers
│   └── scoping.ts          # Monorepo package scope and path sanitization
├── tests/
│   ├── mcp-tools.test.js    # MCP protocol and tool integration tests
│   ├── embeddings.test.js   # Vectorizer and cosine math unit tests
│   ├── recall-ranking.test.js # Multi-factor ranking algorithm tests
│   ├── scoping.test.js      # Monorepo scope and path security tests
│   ├── security.test.js     # SQL injection and path traversal tests
│   ├── invalidation.test.js # Diff parsing and threshold tests
│   └── git-ingest.test.js   # Commit filter regex and classifier tests
├── scripts/
│   ├── benchmark.mjs        # Performance benchmark runner
│   ├── copy-schema.mjs      # Build step copying SQL schema to dist
│   └── evaluate-retrieval.mjs # Information Retrieval evaluation runner
├── .github/workflows/ci.yml # Multi-version Node.js CI workflow
├── package.json
├── tsconfig.json
└── README.md

# Clone the repository
git clone https://github.com/cosmiccoder200x-sys/local-brain-mcp.git
cd local-brain-mcp

# Install dependencies
npm install

# Type check
npm run typecheck

# Build TypeScript to dist/
npm run build

# Run unit and integration tests
npm test

# Run performance benchmarks
npm run benchmark

# Run retrieval quality evaluation
npm run eval

npm test   # runs all suites