Curate and optimize memory

Build a small memory set, learn how search actually behaves, correct entries at the source, tune the recall budget, import existing notes reversibly, and remove only what you added.

Outcome and prerequisites

You will build a small set of entries, understand why search returns what it returns, correct one at the source, compare what each recall budget actually sends to a model, import a Markdown file reversibly, and then undo it. This is the tutorial to read when recall is returning too much, too little, or the wrong thing.

The synapse CLI installed and at least one tool connected.
A project folder. Steps here create and delete entries under one source label.

Add focused entries

Content is read from stdin, never from an argument, so a memory can contain anything without shell quoting getting in the way:
shell
```
printf '%s\n' 'Tutorial apps use port 4100.' | synapse memory add synapsetutorial
printf '%s\n' 'Tutorial commands use Bun.' | synapse memory add synapsetutorial
printf '%s\n' 'Tutorial backups go in the backups folder.' | synapse memory add synapsetutorial
```
text
```
Stored memory #1
Stored memory #2
Stored memory #3
```
synapsetutorial is the source — a label saying where the fact came from. Give every memory one. It is what lets you find a set later, audit what a particular session stored, and delete a batch without hunting.

One durable idea per entry. Three entries about ports, runtimes, and backups can each be recalled, corrected, and deleted on their own; one entry containing all three is returned whole every time any part of it is relevant, and cannot be corrected without rewriting the rest.

Search and inspect

shell

synapse memory list tutorial

text

2	project:/Users/example/project	synapsetutorial	Tutorial commands use Bun.
1	project:/Users/example/project	synapsetutorial	Tutorial apps use port 4100.

The columns are the ID, the scope with its project, the source, and the body. For anything scripted, ask for JSON instead:

shell

synapse memory list "Bun" --json

text

[
  {
    "id": 2,
    "body": "Tutorial commands use Bun.",
    "source": "synapsetutorial",
    "scope": "project",
    "project": "/Users/example/project",
    "created": 1785776940
  }
]

And for one exact record, with nothing trimmed:

shell

synapse memory show 2

text

Memory #2
Scope: project
Project: /Users/example/project
Source: synapsetutorial
Created: 1785776940

Tutorial commands use Bun.

Understand how search behaves

Recall is full-text search with two behaviors worth knowing, because both explain results that otherwise look wrong.

Common words are dropped. A query is stripped of words that carry no meaning on their own. Try it:
shell
```
synapse memory list "what are the"
```
Nothing in that query survives, so instead of matching every memory containing the, Synapse answers the way it answers an empty query — with the most recent entries. That is deliberate. Matching on a common word is both wrong, because a memory that happens to contain are is not the answer to anything, and slow, because a common word makes the index rank most of the store.

An empty query is a real question. It means "what should I know here", and it returns the most recent memory in scope. This is exactly what a session opening asks, and it is what the Claude Code session hook uses.
shell
```
synapse memory list
```
Words that carry a preference are kept. not, never, and use look like function words but change the meaning of a convention completely, so they stay in the query. "Never use npm" and "use npm" must not search identically.

You can ask what it did. When a memory you know is stored does not come back, the fastest answer is to make the search show its working:
shell
```
synapse memory list "what are the credentials" --explain
```
text
```
Query:      what are the credentials
Mode:       search
Expression: "credentials"
Searched:   credentials
Dropped:    what, are, the (matches nearly every memory)
Matches:    0
```
That distinguishes the two things that look identical from the outside: a query that lost its only real word, and a store that genuinely holds nothing.

And you can skip the ranking entirely. When you want an exact string — a flag, an identifier, a path — the ranked search is the wrong tool, because the thing you are looking for may be a word it drops:
shell
```
synapse memory grep -- --no-verify
```
Scope is applied in the query, not after it
Every search returns everything global plus everything for the current project, and nothing from any other project. That is enforced where the rows are selected rather than filtered afterwards, so there is no path where another project's memory is read and then discarded.
Correct at the source

A convention becomes more precise. Replace the record rather than adding a second one that disagrees with it:
shell
```
printf '%s\n' 'Tutorial commands use Bun unless a task requires another runtime.' \
  | synapse memory edit 2 synapsetutorial
synapse memory show 2
```
text
```
Updated memory #2
```
The ID is stable, so anything referring to this memory still refers to the right thing, and future recall returns only the corrected text. Two entries that contradict each other are the single most common way a memory store gets worse as it grows: recall returns both and the model has to guess which is current.

Editing is right when the old wording had nothing worth keeping. When the old version was true and then stopped being true, supersede it instead — the new memory becomes the one recall returns, and the old one stays readable as the record of what used to be the case:
shell
```
printf '%s\n' 'Tutorial commands use Bun. Node is used only for the release script.' \
  | synapse memory add synapsetutorial
synapse memory supersede 2 6
```
text
```
Memory #2 superseded by #6; recall now returns #6 instead
Undo with: synapse memory restore 2
```
Check both. Memory 2 is still there, marked, and out of recall; memory 6 is what a tool now sees. If you decide you were wrong, synapse memory restore 2 puts it straight back.
shell
```
synapse memory show 2
synapse memory list
```

Tune what recall actually sends

The budget controls how much a recall response costs a model in context. Look at where you are:

shell

synapse settings show

text

optimization	balanced
result limit	8
character budget	6000
mesh	off
shell modes	command-scoped, ambient directory
zsh hook	eval "$(synapse hook zsh)"

Budget	Results	Characters	When to use it
Full	25	unbounded	A small store, or when you want everything and context is cheap.
Balanced	8	6,000	The default, and the right answer for most stores.
Lean	4	2,800	A large store, a long session, or a model whose context you are protecting.

shell

synapse settings optimize lean

text

Recall optimization set to Lean

Ask a connected tool to recall synapsetutorial and note how many entries come back. Switch to full and ask again. The stored bodies never change — synapse memory show returns the same text at every setting. The budget only shapes the response.

A tool can request a smaller budget for one call, and that request can only ever shrink your configured ceiling. A session cannot talk its way into a larger response than you have allowed.

shell

synapse settings optimize balanced

Import notes you already have

If you have been keeping conventions in a Markdown file, bring them in. Every import previews first:
shell
```
synapse memory import markdown notes.md
```
text
```
Markdown: 1 found · 1 ready · 0 existing · 0 flagged
ready	notes.md	# Conventions - Use Bun, never npm. - Deploys target Apple silicon only. …
Preview only. Add --confirm to import safe entries.
```
Now try one with a credential in it and watch what happens:
text
```
Markdown: 1 found · 0 ready · 0 existing · 1 flagged
review	flagged.md	Content hidden until the source file is reviewed.
	warning: mentions a credential-shaped environment variable
Preview only. Add --confirm to import safe entries.
```
Flagged content is not merely skipped — it is not even displayed, because printing it to your terminal to warn you about it would defeat the point. --confirm imports the ready entries and leaves flagged ones untouched.

The flagging is conservative, not exhaustive
It looks for private-key markers, credential-shaped variable names, assignments to password- and token-like keys, and bearer tokens. A secret that matches none of those patterns will not be caught. Read your own preview — the flag is a safety net, not a substitute for looking.
shell
```
synapse memory import markdown notes.md --confirm
```
text
```
Import batch #1: 1 stored, 0 linked, 0 already imported, 0 flagged and left untouched
Undo with: synapse memory undo 1 --confirm
```
Imports are idempotent. Running the same file again reports the entries as already imported rather than creating duplicates, so a repeated import is harmless. Claude and Codex memory stores import the same way with synapse memory import claude and synapse memory import codex.
Undo the whole batch
shell
```
synapse memory imports
```
text
```
1	markdown	1 stored	0 linked	active
```
shell
```
synapse memory undo 1 --confirm
synapse memory imports
```
text
```
Undid import batch #1; removed 1 imported memories
```
text
```
1	markdown	1 stored	0 linked	undone
```
The batch is recorded rather than forgotten, so an import you regret is one command to reverse and the record of it having happened survives. Anything you wrote by hand is untouched — undo removes only what that batch stored.

Delete only what you added

shell

synapse memory list synapsetutorial
synapse memory delete 1 --confirm
synapse memory delete 2 --confirm
synapse memory delete 3 --confirm

text

Deleted memory #1

Both destructive commands refuse without --confirm, and say which record they mean:

text

Error: add --confirm to delete memory #3
Error: add --confirm to delete every memory

A final synapse memory list synapsetutorial should return nothing. Use the Memories screen for a visual review before deleting anything you did not create in this tutorial.

Next step

Continue with Use a scoped secret in either shell mode, which is the other half of what Synapse hands a tool — and the half where the boundaries matter most.

Outcome and prerequisites

Add focused entries

Search and inspect

Understand how search behaves

Correct at the source

Tune what recall actually sends

Import notes you already have

Undo the whole batch

Delete only what you added

Next step