Install and connect

Requirements

• Apple-silicon Mac running macOS 13 or later.
• At least one supported tool on PATH: Codex, Claude Code, or pi.
• A writable ~/.local/bin, or a custom path supplied through SYNAPSE_BIN.

Install the app

1. Download synapse.zip from the latest release.
2. Extract the archive and move synapse.app into Applications. Do not install the CLI while the app is still inside Downloads or a mounted disk image.
3. Open Synapse. The app is Developer ID signed and notarized by Apple, so it opens under default Gatekeeper settings with no security override.

Install the CLI

Open Settings in Synapse and choose Install CLI, or run the application binary once from a terminal and use:

synapse install
synapse path
synapse version

The default destination is ~/.local/bin/synapse. If your shell cannot find it, add that folder to PATH and start a new shell.

export PATH="$HOME/.local/bin:$PATH"

Synapse never overwrites an unrelated executable. A managed launcher has a sibling .synapsereceipt containing its digest so future installs can distinguish an update from a conflict.

Enable shell integration

In Settings → Shell environments, choose Enable shell hook. Synapse detects your default zsh, bash, or fish shell, installs the CLI if needed, and adds one marked block to its startup file. Open a new terminal after the setting changes.

The app shows Needs repair if the managed block changes. Repair replaces only that block. Remove deletes only that block; already-running terminals retain the loaded hook until they close. Every changed existing startup file receives a .synapsebackup sibling and an atomic replacement.

Connect tools

On the Synapse dashboard, each detected tool shows its installation and connection state. Choose Connect for Codex, Claude Code, or pi.

Setup performs two changes as one rollback-protected operation:

1. It registers the installed Synapse executable as a user-level MCP stdio server with the single argument mcp. pi has no MCP client, so its step is pi install npm:synapse-pi instead: one package that starts the same server and offers the same tools.
2. It creates SOUL.md when needed and appends or refreshes a small managed pointer in the tool’s global instruction file. Existing user content remains outside that block.

The connected tool follows that pointer on launch, and the MCP server loads the same SOUL.md during initialization. The default guidance tells every connected tool to recall global plus current-project context, save confirmed reusable facts with project scope by default, use a Lean response first, and keep secrets out of memory.

It also tells them to make the link visible: the first reply of a session opens with a single line such as Synapse connected · 3 memories recalled, or Synapse unavailable with a short reason when a call fails. The MCP server supplies that instruction itself, so guidance written before this behavior existed still produces the line without editing SOUL.md.

Before changing a tool store or instruction file, Synapse creates a sibling .synapsebackup. If either half of setup fails, both files are restored.

Use one shared guidance file

Open Settings → Shared guidance. Open shared guidance edits the central SOUL.md. Sync pointers creates it if needed and refreshes every global pointer while preserving every line outside Synapse's managed blocks.

If you want those global files to contain only those pointers, choose Consolidate guidance and confirm. Synapse moves their unmanaged content into SOUL.md, deduplicates simple shared rules, writes pointer-only global files, and keeps .synapsebackup siblings. This operation is never performed implicitly during connection setup.

synapse guidance show
synapse guidance sync
synapse guidance adopt --confirm

Manual connection

The app is the recommended setup path because it detects stale executable paths and repairs them. If you need to register the server manually, use the installed CLI path:

codex mcp add synapse -- ~/.local/bin/synapse mcp
claude mcp add --scope user synapse -- ~/.local/bin/synapse mcp

Then run synapse guidance sync so both global instruction files point to SOUL.md. Do not point an integration at a build artifact such as target/debug/synapse; cleaning the repository would break the connection.

Verify the connection

1. Restart the connected tool so it reloads its MCP servers and instructions.
2. Inspect its available tools. Synapse should expose remember, recall, and vaultstatus.
3. Ask it to remember one harmless confirmed convention, then recall it in a new session.
4. Open the Synapse Memories screen and confirm the exact entry and source are visible.

If the dashboard shows a registered but disconnected state, the stored path is stale or its arguments differ from ["mcp"]. Choose Repair in the app or remove and re-add the manual entry.