Synapse

Operational memory for agents, with governed changes, preserved history, and explicit integrity checks.

Keep decisions, API knowledge and runbooks useful beyond the conversation that created them.

Get started · Workflow · Evidence · Architecture · Documentation

Source and release scope: the diagrams and capability descriptions below refer to this source tree. Distributed binaries can lag behind it. Check syn --version, the release notes and the relevant contract before depending on a newer command or integration.

What Synapse is

Synapse is a local operational knowledge layer for developers and AI agents. Store project context as Markdown, retrieve it through CLI or MCP, and review changes through governed proposal paths. Your Git workflow and existing authoring tools remain useful.

The distinction is continuity with evidence: a decision should survive the task, keep its source context and expose what was checked before another agent relies on it. Synapse complements Notion, Obsidian, documentation repositories and retrieval engines such as QMD, Mem0 and Zep. It can run alone or supply knowledge to a host such as Soma.

Why it matters

An agent result becomes useful memory through a reviewable change. The local knowledge process contract always queues its proposals; an operator reviews the exact payload before acceptance. Other write paths follow their configured policy, including documented safe application rules.

Each step has a separate responsibility. Review assesses a proposed change. The transaction preserves its recorded decision. Verification checks named properties over the selected records. None of these alone establishes the truth of every sentence or the absence of every natural-language contradiction.

Optional model assessments stay advisory. The current grouped EN/PT experiment did not meet its conflict-recall gate, so no classifier is enabled by default. See the measured results and limitations.

Get started

Install from the public distribution repository. Review release verification for checksums, signatures and the expected publisher before running a downloaded executable.

curl -fsSL https://raw.githubusercontent.com/romulofebasi/synapse-releases/main/install.sh | sh
# Alternatively, with Node 18+:
npx @febasi/synapse init ~/brain
npm install -g @febasi/synapse

Create a workspace, record a project and connect an MCP-compatible assistant:

syn init ~/brain
cd ~/brain
syn project add "Payments Platform"
syn person add "Maria Silva" --email maria@company.com --job-title "Tech Lead"
syn person link maria-silva --project payments-platform --role focal
syn api add "Payments API" --auth oauth2 --owner maria-silva
syn search payments
syn mcp install
syn verify

The first interactive syn init offers an optional semantic-model download, about 2.5 GB. Keyword and graph retrieval work without it. Models are local by default; network providers require explicit configuration. See models, installation and the guided tutorial.

How it fits together

Two interfaces call the same core. Markdown is the current content source; SQLite holds a rebuildable search projection and operational state. Pending review rows have their own retention requirements and cannot be recreated merely by reindexing Markdown. Governed source records, retained images and receipts live in separate evidence metadata.

The current source exposes 42 MCP tools, including the versioned knowledge process contract. A host can select a verified binary, read bounded source-cited passages, propose a result and preserve the review boundary. The contract requires no HTTP daemon or additional memory database.

The architecture guide explains layering, transaction recovery and trust boundaries. The MCP reference documents the actual interface.

Knowledge in your existing workflow

Synapse supplies operational memory. Soma supplies an operator workspace for preparing context, supervising work and reviewing results. Other hosts can use the same bounded process contract without adopting Soma.

Current source adapters read Git/Markdown and optional GitHub with fresh revision and access checks. A detected change produces review candidates. It does not silently replace accepted knowledge or write back upstream. Notion, Jira, Confluence and further authoring-tool adapters remain separate integration work.

Local-owner note acceptance and authenticated shared publication use different authority paths. The local knowledge process contract rejects shared authority. Shared source-derived acceptance remains disabled until its dedicated authenticated host workflow is available. See source adapters, source evolution and the shared source contract.

The proof

Evidence should name the workload and its limits. The stored retrieval fixture asks the same 20 questions while six synthetic professional contexts accumulate from 77 to 463 entities. The chart below plots those recorded observations, with no competitor or hypothetical baseline.

This is an internal engineering measurement on macOS arm64, not a field study or a guarantee for other corpora. The original retrieval run did not record its source commit. At the 463-entity endpoint, 17 of 20 target facts rank first and all 20 appear in the top ten. Raw observations: persona-recall.json.

The benchmark harness is in synapse-bench/ in the source repository. Results describe their recorded run, not universal semantic consistency or every distributed binary.

Day to day

Review the command contract and selected policy before accepting proposals in bulk.

Documentation

Status

The source tree continues to evolve beyond the last packaged release. Consult CHANGELOG.md for source changes and release notes for the exact published artifacts. Markdown schema, CLI and MCP compatibility follow the documented semantic-versioning policy. Experimental adapters and planned integrations keep their own explicit status.

Synapse is part of Febasi’s work to turn practical engineering into reusable capabilities. The product remains usable as a standalone local tool and as an additive knowledge component.

On the name

A synapse passes a signal from one neuron to the next. Synapse carries project knowledge from one task to the next. Lil Syn, the connected indigo mascot, is the human face of that idea.

License

MIT. See LICENSE.

_{Built by Rômulo Febasi at Febasi.}

Quickstart: 5 minutes, terminal only

The fast, local proof: from a blank disk to a queryable brain you drive entirely from the terminal: no AI, no config files. The goal is to see it work and decide whether the typed-entity model fits how you think.

Prefer a guided walkthrough: syn setup (language), the exact output you’ll see, and how to introduce yourself? That’s ONBOARDING.md. Want the full human + AI loop: MCP wiring, the propose/accept workflow, federation? That’s TUTORIAL.md.

If you haven’t installed syn yet, INSTALL.md is one paragraph.

1. Make a workspace

syn init ~/brain
cd ~/brain

You now have:

~/brain/
├── .synapse/              # the SQLite index + config
│   ├── config.toml
│   └── index.db
├── projects/
├── people/
├── entities/
├── apis/
├── tasks/
└── notes/

On a fresh, interactive run you’ll be asked one question: whether to download the semantic-search models (~2.5 GB, one-time):

Download the models now? [Y/n]

Say yes for meaning-search (step 4), or skip it: everything below works either way, and you can turn it on later with syn embed --all.

Everything visible to you is plain Markdown. The .synapse/ directory is disposable: delete it, run syn reindex, and you’re back where you were.

2. Add the things in your head

syn project add "Projeto Alfa" --status active --priority high
syn person  add "Maria Silva" --email maria@empresa.com --job-title "Tech Lead"
syn entity  add "Acme Corp"   --kind vendor --contact contato@acme.com
syn api     add "API Pagamentos" --auth oauth2 --base-url https://api.pgto.com --owner maria-silva

Slugs are derived automatically (Maria Silva → maria-silva), and the YAML written to disk is human-readable:

---
type: person
id: maria-silva
title: Maria Silva
email: maria@empresa.com
job_title: Tech Lead
memberships: []
created: 2026-05-24T22:00:00Z
updated: 2026-05-24T22:00:00Z
---

3. Connect them

A person exists once and is referenced by every project they touch.

syn person link maria-silva --project projeto-alfa --role focal
syn task    add  "Migrar webhook v2" --project projeto-alfa --owner maria-silva --due 2026-06-30
syn note    add  "Por que não Stripe" --kind decision --project projeto-alfa --tag pagamentos

syn note covers what doesn’t fit the other types: decisions, runbooks, meeting transcripts, snippets, references.

4. Ask the graph

syn project list
syn person  show maria-silva
syn search  pagamentos
syn search  pagamentos --tag decisao
syn graph   project projeto-alfa
syn info
syn info --format json | jq .total

syn graph walks the link table built from memberships, owner, api, etc. syn search is SQLite FTS5 (fast, exact-term) out of the box. The default binary also ships the semantic layer (opt-out; see INSTALL.md): once you run syn embed --all once (it downloads ~2.5 GB of models the first time), search becomes hybrid: it also matches on meaning, so syn search "the payments decision" finds the right note even if it never says “payments”. From then on entities are embedded as you add them. The full propose/accept loop and semantic walkthrough live in TUTORIAL.md §3b.

5. Audit it

syn doctor

If you removed a file behind the index’s back, or referenced a person that doesn’t exist, you’ll see categorised warnings. Doctor never mutates: it tells you and offers syn reindex.

6. Hand it to your AI

syn mcp

That’s the MCP server on stdio: the door your AI knocks on. Point Claude Code at ~/brain and it answers from your facts, never a hallucination.

That’s as far as quickstart goes: you’ve proven the local brain works. Wiring Claude Code end to end (the client config, the propose/accept loop where the AI suggests and you sanction every write, federation across workspaces) is the job of TUTORIAL.md §4–§7.

7. Free-form notes

echo "# Quick thought\n\nThe webhook idempotency check needs revisiting after vendor migration." \
  > notes/quick-thought.md
syn reindex      # index picks it up
syn search idempotency

You can edit Markdown by hand and rerun syn reindex, or run syn watch (debounced, shipped in v0.2) to reindex automatically on every save.

What changed?

After step 6 your workspace looks like:

~/brain
├── projects/projeto-alfa/_meta.md
├── people/maria-silva.md
├── entities/acme-corp.md
├── apis/api-pagamentos.md
├── projects/projeto-alfa/tasks/projeto-alfa-001.md
├── projects/projeto-alfa/notes/por-que-nao-stripe.md
└── .synapse/index.db

Six concepts, one graph, two doors: terminal and AI. Commit the whole thing to git and the history of “who owns what” is plain git log.

Where to next

• TUTORIAL.md: zero to the full AI loop: MCP wiring, the propose/accept/audit invariant, federation, semantic search.
• RECIPES.md: eight common workflows verbatim (CSV import, weekly review, briefings, …).
• COMMANDS.md: full reference of every subcommand.
• MCP.md: Claude Code wiring and the 20 tools (read, federation, write proposals, maintenance, audit).
• CONFIGURATION.md: cascade config, locales (--lang en, SYNAPSE_LANG=pt-BR), freshness knobs.
• ARCHITECTURE.md: why the layout is edge → core → data.

If something goes wrong, syn doctor is the first stop. Lil Syn looks for a reason: a dangling link, an orphan tag, a file the index doesn’t know about. The tool tells you; you decide.

Install Synapse

The binaries live in a public mirror: romulofebasi/synapse-releases. The source still lives in romulofebasi/synapse (private). Anyone can install without a GitHub account.

One-liner (macOS, Linux)

curl -fsSL https://raw.githubusercontent.com/romulofebasi/synapse-releases/main/install.sh | sh

Installed? → ONBOARDING.md walks you from here to your first answer (syn setup → syn init → first entities), with the real output you’ll see.

The installer:

1. detects uname -s / uname -m,
2. resolves the latest release tag (or SYNAPSE_VERSION if set),
3. downloads the matching tarball and attempts the documented best-effort checksum/signature checks,
4. extracts and drops syn into INSTALL_DIR (default /usr/local/bin),
5. on macOS, clears the Gatekeeper com.apple.quarantine attribute unless configured otherwise.

The installer does not require every verification prerequisite to be present. Read release verification for its exact skip/warning behavior and the strict manual workflow when both publisher and archive checks are required.

Environment knobs

Examples:

# pin an example release; choose the reviewed tag required for your installation
curl -fsSL https://raw.githubusercontent.com/romulofebasi/synapse-releases/main/install.sh \
  | SYNAPSE_VERSION=v1.4.0 sh

# no sudo, no PATH change
curl -fsSL https://raw.githubusercontent.com/romulofebasi/synapse-releases/main/install.sh \
  | INSTALL_DIR="$HOME/.local/bin" sh

Manual download

The archive layout is:

synapse-<version>-<target>.tar.gz
└── synapse-<version>-<target>/
    ├── syn                  (or syn.exe on Windows)
    ├── README.md
    ├── LICENSE
    └── CHANGELOG.md

Choose the reviewed tag and matching archive from the public releases. Source documentation can describe newer capabilities than the selected binary:

Intel Macs (x86_64-apple-darwin) are not supported as of v0.5. The ONNX Runtime behind the semantic layer ships no Intel-macOS build, so there is no syn binary for that target. Apple Silicon is the only supported macOS. (Tracked for a possible later restore via a different backend: ROADMAP SYN-174.)

Linux / macOS

Before the extraction/install steps below, download the selected tag’s SHA256SUMS and SHA256SUMS.cosign.bundle, then authenticate the manifest and compare the selected archive using the manual verification guide. The commands below show the archive layout and installation; archive download alone does not verify its publisher.

VERSION=v1.4.0  # example tag; select the reviewed release you need
TARGET=aarch64-apple-darwin   # change for your platform
curl -fsSLO "https://github.com/romulofebasi/synapse-releases/releases/download/${VERSION}/synapse-${VERSION#v}-${TARGET}.tar.gz"
# Authenticate the manifest and verify this archive before extracting (VERIFYING-RELEASES.md).
tar -xzf "synapse-${VERSION#v}-${TARGET}.tar.gz"
sudo install -m 755 "synapse-${VERSION#v}-${TARGET}/syn" /usr/local/bin/syn
xattr -dr com.apple.quarantine /usr/local/bin/syn 2>/dev/null || true
syn --version

Windows (PowerShell)

$version = "v1.4.0"  # example tag; select the reviewed release you need
$target  = "x86_64-pc-windows-msvc"
$asset   = "synapse-$($version.Substring(1))-$target.zip"
$url     = "https://github.com/romulofebasi/synapse-releases/releases/download/$version/$asset"
$tmp     = "$env:TEMP\$asset"

Invoke-WebRequest $url -OutFile $tmp
# Authenticate the manifest and verify this archive before extracting (VERIFYING-RELEASES.md).
Expand-Archive $tmp -DestinationPath $env:TEMP -Force
$src = "$env:TEMP\synapse-$($version.Substring(1))-$target\syn.exe"
$dst = "$HOME\bin\syn.exe"
New-Item -ItemType Directory -Force -Path (Split-Path $dst) | Out-Null
Move-Item $src $dst -Force
# Add $HOME\bin to your PATH if you haven't already:
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$HOME\bin", "User")
syn --version

Windows may display a SmartScreen warning depending on the selected artifact and local policy. Check publisher/integrity evidence before deciding whether to run it.

With npm / npx (Node ecosystem)

npx @febasi/synapse --help          # run without installing
npm install -g @febasi/synapse      # or install the `syn` command
syn --version

The package is a thin launcher; the real binary is delivered through per-platform optionalDependencies (the esbuild model), so npm installs only the one matching your OS/arch, with no runtime download. Supported targets: darwin-arm64, linux-x64, linux-arm64, win32-x64. Published with npm provenance from its publishing workflow. Inspect the selected package’s actual attestation; this is separate from manually verifying an archive manifest and cosign bundle.

The unscoped synapse name is taken on npm by an unrelated package, so Synapse publishes under the @febasi organization scope.

How it is published (SYN-103): the npm packages are built and published from the public synapse-releases mirror (.github/workflows/npm-publish.yml), which runs after a release is mirrored. It uses npm trusted publishing (OIDC) (no long-lived token) and, because the mirror repo is public, npm generates provenance attestations automatically. Owner setup (one time): configure a trusted publisher on each of the five @febasi/synapse* packages pointing at the synapse-releases repo + that workflow. The launcher source lives in the mirror under npm/synapse/.

From source

If your platform isn’t in the table, or you want to hack on syn:

git clone https://github.com/romulofebasi/synapse.git
cd synapse
./scripts/bootstrap.sh        # enable git hooks, check toolchain
cargo build --release         # default binary (includes the semantic layer): see "Feature flags" below
./target/release/syn --version

You need:

• Rust 1.89+ (see ADR-009 + its SYN-168 amendment).
• A POSIX shell for the hooks.
• macOS, Linux, or Windows (MSRV-tested on Ubuntu in CI).

Feature flags: the v0.5 semantic layer ships by default

cargo build --release produces the default binary: full CLI, MCP server, FTS5 search and the v0.5 semantic layer: on-device embeddings (fastembed / BGE-M3), NER (GLiNER), and hybrid search. The default feature set is ["mcp", "v05_backends"] (SYN-168); the layer adds only ~25 MB (ONNX Runtime) to the binary and bundles no models.

The default build already includes the semantic layer (ADR-008 / SYN-168). To opt out and produce a minimal core binary: full CLI + MCP + FTS5 search, no embeddings/NER/hybrid, and ~25 MB smaller: build with no default features:

# Minimal core binary (no semantic layer):
cargo build --release --no-default-features --features mcp

# Try the mechanics offline, zero downloads (deterministic stub):
cargo build --release --no-default-features --features "mcp test_backend"
./target/release/syn embed --check     # works without any model

# Add hosted embeddings (OpenAI/Voyage) on top of the default layer:
cargo build --release --features network_backends

The default syn already carries the embed command and the --semantic / --no-vector / --grade search flags. See COMMANDS.md and CONFIGURATION.md.

Models download on consent, not at build and not on first write. The binary ships without the ~2.5 GB of local models. They are pulled only when you explicitly ask: answering “yes” to the syn init onboarding prompt, or running syn embed --all (or syn embed <slug>). Until then, writes save without embedding and syn search degrades to FTS + graph: nothing blocks and nothing downloads silently. syn embed --check is read-only and reports models_ready false without downloading. Budget ~2.5 GB for the multilingual defaults, ~325 MB for the English opt-downs; the cache (overridable via SYNAPSE_MODEL_CACHE; see CONFIGURATION.md) is shared across every workspace on the machine.

Full detail: exact models, source repos, cache paths, offline / air-gapped use, privacy, licenses, and the Linux glibc ≥2.38 requirement: lives in MODELS.md.

Signature verification and operating-system trust

Release archives using the current signing workflow include SHA256SUMS and SHA256SUMS.cosign.bundle. Verify the selected release’s actual assets, expected tagged workflow identity and exact archive digest before extraction. Follow VERIFYING-RELEASES.md for the manual policy and the convenience installer’s best-effort behavior.

Sigstore authenticates release evidence; it does not provide Apple notarization or Windows code-signing trust. Gatekeeper/SmartScreen can still prompt. Clearing quarantine or accepting an operating-system prompt is not a substitute for checking the artifact’s publisher and integrity. Check the chosen release notes for platform-specific signing status.

Uninstall

Synapse ships its own uninstaller (SYN-74). The flags compose:

syn uninstall                  # remove the binary at $(which syn)
syn uninstall --purge          # also delete the global config dir
syn uninstall --everything     # also delete the workspaces registry
syn uninstall --everything --force   # skip the y/N prompt (CI-friendly)

--everything implies --purge. Workspace folders (~/brain or wherever you ran syn init) are never touched; they are plain Markdown owned by you.

If syn is no longer on $PATH for some reason, the manual fallback still works:

sudo rm /usr/local/bin/syn          # or wherever you put it
rm -rf ~/.config/synapse                       # global config (Linux)
rm -rf ~/Library/Application\ Support/synapse  # global config (macOS)

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.

Synapse: recipes

Eight workflows you’ll re-run more than once. Every command works against the workspace from TUTORIAL.md; follow that first if you haven’t.

1. Import people from a CSV

You have contacts.csv:

name,role,project
Maria Silva,focal,cliente-alfa
João Santos,dev,cliente-alfa
Carla Lima,pm,cliente-beta

A two-liner:

tail -n +2 contacts.csv | while IFS=, read -r name role project; do
  slug=$(syn person add "$name" --format json | jq -r '.id // empty')
  [ -n "$slug" ] && syn person link "$slug" --project "$project" --role "$role"
done

syn person add is idempotent on slug: re-running skips existing people.

2. Weekly review: what changed in the last seven days

syn search "" --format json | jq '[.[] | select(.updated >= (now - 7*86400 | todate))]'

For tasks specifically:

syn task list --status in_progress
syn task list --status blocked

Pair with syn graph to see who owns what:

for slug in $(syn task list --status in_progress --format json | jq -r '.[].id'); do
  echo "=== $slug ==="
  syn graph task "$slug"
done

3. Find stale tasks

A task is stale when updated is older than a threshold. Use syn export --as json for ad-hoc analysis:

syn export --as json --out /tmp/dump.json
jq '[.entities[] | select(.type == "task" and .status != "concluded" and .updated < (now - 14*86400 | todate))
       | {id, title, owner, updated}]' /tmp/dump.json

Tweak the 14 to the staleness window you care about.

4. Per-project briefing for an external party

Export only what they need to see:

PROJECT=cliente-alfa
syn export --as json --out /tmp/full.json

jq --arg p "$PROJECT" '
  {
    project:   (.entities[] | select(.type=="project" and .id==$p)),
    people:    [.entities[] | select(.type=="person" and .frontmatter.memberships[]?.project == $p)],
    apis:      [.entities[] | select(.type=="api" and (.frontmatter.projects // []) | index($p))],
    decisions: [.entities[] | select(.type=="note" and .frontmatter.kind=="decision")],
  }
' /tmp/full.json > /tmp/briefing.json

Or render the whole workspace and hand them a URL:

syn export --as html --out /tmp/brain-site
python3 -m http.server -d /tmp/brain-site 8765
# open http://localhost:8765

5. Let the AI propose, you sign off in batch

Working with Claude Code on a long thread, end the session with:

syn pending list             # what is queued
syn pending show 1           # spot-check the largest one
syn pending accept 1
syn pending accept 2
syn pending reject 3 --prune # AI was wrong on this one, prune for audit hygiene

Tip: alias acc='syn pending accept', rej='syn pending reject' for fast triage.

6. Rename and merge tags

Tags drift over time (auth, authentication, Auth). Collapse them:

syn tag list                 # see counts
syn tag rename Auth auth
syn tag merge authentication auth

Both commands rewrite frontmatter on every affected entity and re-index in the same transaction (BR-6.1).

7. Cross-workspace federation with the LLM

After syn ws include on multiple workspaces (see TUTORIAL §6), Claude Code can route across them:

“Compare how cliente-alfa (work-brain) handles webhooks vs. the pattern in personal-brain.”

Claude calls list_workspaces, picks the relevant ones from each description/topics, then federated_search and get_entity_from. Workspaces you didn’t opt in are invisible: neither Claude nor any other client can probe their existence.

Curate identity fields so routing works well:

cd ~/work-brain
syn ws topic add payments
syn ws topic add webhooks
syn ws tag add internal

(Or let Claude propose them via add_workspace_topic; same pending-queue flow as recipe 5.)

8. Continuous reindex while editing

If you’re polishing a few notes in your editor:

syn watch --debounce-ms 500

Every save triggers a debounced reindex. Cancel with Ctrl-C.

Pair with syn open <slug>:

syn open decisao-pkce          # opens in $EDITOR, reindexes on close

9. Turn on semantic search for an existing workspace (v0.5)

The default binary already includes the semantic layer (SYN-168); the real gate is the model download, which happens only on consent. The syn init onboarding prompt offers it for new workspaces; for an existing one, syn embed --all is the consent step. (Footprint, cache location, offline use, privacy and licenses: MODELS.md.)

syn embed --check              # "models_ready: false" → models not downloaded yet
syn embed --all                # first run downloads ~2.5 GB of models (consent), then embeds everything
syn embed --check              # "models_ready: true · embedded: N · model: fastembed:bge-m3@…"

syn embed --check is read-only; it reports models_ready without downloading anything. Until you run syn embed --all, writes save without embedding and syn search degrades to FTS + graph; nothing blocks. (On a minimal core build: --no-default-features --features mcp: the embed command and the vector legs are absent entirely.)

From now on every new write is embedded automatically. If you later switch embedding_model in .synapse/config.toml, re-run syn embed --all: it re-embeds only the rows whose stored model no longer matches. To start clean: syn embed --reset-cache && syn embed --all.

10. Choose the right search mode

syn search "billing webhook retries"      # hybrid (default): best recall, blends meaning + words + graph
syn search --semantic "race condition"    # vector-only: "find conceptually similar", even with no shared words
syn search --no-vector webhook-v2         # FTS + graph: exact-term + link traversal, no model load (fast)

Rule of thumb: hybrid for “find what I mean”, --semantic for “find things like this”, --no-vector when you know the term and want zero cold-start.

11. Review NER-proposed entities

The insertion-time pipeline (BR-13) links mentions to existing entities and proposes new ones it can’t resolve, rather than creating them silently:

syn note add "Sync with Carina about the Stripe migration" --kind meeting
syn pending list                          # → a create_entity_from_ner proposal for "Carina" / "Stripe"
syn pending show 1                        # inspect the proposed type + title
syn pending accept 1                      # materialise it, or `reject 1` to dismiss

This keeps the graph growing from what you actually write, while BR-12.3 guarantees nothing is created without your sign-off.

12. Grade search results to tune ranking (v0.6 prep)

syn search "checkout eligibility flag" --grade
#   [1/4] entity   remote-config            Remote Config
#       relevant? [y/N/skip] y
#   ...
#   recorded 4 judgment(s) → .synapse/search-labels.ndjson

The labels accumulate as NDJSON; a future release reads them to tune the hybrid ranking to your sense of relevance. Grade a few dozen real queries and the data is there when v0.6 needs it.

Found a recipe worth sharing? Open a PR on this file.

syn: Command reference

All commands accept these global flags: --format text|json, --verbose, --lang <locale>, and (v0.6) the output/automation set: --plain/--raw (raw, unstyled output), --no-color (drop colour, keep structure), --quiet/-q (suppress non-essential lines), --no-input/--yes (never prompt: for CI/agents). Locale precedence: --lang → SYNAPSE_LANG → system locale → en. Output is rich by default on a TTY (tables, panels, the unicode graph tree, progress, the mascot) and degrades to plain bytes on a pipe / --plain / NO_COLOR; --format json is always machine-clean and unstyled.

Workspace lifecycle

Entities

The six types share add | list | show | rm (except task, which adds done).

syn project

syn project add "Display Name" [--desc TEXT] [--status active|paused|concluded|archived] [--priority low|medium|high]
syn project list [--status STATUS]
syn project show <slug>
syn project rm   <slug> [--force]

syn person

syn person add  "Full Name" [--email X] [--org SLUG] [--job-title "Tech Lead"]
syn person link <person-slug> --project <project-slug> --role <free-form>
syn person list
syn person show <slug>
syn person rm   <slug> [--force]

--job-title (cargo formal) is not the same as --role in the link command (papel funcional naquele projeto). See BR-4.4.

syn entity

syn entity add  "Name" [--kind vendor|customer|internal|partner] [--contact STR]
syn entity list
syn entity show <slug>
syn entity rm   <slug> [--force]

syn api

syn api add  "Name" [--base-url URL] [--auth none|apikey|basic|oauth2|jwt|mtls] [--status production|staging|deprecated] [--owner <person-slug>]
syn api list [--status STATUS]
syn api show <slug>
syn api rm   <slug> [--force]

syn task

syn task add  "Title" [--project SLUG] [--owner SLUG] [--api SLUG] [--due ISO-DATE] [--status open|in_progress|blocked|concluded] [--tag T]...
syn task done <id>
syn task list [--status STATUS]
syn task show <id>
syn task rm   <id> [--force]

IDs are auto-assigned: <project>-NNN when scoped, t-NNN otherwise. done stamps closed_at.

syn note

syn note add  "Title" [--kind decision|runbook|meeting|snippet|reference] [--project SLUG] [--tag T]...
syn note list
syn note show <slug>
syn note rm   <slug> [--force]

Custom entity types (SYN-234 / ADR-028)

Beyond the six built-ins you can define your own types in .synapse/types.toml (book, meeting, decision, client, …) without a code change. A type is a closed core (a small whitelist of indexed, queryable fields) plus an open frontmatter bag validated on read.

# .synapse/types.toml
schema_version = "1.0"

[types.book]
display   = "Book"
store_dir = "books"                 # folder under the workspace root
indexed   = ["author", "year", "isbn"]  # ≤ 16; these become bindable query keys
identity  = ["isbn"]                # SYN-254: a capture matching these on an
                                    # existing book is flagged as a duplicate
                                    # and routed to the gate (⊆ indexed)

  [types.book.fields.author]
  type = "string"
  required = true
  [types.book.fields.year]
  type = "int"                       # string | int | float | bool | date | ref | list

# SYN-248: per-kind policy (covers built-ins too, which are reserved above).
[policy.person]
decay = false                        # profile: current-state, never flagged by `syn stale`

syn types lists every registered type (built-ins + yours). Manage instances with the generic dispatcher (the built-in commands stay for the six core types):

syn new  --type <kind> "Title" [-f key=value]... [--tag T]... [--id SLUG]
syn ls   --type <kind> [--status S] [--as-of DATE]
syn show --type <kind> <id>
syn rm   --type <kind> <id> [--force]

syn new  --type book "Dune" -f author="Frank Herbert" -f year=1965 --tag scifi
syn ls   --type book
syn show --type book dune

Field values are passed as repeatable -f key=value pairs (static clap cannot synthesise a typed flag per runtime-defined field). Each value is coerced to its declared type and validated on write; a missing required field or a type mismatch is rejected. Custom-typed entities are reindexed, FTS-searchable (syn search, MCP search_everything), countable via the query tool (incl. filter.field over an indexed field), and can be link endpoints (MCP link_entity).

Current limitations (honest). Custom types are first-class for create / read / list / remove / search (incl. --type <custom>, SYN-259) / link / update_status / supersession. The remaining gap is insertion-time semantic embeddings: custom entities are embedded by an explicit syn embed --all (FTS-only until then): SYN-251. Declared pattern (regex) field constraints are parsed but not yet enforced (needs a regex dep + ADR; deferred).

Search and graph

syn search <query> [--type <kind>] [--tag T] [--owner SLUG] [--limit N] [--near <slug>]   # --type: built-in|custom (SYN-259); --near: graph-distance rerank (SYN-255)
                   [--semantic | --no-vector] [--as-of DATE] [--grade] [--all]
syn graph  project|person|api <slug> [--rel RELATION]

graph walks the materialised links table. search behaviour depends on whether the semantic layer is present:

• Minimal core build (--no-default-features --features mcp) or models not downloaded yet: plain FTS5, BM25-ranked. The query takes FTS5 syntax (title:foo, "phrase").
• Default build, models present: the default is hybrid: FTS5 + vector similarity + graph-neighbourhood fused with Reciprocal Rank Fusion (k=60). The query is natural language. Flags:
  • --semantic: vector similarity only (best for “find conceptually similar”, needs an embedded workspace).
  • --no-vector: FTS + graph only; skips the embedding step and its cold-start.
  • --grade: after searching, prompt per hit (relevant? [y/N/skip]) and append the judgments to .synapse/search-labels.ndjson (for v0.6 ranking tuning). Requires an interactive terminal; conflicts with --all.
  • --as-of DATE: valid-time filter (SYN-223 / ADR-027): keep only facts true in the world at DATE (YYYY-MM-DD or RFC-3339), using the SQL:2011 closed-open [x-valid-from, x-valid-until) interval. Facts with no x-valid-* stamps always pass. Applies in every mode (FTS and hybrid); local-only (conflicts with --all). Composes with syn at <ref>: see the time-travel section.
  • --all: fan out across every federated workspace (plain FTS, not hybrid).

syn search "the firebase feature flag"        # hybrid (default)
syn search --semantic "auth and sessions"     # vector-only
syn search --no-vector "checkout-v2"          # FTS + graph, no model load

Filters (--type/--tag/--owner) apply in every mode. When the models haven’t been downloaded yet (or the workspace is un-embedded), hybrid search degrades gracefully to FTS+graph rather than failing, and never triggers a download.

Trust-weighted ranking (SYN-250 / ADR-029). The hybrid ranker multiplies each hit’s relevance by its deterministic trust score (the same curve syn stale/syn blame use), bounded to [0.5, 1.0]: a decayed or low-confidence AI fact sinks beneath an equally-relevant fresher one, but trust never fully suppresses a strong textual match. Human-authored facts carry no penalty (full weight).

Embeddings (syn embed)

The semantic layer ships in the default binary (opt-out, SYN-168): to drop it, build a minimal core binary with --no-default-features --features mcp. The ~2.5 GB of local models are not bundled; syn embed --all (or syn embed <slug>) is the explicit consent step that downloads them on first use (the other consent path is answering “yes” to the syn init onboarding prompt).

syn embed --all            # download (on first use) + embed every entity; skips rows whose content + model already match
syn embed <slug>           # (re-)embed one entity
syn embed --check          # show cache state (entities, embedded, current vs stale model, models_ready): read-only, never downloads
syn embed --reset-cache    # drop every vector + meta row; next --all re-embeds from scratch
syn embed --force          # with --all/<slug>: re-embed even when the content hash matches

Writes already embed automatically at insertion time once the models are present (see Insertion-time enrichment below), so syn embed --all is mainly for backfilling an existing workspace the first time you populate the cache, or after switching embedding_model. --check is the quick way to see whether the index is populated and on which model; its output (text and JSON) carries a models_ready field: false means the models haven’t been downloaded yet, and --check reports it without triggering a download.

Insertion-time enrichment (BR-13)

On the default (semantic) binary, once the models are present, every write (project add, note add, an accepted MCP proposal, …) runs a synchronous pipeline inside the transaction: it embeds the entity, runs NER, and links mentions. You don’t call anything: it just happens.

If the models haven’t been downloaded yet, the write still succeeds: enrichment is skipped gracefully with a one-time note (“semantic models not downloaded yet: write saved without embedding. Run syn embed --all…”), and the write never triggers a download. Models are pulled only on explicit consent: answering “yes” to the syn init onboarding prompt (a TTY-only prompt; non-interactive syn init just prints a one-line breadcrumb and never blocks), or running syn embed --all. Once present, the pipeline:

• writes the vector to entities_vec (so the entity is immediately searchable semantically);
• creates typed link rows for mentions that resolve to existing entities (surfaced by syn graph);
• queues a create_entity_from_ner proposal in the pending queue for a mention that does not resolve yet: accepting it (syn pending accept <id>) materialises the new entity (BR-12.3: nothing is created without your sign-off).

Control it with [enrichment] mode in config (off / heuristic / heuristic+ner) or the SYNAPSE_ENRICHMENT_MODE env var per invocation (e.g. SYNAPSE_ENRICHMENT_MODE=off syn project add … for a fast write that skips the model). See CONFIGURATION.md.

Tags

syn tag list                    # tags with counts (desc)
syn tag rename <old> <new>      # rewrites every entity's frontmatter and the index
syn tag merge  <source> <target>

Workspaces and federation

syn ws list                     # every workspace ever seen
syn ws show <id|name>           # full row + SYNAPSE.md
syn ws include <id|name>        # opt this workspace into cross-workspace queries (BR-12.4)
syn ws exclude <id|name>        # remove from the federated pool
syn ws forget  <id|name>        # remove from the registry (folder is left intact)
syn ws gc                       # sweep registry rows whose root has been deleted

syn ws topic add|rm <value>     # curate SYNAPSE.md topics
syn ws tag   add|rm <value>     # curate SYNAPSE.md tags
syn ws edit  [name]             # open SYNAPSE.md in $EDITOR
syn ws refresh [name]           # re-read SYNAPSE.md from disk and refresh the registry cache

syn ws freshness on|off <name>  # toggle the per-workspace freshness advisory (SYN-93)

Federation is opt-in (default off). See ADR-010 and the Privacy gate section in MCP.md.

Workspace maintenance

syn reindex                          # rebuild the SQLite index from the source-of-truth Markdown
syn watch [--debounce-ms 250]        # auto-reindex on filesystem change (SYN-65)
syn doctor                           # audit consistency
syn open <slug> [--no-reindex]       # open an entity in $EDITOR, reindex after exit (SYN-70)
syn export --as json [--out FILE]    # dump every entity + link as JSON (SYN-67)
syn export --as html --out DIR/      # render a static site (SYN-66)
syn config get|set|unset <key> [val] # workspace-scoped TOML knobs (SYN-69)

--as (not --format) avoids colliding with the global --format text|json flag.

syn import (SYN-228)

The honest inverse of syn export --as obsidian: import a Markdown vault as governed proposals (BR-12.3: nothing touches the workspace until you accept):

syn import --from <PATH>          # a .md file, or a directory walked recursively

Each .md becomes a queued capture_fact proposal. A note with YAML frontmatter keeps its type (when it names a registered kind, else note), title, tags, and scalar fields; a frontmatter-less note (plain Obsidian markdown) becomes a note whose title is its first # heading (or the filename) and whose body is the whole file. Review with syn pending list, then syn pending accept --all. The contract is deliberately Markdown + YAML frontmatter (the format Synapse itself emits) not a reverse-engineered external schema, so it round-trips your own export.

Uninstall

syn uninstall                  # remove the binary (asks in tty; --force to skip)
syn uninstall --purge          # also delete the global config
syn uninstall --everything     # also delete the workspaces registry

Workspace folders are never touched: your Markdown belongs to you.

Destructive prompts

Every <type> rm asks for confirmation in a TTY. Non-TTY runs require --force; running in a script without it now fails loudly rather than deleting silently (SYN-71).

Pending proposals (SYN-60..62, SYN-92)

The MCP server enqueues every write proposal here instead of touching the workspace. Review and apply with:

syn pending list                # currently-pending proposals
syn pending list --all          # include accepted + rejected
syn pending show <id>           # full payload + reason + source
syn pending accept <id>         # apply (via Workspace::tx) and mark accepted
syn pending accept 1 3 5        # accept several at once (each applies atomically)
syn pending accept --all        # batch-approve every pending proposal (SYN-185)
syn pending reject <id>         # mark rejected; row kept for audit
syn pending reject <id> --prune # delete the row instead of keeping it
syn pending reject --all        # batch-reject everything (add --prune to delete)

See BR-12.3: MCP must never write without explicit human confirmation. The pending queue is per-workspace, lives in .synapse/index.db, and the row id is monotonic per workspace.

Undo an accepted decision (syn undo, SYN-287 / ADR-039)

syn undo <id>     # reverse a previously accepted decision (same id as `pending list --all`)

It reverses a capture_fact create (removes the entity), a link_entity (deletes the edge), and an update_status (restores the prior status from a pre-image captured at accept time, SYN-292): all on a just-accepted, uncommitted write, no git commit required. It refuses (with guidance to revert via git) for supersessions, custom-typed creates, and batches, and refuses if the fact was changed after the decision (the conflict guard never clobbers later work). Every undo is atomic and is itself recorded on the audit trail (the original accepted entry is never deleted). undo is a human corrective action and is CLI-only by design, it is deliberately not an MCP tool, so the agent can’t erase its own accepted history (the agent proposes, the human disposes: ADR-022/039).

Ambient capture (syn capture)

syn capture "Why we picked PKCE for auth"   # the one-liner: drop a thought in seconds as a raw note (SYN-221)
echo "Why we picked PKCE" | syn capture      # …or pipe stdin; a bare TTY opens $EDITOR
syn capture --from-git                       # seed people (commit authors) + a project (the repo) from git, as proposals (SYN-220)
syn capture --from-git ~/code/myproj         # …from a specific repo; --max N caps the authors proposed

syn capture "<text>" is the promoted capture path (SYN-221): zero schema at the moment of capture; it queues a raw note, and the AI can later propose the typed/linked version (deferred structuring). Everything still goes through the pending queue (BR-12.3).

Governance, audit & forensics

This is the differentiated surface: prove what the AI changed, when, and on whose behalf, and undo it. All of it reads the source-of-truth Markdown, the x-ai-* provenance frontmatter, and git.

syn blame <slug>                     # AI provenance lineage: who/what touched the entity, when, on whose behalf (SYN-240)
syn diff  <slug> [--since <ref>]     # per-field before/after of an entity since a git ref (SYN-240)
syn changes --since <rfc3339> [--limit N]  # what changed since an instant: audit decisions + per-field deltas (SYN-256)
syn timeline <slug>                  # walk the git history of one entity (SYN-121)
syn connections <slug> [--hops N] [--max-nodes N] [--semantic]  # ego graph as JGF (SYN-244); --semantic adds explainable mutual-kNN edges (SYN-245)
syn stale [--limit N]                # AI facts whose trust score has decayed: advisory (SYN-224)
syn types                            # list registered entity types (built-ins + types.toml; SYN-234)

Time travel (SYN-122). Query the workspace as of any git ref: what you knew at commit R:

syn at <ref> -- search <query>       # search the workspace as it was at <ref>
syn at <ref> -- show <type> <id>     # show an entity as it was at <ref>

Bitemporal (SYN-223 / ADR-027). Two orthogonal time axes, each a separate filter, composable:

• Transaction-time: what we knew at commit R: syn at <ref> (above).
• Valid-time: what was true in the world at date D: --as-of D.

syn search <query> --as-of 2025-01-01            # what was true on that date (current history)
syn at <ref> -- search <query> --as-of 2025-01-01 # "using only what we knew at <ref>, what was true on D"

Valid-time comes from the x-valid-from / x-valid-until frontmatter keys (closed-open [from, until)); facts without them always pass.

Supersession (ADR-027 / ADR-031). A captured fact carrying x-supersedes: <id> closes the superseded fact’s interval as an append, never a delete: the older fact gets an x-valid-until (when it stopped being true) plus an x-invalidated-at belief stamp (when we learned it). Three deterministic rules: new-after-old closes the predecessor, older-than-known is born already-expired, disjoint keeps both. The captured fact also carries x-recorded-at (belief-time it entered the store). Built-in F1 only for now; custom-type close + temporal replay are v0.10. --as-of filters the current history; at <ref> reconstructs the tree at a commit.

Field corrections are bitemporal too (SYN-315 / ADR-046). An update_status is an in-place, single-field edit, not a whole-fact supersession. It records valid-time at the field level: the prior value is appended to the entity’s x-field-history frontmatter, so syn ls <type> --as-of <before> reconstructs the pre-correction status while the entity itself stays visible on both sides of the correction. The history lives in the Markdown, so syn reindex rebuilds it (disposable, verify-honest).

Audit trail (syn audit). The append-only .synapse/audit.ndjson:

syn audit list [--all]               # recent entries (newest first); --all includes archived months
syn audit show <id>                  # one entry by its pending id
syn audit verify                     # re-hash each row's payload vs the recorded payload_sha256 (SYN-135)
                                     #  : exits 65 on any mismatch; the tamper-evidence check
syn audit replay <id> [--execute]    # replay an accepted proposal: visual diff by default
syn audit prune <YYYY-MM>            # delete archive months older than DATE (live log untouched)
syn audit stale                      # cross-workspace ranking of stalled open commitments (SYN-123)

Portable receipts (syn provenance, SYN-247). A signed, self-verifying proof of an entity’s provenance that anyone can check without Synapse:

syn provenance export <slug> [--out FILE]   # signed receipt (ed25519)
syn provenance verify  <FILE>               # verify a receipt's signature; needs no workspace access

See PROVENANCE.md, AUDITABILITY.md, and IDENTITY.md for the data model behind these.

Provable non-corruption (syn verify, SYN-263 / ADR-035). Prove the AI memory was not silently corrupted: reproducible, signed, offline. Runs the runtime invariants and emits a verdict; --format json emits the full signed synapse.verify-report/1 (an in-toto Statement signed with your ed25519 identity):

syn verify                # text report: per-invariant pass/fail + trust-root caveat
syn verify --format json  # the signed synapse.verify-report/1 report
syn verify --deep         # also INV-4 (replay the governed decision journal, SYN-266) + INV-13 (logical contradictions, SYN-316)
syn verify --rebuild      # attestation: on INV-1 mismatch, list EVERY diverging fact (SYN-269)
syn verify --since <file> # also INV-12: prove history is an append-only extension of a witness (SYN-270)

Offline consistency proof (syn audit witness + verify --since, SYN-269 / ADR-037). syn audit witness emits a tiny ed25519-signed checkpoint of the audit history (git HEAD + per-author segment prefixes + count); publish it. Later, syn verify --since <witness> proves the current history only ever extended it (HEAD descends from the witnessed commit and every witnessed segment prefix is byte-stable) so a force-push or mid-log rewrite is caught offline, without a remote. A published witness lets a third party hold you to your history.

syn audit witness [--out FILE]   # signed witness checkpoint (default .synapse/audit/witness.json)

Rebuild attestation (--rebuild, SYN-269). Makes the claim your memory is a reproducible build of your files literally checkable: a from-scratch rebuild of the index is compared to the live index, and on any mismatch the signed report names the specific diverging facts (diffoscope-style ± <type> <id>), not just the first, so you see exactly where the index stopped being a faithful build. A clean run is the signed attestation itself (binds git_ref + inputs_hash). A hosted store structurally cannot offer this.

The invariants: INV-1 reindex fixpoint (the index is a reproducible build of the Markdown: a from-scratch in-memory rebuild yields the same canonical dump; the keystone), INV-2 audit payload integrity, INV-3 history integrity (hash-chain + signed checkpoint), INV-5 no silent overwrite (supersession closes its predecessor). With --deep, INV-4 also replays the governed decision journal in a scratch workspace to check it applies cleanly and deterministically (SYN-266 / ADR-036): a journal-integrity check, not store reconstruction (Synapse is state-based; reconstruction is INV-1 + git syn at), and INV-13 runs a deterministic logical-contradiction sweep (SYN-316): no overlapping valid-time values for one field (x-field-history), no supersession cycle, no inverted interval. It guards logical coherence, catching contradictions introduced by a direct Markdown edit that bypasses the gate: the one class INV-1 (storage coherence) and the propose-time gate (SYN-242) cannot see. Deterministic and model-free (no NLI/judgement). INV-8 (stored-receipt round-trip) is checks native stored receipt signatures in governed workspaces. Missing or unsigned receipts report skipped; invalid evidence fails. Legacy export-on-demand receipts do not create coverage. Independent signer trust/identity require opt-in v2 inputs. Exit codes: 0 no checked invariant failed (skips may remain), 1 an invariant was violated. The report always prints the trust-root caveat: tamper-evident, not tamper-proof: a lone local clone cannot detect its own owner’s rewrite without a witness. MCP counterpart: the verify tool.

--from-git (ADR-025) inverts the capture value-timing: a fresh workspace seeds itself from the repo’s history (authors → people, repo → project, with contributor memberships), as queued proposals (BR-12.3), bot-filtered and idempotent. Review and apply the lot with syn pending accept --all.

Freshness advisory

The workspace freshness signal (SYN-93 / SYN-93b, ADR-011) is advisory, never blocking. Phase 2 adds a bounded (3s) network git ls-refs probe of origin to catch commits you haven’t fetched yet; any network/auth/timeout failure is silent (status unreachable, previous state retained). Three escape hatches:

SYNAPSE_NO_FRESHNESS=1 syn info        # silence for this invocation
syn info --no-freshness                # same effect
syn ws freshness off <name>            # per-workspace, persisted

Globally disable in config:

[freshness]
enabled = false

MCP

syn mcp                         # starts the stdio MCP server (feature-gated, default-on)

24 tools across local read / federation / maintenance / audit / integrity / write proposals. Reads include search_knowledge (hybrid, optional type filter), search_everything (SYN-226: hybrid RRF over all kinds incl. custom, no type filter), query (structured aggregation incl. filter.field over a custom indexed field), get_entity, get_entities, list_by_type, project_graph, workspace_overview, recent_changes. All of these now reach custom types (SYN-234). Writes go through the pending queue (BR-12.3): capture_fact (creates a built-in or custom-typed entity), link_entity (any registered kind as an endpoint), update_status, propose_batch, plus the workspace-manifest tools. See MCP.md for client wiring.

Agent assets (v0.6, SYN-175 / SYN-184)

The binary carries the agent-facing assets and emits them on demand, so they never drift from the release that ships them.

syn skill install [--dir PATH] [--force]   # write the Claude Agent Skill (SKILL.md) to ~/.claude/skills/synapse-second-brain/
syn agents init   [--dir PATH] [--force]   # write an llms.txt (cwd by default) orienting any AI agent
syn plugin install [--dir PATH] [--force]  # scaffold a Claude Code plugin: plugin.json + skill + .mcp.json + a SessionStart hook

All three refuse to overwrite without --force and honour --format json.

Environment variables

Output and exit codes

--format json returns canonical, byte-stable JSON on every read command: list, show, tag list, pending list|show, ws list|show, at … show, plus search/info/doctor/graph/audit/cv, and machine-readable errors carry {error, kind, exit_code} on stderr (SYN-188/189/204). Text mode is rich by default on a TTY (colour, ✓/▲ glyphs, tables, entity panels, the unicode graph tree, progress spinners/bars, the graph-constellation mascot); it degrades to plain bytes on a pipe and is fully suppressed by --plain/--raw/SYNAPSE_PLAIN, while --no-color/NO_COLOR/TERM=dumb drop only colour and --quiet/-q drops non-essential lines (ADR-019/021).

Conventions worth knowing

• Slugs are kebab-case ASCII, derived automatically. Renaming is a separate command (<type> rename old new), not an edit.
• Frontmatter round-trips preserve field order; safe to edit by hand without producing noisy diffs.
• Writes are all-or-nothing: filesystem + index commit together, rollback together (BR-6.1).
• A workspace is any folder whose ancestors contain .synapse/; syn finds it walking up from cwd.

syn commit-verify --roster <JSON>

Verifies raw Git HEAD SSHSIG bytes in the git namespace against explicitly pinned local signing keys. Emits synapse.commit-verification/1 JSON and exits nonzero for unsigned, unsupported, invalid, unknown or ineligible signatures. The same pure core serves MCP commit_verify. A compatible roster array keeps v1 behavior. A synapse.commit-roster/1 object additionally requires an explicit --roster-sha256 (roster_sha256 in MCP) selected outside the mutable workspace. It emits v2 with revision/pin/freshness and rejects missing/wrong pins, stale snapshots, future signing claims and unsigned/unknown signatures. --require-current additionally requires current key eligibility; historical administrative revocation can preserve a prior valid signature. Reported compromised_at invalidates signatures at or after its onset. Neither profile establishes team authority or an independently trusted historical timestamp.

Roster entries have issuer, subject, OpenSSH public_key, Unix-second not_before/expires_at and optional revoked_at/compromised_at. Signing-time validity and current_key_valid are separate. Author names/emails do not establish identity; commit time is signer-controlled, and current team membership needs independent revalidation. OpenPGP and alternate SHA256 commit headers are explicitly unsupported. A roster supplied by a caller is a local trust decision, not an authority-issued binding. The snapshot includes schema, bounded revision, observed_at/expires_at Unix seconds and unique signers; its normative SHA-256 prefixes fixed-order JSON with synapse.commit-roster/1 and NUL. Unobserved offline revocations remain unknown. See ADR-055/064 and the CI test generating actual Git/OpenSSH commits. The official Git configuration documents gpg.format=ssh; verification uses the normative git SSHSIG namespace.

Governed source suffix: syn state

This is separate from native v1 syn verify: current Markdown remains the content source, while the optional governed suffix preserves complete accepted before/after manifests and retrievable raw images. Previous history is unknown.

syn state baseline --reason 'adopt reviewed current knowledge' \
  --acknowledge-unknown-history --acknowledge-plaintext-retention
syn state verify
syn state witness --key-dir /private/existing-identity > /independent/state-witness.json
syn state verify --since /independent/state-witness.json --trusted-key '<pinned public key>'
syn state reconcile --expected-parent '<reviewed head SHA256>' --reason 'reviewed external API update'
syn state receipt '<accepted event ID>'

These commands return native JSON objects in both output modes. Verify exits nonzero if uninitialized, damaged, missing retained images or source is Unattested. Reindex cannot turn external edits into accepted history. A reconciliation records the previous accepted state and actual observed state separately; a stale expected parent denies it. Mutation IDs are stable during recovery, and Workspace::tx_with_event_id supports caller request IDs without repeating an accepted ID’s effects; retrieve original evidence with receipt.

Baseline/reconcile accept optional --context <JSON> containing actor_claim (issuer/subject/device_key), proposal/rule/context SHA-256 values and a reason. These are explicit claims until authority/receipts verify them. No password, token, private key or raw prompt belongs in context/reason. Witness export needs an existing signing key, and verification needs a separately trusted pin; its embedded key alone does not establish trust. Preserve the witness independently.

Scope covers regular Markdown recursively outside .git/.synapse components; symlinks/unportable paths and exceeded budgets deny instead of silently skipping. Retained deleted images are plaintext private history with no automatic GC; use filesystem encryption/access controls. Purging an image loses reconstruction coverage. The framework does not publish raw images or commitments externally. See ADR-057 for normative bytes, budgets and adversary/platform boundaries.

MCP counterparts: state_baseline, state_verify, state_reconcile, state_witness, state_receipt. Each calls the same core as the CLI. State verify reports tool error when uninitialized or Unattested; field attribution remains explicitly unverified without authority-issued receipts. These tools do not claim general natural-language consistency, trusted timestamps or team authority.

Native receipts and explicit assurance profiles (SYN-325)

syn state receipt-policy --input <policy.json> [--expected-policy <active-digest>]
syn state signed-receipt <event_id>
syn state witness --key-dir <existing-key-directory> --include-receipts > <independently-retained-witness.json>
syn state verify --profile strict-local --trust <reviewed-trust.json> --trust-sha256 <independent-digest> --since <retained-witness.json> --trusted-key <independent-key-pin>
syn state verify --profile basic
syn state verify --profile strict-team

Without --profile, the existing synapse.governed-state/1 source report stays available. Explicit profiles use synapse.state-assurance/2; passed is the selected policy verdict. Basic can succeed with absent/unsigned receipts and explicit gaps (strict_requirements_met:false). Strict-local requires matching source/images, all receipts from the limited baseline, independently pinned key validity/freshness and a v2 witness covering the exact selected tip/receipt set. A prefix-only witness or old v1 source-only witness is partial, not sufficient. Strict-team additionally requires independently selected current issuer roots, exact resource scope and fresh complete actor/device observations supplied with --team <reviewed-team-inputs.json>. Every retained native receipt must match its original issuer/source seal and event-specific admission, with an independent v3 witness covering both receipt and original seal sets. Missing, stale, copied or untrusted inputs fail; a local key alone does not establish team authority. A successful historical verdict grants no current publication permission.

Configure signing before baseline; no back-signing of unsigned history. Policy JSON contains schema synapse.receipt-write-policy/1, profile strict_local, an absolute existing key_dir, a reviewed public trust snapshot and its normative trust_sha256. Snapshot schema is synapse.local-receipt-trust/1: revision, observed_at/expires_at and unique keys with public_key, not_before/not_after, revoked_at and compromised_at. Times are integer Unix seconds, end exclusive; nullable timing fields remain explicit null. Digest is SHA-256 of its schema plus NUL and fixed-order compact JSON. No auto-generated/trusted signer is used.

An explicit expected public policy digest permits key rotation/trust refresh; prior receipts and public trust revisions stay retained. A wrong prior digest, missing key, permissive Unix private-key mode or invalid/stale signing trust blocks before source installation. Losing the active policy pointer cannot silently downgrade retained strict configuration. Private key paths are local configuration only, never exported in receipts; bearer/private bytes never enter source, evidence or logs.

Native receipts bind full transition/context/source digests and public signing policy; independently retained v2 witnesses additionally bind the ordered exact receipt set. Verification-at-claimed-time is distinct from current key approval: a later administrative revocation can preserve earlier evidence; compromise at or before that claim invalidates it. The clock remains signer-controlled and no offline verifier can know an unobserved revocation. Receipt validity is not semantic truth, organizational authority or a trusted historical timestamp.

MCP counterparts state_receipt_policy and state_signed_receipt share the CLI core. state_verify accepts profile/trust/trust_sha256; state_witness accepts include_receipts and optional include_shared_seals (v3 requires receipt coverage). Team verification accepts the typed team input shared with CLI. Failed selected profiles return tool error plus inspectable JSON; the native signed-receipt result is an object with nullable receipt. See ADR-058.

Scoped offline authority evidence (SYN-326)

syn state binding-verify --bundle <signed-bundle.json> --trust <reviewed-issuer-roots.json> --trust-sha256 <independent-digest> --expect <selected-identity-and-scope.json> [--claimed-at <epoch-microseconds>]

The bundle contains signed binding and snapshot only. Root review/digest and expected authentication issuer, tenant/subject UUIDs, device/fingerprint and exact organization/workspace/project/knowledge GUID are selected separately. The current governed workspace must match that GUID; otherwise the report fails. No access, refresh, M2M, password or private key belongs in these files. Account API identity is not represented as OIDC without such an adapter.

state_binding_verify is the MCP counterpart with bundle/trust/trust_sha256/expect and optional claimed_at. It reports an inspectable object and tool error for failed signature, root pin, identity/scope, revoked/compromised/expired or partial selected-key evidence. Claimed/observed/root times here are Unix microseconds, distinct from native source receipt seconds. Signatures and exact canonical schemas live in the shared pure synapse-evidence Rust package; ADR-059 defines the contract and independent fixtures.

A passing synapse.binding-verification/1 proves this scoped identity observation; source_integrity_checked:false requires separate state verification and shared_acceptance:unknown_without_online_event_bound_admission requires fresh SYN-231 admission. It neither changes source/pending data nor makes strict-team verification pass. Snapshot writer/key activity is an observed point, not evidence of unobserved later revocations or new action authority.

Historical shared admission (SYN-231 component)

syn state admission-verify --bundle <grant-binding-snapshot.json> --trust <reviewed-roots.json> --trust-sha256 <independent-digest> --expect <selected-reviewer-change-policy.json>

MCP state_admission_verify takes bundle/trust/trust_sha256/expect and uses the same core. The bundle contains admission, reviewer binding and fresh selected-key snapshot. Independently selected expect contains reviewer, exact change and policy. The actual governed GUID must match. Missing/stale/wrong-scope evidence denies. The verdict authenticates a historical authority decision; source_installation_verified:false and new_operation_authority:requires_current_online_decision state its limits. This does not enable strict-team writes or replace the prepare/sign/commit host protocol, source receipts, search/citation ACL or independent witness. See ADR-060.

Scoped contradiction diagnostics (SYN-319)

syn contradictions [--fact note/api-contract] [--fact api/catalog] [--limit 50] [--proposal operation.json] [--assessment advisory.json]

MCP contradictions {request:{facts:[],limit:50,proposal:null,assessment:null}} uses the same core. Each fact is {type,id}. Report schema is synapse.contradiction-diagnostics/1; typed exact findings include stable rule IDs, finding digests, fact/field/interval references, indexed paths and exact checked scope. Omitted diagnostics/counts and unavailable checks are explicit. Cycles resolve the full indexed reference graph before scope filtering. Bare supersession targets must resolve to one globally unique fact ID; ambiguous targets now deny acceptance instead of invalidating a row chosen by query order. Unambiguous cross-type targets continue working. No source is changed by this verb.

An empty result is clear only within the checked structured classes. General prose/unindexed semantics stay unknown. Structured native proposal flips are a separate comparison, never an automatic review. Optional external assessment JSON names model_revision, rubric_revision, evaluation_revision, classification (contradiction/entailment/unknown), confidence and abstained. It is explicitly caller-asserted; this binary does not claim to run that model. Abstention requires unknown class and null confidence. Confidence cannot approve a write, change a rule or create an exact invariant result. See ADR-062 and SYN-323 model evaluation.

Versioned knowledge process API

knowledge describes actual build/protocol capabilities or takes bounded versioned request JSON through --request <file|->. Query/propose/review share the MCP knowledge tool. Acceptance and exact-review rejection are explicit operator CLI actions; the MCP agent door refuses both. Legacy rejection refuses terminal rows without adding a contradictory audit entry. See request shapes, scopes, budgets, citations and proof limits.

syn --format json knowledge
syn --no-input --no-freshness --format json knowledge --request request.json

syn shared-source --input <JSON> [--operator-bridge]

Request schema 1 shares typed metadata/operator dispatch with MCP shared_source. The MCP agent can describe public configuration; operator actions deny there. Native bootstrap/exact pending acceptance requires a separate current signing host through the bounded two-frame stdin/stdout bridge. No token/private key is accepted. Shared content requires a fresh scope read proof; old local/automatic write doors cannot publish without the exact host seal. This protocol foundation is documented in SHARED_SOURCE; real Soma issuer/Keychain and full strict-team composition remain separate acceptance work.

Team inputs use schema synapse.team-assurance-inputs/1, public trust and its independent trust_sha256, selected scope and unique actors containing external expected binding expectations and current signed snapshot objects. Authority timestamps use microseconds; existing local source observation and local trust timestamps remain seconds. Historical device eligibility is assessed at original issuer permit issuance, not the source preparation clock. Later administrative revocation preserves preceding decisions while currently_approved:false prevents confusing history with current permission. Use syn state witness --include-receipts --include-shared-seals --key-dir <independent-key-directory> and independently retain the resulting v3 witness and its separately selected public key. No retroactive receipts or team history are fabricated for a local/unsigned baseline.

Standard evidence exchange: syn state attest

state attest is a separate opt-in in-toto Statement v1 export; native report formats and defaults remain available. The subject hashes exact exported native evidence artifact bytes. Basic/strict assurance, originals, selected public trust/witness inputs, skipped checks and excluded surfaces are preserved.

syn state attest --profile basic
syn state attest --profile strict-local --trust <reviewed-trust.json> \
  --trust-sha256 <independent-digest> --since <witness.json> \
  --trusted-key <independent-witness-key> --dsse-key-dir <private-export-key-dir> \
  --artifact-output <new-file-outside-source.json>
syn state envelope-verify --input <dsse.json> --trusted-key <independent-export-key> \
  --artifact <exact-optional-subject-artifact.json>

The optional DSSE export key signs only the outer statement. Independent envelope verification reports signature and subject integrity; native source verification is not rerun and current publication authority is not granted. A failed native policy still exports its honest statement and exits non-zero. Artifact output cannot overwrite an existing file or modify the source. MCP state_attest and state_envelope_verify use the same cores; no MCP private-key path exists. See the versioned predicate.

Scoped advisory decisions (SYN-323)

syn decisions --fact note/a --fact note/b [--provider rules|HOST_ALIAS] reads an exact bounded source subset and emits synapse.source-decision-diagnostics/1. MCP decisions accepts {request:{facts:[{type:"note",id:"a"},{type:"note",id:"b"}],provider:"rules"}} through the same core. There are 42 MCP tools.

Source read authorization, accepted revision integrity, deterministic contradictions, topic, API version, environment and validity precede inference. Pairs are evaluated in both directions because entailment is directional. Unknown/truncated context or exhausted budgets produces abstention. The default rules baseline recognizes identical text and abstains from arbitrary prose. Models never approve or mutate memory.

See provider configuration and reproducible evaluation. Local NLI and Jev are opt-in experiments; the initial EN/PT benchmark failed its recall gate. No model download, Python runtime or hosted credentials are required by default.

Revisioned source acquisition (SYN-335)

syn sources --request '{"connector":"docs","document_id":"catalog","cursor":null,"notification_revision":null,"cancelled":false}' polls one exact host-configured document. --request - reads bounded JSON from stdin; MCP sources takes the same object in request and calls the same core. It returns current revision/digest/access provenance or an explicit no-content unavailable/denied result. It never creates accepted notes or publishes upstream patches.

See configuration, access mapping and adapter coverage. Git/Markdown and opt-in GitHub are implemented; other tools remain separately tracked adapters. There are 42 MCP tools.

Scoped source impact (SYN-327)

The same sources request accepts an optional operation (absent means {"op":"read"}). observe reconciles current source revision and returns only authorized matching dependencies; review pins a proposal ID; suggest_patch requires that reviewed ID and expected_revision, and returns an unpublished suggestion. queue creates an exact source-linked native note proposal; accept requires explicit CLI operator action, pending ID, exact review digest and a fresh matching upstream read. Generic pending accept and MCP cannot bypass that source check. Current adapters always refuse publish, including requests with reviewer consent.

See evolution states, dependency mapping and acceptance limits. Accepted historical local annotations do not establish current upstream truth; current upstream passages are served through fresh source acquisition.

Versioned knowledge process contract

knowledge is an additive CLI/MCP contract for local process clients such as Soma. It wraps existing core/index/source transactions; it does not create another memory database, an HTTP daemon, Rust FFI or a replacement for operational run history.

syn --no-input --no-freshness --format json knowledge
syn --no-input --no-freshness --format json knowledge --request request.json
syn --no-input --no-freshness --format json knowledge --request - < request.json

The default operation describes actual protocol/build/OS/architecture/workspace and supported capabilities. A release/version string does not authenticate the publisher. Clients independently select signed artifact metadata/publisher roots or an explicitly reviewed user-installed digest, verify architecture, and pin the actual executable. This repository remains private; no artifact publication or credential workaround is performed by adding the contract.

Request and response

A request has exactly schema, scope, budget, operation. Describe may omit scope/budget; workspace operations require both. Payloads are bounded to 256 KiB. Valid requests produce synapse.knowledge-response/1 with ok, result, error. Fixed error codes do not echo raw request/source text. Invalid transport/file/JSON inputs can fail before core dispatch; hosts must handle typed malformed/process errors.

{
  "schema": "synapse.knowledge-request/1",
  "scope": {
    "root": "/absolute/selected/workspace",
    "knowledge_workspace": "<actual acknowledged GUID or null for legacy reads>",
    "authority": "local-owner",
    "facts": []
  },
  "budget": {
    "max_output_bytes": 262144,
    "max_latency_ms": 5000,
    "max_tokens": null,
    "tokenizer": null
  },
  "operation": {"op": "query", "query": "database", "type": "note", "limit": 16}
}

Root/GUID must match the selected workspace. Exact facts filters contain typed {"type":"note","id":"decision"} identities and enter SQL before candidate retrieval; they are local selection, not remote ACL grants. Only local-owner is supported. A shared request fails with unsupported_shared_authority; it never falls back to local privilege or treats a cached binding as a current team grant.

CLI knowledge suppresses background freshness/model work. Query uses scoped lexical FTS directly, including builds with vector support; it does not embed or call a model. Current native source acceptance still respects separately configured native policy and any consented enrichment behavior. Unrelated workflows can ignore an unavailable optional knowledge dependency.

Citations, omissions and verification

Query returns actual raw Markdown prefixes, typed fact identity, exact raw whole-file SHA-256, path, provided byte/line range, accepted head, current source-manifest digest, effective native policy digest and explicit omissions/additional-candidate coverage. It validates raw source identity and consistency before/after retrieval under the writer lease. Governed external drift fails; uninitialized legacy reads remain partial. The returned prefix may not contain every lexical match; retrieval relevance is not semantic truth or a calibrated confidence score.

The profile is basic: an acknowledged source suffix does not attest pre-baseline history, authorship, independent witnessing, every index projection, general language consistency or agent attention. Those facets stay explicit. Retrieved documents are task evidence, never permission or executable instructions.

max_output_bytes bounds encoded response; max_latency_ms bounds elapsed core read work. The host must additionally bound stdout and enforce hard process deadline and cancellation. Filesystem work cannot be preempted by an elapsed-time check alone. Committed writes are not relabeled failed solely because a core latency target elapsed; after a host timeout inspect/retry the exact request/queue/receipt state.

Optional max_tokens requires the explicit offline tokenizer cl100k_base:tiktoken-rs-0.12.1. Actual BPE counts apply to supplied passage text only; metadata tokens are not counted. It is not an estimate of an arbitrary agent/model’s hidden prompt or tokenization. Unsupported tokenizer/budget combinations fail rather than guessing from characters. The tokenizer assets are included by the pinned upstream implementation, with no model fetch.

Proposal, review and operator decisions

propose takes a bounded note capture and exact context:

{
  "op": "propose",
  "capture": {"title": "Reviewed result", "body": "Chosen knowledge", "kind": "decision", "tags": []},
  "reason": "Explicit local review",
  "context": {
    "schema": "synapse.knowledge-proposal-context/1",
    "knowledge_workspace": "<actual GUID>",
    "idempotency_key": "<client UUID>",
    "run_id": "<actual operational run UUID>",
    "context_sha256": "<actual immutable Soma context digest>",
    "expected_head": "<exact query head digest>",
    "source_manifest_sha256": "<exact query manifest digest>",
    "policy_sha256": "<exact query native policy digest>",
    "sources": [{"path": "notes/source.md", "sha256": "<original raw source digest>"}]
  }
}

Run/context links are caller evidence references, not authenticated identity or proof that an agent used the sources. An initialized acknowledged baseline is required. Propose always queues; it does not auto-apply even when an old safe-auto-apply policy would allow another write tool. Identical retries return the same pending row; a changed request with the same key conflicts. Idempotency lasts while the operational index and pending rows are retained. Explicit prune/index destruction is not claimed to retain a durable request ledger.

review takes pending_id and returns exact retained payload/context plus review_sha256. The operator CLI accept takes both and rechecks source head, manifest, original source revisions, native policy and reviewed bytes inside the existing native source transaction. Old pending accept doors invoke the same opted-in source/policy guard; switching clients cannot make a stale proposal current.

The MCP knowledge tool uses the same core with agent authority: describe/query/ propose/review are available, but accept returns local_operator_acceptance_required. Reject returns local_operator_rejection_required there. This preserves the existing agent/human approval split. Local CLI actions are explicit operator/process intent, not authenticated shared reviewer identity or a sandbox against an already privileged local process. Current team/source admission requires the separate shared bridge; its absence is never an authorization fallback.

The negotiated reject operation takes pending_id and review_sha256 in the same scope/budget envelope. Its success result is {"pending_id":42,"status":"rejected","review_sha256":"<review digest>","retried":false}. The writer lease and SQLite transaction protect exact retained-row comparison, pending-state transition and the live audit decision. An unchanged rejected review can be retried with retried:true, without another audit append. Changed bytes fail with review_changed; invalid IDs/digests fail with invalid_pending_id or invalid_review_digest; accepted/undone states refuse with invalid_input.

Rejection preserves source notes, accepted seals, retained payload/context and prior audit history. Because it publishes nothing, a stale proposal can be discarded after source/head/proposal-policy drift. Acceptance keeps all existing freshness checks. Legacy pending reject shares the writer/state guard, but its ID-only command does not attest a displayed review and refuses repeated terminal-state decisions. Clients must check that descriptor operations contains reject; older binaries remain supported by retaining the pending intention and showing an unsupported rejection result, without falling back to the legacy command.

The audit append precedes SQLite commit. A crash or commit failure between them can leave a pending row with an already appended rejection entry. Exact retry is idempotent for committed retained rows, not a claim of crash-safe exactly-once audit delivery. See ADR-071.

Verification

Production core fixtures cover scoped raw citations, exact named tokenization, output omissions, wrong root/GUID/shared requests, drift, exact retries, changed requests/review, stale source/policy through old accept doors, queue-only policy and second-run reuse. tests/knowledge_mcp_smoke.py runs actual native CLI/stdio parity and the operator-only accept/reject split. tests/test_guarded_pending_rejection.py provides real-binary unittest acceptance evidence for exact rejection, terminal-state audit protection, retention, stale-source discard, scope and writer contention. All old command formats/tools remain; the additive MCP surface is 42 tools. Soma’s actual pinned-binary integration verifies the full read/run/review/propose/accept/ reuse path, while preserving its full private execution records.

Native shared source bridge, protocol foundation

This is the staged Synapse side of SYN-231/325/326. It introduces current scoped permits, protected reads and a recoverable host signing port. It does not yet prove the complete Soma issuer/Keychain runtime or strict-team dashboard profile; those issues remain open until the paired real-account integration is verified.

An existing local/unsigned ledger cannot be silently relabeled as a shared origin. Use an explicitly selected fresh workspace/policy and acknowledge unknown preceding history and plaintext retention before creating its limited baseline. Shared configuration pins a scope and reviewed authority-root digest independently of returned device/issuer artifacts. Ordinary local workspaces remain usable.

shared-source takes request schema 1 from a bounded --input file or one stdin line. describe returns public configuration metadata. configure requires the explicit operator door and an independent policy hash/CAS. An MCP agent can inspect metadata but cannot configure/bootstrap/accept; a self-declared role or model confidence cannot manufacture approval or an issuer signature.

For commit_candidate (or the retained limited bootstrap spelling), the explicit --operator-bridge holds the native writer lease while staging source/index state. It emits one bounded synapse.source-seal-required/1 frame with the exact prospective record, unsigned native receipt and its normative signing bytes in base64. The parent must enforce a finite child deadline/cancellation, validate exact scope/actor/key, and return a synapse.shared-source-seal/1 public envelope on stdin. No daemon, key file, private key or bearer/M2M credential is part of this bridge.

The native verifier requires genuine detached device receipt integrity, independently selected issuer roots, complete device bindings/key observations, current writer/key eligibility, exact historical review where needed and a fresh operation-specific issuer permit. That permit binds actual scope/policy/context, source event/sequence/head/record and complete signed receipt digest. Read, limited bootstrap and publication purposes are disjoint. Issuance before the native transaction start, wrong purpose/receipt/policy/actor/scope, missing trust or expired authority denies before installation. The lifetime is explicitly at most fifteen seconds; it is not an instant-revocation or trusted-client-clock promise. Publication also checks expiry/policy immediately before SQLite COMMIT.

Prepare-v4 retains the original public policy/actor/receipt/permit/binding/review bytes with the same exact-digest native source/index decision. An uncommitted crash restores preimages; a committed crash replays original public evidence before source record/head success without a host, private key or new signature. Older prepares 1/2/3 remain recoverable. Unsupported older binaries reject v4. A retained historical admission never authorizes another native transaction.

Shared content/read/receipt/resource/prompt and federation API doors require a fresh read-purpose capability in an explicit SYNAPSE_SHARED_READ_PROOF file supplied by the authenticated host. Keep that public capability owner-private outside Git, renew it per SDK-authenticated request/reconnect, and retain its finite expiry. It permits only the configured registered scope, not another project or publication. There is no silent local fallback. API controls do not sandbox a privileged host’s direct disk access.

Current proof: genuine Ed25519 fixture-root/device signatures through an actual native two-frame process; exact CLI/MCP metadata parity, 42-tool surface and operator denial; current scope/read expiry and old write-door denial; and eight actual process-death prepare/commit/evidence/head recovery boundaries, reopened twice without a signing host. The fixture-only test is separate from the real Soma SDK/Keychain proof below and from a consenting human adoption pilot.

See ADR-065 and SOMA-45. Independent witness coverage must include original shared-seal metadata as well as original receipts before strict-team assurance can report complete required coverage.

Exact staged handoff

Use the operator shared-source stage_baseline or stage_pending operation before requesting an issuer decision. Stage results contain candidate_sha256, original source event/sequence/record and, for queued facts, the exact public shared change. Staging retains original source images and releases the writer lease without installing source or accepting the queue. ReviewPending requires current scoped read authority and exposes the actual queued bytes with their review commitment.

CommitCandidate resumes only the explicitly selected candidate digest. The native record, original preparation observation and Markdown bytes are reused; the live index projects those same bytes. Current source/head/context/review policy and a fresh source permit are still required. A death after issuer acknowledgment before native WAL preparation leaves a durable candidate for explicit retry. Missing or changed source refuses installation instead of overwriting external edits.

Built-in capture/status/link mutations and supported batches are covered. Custom and NER mutations remain pending with an explicit unsupported result. The original operational queue row must remain available for the queued review guard; candidate retention does not promise automatic recovery of a separately destroyed index. Frontmatter/preparation timestamps remain untrusted claims, distinct from original issuer observation and current authorization time. See ADR-067.

The local-owner knowledge process contract explicitly refuses configured shared sources. Generic current-scoped reads and the shared operator bridge remain usable; no shared source is relabeled as a local owner grant. Portable original receipt and seal-set codecs support an independent checkpoint issuer without source body or private signing material crossing the process boundary.

Offline provisional notes

queue_note accepts only bounded caller-supplied note fields and a reason. It needs no network or read capability and enqueues a provisional local claim; it returns only the new pending ID and explicit unverified/pending facets. No source content is read, installed or attested. Queue inspection, staging and publication still require current scoped read/review/operation authority. An authenticated actor cannot be self-declared in this offline request, and no path, external target, private-key or authorization slot exists in its capture shape. Both CLI and MCP use the same core behavior. Generic shared-source reads retain their capability checks.

The legacy accept spelling fails with an explicit requirement to use stage_pending and then the independently selected commit_candidate. A retry cannot silently choose a new random candidate after an issuer acknowledged an older event. Ordinary account-free local-owner acceptance remains available.

Real Soma integration now includes two local Febasi SDK accounts and actual Keychain device keys, distinct review of immutable conflicting notes, native source publication and a backend-issued v3 checkpoint verified by the native strict-team verifier against an independently selected issuer key. Later device revocation preserves historical evidence and denies current reconnect/publication. This proof is separate from a consenting human workflow pilot, which remains outstanding.

Explicit source revision acquisition

Synapse monitors selected upstream documentation through optional outer adapters. It preserves canonical source revision/digest/citation/access provenance and proposes knowledge separately. It does not become the authoring application or import an entire enterprise automatically.

Host configuration and access

Set SYNAPSE_SOURCES_CONFIG to an owner-private regular JSON file, at most 64 KiB, outside the knowledge workspace. Logical aliases and stable document IDs are the only selection accepted from CLI/MCP. Review these mappings as host capabilities; neither Markdown nor agents choose a token, identity, executable or arbitrary URL.

{
  "schema": "synapse.source-adapters/1",
  "connectors": {
    "docs": {
      "kind": "git_markdown",
      "repository": "/absolute/selected/git/repository",
      "reference": "main",
      "documents": {
        "catalog": {"path":"docs/api.md","readers":["local-owner"],"api_version":"v2","environment":"prod"}
      }
    },
    "github-docs": {
      "kind": "github",
      "owner": "selected-owner",
      "repository": "selected-repository",
      "reference": "main",
      "key_env": "SYNAPSE_GITHUB_SOURCE_TOKEN",
      "documents": {
        "catalog": {"path":"docs/api.md","readers":["EXACT_ROOT_SUBJECT_UUID"],"api_version":"v2","environment":"prod"}
      }
    }
  }
}

Local-owner mode uses local-owner by default. A separately trusted local host may set SYNAPSE_SOURCE_ACTOR; this is an explicit host mapping, not account authentication. Shared workspaces ignore that override and derive the subject from the current verified Root read capability. Source document readers must include that exact subject. The Root policy is checked before adapter selection/transport and again before returning content. Host policy bytes are hashed as acl_reference and checked again after acquisition; changes during execution deny output.

Git reads only a pinned commit object through fixed git commands, with user/global/system Git settings disabled, no hooks and a 10-second overall process deadline. Uncommitted edits are ignored; symlink/submodule objects and path traversal are rejected. A stable document ID can be explicitly remapped to a renamed Markdown path; its URI/revision changes visibly.

GitHub requires network_backends; key_env:null permits public reads without credentials. Credentials remain only in the environment. Use narrowly scoped GitHub App/user tokens with repository Contents read access. Current GitHub API access intersects the host document ACL; success is not a write grant. Resolve the branch/ref to an exact commit, read its Contents bytes, and recheck the ref with the same credential before output. Redirects/download URLs are never followed. Deleted/restricted/expired/rate-limited/failed sources expose no stale body. A fresh next poll is the bounded retry; no unbounded automatic retry loop runs.

Bounds, cursors and write policy

One request selects one exact document. Content is bounded to 256 KiB and the GitHub JSON response to 512 KiB, with a 10-second total upstream deadline. There is no background scheduler or secret-bearing webhook server. cancelled:true aborts before transport; in-progress work is bounded by its deadline. Webhooks are untrusted hints. Cursors/hints that disagree with the fresh upstream revision trigger a bounded latest-state reconciliation; this does not claim complete intermediate revision/event history. Replayed hints cannot replace current bytes with their claimed version. Source evolution owns durable dedup and impact candidates (SYN-327).

Both adapters advertise write_back:false. The request schema has no publication operation or reviewer-consent field that can unlock it. Suggested patches require a future explicit write capability plus exact upstream revision and reviewer consent. Possessing a token with broader GitHub permissions does not enable writes. Default acquisition remains read-only and makes no local source changes.

Adapter coverage

tests/sources_smoke.py exercises actual Git update/deletion, repeated notifications, policy revocation, cancellation, uncommitted edits, traversal denial and CLI/MCP parity. Optional SYNAPSE_TEST_LIVE_GITHUB=1 uses the authenticated local gh credential only in process memory for a read-only private repository probe; CI never requires it.

Primary transport contract: GitHub Contents API, commit API. ADR-049 and ADR-069 govern the separation of acquisition, source authority and acceptance.

Source evolution and scoped impact

A detected source revision creates review candidates. It never silently replaces an accepted note or treats an unavailable copy as current truth. The source API always acquires current upstream revision/access before serving passages or projecting impact details.

Dependencies and access

The private connector configuration accepts a top-level consumers array. It maps explicit consumes / depends_on dependencies from a connector/document to squad/project decisions and owned documentation. This is reviewed host configuration, not an inferred permission grant.

{
  "id":"squad-a-integration",
  "owner":"EXACT_AUTHENTICATED_SUBJECT",
  "relation":"consumes",
  "connector_id":"docs",
  "document_id":"catalog",
  "api_version":"v2",
  "environment":"prod",
  "readers":["EXACT_CURRENT_OPERATOR_SUBJECT"],
  "fact":{"type":"project","id":"squad-a"},
  "documentation_uri":"https://selected.example/squad-a/integration"
}

The current operator must be allowed by the source document and consumer ACL; the candidate owner must also be allowed by the source document. Exact version/environment filters apply before retrieving the optional native consumer identity. Missing native facts receive no candidate. The host must keep these explicit source/consumer grants current; they do not infer account membership from names. Shared operator identity comes from the verified Root read capability; an environment override cannot impersonate a shared subject.

For the API v2 authentication example, two matching authorized squads get source-linked review candidates. A restricted owner, v1 consumer and test-environment consumer get no recipients/details. Native consumer_fact, relation, owned documentation reference and full source citation accompany the candidate. No notification is sent to people automatically; the caller receives authorized candidates for a dashboard/workflow.

Observation and lifecycle

Metadata records exact connector/document/revision/digest/observation time/access hash/URI/version/environment. Repeated deliveries of the same revision/access/content deduplicate candidates. A reused immutable revision with changed bytes fails as divergence. A cursor/hint gap reconciles the latest upstream state with bounded acquisition; unobserved intermediate revisions are not invented. A stable document ID can be explicitly remapped after a rename.

States distinguish observed revisions, analyzed dependencies, proposed candidates, explicit review, native accepted annotation, superseded candidates and unavailable sources. A new revision supersedes previous candidates. Deletion, revocation or acquisition failure removes current availability and returns no old passage or old impact detail. Restored access creates a candidate that needs fresh review; prior approval is not reused silently.

The operational lineage is a bounded, owner-private metadata ledger per verified host actor, under .synapse/source-monitor, with durable atomic replacement while holding the native writer lease. It retains no upstream body or credential. History/candidate count is bounded to 512 and serialized state to 4 MiB; exhaustion fails rather than silently dropping history. This ledger is not a signed accepted-knowledge proof. Accepted source history remains the native governed transaction evidence. Existing Git/index/receipt distinctions continue to apply.

Review, patch and native acceptance

Use the same syn sources --request / MCP sources contract with an additive operation:

{"connector":"docs","document_id":"catalog","cursor":null,"notification_revision":null,"cancelled":false,"operation":{"op":"observe"}}

review takes proposal_id. suggest_patch takes the reviewed ID, current expected_revision and bounded replacement; it produces a source-linked suggestion with a replacement digest, not a published edit. Revision, access policy or document mapping changes invalidate it. Both current adapters have write_back:false; publish fails even with explicit consent or a broadly privileged token. A future write adapter needs explicit capability, reviewer consent and an upstream concurrency precondition.

queue takes a reviewed proposal and explicitly authored annotation body. The exact note payload retains x-upstream-source, x-source-impact, x-source-consumer and x-source-dependency. Repeated identical queue requests return the original row. The queue remains pending until an operator uses accept with the exact returned pending_id and review_sha256. Fresh upstream access/revision/digest/policy must still match; exact pending bytes are checked again inside the native transaction. Generic native acceptance refuses source-derived queue rows without fresh adapter evidence, and MCP cannot invoke operator acceptance. Native source/history/index/status commit together through the existing transaction primitive.

This first acceptance slice is local-owner only. Shared observation/impact uses authenticated Root reads, but shared source-derived acceptance requires a dedicated Root host workflow and remains disabled. It cannot be bypassed through generic shared candidate sealing. The native accepted note is a historical, locally authored annotation, not a replicated live upstream page. Generic note retrieval preserves that historical annotation; it does not assert fresh remote authorization or currentness. Current external passages and impact views must use the source API. Privileged raw filesystem access remains outside the API’s access-control contract.

Upstream reads and local commits have optimistic preconditions, not an atomic transaction across GitHub and the local filesystem. No distributed write guarantee, complete enterprise ACL synchronization, background worker or human pilot ROI is claimed. Queue/index recovery has the same limits as the existing native operational queue; rebuilding an index does not invent missing review rows.

Verification

tests/source_impact_smoke.py uses actual Git commits and the native CLI/MCP on owned synthetic fixtures. It proves two-squad fan-out with version/environment/restricted-owner exclusions, idempotent notifications/queueing, review, explicit native acceptance and its preserved source citation, generic/MCP approval denial, changed authentication source, rename, stale patch/queued acceptance, revocation/deletion and no upstream mutation. Native state verify validates accepted local history before/after source changes. Pure tests cover immutable revision divergence, access-precondition changes, restored-access review and supersession. These are engineering conformance tests, not a consenting human field pilot.

See ADR-070, SYN-327 (#312), SYN-335 (#96) and the optional decision experiment.

Synapse: Architecture

Two interfaces, one governed core, inspectable knowledge on disk.

This guide describes the current source tree. A published executable can implement an older contract; inspect its version and release notes before integrating a newer surface. The ADR index records the decisions and the limits of each implementation slice.

Runtime topology

Every read or write supported by an edge must bind to the corresponding shared core operation. An interface-specific approval rule is a drift defect. Synchronous SQLite work runs through spawn_blocking at the MCP boundary; other CLI commands do not need a long-running server.

Knowledge lifecycle

The knowledge process contract is a bounded CLI/MCP interface for hosts such as Soma. It returns source-cited passages with raw whole-file digests, accepted head, source manifest and explicit omissions. Hosts pin the actual executable and enforce stdout limits, cancellation and hard deadlines independently of the core budget.

Knowledge proposals always queue. An operator reviews the exact payload, then acceptance rechecks source head, manifest, original source revisions, policy and review digest. An MCP caller may describe, query, propose and review; it cannot invoke local operator acceptance. Other write tools retain their own documented proposal and safe-application policy rules. Read content and model confidence never grant permission.

Content, projection and operational state

yaml_serde handles frontmatter with ordered mappings (ADR-054). Serialization preserves the supported field semantics and order; it does not preserve every original YAML comment or quoting choice. Entity identity is (type, id), so project/alfa and api/alfa may coexist. Slugs follow the documented ASCII kebab-case rules. Explicit rename operations update supported references through one workspace transaction.

The index materializes relationships such as project membership, API ownership and task scope. Every SQLite connection enables foreign keys. Reindexing repairs the derived projection; it cannot manufacture lost review context or erase a governed source mismatch.

Durable source transactions

The transaction protocol is documented in ADR-056, extended by ADR-057, ADR-058 and ADR-065.

Repeated recovery reuses the original committed bytes. It does not request a new signature or reinterpret historical approval as current permission. Changed database incarnation, path escapes and unexpected external edits preserve evidence and refuse unsafe repair.

The writer lease is advisory. External editors and raw filesystem readers can observe a short installation window. Unix directory fsync provides the documented power-loss ordering; other platforms have a narrower durability claim. A privileged disk owner, complete disk loss and dishonest hardware require independently retained evidence and backups.

Source history and verification

An explicitly acknowledged baseline starts the governed Markdown suffix. Unknown preceding history remains unknown. In an opted-in workspace, mutations require current content to match the accepted manifest; external changes need explicit reconciliation.

Source images are retained as private plaintext metadata. Manual retention, filesystem permissions and encryption policy matter: hashes provide no confidentiality. Attachments, keys, arbitrary non-Markdown files and excluded directories are outside the documented Markdown evidence scope.

A successful historical check has a different purpose from a current operation permit. Missing, unsigned, stale or skipped inputs remain visible. Complete strict profiles deny required gaps instead of silently downgrading them. See provability, ADR-066 and ADR-067.

Retrieval and optional models

Hybrid retrieval combines FTS5/BM25, optional vector search and graph-neighborhood signals through reciprocal rank fusion. A model-ready local binary can use the configured semantic backends; without consented model assets, retrieval degrades to supported lexical/graph paths without downloading a model implicitly. --semantic and --no-vector select the documented search modes.

The default semantic stack uses local embeddings and entity recognition. Optional network providers require explicit configuration. Insertion-time enrichment can add supported vectors and link proposals, subject to the native transaction and proposal rules. The model guide explains downloads, cache and provider choices.

The bounded host knowledge query intentionally uses scoped lexical retrieval and does not start model inference. General contradiction assessment is a separate experimental advisory port. Exact diagnostics check selected fields, intervals and reference classes; probabilistic output cannot change those results, source or authority. The current grouped experiment failed its recall gate, so it establishes no default semantic-consistency model. See ADR-062, ADR-068 and the measured experiment.

Hosts, source adapters and shared authority

A local-owner workflow remains account-free. A host such as Soma can add account, workspace, project and device authority without sending private signing keys or bearer credentials to Synapse. The native shared bridge requires fresh scoped public host evidence; the local knowledge contract rejects shared authority rather than falling back to local privilege.

Shared candidates freeze exact source bytes before independent review. Publication resumes an explicitly selected candidate and requires fresh current admission. Historical seals remain historical evidence after their operation lease expires. Supported shared built-in mutations, offline provisional notes and the remaining adoption-pilot boundary are described in SHARED_SOURCE.md.

Current external source adapters read Git/Markdown and optional GitHub. Every passage or impact projection rechecks upstream revision and access; there is no stale remote-body cache fallback. A change produces bounded review candidates and metadata lineage. Native local annotations preserve exact upstream citations, while shared source-derived acceptance and all upstream write-back remain disabled in this slice. Notion, Jira and Confluence adapters are planned integrations. See source adapters and source evolution.

Code map and maintenance

The current source exposes 42 MCP tools; consult MCP.md for the actual surface. Do not infer a packaged release’s tool count from the source-tree documentation. Module size thresholds and review rules remain in ADR-015. Update diagrams when a responsibility, arrow or trust boundary changes, using the visual asset notes.

Changelog

All notable changes to synapse are documented in this file.

Format inspired by Keep a Changelog; versioning follows Semantic Versioning. Generated automatically from Conventional Commits by git-cliff.

[1.5.1]: 2026-10-18

This patch repairs release documentation packaging after the Windows v1.5.0 archive used checkout-converted line endings. Documents now use exact committed Git bytes, and all four archive changelogs must match the source receipt before signing or publication. The strict npm consumer is unchanged. Documentation-site diagrams also use pinned local renderer assets. This adds no CLI or MCP feature.

✅ Testing

• SYN-343: Record independent release producer controls (bebda1f)

• SYN-343: Expose checkout-dependent release documentation (316fe40)

• SYN-342: Challenge chapter and CLI diagram coverage (fc14858)

• SYN-342: Expose raw diagrams in the generated docsite (467f0eb)

🐛 Bug Fixes

• SYN-343: Bind packaged documents to committed source bytes (c902f44)

• SYN-342: Bundle pinned Mermaid assets in the docsite (140b2b5)

📝 Documentation

• SYN-343: Align contributor release instructions (17d596f)

• SYN-343: Record frozen patch candidate verification (66f44b0)

• SYN-342: Preserve readable diagram layouts (dd10f9b)

• SYN-342: Record independent publication gate challenges (52e9fd9)

• SYN-342: Record bounded docsite diagram evidence (2bfad74)

🤖 CI

• SYN-342: Require independent publication coverage tests (cedfcce)

🧹 Chores

• SYN-343: Prepare patch version and reviewed release notes (e644232)

[1.5.0]: 2026-10-18

♻️ Refactoring

• SYN-231: Isolate preparation and document projection (5740e20)

✅ Testing

• SYN-340: Require metadata-free release packaging (2355ea9)

• SYN-340: Challenge originating release workflow boundaries (d9ef69f)

• SYN-338: Challenge native rejection boundaries (271bb19)

• SYN-338: Preserve seals and retry timestamps (7c9801e)

• SYN-325: Require explicit missing team identity failure (ac6548d)

• SYN-326: Verify issuer rotation and historical trust (b6777b1)

• SYN-329: Keep audit fixtures inside retention window (c87dcde)

• SYN-328: Prove pre-push child repository isolation (3714fa1)

✨ Features

• SYN-327: Govern scoped source impact proposals (6b5aa85)

• SYN-335: Add explicit revision source adapters (3f5cf03)

• SYN-323: Add scoped advisory decision providers (7b2eee1)

• SYN-320: Export standard native state attestations (efae9ed)

• SYN-231: Queue provisional offline shared notes (5fedf25)

• SYN-231: Retain exact source candidates before review (df488f0)

• SYN-325: Compose historical team source assurance (6bc3b38)

• SYN-231: Seal native shared source operations through a host (05b98c5)

• SYN-261: Pin commit roster revisions and validity (2ffa90b)

• SYN-321: Add bounded versioned knowledge process contract (b56163c)

• SYN-319: Report scoped exact contradictions without prose claims (e97ea67)

• SYN-318: Gate memory ci with pinned assurance policy (af42a51)

• SYN-231: Verify exact historical shared admissions (63af722)

• SYN-326: Verify portable scoped authority evidence (5db71d9)

• SYN-325: Persist receipts and require local assurance (5beacf3)

• SYN-324: Preserve governed source state and witnesses (c810f32)

• SYN-261: Verify commit SSHSIG against pinned trust (7d1010d)

• SYN-316: Add INV-13 logical-contradiction invariant to verify (701e065)

🐛 Bug Fixes

• SYN-340: Omit host metadata from release archives (76ea7e0)

• SYN-340: Bind mirror receipt to originating event head (e2960ea)

• SYN-340: Reject ambiguous release artifact staging (8b8e727)

• SYN-338: Guard exact pending rejection decisions (d272447)

• deps: Update rustls for current security advisories (ece3c34)

• SYN-318: Verify stripped native ci artifacts within budget (6512983)

• SYN-324: Preserve workspace writes across commit failures (fd58423)

• SYN-330: Merge security and knowledge framework contracts (4f627bb)

• SYN-330: Replace unsupported YAML and patch advisories (5923c07)

• SYN-328: Isolate git environment before pre-push checks (911739b)

💄 Style

• SYN-316: Inline let-and-return in inv13 test helper (8d82f51)

📝 Documentation

• SYN-340: Retain verified producer compatibility evidence (0557133)

• SYN-340: Preserve independent release boundary evidence (679fafc)

• SYN-340: Regenerate integrated 1.5.0 release notes (a728745)

• SYN-339: Record independent dependency review (bb1edeb)

• SYN-339: Freeze stable validation evidence (4bde86d)

• test: Document required native contract gates (6646799)

• diagrams: Merge semantic and evidence corrections (0722253)

• diagrams: Clarify topology and restore measured chart data (c419a80)

• product: Merge the visual memory architecture (b0293df)

• guides: Align evidence and distribution boundaries (696562f)

• product: Visualize governed memory and integration boundaries (9b9d732)

• standards: Merge readable copy cleanup (07c6e4c)

• standards: Rewrite readable copy without em dashes (bd57e60)

• standards: Merge English positioning and public copy (b3bc498)

• standards: Align English positioning and public copy (56b22dd)

• SYN-109: Publish searchable canonical documentation (6072d46)

• SYN-325: Align evidence copy with Febasi conventions (f712bea)

• SYN-236: Reconcile backlog IDs and execution priority (195f1aa)

• SYN-322: Define knowledge framework and trust contracts (444dd93)

• research: 2026 market positioning and Febasi substrate brief (3ceddd0)

• readme: Correct npm install wording (no runtime download) (15911b3)

• readme: Restructure the proof, scorecard hero and 2-up grid (1c16a3f)

• readme: Surface verify invariants, mcp tools, npm, day-to-day (56c4139)

• changelog: Release v1.4.0 (f4608d8)

🤖 CI

• SYN-338: Unify required native contract validation (c32d85c)

🧹 Chores

• SYN-340: Integrate verified dependency pruning (14673ae)

• SYN-339: Prune unused dependency declarations (4f51d6a)

• SYN-340: Prepare reviewed 1.5.0 release inputs (98cf748)

[1.4.0]: 2026-07-13

♻️ Refactoring

• SYN-103: Move npm publishing to the public mirror (option B) (b255007)

✨ Features

• SYN-103: Npm/npx wrapper via per-platform packages (#83) (d793acd)

• SYN-102: Homebrew tap formula + release automation (#82) (bf5e9c3)

• SYN-108: Sign release artifacts with keyless cosign (#88) (a88c949)

📝 Documentation

• SYN-103: Point npm package at the public mirror + humanise copy (720bfa8)

• changelog: Release v1.3.0 (6b88949)

🧹 Chores

• release: V1.4.0 (0b1c5dd)

• SYN-102: Drop the Homebrew distribution path (9b56772)

• SYN-103: Publish the npm wrapper under the @febasi org scope (90309fb)

[1.3.0]: 2026-07-07

✨ Features

• bench: Phase-B VACUUM + bitemporal grader assertion (#281,#286) (a65caf0)

• SYN-300: Thread –workspace into syn mcp install (#287) (15d3e7f)

🐛 Bug Fixes

• SYN-315: Make update_status corrections bitemporal (#289) (c88ec28)

📝 Documentation

• adr: Resolve the v1.3.0 spikes + scoping decisions (e6250e0)

• changelog: Release v1.2.0 (26c456b)

🧹 Chores

• release: V1.3.0 (f4a187b)

[1.2.0]: 2026-07-06

♻️ Refactoring

• SYN-304: Keep search and mcp modules under ADR-015 budget (e221264)

• SYN-301: Split embed/hybrid under ADR-015 (0 red) (6208ed2)

✅ Testing

• SYN-310: Declare new MCP surface in the parity manifest (f25b023)

• SYN-298: OutputSchema strict-client conformance + bench README (8e95525)

✨ Features

• SYN-306: Composite parallel search + compatibility score (fe1457c)

• SYN-309: Actionable MCP errors + read-time _meta hints (ca02543)

• SYN-312: Five governed-workflow MCP prompts (e7d9154)

• SYN-311: Self-describing vocabulary via syn context + resource (ba8ce57)

• SYN-310: Workspace_health MCP tool (agent-facing digest) (c1e6665)

• SYN-304: Fix agent-asset drift + no-drift test; surface verify (9122132)

• SYN-304: Per-hit relevance signal on hybrid search (fa3a128)

• SYN-304: Add MCP tool annotations and fix doc currency (838b48b)

• SYN-303: Governed capture from agent-supplied context (MVP) (8b01b91)

• SYN-254: Normalise identity match (case/accent/whitespace) (e4597bb)

• SYN-301: Passage-level chunked embeddings + opt-in reranker (d802cb1)

• SYN-301: Deterministic structure-aware markdown chunker (452064f)

• brand: Visual system + 6 benchmark/brand cards for the READMEs (7e902b7)

• SYN-298: Qa –distractors: the noise-scale axis for scenario D (2ae60dc)

• SYN-300: Syn mcp –workspace: serve a brain from any directory (31d234b)

• SYN-298: Bitemporal-probe: SYN-223 –as-of correctness, isolated (ed3f133)

• SYN-298: Scenario D: Q&A three-leg attribution + LLM judge (6bf349e)

• SYN-298: Correction + abstention scenarios; capture agent answer (59fc894)

• SYN-298: Gate-probe: SYN-242 contradiction gate in isolation (55bd6d5)

• SYN-298: Isolate agent to MCP, retry zero-tool turns, Wilson CI (68833e6)

• SYN-298: Headless Claude Code driver: pass@1 + pass^k + cost (8204468)

• SYN-298: Synapse-bench loop: deterministic state grader (fbeaaa4)

• SYN-296: Persona-bench: recall-at-scale on persona corpora (055e4f4)

• SYN-296: Add 6 persona fixtures for realistic bench scenarios (a7e63e1)

• SYN-292: Syn undo Phase 2: reverse link + update_status (5e2a0c4)

• SYN-293: Real-backend RAM/quality charts + clean-models command (d05b4d5)

• SYN-293: Add breaking-point bands to the latency scaling chart (034eb81)

• SYN-293: Benchmark v2 phase A: latency & index-size curves vs N (2a114f6)

• SYN-106: Freeze the v1.0 MCP tool surface (+ BR-104/105 policy) (918482c)

• SYN-290: Reproducible benchmark stamps + deterministic SVG charts (bbb1c54)

• SYN-289: Synapse-check: GitHub Action running syn verify in CI (469577e)

• SYN-288: Syn mcp install: zero-friction MCP registration (b0fe276)

• SYN-287: Syn undo: first-class reversal of an accepted create (9b9437b)

🐛 Bug Fixes

• SYN-271: Reindex –relink + exclude all enrichment edges from dump (97269d1)

• SYN-301: Reranker scores the snippet, not the full body (7a97698)

• SYN-298: Retry transient claude -p crashes too, not only zero-tool (aed8fd1)

• SYN-297: Emit MCP outputSchema strict clients accept (5c686e0)

• SYN-293: Index hard negatives (kind: reference, not note) (d99c735)

💄 Style

• synapse-bench: Cargo fmt corpus.rs (a07e352)

📝 Documentation

• adr: Accept ADR-044 with the persona-bench k-sweep result (82afdfc)

• adr: Add ADR-044 (composite search) and ADR-045 (model policy) (6521080)

• SYN-303: Add ADR-043 for governed agent-supplied capture (85f62f9)

• brand: Add retrieval-quality chart + LTR research note (8f2d021)

• SYN-301: Accept ADR-042, record measured recall@1 0.75 to 0.85 (3f56f97)

• SYN-301: Mark plan 023 in progress (chunker landed) (8ffcbeb)

• SYN-301: Add ADR-042 and plan 023 for retrieval quality (a2ffaee)

• brand: New wordmark subtitle governed memory for AI agents (70698d6)

• readme: Logo hero, tables, new write-flow banner, benchmark guide (71c468e)

• readme: Professional rewrite with brand visuals (e2d1d09)

• SYN-298: Record noise-scale sweep + bitemporal-probe results (d881819)

• SYN-298: Scenario-B finding: update_status is not bitemporal (361b1f9)

• readme: Add two brand-styled mermaid diagrams (0d089cf)

• SYN-298: Scenario D result: e2e 100% beats recall@10 80% (b0b39a6)

• readme: Slim to brand + key benchmarks; add BENCHMARKS.md (3c67cb9)

• SYN-298: Consolidate round-2 results (B, D-abstention, gate-probe) (1350dd6)

• SYN-298: First agent-in-the-loop findings + scenario fixtures (61a48a2)

• ADR-041: Agent-in-the-loop benchmark driver decision (07f3382)

• SYN-298: Agent-in-the-loop benchmark research + methodology (f761c79)

• SYN-296: Persona recall curve + finding (no degradation at scale) (0adddb3)

• SYN-293: Refresh real charts with adversarial hard negatives (fe306ad)

• SYN-294: Correct the FTS5 external-content claim (it’s standard) (66f3e70)

• research: Benchmark redesign: scaling, resources, correctness (87c78be)

• SYN-215: Set Lil Syn as primary mascot, constellation secondary (c5a9699)

• SYN-291: Currency pass to v1.0/v1.1 + benchmark embed + MIGRATING (5d9ae36)

• repo: Refresh CLAUDE.md current-state to v1.0.0 + v1.1.0 plan (7c15b6f)

• changelog: Release v1.0.0 (e016b5f)

🧹 Chores

• release: V1.2.0 (eac07dc)

• SYN-102: Add Homebrew formula (pending tap repo publication) (9c506f8)

• repo: De-reference removed spike from .gitignore comments (785a951)

• repo: Remove dead SYN-89 embedding-backend spike (0b4ba23)

[1.0.0]: 2026-06-21

♻️ Refactoring

• core: Split pending/verify test modules (ADR-015) (e33fb4e)

• SYN-281: Group verify flags + one built-in link extractor (d89c407)

⚡ Performance

• SYN-277: Score syn stale from the indexed frontmatter (82ab35e)

• SYN-275: Bulk-load body/tags to drop the embed_all n+1 (d33b4ce)

✅ Testing

• SYN-280: Harden migration paths + document expand-only policy (4cda405)

• SYN-279: Harden apply (disjoint supersede, link FK, multi-EAV) (e2ff923)

• SYN-278: Lock custom ref-link reindex round-trip + fix comment (4048abb)

• SYN-268: Fuzz the untrusted input boundary (proptest-first) (e1c5c8f)

• SYN-267: Stateful supersession + temporal proptest (9bea0ae)

• SYN-265: Invariant proptest suite for index coherence (0862cf1)

• SYN-264: Differential CLI-MCP port-parity suite (ab3ef77)

✨ Features

• SYN-270: Offline witness checkpoint + verify –since consistency (e4c1eab)

• SYN-269: Syn verify –rebuild attestation with localized diff (3838a09)

• SYN-266: Deterministic replay engine + clock seam + verify –deep (a533587)

• SYN-263: Syn verify + signed report on both doors (58e7bbe)

• SYN-262: Canonical logical index dump + verify report schema (3856ccd)

🐛 Bug Fixes

• SYN-274: Reject path-traversal in types.toml store_dir (17bd617)

• bench: Repair API drift so synapse-bench compiles and runs (3b9f517)

📝 Documentation

• SYN-282: Add provable-non-corruption positioning whitepaper (67ed91b)

• SYN-276: Record the ort rc posture for v1.0 (ADR-038) (aeb155b)

• SYN-273: Fix stale tool count (24) and adr count (37) (1ed4218)

• SYN-272: Lead the README with syn verify and the four pillars (cc9995d)

• handoff: V1.0 Hardening self-contained next-session prompt (909a64b)

• roadmap: Add v1.0 Hardening phase (syn verify, SYN-262..270) (6bbf486)

• research: Provable non-corruption study for syn verify (v1.0) (5a3b2af)

• changelog: Release v0.11.0 (c543962)

🧹 Chores

• release: V1.0.0 (26d21d0)

[0.11.0]: 2026-06-17

⚡ Performance

• SYN-251: Skip re-embed+NER when embeddable content is unchanged (cbb7dd3)

✅ Testing

• SYN-258: Temporal-correctness invariant for at + as-of (d0179d6)

✨ Features

• SYN-249C: Doctor reports HEAD commit signature posture (ADR-034) (cf5d0d0)

• SYN-248: Per-type profile-vs-log decay policy (ADR-033) (ebb2997)

• SYN-255: Opt-in –near anchor-distance reranker (e1e8bcd)

• SYN-245: Explainable mutual-kNN semantic edges in connections (aecf733)

• SYN-254: Identity-field duplicate detection routed to the gate (7de6daa)

• SYN-259: Valid-time pushdown to FTS candidates + search –type (7b3d684)

🐛 Bug Fixes

• SYN-248: Use is_none_or for the decay-policy lookup (clippy) (55c2409)

• SYN-260: Enforce no-unwrap lint + repair inert pre-commit fmt gate (271d9d8)

📝 Documentation

• roadmap: Mark v0.11 active issues complete in project state (ffdab59)

• roadmap: Reshape v0.11 issues per 4-subagent direction study (bd96c8e)

• changelog: Release v0.10.0 (e1aaf5c)

🧹 Chores

• release: V0.11.0 (df7a8a8)

[0.10.0]: 2026-06-15

✨ Features

• SYN-242: Propose-time contradiction detection forces the gate (4b6fbc1)

• SYN-252: Proposal-quality contract prompt + docs (0198e81)

• SYN-250: Trust-weighted hybrid ranking, shared decay curve (48008ed)

• SYN-257: Kind-aware set_field: custom update_status + F1 close (a173ec2)

• SYN-256: Syn changes CLI + blame/diff MCP tools (both doors) (3cfa28d)

📝 Documentation

• mcp: Fix local-read tool count comment (9 -> 11) (90b829d)

• roadmap: Mark v0.10 complete in project state (4ba1992)

• roadmap: Refocus v0.10 on memory-quality, defer rest to v0.11 (1bc1ef6)

• mcp: Correct tool count to 21 (search_everything + query) (89606d6)

• changelog: Release v0.9.0 (f601a7d)

🧹 Chores

• release: V0.10.0 (c4b85d5)

[0.9.0]: 2026-06-14

♻️ Refactoring

• SYN-227: Split reindex tests into reindex/progress_tests.rs (3bf3848)

• SYN-234: Split custom-type reindex into reindex/custom.rs (d3244f5)

• audit: Split chain + checkpoint into submodule (ADR-015) (aa57f48)

⚡ Performance

• SYN-227: Fix super-linear reindex (8s -> 0.4s at 10k) (1a1d1df)

✅ Testing

• SYN-227: Synthetic-corpus perf budget for reindex + search (ee998e2)

✨ Features

• SYN-223: Supersession write rules + belief-time axis (ADR-031) (446fe18)

• SYN-223: Add as-of valid-time filter across search, list, and at (b8a603d)

• SYN-223: Valid-time schema + reindex population (ADR-027) (0152d39)

• SYN-240: Mcp recent_changes per-field deltas (99f9168)

• SYN-228: Syn import: Markdown vault to governed proposals (82745d8)

• SYN-234: Materialize graph edges from custom ref fields (5ca373c)

• SYN-226: Search_everything MCP tool (RRF over all kinds) (9173a5f)

• SYN-234: Governed MCP create of custom-typed entities (fcb6986)

• SYN-234: Query filter by custom indexed field (EAV payoff) (2e1d926)

• SYN-234: Syn ls/show/rm –type <kind> for custom entities (5bbcbcd)

• SYN-234: Syn new –type <kind> creates custom-typed entities (40ccb54)

• SYN-234: Reindex registered custom types into entities + EAV (3cea002)

• SYN-234: Add registry resolve gate and validate_doc to core::types (8ffa099)

• SYN-234: Add entity_fields EAV table for open-type indexed fields (e27f05e)

• SYN-228: Syn export –as obsidian (markdown vault + wikilinks) (2cdaf3c)

• SYN-234: Types.toml validation registry + syn types (4612bce)

• SYN-247: Syn provenance: portable signed provenance receipts (6ac53ab)

• SYN-244: Syn connections: ego graph as JGF (SYN-243 contract) (995315a)

• SYN-224: Syn stale: advisory list of decayed AI facts (c6ab60d)

• SYN-241: Deterministic per-fact trust score (ADR-029) (35302ab)

• SYN-240: Syn diff: per-field before/after over git (bf8d637)

• SYN-240: Syn blame: AI provenance lineage of an entity (6980735)

• SYN-249: Per-author audit segments (merge-safe writes) (b79ae36)

• SYN-249: Attribute audit entries to the deciding identity (ebe95ff)

• SYN-239: Wire chain + checkpoint into syn audit verify (279c6af)

• SYN-239: Ed25519-signed audit checkpoint (truncation defense) (fbbb824)

• SYN-239: Hash-chain the audit trail + chain verification (820bf1f)

🐛 Bug Fixes

• docs: Close intra-doc link and html tags for cargo doc (c1929b2)

• SYN-234: Custom types can anchor project_graph (9f56631)

• SYN-234: Cover custom types in stale, doctor and HTML export (a19d4d5)

• SYN-234: Kill the EntityType::Note fallback in row_to_entity (395a442)

• SYN-234: Allow custom-typed entities as link endpoints (3abf8d3)

• SYN-234: Reach custom types from MCP reads (contract phase) (bd35deb)

• store: Make entity removal atomic with the index DELETE (a462df1)

• hooks: Word-boundary pt matching to avoid English collisions (e665f60)

📝 Documentation

• SYN-223: Mark v0.9 complete in project state (eb424cf)

• handoff: Self-contained next-session prompt + v0.9.0/v0.10 state (2e282e6)

• roadmap: V0.9.0 release cut + v0.10 phase + research positioning (7bd066e)

• research: Comparative agent-memory field study + roadmap input (f123bd5)

• handoff: Record (1)(2)(3) completion + SYN-227 reindex finding (89b0c85)

• handoff: Record consolidation pass + remaining contract gaps (c5d6824)

• roadmap: Apply the v0.9 cut list and define minimum v1.0 (c9792c2)

• brand: Reposition the headline from the gate to the proof (e57398c)

• commands: Document the v0.9 surface and add doc-gates (73ee1fa)

• handoff: Record SYN-234 (full) + SYN-226; map remaining blockers (f1e3f19)

• SYN-234: Resolve ADR-028 EAV-vs-generated-columns spike (e79d01b)

• handoff: V0.9 session handoff: state + remaining order (7bffaa7)

• claude: Record v0.9 progress (10 work-items shipped) (b63484b)

• claude: Record v0.9 progress (8 shipped; schema chain deferred) (05e2577)

• claude: Record v0.9 progress (SYN-239 done, SYN-249 wip) (f649e67)

• adr: Accept ADR-026..030 (v0.9 governance foundation) (10f4d00)

• adr: Revise ADR-026 two-tier + add ADR-030 git-native signed audit (0c719ef)

• adr: Add ADR-026..029 for v0.9 governance foundation (53c45f1)

• roadmap: Re-anchor v0.9 to temporal governance & adoption (35ebf00)

• changelog: Release v0.8.0 (9590bb5)

🧹 Chores

• release: V0.9.0 (b83f611)

[0.8.0]: 2026-06-11

♻️ Refactoring

• core: Split pending tests into submodule (ADR-015) (c1e9633)

✨ Features

• SYN-222: Syn digest: weekly activity + attention prompt (9c56ff9)

• SYN-221: Frictionless syn capture one-liner (inline text) (f081456)

• SYN-220: Ambient git capture via syn capture –from-git (ADR-025) (0dcb04c)

• SYN-185: Batch approval over syn pending (ADR-024) (7ec12fc)

📝 Documentation

• release: Align README and CLAUDE for v0.8.0 (6196d76)

• SYN-229: Reposition brand around governed memory (9bd4ffd)

• release: Align README/MCP/SKILL/CLAUDE with v0.7.0 (a02c5e2)

• changelog: Release v0.7.0 (98c576c)

🧹 Chores

• release: V0.8.0 (0b9a451)

• hooks: Block Portuguese in commits and gh issue/pr commands (cb34328)

[0.7.0]: 2026-06-08

♻️ Refactoring

• mcp: Replay_proposal client-driven, no sampling (SYN-219) (bc9eea3)

• core: Split pending apply paths into apply submodule (ADR-015) (fd8c8af)

✨ Features

• SYN-183: Read-only query tool, structured aggregation (ADR-023) (51161d3)

• SYN-218: Confidence-tiered write policy (ADR-022) (7310ac2)

• SYN-217: Incremental reindex via dirty-tracking ledger (facab8a)

• SYN-237: Onboarding fp32/int8 embedding choice + dense int8 BGE-M3 (4bc9496)

• core: Atomic propose_batch + crash-safe accept (SYN-202, SYN-216) (5ac4e57)

🐛 Bug Fixes

• models: Reconcile model-size figures to measured truth (SYN-214) (6bed78c)

📝 Documentation

• roadmap: Restructure v0.7-v0.9 + commercial from strategic audit (d2da947)

• adr: Accept ADR-022: confidence-tiered write policy (BR-12.3) (e02c2f8)

• roadmap: Reprioritise v0.7; defer async + Intel macOS to v2.0 (f901d63)

• changelog: Release v0.6.0 (9786f2c)

🤖 CI

• workflows: Disable push-on-main trigger (PR + manual only) (84f506a)

🧹 Chores

• release: V0.7.0 (2f6a4c0)

• deny: Ignore RUSTSEC-2026-0173 (proc-macro-error2 unmaintained) (d1926a3)

[0.6.0]: 2026-06-07

✨ Features

• SYN-200: Branded model-download experience (7f622df)

• SYN-197: Animated mascot reveal on onboarding (ac906c3)

• SYN-199: Charming empty + healthy states (157f0b1)

• SYN-198: Brand banner on bare syn and –version (370824f)

• SYN-196: Brand module: graph-constellation mascot + wordmark (d5e9d19)

• SYN-201: OutputSchema on MCP read tools (5e4275e)

• SYN-184: Syn plugin install: scaffold the Claude Code plugin (e0b350b)

• SYN-175: Syn skill install / syn agents init: emit agent assets (2f2065f)

• SYN-182: Propose_batch: one accept for many proposals (a9bf156)

• SYN-181: Get_entities batch read with field projection (5b7cc2c)

• SYN-180: Recent_changes delta mcp tool over the audit trail (75b765c)

• SYN-179: Workspace_overview digest mcp tool (0a8ba20)

• SYN-178: Resource_link on search hits and get_entity (b574b3b)

• SYN-177: StructuredContent + compact json on all mcp reads (5ebd869)

• SYN-192: Branded progress animation + federation spinner (e10e731)

• SYN-191: Tty progress for embed –all, reindex and watch (edad154)

• SYN-193: Unicode graph tree, show panels, clean search snippets (52d7515)

• SYN-190: Unicode tables for list/info/doctor on a rich TTY (a775fa0)

• SYN-171: Capture self-identity globally and seed self person (7b3ea91)

• SYN-188: Writes emit structured JSON under –format json (292c4c9)

• SYN-188: Machine-readable JSON errors with branchable kind (8658dea)

• SYN-176: Bound list_by_type MCP read (limit + cursor) (7f47f66)

• SYN-186: Styled output + –plain/–no-input/–quiet (ADR-019) (cde313f)

🐛 Bug Fixes

• mcp: Refresh tool descriptions + build router once (eea23bd)

• SYN-213: Rich rendering for federated_search hits (f44fe7e)

• SYN-211: Don’t clobber a same-slug non-self person on seed (f4cb7fe)

• SYN-210: Make the “no self person” error actionable (2872522)

• SYN-209: Validate a real calendar birthdate (95b8497)

• SYN-207: Validate per-leaf payload in propose_batch (d4dd7fd)

• SYN-205: Consume birthdate in cv; correct the schema doc comment (8b02e7c)

• SYN-206: Materialise self->org graph edge from affiliations (8d7e920)

• SYN-204: Honour –format json on list/show/tag/pending/ws/at-show (2dd0fb1)

• SYN-203: Uniform {result, freshness?} envelope on every read (0139f59)

📝 Documentation

• release: Bring readme + docs up to date for v0.6 (b18f914)

• SYN-202: Register atomic propose_batch follow-up in v0.7 roadmap (29b1004)

• SYN-196: Register brand & delight cluster in roadmap (e377bde)

• adr: Adopt anstream/anstyle terminal styling (ADR-019); v0.7 split (141efef)

• roadmap: Rendering opt-out contract (SYN-195) (4619cb1)

• roadmap: Plan premium cli output (SYN-192..193) (d474b09)

• roadmap: Plan cli ux & agent-friendliness (SYN-186..191) (5c26d48)

• roadmap: Number syn agent as SYN-185 (carry-over) (0010cd7)

• roadmap: Plan mcp agent-ergonomics tickets (SYN-176..184) (ea6df57)

• mcp: Correct tool count + federated/get_entity shapes vs code (69e1152)

• roadmap: Plan syn skill install for v0.6 (SYN-175) (56788a2)

• readme: V0.5.0 released; Next is v0.6 (f162e87)

• changelog: Release v0.5.0 (b2ba0ad)

🧹 Chores

• release: V0.6.0 (de901fc)

[0.5.0]: 2026-06-05

♻️ Refactoring

• SYN-153: Split cli/audit.rs (611 lines) into cli/audit/* (e4ba676)

• SYN-152: Split cli/at.rs (620 lines) into cli/at/* (3f087e7)

• SYN-151: Mcp/server.rs to dispatcher pattern (cf5d1b1)

✨ Features

• SYN-168: Opt-out semantic layer + consent-gated model download (8435ca0)

• SYN-93b: Workspace freshness Phase 2: network ls-refs via gix (3c932e7)

• SYN-165: Opt-in OpenAI + Voyage network embedding backends (ce188ad)

• SYN-166: Syn search –grade captures relevance labels (a9ee65c)

• SYN-88: Mirror search modes in the MCP search_knowledge tool (0cf3254)

• SYN-162: Synapse-bench harness + relink_all + ship-gate report (61426bc)

• SYN-86: Hybrid RRF search + –semantic/–no-vector modes (SYN-87) (95e0eb2)

• SYN-161: Heuristic linker + ner-span resolver (1bcf29b)

• SYN-160: Insertion-time enrichment pipeline run_on_write (BR-13) (9321e40)

• SYN-85: Syn embed –all|<slug>|–check|–reset-cache (bedeac6)

• SYN-164: Gliner ner backend via kreuzberg-gliner-rs (rc.12 fork) (e369e68)

• SYN-83: Fastembed-rs production embedding backend (BGE-M3 default) (8d5ade5)

• config: Enrichment block + model cache dir resolver (0412cca)

• SYN-84: Deterministic embedding + ner stubs (test_backend feature) (8494dfe)

• SYN-82: Embedding + ner backend traits (semantic contracts) (596db14)

• SYN-81: Wire sqlite-vec via auto_extension; entities_vec table (7fbd3b5)

• SYN-80: Vector cargo feature + migrations_vec/ scaffolding (557b92b)

🐛 Bug Fixes

• SYN-168: Align clippy.toml msrv with Cargo.toml (1.89) (97b7552)

• SYN-168: De-risk v0.5 release: native linux builds + MSRV 1.89 (f7af50e)

• SYN-86: Sanitise hybrid FTS query to OR-of-quoted-terms (05ddb08)

• core: Unbroken rustdoc links in embeddings::factory (ffd26be)

💄 Style

• SYN-168: Rustfmt readiness.rs (one-line is_some_and) (7c23a1c)

• index: Cargo fmt after SYN-80 split (36bf8d9)

• mcp: Cargo fmt fixups after SYN-151 (ff127b9)

📝 Documentation

• install: Mark Intel macOS unsupported + track SYN-174 (f37fd48)

• changelog: Release v0.5.0 (151aa15)

• onboarding: Add ONBOARDING.md as the linear first-run guide (bed5445)

• roadmap: Plan v0.6 mandatory setup + identity onboarding (0989df5)

• changelog: Release v0.5.0 (8a500ee)

• SYN-168: Onboarding-first first-run + tutorial deep-dive (f1632e9)

• changelog: Release v0.5.0 (2b5a60d)

• SYN-168: Add MODELS.md: the semantic models reference (953aa58)

• SYN-168: Fix stale MCP tool count + round out the TUTORIAL (9ee6c82)

• readme: Restructure §Status as a table + per-version bullets (dd20ef1)

• semantic: Document the v0.5 semantic layer across user-facing docs (7c27552)

• README: Mark v0.5 feature-complete (f2c9489)

• README: V0.5 core complete: bench harness landed (4ff3731)

• SYN-167: Editor-integration section promoting syn lsp (717dfcc)

• README: Syn-164 landed via kreuzberg-gliner-rs fork (6fdd900)

• README: Refresh §Status for v0.5 semantic layer in progress (46537ab)

• SYN-152: Drop intra-doc links into private submodules (03887dd)

• SYN-151: Drop intra-doc links into private items (0f23350)

• adr: Stress-test ADR-008 against lancedb / surrealdb / vectorlite (05cc0dd)

• SYN-89: Adr-008: embedding backend, vector storage, ner backend (640116e)

• SYN-160: Close v0.5 brief; BR-13 codified; ROADMAP refreshed (c72700d)

• researchs: Lock v0.5 brief decisions: bge-m3 + gliner core (c030706)

• researchs: V0.4 closure read + v0.5 semantic layer brief (2ca6a37)

• readme: Refresh status with v0.3 + v0.4 + lsp visibility (b37a418)

• changelog: Release v0.4.0 (1777684)

🤖 CI

• release: Drop x86_64-apple-darwin (no ort Intel-macOS prebuilt) (3449db5)

• release: X86_64-apple-darwin on macos-15-intel (macos-13 retired) (f32d2c2)

• SYN-168: Build macOS x86_64 natively on macos-13 (92ad0f1)

• SYN-154: File-size lint enforcing ADR-015 red/yellow tiers (9f37a95)

🧹 Chores

• release: V0.5.0 (a39b4be)

[0.4.0]: 2026-05-27

✨ Features

• SYN-142: Full as-of fts index reconstruction via in-memory sandbox (d6613a3)

• SYN-140: Tag-level federation redaction via Redactable trait (8c5d0d1)

• SYN-139: Mcp resources/list cursor pagination (c06ea5f)

• SYN-143: Syn ws clone <git-url> (915e778)

• SYN-146: Syn doctor –lint-provenance (4334abe)

• SYN-137: X-ai-history chain on entity re-mutations (a59d834)

• SYN-130: Syn lsp companion via tower-lsp-server (ADR-018) (0db9e16)

• audit: Replay –execute + replay_proposal MCP tool (SYN-136) (ad12dee)

• at: List, info, graph subcommands as of ref (SYN-141) (d176071)

• mcp: Real Tasks progress + cancellation (SYN-138) (b59a318)

• audit: Syn audit verify: re-hash payload vs sha256 (SYN-135) (6a4ae48)

• cv: Syn cv export: deterministic Markdown CV (SYN-133) (909c4aa)

• identity: Syn experience + skills auto-derive (SYN-132) (e13c2b3)

• identity: Ed25519 signing, keygen, revocation (SYN-131) (ba3b103)

• mcp: Split server.rs into focused submodules (SYN-150) (ef6a125)

💄 Style

• at: Trim trailing blank line (cargo fmt) (d8adf2c)

📝 Documentation

• roadmap: Close v0.4 hygiene gaps before release (1110fdd)

• SYN-140: Fix rustdoc intra-doc links (81dcb6d)

• SYN-147: Adr-016, adr-017, identity user-facing doc (dce5bef)

• researchs: V0.4 brief: refinement & extensibility (7a5346b)

• changelog: Release v0.3.0 (76e3464)

🧹 Chores

• release: V0.4.0 (ff4c2eb)

[0.3.0]: 2026-05-25

✨ Features

• identity: Me.synapse portable bundle prototype (SYN-125) (8da8165)

• audit: Syn audit replay <id> (SYN-113, v0.3 scope) (2d6d3e4)

• cli: Syn capture: zero-friction stdin → pending (SYN-124) (bd9ddda)

• audit: Syn audit stale –over WINDOW cross-workspace (SYN-123) (f796a96)

• cli: Syn at <ref> – search|show subset (SYN-122) (17129d9)

• cli: Syn timeline <slug> walks entity history (SYN-121) (3a3acc4)

• mcp: Mcp_tasks feature placeholder (SYN-118) (0656170)

• mcp: Three named prompts (SYN-116) (8289f37)

• mcp: Resources surface (SYN-115) (88f47d7)

• cli: Syn audit show|list|prune (SYN-112) (3f136ec)

• provenance: X-ai-* frontmatter stamps on accept (SYN-111) (ec4de9c)

• federation: Capability disclosure server-card (SYN-117) (9d847f8)

• pending: Context_snapshot column for replay (SYN-114) (6bebd42)

• audit: Append-only audit trail (SYN-110) (8789e1e)

🐛 Bug Fixes

• ci: Apply cargo fmt + enforce in pre-push hook (38810e4)

• ci: Mirror trigger uses workflow_run.head_branch, not the api (3bac81d)

📝 Documentation

• adr: Adr-015 file-size threshold + modular split policy (69d52bb)

• adr: Adr-012/013/014 + audit and provenance user docs (244cc2f)

• roadmap: V0.3 milestone opened, 18 issues filed (not 17) (3b01c74)

• researchs: V0.3 brief locked + roadmap fase v0.3/v0.4 (f55a63c)

• researchs: New folder + v0.3 multi-context brief (5ec2433)

• changelog: Release v0.2.0 (f7090f9)

🧹 Chores

• release: V0.3.0 (138e4d0)

[0.2.0]: 2026-05-25

✨ Features

• index: Last_modified_commit per entity (SYN-68) (66ec591)

• cli: Completions + man pages (SYN-63 + SYN-64) (f466534)

• cli: Watch + export + open + config + uninstall + rm guard (fcf0590)

• mcp: Pending queue and 5 write proposal tools (SYN-60..62, SYN-92) (f58650c)

• freshness: Workspace drift advisory (SYN-93 Phase 1) (8dab4e4)

• mcp: Federation read tools (SYN-78 + SYN-92 read slice) (cf3fcfa)

• core: Federation helper and –all reads (SYN-77 + SYN-79) (c1015d5)

• cli: Syn ws registry and manifest curation (4f556d7)

• registry: Workspace registry + SYNAPSE.md manifest (f2a35a8)

📝 Documentation

• audit: Align every doc with the v0.2 surface that shipped (3fca048)

• tutorial: Walk-through + recipes (SYN-72 + SYN-73) (92d764a)

• adr: Adr-011 workspace freshness + br-12.5 (edcc39c)

• adr: Extend adr-010 with workspace identity card (7abf0cb)

• adr: Adr-010 workspace federation and v0.2 issues (6cdbc59)

• brand: Horizontal wordmark hero + source-code disclaimer (7a76170)

• brand: Full mascot gallery and per-doc placement (3b5e723)

• brand: Mascot, slimmer README, docs/ split (b303990)

• changelog: Release v0.1.0 (4c1c54f)

🤖 CI

• mirror: Publish private releases to synapse-releases (public) (0d9c047)

🧹 Chores

• release: V0.2.0 (e91761e)

• fmt: Cargo fmt sweep after federation work (54b651d)

[0.1.0]: 2026-05-24

♻️ Refactoring

• core: Fluent args, BSD exit codes and output helpers (ef36fca)

✅ Testing

• workspace: Sqlite-failure rollback restores filesystem (SYN-53) (0e7892d)

• slug: Five proptest invariants (SYN-52) (68f9ee6)

• cli: End-to-end fixtures and insta snapshots (SYN-50/51) (7e00fd3)

✨ Features

• info: Stable JSON output and totals (SYN-29) (ff6bc68)

• i18n: Fluent loader plus pt-BR and en coverage (c25182c)

• cli: Tasks with sequential IDs and done marker (SYN-21) (3cd7f75)

• mcp: Stdio server with four read tools (SYN-39/40/41/42/43/44) (394a8f3)

• config: Cascade config, setup and init polish (SYN-30/31/32) (cf33c3d)

• cli: Tag ops and graph queries (SYN-23/26/27) (a15a7c2)

• cli: Note type, FTS5 search and workspace doctor (SYN-22/24/25/28) (44d61dc)

• cli: Wire AppDeps, dispatch trait and CRUD (SYN-1/4/11/15..20) (d87da7c)

• store: Atomic tx and index DDL (SYN-3/6/7/8/9/10) (422a7f4)

• SYN-5: Slug primitives, EntityType enum and typed Frontmatter (bb603ec)

🐛 Bug Fixes

• release: Commit_preprocessors must be a sequence, not a map (7e50089)

• deny: Patch RUSTSEC-2026-0009 (time) and ignore 0140 (build-only) (3f1eab1)

• docs: Use absolute intra-doc links for Commands and find (62eca10)

📝 Documentation

• api: Re-enable warn(missing_docs) on the crate (SYN-49) (9bf0f37)

• readme: Tighten identity, add SAYS backronym as in-joke (f4067cc)

• repo: Move design notes to docs/design and drop issues.py (32a712a)

• business: Add normative BUSINESS_RULES.md (BR-1..BR-12) (b7998a1)

• roadmap: Document ID gap policy and add issues generator (19aad29)

• roadmap: Add detailed ROADMAP covering v0.1 to v1.0 (4960a17)

• adr: Record MSRV policy and release pipeline (006, 007) (3522c9d)

📦 Build

• release: Wire git-cliff, release workflow and seed CHANGELOG (3986ce8)

🤖 CI

• workflow: Paths filter, cancel-in-progress, slimmer matrix (2f6daf3)

🧹 Chores

• cli: Remove leftover .tmp files from doc-script (599b265)

• deps: Bump MSRV to 1.88 (ADR-009 supersedes ADR-006) (d5e224e)

• SYN-0: Bootstrap synapse repository scaffold (2cc63a7)

Synapse: Brand notes

Source of truth for the Synapse identity. If you are editing the README, docs, or any external surface, pull from here.

Mascot: Lil Syn

A round indigo character with cream eyes, designed by Claude Design. Lil Syn is the personality of the brand; the wordmark is the identity. They show up together in headers, never overlap.

Mascot resolution (SYN-215)

The brand has two marks; this is the settled relationship between them (decision 2026-06-21):

• Lil Syn is the primary, warm mascot: the character that fronts the README, docs headers, install/celebration moments, and anything human-facing. It carries the personality.
• The graph constellation is the secondary, technical mark: used where an abstract, system-level glyph fits better than a character: the favicon, social/OG card, CI badges, and diagram motifs. It is not a rival mascot; it is the technical face of the same identity.

They never compete in the same slot: human-facing → Lil Syn; technical/glyph slot → constellation. When in doubt, use Lil Syn.

The full cast

Files

assets/branding/
├── BRAND.md
├── lil-syn-classic.svg     /  .png (@2x)
├── lil-syn-stack.svg       /  .png (@2x)
├── lil-syn-firing.svg      /  .png (@2x)
├── lil-syn-thinking.svg    /  .png (@2x)
├── lil-syn-hearts.svg      /  .png (@2x)
├── lil-syn-sleepy.svg      /  .png (@2x)
└── lil-syn-confused.svg    /  .png (@2x)

All SVGs are flat (no filters), single-fill-per-shape, optimised to roughly 4–5 KB. PNGs are 2048×2048 for clients that don’t render SVG inline (GitHub markdown does: prefer SVG).

Colour palette

The primary three carry the whole brand. The extended set appears only in the variants that need it: never invented elsewhere.

Primary

Extended (variant-specific)

Greys derive from cream: #1A1A1A near-black for body text, #E7E2D6 for hairlines, #888880 for muted captions.

Typography

• Display / wordmark: Sora: geometric sans, for Synapse, h1/h2 in marketing surfaces.
• Body: system stack (-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif) for docs/READMEs that render on GitHub.
• Code / terminals: JetBrains Mono for CLI screenshots and marketing inline code.

Voice

The product is the connection between your projects. The mascot is the smaller, curious side: it cheers when things work, looks puzzled when something is missing, dozes when nothing’s happening.

Voice should match the variant on screen:

• Indigo, factual, unfancy as the default.
• A flash of cheer next to firing for a shipped milestone. Name a version or count only when verified for that release.
• A hint of warmth next to hearts (“built with care”).
• Direct apology next to confused (“error: entity ‘foo’ not found: try syn project list”).
• Never corporate. Never marketing-speak.
• Lead with governed operational memory in the README hero, installation and MCP onboarding. Explain proposals, review, supported reversal and explicit verification scope. The neuron metaphor explains continuity; concrete evidence explains value. Write policies can permit safe application, so do not claim that an agent never writes or that every change always receives human review (ADR-022).

Canonical product statement

Operational memory for agents, with governed changes, preserved history, and explicit integrity checks.

Use this statement in README, public docs and integration material. Short captions can name a specific task, such as “Carry reviewed knowledge into the next task”, but must not enlarge the assurance claim. Keep supporting copy in English and do not use em dashes.

Claims and product status

• Lead with continuity of work, reviewable changes and the evidence available to inspect.
• Name the selected verification scope. A pass over stored bytes does not prove that all claims are true or that all natural-language contradictions have been detected.
• Keep source-tree capabilities distinct from the last packaged release. A current source MCP count or new process contract is not automatically available in an older binary.
• Identify planned integrations near their diagram. A host boundary does not make every client, shared workflow or authoring-tool connector available.
• A signed receipt is evidence over exact bytes. Identity, current organizational permission and independently retained witnessing require their own selected inputs.
• Do not use absolute slogans such as “the memory your agents cannot silently corrupt” or an unqualified promise that every fact is provable. Keep historical wording in its original dated evidence when needed, rather than promoting it as current positioning.

Visual documentation

Use the product’s indigo, paper and amber palette with a restrained grid, generous spacing and readable labels. Lil Syn remains the human-facing identity; diagrams explain concrete responsibilities, data movement and trust boundaries rather than adding decorative networks.

The overview kit holds editable static SVGs for the governed lifecycle, core topology, tool integrations and recorded retrieval evidence. Pair every figure with searchable English text and meaningful alt text. Preserve raw benchmark data and its limits. Do not invent comparison baselines or imply a model assessment grants authority.

Where each variant currently lives

When in doubt, classic.

Synapse: auditability of AI writes

For compliance reviewers: Synapse never writes from MCP without a human-accepted proposal (BR-12.3). Every accept, reject and prune appends one JSON line to .synapse/audit.ndjson (ADR-013) before the workspace mutation. Accepted entities also carry per-file provenance frontmatter (x-ai-*, ADR-012). The trail and the stamps are independent and you can read either one without running Synapse.

1. The two layers

Synapse’s audit story has two layers, each answering a different question:

The trail is the regulator’s receipt. The frontmatter is the file’s self-description.

See also PROVABILITY.md: the audit trail this document describes is one of the integrity classes syn verify turns into a signed, reproducible proof. Where this page answers “can I read what happened?”, that one answers “can I prove the memory wasn’t silently corrupted?”: including the honest tamper-evident-not-tamper-proof ceiling.

2. The audit trail

Every decision the pending queue makes: accept, reject, prune, appends one JSON line:

{
  "id": 7,
  "kind": "capture_fact",
  "decision": "accepted",
  "proposed_at": "2026-05-25T15:00:00Z",
  "decided_at": "2026-05-25T15:30:00Z",
  "source": "mcp:capture_fact",
  "reason": "user-supplied justification",
  "payload_sha256": "sha256:f8e2c1…"
}

• id matches syn pending show and survives the row’s deletion.
• decision is accepted | rejected | pruned.
• payload_sha256 ties the trail entry to the original proposal payload. The payload itself lives on the queue row until the user prunes it: the hash forever links the two.

Read the trail

syn audit list                              # live tail (last 100, newest first)
syn audit list --all                        # include archive months
syn audit list --decision accepted          # filter by decision
syn audit list --source mcp:                # filter by source prefix
syn audit show 7                            # one entry
syn audit list --format json | jq           # the canonical interchange

For a human-friendly replay of one decision against the current workspace state:

syn audit replay 7                          # surface payload + context snapshot
                                            # + current entity state diff

In v0.3 syn audit replay does not re-run the original prompt against a model: it surfaces enough to spot drift visually. The v0.4 follow-up will optionally route through the configured MCP client to re-run the prompt and diff the output.

Retention and pruning

Default retention is 90 days. After that, on the next append, rotation moves stale entries into .synapse/audit-archive/<yyyy-mm>.ndjson and rewrites the live tail. The archive is never auto-deleted.

syn audit prune --before 2025-01            # remove archive months only
                                            # live tail untouched

Tune retention in ~/.config/synapse/config.toml (or the workspace config):

[audit]
retention_days = 90        # default; set to a smaller number to roll faster

What the trail never does

• It does not auto-delete anything. syn audit prune is the only path to physical removal, and it only touches the archive.
• It does not drop unparseable lines on rotation, a corrupted line stays as a forensic artifact, not as a silent deletion.
• It does not lie. If the audit append fails after a successful workspace mutation, the queue row stays pending so the reviewer can see “this needs to retry”; the trail is never written past what actually happened. See ADR-013 for the ordering rationale.

3. The propose / sanction loop

MCP write tool                pending queue              workspace
─────────────────             ───────────────             ─────────
capture_fact          ─►      enqueue (id=N)
link_entity                                     ◄── syn pending list
update_status                                   ◄── syn pending show N
add_workspace_topic                             ◄── syn pending accept N
add_workspace_tag             apply ────────────►  Workspace::tx
                              audit-append (accepted, id=N)
                              mark accepted

This is BR-12.3 in one paragraph: MCP never writes directly. Every write tool returns {pending_id, accept_command, reject_command, kind, summary} and the resulting entity lands on disk only when the human runs syn pending accept.

4. EU AI Act Article 50 mapping

Article 50 enforcement begins 2026-08-02. Mapping the obligations to Synapse:

The inline = false config flag is the escape hatch for users who need clean entity files but still want the regulatory receipt, the audit trail keeps the same metadata regardless.

5. References

• BUSINESS_RULES.md §12: BR-12.3 through BR-12.5, the normative rules this doc operationalises.
• ADR-012: frontmatter stamps.
• ADR-013: audit.ndjson format and rotation.
• ADR-014: portable identity bundle (separate but related: provenance + identity are the two human-owned signatures Synapse ships).
• MCP.md: the MCP write tools and the response shape every accept-command piggybacks on.
• PROVENANCE.md: companion document focused on the per-file frontmatter stamps.

Benchmarks

Synapse is benchmarked along two axes that matter to a real user: does it scale to my project and machine? and does the governed-memory story actually hold when a real AI agent drives it? The first is deterministic and offline; the second drives a live agent (Claude Code) over MCP and grades the resulting state, not the transcript.

• Methodology contract (scaling): ADR-040
  • the scaling research note.
• Agent-in-the-loop design + driver decision: ADR-041, plan 022, and the findings notes (methodology · first results).
• All numbers are owner-run, not CI (agent runs cost tokens + are non-deterministic; ADR-041). The harness lives in synapse-bench/.

1. Scaling: latency & index size vs corpus size

Will it handle your project, and where does it break? The honest answer is a curve over corpus size, not a single number.

The shape is the point: FTS-only (BM25) stays nearly flat: it tracks the result set, not the corpus: while vector-flat climbs with N (a brute-force cosine scan over every embedding, O(N·d); the line that eventually breaks), and hybrid (RRF) tracks both. The index grows linearly on disk:

(These two are the stub backend at large N, the latency/size mechanics are real; the vectors aren’t semantic, so these charts are about scaling shape, not quality.)

2. Resources: will it fit on my machine?

With the real backend (BGE-M3 on-device), the answer is floor + slope: the model is the ~1.8 GB floor, your data adds to it gently.

The binding constraint is the model, not your notes, a 16 GB machine fits far more than a single user will ever write. Embedding runs at ~13 docs/s on this CPU (a one-time ingest cost); reindex of the index structure stays in the tens of ms.

3. Retrieval correctness at scale

“Fast” is worthless if the right fact stops ranking. The honest correctness signal comes from realistic data: 6 fictional professionals’ full quarters (persona fixtures, ~460 entities, 320 cross-referenced notes) + a 120-question needle bank (persona-bench, SYN-296). We fix one professional’s 20 facts and watch recall as the other five careers pile into the same brain:

The raw observations contain six measured points. At 77 entities, 19 of 20 target facts appear in the first ten results; at the five larger measured sizes, all 20 do. First-result recall ranges from 75 to 90 percent and ends at 85 percent for 463 entities. This internal synthetic fixture does not establish quality, capacity or robustness for other workloads. The original run’s source commit is unknown.

The historical illustration in brand/images/retrieval-quality.png now derives from this same canonical chart. Its previous hand-positioned curve did not match the recorded values. No new benchmark or matched competitor comparison is claimed here.

recall@1 improved from 0.75 to 0.85 (SYN-301 / ADR-042). The measured weakness at the top of the list was that an entity was embedded as a single whole-entity vector, so a fact buried in a long note was averaged away. Embedding at passage granularity (a deterministic Markdown chunker, one vector per chunk pooled back to its parent by best distance) lifted full-haystack recall@1 from 0.75 to 0.85 with no recall@10 regression (recall@10 is 0.95 at the first measured point and 1.0 at the other five). An opt-in cross-encoder reranker ([enrichment] rerank, ADR-042 Track B) is also available; on this corpus chunking already captured the recall@1 gain and the reranker was neutral at scale, so it ships off by default: useful to try on longer-document workloads, not a headline win here. Raw data: persona-recall · stub · real.

Reproduce (the model is cached & reused; clean-models reclaims the GBs):

cd synapse-bench
cargo run --release -- sweep --tiers 500,2000,8000 --reps 5 --out ../docs/assets/bench
cargo run --release --no-default-features --features real -- sweep --tiers 200,800,2000 --out /tmp/r
cargo run --release --no-default-features --features real -- persona-bench --out /tmp/p
cargo run --release -- clean-models

4. Agent-in-the-loop: does governed memory hold under a real agent?

The distinctive benchmark: drive a real agent (Claude Code, headless) through the full governed-memory loop over MCP (insert / correct / contradict / retrieve) and grade the resulting memory state via syn verify’s canonical dump (the τ-bench get_data_hash() analog), not the transcript. The agent is isolated to the MCP tools (a system prompt + --disallowedTools block file/shell/web access) so the benchmark measures MCP-driven memory, not the agent reading project files. Because the CLI gives no seed control, every task runs N times and reports pass@1 (capability) with a 95% Wilson CI, pass^k (reliability = every run passes its assertions), and cost.

Run it (owner-run; needs claude + credentials; see the harness README):

cd synapse-bench
cargo run --release -- drive --task fixtures/tasks/insert-01.json --runs 15 --syn-bin "$(command -v syn)" --out /tmp/insert.json
cargo run --release -- gate-probe --seed seeds/aurora --payload fixtures/gate-probes/aurora-archived.json --out /tmp/gate.json
cargo run --release -- qa --needles fixtures/needles/ana-yamamoto.json --persona fixtures/personas/ana-yamamoto --limit 10 --judge-model claude-sonnet-4-6 --syn-bin "$(command -v syn)" --out /tmp/qa.json

Results (Claude Code 2.1.197; judge = Sonnet over an Opus agent)

Two findings that shape the positioning:

1. Contradiction defence is two independent layers. A capable agent surfaces a contradiction in its own reasoning and asks the human before ever filing the write, so the agent-in-the-loop path shows non-corruption, and the gate (SYN-242) is the non-bypassable floor for when the agent doesn’t notice (a weaker/autonomous agent, a subtle conflict, too much data). gate-probe measures that floor directly: it detects and gates a conflicting update_status, 100%, with a hard-negative control.

2. Scenario D separates retrieval from generation, and the agent beats single-shot retrieval. Each needle is answered three ways over a persona haystack: retrieval (gold in syn search top-k), oracle (gold injected, the generation ceiling), and end-to-end (agent via MCP), with a reference-guided judge on a different model. On a 10-needle run: recall@10 = 80% but e2e = 100% (oracle ceiling 100%). The gap is the finding: the two needles the top-10 retrieval missed were still answered correctly end-to-end, because the agent issues multiple MCP searches and reasons across related notes. So the MCP-driven loop recovers retrieval gaps a single ranked query would drop; the oracle−e2e gap (here zero) isolates genuine read failures when they occur.

Under noise, retrieval holds. Piling synthetic distractors into the haystack (qa --distractors N; the agent’s token cost is ~flat in N because it searches via MCP, so only the one-time embed scales) leaves the answer intact:

¹ the lone e2e dip is a 5-needle-sample claude -p blip, not degradation. Recall@10 and the oracle ceiling stay at 100% through 8 000 distractors, the retrieval cliff the flat-vector scaling curve predicts lives at far larger N (tens of thousands+), not the low thousands a real second brain holds. The 100 000 tier is a ~2 h one-time embed (documented, not run).

Reliability, not just capability, is the headline for a “can’t silently corrupt” tool: the recurring ~1/N miss in these runs is a transient claude -p crash (now retried), not Synapse: the governance behaviours (update-on-existing, abstention, non-corruption, gate detect-and-gate) are effectively clean.

Honest limits. Judge and agent are both Claude (a weaker preference-leakage guard than a cross-family judge): audit judge–human agreement before trusting the e2e number; the raw verdicts are kept for that. The distractor-scale sweep (1k/10k/100k) and the bitemporal --as-of correction assertion are the next slices (plan 022).

The Synapse benchmark, explained for non-experts

This is the plain-language companion to BENCHMARKS.md. It explains what the metrics mean, how the recorded tests ran, which results they support and where their evidence is limited. The observations are owner-run engineering experiments, not a human field study or a promise about every workload, agent or released executable.

The question it tries to answer

Imagine an assistant maintaining a team’s notebook: API owners, decisions, constraints and open tasks. A useful benchmark needs to check whether the assistant preserves the expected recorded state, whether supported conflicting changes receive the intended review and whether later questions retrieve the right evidence.

The question is: under the recorded scenarios, what changed, what remained intact and what did the checks actually cover? Storage integrity, supported structured conflicts and factual truth are different questions. A result about one does not establish the others.

There are two test families:

1. Scaling, with deterministic offline measurements of latency, size and resources.
2. Agent in the loop, where a real agent uses MCP and the harness grades the resulting state or answer. These runs require the selected provider and are not offline tests.

The current source overview adds a plot of the stored persona retrieval observations. Its 20-question fixture is separate from the 10-question agent Q&A scenario below. Do not merge their sample sizes or present one as a rerun of the other.

Glossary, in human terms

Distractors. Irrelevant records deliberately added to make retrieval harder. Finding the same target facts among 2,000 or 8,000 additional records tests those particular noise fixtures. It does not reproduce every kind of accumulated organizational knowledge.

Recall@10. The fraction of target facts found within the first ten ranked results. recall@1 asks whether the fact ranks first. A hit measures retrieval against the recorded reference; it does not certify that the reference or generated answer is true.

Noise chart. A plot of retrieval results as distractors increase. In the recorded agent Q&A noise probes, top-ten recall was 80% without distractors and 100% at the two measured noise levels, +2,000 and +8,000. That is a small set of observations, not a flat curve proven at every corpus size. The separate persona fixture starts at 95% top-ten recall and reaches 100% at its larger measured corpus sizes.

Saturation. A metric reaches 100% on its tested sample. This can indicate a successful scenario or a test too small/easy to discriminate. “10 of 10 runs” makes the sample visible; it is not a general guarantee.

Gate. The deterministic proposal guard for supported structured changes, such as certain status or relationship conflicts and identity collisions. It does not require a model to notice those supported cases. General disagreements in prose are outside that detector’s scope, and unsupported proposal classes must not be counted as semantically consistent. See ADR-062.

e2e (end-to-end). The agent receives a question, uses only the allowed MCP tools and produces an answer. This checks the complete tested agent/tool loop rather than one search. It remains an engineered scenario with a selected model, fixture and grading method.

The three attribution legs. Each question is examined in three ways:

• Retrieval: is the reference fact present in the raw top-k results?
• Oracle: can the model answer when given the reference evidence directly?
• e2e: can the agent find and use evidence through MCP without that direct injection?

Differences help investigate failures. A high oracle score with a lower e2e score suggests problems in the retrieval/reasoning/tool loop. It does not identify one cause conclusively without inspecting the run.

pass@1 vs pass^k. The harness reports single-attempt success frequency as pass@1. Its pass^k field records whether every graded run passed its assertions. In this harness it is an all-runs result, not a separately estimated population success probability. Neither a lucky success nor a small all-pass sample proves future reliability.

95% Wilson confidence interval (CI). With 12 successes in 15 insertion attempts, the observed rate is 80%, with a Wilson interval of about 55% to 93%. The width reflects sampling uncertainty under the experiment’s assumptions. It is not a forecast that production performance will fall within that range on a different workload.

How the tests were actually run

The agent-in-the-loop harness limits Claude Code to Synapse MCP tools. A --disallowedTools block removes file, shell and web tools from the allowed interface. This keeps the scenario focused on MCP-driven memory instead of direct repository reads. It is a harness configuration, not a sandbox against a separately privileged host process.

After each task, the harness grades the canonical recorded state and explicit assertions. A verification report checks its named invariants; signing depends on the available key and selected policy. A canonical dump or signature does not establish the truth of all prose. This state-oriented grading is analogous to the τ-bench get_data_hash() approach, rather than treating a convincing transcript as successful storage.

The agent is nondeterministic, so the harness repeats each task. A different-model judge (Sonnet judging an Opus agent) scores Q&A against references. Both models are from the Claude family, so that is not independent human adjudication or a cross-family assessment.

The recorded scenarios are insertion (A), correction (B), a supported conflicting change (C, with agent behavior and the isolated gate measured separately), and retrieval Q&A (D). The harness in synapse-bench/ in the source repository and methodology retain reproduction details.

What the recorded runs show

The agent Q&A noise probes are distinct recorded samples:

The methodology attributes the +2,000 e2e dip to a transient claude -p failure on a five-question sample and records a retry. The observed dip remains part of the evidence; a suspected infrastructure cause does not prove the absence of retrieval or answer-quality problems in other runs.

In the baseline Q&A sample, two reference facts were missing from the first raw top-ten search, yet the agent produced correct answers after additional searches. This shows recovery of those two gaps in that run. It does not imply that agents recover every retrieval miss.

The conflict scenario separates two mechanisms. The agent voluntarily notices a conflict; Synapse separately holds a supported structured conflict when the isolated guard is tested. The first depends on agent behavior. The second checks its documented rule classes and configured write path. Neither result establishes arbitrary natural-language contradiction detection, universal non-corruption or a privileged-process security boundary.

Where the benchmark is weak (honest self-critique)

1. Small samples. The agent scenarios use 8 to 15 runs. The intervals are wide, and repeatedly running a similar fixture does not create broad field coverage.
2. Related judge and agent. Sonnet and Opus share a model family. Style preferences or shared blind spots can affect grading. Cross-family and human review would add evidence; neither is implied by the current scores.
3. Saturated metrics. Several samples reach 100%. More diverse cases, harder negatives and repeated seeds are needed before drawing broader conclusions.
4. Execution failures affect results. The five-question noise probe includes an infrastructure-associated answer-score dip. Report retries and failures instead of presenting only the successful rerun.
5. The 100,000-distractor tier was not run. Its approximately two-hour embedding cost is an estimate in the methodology. It supplies no measured quality result at that size.
6. Stub scaling is mechanical evidence. The large scaling curves use nonsemantic vectors. Their latency/size measurements do not establish semantic retrieval quality.
7. The persona fixture has incomplete provenance. Its stored JSON records 20 questions, macOS arm64 and six corpus sizes, but the original run’s source commit is unknown. It cannot establish performance of every later development commit or packaged release.

Weaknesses of Synapse itself that the benchmark exposed

1. Insertion needs better reliability. Three of fifteen attempts failed their complete insertion assertions. Saving the wrong or incomplete context is a practical weak point, even if a later storage-integrity check passes.
2. First-result retrieval still misses targets. Early persona notes reported around 0.78 recall@1; the dedicated chunking comparison reported a full-haystack improvement from 0.75 to 0.85 (SYN-301, ADR-042). In the stored 463-entity endpoint, 17 of 20 targets rank first and all 20 rank in the top ten. Those are separate recorded comparisons, not a new measurement of every current release. An opt-in reranker did not improve that corpus’s endpoint further.
3. Agent caution is not a Synapse guarantee. The 10/10 preserved-fact sample depends on the agent asking first. The isolated structured gate has its own evidence and scope; it cannot replace reasoning about every possible conflicting sentence.
4. Agent-driven temporal correctness remains a separate coverage question. The original agent benchmark did not assert complete --as-of correctness. The bitemporal-probe checks the supported write path; later native tests and current source contracts must be inspected independently. Do not infer a completed agent-loop temporal proof.
5. Semantic models have an ingestion and memory cost. The documented multilingual default download is about 2.5 GB. The measured embedding throughput, around 13 documents per second on its recorded CPU, makes large initial imports expensive. That is not a universal throughput estimate or a guarantee that later queries are unaffected by resource contention.

Use the raw persona observations, complete benchmark methodology and verification scope together when assessing these results.

Synapse in CI: the synapse-check Action

Run syn verify on every pull request so a team’s AI-written knowledge fails the build if it was silently corrupted. This turns the v1.0 headline (syn verify) from a local command into a shared gate.

Quick start

Add a workflow that runs the action against your Synapse workspace:

# .github/workflows/synapse.yml
name: synapse
on: [pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: romulofebasi/synapse@v1
        with:
          version: '1.0.0'            # pin it: never float a gate to latest
          working-directory: 'brain'  # your Synapse workspace
          args: '--rebuild'           # diffoscope-style: names every diverging fact

On every PR the job installs the pinned syn, runs syn verify --rebuild in your workspace, writes the report to the job summary, and fails closed: a non-zero exit (a diverging fact, a broken hash-chain, a tampered index) breaks the build. A clean workspace passes.

Inputs

What it proves

syn verify --rebuild checks the index is a bit-for-bit rebuild of your Markdown, the audit hash-chain + signed checkpoint are intact, and no fact was silently overwritten, and on a mismatch it names the exact diverging fact. See docs/PROVABILITY.md for the full guarantee and its honest ceiling, and docs/COMMANDS.md for the syn verify surface.

Notes

• The action installs a prebuilt syn for the runner’s OS/arch from the public synapse-releases repo; supported runners: Linux (x64/arm64), macOS (arm64), Windows (x64).
• Pin @v1 (or a tag) on the action and pin version: on the input: both, so the gate can’t drift under you.
• This composes with the multi-channel install work (Homebrew / cargo-binstall); when a stable channel lands, the install step simplifies.

Configuration

Synapse reads configuration in cascading layers. Later layers override earlier ones:

1. Compiled-in defaults (zero config).
2. System config: /etc/synapse/config.toml (POSIX only; skipped on Windows).
3. Global user config: see Paths below for the OS-specific location.
4. Workspace config: <workspace>/.synapse/config.toml.
5. Runtime overrides: CLI flags and environment variables.

Missing files at any layer are not errors: they just contribute nothing.

Config schema

# ~/.config/synapse/config.toml  (or wherever your OS puts it)

# IETF language tag. Omit to follow the system locale.
lang = "pt-BR"

# Default --format when not overridden. text | json
format = "text"

# Workspace freshness advisory (SYN-93, ADR-011).
[freshness]
enabled          = true   # global kill-switch
interval_minutes = 30     # minimum gap between two checks on the same workspace
silent_cli       = false  # suppress the stderr line; MCP enrichment is independent

# Write-proposal auto-apply policy (SYN-218, ADR-022). Evolves BR-12.3
# from an absolute gate into a confidence tier.
[proposals]
# "manual" (default): every MCP proposal queues for `syn pending accept`
#                      (the pure propose/accept invariant).
# "safe"           : auto-apply only the low-risk, reversible tier
#                      (today: link_entity between two entities that already
#                      exist and are not the `self` person); everything else
#                      still queues. Auto-applied writes are stamped and
#                      recorded on the audit trail as `auto-accepted`.
auto_apply = "manual"

# Semantic layer (v0.5 / BR-13): embedding + NER pipeline that runs
# inside Workspace::tx on every write. Active in the default build
# (the semantic layer ships by default, SYN-168); on a minimal core
# build (`--no-default-features --features mcp`) the block is still
# parsed but ignored, so the same config travels across builds.
[enrichment]
mode            = "heuristic+ner"        # "heuristic" (no NER) | "heuristic+ner" | "off"
embedding_model = "bge-m3"               # fp32 ~2.2 GB (default); "bge-m3-int8" (~560 MB, same 1024-dim space, small recall cost); "bge-small-en-v1.5-q" (~65 MB, English only)
ner_model       = "gliner-multi"         # ~350 MB cached, multilingual (default); or "gliner-base-en" (~260 MB, English only)
ner_threshold   = 0.85                   # spans below this confidence are dropped
# model_cache_dir = "/custom/path"       # override the platform default (see below)

# Opt-in network embedding provider (SYN-165): default is local
# fastembed (content never leaves the laptop). "openai"/"voyage" send
# each entity's text to a third party per write; warned at `syn init`.
# Requires a build with `--features network_backends`. See IDENTITY.md.
# provider = "openai"                    # or "voyage"; default is local fastembed
# [enrichment.openai]
# model    = "text-embedding-3-small"    # key via OPENAI_API_KEY env var (preferred) or api_key here
# base_url = "https://api.openai.com/v1" # override for a proxy / Azure gateway
# [enrichment.voyage]
# model    = "voyage-3"                  # key via VOYAGE_API_KEY env var or api_key here

The whole [enrichment] block takes effect on any build that includes the semantic layer, which is the default build (cargo build --release, SYN-168). A minimal core build (--no-default-features --features mcp) parses and ignores the block, so one config file travels across builds. The local models are not bundled and download only on consent (the syn init onboarding prompt or syn embed --all): see INSTALL.md → Feature flags for the footprint (~2.5 GB for the multilingual defaults, ~325 MB for the English opt-downs).

Only fields actually consumed by code live in the schema. Extra fields are preserved on read but ignored: handy for staging future settings.

Paths

Paths are resolved by the etcetera crate (ADR-001 + SYN-30).

The model cache directory may be overridden, in precedence order, by [enrichment] model_cache_dir = "…" in any config layer or by the SYNAPSE_MODEL_CACHE environment variable. First-run model downloads (~2.2 GB BGE-M3 + ~350 MB GLiNER-multi v2.1 quantised by default: about 2.5 GB total) land here and are reused across workspaces; sharing the cache between repos is intentional. The English opt-down models are far smaller (~65 MB BGE-small + ~260 MB GLiNER-base ≈ 325 MB).

For the full story on the models: source repos, when/how they download, offline & air-gapped provisioning, what touches the network, privacy posture, licenses, and platform compatibility (incl. the Linux glibc ≥2.38 requirement): see MODELS.md.

Environment overrides

Bootstrapping the global config + identity (v0.6)

syn setup            # guided in a TTY: locale, format, then your self-profile
syn setup --force    # overwrite existing config + re-capture identity

As of v0.6 syn setup is guided and compulsory (BR-14.1): on a fresh interactive machine syn init runs it inline before proceeding, and it captures a global self-profile: name, birthdate, profession, employers: into a profile.toml kept separate from config.toml (tool behaviour cascades; identity does not). That profile seeds the self: true person into every workspace on syn init (ADR-020). Override the profile path with SYNAPSE_PROFILE.

Non-TTY (CI, piped install, --no-input, SYNAPSE_AGENT) falls back to compiled defaults silently and skips identity capture: syn setup/syn init never block a build.

Locale precedence (BR-10.1)

--lang <CODE>   >   SYNAPSE_LANG=<CODE>   >   sys-locale   >   en  (fallback)

Examples:

syn --lang en project add "Projeto Alfa"          # one-off override
SYNAPSE_LANG=pt-BR syn info                       # shell-level override
unset SYNAPSE_LANG && syn info                    # fall back to system

Locale strings follow IETF BCP-47 (en, pt-BR, es-MX, …). Unknown locales silently fall back to en (every key is guaranteed in en per BR-10.2).

Environment variables

Output & styling (v0.6, ADR-019/021)

Output is rich by default on a TTY: colour, ✓/▲ glyphs, unicode tables, entity panels, the graph tree, progress spinners/bars, and the graph-constellation mascot. It degrades to plain bytes on a pipe and is controlled by: --plain/--raw (or SYNAPSE_PLAIN) for fully raw output; --no-color/NO_COLOR/TERM=dumb to drop colour but keep structure; --quiet/-q to suppress non-essential lines; --no-input/--yes to never prompt. --format json is always machine-clean and unstyled.

Workspace freshness (SYN-93)

The [freshness] block governs the advisory described in detail in ADR-011. Three knobs and a per-workspace override:

Future settings (not in v0.1)

The cascade is intentionally minimal today. Coming up:

Embedding/NER backend selection shipped in v0.5 as the [enrichment] block above, not a future setting.

Add them via a versioned migration (the same pattern the index uses); never by silent format change.

Contributing to Synapse

Synapse is currently invite-only on the source repo. If you have access, this is the operational guide. If you don’t and would like to, open a thread.

One-time setup

git clone https://github.com/romulofebasi/synapse.git
cd synapse
./scripts/bootstrap.sh         # activates .githooks/ and checks toolchain

Required:

• Rust 1.89+ (matches Cargo.toml and native file locking)
• POSIX shell for the git hooks

Recommended (the bootstrap script lists what’s missing):

• cargo-nextest: faster test runner
• cargo-deny: license/advisory/ban audit
• cargo-shear: orphan dep detector
• typos: pre-commit typo catcher
• git-cliff: local changelog preview

Commit messages (mandatory)

Conventional Commits, with scope:

type(SCOPE): subject

• type ∈ {feat, fix, docs, refactor, perf, test, chore, build, ci, revert, style}
• SCOPE is the SYN-N ticket (e.g. SYN-60) or an area (cli, mcp, index, store, core, model, i18n, config, deps, ci, hooks)
• subject is imperative, lowercase first letter, ≤72 chars total, no trailing period
• ! before : marks a breaking change: feat(SYN-60)!: rename roles to memberships

Enforced by .githooks/commit-msg and re-enforced by .github/workflows/commit-lint.yml on every PR.

Examples that pass:

feat(SYN-22): introduce note entity type
fix(index): respect PRAGMA foreign_keys on reopened connections
docs(adr): record adoption of rmcp 1.7
chore(deps)!: bump rusqlite 0.38 to 0.39

Before pushing

The pre-push hook requires Cargo and rejects failed validation:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo nextest run --all-features         # falls back to cargo test
python3 scripts/check-native-contracts.py
cargo doc --no-deps --all-features       # if src/ changed

You can run these any time:

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo nextest run --all-features
cargo deny check

Adding a feature

1. Ticket exists? If yes, the SYN-N is your scope. If no, open one tied to the right phase milestone (v0.1 / v0.2 / v0.3 / v0.4 / v0.5 / v1.0).
2. Business rule exists? Check docs/business/BUSINESS_RULES.md. If your change contradicts a rule, the rule changes first (PR + ADR).
3. Where does code go? Edge (CLI or MCP) calls the same function in core/. A feature that lives only in one edge is a bug.
4. File-size sanity (ADR-015). Before adding 100+ lines to an existing file, check wc -l. Yellow tier (500-800 lines): the reviewer must call it out. Red tier (800+): a refactor issue must exist and be linked, and the new code must either be part of the refactor or already remove lines.
5. Tests. Unit tests next to the code; integration tests in tests/cli.rs; snapshot tests with insta. Property tests on parsing/encoding code.
6. Smoke test the release binary. After clippy + unit tests pass, build --release and exercise the feature end-to-end against a temp workspace. cargo test covers logic; smoke covers integration (filesystem, CLI parsing, MCP stdio). Don’t mark the ticket done without it.
7. Translate. Every user-visible message gets a key in i18n/en/synapse.ftl and i18n/pt-BR/synapse.ftl, in the same commit as the feature.

File-size policy (ADR-015)

Code-review caps to keep the project legible:

Line count is a heuristic, not dogma: what matters is cohesion. A 600-line file of schemars-derived argument structs is fine; a 600-line file of braided business logic is not. ADR-015 has the full playbook and the principles (single responsibility per module, dependency inversion at boundaries, use-case isolation, edge/core/data layering preserved).

Current candidates (2026-05-25): none in red tier. src/mcp/server.rs was the example that drove ADR-015 and landed at ~640 lines (yellow tier) after the SYN-150 split: every other module in src/mcp/ stays green.

Adding an ADR

A non-obvious decision needs an Architecture Decision Record. Copy docs/adr/template.md, name it NNN-kebab-title.md, link from docs/adr/README.md. One decision per file.

Releasing

Maintainers prepare releases through ordinary reviewed source changes:

# Generate a candidate section with the reviewed git-cliff version and cliff.toml.
git cliff --unreleased --tag vX.Y.Z --strip all --offline --no-exec

# Validate committed manifest/lock versions, notes and publication controls.
python3 scripts/check-release-tests.py -v
python3 scripts/check-release-independent-tests.py -v
python3 scripts/check-release-document-tests.py -v

Replace the candidate section rather than prepending it twice. Preserve older sections exactly. Commit matching root manifest and lockfile versions with the reviewed notes, then require exact-source CI, MSRV and independent review. Only after those gates pass, create the authorized annotated version tag on that reviewed source. Use Rômulo Febasi <romulo@febasi.com.br> for both commit and tag identity. Changelog generation alone does not create a Git tag.

The tagged workflow builds four native targets: Linux x86_64 and ARM64, Apple Silicon macOS, and Windows x86_64. It packages document bytes from committed Git blobs, checks every archive changelog against the source receipt, and signs the checksum manifest before publication. It does not write back to main. The public mirror preserves the original assets and signature. npm independently verifies the exact source receipt, signature and archive layout before publishing five platform/launcher packages with OIDC.

Existing release tags and assets are never replaced by the workflow. Fix a published packaging defect with a new reviewed patch version. An explicit retry of an unpublished release must select the existing tag as the workflow ref and input; a branch dispatch does not retain the required signing identity.

See ADR-007 and release verification for the complete contract and platform limits. Checksums and signatures authenticate selected bytes; they do not prove independent build reproducibility.

House rules

• Don’t add a dependency without an ADR.
• Don’t reach for unsafe: #![forbid(unsafe_code)] is set at the crate root.
• Don’t introduce serde_yaml or serde_yml: both are banned in deny.toml (ADR-004).
• Don’t use unwrap() in library code; doctests use ? with # Ok::<_, Error>(()).
• Don’t shell out to git from production code: use gix if needed.
• Don’t add a CLI message without a Fluent key.

If something here is wrong, edit it (this file is the source of truth for contributors).

_{Ship it.}

Documentation publication

The documentation site is generated with pinned mdBook 0.5.4 from canonical tracked product Markdown. It includes README, quickstart, installation, tutorial, recipes, command/contract references, architecture, business/design/research docs, the complete canonical ADR index and ADR pages, and changelog. Browser-side full-text search covers the generated chapters. No manual duplicate ADR index is maintained.

Internal session handoffs and authoring templates are excluded from public publication. Only tracked regular product files, branding assets and explicitly sanitized decision evaluation artifacts enter the book; untracked notes, environment files, private keys, database files and model weights are never copied. Publication records the exact source commit and source file hashes in publication.json.

Editorial standard

Follow the Febasi writing rule. Maintain English copy in README, product statements, ADRs, design pages and the site title. Do not use em dashes in authored prose. The canonical positioning is:

Operational memory for agents, with governed changes, preserved history, and explicit integrity checks.

Review the rendered homepage and affected chapters as well as source Markdown. The publisher preserves tracked source text; it does not translate or normalize legacy chapters automatically. Editorial changes must preserve historical decision status, code examples, identifiers and link targets.

Mermaid diagrams

The generated book uses official mdbook-mermaid 0.17.1, compatible with mdBook 0.5. The Pages workflow verifies both official release archive SHA-256 values before unpacking either executable. The standard mdbook-mermaid install command copies its bundled Mermaid runtime and initializer into the generated book. mdBook publishes both as local scripts, including on nested ADR pages. There is no runtime CDN dependency and no change to canonical Markdown fences. Upstream license banners remain in the bundled assets.

The publication verifier checks each chapter’s fenced diagram count against its HTML containers, rejects raw Mermaid code blocks, and requires the pinned local runtime and initializer in that order. Missing, changed, remote or escaping script references fail publication. These checks prove generated structure and asset identity. They do not execute JavaScript or prove SVG rendering, typography or layout. Browser acceptance must separately inspect diagrams, console errors, light/dark themes and nested-page navigation before closing SYN-342 (#347). See ADR-072.

Local validation

Install the same pinned official tools used by .github/workflows/pages.yml without compiling them, then run the full documentation publication suite:

python3 scripts/check-docsite.py -v
python3 scripts/check-docsite-independent-tests.py -v

For a persistent preview:

python3 scripts/prepare-docsite.py --output /tmp/synapse-docsite
mdbook-mermaid install /tmp/synapse-docsite
mdbook build /tmp/synapse-docsite
python3 scripts/verify-docsite.py /tmp/synapse-docsite
python3 -m http.server 8080 --bind 127.0.0.1 --directory /tmp/synapse-docsite/html

Use an absent dedicated output directory; regeneration never deletes an arbitrary folder. The verifier checks all generated chapter paths, tracked asset coverage, search contents, canonical ADR coverage and absence of private/runtime artifacts. It rejects em dashes in rendered chapter/navigation text, accessible labels and maintained SVG text. Tracked documentation SVGs are published with the book. Browser verification additionally checks actual search results and navigation. GitHub pull requests build and validate an artifact; merged main deploys through GitHub Pages with separate minimal deployment permissions. Both official tool archives are pinned by version and SHA-256 in the workflow.

The independent publication review preserves the original eight-mutant campaign and its three survivors. The added tests independently derive complete chapter coverage from tracked canonical sources and invoke the actual verifier CLI on broken non-release diagram pages. Pages requires both suites, 14 original methods plus three independent methods. Changes to either suite also select the documentation workflow. Final workflow wiring and browser acceptance remain distinct from the original frozen review.

Domain rollout

The initial Pages URL is https://romulofebasi.github.io/synapse/. The requested canonical URL is https://synapse.febasi.com.br/. The repository uses Pages workflow deployment; its Git repository remains private.

The authoritative DNS provider is Cloudflare. To finish the custom-domain acceptance of SYN-109, an authorized operator must provide access to the zone or create this new record:

Verify the exact domain through GitHub’s ownership/domain validation, configure the Pages custom domain after DNS resolves, wait for its certificate and enable HTTPS. The book’s site-url must be / for the custom domain (initial project-site prefix is /synapse/). Validate the final URL, HTTPS certificate, redirects, chapter links and browser search before marking #89 complete. Do not point a DNS record at a disabled/unowned Pages site.

The source publication and default Pages URL can be delivered while zone access is unavailable; that does not satisfy the requested custom-domain acceptance. No credentials belong in this document or generated artifact.

Primary references: mdBook installation, GitHub Pages custom domains.

Mermaid references: official mdbook-mermaid v0.17.1, mdBook local JavaScript configuration.

Synapse: editor integration

TL;DR: Synapse ships an LSP companion (syn lsp) so any editor that speaks LSP gets entity-aware completion, hover, go-to- definition and dangling-reference diagnostics on every .md file in a workspace. Build with the lsp feature, point your editor at the syn lsp binary, done.

1. Build with the LSP feature

cargo install synapse --features "mcp lsp"
# or, from this repo:
cargo build --release --features "mcp lsp"
# binary lands at target/release/syn

Confirm the subcommand:

syn lsp --help
# Run the LSP companion on stdio (slug/type/tag completions, hover,
# go-to-definition, dangling-ref diagnostics): SYN-130.

The server reads .synapse/index.db from the workspace root; runs syn reindex once if completions look stale.

2. What you get

• Completion in .md files:
  • Inside [[<cursor>: every workspace entity slug.
  • After type: <cursor>: the six entity types (project, person, entity, api, task, note).
  • Inside tags: [<cursor>: every distinct tag in the workspace.
• Hover over [[slug]]: entity title + first paragraph of the body.
• Go-to-definition on [[slug]]: jumps to the entity’s markdown file.
• Diagnostics: [[slug]] with no matching entity is flagged as a Warning, source: "synapse".

3. Helix

~/.config/helix/languages.toml:

[language-server.syn-lsp]
command = "syn"
args    = ["lsp"]

[[language]]
name             = "markdown"
language-servers = ["syn-lsp"]
roots            = [".synapse"]

Helix auto-discovers the workspace root by walking up to .synapse/.

4. Neovim (nvim-lspconfig)

init.lua:

local lspconfig = require("lspconfig")
local configs   = require("lspconfig.configs")

if not configs.syn_lsp then
  configs.syn_lsp = {
    default_config = {
      cmd       = { "syn", "lsp" },
      filetypes = { "markdown" },
      root_dir  = lspconfig.util.root_pattern(".synapse"),
      settings  = {},
    },
  }
end

lspconfig.syn_lsp.setup({})

5. VS Code (and Cursor)

VS Code does not auto-discover non-marketplace LSPs, so it needs the thinnest possible extension. Drop this into a folder and code --install-extension .:

// package.json
{
  "name": "synapse",
  "version": "0.0.1",
  "engines": { "vscode": "^1.94.0" },
  "activationEvents": ["onLanguage:markdown"],
  "main": "./extension.js",
  "contributes": {
    "languages": [{ "id": "markdown", "extensions": [".md"] }]
  }
}

// extension.js
const { LanguageClient, TransportKind } = require("vscode-languageclient/node");
let client;
function activate() {
  client = new LanguageClient(
    "synLsp",
    "Synapse LSP",
    {
      command: "syn",
      args: ["lsp"],
      transport: TransportKind.stdio,
    },
    {
      documentSelector: [{ scheme: "file", language: "markdown" }],
      workspaceFolder: undefined,
    },
  );
  client.start();
}
function deactivate() { return client && client.stop(); }
module.exports = { activate, deactivate };

Cursor inherits the same extension API; the config above works identically.

6. Zed

~/.config/zed/settings.json:

{
  "lsp": {
    "syn-lsp": {
      "binary": { "path": "syn", "arguments": ["lsp"] }
    }
  },
  "languages": {
    "Markdown": { "language_servers": ["syn-lsp"] }
  }
}

7. Troubleshooting

No completions. Run syn reindex in the workspace. The LSP server reads from .synapse/index.db; if it’s missing or empty nothing comes back. Also verify your editor is actually launching the server: most editors expose an “LSP log” command that shows the stdio handshake.

[[slug]] warning is wrong. The diagnostic source is synapse and it fires when no entity with that slug exists in the index. The fix is either (a) create the entity (syn project add foo, etc.) or (b) update the link.

Hover shows nothing. Hover is only implemented for [[slug]] references. Hovering on free text returns nothing by design.

Go-to-definition opens the wrong file. Each slug must be unique across the workspace: the index returns the first match. If you have two entities with the same slug in different types, rename one.

8. References

• ADR-018: why we picked tower-lsp-server over the inactive tower-lsp.
• SYN-130, acceptance criteria for the v0.4 LSP companion.
• LSP 3.18 spec: https://microsoft.github.io/language-server-protocol/.

Synapse: portable identity & curriculum

For compliance reviewers: Synapse’s identity bundle is a signed, human-owned artefact. The human runs syn identity keygen, signs the bundle on export, and the importer verifies against a workspace-local trusted_keys allow-list. Revocation is in-band: a bundle’s revoked array propagates to every consumer who re-imports. The curriculum surface (syn experience, syn skills, syn cv export) is reproducible without an LLM: same inputs always produce identical bytes. ADR-014, ADR-016, ADR-017 cover the design rationale.

1. What a bundle is

me.synapse.json is a single JSON file the human carries across employers. Shape:

{
  "synapse_protocol": "synapse/v1",
  "kind": "identity-bundle",
  "exported_at": "2026-05-25T18:54:15Z",
  "person": {
    "id": "romulo",
    "title": "Rômulo",
    "frontmatter": { /* full YAML mirror as JSON */ },
    "body": "/* markdown body */"
  },
  "attestations": [
    { "type": "project", "id": "cliente-alfa", "role": "tech-lead",
      "since": "2024-01-01", "title": "Tech lead Cliente Alfa" }
  ],
  "skills": [
    { "name": "rust", "count": 17 },
    { "name": "mcp",  "count": 9 }
  ],
  "revoked": [],
  "signature": "base64-64-bytes-ed25519",
  "public_key": "base64-32-bytes-ed25519"
}

The bundle is tiny (a low double-digit KB even with dozens of attestations) and human-readable. Any text editor can open it. That is the point: a regulator or recruiter who does not have Synapse installed can still read the artefact.

2. Signing & verification

# Once per human, kept on the laptop.
syn identity keygen
# wrote private key to ~/.config/synapse/identity/private.key: public: <base64>

# Export: signs with the configured key.
syn identity export --out me.synapse.json --key ~/.config/synapse/identity/private.key

# Import: verifies against [identity] trusted_keys in config.toml.
syn identity import me.synapse.json
# pessoa "romulo" importada de me.synapse.json

The signed bytes are canonical JSON: keys recursively sorted, the signature field omitted, public_key included. Two implementations must agree on the canonicalisation byte-for-byte; that is why Synapse owns both the producer and the verifier today and the format is byte-stable.

Trust model:

• If trusted_keys is empty, any embedded public_key is accepted. This is the single-user mode: you sign your own bundle, you import it on another machine, it Just Works.
• If trusted_keys is non-empty, the bundle’s public_key must appear in the list. This is the cross-org mode: an employer or recruiter pins the keys they trust.
• An unsigned bundle (v0.3 format) errors on import unless you pass --allow-unverified. The imported person stamps verified: false so downstream consumers can see the trust level at a glance.

ADR-016 covers the full rationale. The crypto layer is ed25519 via ed25519-dalek 2.1; no PKI, no Sigstore: local-first by design.

3. Revocation

A bundle author who realises an attestation is wrong (employer dispute, role title was inflated, security incident) does not need to chase down every consumer. Revocation is in-band:

syn identity revoke me.synapse.json --target project/cliente-alfa --key ~/.config/synapse/identity/private.key
# "project/cliente-alfa" revogado: bundle agora lista 1 revogação(ões)

The bundle’s revoked array now contains project/cliente-alfa. The next consumer to syn identity import me.synapse.json filters attestations whose {type}/{id} (preferred) or bare id appears in revoked before writing to attested_involvement. Re-signing happens automatically when --key is provided; without --key, the old signature is dropped so the bundle does not lie about being verified.

Revocation is additive. The author cannot un-revoke; that is a deliberate property: once you have told a consumer “this attestation is wrong”, it stays wrong.

4. Capturing experience

The bundle’s attestations array comes from the self: true person entity’s attested_involvement frontmatter. The CLI to manage it:

# Add an entry.
syn experience add "Tech lead at Cliente Alfa" \
  --target project/cliente-alfa \
  --role tech-lead --since 2024-01-01

# Review.
syn experience list

# Remove every entry matching project/cliente-alfa.
syn experience rm project/cliente-alfa

Each add rewrites the self person’s markdown atomically. The person entity must exist with self: true in its frontmatter: Synapse refuses to guess which person is the human behind the workspace.

As of v0.6 you normally don’t create it by hand. syn setup captures a global self-profile (name, birthdate, profession, employers) into profile.toml, and syn init seeds the canonical self: true person into every workspace from it: “capture once, seed everywhere” (BR-14, ADR-020). Employers become entity(kind=org) nodes, linked from the self person by an employed-by graph edge (recorded under affiliations and materialised by the seed / syn reindex). The seeded frontmatter looks like:

---
type: person
id: ada-lovelace
title: Ada Lovelace
self: true
birthdate: 1815-12-10        # optional; rendered by the detailed cv export
headline: Mathematician      # → cv headline
affiliations:
  - org: analytical-engine-co
memberships: []
---

If there’s no profile yet (a non-interactive install), set self: true by hand on the entity that represents you, or run syn setup and re-init: cv/identity export point you at syn setup when no self person exists. Override the profile path with SYNAPSE_PROFILE.

syn experience is not capture_fact (BR-12.3). It runs synchronously and writes directly. The pending queue is for LLM-proposed writes; experience entries are claims the human is making about their own past, so they bypass the queue.

5. Skills derivation

syn skills ranks the workspace’s tag frequency:

syn skills --limit 10
#    17  rust
#     9  mcp
#     7  cli
#     5  observability
#     ...

A tag that recurs across many entities is a topic the human spends real time on. The v0.4 algorithm counts every occurrence of a tag across every entity in the workspace; the top N (default 20, capped 200) ships in the bundle’s skills array and renders in the CV.

This is the simplest defensible signal. ADR-017 lists the richer signals reserved for v0.5+ (project depth, decision count, owner-resolved attribution). If the ranking surprises you, the fix is usually to clean up tag noise or rename a tag, not to call ranking broken.

6. CV export

syn cv export --out cv.md
# CV gravado em cv.md

syn cv export --style minimal       # flat skill list, no decisions section
syn --format json cv export         # structured intermediate for custom renderers

The Markdown sections are fixed and ordered:

1. # {name} + optional _headline_
2. Born: {birthdate}: detailed style only, when the self person has a birthdate (v0.6, SYN-205)
3. Contacts line (email · github · linkedin · website)
4. ## Summary: the person body
5. ## Skills: top N from syn skills (counts in detailed only)
6. ## Experience: attested_involvement, newest first
7. ## Recent decisions (detailed only): last 5 notes with kind: decision, capped with an explicit comment marker

Two runs against the same workspace produce byte-identical output. That is the contract: a regulator or recruiter who reproduces the file gets the same bytes you handed them. An LLM is welcome to polish the result afterwards (copy the Markdown into your model of choice and ask for a rewrite) but the canonical CV is the deterministic one.

PDF export is deferred to v0.5+. Today the workflow is syn cv export | pandoc -o cv.pdf if you need PDF.

7. Worked example: full round-trip

# 1. Generate a key (once).
syn identity keygen

# 2. Mark yourself.
$EDITOR people/romulo.md
# … set `self: true`, fill in email/github/headline, save.

# 3. Record involvement.
syn experience add "Tech lead Cliente Alfa" \
  --target project/cliente-alfa --role tech-lead --since 2024-01-01
syn experience add "Dev Cliente Beta" \
  --target project/cliente-beta --role dev \
  --since 2022-06-01 --until 2023-12-01

# 4. Export the bundle, signed.
syn identity export --out me.synapse.json \
  --key ~/.config/synapse/identity/private.key

# 5. Hand the bundle to someone.
#    They configure their workspace's config.toml:
#      [identity]
#      trusted_keys = ["<your base64 public key>"]
#    Then:
syn identity import me.synapse.json
# → pessoa "romulo" importada; verified=true.

# 6. Render the CV (on any machine that has the workspace + bundle).
syn cv export --out cv.md

8. Troubleshooting

“importando bundle sem assinatura” / --allow-unverified. You exported without --key (or the key file was unreadable). The bundle is still importable but the consumer needs to opt in with --allow-unverified. The imported person carries verified: false. Fix it by re-exporting with a real key.

“assinatura do bundle inválida ou não-confiável”. Either the bundle was tampered with after signing (canonical JSON no longer matches the signature), or the public_key is not in the consumer’s trusted_keys allow-list. Compare the bundle’s public_key against your config; add it explicitly via syn identity import --trusted KEY for one-shot acceptance.

Lost private key. You can no longer sign new exports or new revocations of bundles you already produced. Bundles already signed with the lost key remain verifiable forever. The recovery path is: syn identity keygen to make a new key, re-export your bundle with it, and ask consumers to add the new key to their trusted_keys. There is no way to “transfer” trust from the old key to the new one, that would defeat the point of asymmetric crypto.

No self: true person. syn experience and syn identity export both refuse without exactly one person flagged self: true. Add the flag to the frontmatter of the person entity that represents you. If you have multiple, pick one: federation (BR-12.4) does not span identities, each workspace has exactly one self.

8b. Network embedding providers: the privacy trade-off (SYN-165)

By default the v0.5 semantic layer embeds on device (fastembed + BGE-M3): your notes never leave the laptop, which is the whole point of a local-first second brain (BR-12.1).

Two opt-in network providers exist for users who want a hosted model instead:

[enrichment]
provider = "openai"          # or "voyage"; default is local fastembed

[enrichment.openai]
# Prefer the env var OPENAI_API_KEY over a key in this file: a key on
# disk is a secret that may get committed (BR-12.2).
model = "text-embedding-3-small"

Equivalent block for Voyage under [enrichment.voyage] (VOYAGE_API_KEY, default model voyage-3). Both are requested at 1024 dimensions so the vector fits the existing table.

What you are trading. With a network provider, the full text of every entity is sent to that third party on every write: every note, meeting, decision, and person record. The provider’s data-handling policy, not Synapse, then governs that content. This is the explicit exception to BR-12.1, and Synapse makes it loud:

• syn init prints a warning when a network provider is inherited from a config layer.
• Each time a network backend is instantiated (CLI write or MCP server start), it prints a one-time content is sent to <provider> warning to stderr.
• Synapse stores no API key itself: it reads the env var (or your config) at call time and keeps nothing.

The feature is compiled in only with --features network_backends; a default build cannot send anything anywhere.

9. References

• ADR-014: original bundle format (v0.3 prototype).
• ADR-016: mandatory ed25519 + revocation (v0.4).
• ADR-017: experience array, skill derivation, CV format.
• AUDITABILITY.md: the broader audit story; the identity layer sits next to it.
• PROVENANCE.md: x-ai-* stamps on AI-authored entities.

Synapse + MCP: letting your AI read your second brain

syn mcp starts a Model Context Protocol server over stdio. Any MCP client can plug in. We document Claude Code below; the wiring is the same for any client that supports stdio MCP servers.

What gets exposed

Twenty-five tools. Twelve read-only on the current workspace (incl. query, the read-only aggregation tool, SYN-183, and workspace_health, SYN-310); four read-only across opt-in workspaces (SYN-78, SYN-92 read slice); one maintenance tool (reindex, SYN-138); one audit tool (replay_proposal, client-driven: it returns replay material the agent re-runs; no server-side sampling, SYN-219); one integrity tool (verify, SYN-263: proves the memory was not silently corrupted); six write proposals routed through a human confirmation queue. Write tools never touch the workspace directly: the AI proposes; you sanction (or, under the safe auto-apply policy, low-risk reversible writes apply and are stamped auto-accepted; SYN-218).

The read contract (SYN-177/178/201/203). Every read tool returns the uniform { "result": <payload>, "freshness"? } envelope as MCP structuredContent (read that field directly: no prose parsing), plus a compact-JSON text mirror for clients without structured support. Each read tool advertises an outputSchema on tools/list, and search_knowledge hits + get_entity attach a resource_link to synapse://entity/{type}/{id} so a result is openable with resources/ read: no second get_entity round-trip.

Read-time hints (SYN-308). The high-value reads (search_knowledge, search_everything, workspace_overview, list_by_type, recent_changes, blame) attach a deterministic _meta sidecar, a sibling of structuredContent, so it never touches the outputSchema contract. It carries workspace (which brain answered), a precision breakdown of the SYN-304 relevance bands ({strong, good, partial}) and result_count for searches, and a next_step, the cheapest sensible follow-up (triage-then-get_entity, paginate with cursor, call workspace_health, propose an update on a low-trust blame). The agent reads _meta to judge whether results are on-topic before spending tokens, and errors carry a matching data.remediation (SYN-309, below).

Workspace-local

search_knowledge mode (v0.5, SYN-88). Mirrors the CLI search modes: "hybrid" (default, FTS + vector + graph fused with RRF), "semantic" (vector similarity only), or "no-vector" (FTS + graph, skips the embedding step). The semantic layer ships in the default server (SYN-168); the vector legs go quiet: every search falls back to plain FTS5: when the models haven’t been downloaded yet or on a minimal core build (--no-default-features --features mcp). The hits keep the {type, id, title, snippet} shape (plus matched_by/relevance/compatibility when fused: SYN-304/306), wrapped in the {result, freshness?} envelope described above; a client that does not set mode keeps the default hybrid ranking. The independent legs (FTS + vector) run in parallel on separate connections (SYN-306 / ADR-044); the fused order is a pure function of the per-leg orders, so it stays deterministic. There is no separate semantic_search tool, the mode parameter delivers it without duplicating the search path.

Enrichment on accept (v0.5, BR-13). With the semantic models present, accepting a write proposal (or any other workspace write) runs the insertion-time enrichment pipeline inside the transaction: the new entity is embedded into entities_vec and its mentions are linked, so it is immediately findable by the next search_knowledge call. NER mentions that don’t resolve queue their own create_entity_from_ner proposals for review. Before the models are downloaded, the write still succeeds, enrichment is skipped gracefully and never triggers a download (run syn embed --all to backfill once the models are in place).

Federation (v0.2, SYN-78 + SYN-92 read slice)

Write proposals (v0.2, SYN-60/61/62/92)

Every write tool below enqueues a proposal; it does not touch the workspace. The response carries the pending_id plus accept_command / reject_command strings the LLM can surface verbatim. The user reviews with syn pending show <id> and applies with syn pending accept <id>. See BR-12.3: MCP não escreve sem confirmação humana.

Every write tool also accepts an optional context JSON snapshot (SYN-114) recorded with the proposal for syn audit replay.

Response shape for every write tool:

{
  "pending_id": 7,
  "accept_command": "syn pending accept 7",
  "reject_command": "syn pending reject 7",
  "kind": "capture_fact",
  "summary": "note \"PKCE OAuth decision\""
}

Write tools return this object as structuredContent plus a compact-JSON text mirror (the read envelope is for read tools only). The same use cases back the CLI; there is no “second truth”.

Freshness advisory (SYN-93, ADR-011)

Every tool response that touched a workspace can carry a freshness block when the workspace’s tracked origin branch differs from the local one (or the check has timed out: Phase 2). The shape is:

{
  "result": <original tool payload>,
  "freshness": {
    "workspace": "client-alfa",
    "status": "diverged",
    "behind_count": -1,
    "last_check": "2026-05-25T14:00:00Z",
    "advice": "git -C /Users/.../client-alfa pull"
  }
}

Rules:

• result is always present (the uniform envelope, SYN-203); only the freshness block is conditional; it is attached when there is something to say, and omitted for up_to_date/unknown statuses (silence is the polite default).
• behind_count = -1 in Phase 1 means “histories differ; the precise count lands with SYN-93b”.
• advice is always a concrete git -C <root> pull command the LLM can surface verbatim.
• The check itself is filesystem-only and rate-limited (default 30 min); the AI never pays a network round-trip for it.

Disable per-workspace with syn ws freshness off <name>. Disable globally with [freshness] enabled = false in any config layer. The MCP enrichment ignores silent_cli; that knob only governs the CLI stderr line.

Privacy gate (BR-12.4, SYN-79)

Federation defaults OFF. A workspace only appears in list_workspaces, contributes hits to federated_search, or is readable via get_entity_from / get_workspace_manifest after the user runs syn ws include <name> on it.

This is a structural invariant, not a check: every fan-out path in the codebase goes through crate::core::federation::fan_out{,_filtered}, which hard-codes Registry::list_federated() (the SQL filter is WHERE federated = 1). Non-opt-in ids passed to federated_search.workspaces are silently dropped: distinguishing “exists but not federated” from “does not exist” would leak the bit BR-12.4 is meant to keep private. The same applies to get_entity_from and get_workspace_manifest: both raise an indistinguishable entity '<name>' not found for “no such workspace” and “exists but private”.

Claude Code

The zero-friction path (SYN-288): let syn write the config for you:

syn mcp install                          # Claude Desktop (claude_desktop_config.json)
syn mcp install --client claude-code     # project-local .mcp.json in the current dir
syn mcp install --workspace my-brain     # pin a brain by name/path (SYN-300 / #287)
syn mcp install --print                  # print the JSON snippet, write nothing
syn mcp uninstall                        # remove just the synapse entry

--workspace <path|name> (SYN-300 / #287). By default the installed config runs syn mcp with no cwd, so it only finds a brain when the client launches inside the workspace. Pass --workspace and install bakes --workspace <ref> into the config args, so the server serves that brain from any directory, the cross-project “query my brain from another repo” flow, with no manual editing.

install merges a synapse entry into the existing config: other MCP servers and unrelated keys are left untouched, the prior file is backed up to *.json.bak, and re-running updates the entry in place (idempotent). It points command at the absolute path of the running syn binary.

Prefer to edit by hand? Add this to ~/.claude.json (or run claude mcp add synapse …):

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

• command is whatever syn you installed (which syn to confirm).
• cwd is the workspace you want the server to read from.
• No environment variables needed for v0.1.

Serve a brain from another project (cross-directory)

syn mcp reads the workspace from the current directory by default, so a client launched in a different project (not itself a Synapse workspace) has nothing to serve. To point the server at your brain wherever you are, pass --workspace (SYN-300 P1): an absolute path, or a registered name/id from the global catalog (syn ws list; every syn init registers there):

# by path
claude mcp add synapse -- syn mcp --workspace /Users/you/brain
# or by registered name/id: works from any project directory
claude mcp add synapse -- syn mcp --workspace my-brain

Now Claude Code in any repo answers from that brain: you don’t have to cd into it. (This is cleaner than the cwd field above, which depends on the client honoring a working directory; --workspace resolves the brain itself.)

Restart Claude Code and ask, in any project:

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

Claude calls project_graph(type=project, id=projeto-alfa) to find Maria, then get_entity(type=person, id=maria-silva) to read her file, then surfaces the answer with the right slugs.

Other MCP clients

If your client speaks MCP over stdio, the launch command is the same:

syn mcp

Synapse also advertises resources on resources/list: the workspace manifest, the server card, synapse://capabilities (SYN-311, the self-describing vocabulary: entity types + their fields, link relations, reserved x-* keys, write-proposal payload shapes, enrichment sources; read it before proposing to avoid an invalid kind/rel/key, the same dump the CLI syn context prints), every entity, and the recent audit trail.

Synapse advertises tool schemas (input + output JSON Schema) on tools/list, each with MCP tool annotations (readOnlyHint on every read, no destructiveHint on the additive write proposals, idempotentHint on reindex) so a client can auto-allow reads and gate writes without guessing. The 25 names are search_knowledge, search_everything (SYN-226, RRF over every kind), query (SYN-183, read-only aggregation), get_entity, get_entities, list_by_type, project_graph, workspace_overview, workspace_health (SYN-310), recent_changes, blame (SYN-256), diff (SYN-256), verify (SYN-263, proves non-corruption), list_workspaces, federated_search, get_entity_from, get_workspace_manifest, reindex (SYN-138, emits Tasks progress under --features mcp_tasks), replay_proposal (SYN-136/SYN-219, client-driven: it returns replay material the agent re-runs: no server-initiated sampling, which the MCP spec has since deprecated in SEP-2577), capture_fact, link_entity, update_status, add_workspace_topic, add_workspace_tag, propose_batch.

Actionable errors (SYN-309)

A recoverable condition (unknown id/type, a missing/invalid proposal field, no workspace, a model still downloading) comes back as a JSON-RPC invalid_params error whose data carries a stable code (the i18n key), a category (user/transient), recoverable/retryable flags, and a remediation string naming the exact next step (e.g. “unknown type: read the synapse://capabilities resource for the registered types”, or “no such entity: discover ids with search_knowledge”). The remediation is also appended to the human-readable message. Genuine faults (a corrupted audit trail, a migration mismatch) stay internal_error but are still annotated, so a client never has to parse prose to know whether the agent can retry. Internal paths and SQL are never leaked (ADR-023 posture).

Locking down what the AI sees

The server’s cwd workspace is always fully readable through the local read tools (search_knowledge, search_everything, get_entity, get_entities, list_by_type, project_graph, workspace_overview, workspace_health, recent_changes, plus the read-only query aggregation). Other workspaces are only reachable when the user has opted them in:

cd ~/work-brain && syn ws include work-brain    # join the federated pool
cd ~/client-acme-brain && syn ws include client-acme-brain
syn ws exclude work-brain                       # leave anytime

The federation tools (list_workspaces, federated_search, get_entity_from, get_workspace_manifest) only ever see workspaces marked federated = 1. Workspaces left at the default (private) never leak through the server, even if the LLM literally asks for them by name. See the Privacy gate section above.

The simplest segmentation is still one workspace per audience:

~/brain/                       ← personal: notes, decisions, drafts
~/work-brain/                  ← work: APIs, stakeholders, tasks
~/client-acme-brain/           ← per-client

Run one syn mcp per cwd (Claude Code spawns one process per mcpServers entry); opt only the workspaces you trust into the federated pool.

Inspect the server by hand

Useful when something is off. The protocol is JSON-RPC over stdio:

cd ~/brain
{
  printf '%s\n' \
    '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"manual","version":"0"}}}' \
    '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
    '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
    '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_knowledge","arguments":{"query":"pagamentos"}}}'
  sleep 1
} | syn mcp | jq .

You’ll see serverInfo + the full tools/list schema set (25 tools, each read carrying an outputSchema) + a search_knowledge result whose structuredContent is the {result, freshness?} envelope, with resource links on the hits. With the semantic models present the result is hybrid-ranked; add "mode":"semantic" to the arguments for vector-only.

Shipped in v0.5

Prompts

Nine named prompts (the synapse: namespace), each a deterministic function of (name, args, workspace): no LLM round-trip to assemble:

• synapse:capture-decision: guided capture_fact flow for a decision note.
• synapse:daily-review: yesterday’s accepted proposals + open tasks.
• synapse:weekly-brief: audience-tailored weekly briefing.
• synapse:proposal-contract (SYN-252): the proposal-quality contract an agent should read before a capture session.
• synapse:onboard-workspace (SYN-312): first-run orientation: read the capabilities + overview, confirm the self-identity, learn the propose→accept gate. Start a fresh session here.
• synapse:orient (SYN-312): the cheapest-read decision table (which read tool for which question) as a fetchable prompt.
• synapse:catch-me-up (SYN-312): resume with a delta via recent_changes since a given instant, not a full re-read.
• synapse:resolve-contradiction (SYN-312): when a capture_fact returns a contradicts signal, walk the supersede-don’t-duplicate path (x-supersedes).
• synapse:capture-and-verify (SYN-312): the full governed-write loop: propose → hand over the accept command → offer syn verify.

Contradiction detection (SYN-242)

At propose-time Synapse checks, deterministically and on structured fields, whether a write contradicts an accepted fact: same subject + predicate, different object: an update_status that flips a field to a different value, or a link_entity that re-points the same edge to a different relationship. A contradiction is never “low-risk reversible”, so it is forced to the human gate even under auto_apply = safe, and the write tool’s response carries a contradicts: {subject, predicate, existing, proposed} signal. Resolve by superseding the existing fact (x-supersedes, SYN-223): invalidation, not duplication, not by adding a near-duplicate. Free-text (NLI) contradiction and same-subject detection across separate captures (identity resolution) are deferred to v0.11 (SYN-245/254).

Proposal-quality contract (SYN-252)

The differentiator of governed memory is that a human accepts each fact, so the scarce resource is the reviewer’s attention. A good proposal respects:

1. Atomicity: one subject–predicate–object per proposal; never bundle unrelated claims.
2. Observation date: x-valid-from is when the fact became true in the world, not when you learned it (transaction-time comes from git; don’t duplicate it).
3. No echo: search first; propose deltas, not duplicates of what’s already there.
4. Supersede, don’t duplicate: a changed fact carries x-supersedes: <old-id> (the old interval is closed on accept: invalidation, not deletion, SYN-223).
5. No meta-extraction: facts about the domain, not about the conversation.
6. Attribution: cite the source; provenance (x-ai-*) records who/when automatically.
7. Typed over prose: prefer a typed entity + indexed fields when the domain has structure (syn types).

Agents fetch the canonical copy via prompts/get synapse:proposal-contract; this section is the human-readable mirror.

What doesn’t exist yet (and when)

When syn mcp hands back a (no hits) response, that’s Lil Syn dozing on an empty index. The fix is usually one of: a missing tag, a typo, or just not enough indexed yet. Run syn search <term> from your shell to see if you find it before blaming the AI.

Migrating to Synapse 1.0

TL;DR: 0.x → 1.0 is a no-op for your data. The Markdown is the source of truth and the index is disposable, so there is nothing to migrate by hand: upgrade the binary and run syn reindex if anything looks off. v1.0 freezes the public surface under semver; this page says exactly what that covers.

What “1.0 stable” means

The 1.0 stability promise covers the Synapse public surface under semantic versioning (BR-11.2):

• the Markdown + frontmatter schema (the on-disk format your notes live in),
• the CLI (syn subcommands and flags),
• the MCP tool surface (the 24 tools an agent sees).

A breaking change to any of these requires a major bump (and, for commits, a ! per the conventional-commit policy). Additive changes (new optional frontmatter keys, new commands, new MCP tools) are minor.

What the promise does not cover (documented, not a broken promise):

• The transitive ML runtime (ort/ONNX Runtime). v1.0 ships on an ort release candidate, transitively forced by the embedding/NER stack, with a tracked exit to the final release: see ADR-038. The semantic models download on consent and the index is disposable, so any runtime change is re-derivable, never silent data loss.
• The SQLite index schema (.synapse/index.db). It is disposable: see below, so it is deliberately not part of the semver surface.

The index is disposable (so migrations are low-stakes)

The SQLite index is a pure function of your Markdown (BR-1.4 / BR-7.2.1). If an upgrade changes the index format, you do not migrate data: you rebuild it:

rm -rf .synapse/index.db && syn reindex      # or: syn reindex --force-rebuild

No user data lives only in the index, so the worst case of any index-schema change is a rebuild. Index migrations are expand-only (new columns are nullable and populated by reindex, never required at migration time), and applied migrations are checksum-locked: see BR-7.2.1. You can prove the rebuild is faithful with syn verify (syn verify --rebuild names any divergence).

Upgrading from 0.x

1. Update the binary (see docs/INSTALL.md; the synapse-check Action pins a version for CI).
2. Open a workspace. If syn doctor or syn verify flags anything, run syn reindex. That is the entire migration.
3. (Optional) MCP clients: syn mcp install now wires Synapse into your client config for you (see docs/MCP.md).

There is no frontmatter rewrite, no manual schema step, and no data export/import needed to move from 0.x to 1.0: the format was stable in practice across 0.x and is now stable by promise.

Reverse migrations

Forward migrations are the norm; reversal is not generally needed because the index is disposable (drop it and reindex on the older binary). A basic schema-reverse path for the rare in-place-downgrade case is tracked as a v1.1 item (SYN-105). Until then: to downgrade, check out the older syn, delete .synapse/index.db, and reindex.

Synapse: the semantic models

In one line: the local embedding and NER models download only with your consent. Once the required files are cached and local backends are selected, those inference paths work offline. Explicit hosted providers and other external integrations have separate network behavior.

The default binary ships the semantic layer compiled in (opt-out, ADR-008 §SYN-168), but the model weights are not bundled. This page is the single source of truth for what gets downloaded, from where, to where, how big, and what it means for privacy, licensing, and compatibility.

Which models

Two models, two jobs. Both run locally on CPU via a statically-linked ONNX Runtime: no GPU, no Python, no separate runtime install.

Total default footprint: ~2.5 GB (one-time download, shared across every workspace on the machine). The binary itself only grows ~25 MB (the ONNX Runtime).

Quality vs speed: the embedding profile (SYN-237)

The default bge-m3 is fp32: maximum recall, ~2.2 GB. The same model quantised to int8 is a lighter, faster, lower-memory alternative at a small recall cost. The guided syn init asks which you want (Quality is the recommended default); you can also set it directly:

Both are multilingual and 1024-dim (the same vector space) so switching is just a re-embed (syn embed --all), never a schema change. With bge-m3-int8 + gliner-multi, the multilingual footprint drops to ~900 MB.

Lighter, English-only opt-downs

Set these in .synapse/config.toml ([enrichment]) if multilingual quality or disk is not worth ~2.5 GB to you:

English opt-down total: ~325 MB. See CONFIGURATION.md for the exact [enrichment] keys.

¹ Licenses are the upstream model-card licenses at time of writing: verify them on the linked model card for your use case; you (not Synapse) are responsible for complying with each model’s terms. ONNX Runtime is MIT-licensed.

Where the models come from

Both models are fetched over HTTPS from the Hugging Face Hub (huggingface.co / its CDN):

• Embeddings: the fastembed crate resolves BGE-M3 to its Hugging Face repo and downloads the ONNX file + tokenizer.
• NER: Synapse calls the Hugging Face hub client (hf-hub) directly for onnx/model_quantized.onnx + tokenizer.json from the repo above.

The fetch is anonymous: no Hugging Face account or token is needed for these public repos. As with any HTTPS request, Hugging Face’s servers see your IP address and a user-agent for the duration of the download; no information about your workspace, notes, or queries is ever sent: Synapse only issues GETs for model files.

Both transports use rustls (not system OpenSSL), so musl/Alpine and minimal containers work without extra system libraries.

Where they’re cached

Downloads land in a per-OS cache directory and are reused across every workspace on the machine (sharing is intentional: you download BGE-M3 once, not once per brain):

Inside it: …/models/fastembed/… (embeddings) and …/models/gliner/<repo>/… (NER). A small .synapse-ready-<model> sentinel marks a model as fully downloaded; that file is how a write or search knows the model is present without trying to fetch it (SYN-168).

Override the location (precedence: config → env):

# .synapse/config.toml  (or any config layer)
[enrichment]
model_cache_dir = "/data/synapse-models"

SYNAPSE_MODEL_CACHE=/data/synapse-models syn embed --all

Point both at the same shared path (e.g. an NFS mount or a team image) to provision a fleet from one download.

When they download (consent, never ambush)

The models are pulled only on an explicit action: never silently on your first syn project add:

1. syn init onboarding: on an interactive terminal, a fresh syn init asks “Download the models now? [Y/n]”. Decline and it explains exactly what you keep and lose; you can change your mind later.
2. syn embed --all: the explicit “turn it on now” command; downloads on first run, then embeds the whole workspace.

Until a model is present, Synapse degrades gracefully: writes still save (without embeddings), and syn search falls back to fast keyword (FTS5) + graph. Check the state any time; this command is read-only and never triggers a download:

syn embed --check        # … models_ready: false  → not downloaded yet

Offline & air-gapped use

With the required model files cached and a local backend selected, embedding and NER inference run on device without sending note/query text to a model provider. Changing models or explicitly refreshing an incomplete cache can require another consented download.

This scope covers the local model path. Explicit hosted providers, remote source adapters and an external MCP client or host have separate network behavior. An air-gapped deployment must select local providers and configure those other paths accordingly.

For machines that must never reach huggingface.co:

• Pre-seed the cache. Download the models on a connected machine, then copy the cache directory (see table above) to the target, or point SYNAPSE_MODEL_CACHE at a pre-populated shared path. The .synapse-ready-* sentinels travel with it.
• Run without models. Set [enrichment] mode = "off" (or SYNAPSE_ENRICHMENT_MODE=off per command) to skip the pipeline entirely, and use syn search --no-vector for keyword + graph search with zero model load.

Enrichment is one-way: reindex drops inferred links (SYN-271)

Enrichment edges (the inferred mentions / references graph links and the vector embeddings) are produced at write time, not by reindex. reindex rebuilds the deterministic projection of your Markdown (entities, tags, structural links from frontmatter); it does not re-run the linker or the models. Two consequences:

• A reindex --full (a from-scratch rebuild) drops the inferred mentions / references edges until they are re-derived.
• Entities created before you downloaded the models have fewer inferred links than those created after.

This is a disposability property, not an integrity problem: syn verify deliberately excludes enrichment edges from its canonical dump (they are model/heuristic-derived, not a pure function of reindex(markdown)), so a rebuilt index still verifies clean.

To restore the heuristic inferred links (slug / @mention / URL: deterministic, model-free, offline) after a --full rebuild:

syn reindex --relink      # re-derive mentions / references edges; never re-runs NER, never creates entities

--relink is idempotent and queues no proposals: it only re-creates links to entities that already exist. The NER-derived mentions:<kind> edges come back on the next write of each entity (or a re-embed), since they need the model.

What touches the network (and what never does)

Local inference is the default (BR-13). Under that model path, Synapse does not send your note, entity or query text to an embedding provider. This is a boundary of local model execution, not a blanket promise about hosted backends, configured remote source adapters or the application consuming MCP results. Synapse has no built-in telemetry.

The hosted backends (network_backends feature: OpenAI / Voyage) are opt-in and require an explicit [enrichment] provider. Enabling one sends text to that provider when the configured embedding operation runs, including supported writes and semantic queries. syn init warns when a network provider is active. See IDENTITY.md and CONFIGURATION.md for configuration and egress details.

Compatibility

• CPU-only. The models run on the CPU via ONNX Runtime; no GPU or CUDA is required or used.
• Platforms. macOS (Apple Silicon only: the ONNX Runtime has no Intel-macOS build, so x86_64-apple-darwin is unsupported; ROADMAP SYN-174), Linux (x86_64 + aarch64), Windows (x86_64).
• Linux glibc ≥ 2.38. The prebuilt ONNX Runtime that ships with the semantic layer is linked against glibc ≥ 2.38 and GCC 13+ libstdc++. Practically: Ubuntu 24.04+, Debian 13 (Trixie)+, Fedora 39+ and equivalents. Older distros (Ubuntu 20.04/22.04, Debian 12) lack the symbols (__isoc23_strtol, __cxa_call_terminate) and the binary will not run there: build a core binary (--no-default-features --features mcp) for those, or upgrade the base. (This is also why the release pipeline builds the Linux artifacts on ubuntu-24.04 runners: SYN-168.)
• Disk. Budget ~2.5 GB for the multilingual defaults (~325 MB for the English opt-downs) in the cache directory, plus ~25 MB in the binary.
• First use and latency. Download time depends on the selected models, cache and connection. Inference time depends on hardware, text length and batch size. Measure the chosen configuration before setting a latency target.

Managing the cache

syn embed --check          # cache state (read-only; models_ready flag)
syn embed --all            # download (if needed) + embed everything; idempotent
syn embed --reset-cache    # drop every vector + meta row (forces a clean re-embed)

Switching models. Change embedding_model / ner_model in .synapse/config.toml, then syn embed --all: it re-embeds only the rows whose stored model id no longer matches. To reclaim disk from a model you no longer use, delete its sub-directory under the model cache (see table) by hand; Synapse never deletes downloaded weights on its own.

See also

• INSTALL.md: feature flags, opting out, the footprint table.
• CONFIGURATION.md: the [enrichment] block, cache-path override, env vars.
• ADR-008: why BGE-M3 + GLiNER + sqlite-vec, and the opt-out amendment.
• IDENTITY.md: the opt-in hosted providers and their privacy trade-off.

Synapse: onboarding: from install to your first answer

The linear path: what you run, in order, and exactly what you’ll see, from a freshly-installed syn to a workspace your AI can reason about. In a hurry? QUICKSTART is the same journey as a six-command cheat-sheet. Going deep on the AI loop? That’s TUTORIAL.

Prerequisite: syn is on your PATH. If not, INSTALL.md is one paragraph (and notes the Linux glibc ≥ 2.38 requirement for semantic search).

Step 1: Guided setup: language, defaults & who you are (syn setup)

syn setup writes your global config once per machine. As of v0.6 it is guided: after locale + output format it captures a short self-profile (name, birthdate (optional), profession, employers) saved to a global profile.toml (separate from config.toml). Press Enter to accept a default or skip an optional field:

$ syn setup
   ◉───◉
   │ ╲ │
   ◉───◉───◉
       │ ╱
       ◉

locale [en-US]:                          ← your language: en, pt-BR, es-MX, …
output format [text|json] [text]:
Full name:                               Ada Lovelace
Birthdate (YYYY-MM-DD) [skip]:           1815-12-10
Profession / headline [skip]:            Mathematician
Employers (comma-separated) [skip]:      Analytical Engine Co.
✓ identity saved for Ada Lovelace → ~/.../synapse/profile.toml

Language precedence is --lang > SYNAPSE_LANG > system locale > en. The profile is captured once and seeded into every workspace as your self person (Step 5): “capture once, seed everywhere” (BR-14, ADR-020).

Compulsory on a fresh interactive run, never blocking otherwise (BR-14.1). syn init runs this guided setup inline the first time on a TTY. In a non-interactive context (CI, pipe, --no-input, SYNAPSE_AGENT) it falls back to silent defaults and skips identity: automation never waits on a prompt. Override the profile path with SYNAPSE_PROFILE.

Step 2: Create your first workspace (syn init)

A workspace keeps current knowledge in Markdown with operational metadata beside it. Create one:

$ syn init ~/brain
workspace initialised at /Users/you/brain
seeded manifest /Users/you/brain/SYNAPSE.md
registered in workspace registry (id: brain-a1b2c3)

What just happened:

• the canonical folders (projects/ people/ entities/ apis/ tasks/ notes/) and the .synapse/ metadata directory were created. The search projection is rebuildable; the whole directory is not a disposable cache;
• SYNAPSE.md: the workspace’s identity card: was seeded. Its name defaults to the folder name (brain); open it and replace the “Describe what this workspace is about…” brief with one concrete paragraph. That text is what the AI reads to route questions across workspaces;
• the workspace was registered so federation and syn ws can find it. It starts private and non-shareable: nothing is shared until you opt in.

Keep .synapse/ with the selected workspace backup. It can hold configuration, pending proposals/review guards, durable transaction recovery data, retained source images, receipts and signing/trust policy. Markdown can rebuild derived retrieval data, but cannot recreate lost pending rows or missing historical evidence. Signing keys may use separately configured paths and need their own preservation policy. See architecture before removing an index or metadata directory.

(Messages appear in your configured language: the example above is en; on pt-BR you’d see “workspace inicializado em …”.)

Step 3: The semantic models (one-time, with your consent)

Right after syn init, on a fresh interactive setup, Synapse asks once whether to download the on-device search models:

Semantic search is built in: Synapse can find notes by meaning (not just
keywords) and grow the graph from people/tools it spots in your text. It
needs a one-time ~2.5 GB model download (cached, shared across every
workspace on this machine).
Download the models now? [Y/n]

• Yes → downloads ~2.5 GB once (shared across all your workspaces), then meaning-search is live.
• No / skip → Synapse runs as a keyword + graph brain. You keep syn search, syn graph, links, MCP: everything except meaning-search and automatic entity discovery. Turn it on any time with syn embed --all.

Either way nothing blocks, and nothing downloads silently. Check the state: read-only, never triggers a download:

$ syn embed --check
entities                0
embedded_total          0
models_ready            false      ← not downloaded yet

Footprint, cache location, offline/air-gapped use, privacy and licenses: MODELS.md.

Step 4: Capture what’s in your head

syn project add "Client Alpha" --status active
syn person  add "Maria Silva" --email maria@company.com --job-title "Tech Lead"
syn person  link maria-silva --project client-alpha --role focal
syn note    add "Why we picked PKCE" --kind decision --project client-alpha --tag auth

Each prints what it created (project "Client Alpha" created (id: client-alpha)). Slugs derive automatically; the YAML on disk is plain and hand-editable. In an acknowledged governed workspace, external edits require explicit reconciliation; reindexing does not approve them. A person exists once and is referenced by every project they touch.

Step 5: Your identity & CV

Synapse can carry a portable, signed record of your work across employers. The anchor is one person entity that represents you, flagged self: true. As of v0.6 you don’t create it by hand: if you completed the guided setup (Step 1), syn init already seeded this self person into the workspace from your global profile (name, birthdate, headline, and your employers as linked entity(kind=org) nodes). Confirm with:

syn person show <your-slug>   # self: true, birthdate, headline, affiliations

No profile yet (e.g. a non-interactive install)? Run syn setup to capture it: the next syn init seeds the self person. Or set self: true by hand on the entity that represents you. (cv/identity export will tell you to do exactly this if no self person exists.)

With your self person in place:

syn identity keygen          # ed25519 keypair for signing the bundle
syn experience add "Tech Lead, Payments" --target project/client-alpha --role tech-lead
syn cv export                # deterministic Markdown CV from the graph

“Who you are” is captured once by the guided syn setup (name, birthdate, profession, employers → global profile.toml) and seeded as exactly one self person per workspace on syn init (BR-14 / SYN-171/172). cv/identity export require that single self person and point you at syn setup if it’s missing. See IDENTITY.md.

Step 6: Search it, and hand it to your AI

syn search alpha                      # keyword (FTS5): fast, exact-term
syn search "the payments decision"    # hybrid (if models are on): matches meaning
syn graph project client-alpha        # walk the links
syn mcp                               # expose the workspace to Claude Code over stdio

Point Claude Code at the workspace so it can retrieve your recorded facts and their context. Check its citations and conclusions; access to stored knowledge does not guarantee a correct answer. The full human + AI loop (propose/accept/audit, federation and freshness) is TUTORIAL.md.

You’re set

If something looks off, syn doctor is always your first stop.

Synapse: provable non-corruption

Provable, not estimated.

For evaluators and adopters: this is the long-form argument behind one line in the README: that Synapse can prove specific non-corruption properties of an AI’s memory, offline, from your own git, rather than estimate them with a benchmark. It cites the command (syn verify) and the decisions (ADR-035/036/037) that make the claim true, and it states: plainly, > where the proof stops. The honesty is the point: a tool that says “tamper-evident, not tamper-proof” is worth more than one that hand-waves “cryptographically secure.”

Current implementation boundary (2026-10-12)

At 3ceddd0, verification covers the documented deterministic projection, not universal knowledge correctness. INV-5 validates declared supersession closure; it does not detect every unrecorded historical edit. INV-13 checks overlapping intervals, cycles and inverted intervals, not general prose contradiction. INV-8 is Skip because receipts are export-on-demand; a basic report permits skipped checks and can be unsigned if no key is available. ADR-034 reports commit signature presence; cryptographic commit/allowlist verification remains SYN-261.

The trust ladder below describes architectural assurance goals; L4 is not fully enforced in the current build. ADR-051, ADR-052 and ADR-053 record the extension path, with implementation issues. These designs do not add runtime guarantees by themselves.

1. The problem: AI memory drifts silently

An assistant with long-term memory accumulates facts. Over a long enough horizon, some of those facts get silently overwritten, contradicted, or mangled, and the failure is invisible, because the memory keeps answering confidently. The field’s published answer to this is better auto-correction plus judge-scored benchmarks: run a suite, have an LLM grade whether the memory stayed coherent, report a percentage. (HaluMem, for instance, measured auto-update correctness below 26%.)

A judge score is an estimate. It tells you, probabilistically, that memory tended to stay correct on a sample. It cannot hand you a specific, checkable guarantee about your workspace right now, it depends on a model’s judgement, and it cannot be reproduced bit-for-bit by a skeptical third party.

2. The thesis: prove three integrity classes, offline, per-fact

Every integrity system in the literature proves one of three things:

• (A) Content integrity: this artifact is the one that was attested (a hash or signature over the bytes).
• (B) History integrity: the append-only log was not reordered, truncated, or rewritten (a consistency proof).
• (C) Derived-state integrity: the output was reproducibly derived from the input (a deterministic rebuild).

Synapse is structurally positioned to prove all three at once, offline, per fact: because the truth is your Markdown in your git, and the SQLite index is a pure function of it. That last property is the whole game: the index is a reproducible build of your files. Delete it, rebuild it, and you must get the same logical state back; if you don’t, something is wrong and the tool can say exactly which fact diverged.

This user-held source makes independent rebuild checks practical. A hosted or self-hosted system can adopt equivalent evidence mechanisms using exported sources, snapshots, authenticated logs and deterministic projections; Markdown is a useful implementation choice, not an exclusive prerequisite.

3. The mechanism: syn verify

syn verify assembles primitives Synapse already ships (audit verify + reindex + at/--as-of) and reframes them as proofs, each contributing one line to a signed, reproducible report. The same core::verify::run backs both doors: the CLI command and the MCP verify tool (docs/COMMANDS.md, docs/MCP.md).

The canonical dump (ADR-035). A raw .db is not byte-deterministic: rowids, FTS internals, and float vectors vary run to run. So verify never hashes the database file. It computes a canonical logical manifest: ordered rows, with the non-reproducible surface (FTS, pending queue, reindex ledger, vectors, mentions:* enrichment) excluded or pinned to model@precision. That manifest is byte-stable across calls and across a reindex --full: that stability is the foundation everything else stands on.

The invariants checked on a default run:

Opt-in deepenings:

• --deep adds INV-4 (replay determinism): replaying the accepted-decision journal in a scratch index is deterministic. (See §5 on why this is framed as determinism, not store reconstruction: that distinction is deliberate and honest.) It also adds INV-13 (logical coherence, SYN-316): a deterministic, model-free sweep for contradictory facts (overlapping valid-time values for one field, supersession cycles, inverted intervals). This is the one check that catches a corruption introduced by a direct Markdown edit that bypasses the gate: INV-1 proves the index is a faithful build of the Markdown, but if the Markdown itself was hand-edited into a contradiction, only INV-13 sees it.
• --rebuild makes INV-1 diffoscope-style: on a mismatch it doesn’t just say “diverged,” it names every diverging fact. “Your memory is a reproducible build of your files, and if it isn’t, here is exactly which fact broke.”
• --since <witness> adds INV-12 (offline consistency): it proves your audit history is an append-only extension of a previously published witness, using git ancestry + segment-prefix stability, with no remote and no network (ADR-037).

The proof artifact. A signed synapse.verify-report/1, shaped like an in-toto Statement: {subject:{workspace, git_ref, inputs_hash}, predicate:{tool_version, invariants:[{id,status,evidence}], checkpoint, witness_status, ts}, sig, pubkey}. When an identity key is available, it is signed with the existing ed25519 identity (reusing the SYN-247 receipt path); otherwise signature/public_key remain absent. It is reproducible: anyone with your repo at git_ref re-runs syn verify and gets a bit-identical inputs_hash and the same verdicts.

Two further integrity properties (port parity (CLI ≡ MCP for every read) and temporal correctness (at <ref> -- search --as-of reconstructs the state that held)) are proven by the differential and property-based test suites (SYN-264/265), not as lines in the per-workspace report. They are invariants of the build, checked in CI, rather than of your workspace at verify time.

4. The ladder: L1 → L4

A workspace earns a higher rung as its trust root strengthens. The ladder is framing for “how strong is this proof,” borrowed in spirit from SLSA; it is not a network service:

• L1: Audited. Append-only audit trail exists; decisions are recorded.
• L2: Hash-chained. The trail is self-chained and an ed25519 checkpoint is signed; local tampering is evident.
• L3: Git-witnessed. The workspace is versioned; integrity rides git’s Merkle DAG and a published witness can catch a history rewrite (--since).
• L4: Signed-identity (target). Genuine signature validation against known, non-revoked identities would attest authorship (ADR-030). ADR-034 only ships posture; SYN-261 and ADR-053 track enforcement.

5. The honest ceiling

A proof you can trust is a proof that states its own limits. Synapse’s are written into the ADRs, not buried:

• Tamper-evident, not tamper-proof (ADR-037). A lone local clone cannot detect its own owner’s rewrite: there is no witness to contradict a history that was rewritten and re-signed end to end. syn verify therefore prints its trust root: local-only, checkpoint-witnessed, or remote/published-witness. A tracked remote, or a published syn audit witness, is what lets a third party hold the owner to their history. This is exactly where competitors say “cryptographically secure” and stop; Synapse says where the evidence ends.

• Replay is determinism, not store reconstruction (ADR-036). It is tempting to claim “replay the audit log and you get the store back.” For a state-based, hand-editable Markdown store with a hash-only log and a wall-clock, that reconstruction is unsound, and ADR-036 says so explicitly. So INV-4 proves the weaker, true thing: replay is deterministic (pinned via a clock seam), and reconstruction of state is the job of INV-1/INV-7 (rebuild from the files), not of replay. verify --deep is a bounded journal-integrity check, not a store-from-log rebuild. Stating this is what keeps the keystone claim (INV-1) credible.

• Canonicalisation is the one real prerequisite. Because the database isn’t byte-deterministic, the entire argument rests on the canonical logical manifest (ADR-035) being stable and complete. That is a property to keep tested, not assume.

• Current local baseline. No mandatory Rekor/Fulcio, OIDC or Trillian witness-net, no runtime model-checker, no RDF/OWL, no IPFS/CID. Synapse adopts the proofs from that literature (Merkle DAG, consistency proofs, reproducible-build comparison, in-toto attestation shape) and runs them over git and ed25519 it already has: offline, dependency-light, deterministic over ML.