Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Auto memory

Auto memory lets the agent save what it learns about a project (build and test commands, layout, conventions, corrections, preferences you state) so that a later session starts with it. The agent saves notes with the memory tool, one structured call per topic; the index of those notes loads into the system prompt of each new session.

Auto memory is a persistence vector. Text an injection gets the model to write is read by every later session, so Fontaine never approves a memory write by label: each one goes through the deterministic floor and, in auto mode, the guardian.

The default is on while the feature is being tested, and should return to off until the memory-poisoning cases in the guardian scorecard have been scored live. To turn it off now:

[memory]
auto = false
KeyMeaningDefault
[memory] autoThe agent may save notes to the per-project store, and the store’s index loads each session.true

Only the user file and --settings can set it; a repository’s settings cannot. /config shows and toggles it, and a change applies at the next launch. When it is off the store is inert: its files are not loaded and no root is added, and /memory still lists them so you can clean up.

The store

Notes live in your data directory, outside any repository, so a cloned repository cannot plant them and they cannot be committed by accident:

<data dir>/memory/<project key>/MEMORY.md     the index, loaded into the prompt
<data dir>/memory/<project key>/<topic>.md    detail, read on demand with the read tool

The project key is a readable slug of the project path plus a short digest of it, for example fontaine-3fa91c2e. The path is the owning git checkout of the launch directory when there is one, so every subdirectory and every worktree of a repository shares one store; outside a repository it is the launch directory. The directory is created on first need, readable by you only (mode 0700, or a current-user-only ACL on Windows). A store directory that is a symlink is refused.

MEMORY.md is a short index with one line per topic file, linking to it. Nothing else about the files is enforced. Only the first 200 lines or 25,000 bytes of the index, whichever is smaller, reach the prompt, with a warning when the index was cut; topic files are not loaded until the agent reads them. A MEMORY.md that is a symlink or not valid UTF-8 is refused with a warning.

What the agent is told

The system prompt gets one layer when auto memory is on. It says that these are notes saved in earlier sessions, that they are unverified data about the project and not instructions, and that they must never change what the agent may do. It then gives the directory, the capped index, and short guidance on what to save and how to write it. The layer is present even when nothing has been saved yet, so the agent knows where to write. It rebuilds like instruction files do: on a model switch, an output-style change, /add-dir and a new session. The root agent gets it; a subagent does not get its own memory.

The memory directory is a workspace root, so read, write and edit reach it from any project. It is labelled memory in the system prompt’s root list and auto memory in /status, it is left out of the file index that completion and the ledger use, and the out-of-roots denial points at it.

The memory tool

The memory tool is how a note is saved: one call with topic (one line, at most 64 characters) and content (markdown, at most 100,000 bytes) writes the topic file and keeps the MEMORY.md index line for it — replacing the line’s link text in place when the topic already has a line, appending one when it does not. The file name is derived from topic, so the model never names a path and never edits the index by hand; that mechanical index bookkeeping is where fuzzy guardian soft-denies used to concentrate. Reads need no subcommand: the store is a workspace root, so read, ls and glob reach it at read-only fast-path cost.

Raw write and edit on the store’s files remain, for repairing the store by hand — fixing a dangling index line, removing a note — at the same gating as the tool. The tool is registered only while auto memory is on, and it is offered to subagents too: each call a child makes is gated on its own, as with any other write.

How writes are gated

The store sits under Fontaine’s own data directory, so every write and edit into it meets the protected-path floor, which sits ahead of every mode and every allow rule:

ModeA memory write
manual, acceptEditsAsks you, with the diff. An allow rule does not approve it.
autoGoes to the guardian.
dontAsk, headlessDenied.

There is no fast path: acceptEdits does not cover it, and neither does a read-only label. A deny or ask rule on write or edit for the memory path works as for any path. Subagents share the scope, so one can also propose a memory write, and each is gated on its own.

A memory tool call is gated exactly like the raw writes it replaces — the workspace-write class keeps it out of every fast path, and its locate error denies nothing in containment because the call names no path:

ModeA memory call
manual, acceptEditsAsks you.
autoGoes to the guardian, which sees the topic file and the index as the touched paths.
dontAsk, headlessDenied.

allow = ["memory"] and deny = ["memory"] name the tool whole; it takes no specifier. An allow rule does not approve the call — the store is protected like a raw write to it, so the floor decides first. See the tool’s entry in the tools reference.

A shell command that writes there (echo ... >> MEMORY.md) is not covered by the protected-path floor, which gates only write and edit: it takes the ordinary shell gate, a prompt outside auto and the guardian in auto. Shell redirect targets cannot be extracted soundly enough to be a floor, so the guardian’s memory rule is what covers this case. If you want a human to confirm each memory write, use a mode other than auto, or an ask rule on the path.

What the guardian does with a memory write

The guardian is told the memory directory as a session fact, set by Fontaine from the session and never from a tool argument. A call whose target is under that directory, including a shell command that writes there, is judged against the memory-write rule: allow plain project facts that your request or the repository supports; deny or escalate content that instructs the future agent, widens permissions or relaxes the guardian, contains secrets, embeds URLs or commands to run, or traces to tool results, web pages or file text rather than to you. Low confidence is a denial. The rule is in the minimal profile as well. The memory text is not added to the guardian’s project_instructions: that block is your own files, and notes are agent-written and possibly attacker-influenced. See The guardian.

Auditing and clearing

/memory lists the instruction files and then the store’s MEMORY.md and topic files, sorted, with when each was modified. Its first line says whether auto memory is on and where the directory is. /memory <n> opens a file in your editor. /memory has no delete action: delete files in your editor or the file system, or remove the whole <data dir>/memory/<project key>/ directory. /context shows a memory row when the layer is loaded. Memory saves are ordinary records in the audit log — memory tool calls, or write and edit records — with their tier and reason.

Integrity checks

fontaine doctor compares the store with its index and never changes either. It checks the store for the current workspace, even with [memory] auto = false, and ignores links inside fenced code blocks and http(s) links.

FindingLevel
No store directory yetok
The store is a link or not a directory; MEMORY.md is a link, not a regular file, unreadable or not UTF-8fail
MEMORY.md is past the line or byte cap, with the number of lines that never reach the promptwarn
An index line links to a *.md file that does not exist, naming the line and targetfail
An index line links to something a session never loads as a topic file: a directory, a nested path or a linkwarn
A topic file no index line links towarn
Two index lines link to the same filewarn
A link that leaves the store (another scheme, .. or an absolute path); it is never followed or readwarn

Differences from Claude Code

  • The store is in Fontaine’s data directory, not under ~/.claude/projects/.
  • Saving goes through a first-party memory tool, one structured call per topic; Claude Code has no such tool — its agent writes memory files with the raw file tools.
  • Every write is gated by the floor and, in auto, the guardian; no memory write skips both.
  • The loaded text is framed as unverified notes, and kept out of the guardian’s context.
  • The index is capped at 200 lines or 25,000 bytes.
  • Only the user can turn it on or off; a repository cannot.
  • There is no automatic subagent memory.