Synaptic

Synaptic is a source-grounded code maintenance platform built around three connected systems:

API maintenance, repository memory, and a persistent knowledge 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.

1. API maintenance keeps 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.

2. Repository memory preserves 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.

3. The knowledge graph is 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 with

tree-sitter.

The graph answers architectural questions, traces reverse impact ("what would this change

break?"), forecasts and speculatively runs changes before you make them, plans safe refactors,

diffs architecture across git history, and audits SQL for performance and security. Memory adds

what the graph cannot infer from the current tree alone. API maintenance uses both to turn

upstream change into evidence-backed repair plans. The engine and terminal workflow ship as a

single static Rust binary (`synaptic`) with no runtime or interpreter. An optional native

`synaptic-ui` addon provides visual single-repository, workspace federation, and MCP setup plus a

searchable Tools view for every Synaptic task on Windows, Linux, and macOS. Synaptic writes

machine-readable graphs alongside human-readable reports and 2D/3D/SVG

visualizations, and exposes an MCP server so an AI coding assistant can use these systems before

grepping or reading files.

Architecture explorer

Turn an existing `graph.json` into a self-contained, offline architecture map:

synaptic chart

The overview ranks source-grounded communities and their strongest exact relationships. Search,

switch themes, or open any subsystem without rebuilding the graph.

Inside a subsystem, select a symbol to isolate its real one-hop dependencies. The inspector shows

incoming and outgoing relations, and each row continues directly to the connected symbol.

The desktop app's App screen checks the GitHub Release published by the release workflow,

downloads the matching archive, verifies its published checksum, and updates the bundled

executables. Add to applications installs it for the current user and makes it searchable from

Windows Start, macOS Applications, or the Linux application menu without administrator access.

Removing the desktop installation does not touch project data, graphs, settings, or a separately

installed CLI.

The desktop app follows the operating system's light or dark preference on first launch and saves

the user's choice after that.

If someone downloads only `synaptic-ui`, its first-run screen automatically downloads the

verified command tools from the latest GitHub Release and places them beside the app. No terminal,

PATH change, or system-wide install is required.

If you do not want to run the MCP server yourself, Synaptic Cloud is a paid hosted MCP

service for using Synaptic with your projects: synapticgraph.com.

For commit-triggered graph sync and verified API or dependency draft repairs, follow the

GitHub automation guide.

Use Synaptic with a project

Start from any repository root. Synaptic writes its index and reports to `synaptic-out/`

and keeps project-specific configuration under `.synaptic/`.

The easiest path is to ask your AI coding agent to install and configure Synaptic for

the current repository, then have it follow the

Installation,

Quickstart, and

Assistant Integration

guides. 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

# Optional: install and launch the native setup UI
cargo install --path bin/synaptic-ui
synaptic-ui

# 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 `.synapticignore` if there are generated, vendored,

or sensitive paths you do not want indexed; `extract` also honors `.gitignore` and skips

common secrets like `.env` and key files. Use `synaptic hook install` when you want Git

commits, checkouts, and graph merges to keep `synaptic-out/graph.json` fresh 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: run `extract` first, use `query` / `affected` / `search` to explore,

add hooks or `watch` when the project is active, then enable `memory` and `api` workflows when

you want Synaptic to preserve history or maintain external contracts.

Why

• 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 tagged `EXTRACTED`,

`INFERRED`, or `AMBIGUOUS`.

• 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.

Highlights

• 30+ languages via tree-sitter, each built and tested in isolation in CI, plus

regex-based extractors for a few formats and script extraction for Vue/Svelte/Astro and

Razor/Blazor. See Languages.

• One command to a full graph plus 2D, 3D, and SVG visualizations, a Markdown report,

and GraphML / Cypher / DOT / Obsidian / wiki exports. See Output Formats.

• Graph queries: relevant-subgraph search, shortest path, node explanation,

reverse-impact ("what depends on this"), find-all-references (`synaptic references` /

the `find_references` tool: everywhere a symbol is used, including the imports and

inheritance a caller-only view misses), and per-file symbol outlines. See

Querying.

• Dynamic-dispatch awareness: event buses (Node EventEmitter, DOM CustomEvent, C# events)

and Electron IPC link a publisher to its subscriber through a channel node, so a handler reached

only across the bus is not a phantom 0-caller. Reflection and dynamic dispatch that cannot be

resolved statically (by-name lookups, dispatch tables, `eval`, dynamic import, .NET/Python/JVM

reflection) are cataloged so a "0 dependents" answer is never mistaken for "safe to change":

`synaptic hazards` (and the `dynamic_hazards` MCP tool) list the sites, and `affected` attaches a

caveat when a symbol is reachable only dynamically.

• Time-travel diff: `synaptic diff [rev2]` (or `--since `) reports how the

graph changed between two git revisions, added/removed dependencies, removed APIs,

architectural drift, new cycles, and hotspots, with a Markdown or self-contained HTML report.

• Architectural search (SYNQL): `synaptic search` runs a small Cypher-inspired query

language over the graph, matching on structure (kind, visibility, LOC, fan-in/out,

variable-length paths) with `count(...)` aggregation, `--explain`, saved queries, and a

library of named patterns (singleton, factory, observer, service-locator, god-class). Not

text search. `synaptic search --file ` lists every symbol defined in a file, ordered

by line, with no query needed.

• Safe refactor: `synaptic refactor rename` / `move` / `extract` emit a confidence-scored

execution plan (`plan.json` + `plan.md`) for an AI agent to apply, then `refactor verify`

rebuilds and checks the graph held (the definition moved/renamed, no references lost, no new

cycles). Synaptic never edits source itself.

• Change forecasting and speculative execution: `synaptic predict` forecasts a change's

blast radius, public APIs at risk, at-risk tests, new cycles, risk score, and a verify

checklist before you edit (`--edit ":"` forecasts a described edit before any

code is written); `synaptic speculate` then applies the change in a throwaway git worktree

and actually runs the at-risk tests plus a build/type-check, reporting real pass/fail — the

ground-truth half of prediction; and `synaptic eval replay` replays history to score forecast

quality against git ground truth (co-edited tests, removed APIs), turning prediction accuracy into

a CI-gateable metric. See

Commands.

• SQL performance & security audit: `synaptic sql audit` flags row-level-security gaps,

over-broad grants, likely SQL injection, missing indexes on filter/foreign-key columns,

`SELECT *`, non-sargable predicates, N+1 patterns, and missing primary keys over the SQL-aware

graph (extraction now models columns, indexes, RLS policies, and grants, and links application

queries to the tables they touch). `synaptic sql advise --query ""` critiques a candidate

query before you write it, cross-referenced against the graph's tables/indexes/RLS. See

SQL Auditing.

• Resource graph (universal, on by default): data/resource files (data JSON and `.mcmeta`

under `assets/`, `data/`, and generated dirs) are indexed as graph nodes, and reference-like

strings inside them bind to the file, resource (by path-derived id like `ns:path`), or code

symbol they name — so `affected` and `query_graph` span code *and* resources. A generated

resource that duplicates a hand-authored one at the same logical path gets a `shadows` edge

(surfaced by `readiness_audit`). Framework-agnostic — a Minecraft `ResourceLocation` is just

one instance of the logical-id shape. Localization JSON also contributes a bounded set of

key-only search aliases (never translated prose), so message catalogs are discoverable

without one graph node per translation. `extract --no-resources` restores the code-only graph.

• Port/readiness audit: `synaptic audit readiness` ranks likely port blockers from graph,

source, and config signals: framework sentinel returns, placeholders/stubs,

generated-resource noise, and project metadata. The MCP `readiness_audit` tool exposes the

same structured report.

• MCP server (stateless protocol 2026-07-28 with legacy compatibility through

2025-11-25) exposing 30 core tools, five vulnerability tools, and five

read-only repository-memory tools over stdio or HTTP:

subgraph search, source reading, reverse-impact, find-all-references, dynamic-dispatch hazards,

PR/working-tree blast radius, change forecasting, predictive test selection, edit-impact prediction,

structural search, time-travel diff, plan-only rename, and SQL audit/advise, plus prompts, completions,

resource subscriptions, and structured tool output. See

MCP Server.

• Source-grounded repository memory: a temporal overlay for previous

changes, failed attempts, regressions, decisions, procedures, verification,

external issue/PR/CI/incident artifacts, semantic community summaries, and

revision-aware file/symbol lineage. Git hooks capture exact commits and

refresh knowledge; principal policy, compact/federated stores, checksummed

team bundles, retrieval benchmarks, and aggregate impact evidence are built

into the CLI and MCP surface.

See Repository Memory.

• Self-maintaining API workflows: `synaptic api` inventories SDK versions,

discovers contracts, records coverage gaps, detects source-grounded breaking

changes, localizes affected call sites, and prepares bounded repairs in an

isolated worktree. Verification fails closed on incomplete evidence, and only

the explicit `publish` stage can create or update an idempotent draft PR. See

API maintenance.

• Dependency vulnerability management: `synaptic vuln` reads every lockfile in

a repository across 12 package ecosystems, matches resolved versions against an

OSV corpus, and decides whether each advisory actually applies here rather than

stopping at a version match. Findings carry an evidence ladder, a dependency

path, a CVSS-derived priority, graph-backed call sites and entry-point

exposure, and a remediation plan; applicable findings with a fixed target can

become bounded, isolated repairs whose patched dependency resolution and

repository tests must pass before Synaptic can create one deterministic draft

GitHub PR or GitLab MR. Checksummed export/import keeps repair and provider

credentials separated, and Synaptic never approves or merges. Accepted risks

are time-boxed and expire on their own. Five MCP tools let assistants check packages, run a

graph-backed scan, inspect exposure evidence, and request a bounded repair

hand-off. Whole-repository scans stay local by default; an agent must opt in

before the dependency list is sent to OSV. See

Vulnerability Management.

• Incremental rebuilds, file watching, and git hooks keep the graph current. See

Incremental Updates.

• Graph-aware PR dashboard with blast radius and merge-order conflict detection. See

PR Dashboard.

Token economy

A core payoff of querying a compact graph is **reading a small answer instead of the whole

codebase**. `query_graph` defaults to a terse, ranked list of the most relevant symbols (a

few hundred tokens); pass `full=true` for the whole subgraph with its edges. The figures

below measure a *full* subgraph response (at a 2,000-token budget) on Synaptic's own source

(199 Rust files, 56,408 lines, 510,966 `cl100k` tokens) -- 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 used **27-38x fewer

tokens (about 31x 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 the `graph.json` index 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 exact `cl100k_base` counts via

`cargo run -p synaptic-server --example tokcount`. The baseline is the unique source files

referenced by the result (whole files, the conservative grep-then-read case; it does not

count the dead-end files you would open without the graph). Run `synaptic extract .` on any

repo and compare for yourself. This is a context-compression measurement, not an end-to-end

agent-savings claim; the paired SWE-bench/BEIR methodology is in BENCHMARKS.md.

Advanced-tool performance

The analysis tools answer in milliseconds because they run over the in-memory graph, not the

source. Criterion micro-benchmarks (dev machine; run `cargo 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 measured 136.1 -> 6.07 ms, a 10k-node topology

comparison 54.92 -> 9.77 ms, and a 1,000-site duplicate edge **240.74 ->

0.56 ms**. These are machine-dependent micro-benchmarks; the committed fixtures

and growth curves are the reproducible evidence.

Time-travel `diff` is 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 under `synaptic-out/history/`, so a repeat diff of the same

commits returns immediately and only the working-tree side is rebuilt.

Accuracy

The token study above is a smoke test on one repo. The relationships Synaptic extracts are

validated separately, against a hand-labeled corpus of mini-repos whose true call edges,

test linkages, blast radii (including distractor nodes that must *not* be flagged), and

cross-language couplings (including look-alikes that must *not* connect) are written out by

hand in a `ground_truth.toml`. A preflight fails the run if any labeled symbol does not resolve,

so a dropped node becomes a loud failure rather than a quietly smaller denominator. Every number

below is exact set-comparison against those labels, reproducible with `synaptic eval corpus`:

Across 11 fixtures / 6 language families / 42 labeled symbols (all resolved): pooled call edges

precision 100% / recall 94% / F1 97% over 18 labeled edges; blast-radius **recall 100% with

0 distractors leaked; affected-test recall 100%** over the labeled linkages with the one

labeled *unrelated* test correctly not selected; cross-language **precision 100% / recall

100% / F1 100%** over 6 labeled couplings with 6 distractor couplings (look-alike routes, a

wrong-service gRPC stub, an unregistered PyO3 helper, ...) correctly not connected. Reading

the numbers honestly:

• No false call edges were observed in this 18-edge corpus (precision 100%); that is a

result on the corpus, not a guarantee at scale.

• Recall is 100% for Python/TypeScript/Java/Go, which resolve cross-file calls. The 50%

on Rust is real and expected: Rust call resolution is intra-file, so a module-qualified

cross-file call is a true miss. Cross-file *reachability* is still preserved through `imports`

edges, which is why blast-radius recall stays 100%.

• Blast radius is scored for noise, not just misses: each seed labels distractor nodes that

must stay out, and none leaked (100% exclusion); the average reported impact-set size equals

the true affected-set size, so the walk is not over-broad.

• Affected-test selection is multi-hop: the `deep-python` fixture changes a leaf three call

hops below its test and still selects it, while a deliberately unrelated test is excluded

(so recall is not bought with precision).

• Cross-language precision is earned across five boundary kinds: a TypeScript

`fetch("/session")` connects to the Rust axum handler that serves it (and a mounted

`/api/users` client reaches its prefix-composed route); a Python gRPC client reaches its tonic

server; a Kafka producer reaches its consumer; a Python `import` reaches its PyO3-exported Rust

function; a JS WebSocket command reaches its C# handler — while every look-alike distractor

(a `/sessions` path, a wrong-service stub, a wrong topic, an *unregistered* PyO3 helper, an

unhandled message) is correctly left unconnected.

The corpus is intentionally small and hand-verified; it validates extraction *correctness* on

representative shapes, not internet-scale coverage. The scale section measures real

repositories. See BENCHMARKS.md for methodology and the ground-truth format.

Prediction calibration

The change-forecast layer attaches a confidence to each predicted co-change. `synaptic eval

calibrate` measures whether that confidence is meaningful: it walks recent history, and for each

commit uses every changed file as a seed, asks the predictor (trained only on prior commits)

which files should co-change, then scores each prediction's confidence against what actually

changed. It reports a reliability table (predicted vs. observed hit rate per confidence

bin), a Brier score, the Brier skill score against an always-guess-the-base-rate

baseline (so the Brier number is interpretable), and expected calibration error.

This is a per-repo property: confidence reflects each repo's commit habits, so run it on yours.

On this repo's own (squash-heavy, synthetic) history the skill score is negative — co-change

prediction there is *worse than guessing the base rate*, because squashed commits touch many

files at once and inflate apparent co-change. That is the metric working: it refuses to dress up

a predictor that is miscalibrated on this history. Methodology in BENCHMARKS.md.

Scale

Extraction throughput across real OSS repositories spanning size tiers and language families,

each cloned at a pinned SHA (`synaptic eval scale`; network + git, opt-in). Each timing is the

median of 5 reps. The 2026-08-12 run covered **10 repositories, 9 language families, 783,928

supported LOC, 71,437 nodes, and 111,851 edges** with no skips. Warm throughput ranged from

44k to 339k LOC/s; median cold-to-warm speedup ranged from 1.4x to 2.8x. The largest checkout

measured here, Humanizer (476,967 supported LOC), took 7.07s cold and 2.69s warm.

Those are machine-specific development-worktree results, not universal or clean-release

claims. "Cold" clears Synaptic's AST cache but the checkout and OS file cache were warm;

incremental timing re-extracts a named unchanged source file and is not patch latency. Full

method, per-repository results, limitations, exact SHAs, and raw samples are in

BENCHMARKS.md.

Extraction quality at scale

Scale measures how *fast* extraction runs; a graph that anchored every declaration to the wrong

line would post identical timings. `synaptic eval quality` measures whether the graph is right,

across 60 pinned repositories covering all 39 shipped languages (80,061 files, 938,001 nodes),

using properties that need no hand labels: anchor exactness, parse and recovery health,

determinism, incremental equivalence, and an independent universal-ctags comparison.

The 2026-08-15 run: pooled anchor exactness 735,198 / 735,493 (99.96%), with **60/60

repositories deterministic and incrementally equivalent** and no skips. 30 of 39 languages are

exact on every checked declaration.

The corpus is language-complete by construction — a test fails when a shipped extractor has no

repository exercising it — and each repository carries pinned bounds, so a regression exits

non-zero naming the repository and metric. The oracle is published as a symmetric difference,

never a recall score: ctags is an independent second opinion, not ground truth. Method,

per-language results, and the defects this benchmark found are in BENCHMARKS.md.

Install

Synaptic builds with a stable Rust toolchain (pinned to 1.97.1 via

rust-toolchain.toml).

# From a clone, installs the `synaptic` binary onto your PATH:
cargo install --path bin/synaptic

# Optional native workspace/MCP setup app (uses `synaptic` from the same directory or PATH):
cargo install --path bin/synaptic-ui

# ...or build it in-tree:
cargo build --release -p synaptic -p synaptic-ui

Prebuilt CLI and optional UI binaries for Linux/macOS/Windows are attached to each tagged

GitHub Release (see the `release` workflow). Optional integrations are

behind feature flags (off by default): `pg` (Postgres introspection), `push` (live

Neo4j/FalkorDB export), and `office` / `gws` / `media` (spreadsheet / Google-Workspace /

audio-video ingest), e.g. `cargo install --path bin/synaptic --features pg,push`. See

Installation,

Desktop UI, and

Configuration.

Once installed, update in place with `synaptic self-update` (verifies a SHA-256

checksum and prompts before replacing the binary). Opt in to a background

"update available" notice with `synaptic self-update --enable` — off by default,

runs at most once a day, and never blocks normal commands. `cargo install` /

source builds can self-update too, but the swap installs the default-feature

prebuilt binary.

Quickstart

# 1. Build the graph for the current directory -> synaptic-out/
synaptic extract .

# 2. Ask the graph a question (returns a relevant subgraph)
synaptic query "authentication flow"

# 3. What would changing a symbol break? (reverse impact)
synaptic affected parse_config

# 4. Serve the graph to an AI assistant over MCP
synaptic serve

`extract` honors `.synapticignore` / `.gitignore` and skips sensitive files (`.env`, keys).

A code-only corpus runs fully offline; the optional LLM semantic pass over docs and papers

(`extract --semantic`) needs an API key (e.g. `OPENAI_API_KEY`). See

Quickstart.

Output artifacts (`synaptic-out/`)

Commands

Community

Questions, ideas, or want to show what you built? Join us on

Discord.

License

GNU Affero General Public License, version 3 or later

(`AGPL-3.0-or-later`), see LICENSE and NOTICE. If you modify

Synaptic and let users interact with it over a network, the license requires you

to offer those users the corresponding source. Historical releases remain

available under the licenses under which they were received. The separately

maintained private Synaptic Platform site and B2B control plane are proprietary

and are not covered by this repository's license.