How do I install Synapse?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Synapse need an API key?

No required environment variable is listed on this record.

What transport does Synapse use?

Synapse runs locally over stdio.

When was Synapse last checked?

Last checked 2026-10-28. Shared local memory and skills for Claude Code, Codex, pi, and Ainz. macOS desktop app; Linux terminal dashboard, CLI, and MCP server.

Servidor MCP Synapse

Synapse

Shared memory and skills for Claude Code, Codex, pi, and Ainz.

Stop repeating the same project conventions to each coding agent. With Synapse, you can save a correction in one tool and recall it in another, in the same project. Keep your memory on your machine and manage reusable skills in one library.

Download for macOS · Windows installer · Linux setup · Try a handoff · Documentation

macOS desktop (Apple silicon, macOS 13+, signed and notarized) · Windows desktop (x64 installer) · CLI and MCP server · MIT license · No account required

The macOS app checks for signed releases when it opens and hourly while it is running. Use Synapse → Check for Updates… at any time. If a document has unsaved changes, Synapse installs the update but waits until the next normal launch instead of forcing a restart.

Supported harnesses

A harness is the coding agent you run. Synapse ships these connectors:

Harness	Command	Connection	Extra integration
Claude Code	`claude`	MCP	Session hooks and status line
Codex	`codex`	MCP	Respects `CODEX_HOME`
pi	`pi`	`synapse-pi` extension	Session integration; no native MCP client needed
Ainz	`ainz`	MCP	Registers Synapse as a required server

All four have descriptors for shared guidance, skill locations, and launch arguments. Run synapse tool list to see built-in and custom harnesses, then synapse connect <name> to connect one installed on your machine.

Add your own harness

You can add a harness without rebuilding Synapse or waiting for a release. From your repository root:

synapse tool create mytool
synapse tool show mytool
synapse connect mytool

The first command opens a commented TOML template in your editor and validates it before saving .synapse/tools/mytool.toml. Fill in your harness's executable, configuration and instruction paths, MCP registration commands, and launch flags. Restart the harness after connecting, then ask it to save and recall a project convention.

Use synapse tool create mytool --user for a personal connector available across projects. Project descriptors override user descriptors, which override built-ins. Run project commands from the repository root. .synapse.yaml remains the project credential-scope configuration; harness definitions live in .synapse/tools/.

Custom harness guide and example. Support for hooks or a non-MCP protocol may require an adapter in addition to a descriptor.

Contribute a harness

PRs for additional harnesses are welcome. Start with a working custom descriptor, then add it to crates/synapsecore/assets/tools/ and register it in BUILTINS in agent/tool.rs. Include the harness version and platforms you tested, coverage for connection detection and cleanup, and an update to this table. See the contribution checklist.

Save a correction. Recall it in another agent.

An example with two connected tools in the same repository:

You → Codex
  Use Bun for JavaScript tasks in this repo.
  Remember that convention for this project.

Synapse
  Stores the confirmed convention in local project memory.

You → Claude Code, in a new session
  Recall this project's tooling convention.
  How do I install dependencies?

Claude Code, using the recalled convention
  bun install

You choose which decisions to keep. Connected agents can recall those decisions across sessions; project-scoped recall includes global guidance and that project's memory. Synapse shares saved context, not the full conversation. An agent still needs to consult memory and follow it.

Walk through this example, including how to inspect the saved record, correct it, and check its project scope.

Try it with your tools

On macOS:

Download the app, extract it, and move synapse.app into Applications.
Open Synapse and choose Connect for the tools you use: Claude Code, Codex, pi, or Ainz. For Ainz, this also enables its native shared-memory integration; running ainz synapse connect from Ainz performs the same reciprocal handshake.
Restart those tools so they load the connection and shared guidance.
Ask one tool to remember a confirmed project convention. Open another in the same folder and ask it to recall that convention.
Inspect the record in Synapse's Memories screen.

On Windows, build and run the per-user installer with packaging/windows/build.ps1. It includes the desktop app and the CLI. See Windows build and verification.

On Linux, build the CLI from the repository root with a current stable Rust toolchain and a C compiler/linker:

cargo build --release --locked --manifest-path crates/synapsecore/Cargo.toml
./crates/synapsecore/target/release/synapse-cli install
export PATH="$HOME/.local/bin:$PATH"
synapse connect
synapse

synapse connect connects installed tools. Restart them afterward. Use synapse status for text status; the same binary provides the CLI and MCP server. The Linux build has no desktop UI dependency and uses the encrypted vault instead of macOS Keychain. Release downloads contain the macOS app and Windows installer; Linux users build from source.

See the installation guide for CLI setup and connection troubleshooting.

What you can share

Capability	How you use it
Project memory	Save decisions, corrections, and conventions. Recall them in a later session or another connected agent, from any clone or worktree of the same repository. Credentials are stripped before anything is stored.
Existing memory	Preview and import Claude and Codex memory without changing the originals. Undo an import batch when needed.
Project Knowledge	Opt into repository Markdown guides for architecture, stack, database, and testing. Connected agents create and refresh them when asked; Synapse shares a compact index and flags changed sources. See Project Knowledge.
Shared guidance	Edit one `SOUL.md` and point your connected tools at it.
Agent Skills	Maintain one library, install skills into connected tools, and check which copies have drifted.
MCP servers	Keep one list of MCP servers and give it to every connected tool, with each token in the vault instead of in plaintext in every tool's config.
Plugins and Scenes	Watch connected sessions as characters in their own pixel-art workshop rooms. Initialize, validate, and install local scene packs with `synapse plugin`, then find Scenes under Plugins in the app. See Scenes and plugins.
Agent coordination	Enable the optional mesh to let agents message each other and work together. Join them yourself with `synapse mux`.
Scoped credentials	Approve which project folders may receive which environment variables, using the local encrypted vault or macOS Keychain.
The Map	See every memory as a graph in three dimensions — projects as clusters, a correction as a line to what it replaced, and a memory nothing else touches looking like one.

Search, edit, export, restore, or delete stored memory from the app. Search matches words in any form and fragments of identifiers, so deploying finds "deploys" and hashpw finds scripts/hashpw.sh. Supersede a decision when it changes: future recall returns the current version, and you can still inspect or restore the old one. synapse memory eval scores recall against questions you write down, so a change to what you store can be measured instead of guessed.

One skill library

Claude Code, Codex, pi, and Ainz all read the Agent Skills format, each from its own folder. Synapse keeps one copy and installs it into each:

synapse skill list                # what is in your library
synapse skill adopt humanize      # bring in a skill a tool already has
synapse skill create my-workflow  # start a new one
synapse skill install             # copy them all into every connected tool
synapse skill status              # where each one is, and what has drifted

Editing a skill in the library marks the installed copies as out of date; install brings them back in step. A skill Synapse did not put there is left alone.

A procedure that is really about one repository belongs to it rather than to every session on the machine:

synapse skill create release --project   # this repository's own
synapse skill install release --project  # into its .claude/skills, not your home

Letting agents improve themselves

Turn it on and a session can write down a procedure it worked out, and correct one that turned out wrong:

synapse settings learn on
synapse skill proposed            # what agents wrote and nobody has looked at
synapse skill approve cut-a-release
synapse skill history cut-a-release   # what it used to say
synapse skill revert cut-a-release    # and back again

Or bring in one somebody else published. It arrives waiting for review, the same as one an agent wrote:

synapse skill search release notes
synapse skill get phuryn/pm-skills/release-notes

The gate is on installing rather than on writing. A taught skill sits in the library and in no tool until you approve it, so writing one costs you a line in a list rather than context in every session on the machine. Corrections are the deliberate exception: they reach the copies Synapse installed, because you already agreed to that skill being loaded and a correction that never arrives leaves every session running the version that was wrong. Nothing it replaces is lost.

Working as a team

Turn the mesh on in Settings → Agent mesh, or from the terminal:

synapse settings mesh on
synapse relay team open web      # a lead in this terminal, its team in the background
synapse relay agents             # who is on the mesh and what they are doing
synapse relay feed --follow      # watch them talk

Each agent launches with a role — a durable brief describing what it owns. The built-in roles cover the usual shape of a team, and synapse relay role create <name> writes your own into the project so it travels with the checkout.

Most jobs do not want four agents, and picking a roster before you understand the job is its own small chore. The overseer team is one agent that grows its own:

synapse mux --team overseer

@overseer get the release notes written and the changelog updated

You are on the roster yourself either way, so nothing is interposed: any worker it starts is directly addressable without going through it.

MCP servers

Describe a server once and every connected tool gets it. What a tool is handed is synapse mcp run <name>, which reads the library, fetches the secrets from the vault, and replaces itself with the real server, so no token sits in any tool's config:

synapse mcp add github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
synapse mcp secret github GITHUB_PERSONAL_ACCESS_TOKEN   # prompted, stored in the vault
synapse mcp install github                              # Claude Code, Codex, Ainz

A server a tool already has can be adopted, its values moved into the vault, and the tool's own entry swapped for the library's:

synapse mcp adopt github --tool claude
synapse mcp install github --tool claude --replace

synapse mcp search finds servers in the official MCP Registry. The app's MCP screen does all of this, with Installed and Search tabs.

Both searches ask every source at once: skills.sh and the MCP Registry are built in, and a team's own GitHub repository of skills and server.json files is one command away. A repository can carry .synapse/sources.toml, which is searched only once its exact contents are approved:

synapse source add team acme/agent-skills --token work.github
synapse skill get team:skills/release-notes
synapse source allow          # approve this project's sources file

Using pi

pi has no MCP client, so it reaches Synapse through a package instead:

synapse connect pi               # or, from pi's side: pi install npm:synapse-pi
synapse launch pi                # one session with memory, the vault, and the mesh

Everything a connection means elsewhere arrives with that package: the tools, this project's memory before the first turn, a status line, /synapse, /recall, /remember, and /mesh. The source is in pi/.

Learn more

Website

The manual includes every technical document in docs/. Use Bun 1.4.3 or later, run bun run site and bun run sitecheck, then bun run serve to preview http://127.0.0.1:4173/synapse/. Commit the regenerated site/ with its sources. The Pages workflow rebuilds and publishes on main. See the development guide for the workspace gates.

Synapse

Adicionar este servidor

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Synapse?

Does Synapse need an API key?

What transport does Synapse use?

When was Synapse last checked?

Documentation

Synapse

Supported harnesses

Add your own harness

Contribute a harness

Save a correction. Recall it in another agent.

Try it with your tools

What you can share

One skill library

Letting agents improve themselves

Working as a team

MCP servers

Using pi

Learn more

Website