Synaptic

# Synaptic

<p align="center">
  <a href="https://discord.gg/ytX7R2PbNz"><img src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=for-the-badge" alt="Join our Discord"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0--or--later-blue?style=for-the-badge" alt="License: AGPL-3.0-or-later"></a>
  <a href="https://github.com/ColinVaughn/Synaptic/releases"><img src="https://img.shields.io/github/v/release/ColinVaughn/Synaptic?style=for-the-badge" alt="Latest release"></a>
</p>

<p align="center">
  <a href="https://discord.gg/ytX7R2PbNz"><img src="https://invidget.switchblade.xyz/ytX7R2PbNz" alt="Synaptic Discord invite"></a>
</p>

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](https://tree-sitter.github.io/).

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. It all ships as a single static Rust binary
(`synaptic`) with no runtime and no interpreter, 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.

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](https://synapticgraph.com/).

## 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](https://github.com/ColinVaughn/Synaptic/wiki/Installation),
[Quickstart](https://github.com/ColinVaughn/Synaptic/wiki/Quickstart), and
[Assistant Integration](https://github.com/ColinVaughn/Synaptic/wiki/Assistant-Integration)
guides. If you prefer to do it yourself, the manual path is:

```sh
# 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 `.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:

```sh
# 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](https://github.com/ColinVaughn/Synaptic/wiki/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](https://github.com/ColinVaughn/Synaptic/wiki/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](https://github.com/ColinVaughn/Synaptic/wiki/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 <rev1> [rev2]` (or `--since <date>`) 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 <path>` 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 "<kind>:<symbol>"` 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](https://github.com/ColinVaughn/Synaptic/wiki/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-sarg