Design the write rule before you design the schema.
The memory schema is the visible part of the design — the fields, the types, the storage format. Teams spend time on it. The write rule is the invisible part — when does a fact enter the memory, who decides, at what level of specificity, with what audit trail. Teams defer it until the memory is already filling up with garbage, and then they realize the schema was never the problem.
A memory system that writes too eagerly is a memory system that quickly becomes noise. The agent wrote things the user said in passing — a frustration about a meeting, a throwaway preference, a hypothesis they were testing aloud. The memory now contains those artifacts as if they were stable truths. Future retrievals surface them. The agent acts on them. The user's trust erodes because the system is "remembering" things they did not mean to commit.
A memory system that writes too rarely does not compound. The agent never records the pattern that would make it more useful in session fifty than in session one. The memory stays sparse. The system stays stateless in practice even if it looks stateful in theory.
The design challenge is a write discipline, not a storage problem.
The picture
Draw a decision tree at the moment the agent loop is about to write to memory. The tree has four branches, each with a question:
Should this be remembered? Is this fact useful in a future session, or only in this one? Session-local information — the current draft, today's meeting notes, a running calculation — is not memory. It is working state. If it crosses sessions, it is memory.
Which regime? Semantic (true and stable), episodic (happened, may matter later), procedural (how we work), or working (this session only). If you cannot answer, the fact is under-specified for memory purposes.
At what specificity? Verbatim (the user's exact words), distilled (the meaning extracted from those words), or pointer (a reference to a resource where the detail lives). Procedural memory almost always should be distilled, not verbatim — "user prefers direct language over diplomatic hedging" is more useful than "user once said 'just tell me directly, I don't need the softening.'"
Who can edit later? Memory that the user cannot read, modify, or delete is an autonomous system making permanent decisions about how to treat a person. That is a design choice with real trust consequences, not a detail to address after shipping.
Why it matters now
The 2024 generation of "the agent remembers what you tell it" demos optimized for write-eagerness because write-eagerness was impressive in demos. The agent wrote everything, the user felt heard, and in a fifteen-minute demo session nothing went wrong. In a six-month product relationship, write-eagerness becomes a liability. The memory grows unboundedly. Retrieval surfaces noise. Users start to notice the system remembering things incorrectly or acting on outdated information they cannot find to correct.
The 2026 generation of memory-augmented systems is more disciplined about writes than reads. The write decision is harder than the read decision. Retrieval can be tuned with recency and relevance scoring; a bad write cannot be tuned away. You have to prevent it at the source.
A source you should trust
MemGPT (Packer et al. 2023) is the academic source on explicit memory hierarchies with controlled write operations. The key contribution is the distinction between main context (working memory), external storage (long-term memory), and the deliberate management of the boundary between them. The write-rule design problem this lesson addresses is exactly what MemGPT formalizes.
Anthropic's auto-memory documentation for Claude Code describes the write protocol used in a shipping product with hundreds of sessions of history. It is operator-grade evidence of what the rules look like in practice, not just theory.
A recipe
A four-question write protocol for every memory write:
- Relevance. Is this useful in a future session, or only in this one? If only this one, do not write. This single filter eliminates the majority of write-eager garbage.
- Regime. Which of the four memory types is this? If you cannot decide in thirty seconds, the fact is not ready to be committed. Write-to-understand is a reading-loop problem, not a memory problem.
- Specificity. Verbatim, distilled, or pointer? Most procedural memory should be distilled — the extractable rule, not the raw sentence that implied it. Most episodic memory should be a summary pointer, not a verbatim transcript.
- Reversibility. Can the user (or the agent itself) supersede this later? Memory should always have an update path. If the system writes "user prefers email communication" and the user switches to Slack, there must be a mechanism for that preference to update.
The smell of it going wrong
- The memory store grows without bound with no compaction mechanism. Memory has a retention policy; that policy is part of the design.
- The agent writes the same fact in three places under three names, because the write protocol does not deduplicate before committing.
- Users have no way to read, edit, or delete what the agent has remembered about them. This is not a nice-to-have; it is a trust requirement.
- The memory contains things the user said in passing that were never intended as persistent facts. Write-eager systems treat all user utterances as potential memory candidates; disciplined systems filter first.
- The team treats memory quality problems as retrieval problems. "The agent is surfacing wrong facts" usually means the wrong facts were written in the first place, not that retrieval is broken.
A judgment call from real work
PL auto-memory uses a two-step write protocol that the indexing-discipline rule crystallized.
Step one: write the memory file. A separate markdown file with YAML frontmatter naming the type, a one-line description, and structured body content. For feedback and procedural memories, the body follows the rule-why-how-to-apply structure: what the rule is, why it exists, and how to apply it in context.
Step two: decide whether to add a pointer in MEMORY.md. This is the contested step. The default temptation is to add every new memory to the index so it is always available. The problem is that MEMORY.md is loaded on every single call in every single session. An uncapped index becomes a context tax paid on every interaction, including ones where the indexed memory is irrelevant.
The discipline that emerged from operational experience: only cross-cutting memories go in the index. A memory about how to present decisions in product strategy contexts is cross-cutting — it is relevant to nearly every session. A memory about the specific course-visualization playbook for a particular course-authoring session is topic-narrow — it is relevant only when doing that kind of work, and loading it on sessions about code or content or deployment wastes context budget.
The cost of getting this wrong showed up concretely: MEMORY.md had grown to a point where it was loading forty or fifty lines of memories per session that had not been relevant in weeks. Auditing the index and moving topic-narrow memories to unindexed files reduced the per-session context overhead and, more importantly, reduced the cognitive noise from irrelevant memory pointers appearing in the agent's working context.
The lesson from this operational experience: write discipline and index discipline are different problems. A memory can be well-written and still poorly indexed. Design both.
Rules from this lesson
- Writes are designed decisions, not automatic logging — write-eagerness is a bug, not a feature.
- Every write has a regime, a specificity, and a reversibility property; a write that lacks all three is not ready to be committed.
- Memory the user cannot see, edit, or delete is a trust failure waiting to ship, not a simplification.