🔍 Synapse

Your codebase. Fully understood. Zero waste.

The structural code intelligence layer that makes AI assistants dramatically more accurate, efficient, and useful on real-world codebases.

😤 The Problem

You have a large codebase. Your AI assistant doesn't.

Every time you start a new conversation — with Claude, Cursor, or any other AI — it starts completely blind. It has no idea what CartService does, who calls validateEmail, or whether there's a circular import hiding in your auth module. So you do what everyone does:

You paste files. Lots of files.

And the problems stack up fast:

The bigger your codebase, the worse all of this gets.

Related MCP server: CodeGraph

💡 The Solution

Synapse indexes your entire codebase into a local SQLite graph — every symbol, every call edge, every import, every embedding — and serves it to your AI through a Model Context Protocol (MCP) server with 26 precise tools.

Instead of pasting files, your AI asks for exactly what it needs:

AI: "What does CartService depend on?"

Without Synapse           │  With Synapse
────────────────────────────┼──────────────────────────────────
Developer manually locates  │  AI calls outgoing_calls("CartService")
and pastes cart.ts (400     │  Gets: 6 precise edges, file:line
lines) + cartService.ts     │  locations, resolved targets
(280 lines) into context    │  — in ~1 KB, under 100ms
~15,000 tokens consumed     │  ~300 tokens consumed

The result: AI that works from ground truth, not guesswork.

📉 Token Consumption — The Numbers

This is the core business case. Token costs are real. Context limits are real. Latency from giant prompts is real.

Before Synapse

Developer asks: "Refactor CartService to support multiple currencies"

Step 1: Find relevant files (manual, ~5 min)
Step 2: Paste cart.ts          → ~8,000 tokens
Step 3: Paste cartService.ts   → ~6,000 tokens
Step 4: Paste product.ts       → ~4,000 tokens
Step 5: Explain dependencies   → ~1,000 tokens
                               ─────────────────
Total context load:             ~19,000 tokens
                               (before AI even responds)

After Synapse

AI uses Synapse tools automatically:

explore_symbol("CartService")     → ~400 tokens  (definition + callers + callees)
find_references("CartService")    → ~200 tokens  (who depends on it)
get_source("cart.ts", 45, 92)     → ~300 tokens  (only the relevant lines)
outgoing_calls("CartService")     → ~150 tokens  (exact dependencies)
                                  ─────────────────
Total context load:                ~1,050 tokens

That's an 18× reduction in token consumption for this query. At scale — across a team, across hundreds of sessions — this compounds into thousands of dollars saved per month.

Why targeted queries beat file-pasting

🎯 Why Synapse

✅ Ground truth, not guesswork

Synapse reads your actual parsed AST. Every symbol location, every call edge, every import binding comes from the real code — not from a language model's training data. No hallucinated function names. No wrong file paths. No invented APIs.

✅ AI that understands your architecture

The call graph tells the full story: what calls what, what imports what, what's dead, what's a hub. Your AI can answer architectural questions — circular imports, dependency chains, hub identification — that are impossible without this structure.

✅ Works across your entire codebase, instantly

43 languages. Every file indexed. Cross-file references resolved. Semantic search via local embeddings. Whether your repo has 100 files or 100,000, the AI always has an index — not a partial, hallucinated memory.

✅ Fully local — zero data exposure

Everything runs on your machine. The SQLite database lives in your repo. No code is sent to any server. Embedding inference runs locally via Transformers.js. This matters for enterprise codebases, proprietary code, and compliance requirements.

✅ Persistent intelligence

Index once. Query forever. The incremental indexer detects file changes via xxhash and only re-parses what changed. Your AI doesn't need a "warm-up" monologue about your codebase every session — the graph is always ready.

✅ Compatible with any MCP client

Works with Claude Desktop, Cursor, VS Code, and any editor that supports MCP. One index, any client.

🚀 Quick Start

# 1. Install
git clone <repo-url> && cd synapse
./setup.sh          # macOS / Linux
./setup.ps1         # Windows

# 2. Index your project (one time, incremental after that)
synapse init /path/to/your/repo

# 3. Connect to your AI client
synapse configure /path/to/your/repo

# 4. (Optional) Enable semantic search — 23 MB one-time download
synapse embed /path/to/your/repo

# Done. Open your AI client and ask about your code.

🛠️ Tech Stack

📦 Installation

Requirements: Node.js ≥ 20, pnpm 9.12+

git clone <repo-url>
cd synapse
./setup.sh

git clone <repo-url>
cd synapse
./setup.ps1

git clone <repo-url>
cd synapse
setup.bat

The setup script handles everything: verifies Node ≥ 20, installs pnpm 9.12 via corepack, builds all packages, links synapse + synapse-mcp globally, and writes .vscode/mcp.json.

{
  "servers": {
    "synapse": {
      "type": "stdio",
      "command": "node",
      "args": [
        "${workspaceFolder}/packages/mcp-server/dist/bin.js",
        "--root", "${workspaceFolder}",
        "--db",  "${workspaceFolder}/.synapse/graph.db"
      ]
    }
  }
}

💻 CLI Reference

synapse <command> [options]

🔄 Keeping the Index Fresh — 3 Sync Modes

Synapse has three distinct modes for handling codebase changes. You don't need all three — pick what fits your workflow.

Mode 1 — synapse init (on-demand)

Run once, or re-run whenever you want a manual refresh.

synapse init /path/to/repo

• Computes an xxhash for every file on disk

• Compares against stored hashes in SQLite — skips unchanged files instantly

• Re-parses AST only for new or modified files

• Run synapse reindex instead to force a full re-parse (ignores hash cache)

Typical re-run on a large repo: a few seconds, not minutes.

Mode 2 — synapse watch (live, manual)

Long-running process in a terminal. Keeps the DB warm as you code.

synapse watch /path/to/repo

• Does one full incremental index on startup (same as init)

• Then starts a chokidar file watcher — reacts to every save/create/delete

• Debounced — rapid saves don't trigger a parse storm (default 250 ms)

What it logs on each event:

[+] src/cart.ts        12 sym / 34 edge  (43ms)   ← file changed/added
[-] src/old.ts                                     ← file deleted → symbols removed
[r] resolved 5 imports + 12 edges  (8ms)           ← cross-file references re-resolved

Deleted files are fully cleaned up — all their symbols are removed and incoming edges are nulled.

Mode 3 — MCP server auto-sync (always-on, zero config)

No command needed. This runs automatically every time the MCP server starts (i.e., when VS Code loads it).

What it does, in order:

1. Lock check — tries to acquire a file lock. If another MCP instance is already watching → silently backs off (avoids duplicate watchers)

2. Crash recovery — if a previous index run crashed mid-way (indexing=true left in the manifest) → forces a clean full reindex automatically

3. HEAD check — compares the current git HEAD to last_indexed_head in the DB. If HEAD changed (you pulled, switched branches, rebased) → triggers an incremental reindex before serving any tool calls

4. Chokidar watcher — starts the same live watcher as Mode 2 in the background

This is why you never need to manually re-run init after switching branches. The MCP server catches the HEAD change on next startup and reindexes silently.

Which mode should you use?

🔌 MCP Server

26 tools and 3 resources over stdio (default) or HTTP.

# stdio — VS Code / Claude Desktop
node packages/mcp-server/dist/bin.js \
  --root /path/to/repo \
  --db   /path/to/repo/.synapse/graph.db

# HTTP — remote, containerized, or shared deployments
node packages/mcp-server/dist/bin.js \
  --root      /path/to/repo \
  --db        /path/to/repo/.synapse/graph.db \
  --transport http --port 4000 --host 0.0.0.0 \
  --token     "$CODEGRAPH_TOKEN" \
  --redact-paths

• GET /healthz → { ok: true, sessions: N }

• Stateful sessions via mcp-session-id header

• CORS restricted to localhost when auth is enabled

• Request body limit: 10 MB

🧰 MCP Tools (26)

🏷️ Symbol Lookup — Find anything in your codebase instantly

🔗 Call Graph — Understand dependencies without reading files

🔎 Code Search — Grep smarter, not broader

📊 Source & Metrics — Get exactly the lines you need

📜 Git History — Context that lives outside the code

🏗️ Architecture & Security — Systemic insight

📂 Resources (3)

🔍 grep_code — Smart Three-Backend Chain

  grep_code("pattern")
       │
       ├──► 1. ripgrep (rg)      Rust + SIMD + parallel I/O
       │         ↓ not found / not installed
       ├──► 2. SQLite FTS5       trigram pre-filter → JS regex (no disk I/O)
       │         ↓ no content stored
       └──► 3. Disk scan         readFileSync + JS RegExp (always works)

  All three return: file · line · col · match text · context lines · enclosing symbol

The ripgrep backend streams output asynchronously via spawn() + readline — the event loop is never blocked and there is no memory buffer cap, making it safe for very large repos.

🧠 Semantic & Hybrid Search

Default: Transformers.js — 100% local, zero server

synapse embed /path/to/repo   # ~23 MB one-time download, fully cached after

Alternative: Ollama

ollama serve
synapse embed /path/to/repo --provider ollama --model nomic-embed-text

Once embeddings exist, semantic_search and hybrid_search use them automatically.

🌐 Language Support

🥇 Tier 1 — Full adapters (7 languages)

Symbols · call edges · import resolution · cross-file linking · SCIP-stable IDs

🥈 Tier 2 — Generic adapters (20 languages)

AST + call tracking · no per-language module resolution

C++ Rust Ruby Kotlin Swift PHP Dart Scala Zig Lua Bash Elixir Elm OCaml Solidity Objective-C Vue ReScript and more

🥉 Tier 3 — Text-only (16 languages)

File-level symbols · no AST

Markdown JSON YAML TOML SQL XML HTML CSS GraphQL Protobuf .env Dockerfile and more

43 languages · 100+ file extensions

🗄️ Database Design

SQLite · WAL mode · Schema v9 · Dual connection handles (read-only db + write-on-demand wdb)

Cross-file edge invariant: edges.target_id has ON DELETE CASCADE. Before deleting symbols during reindex, Synapse nulls out incoming cross-file edges first — edges survive, and the resolver re-links them on the next pass.

🏛️ Architecture

┌───────────────────────────────────────────────────────────┐
│                      AI Assistant                          │
│           (Claude · Cursor · any MCP client)               │
│                                                            │
│  "What breaks if I refactor CartService?"                  │
│       ↓ AI calls find_references + call_hierarchy          │
└──────────────────────────┬────────────────────────────────┘
                           │  MCP (stdio or HTTP)
┌──────────────────────────▼────────────────────────────────┐
│                      MCP Server                            │
│    26 tools · 3 resources · 8 KB auto-offload threshold    │
└──────────────────────────┬────────────────────────────────┘
                           │
┌──────────────────────────▼────────────────────────────────┐
│                    @synapse/core                         │
│                                                            │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │   Indexer   │  │   Resolver   │  │   Embeddings    │   │
│  │ tree-sitter │  │ cross-file   │  │ Transformers.js │   │
│  │ 43 languages│  │ edges + BFS  │  │   or Ollama     │   │
│  └──────┬──────┘  └──────┬───────┘  └────────┬────────┘   │
│         └───────────────┬┘                   │            │
│                         └───────────────────-┘            │
│  ┌─────────────────────────────────────────────────────┐  │
│  │          SQLite · WAL mode · Schema v9               │  │
│  │  files · symbols · edges · file_imports · manifest   │  │
│  │  symbols_fts · symbol_embeddings                     │  │
│  │  file_content · file_content_fts                     │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

Design decisions that matter:

🔧 External Dependencies

All optional. Synapse degrades gracefully.

⚙️ GitHub Action

Index on every push, comment API diffs on PRs — keep your AI's index always current:

- uses: ./
  with:
    languages: typescript,python
    db-path: .synapse/graph.db
    comment-on-pr: true
    base-ref: ${{ github.base_ref }}

Outputs: files-indexed · symbols-count · api-changes · db-path

The DB is cached by source-file hash — incremental runs re-parse only what changed.

🐳 Docker

docker build -t synapse .

docker run -p 4000:4000 \
  -v /path/to/repo:/repo:ro \
  -v /path/to/data:/data \
  synapse \
    --db /data/graph.db --root /repo \
    --transport http --host 0.0.0.0 --port 4000 \
    --token "$CODEGRAPH_TOKEN"

Multi-stage build (Node 22 slim). Non-root synapse user in the runtime stage.

🧪 Development

packages/
  core/        @synapse/core       — indexer, resolver, DB, embeddings
  mcp-server/  @synapse/mcp-server — MCP server, HTTP transport, all 26 tools
  cli/         @synapse/cli        — CLI commands
fixtures/
  sample-shopping-app/               — TypeScript fixture used by all tests

pnpm install           # install dependencies
pnpm -r build          # build all packages
pnpm -r test           # 261 tests across 30 files
pnpm -r test --watch   # watch mode

Test coverage: indexing · cross-file resolution · all 26 MCP tools · HTTP transport · Bearer auth · path redaction · Transformers.js embeddings · three grep backends · SCIP ingestor · cycle detection

The Bottom Line

Without Synapse, your AI is reading your codebase one pasted file at a time. With Synapse, it queries a complete, structured graph — and uses a fraction of the tokens to do it.

Less context waste. Fewer hallucinations. Faster answers. Better code.

100% local · No cloud · No telemetry · Works with any MCP client