Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.