The Design Mistake Underneath All Three

Two ways to think about agent memory. The first: the agent writes notes, the user reads them when something goes wrong. The second: the agent's memory is a designed artifact — a system with a purpose, a structure, and an owner. Most first attempts at agent memory use the first model without knowing it. Most failures come from the second model being the right one all along.

The three mistakes are not independent. They are three symptoms of the same underlying failure: treating memory as a write operation rather than a read operation. Memory that is designed for writing looks like "save everything, write often, append always." Memory that is designed for reading looks like "what would I need to find in six months, written so I can find it."

This piece names each mistake, explains the mechanism that produces it, gives a diagnostic test for identifying which mistake you are making, and connects each one to the architectural fix: the Wiki Memory pattern.

Mistake 1: Writing Too Much

The first instinct is to save everything. Every tool result. Every decision. Every draft. "We will need it later." You will not. Most of it will never be read again. What you actually need is buried under what you should have discarded.

The mechanism is familiar from software engineering: developers who never delete code. The file grows. The comments contradict each other. The dead code sits there, looking active, confusing every person who reads it later. The same thing happens in agent memory.

A concrete example: an operator configured the agent to save the full result of every tool call to the long-term memory file. After three months, the memory file was 4,200 lines long. The agent was using it for context on every session. The sessions were slow because the context assembly had to read 4,200 lines before every turn. The operator's diagnosis was "the model is getting slow." The model was fine. The memory file was the problem.

The diagnostic test: compare the memory file to the session that produced it. If the memory file is longer than the conversation that generated it, you are keeping too much. A useful memory file is always shorter than the work session that produced it. The conversation is the raw material; the memory is the distilled artifact.

The fix: define what earns a place in long-term memory. Three things qualify:

  • Stable facts about the user, project, or environment that will not change next week.
  • Decisions that affect future behavior, and the reasoning behind them.
  • Open threads the agent is expected to come back to.

Tool outputs are not in that list. Intermediate drafts are not in that list. Log entries are not in that list. They belong in files, not in memory. Memory is for what survives; everything else should be in a file the agent can read when it needs it.

Mistake 2: Writing Too Little

The opposite failure. The agent saves a single sentence per session: "Worked on Q3 plan." Or it appends nothing at all — every session starts from zero because the previous session did not leave enough to reconstruct the work.

The mechanism is different here: not carelessness but uncertainty. The operator is not sure what to save. The agent is not sure either. The result is a memory file that tells you nothing about the why behind the work.

The cost surfaces weeks later. A new session starts. The agent asks "what were you working on?" The operator says "the Q3 plan, I told you about this." The agent says "I have a note that says Q3 plan but no context about what that means." The session starts from scratch. The work that was done is not recoverable from the memory file.

The fix: memory should be enough to reconstruct intent. Not the full transcript, but enough that a fresh agent could pick up the work and ask the right questions. The minimum useful memory note has four lines:

  • What the work is (one sentence).
  • Why it matters (one sentence — often the user's framing).
  • What is open (one sentence or a short list).
  • What the next step looks like (one sentence).

If you cannot fill those four lines, you do not yet understand the work well enough to leave it for later. This is useful feedback: a memory file that stays empty is a signal that the work is not yet defined well enough to be handed off.

The comparison to the first mistake is useful here. Too-much saves everything and buries what matters. Too-little saves almost nothing and loses the why. Both are failures of curation. The first curator never deletes. The second curator never writes.

Mistake 3: Writing in the Wrong Place

The third mistake is the most expensive: memory in a place the human cannot see, edit, or delete without a special tool.

The failure shows up in three forms. The first is an opaque vector store — the agent writes chunks to a semantic index, and the operator cannot open that index in a text editor. When the agent starts behaving oddly, there is no audit trail. The operator cannot read the memory to find out what the agent was told to remember.

The second form is a single running file. Every session appends. After three months, the file is thousands of lines and the recent context is buried at the bottom. The operator can technically read the file but cannot find anything in it.

The third form is a database only the agent queries. The same problem as the vector store, dressed up with a different interface.

The architectural problem is the same in all three cases: the human cannot audit the memory. Without auditability, the first two mistakes are invisible. The operator does not know the agent is saving too much or too little because the operator cannot read what the agent is saving.

Narrative: The Opaque Vector Store

A realistic scenario. An operator configured an agent with a vector-store memory: every session's tool results and decisions were chunked and embedded into a semantic index. The setup seemed sophisticated. After two months, the agent began making decisions that contradicted each other across sessions. The operator checked the vector store and found thousands of chunks — but the semantic retrieval was surfacing old, outdated chunks that looked relevant to the query but no longer reflected the workspace's current state.

The agent retrieved an old chunk about a project that had been renamed six weeks prior. It used the old name. The downstream system expected the new name. Something broke, and the operator spent two hours tracing it back to a stale memory chunk the agent had retrieved and acted on without the operator's knowledge.

The fix: move the canonical memory to a readable layer. The vector store is fine for retrieval. The canonical memory layer should be a human-readable file system — markdown files in the workspace, one per concern, that the operator can open in any text editor and immediately understand what the agent is supposed to know.

The diagnostic test for wrong-place is immediate: can you open the memory file in a standard text editor without a tool call? If not, it is in the wrong place.

How the Three Mistakes Connect

Mistakes one and two happen inside the system. Mistake three puts memory outside the operator's reach — and that makes mistakes one and two invisible.

The wrong-place mistake is the most dangerous because it hides the other two. When memory lives in an opaque store, the operator cannot see that the agent is saving too much or too little. The memory looks fine from the outside. The failures show up as agent behavior problems, and the operator blames the model.

The architectural fix for all three is the same: a readable memory layer. Once the operator can read the memory file, the first two mistakes become visible and self-correcting. The operator who can see a 4,200-line memory file deletes half of it. The operator who can see an empty memory file adds the right content. The operator who can see an opaque vector store moves to markdown files.

The architectural solution is described in the Wiki Memory article. The short version: separate the retrieval layer (vector store) from the canonical memory layer (human-editable files). The agent reads from all layers. It writes to long-term memory files. The human audits and edits the wiki layer. This design makes all three mistakes visible and correctable.

The Relationship to Wiki Memory

This article names the disease. Wiki Memory describes the cure.

The three mistakes are failures of curation. The agent writes without editing. The memory grows without bound. The contradictions accumulate. The operator cannot audit what the agent is remembering.

Wiki memory is the architectural response: a human-edited knowledge base that sits above the agent's notes. The agent writes session notes. The human edits the wiki. The wiki is the source of truth for durable facts. The long-term memory file is the agent's scratchpad.

When this article says "write less" and "write in the right place," wiki memory is the structure that makes both prescriptions enforceable. Without the wiki layer, "write less" is a behavioral recommendation that depends on the operator remembering to do it every session. With the wiki layer, the operator can audit what the agent wrote, edit what is wrong, and delete what is stale.

The three-layer memory model — short-term, long-term, semantic — is the floor. The wiki layer is what keeps the floor from becoming a graveyard. The piece on Memory: Short-Term, Long-Term, and Semantic describes the three layers in detail. The piece on Wiki Memory describes the fourth layer and why it is necessary.

Diagnostic: Which Mistake Are You Making?

A quick test for each:

  • Too much: Can you open the memory file and find the signal in under a minute? If the file is too long to scan, you are saving too much.
  • Too little: If you handed this memory file to a fresh agent with no context, could it reconstruct what the work was and what to do next? If not, you are saving too little.
  • Wrong place: Can you read the memory without a special tool call? If not, it is in the wrong place.

If the answer to the wrong-place question is no, fix that first. The other two mistakes are invisible until you can see the memory.

A Note on Cross-Session Memory

One reason the wrong-place mistake is so common: the agent's memory lives in a session-scoped system that the operator does not have a window into. When the agent finishes a session, its memory is written somewhere the operator cannot easily inspect.

The piece on Sessions, Sub-Agents, and Child Sessions discusses session-scoped memory and the failure modes that come from sessions not sharing memory by default. The piece on Context vs Memory explains the distinction between what the model sees in the current call (context) and what survives between calls (memory). Both are relevant to understanding why cross-session memory is a separate design problem from session-scoped memory.

The design principle: memory that is needed across sessions should live in a place the operator can audit between sessions. If the operator cannot read it without a session active, the memory is in the wrong place.

Takeaway

Memory is the part of an agent that survives across sessions. Get the design right early.

The three mistakes — writing too much, writing too little, writing in the wrong place — are curatorial failures. They are fixed by designing the memory as a readable, auditable system, not as a write-only log.

Write what matters. Write it where you can read it. Edit it when it goes stale.

The cost of getting memory wrong is invisible at first. The agent seems to be working. The cost shows up three months later when the agent cannot reconstruct the work, the operator cannot audit what the agent is remembering, and the only fix is a complete memory rebuild. Get it right early.