Memory and recall

What belongs in durable memory

Good memory remains useful after the current conversation ends. Store confirmed decisions, recurring preferences, corrected assumptions, naming conventions, project constraints, and facts whose source is clear.

Shared guidance lives in SOUL.md. Each connected tool's global instruction file contains a managed pointer to it, and the MCP server loads the same file during initialization. Both tools therefore receive the same recall, storage, scope, and token-budget policy.

Do not store transient task status, speculative ideas, full conversation transcripts, secret values, or instructions that attempt to override the current request or repository guidance. Synapse is the canonical durable memory store; it does not create separate Markdown files for individual memories.

printf '%s
' 'Use Bun for JavaScript tasks in this repository.' \
  | synapse memory add tooling

memory add and memory edit read the body from stdin. This keeps long content and shell metacharacters out of command arguments. Empty or whitespace-only memory is rejected.

Global and project scope

Project memory is the default. Synapse resolves the supplied path to its repository or approved project root and returns that memory only alongside global memory for the same project. Unrelated project memory stays out of MCP recall.

Use global scope only for preferences and conventions that should follow you everywhere. The desktop editor can move a record between scopes. The CLI accepts an explicit scope when adding:

printf '%s
' 'Use Bun in this repository.' | synapse memory add tooling --project .
printf '%s
' 'Prefer concise status updates.' | synapse memory add preferences --global

Import existing memory

The Memory screen previews Claude and Codex independently, maps each item to its project when possible, and imports safe entries into the same scoped store. Source files are read-only: Synapse never edits or deletes them.

• Claude imports leaf Markdown files from project memory directories and skips MEMORY.md indexes.
• Codex imports processed memory rows from a recognized local memory database and maps thread IDs to project roots through the local thread catalog.
• Full conversations, session history, tasks, settings, authentication files, and global instruction files are not imported.
• Credential-shaped entries are held for review. Their content is hidden in previews and is not imported by the app.
• Repeated imports are idempotent. Exact scoped duplicates are linked instead of copied, and each batch can be undone without removing a memory that was edited or shared by another source.

synapse memory import claude
synapse memory import claude --confirm
synapse memory import codex --confirm
synapse memory import markdown ./notes --confirm
synapse memory imports
synapse memory undo <batch> --confirm

Search and recall

Memory is stored in an SQLite FTS5 table using Unicode tokenization. A non-empty query searches the memory body; an empty query returns recent entries. Connected tools are instructed to begin with a focused query, the smallest useful result limit, and a Lean response.

{
  "query": "project naming conventions",
  "limit": 4,
  "budget": "lean",
  "project": "/Users/example/project"
}

The optional per-call budget may be full, balanced, or lean. It can only make the response smaller than the mode selected in Settings; a tool cannot override a user-selected Lean ceiling with Full.

synapse memory list "Bun JavaScript"
synapse memory list --json
synapse memory show 24
synapse memory show 24 --json

The CLI lists up to 100 matching memories across the local store for management. Each record contains an integer ID, exact body, source, global or project scope, project root, and Unix timestamp. JSON output is suitable for local automation.

Ranked search drops words that appear in nearly every memory — the, are, where — because a memory that matches only on one of those is a confident wrong answer, and an agent acts on it. Words that carry meaning in a preference, including not, never, and use, are kept. Two commands exist for when that is the wrong behaviour or the wrong result:

synapse memory grep -- --no-verify
synapse memory list where are the credentials --explain

memory grep matches the characters you give it and nothing else, which is what you want for an identifier, a flag, a path, or a word the ranked search treats as noise. --explain answers the other question — why a memory you know is stored did not come back:

Query:      where are the credentials
Mode:       search
Expression: "credentials"
Searched:   credentials
Dropped:    where, are, the (matches nearly every memory)
Matches:    1

-0.4596	31	global	vault	Credentials live in the vault, never in the repository.

Inspect and correct

The desktop Memories screen searches the same store and lets you inspect, edit, or delete individual entries. CLI edits replace the body and optionally the source:

printf '%s
' 'Use Bun unless a task explicitly requires another runtime.' \
  | synapse memory edit 24 tooling

synapse memory show 24

Editing changes the stored original. Recall optimization does not.

Correcting a memory

A convention changes. Something you stored last month is now wrong. Adding the new version on its own leaves two memories contradicting each other, both are recalled, and the ranking decides which one a tool acts on — possibly the one you had already retracted.

Say which replaced which:

printf '%s
' 'Deploys run from the release branch, after the tag is signed.' \
  | synapse memory add deploys --global

synapse memory supersede 12 47

A connected tool does it in one call, passing the id that came back from its own recall:

{
  "content": "Deploys run from the release branch, after the tag is signed.",
  "scope": "global",
  "supersedes": [12]
}

Nothing is deleted. Memory 12 keeps its id, stays in memory list and the dashboards marked as replaced, still says what replaced it, and comes back at any time:

synapse memory show 12
synapse memory restore 12

What changes is only what recall can see. A superseded memory stops being returned to tools and stops counting toward the number a session reports — the count a tool announces is the count it can actually draw on. Deleting the replacement restores what it replaced on its own, so a correction can never leave the older version hidden behind an id that no longer exists.

Choose between the three: edit when the memory was badly worded and there is nothing to keep, supersede when the old version was true and stopped being true, and delete when it should never have been stored.

Response budgets

The response reports the optimization mode actually applied. Choose the ceiling in Settings → Recall optimization, or use the CLI:

synapse settings show
synapse settings optimize lean
synapse settings optimize balanced

A memory that will not fit in what is left of the budget is returned as its opening sentence, marked abridged, rather than cut off wherever the character count landed. Half a memory reads exactly like a whole one — never deploy from main unless is a rule with its condition amputated — and one long memory at the top of the results no longer costs you every result under it. A tool that receives an abridged memory is told to recall it again, more narrowly, before acting on the part it cannot see.

Destructive actions

Deleting one memory, undoing an import, and wiping every memory require explicit confirmation. The desktop app presents a separate confirmation. A wipe removes memory and import history but leaves guidance, vault labels, stored values, scope approvals, and settings intact.

synapse memory delete 24 --confirm
synapse memory wipe --confirm

Before a large cleanup, create a portable snapshot with synapse data export. Use a wipe when the goal is to clear context while retaining the vault setup; use a database restore when the goal is to return the entire Synapse state to an earlier snapshot.