Synapse: zero to the AI loop (~15 minutes)

The deep dive. QUICKSTART installs syn and proves the local brain works in five minutes; this picks up from there and builds the full Synapse + Claude Code loop (the load-bearing invariant where the AI proposes and you sanction every write) then the parts quickstart only teases: semantic search, federation across workspaces, and freshness.

Prerequisite: syn is already installed; the one-liner is in INSTALL.md. If you ran through QUICKSTART you already have a workspace with a couple of entities; skim §1 and land on §4 (the MCP server), where this goes beyond it.

Every command below was validated against a real workspace on macOS. Linux is identical; Windows uses the PowerShell installer (see INSTALL.md).

1. A workspace to work against

A workspace is just a folder. Pick one:

mkdir -p ~/brain && cd ~/brain
syn init

You should see:

workspace inicializado em /Users/you/brain
manifest inicializado em /Users/you/brain/SYNAPSE.md
registrado no registry de workspaces (id: brain-xxxxxx)

On a fresh, interactive syn init, Synapse also asks once whether to download the semantic-search models (~2.5 GB, one-time):

Download the models now? [Y/n]

Say yes to enable meaning-search right away, or skip and turn it on later with syn embed --all (§3b). Either way the workspace is created and nothing blocks: decline and Synapse runs as a keyword + graph brain until you change your mind.

The SYNAPSE.md is your workspace’s identity card: what it’s about, who it’s for. The AI reads it when routing questions across multiple workspaces (more on that in recipe 7).

2. Capture your first entity

Synapse models the world as six entity types: project, person, entity (org / vendor), api, task, note. Start with a project and a person:

syn project add "Cliente Alfa"
syn person  add "Maria Silva"
syn person  link maria-silva --project cliente-alfa --role focal

Browse what you just made:

syn project list
syn graph project cliente-alfa

The graph already shows the inbound focal link. No magic: link rewrote both frontmatters and an index row.

3. Search

Everything you write lands in an FTS5 index:

syn search alfa
syn search alfa --type project
syn search PKCE                 # after recipe step 6 below

Search is what makes Synapse worth the friction of typed entities: it stops being a folder of notes and starts being a queryable second brain.

3b. Semantic search (v0.5)

Semantic search ships in the default binary (it’s opt-out: see INSTALL.md). Once its models are present, search does more than match words: it matches meaning, and it connects the dots through the graph.

The models download on your say-so, not behind your back. The ~2.5 GB of on-device models (one-time, shared across every workspace) are pulled only when you consent: syn init offers the download on a fresh, interactive setup, and syn embed --all pulls them any time. Until then, writes still save (just without embeddings) and syn search falls back to fast keyword + graph: nothing blocks on a download you didn’t ask for. (Where they come from, where they live, offline use, privacy and licenses: MODELS.md.)

Turn it on and backfill in one step:

syn embed --all            # downloads the models on first run, then embeds every entity (idempotent)
syn embed --check          # entities: N · embedded: N · models_ready: true

From here, every new entity you add is embedded and its mentions linked automatically, inside the same transaction (BR-13).

Now search by meaning, not keywords:

syn search "the payments decision"     # hybrid (default): finds the note even if it says "pagamentos", never "payments"
syn search --semantic "auth flow"      # vector-only: conceptually nearest entities
syn search --no-vector projeto-alfa    # FTS + graph, skips the model (fast, exact)

The default hybrid mode fuses three signals (full-text, vector similarity, and graph-neighbourhood) so a query about “the flag from the meeting with Carina” can surface the flag entity even though that note never names it: the graph leg rides in from the meeting note that does.

NER proposes new entities. When the pipeline spots a person/tool/product mention that isn’t an entity yet, it queues a proposal instead of guessing:

syn pending list                       # look for kind = create_entity_from_ner
syn pending show 3                     # inspect the proposed entity
syn pending accept 3                   # materialise it (BR-12.3: never without your sign-off)

Grade results to tune ranking (optional, feeds v0.6):

syn search "checkout flag" --grade     # prompts relevant? [y/N/skip] per hit
# judgments append to .synapse/search-labels.ndjson

Want fast writes without the model on a given command? SYNAPSE_ENRICHMENT_MODE=off syn note add ….

4. The MCP server

Now the interesting part. syn mcp exposes the workspace to any MCP client over stdio. For Claude Code:

// ~/.claude.json
{
  "mcpServers": {
    "synapse": {
      "command": "syn",
      "args": ["mcp"],
      "cwd": "/Users/you/brain"
    }
  }
}

Restart Claude Code, then ask:

“Who is the focal contact for projeto-cliente-alfa, and which APIs do they own?”

Claude calls project_graph, get_entity, and answers with the slugs you typed. No hallucination, no “I don’t have access to that.”

5. The AI proposes, you sanction

This is the load-bearing invariant (BR-12.3): MCP never writes directly. The AI proposes; you accept.

In Claude Code:

“Capture a decision note: we picked PKCE for OAuth on Cliente Alfa. Tag it auth.”

Claude calls capture_fact (kind defaults to decision). The response includes a pending_id and the exact commands to copy. In your shell:

syn pending list
# id  kind          status   proposed_at               source
#  1  capture_fact  pending  2026-05-25T15:30:00Z      mcp:capture_fact

syn pending show 1     # see the full payload + Claude's reasoning
syn pending accept 1   # apply it

Now syn search PKCE finds the note. The AI created it; you approved it; the markdown is yours.

Same flow for link_entity, update_status, add_workspace_topic, add_workspace_tag.

Not every proposal is right: reject the ones that aren’t with syn pending reject 2 --prune (drops it, keeps the queue clean). And every write the AI does land is on the record: the markdown carries x-ai-* provenance frontmatter and an append-only line goes to .synapse/audit.ndjson. syn audit list replays who proposed what, when, and what you decided; syn audit verify re-hashes the trail against the payloads. The loop isn’t “the AI writes”; it’s “the AI proposes, you decide, and the decision is auditable.”

6. Workspaces share, but only when you say so

Federation (BR-12.4) is opt-in by default. Workspaces stay isolated until you let them join the pool:

cd ~/work-brain && syn init && syn ws include work-brain
cd ~/brain      && syn ws include brain
syn ws list

Now syn search pagamentos --all queries both. So does Claude Code via federated_search. Workspaces you didn’t syn ws include remain invisible; the LLM cannot probe whether they exist (see MCP.md > Privacy gate).

7. Stay fresh

If you git clone a workspace that someone else also writes to, Synapse warns when your local copy drifts from origin:

syn: workspace "team-brain" differs from origin's tracked tip; run `git -C ... pull`.

The advisory is never blocking (ADR-011). Suppress per-invocation with --no-freshness, per-workspace with syn ws freshness off <name>, globally with [freshness] enabled = false.

8. Next steps

Whenever the index and the Markdown drift: you edited a file by hand, deleted one behind Synapse’s back, left a dangling link: syn doctor tells you (categorised, never mutating) and offers syn reindex. Make it your first stop when something looks off.

• RECIPES.md: eight common workflows verbatim
• COMMANDS.md: every subcommand (incl. syn capture, identity + syn cv export)
• MCP.md: all 20 tools and the privacy model
• MODELS.md: the semantic models: footprint, cache, offline, privacy, licenses
• CONFIGURATION.md: config layers and env vars
• docs/adr/: the load-bearing decisions

You’re set.