MCP tool reference

Server

Synapse implements an MCP stdio server. A tool launches the same signed or installed executable with the mcp argument:

~/.local/bin/synapse mcp

The process uses stdin and stdout for protocol messages. Do not wrap it in a command that writes banners or shell setup output to stdout. The server opens the same local database as the desktop app and holds a shared lifecycle lock while connected.

Session start

Connecting Claude Code also installs a SessionStart hook that runs synapse session. It does two things a tool cannot do for itself: it prints a line in the terminal before the model has written anything, and it puts this project's memory into the session's context before the first turn. A connected pi runs the same command from its extension and shows the same two halves.

synapse session --json

{
  "systemMessage": "Synapse connected · 128 memories",
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Synapse is connected and holds 128 memories for /Users/example/project. …"
  }
}

additionalContext carries the memories themselves, most recent first, under the same scope rule recall uses: everything global, plus everything stored for this project, and nothing from any other project. A session therefore opens already holding what the project has decided, rather than being asked to go and look.

That matters because the alternative was guidance. Asking a model to call recall before it starts is an instruction it may or may not follow, and a session that skipped it worked from nothing while still reporting a connection. Guidance still asks for recall, because a focused query in the middle of a task is the case a session-start recall cannot cover.

Before compaction

The other end of the same session. When a long session is about to be compacted, everything it worked out that nobody wrote down is about to stop existing — and it is the only moment where not having written something down costs immediately. Connecting Claude Code installs a PreCompact hook that runs synapse compact; a connected pi runs the same command from session_before_compact.

synapse compact

{
  "hookSpecificOutput": {
    "hookEventName": "PreCompact",
    "additionalContext": "Synapse holds this project's durable memory, and this session is about to be compacted…"
  }
}

It asks for an explicit list of what the session settled and is not already stored, and for a remember call for each one. It deliberately recalls nothing: the context window is being reclaimed, and spending it re-injecting memory the session already had is the opposite of what a compaction is for.

The compaction itself is never blocked, cancelled, or rewritten. A memory tool that traded a session's whole context for a reminder would be a worse bargain than forgetting.

remember

Stores a durable fact, decision, preference, convention, or correction.

{
  "content": "Use small focused modules.",
  "source": "synapse",
  "scope": "project",
  "project": "/Users/example/project",
  "supersedes": [18]
}

{
  "id": 24,
  "stored": true,
  "superseded": [18]
}

The store and the replacement happen in one transaction. Without supersedes, a correction is a second memory contradicting the first, both come back from the next recall, and the ranking decides which one an agent acts on — including the version its own author had already retracted.

recall

Returns durable context relevant to a query. An empty query returns recent memory.

{
  "query": "module structure",
  "limit": 8,
  "budget": "lean",
  "project": "/Users/example/project"
}

{
  "optimization": "lean",
  "memories": [
    {
      "id": 24,
      "body": "Use small focused modules.",
      "source": "synapse",
      "scope": "project",
      "project": "/Users/example/project",
      "created": 1785250000
    }
  ]
}

Two fields appear only when they are true of the result. abridged marks a memory returned as its opening sentence alone, because the response budget could not carry the rest — recall it again with a narrower query or a larger budget before acting on the part you cannot see. superseded never appears here at all, because a replaced memory is not recalled.

vaultstatus

Lists active environment-variable names and scope trust state for a folder. It never returns secret values and cannot inject them into the connected tool.

{
  "path": "/Users/example/project"
}

path is optional. Resolution falls back to SYNAPSE_PROJECT_DIR, then the server process’s current directory.

{
  "path": "/Users/example/project",
  "backend": "encrypted",
  "available": ["DATABASE_URL"],
  "ambient": "ready",
  "shell": "zsh",
  "scopes": [
    {
      "path": "/Users/example/project/.synapse.yaml",
      "scope": "project",
      "trusted": true,
      "changed": false,
      "env": ["DATABASE_URL"],
      "denied": [],
      "error": null
    }
  ],
  "warnings": [],
  "note": "Values stay in the vault and never in a response. Use synapse run for one child or install the shell hook for an approved directory."
}

teach and revise

Two tools that appear only while synapse settings learn on is set. They are how a session writes down a procedure it worked out, and corrects one that turned out wrong. Both write to the Synapse skill library and to nothing else.

teach takes a name, a one-line description, the instructions as Markdown, a scope of project (the default) or global, the absolute project root, and a note for you saying why it was worth keeping. Synapse writes the frontmatter itself rather than accepting it, so a model never gets to invent YAML keys or a name that disagrees with its own directory. The result always says the same thing: stored, and waiting for you.

revise takes the name, the corrected instructions in full, and a note saying what was wrong with the version it replaces. It returns the revision id holding the old text and the tools the correction reached.

Mesh tools

Three tools are always present. Sixteen more appear only while the agent mesh is switched on, and two more while self-improvement is, because a tool definition costs context in every session that loads it. They let connected sessions register under a name, message each other directly or by channel, park on wait until work arrives, report and watch work state, and start or stop background workers.

The guidance explaining them is sent with them and withdrawn with them, so the tool list and the instructions can never be out of step. That is true of both switches. See the agent mesh guide for the full list and what each one is for.

Operational behavior

• Tool errors are returned as readable strings. Protocol messages remain on stdio.
• The server identifies itself as synapse using the application version and advertises tool capability only.
• Opening the database runs integrity and relationship checks, applies numbered migrations, and secures database permissions.
• A running MCP process holds a shared database lock. synapse data restore requires an exclusive lock and therefore refuses while any connected server or the desktop app is using the database.
• Connected tools should recall before decisions that depend on project history and remember only stable confirmed context after it is established. A Claude Code session starts with that memory already in context; see Session start.