# Synapse MCP — Full Knowledge Base & Technical Specification > Synapse MCP is a persistent, local code-knowledge graph server built in Elixir, operating over the Model Context Protocol (MCP). It converts any codebase into an Abstract Syntax Tree (AST) graph stored in ETS in-memory tables, giving AI coding agents (Claude Code, Cursor, Windsurf, Warp, Antigravity, Copilot, Zed) microsecond structural vision, 30–60% token compression, and zero-breakage refactoring capabilities. Built on the BEAM with OTP supervision, pure Elixir embeddings, and 100% local data sovereignty. --- ## Architecture Synapse MCP is an Elixir umbrella app with three OTP applications: - **synapse_core** — graph engine, indexer, ETS store, embedder, chunker - **synapse_mcp** — MCP protocol layer, tool dispatcher, transport (stdio/HTTP/SSE) - **synapse_pro** — Pro features: graph exploration, safe writes, change review, test quality, knowledge cache, debug trace ### Supervision Tree ``` SynapseCore.Supervisor (one_for_one) ├── SynapseCore.Repo (Ecto/SQLite with SQLCipher) ├── SynapseCore.RepoHeat (ranks repos by query frequency) ├── SynapseCore.Embedder.Native.IdfServer (GenServer + 4 ETS tables) ├── SynapseCore.Embedder.Pipeline (GenStage producer/consumer) ├── Task.Supervisor (SynapseCore.IndexerTaskSupervisor) ├── SynapseCore.Store.SQLiteWriter (single durable write lane) ├── SynapseCore.Indexer.Admission (global concurrency bounder) ├── SynapseCore.Store.ETS (owns 12 named ETS tables) ├── SynapseCore.ScratchpadStore (Agent) ├── SynapseCore.Learn (GenServer) ├── SynapseCore.RouteLearn (GenServer) ├── Registry (unique, SynapseCore.IndexerRegistry) └── DynamicSupervisor (SynapseCore.IndexerSupervisor) └── one Indexer GenServer per registered repo ``` ### ETS Graph Store — 12 Named Tables | ETS Table | Type | Purpose | |---|---|---| | `:synapse_chunks` | set | chunk_id → chunk struct | | `:synapse_index` | bag | {repo_id, file_path} → chunk_ids | | `:synapse_symbols` | set | symbol → chunk_id | | `:synapse_edges` | bag | from_chunk_id → edge | | `:synapse_edge_targets` | bag | to_chunk_id → edge | | `:synapse_behaviour_facts` | set | behaviour/module facts | | `:synapse_file_index` | set | file_path → metadata | | `:synapse_worktree_deltas` | set | git worktree delta overlays | | `:synapse_repo_status` | set | repo_id → indexing status | | `:synapse_learn` | set | agent learning cache | | `:synapse_stats` | set | usage stats | | `:synapse_sys_config` | set | boot status, system config | All reads are direct `:ets` calls on public named tables — no GenServer round-trip. A single `Store.ETS` GenServer serialises writes. This is what gives microsecond query latency. ### Native Elixir Embeddings (BM25F + Random Projection) No external ML runtime. No Python. No NIFs for embeddings. Pure Elixir: - Code-aware tokeniser (camelCase, snake_case, module dots, operators) - BM25F with 3 weighted fields: symbol name (3×), summary (2×), raw_source (1×) - IDF table in ETS (not `:persistent_term` — the literal allocator OOM'd the VM at 50–100MB) - Random projection into 256 dimensions via compile-time projection matrix - L2 normalisation (cosine similarity = plain dot product) - Per-chunk embed: 10–50µs. 1,000 chunks: 10–50ms. ### Shadow Graph (Safe Writes) Before an agent edits a file, `ShadowGraph.simulate/2` builds an ephemeral graph from proposed contents, diffs against baseline ETS chunks, and returns: - Compilation errors (callers that would break) - Contract warnings (changed signatures) - Blast radius (all affected chunks) If anything is unsafe, the write never touches disk. All in-memory, all in Elixir. ### Cross-Repo Edge Resolution `CrossRepoLinker` scans unresolved edges across all registered repos, resolves them against a global ETS symbol index. Language-match and same-repo preferences break ties. Runs entirely in ETS — no file I/O, no database writes. ### Admission Control `Admission` GenServer bounds aggregate file-index workers across all repos. Manual work preempts background. Grants rotate fairly. Permits are reference-tracked; late releases are harmless. --- ## The Problem: Context Window Exhaustion & Silent Breakage Standard AI coding tools rely on `grep`, `find`, and raw file reads, or line-slicing vector embeddings. This creates two failure modes: 1. **Token Exhaustion Loops:** An agent dumps uncompressed 30,000-line context files into the prompt window, burning $0.30–$0.70 per session in wasted API token costs. 70% of agent session time is spent on exploration, not coding. 2. **Silent Breakage:** Text search misses imported function aliases and unqualified calls across sub-packages. The agent edits 2 obvious callers, declares success, and leaves 3 subtle callers broken in production. The agent wasn't dumb — it was lied to by text search. --- ## Tool Surface (13 Consolidated MCP Tools + ask_synapse) | Tool | Actions | What It Does | |---|---|---| | `ask_synapse` | — | Natural-language entry point that routes to the right tool | | `synapse_search_codebase` | `symbol`, `regex`, `semantic` | AST symbol lookup, in-memory regex, vector similarity | | `synapse_explore_graph` | `context`, `callers`, `callees`, `cycles` | Transitive call-graph traversal (1–3 hops) | | `synapse_get_context` | `find`, `edit`, `explain`, `onboard` | Pre-edit safety packs, context discovery, reading order | | `synapse_inspect_files` | `read_files`, `read_chunk`, `count_lines` | AST-aware file reading with outlines | | `synapse_modify_files` | `write_safely`, `find_and_replace`, `delete_chunk` | Staged safe writes with dry-run and auto-rollback | | `synapse_debug_trace` | `resolve_stack`, `trace_behaviour` | Crash stack trace → indexed code locations | | `synapse_change_review` | `impact`, `analyse_diff`, `review_diff` | Blast radius, diff review, broken contracts | | `synapse_test_quality` | `find_tests`, `coverage`, `recommend_test_targets` | Test mapping, coverage gaps, test targets | | `synapse_knowledge_cache` | `save_summary`, `query`, `learn`, `suggest` | Persistent encrypted cache on AST nodes | | `synapse_codebase_insights` | `overview`, `public_api`, `contracts`, `dependencies`, `detect`, `refactor_opportunities` | Architecture metrics, language detection, contracts | | `synapse_manage_repos` | `list`, `register`, `archive`, `restore`, `unregister`, `update_excludes` | Repository lifecycle | | `synapse_indexer_control` | `status`, `health`, `trigger` | Indexer supervision and health | | `synapse_capability_manifest` | — | Self-describing schema for agent discovery | --- ## Benchmark Results ### 500k LOC Elixir Codebase — Security Audit | Metric | grep-based agent | Synapse agent | Delta | |---|---|---|---| | Tokens | 6.2M | 2.5M | −60% | | Cost | $12.63 | $5.05 | −60% | | Time | 16m 56s | 7m 36s | 2.2× faster | | Vulnerabilities | 3 critical | 3 critical | identical | ### Architectural Verification Task | Method | Tool Calls | Latency | Tokens | |---|---|---|---| | Traditional grep + read | 9 | 12,400 ms | 8,400 | | Synapse MCP | 1 | 2 ms | 3,660 | | Improvement | 88.9% fewer | 6,200× faster | 56.4% fewer | --- ## 2026 Codebase Context Engine Comparison | Feature | Synapse MCP | Augment Code | Greptile | CocoIndex | Sourcegraph | |---|---|---|---|---|---| | Execution | Local (12µs) | Cloud (100ms) | Cloud (500ms+) | Python (50ms) | Enterprise Cloud | | AST Traversal | Microsecond | Cloud Vector | Basic | Tree-sitter | SCIP Compiler | | Safe Writes | Yes | No | No | No | No | | Stack Resolution | Yes | No | Partial | No | No | | Worktree Overlay | Sub-50ms | No | No | No | No | | Payload Compression | 30–60% | Partial | No | Partial | Partial | | Data Sovereignty | 100% Local | Cloud | Cloud | Local | Self-Hosted | | Protocol | MCP (stdio+HTTP) | Proprietary | HTTP | Python MCP | Custom API | | Pricing | Free / $19/mo | Credit-based | SaaS | Free | Enterprise | --- ## Blog Posts (Full Library) ### Architecture & Engineering - [How Local Code Knowledge Graphs Work — Inside the Microsecond BEAM Engine](https://synapse-mcp.dev/blog/how-local-code-knowledge-graphs-work.html): Elixir architecture deep dive — ETS, GenServer-per-repo, pure Elixir embeddings, Shadow Graph, the :persistent_term crash. - [Why Synapse MCP Beats Native IDE Indexers](https://synapse-mcp.dev/blog/why-synapse-mcp-beats-native-ide-indexers.html): Cursor Merkle Trees vs Windsurf vectors vs local AST graphs. Staleness, vendor lock-in, semantic guesswork. - [Why AI Coding Agents Need AST Knowledge Graphs, Not Vector Embeddings](https://synapse-mcp.dev/blog/why-ai-agents-need-ast-graphs-not-vectors.html): Vector RAG chops functions in half. AST graphs preserve structure. - [Codebase Context Engines Compared (2026)](https://synapse-mcp.dev/blog/codebase-context-engines-compared.html): Augment Code vs Greptile vs CocoIndex vs Sourcegraph vs Synapse MCP. ### Benchmarks - [2ms vs. 12 Seconds](https://synapse-mcp.dev/blog/2ms-vs-12-seconds-the-ast-graph-benchmark.html): 9 grep calls vs 1 graph query. 6,200× faster, 56.4% token savings. - [Three-Arm Benchmark](https://synapse-mcp.dev/blog/three-arm-benchmark-synapse-vs-codebase-memory-vs-shell.html): Synapse vs codebase-memory-mcp vs shell. 177K tokens (shell) vs ~71K (Synapse) — 60% savings, 2.2× faster. Total session cost is what matters. - [Synapse vs Graphify — Live Head-to-Head Benchmark](https://synapse-mcp.dev/blog/synapse-vs-graphify-live-benchmark.html): Same hardware, torvalds/linux at 74,619 files. Synapse: 37.5× faster discovery, 5.9× lower RAM, 400× faster cold queries, 9.7–15.2× fewer tokens. - [Karpathy's LLM Wiki vs. Synapse MCP: Why Code Needs a Graph, Not Prose](https://synapse-mcp.dev/blog/synapse-karpathy-and-the-code-graph.html): Karpathy's wiki is brilliant for prose — but code isn't prose. Applied to a codebase, prose summaries de-structure the code, break at scale, and stale on every edit. Against Karpathy's LLM Wiki [gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) we keep the code itself as the source of truth with a live, read-write code knowledge graph. - [How Do AI Agents Spend Your Money?](https://synapse-mcp.dev/blog/how-do-ai-agents-spend-your-money.html): Agentic tasks use 1,000× more tokens than standard reasoning. Why and how to fix it. ### Refactoring & Best Practices - [Stop Letting AI Hallucinate Refactors](https://synapse-mcp.dev/blog/stop-letting-ai-hallucinate-refactors.html): Silent breakage, the 12-turn discovery loop, and how caller graphs fix it. - [Why LLMs Code Better with Knowledge Graphs](https://synapse-mcp.dev/blog/why-llms-code-better-with-knowledge-graphs.html): 30–60% token savings, false confidence elimination, multi-app refactoring. - [We Caught Our AI Lying About a Tool Call](https://synapse-mcp.dev/blog/we-caught-our-ai-lying-about-a-tool-call.html): Agent claimed success without evidence. Grounding policies that stop it. ### Pricing - [Why Synapse Pro is $19/month](https://synapse-mcp.dev/blog/why-synapse-pro-is-19-a-month.html): The $20/mo developer tool anchor. Token savings pay for it. --- ## Installation Download from https://synapse-mcp.dev/download — binary for macOS (.dmg), Windows (.msi), Linux (.deb, .rpm, .AppImage). Auto-detects IDE and registers agent rules. ```bash synapse-mcp start synapse-mcp status synapse-mcp enable ``` ### MCP-First Discovery Policy To prevent LLMs from defaulting to `grep`, add this to `AGENTS.md`, `CLAUDE.md`, or `.cursorrules`: ```markdown # MCP-First Discovery Policy (Synapse) You MUST use the synapse MCP server tools as the EXCLUSIVE ENGINE for all initial codebase discovery. Do NOT use grep_search, find, rg, ls, or manual file reading for initial code discovery. ``` ### Editions - **Free ("Golden Graph" — $0):** Full AST indexing (50+ languages), 3 search modes, context retrieval, file inspection, standard writes, unlimited repos. - **Pro ("Shadow Graph" — $19/mo or $190/yr):** Graph exploration (callers/callees/cycles), safe writes, stack trace resolution, test coverage, knowledge cache, change review, unlimited repos. --- ## Tech Stack - **Language:** Elixir (umbrella app, 3 OTP apps) - **Runtime:** BEAM / OTP 27 - **Graph Store:** ETS (12 named tables, lock-free reads, serialised writes) - **Durable Storage:** Ecto + SQLite with SQLCipher (encrypted at rest) - **Embeddings:** Pure Elixir BM25F + random projection (256-dim, 10–50µs per chunk) - **AST Parsing:** Tree-sitter via NIF (50+ languages) - **Packaging:** Burrito (standalone binary for macOS, Linux, Windows) - **Protocol:** MCP (stdio + streamable HTTP + SSE) --- Official Website: https://synapse-mcp.dev Publisher: Myelix Labs (https://myelix.com) GitHub: https://github.com/myelixlabs/synapse-mcp