codebase-synapse

The Problem

AI coding agents (Claude, Cursor, etc.) are powerful — but they work with limited context. They can only see the files you open or feed them. Ask about call chains, architectural patterns, or blast-radius impact, and they guess.

Codebase Synapse fixes this. It indexes your entire repo into a local knowledge graph stored in SQLite, giving your AI agent real answers backed by structural analysis — not hallucinations.

How it works

graph LR    A["📁 Your Codebase"] -->|Tree-sitter| B["🧩 Parser"]    B -->|Symbols & Edges| C["🕸️ Knowledge Graph"]    C -->|SQLite| D["💾 Local DB"]    D -->|52 MCP Tools| E["🤖 AI Agent"]        style A fill:#1a1b26,stroke:#7aa2f7,color:#c0caf5    style B fill:#1a1b26,stroke:#bb9af7,color:#c0caf5    style C fill:#1a1b26,stroke:#9ece6a,color:#c0caf5    style D fill:#1a1b26,stroke:#e0af68,color:#c0caf5    style E fill:#1a1b26,stroke:#f7768e,color:#c0caf5

⚡ Quick Start

1. Index your project (CLI, Zoekt-style)

codebase-synapse index /path/to/your/repo

Indexing runs as a separate CLI command and writes into ~/.codebase-synapse/codebase.db. The first index is the slow one; re-running it only re-indexes changed files. The MCP server never indexes — it only reads the pre-built index.

2. Start the MCP server

npx codebase-synapse

That's it. No Docker. No database setup. No cloud. The server starts via stdio and serves the pre-built index to your MCP client.

Configure your client

{  "mcpServers": {    "codebase-synapse": {      "command": "npx",      "args": ["-y", "codebase-synapse"]    }  }}

{  "mcpServers": {    "codebase-synapse": {      "command": "npx",      "args": ["-y", "codebase-synapse"]    }  }}

npx -y codebase-synapse

✨ What It Does

🔍 Search & Discovery

🕸️ Knowledge Graph

🏗️ Architecture

🔬 Git Archaeology

🧠 Memory & Context

🛡️ Codebase Guard

Included as a bonus: codebase-guard is a PreToolUse hook for Claude Code that blocks writes to high-impact files until the agent runs impact_analysis first.

It uses PageRank scores and blast-radius data from the knowledge graph to identify architectural hubs. No more accidental edits to core files.

🔧 Technical Details

Supported Languages

Rust · Python · TypeScript · JavaScript · Go · Java · C# · PHP · C · C++

Architecture

src/├── parser/       # Tree-sitter parsing & entity extraction├── graph/        # Knowledge graph, PageRank, Leiden clustering├── indexer/      # Repository indexing pipeline├── search/       # BM25 full-text + vector cosine + hybrid RRF├── embedding/    # Candle-based local embeddings (feature-gated)├── memory/       # Persistent & session memory stores├── mcp/          # MCP protocol transport + 52 tool handlers├── git/          # Git archaeology, intent classification, hotspots├── context/      # Budgeted context preparation for AI├── cypher/       # Nom-based Cypher parser → SQL CTE planner├── similarity/   # MinHash + LSH structural similarity├── semantic/     # Multi-signal scoring (tokens, directory, AST)└── cli/          # Interactive TUI installer + artifact export/import

🤝 Contributing

Contributions are welcome! The project uses standard Rust tooling:

# Run testscargo test
# Lintcargo clippy -- -D warnings
# Formatcargo fmt --all

📄 License

Apache-2.0