Synapse

Standalone enterprise graph app: reads CBM's code graph read-only, computes its own code analysis (tags, communities, capabilities), and owns a separate business graph (docs, tickets, meetings) that joins into code by (project, qualified_name).

Why this exists

CBM (codebase-memory-mcp) is a pure code knowledge graph — fast, local, C-based. Synapse used to live partly inside CBM's own repo as a TS sidecar that wrote analysis output back into CBM's graph. That coupling proved awkward (no place to put a Decision node, CBM node ids churn on reindex, non-code concepts don't fit CBM's schema) and was reversed: CBM is a strictly read-only target for Synapse. Nothing Synapse computes is ever written back into CBM. See synapse-planning/ideas/architecture-pivot.md for the full decision history.

Architecture

CBM (unchanged, read-only)          Synapse (this repo)
───────────────────────             ────────────────────
query_graph / search_graph  --CLI-->  src/cbm/client.ts (read-only)
                                       src/analysis/*.ts (Louvain, PageRank —
                                         graphology, in-memory)
                                       src/graph/store.ts (SQLite —
                                         persistence only, not Kuzu; Kuzu
                                         was abandoned by its maker Oct 2025)
                                       src/ingest/*.ts (doc → symbol
                                         resolution)
                                       src/llm/*.ts (bounded LLM
                                         classification, ollama)
                                       src/server/index.ts (Fastify, the
                                         HTTP API)
                                       web/ (Vite + React + sigma.js/
                                         graphology UI)

Code facts flow one direction: CBM → Synapse. Nothing Synapse computes flows back into CBM. Synapse's own graph store (SQLite) is the only place tags, communities, capabilities, documents, and cross-graph references live.

Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm 8.0.0 or higher

synapse setup (step 3 below) checks for and installs the following, each with a different policy:

| Tool | Auto-installed by synapse setup? | |---|---| | context-mode | Yes, always — runs npm install -g context-mode if missing | | rtk | Yes, on mac and Linux — prefers brew install rtk; falls back to rtk's own curl \| sh installer only with --allow-remote-install (same remote-script gating as CBM below). No supported install on Windows yet. | | CBM (codebase-memory-mcp) | Only with --allow-remote-install, since the install path pipes a remote script into bash (curl \| bash). Without that flag, synapse setup/synapse doctor print the install command for you to run yourself. |

• rtk on Linux: works out of the box if Homebrew on Linux is installed. Without brew on PATH, run synapse setup --allow-remote-install to let it run rtk's installer (curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh), or run that command yourself and re-run synapse setup.
• context-mode: always installs via npm install -g context-mode — no OS-specific step beyond the Node.js/npm prerequisite above.

Quick Start

@jabbs19/synapse is published to npm (CI publishes on every version tag — see .github/workflows/publish.yml). Install it globally, no repo checkout needed:

1. Install the CLI:

   npm install -g @jabbs19/synapse

   This gives you the synapse command from any directory (no syn alias — that's only set up by the from-source installer below).

2. Verify installation:

   synapse doctor

   Checks machine-wide health (CBM, context-mode, rtk, agent MCP registration) and reports what's missing.

3. Install machine-wide prerequisites:

   synapse setup [--allow-remote-install]

4. Initialize CBM for a repository:

   synapse init <repo-path>
   synapse index cbm <repo-path>

To upgrade later, run synapse upgrade (or npm install -g @jabbs19/synapse again for a specific version).

From source (local development, or heavy customization)

Use this instead of the npm install when you need to modify Synapse itself, run against an unpublished change, or want the syn shell alias.

1. Bootstrap from GitHub:

   The repository is private. Authenticate gh as an account with access first (gh auth switch --user Jabbs19, or set GH_TOKEN to an authorized token), then run:

   gh api -H "Accept: application/vnd.github.raw" repos/Jabbs19/synapse/contents/scripts/install.sh | bash

   The installer clones to ~/.synapse-cli/src, builds and links the CLI, and adds the syn alias to any existing supported shell rc files. It refuses to replace an existing linked checkout; use synapse upgrade for that checkout, or explicitly pass --force/SYNAPSE_CLI_HOME when changing installations.

2. Manual no-gh fallback:

   git clone https://github.com/Jabbs19/synapse.git
   cd synapse

3. Install dependencies, build, and link the CLI globally:

   make install-cli

   Runs npm install, npm run build, and npm link, then appends the syn alias (in each shell's own syntax) to ~/.zshrc, ~/.bashrc, ~/.bash_profile, and ~/.config/fish/config.fish if it's not already there (open a new shell or source the relevant rc file to pick it up). synapse doctor reports whether the alias is present for your current $SHELL.

   npm link symlinks dist/cli/cli.js (the bin entry in package.json) into your global npm bin directory, making the synapse command (and the syn alias) available from any directory. Re-run make install-cli (or just npm run build) after pulling changes — the link stays live, but the compiled output needs to be regenerated.

4. Verify, setup, and initialize — same synapse doctor / synapse setup / synapse init steps as the npm path above.

5. Run the development servers:

   npm run dev:server   # Fastify API, http://127.0.0.1:4100
   npm run dev:web      # Vite dev server, http://localhost:6767

CLI Commands

The Synapse CLI (synapse command after installation) provides the following commands:

Repository Status

synapse status [path]

Shows repo-local initialization state and project identity.

Machine Setup

synapse doctor

Checks machine-wide setup health and prerequisites.

synapse version

Shows the installed CLI's version, plus a git SHA for from-source checkouts (registry installs have no .git directory to read one from).

synapse setup [--allow-remote-install]

Installs and verifies machine-wide prerequisites, including CBM.

Repository Initialization

synapse init [path]

Bootstraps a git repository for use with Synapse.

Indexing Commands

synapse index cbm [path]

Checks and refreshes the CBM index for a repository.

synapse index context [path]

Registers the repository with context-mode.

synapse index align [path]

Reconciles cross-tool project identity (CBM, context-mode, and Synapse).

Telemetry Sync

synapse telemetry sync rtk
synapse telemetry sync cbm
synapse telemetry sync context-mode

Imports tool usage telemetry (rtk token savings, CBM request logs, context-mode stats) into the Synapse server.

Building for Production

npm run build

This produces:

• Server: Compiled TypeScript in dist/ (ready for Node.js)
• Web UI: Optimized static assets in web/dist/ (ready for serving via CDN or HTTP server)

The compiled CLI is available at dist/cli/cli.js.

Running it

Development

Two processes, matching CBM's own daemon + graph-ui split:

npm run dev:server   # Fastify API, http://127.0.0.1:4100
npm run dev:web      # Vite dev server, http://localhost:5173 (or next free port)

Production

Start the server and serve the web UI:

# Start the API server
NODE_ENV=production node dist/server/index.js

# Serve the web UI (from the directory that served the build)
# Use any static HTTP server pointed at web/dist/

Configuration

No .env file — the server derives what it needs. codebase-memory-mcp is expected on PATH (installed per Prerequisites), and the CBM project name comes from this repo's .synapse/config.json (identity.cbm_resolved_project, written by synapse init). Synapse's LLM classification talks to a local Ollama instance only — there are no provider API keys to set.

Optional overrides via environment variables (all have working defaults):

| Var | Meaning | Default | |---|---|---| | SYNAPSE_SERVER_PORT | Fastify port | 4100 | | SYNAPSE_DATA_PATH | SQLite file path | .data/synapse.db | | SYNAPSE_OLLAMA_MODEL | Model for capability classification | freehuntx/qwen3-coder:14b |

API surface (current)

| Route | Purpose | |---|---| | GET /api/graph?limit=N | Pull a connected code subgraph from CBM (edges-first, then resolved nodes) | | POST /api/communities/run | Seed from CBM, run Louvain + PageRank, reconcile capability ids against Synapse's own prior graph, persist | | GET /api/capabilities | List capabilities and current node membership, for the graph UI's filter/legend/coloring | | POST /api/documents/ingest | Hand-load a document, resolve tier-1/2/3 references into CBM's code (or the capability registry as a fallback), persist | | GET /api/documents | List every persisted document, for the document browser | | GET /api/documents/:id | Read a persisted document back with its resolved references |

The web UI (web/) has two tabs: Graph (sigma.js canvas, filterable by kind/capability/file path, colored by capability when membership data exists, kind otherwise) and Documents (ingest form + browsable list + detail view with tier badges).

What's real vs. what's a proof

• Real: the CBM read path, the Louvain/PageRank analysis, graph-native capability reconciliation (no cache file — verified stable across repeated runs against a real project), all three linking tiers (symbol/file/capability-classification), the graph + documents UI.
• Proof only, not production: document ingestion takes raw text via JSON — no Word/PDF conversion (mammoth/pdf-parse) and no real JIRA client (jira.js) exist yet (tracked in a dedicated plan, see below). Entity dedup (the same real-world thing mentioned in two docs staying one node, not two) and capability-registry curation are unbuilt (also tracked separately). The capability registry lives only in SQLite — whether it needs a git-trackable, human-curated export is an open question, not a decision.

Where to look next

synapse-planning/ideas/architecture-pivot.md in this repo has the full history of how Synapse got here (the CBM-sidecar-to-standalone-app pivot, phase-by-phase status through the UI build-out, deviations found during implementation including two real CBM Cypher-engine bugs worked around in src/cbm/client.ts). That port is complete as of the UI build-out.

Two follow-on plans pick up from here, each scoped as fresh, unstarted work rather than a continuation: real docx/PDF/JIRA ingestion, and entity dedup + capability registry curation. Neither has been copied into this repo's synapse-planning/ yet — as of this writing they exist only as drafts on the machine that wrote them, so there is no in-repo path to link here.