Synapse

Install and connect your first tools

Go from the signed release archive to a working local MCP connection, and verify the same memory from the desktop app, the terminal, and the coding tool itself.

Outcome and prerequisites

You will install Synapse, install its command-line tool, connect at least one coding tool, store one harmless memory, and see that same record through three separate surfaces. By the end you will also know exactly which files were touched and how to take every one of them back.

  1. Move the app somewhere permanent, then open it

    Extract synapse.zip, move synapse.app to Applications, and open it. The app is Developer ID signed and notarized, so it opens without a security override and without a right-click workaround.

  2. Install the CLI

    Open Synapse Settings and choose Install CLI, or run the installer from inside the bundle. Either way it reports where it landed:

    text 
    Installed /Users/example/.local/bin/synapse
Add /Users/example/.local/bin to PATH to use synapse from your shell.

    Open a new terminal and confirm the shell can find it:

    shell 
    synapse version
synapse path
    text 
    synapse 0.1.0-beta.24
    text 
    data	/Users/example/Library/Application Support/synapse
soul	/Users/example/Library/Application Support/synapse/SOUL.md
cli	/Users/example/.local/bin/synapse

    If the shell cannot find synapse, add ~/.local/bin to PATH and start another shell. The data path above must match what the app reports on its Settings screen — if the two differ, something has set SYNAPSE_DATA in one context and not the other, and they are reading different stores.

  3. Connect a detected tool

    Return to the dashboard. Each supported tool appears as a row with its state. Choose Connect beside Codex, Claude Code, or pi, and the row moves from detected to connected. Connect the others too if you have them — the whole point is one memory behind all of them.

    Detection is not a guess. Synapse parses the actual entry named synapse in the tool's own configuration and reports connected only when the stored command resolves to the expected executable and its arguments are exactly ["mcp"]. A tool whose binary was deleted or moved reads as stale, not healthy.

  4. Know what connecting actually wrote

    This is worth understanding now rather than the first time something looks wrong. Connecting is not a black box — it is four specific changes, and every one is reversible.

    ChangeWhereHow it is made
    The MCP server~/.codex/config.toml or ~/.claude.jsonThrough the tool's own mcp add command, not by editing its file directly.
    A guidance pointer~/.codex/AGENTS.md or ~/.claude/CLAUDE.mdAppended inside a managed block. Your own text is untouched.
    A session hook~/.claude/settings.jsonClaude Code only. Runs synapse session at session start.
    A status line~/.claude/settings.jsonClaude Code only, and only if you do not already have one. Yours is reported, never replaced.

    Every changed file gets a .synapsebackup sibling before it is replaced, and the whole operation rolls back if any step fails. Check the shared guidance file was created:

    shell 
    synapse guidance show
    text 
    SOUL.md	/Users/example/Library/Application Support/synapse/SOUL.md
exists	true
pointers	2/2
consolidated	false

    A full count — pointers 3/3 with all three tools connected — means each one points at a single editable SOUL.md. That file is yours to edit; it is where shared guidance for every connected tool lives.

  5. Restart the tool and read its first line

    Close and reopen the connected tool so it loads the new MCP server. A running session keeps the tool list it started with, so this step is not optional.

    Claude Code will print a line beside its welcome box before the model has written anything:

    text 
    Synapse connected · no memories yet

    That line comes from the session hook, which is the only way to state the connection before the first reply. It also hands the session this project's memory directly, so a Claude Code session starts already holding what the project has decided rather than being asked to go and look. On an empty store there is nothing to hand over yet, which is what you are seeing.

    Codex has no session hook, so it reports the connection in its first reply instead, following the guidance in SOUL.md. Either way, ask the tool what Synapse tools it has. The answer should include remember, recall, and vaultstatus — three, not more. The sixteen mesh tools appear only when you switch the mesh on.

  6. Store one memory

    Tell the connected tool:

    Remember this confirmed tutorial convention: documentation examples use the source label synapsetutorial.

    It should call remember with the current project root and report a numeric ID. Use an ordinary convention for this — memory is plain text readable by every connected tool, so never put a token, password, or private key in it.

  7. Verify the same record three ways

    One store, three surfaces. Check all of them, because a mismatch here is the clearest signal that something is pointed at the wrong place.

    shell 
    synapse memory list synapsetutorial
    text 
    1	project:/Users/example/project	synapsetutorial	Documentation examples use the source label synapsetutorial.

    The columns are the ID, the scope and project it belongs to, the source label, and the body. Now the exact record:

    shell 
    synapse memory show 1
    text 
    Memory #1
Scope: project
Project: /Users/example/project
Source: synapsetutorial
Created: 1785776940

Documentation examples use the source label synapsetutorial.

    Finally, open the Memories screen in the app and search for synapsetutorial. The body, source, and scope must match what the terminal just printed. At this point the coding tool, the CLI, and the desktop app are provably reading one local database.

If something is not right

SymptomWhat it usually means
The tool lists no Synapse toolsIt was not restarted after connecting. Close it fully and reopen.
The dashboard row says staleThe app moved after the connection was made. Choose Repair.
synapse: command not found~/.local/bin is not on PATH, or the shell has not been restarted.
CLI and app show different memory countsThey are on different data directories. Compare synapse path with the app's Settings screen.
The tool reports a connection that is not thereRun synapse doctor. It reports what is actually configured rather than what should be.
shell 
synapse doctor

That one command is also what to attach to a bug report. It carries no memory contents and no secret names, so it is safe to paste into a public issue.

Undoing all of it

shell 
synapse disconnect claude     # or codex, or nothing for every tool

Disconnecting removes only what Synapse wrote: the MCP entry, the managed block in the instruction file, the session hook, and the status line — and only if that status line is the one Synapse installed. Your own words in CLAUDE.md, your own status line, and every memory survive it. Removing memory is a separate, explicit decision covered in Check, migrate, and remove Synapse.

Next step

Continue with Carry one decision between tools to prove a real handoff across a session boundary and a tool boundary.