maintaining-deferred-memory

Deferred memory contains the agent's knowledge. Use deferred memory for understanding of a subject that matters only when that subject comes up. If the agent needs it on most turns, it is core memory: use the maintaining-core-memory skill. If it is a procedure with a trigger, use the creating-skills skill.

Deferred memory should NOT be used to store:

• Information that can be accessed by querying the message history (recall memory). For example, logs of specific interactions can simply be looked up in past messages. Reserve deferred memory to store knowledge that is actually derived from experience, or to organize knowledge in a way that optimizes recalling the right information at the right time through progressive disclosure.
• Justifications, reasons, or sources for updating memory. These belong in the commit message; see Commit memory changes.

Check the limits first

Read $MEMORY_DIR/.memfs.config.json if it exists. The memory repository's pre-commit hook enforces it:

• maxDepth limits how many directories can sit between the memory root and a file (default 2). persona.md is depth 0, projects/MEMORY.md is depth 1, and projects/acme/notes.md is depth 2. skills/ is exempt.
• maxFileCharacters caps each memory file, frontmatter included (default 20,000 characters). fileCharacterLimits overrides it per glob; the first match wins and null removes the cap.
• readOnlyFiles lists globs whose files cannot change. Do not edit them.

When the config file is absent, the defaults apply. When content does not fit, split it into more files or flatten the structure; change the config only when the user asks.

Layout

$MEMORY_DIR/
├── MEMORY.md              # root index (core memory)
└── projects/
    ├── MEMORY.md          # index for projects/
    ├── acme.md
    └── acme/
        ├── MEMORY.md      # index for projects/acme/
        └── incidents.md

• The top-level MEMORY.md is always in context, so it must tell the agent what each subdirectory contains and when to open it. Without that entry the directory is never read.

• skills/ is reserved for skills and is never deferred memory.

• A directory is memory only when it has its own MEMORY.md. The agent will not discover a directory without one, and neither will the files in it.

• Every MEMORY.md has no frontmatter.

• Every other Markdown file starts with frontmatter containing exactly two fields:

  ---
  name: acme
  description: How the Acme integration works, why it fails, and what to do about it.
  ---
  

• description says what the file is about. The agent sees it when it lists the directory, so make it specific enough to decide whether to open the file.

• Name files and directories after their subject, not after a date or session. Group related subjects under one directory instead of creating many top-level directories.

Write the indexes

Discovery runs through the MEMORY.md chain, one level at a time:

• The system prompt lists each top-level memory directory only by path. Add a line to root MEMORY.md saying when to open the directory, in the words a future request would use. When a deeper file's topic would not be guessable from that line, name the file there too.
• When the agent opens a directory, it sees that directory's MEMORY.md, then each file's description and each subdirectory's index summary (the first prose paragraph of its MEMORY.md). Start every MEMORY.md with that summary paragraph.
• A directory listing shows at most 10 entries, most recently edited first, so stable files fall out of it. Link every file that matters from its MEMORY.md rather than relying on the listing.
• Use relative Markdown links from the memory root, such as [Acme](projects/acme.md).

After adding or moving a file, trace the path a future request would take from root MEMORY.md to the file. If any step depends on knowing the file already exists, fix the index.

Indexes are the only way the agent finds deferred memory: it opens a file only when every entry on the path from root names what it is looking for. Keep them accurate as memory changes. Whenever you add, move, or substantially change what a directory holds, reread its entry in each parent MEMORY.md up to root and rewrite it to name the topics the directory now covers, in the words a future request would use. An entry written when the directory was new goes stale as it fills, and a topic no entry mentions is effectively lost.

Design for progressive disclosure

Each level should give the agent enough to decide whether to go deeper, and nothing it would have to read past to decide.

• Put frequently needed material shallow and rarely needed detail deeper. Keep related material in one directory so it loads together.
• A small topic, where most of the content is useful whenever the subject comes up, belongs entirely in its directory's MEMORY.md. Splitting it adds reads without saving context.
• For a large topic, MEMORY.md holds only what the agent needs every time it opens the directory, plus a map: what each deeper file or subdirectory covers and when it is worth opening. The map should also tell the agent when it can stop.
• A description states what the file is about, not when to use it; when-to-open belongs in the parent's link. If you can write a "use when the user wants to…" trigger, the content is a procedure and belongs in a skill.
• Make each statement stand alone. Name the subject instead of writing "it" or "the repo", because the agent may read only part of a file.
• Aim for fewer than 10 entries per directory so the listing stays complete. At the maxDepth limit, use clearly scoped sibling files linked from MEMORY.md rather than nesting further.

Write analysis, not logs

Recall already returns what happened. A deferred memory file is worth keeping only when it holds what recall cannot: the agent's own synthesis of a subject, built across many events and refined as understanding improves.

• Before writing, ask whether searching message history would give a future agent the same thing. If it would, do not write the file.
• Write the current understanding: how the subject works, the patterns across events, why things failed or succeeded, what to do about it, and the open questions.
• Revise the file in place when new evidence arrives. Fold the new event into the analysis; never append a dated entry, a quote, or an incident narrative; the commit carries the event.
• When the file you are updating is already a log, convert it: write the analysis the entries support and delete the entries. Keeping them under an "incident history" heading leaves the log in place; git and recall already hold it.
• When a raw event matters, point to it with terms that will find it in recall rather than copying it.
• Keep one home per subject. Update the existing file instead of adding a near-duplicate, and replace stale conclusions where they live.
• Leave out content the agent can cheaply rederive from the source of truth: file contents, command lists, and current status. Link to the owning source instead.
• Never store secrets. Reference them by name, such as $SECRET_NAME.

Commit memory changes

Every memory commit must let someone reading git log or git blame on a memory or skill line trace back to the events that justified it. Commit each learning separately; a learning may touch several files. When a turn produces several learnings, finish and commit one before editing for the next. From the repository root, stage only that learning's files and commit in one shell call:

git add <changed files> && git commit -m "memory(<origin>): <what was learned>

<what happened: the events that led to this learning and why it should persist>

Sources:
- <conversation ID> (<message IDs>), <who>, <date>: <what happened there>"

• <origin> is self when you edit your own memory during a conversation, or dream when you are a reflection or dream subagent reviewing past transcripts.
• Provenance belongs in the commit, not the memory file: who said or did it (name and ID), when, the quote, and the incident go in the body and Sources:. The memory line states only the resulting rule or fact. For example, the file says "Be concise" and the commit says "feedback 'talk more concisely' from Charles on ". Git dates the commit, not the event, so write the event date.
• The subject states the learning itself, such as memory(self): Sarah wants one commit per learning, not the file edit.
• The body tells the story: what the user said or corrected, what failed or succeeded, or what pattern recurred, and why it generalizes beyond that moment. A reader should understand why the memory exists without opening the sources.
• Sources: lists the evidence precisely enough to find again, with one line on what happened at each: a conversation ID with the message IDs where it happened, a transcript or session ID, a file path, a URL, PR, or issue, or a commit hash. When the user explicitly asked for the change, cite that request. Resolve values such as $CONVERSATION_ID before writing them; never commit a literal variable name.
• Do not invent a source. If the origin cannot be identified, write Sources: unknown and say why in the body.
• Never include secrets.