MnemoverseDocs

Appearance

Edward Izgorodin·Published Aug 12, 2026Updated Aug 13, 2026

Your Agent Doesn't Need More Memory. It Needs to Know What It's Allowed to Believe ​

TL;DR

  • The useful split is evidence versus policy — what happened versus what should happen — not short-term versus long-term memory.
  • It works best as three scopes that differ in how easily they change: shared project truth, role memory, and episodes.
  • Every entry needs a small passport, and the two fields most often missing are the time axes: when it was recorded, and when it was true in the world.
  • Replacing a fact instead of closing it is the most common destructive operation in agent memory, and it stays invisible until someone asks about the past.
  • Retrieval should hand contradictions to the reasoning step rather than let the nearer embedding win in silence.

Every team that wires long-term memory into a coding agent hits the same wall about three weeks in. The agent remembers plenty. It remembers the migration you abandoned, the library you replaced, the convention one person suggested once in a thread. It recalls all of it with the same flat confidence, and now you are debugging your memory instead of your code.

The instinct at that point is to store less, or to store better. Both are the wrong axis. The problem is not how much the agent remembers. The problem is that everything it remembers has the same authority.

Memory versus knowledge is not the useful split ​

The common framing separates short-term memory from long-term knowledge: the conversation you are in now, versus facts you keep forever. It is a real distinction and it does not help you much, because it says nothing about what an agent should do when two remembered things disagree.

A more useful split is evidence versus policy.

Evidence is what happened. The agent tried a fix, it failed. A user rewrote a function. A test went red. Evidence is cheap to produce, it accumulates fast, and any single piece of it can be wrong or unrepresentative.

Policy is what should happen. Use pnpm. Tests mirror the src layout. Never touch the legacy billing module. Policy is expensive to produce because a human usually has to decide it, and it should be hard to change by accident.

Once you hold those apart, a lot of confusing behaviour becomes obvious. An agent that treats one observation as policy will overfit to a single incident. An agent that treats a merged architecture decision as mere evidence will keep relitigating it. Most memory systems collapse both into one undifferentiated bucket of "things we know", which is why they feel unpredictable.

Three layers, not one bucket ​

In practice the split works better as three layers, because evidence and policy live at different scopes.

Shared project truth. Architecture decision records, API contracts, naming conventions, the deployment runbook. This is policy. It is versioned, it is source-linked, and every agent working on the project should read the same copy. If your agent invents a different answer to "which database do we use", that is not a memory problem, that is a missing shared layer.

Role memory. Heuristics that belong to a job rather than to a project or a model. What a frontend reviewer usually checks. How the QA pass is structured. Which failure modes the migration specialist has learned to look for. This layer is the one most systems skip entirely, and it is why teams end up re-teaching the same review standards to every new agent session. Note the scoping: role memory belongs to the role, not to the current chat and not to the current model.

Episodes. What happened on a task. What was attempted, what failed, what feedback followed. This is evidence in its rawest form, and it is the layer that grows fastest and rots fastest.

The layers are not a hierarchy of importance. They are a hierarchy of how easily something should change. Episodes are written constantly. Role memory shifts slowly. Shared project truth changes only when a human decides it does.

Every item needs a passport ​

Whatever you store, each item should carry the same small set of fields. Not because metadata is inherently virtuous, but because every hard retrieval question turns out to be a question about one of these:

  • origin. Where this came from. A file, a conversation, a test run, an ADR.
  • author. Which human or which agent produced it.
  • recorded_at. When it entered the store.
  • valid_from and valid_to. When it was true in the world.
  • confidence. How much weight it should carry.
  • status. Active, superseded, or disputed.

This list is deliberately about belief: where a claim came from and whether it still holds. A companion piece, provenance in agent memory, works the same problem from the accountability side and lands on a partly different set — principal, evidence, derivation, and the status of a decision. Neither list is a superset of the other, and both are worth reading before you fix a schema.

The two time fields are the ones people leave out, and leaving them out causes a specific and nasty bug.

The two time axes, and the bug you get for free without them ​

Suppose your codebase used Redux, and last quarter you moved to Zustand.

With one time axis, the agent learns "we use Zustand" and the older note is overwritten or decays away. Now ask it why a component written in March is structured the way it is. It cannot tell you. The fact that explains that code has been deleted because it is no longer current.

recorded_at and valid_from / valid_to are different questions. "Use Redux" was true from January to June and was recorded in February. It is not wrong. It is closed. An agent that keeps closed facts with their validity window can still explain old code, warn you that a pattern you are copying belongs to a superseded era, and avoid confidently rewriting history.

Replacing rather than closing is the single most common destructive operation in agent memory, and it is invisible until someone asks a question about the past.

The two-axis idea is settled engineering outside this field, and it has a name. Bitemporal modelling — separating the time a fact was true from the time the system learned it — was standardised in SQL:2011 as system-versioned and application-time period tables (ISO/IEC 9075:2011; Kulkarni & Michels, Temporal features in SQL:2011, ACM SIGMOD Record 41(3), DOI:10.1145/2380776.2380786). See Bitemporal Memory for AI Agents for where it comes from and which agent systems actually implement it.

Promotion: how evidence earns the right to become policy ​

If evidence and policy are different things, there has to be a path from one to the other, and it should be explicit rather than accidental.

An agent observation starts as low-authority evidence. It becomes policy through one of a few events:

  • a human correction, which is the strongest signal and should be treated as such
  • a merged ADR or pull request that encodes the decision in the repository
  • a repeated successful outcome, where the same approach has worked enough times to stop being a guess

The important word is earns. Systems that let a single agent observation write directly into shared knowledge will drift, and the drift is hard to notice because each individual step looks reasonable. Systems with no promotion path at all leave every session starting from the same standing start.

Demotion matters too, and it is rarer to see implemented. If a policy keeps producing failures, something should notice. That does not mean automatically deleting it. It means marking it disputed and surfacing that to a human.

Once a claim is disputed, something has to decide which side wins at retrieval time — recency, authority, or the source that carries more weight. That question has its own piece: who wins when agents disagree.

Retrieval should preserve contradictions, not resolve them silently ​

This is the part that most implementations get wrong, and it follows directly from everything above.

The default behaviour of a vector store is to return the nearest matches. If two stored items contradict each other, the one that happens to sit closer in embedding space wins, silently, and the agent proceeds as though there was never any disagreement.

That is exactly backwards. A contradiction is information. If the store holds "we use Redux, valid until June" and "we use Zustand, valid from June", the right behaviour is not to return one. It is to return both, with their validity windows, and let the reasoning step handle it. The same goes for a policy that a recent episode contradicts: an agent that sees "convention says X" alongside "X failed twice last week" can raise it with you. An agent that sees only the closer embedding match cannot.

Preserving contradictions costs context budget, which is the honest tradeoff. But losing them costs correctness in a way you cannot detect from the outside.

The practical gap nobody mentions ​

Here is the thing that surprises teams most, and it has nothing to do with architecture.

Connecting a memory tool does not make an agent use it.

You can wire up a perfectly good memory backend, expose it over MCP, watch the tools register, and then watch the agent go a full session without calling any of them. Tool availability is not tool usage. The model has no standing incentive to check memory before acting, and no habit of writing anything down afterwards.

What closes the gap is boring: standing instructions. Something in the system prompt or the project rules that says, in effect, recall before you act on anything project-specific, and save durable decisions and corrections when they happen. In Cursor that is a rule file. In Claude Code it is the project instructions. The exact mechanism does not matter much; the presence of the instruction does.

If you take one thing from this piece, take that. It is the cheapest fix in the list and it is the one most often missing. The wording we use is in Make Your Agent Use Memory.

There is measured evidence for how wide this gap runs, on the writing side as well as the reading side. In our own production store, the reinforcement signal a learning memory needs most — an explicit outcome report after a recall — reached between 0% and 12.8% of the edges of the live tenants we sampled, against 94.8% for a benchmark tenant whose harness sent it after every query. Same engine, structurally different memory. That measurement, and the force-versus-ask-versus-prescribe argument that follows from it, is in agent memory feedback: the missing signal.

What this looks like when it works ​

An agent starts a task. It reads shared project truth, so it does not ask which package manager you use. It reads role memory for the kind of work it is doing, so the review standards do not need restating. It pulls relevant episodes, including the failed attempt from two weeks ago, with the failure attached rather than sanded off.

Halfway through, it hits a convention that a recent episode contradicts. Instead of picking one, it says so. You decide. That decision, being a human correction, promotes to policy, and the next session starts from there.

None of that requires a particular database. Graphs, vectors, plain files on disk all work. What it requires is deciding, deliberately, what your agent is allowed to believe and how it earns the right to believe it.

Common questions ​

What is the difference between evidence and policy in agent memory? ​

Evidence is what happened: an attempt, a failure, a correction, a test result. It is cheap to produce and any single piece of it can be unrepresentative. Policy is what should happen: a convention, an architecture decision, a rule. It is expensive to produce because a human usually decides it, and it should be hard to change by accident. Systems that collapse both into one bucket behave unpredictably.

Why should an agent keep superseded facts instead of overwriting them? ​

Because the old fact is what explains old code. If a project moved from Redux to Zustand, "we use Redux" was true from January to June. Deleting it destroys the explanation for every component written in that window. Mark it superseded, keep its validity window, and write the new one alongside.

What should a memory entry record besides its content? ​

Origin, author, when it was recorded, when it was true in the world (valid_from and valid_to), a confidence weight, and a status of active, superseded, or disputed. The two time fields are the ones most often left out, and leaving them out is what makes an agent unable to explain the past.

How does an observation become a rule? ​

Through an explicit promotion path: a human correction, a merged ADR or pull request, or an outcome repeated enough times to stop being a guess. Letting a single agent observation write directly into shared knowledge causes drift that is hard to notice, because each individual step looks reasonable.

Why should retrieval return contradictions instead of the closest match? ​

A contradiction is information. If the store holds "we use Redux, valid until June" and "we use Zustand, valid from June", returning only the nearer embedding hides a disagreement the reasoning step should see. Preserving contradictions costs context budget; losing them costs correctness in a way you cannot detect from the outside.

Sources ​

  • ISO/IEC 9075:2011, Information technology — Database languages — SQL: system-versioned and application-time period tables. iso.org/standard/53681
  • Kulkarni, K. & Michels, J.-E. (2012). Temporal features in SQL:2011. ACM SIGMOD Record 41(3), 34–43. DOI:10.1145/2380776.2380786
  • Snodgrass, R. T. (1999). Developing Time-Oriented Database Applications in SQL. Morgan Kaufmann — the standard treatment of valid time versus transaction time.
  • Mnemoverse production measurement, 2026-08-12: feedback-touched share of concept-graph edges per tenant class. Reported in agent memory feedback: the missing signal.

— Edward Izgorodin · Last updated 2026-08-13

— Mnemoverse is a persistent-memory API for AI agents. Free key: console.mnemoverse.com · Docs: Getting Started