Check, migrate, and remove Synapse

Outcome and prerequisites

You will produce the report to attach to a bug, verify the store's integrity and schema version, understand what happens when a release changes the schema, and then walk both removal paths — one tool, and everything — reading what each will do before it does it.

• The synapse CLI installed and at least one tool connected.
• Export and restore safely read first. This tutorial assumes you know how to take a snapshot; the removal steps are more comfortable when you have one.

1. Get the whole picture in one command

   shell Copy

   synapse doctor

   text Copy

   Synapse 0.1.0-beta.24
   
   Store
     State          ok
     Schema         v10
     Memories       0
     Size           0 MB
     Backups        0
     Recall budget  balanced
   
   Connected tools
     Claude Code    installed, not connected
       version      2.1.241 (Claude Code)
       guidance     no
       notice       no
       compaction   no
       status line  none
     Codex          installed, not connected
       version      codex-cli 0.147.0
       guidance     no
       notice       no
       compaction   no
       status line  none
     pi             not installed
   
   Skills
     In the library 1
     Installed      0
     Out of date    0
     Agents write   no

   This is what to attach to a bug report. It answers most first questions without a round trip: which version, whether the store is sound, what schema it is on, whether each tool is actually connected rather than merely installed, and whether the guidance pointer, session notice, and status line are in place.

   --json gives the same thing structured. Note what is not here: no memory contents, no secret names, no file paths outside Synapse's own. A doctor report is safe to paste into a public issue.

   Read the tool rows carefully. installed, not connected means the tool is on the machine but has no Synapse entry. Agents write under Skills is whether self-improvement is on, and a count of anything waiting for you appears under it when there is any. A tool that was connected and whose executable later moved reports as stale rather than healthy, because detection resolves the stored command rather than trusting the entry exists.

2. Check the store itself

   shell Copy

   synapse data check
   synapse data check --json

   text Copy

   {
     "path": "~/Library/Application Support/synapse/brain.db",
     "version": 7,
     "integrity": "ok"
   }

   Two different checks run when the database opens, with very different costs. A relationship check is index-driven and runs every single time. A full page-by-page scan reads the whole file, so it runs once per process against an unchanged file — which is why a status line redrawing on every turn stays cheap while data check is thorough.

   integrity: ok means both passed. Anything else is reported rather than worked around, and restoring a snapshot is the answer.

3. Understand what a migration does

   Schema v7 in the report above is the store's version. Each release that changes the schema adds a numbered migration and raises that number. Opening the database applies any that are missing, in order.

   Three things are true of every migration and worth knowing before you upgrade:

   • A backup is taken first. Before any migration runs against an existing store, Synapse copies it into the backups folder. If a migration fails, that copy is what you restore.
   • Shipped migrations are never edited. A release only ever appends. That is what makes the upgrade path from any older version deterministic rather than dependent on which releases you happened to install.
   • A newer store refuses an older binary. If the database reports a version this release does not know about, Synapse says so and stops rather than guessing at a schema from the future.
   shell Copy

   ls ~/Library/Application\ Support/synapse/backups/

   Backups are bounded — only the newest few are kept — so the folder cannot grow without limit. The same rule applies everywhere Synapse writes something unbounded: worker logs and the crash log keep their tail rather than the whole history.

4. Disconnect one tool

   Disconnecting undoes one tool's integration and nothing else:

   shell Copy

   synapse disconnect claude

   text Copy

   Removed Claude Code skill `synapse-mesh`
   warning: Claude Code skill `release-checklist`: `release-checklist` in Claude Code has been changed since Synapse installed it

   Read that second line closely, because it is the whole design in one sentence. Synapse removed the skill it had written and left untouched. It refused to remove the one that had been edited since — because at that point the file is partly yours, and Synapse will not delete work it cannot prove is its own.

   The same run also asks the tool's own CLI to forget the MCP server, strips the managed block from its instruction file while leaving your text in place, and removes the session hook and status line from its settings — but only if they are the ones Synapse wrote. A status line you configured yourself is reported and left alone.

   Every step reports rather than aborts. A disconnect that stopped at the first problem would leave the tool half-connected, which is the worst available outcome; finishing and telling you what it could not do is better.

   shell Copy

   synapse disconnect

   With no tool named, it disconnects every one.

5. Read the uninstall preview

   Run it without --confirm first. It always previews:

   shell Copy

   synapse uninstall

   text Copy

   `synapse uninstall --confirm` would remove:
     · every skill Synapse installed, leaving any you wrote
   
   Your memory in ~/Library/Application Support/synapse would be left alone.
   
   Add --confirm to go ahead.

   On a fully connected machine the list is longer — the MCP entries, the managed instruction blocks, the session hook, the status line, the installed CLI, the shell startup block. The last line is the one to notice: memory is never removed as a side effect. Uninstalling the software does not delete what you have taught it.

6. Remove everything, including memory

   Taking the data folder requires asking for it by name, and the preview changes to say so:

   shell Copy

   synapse uninstall --data

   text Copy

   `synapse uninstall --confirm` would remove:
     · every skill Synapse installed, leaving any you wrote
   
   And, because --data was given, everything in ~/Library/Application Support/synapse
   including all of your memory. That cannot be undone.
   
   Add --confirm to go ahead.

   Two flags, both required, and a sentence that says it cannot be undone. If you want a copy first, synapse data export writes a consistent snapshot you can restore into a fresh install later — see Export and restore safely.

   shell Copy

   synapse data export ~/synapse-final-snapshot.db   # optional, but do it
   synapse uninstall --data --confirm

What survives

The principle behind all of this: everything Synapse writes outside its own folder, it can take back — and nothing else. After a full uninstall, these are untouched:

Next step

That is the whole maintainer track. If something in it did not behave as described, synapse doctor --json plus the exact command you ran is everything a bug report needs. See Troubleshooting for the common failures and what each one means.