Start here

Understand the Synapse model, choose a path through the guide, and know where its guarantees stop.

The model

Synapse is a local service with two deliberately separate jobs. Its memory layer gives connected developer tools one durable, searchable context store. Its vault layer gives commands or opted-in shells carefully scoped environment variables while keeping secret values sealed in a store of their own.

The desktop app is the control surface. The CLI exposes the same memory, vault, scope, settings, and data-lifecycle operations. The MCP stdio server gives connected tools three narrow capabilities: remember durable context, recall it, and inspect value-free vault status. An optional agent mesh adds a fourth job on top of the same store: letting those connected tools coordinate with each other.

What Synapse stores

Material	Location	Visible to
Memory text, source, global or project scope, origin, and import history	Local SQLite database	Desktop app, CLI, and scoped MCP memory tools
Shared working guidance	`SOUL.md` in the Synapse data directory	You and every connected tool through managed global pointers
Vault names, secret labels, account references, global mappings	`brain.db`, the local SQLite database	Desktop app and CLI; MCP receives names only
Secret values	`vault.db`, sealed under the key in `vault.key` — or macOS Keychain, if that is what the machine is set to. Never `brain.db`.	Synapse, a child launched with `synapse run`, or processes launched from an activated shell
Project and folder mappings	Approved `.synapse.yaml` files	You, Synapse, and the repository if you commit the file
Scope approvals	Local SQLite database as a path and content digest	Synapse
Mesh roster, channels, and messages between agents	Local SQLite database, while the mesh is on	Desktop app, CLI, and agents that have joined
Agent Skills library	The Synapse data directory, copied into each tool's own skills folder	You, and every tool that reads the Agent Skills format
Skills agents proposed, and what a skill used to say	Local SQLite database, while self-improvement is on	You. A proposed skill reaches no tool until you approve it
Agent roles and team rosters	TOML in the project's `.synapse` folder or the Synapse data directory	You, Synapse, and the repository if you commit them

What Synapse does not do

It does not sync memory or secrets to an account or hosted service.
It does not send secret values through MCP, write them to YAML, or accept them as command arguments.
It cannot directly modify an already-running parent process. Use synapse run -- <command> for one child, or explicitly evaluate synapse hook so your shell applies quoted environment changes itself.
It does not decide that every conversation detail deserves permanent memory. Connected tools receive instructions to keep stable, confirmed context.
It does not continuously mirror native tool stores. Imports are explicit, previewed, and reversible; new shared memory belongs in Synapse.
Synapse is a signed Apple-silicon build for macOS 13 or later.

Choose a path

I want to use Synapse now.: Follow Install and connect your first tools. It covers download, first launch, the CLI, both supported tools, and a working recall check.
I want to manage Synapse from the app.: Use the desktop app reference for every screen, status, confirmation, editor, and shell-integration control.
I want to understand memory behavior.: Read Memory and recall, then follow Carry one decision between tools.
I need credentials for local commands.: Read Vaults and scopes, then build a complete approved scope in Use a scoped secret in either shell mode.
I want my tools to work together.: Read Agent mesh. It covers turning it on, roles, teams, background workers, and what the mesh deliberately does not do.
I want to talk to my agents rather than watch them.: The app's Console puts you on the mesh under your own name. Hand a job to one agent walks through describing an outcome and letting it decide whether the work needs a team.
I keep re-deriving the same procedure.: Let a session write it down. Let your agents write skills covers what an agent may and may not do to your library, and why the gate is on installing rather than on writing.
I keep copying the same skill into every tool.: Read Skills. One library, installed into Claude Code, Codex, and pi together, with drift reported rather than silently resolved.
I need automation or exact syntax.: Use the complete CLI reference and MCP tool reference.
I am planning backups or a recovery.: Read Data lifecycle before exporting or restoring the database.