CodeGraph

Synaptic is a source-grounded code maintenance platform built around three connected systems:API maintenance,repository memory, and a persistentknowledge graph. Together they let an engineer or AI assistant understand what the code does, remember what has happened to it, and make bounded repairs without guessing.
- API maintenancekeeps external dependencies and SDKs safe to change. Dependency bots can tell you a new version exists; Synaptic inventories the APIs your code actually uses, detects source-grounded breaking changes, finds the affected call sites, plans a bounded repair in an isolated worktree, verifies graph invariants and selected tests, and only publishes a draft PR when the evidence is complete.
- Repository memorypreserves the history that usually lives in people, chats, failed branches, incident notes, and old PRs. It records previous changes, regressions, decisions, procedures, verification results, and external artifacts as source-linked evidence, then retrieves that memory through the CLI or MCP server so future work starts with context instead of archaeology.
- The knowledge graphis the structural map underneath everything. Synaptic turns any folder, monorepo, or federated set of repositories into a persistent, queryable graph of symbols, files, resources, calls, imports, inheritance, SQL usage, dynamic-dispatch hazards, and cross-repo edges across 30+ languages withtree-sitter.

If you do not want to run the MCP server yourself,Synaptic Cloudis a paid hosted MCP service for using Synaptic with your projects:synapticgraph.com.

The easiest path is to ask your AI coding agent to install and configure Synaptic for the current repository, then have it follow theInstallation,Quickstart, and[Assistant Integrationguides. If you prefer to do it yourself, the manual path is:

# 1. Install the binary from this repository cargo install --path bin/synaptic # Or download a prebuilt binary from GitHub Releases, then confirm it works synaptic --version # 2. Build the first graph for your project cd path/to/your/project synaptic extract . # 3. Ask structural questions without rereading the whole codebase synaptic query "authentication flow" synaptic affected parse_config synaptic search --pattern god-class # 4. Keep the graph current as the project changes synaptic update synaptic watch synaptic hook install

For a normal project setup, add a.synapticignoreif there are generated, vendored, or sensitive paths you do not want indexed;extractalso honors.gitignoreand skips common secrets like.envand key files. Usesynaptic hook installwhen you want Git commits, checkouts, and graph merges to keepsynaptic-out/graph.jsonfresh automatically.

Once the graph exists, turn on the higher-level systems as needed:

# Repository memory: ingest history, docs, decisions, and outcomes synaptic memory refresh --root . synaptic memory search "previous auth migration" # API maintenance: configure monitored APIs and check real usage synaptic api init synaptic api discover --json synaptic api coverage --json synaptic api scan --offline --json # AI assistant integration: serve the graph and memory over MCP synaptic serve synaptic install codex --global

The safest mental model: runextractfirst, usequery/affected/searchto explore, add hooks orwatchwhen the project is active, then enablememoryandapiworkflows when you want Synaptic to preserve history or maintain external contracts.

- Structural clarity.God nodes, surprising cross-module connections, import cycles, and community structure are computed for you.
- Impact and foresight.Reverse impact, change forecasting, and speculative test runs answer "what depends on this?" and "what would this change break?" before you touch the code.
- Token economy.Querying a compact graph costs a fraction of feeding raw files to an LLM, so an assistant can answer those questions without loading the repo.
- Confidence you can audit.Every inferred relationship is taggedEXTRACTED,INFERRED, orAMBIGUOUS.
- Scales past one repo.A workspace can federate many repos with real cross-repo edge resolution (export surfaces plus import / tsconfig / module-federation aliases).
- Offline by default.A code-only corpus never makes a network call. The optional semantic pass over docs and papers is the only feature that needs an API key.

A core payoff of querying a compact graph isreading a small answer instead of the whole codebase.query_graphdefaults to a terse, ranked list of the most relevant symbols (a few hundred tokens); passfull=truefor the whole subgraph with its edges. The figures below measure afullsubgraph response (at a 2,000-token budget) on Synaptic's own source (199 Rust files, 56,408 lines,510,966cl100ktokens) -- one such answer to a structural question is~1,950 tokens, versus reading the source files it actually touches:

Across six questions spanning different subsystems, querying the graph used27-38x fewer tokens(about31x overall) than reading the files the answer references:

A query response stays small no matter how big the repo gets (it is capped by the token budget), so the ratio grows with the codebase. Note thegraph.jsonindex itself is large because it encodes every symbol and edge; you never load it into context, you query it and get back only the slice above.

Reproducible.Tokens are exactcl100k_basecounts viacargo run -p synaptic-server --example tokcount. The baseline is the unique source files the result's nodes live in (whole files, the conservative grep-then-read case; it does not count the dead-end files you would open without the graph). Runsynaptic extract .on any repo and compare for yourself.

The analysis tools answer in milliseconds because they run over the in-memory graph, not the source. Criterion micro-benchmarks (dev machine; runcargo bench -p synaptic-synql -p synaptic-refactor):

The 0.6.3 graph-pipeline audit added dedicated Criterion coverage for construction, incremental comparison, and federation (cargo bench -p synaptic-graph -p synaptic-incremental -p synaptic-workspace). On the audit fixtures, one-pass 16 x 500-node federation measured136.1 -> 6.07 ms, a 10k-node topology comparison54.92 -> 9.77 ms, and a 1,000-site duplicate edge240.74 -> 0.56 ms. These are machine-dependent micro-benchmarks; the committed fixtures and growth curves are the reproducible evidence.

Time-traveldiffis build-bound rather than query-bound: the graph delta itself is near-instant, and the cost is building each revision in a throwaway git worktree. Built graphs are cached per commit SHA undersynaptic-out/history/, so a repeat diff of the same commits returns immediately and only the working-tree side is rebuilt.

…