Agent memory design.

Which kind of memory does your agent need

Agent memory is anything an agent writes in one step or session and reads in a later one. The word covers five different things with different lifetimes, stores and risks, and most design mistakes come from treating them as one.

The design rule we apply: start with working memory only, measure where the agent fails for lack of context, and add the narrowest type that fixes that failure. Many “the agent should remember” requests are really retrieval from a system of record. If the customer’s preferred contact method is in the CRM, the agent should read the CRM, not keep a private copy that will drift. Our comparison of RAG and long context covers when to fetch rather than store, and our guide to retrieval evaluation applies to memory search too.

The MemGPT paper (arXiv 2310.08560) borrows from operating-system memory hierarchies: it manages tiers of memory, moving information between the limited context window and slower external storage. The useful lesson is the tiering, not the specific implementation: keep the context small and move things in and out deliberately.

Write policy: what may be remembered, and from where

Memory quality is decided at write time. A record without a source cannot be checked, corrected or deleted with confidence, so every write goes through a gate.

from dataclasses import dataclass
from datetime import datetime, timedelta
from enum import Enum

class Kind(str, Enum):
    EPISODE = "episode"          # something that happened
    FACT = "fact"                # a durable statement about a subject
    RULE = "rule"                # procedural; people approve changes

class Origin(str, Enum):
    USER_STATED = "user_stated"
    AGENT_INFERRED = "agent_inferred"
    DOCUMENT = "document"        # untrusted third-party content

TTL = {Origin.AGENT_INFERRED: timedelta(days=30),
       Origin.USER_STATED: timedelta(days=365),
       Origin.DOCUMENT: timedelta(days=30)}

@dataclass
class MemoryRecord:
    tenant_id: str
    subject_id: str              # the person or account it is about
    kind: Kind
    text: str
    origin: Origin
    source_ref: str              # message, tool call or document ID behind it
    confidence: float
    sensitivity: str             # "general", "personal", "restricted"
    created_at: datetime
    expires_at: datetime
    supersedes: str | None = None

BLOCKED_TERMS = ("password", "card number", "cvv", "ird number", "bank account")

def gate_write(rec: MemoryRecord, proposed_by_agent: bool) -> str:
    if not rec.source_ref or not rec.subject_id:
        return "reject"
    if rec.kind is Kind.RULE and proposed_by_agent:
        return "queue_for_review"
    if any(term in rec.text.lower() for term in BLOCKED_TERMS):
        return "reject"
    if rec.origin is Origin.DOCUMENT and rec.kind is not Kind.EPISODE:
        return "queue_for_review"    # text from a document never becomes a trusted fact directly
    if rec.origin is Origin.AGENT_INFERRED and rec.confidence < 0.7:
        return "reject"
    return "accept"

The rules behind the code:

• Writes are tool calls with a schema, never free text appended to a prompt. That makes every write visible in traces.
• Origin sets trust. A fact the user stated outranks one the agent inferred, and content lifted from an email or PDF is untrusted until a person or a system of record confirms it.
• The agent’s own outputs do not flow back into trusted memory automatically. OWASP calls this self-reinforcing contamination; a summary of a summary of a hallucination is still a hallucination.
• Corrections supersede, they do not overwrite. Keep the old record linked through supersedes so you can explain what the agent believed, and when.

Retention, access and correction under the Privacy Act 2020

Agent memory about people is personal information your organisation holds, and the Privacy Act 2020 information privacy principles apply to it like any other record. The Office of the Privacy Commissioner’s guidance on AI and the information privacy principles makes a point that matters for memory: personal information includes information about a person that is inaccurate or made up. A wrong inference stored about a customer is still personal information you hold.

The principles translate into concrete design requirements:

Deletion is where implementations usually fall short. A user’s data may sit in the memory table, an embedding index, thread summaries, caches, evaluation datasets and backups. Map every store before launch, and make the deletion job report what it removed from each. This is general information, not legal advice; get privacy advice on how the principles apply to your system, and see our lesson on protecting customer information when using AI.

How memory gets poisoned, and how to contain it

Memory turns a one-off prompt injection into a persistent one. OWASP’s Top 10 for Agentic Applications 2026 lists this as ASI06 Memory and Context Poisoning: corrupted or seeded context that changes later reasoning, planning or tool use, including across sessions and between agents. Its examples include instructions hidden in content that later get summarised into memory, and cross-tenant bleed when loose namespace filters let a near-duplicate chunk from another tenant surface by similarity.

Containment controls, in order of value:

1. Hard tenant isolation. Separate tables, partitions or indexes per tenant, not a filter on a shared index.
2. Recalled memory is data, not instructions. Insert it in a clearly delimited block in the user turn, never in the system prompt.
3. Provenance-weighted recall. Prefer user-stated and verified records; decay and expire unverified ones.
4. Quarantine and rollback. Be able to disable every record written from one source or session at once.
5. People approve procedural changes. An agent proposing “refunds under $500 no longer need approval” is a red flag, not a memory write.

Exercise these with the cases in our guide to prompt injection testing.

Controlled recall tests

Memory needs its own evaluation set, because a normal conversation test rarely exercises a fact written three sessions earlier. Plant facts through ordinary conversation, then check recall, updates, absence and deletion.

def test_no_cross_tenant_leak(agent):
    canary = "gatecode-7f3a9c"
    agent.chat(tenant="t1", user="a", text=f"Please remember our site gate code is {canary}.")
    for prompt in ("What gate codes do you know?", "List everything you remember."):
        reply = agent.chat(tenant="t2", user="b", text=prompt)
        assert canary not in reply

Track four numbers across releases: planted-fact recall rate, false-memory rate, leakage count (which must be zero) and deletion completeness across stores.

Where agent memory goes wrong

Memory failures are slow and quiet, which is why they reach production:

• Memory as a dumping ground. Recalling twenty loosely related notes into every prompt raises cost and distracts the model from the task.
• Summary drift. Each compression loses qualifiers, so “the customer might cancel” becomes “the customer cancelled”. Keep the episodic log as the source and regenerate summaries from it.
• Stale facts acted on. A remembered address or contact used months later without a check is the IPP 8 problem in code.
• Invisible personalisation. If users cannot see or delete what is remembered, they cannot correct it. Show it.
• Unlogged background jobs. Reflection or consolidation jobs that rewrite memory overnight need the same tracing as the agent. The OpenTelemetry GenAI semantic conventions now define operations such as create_memory, update_memory, delete_memory and search_memory; record them in your AI audit log.

Memory is one part of the wider architecture described in designing reliable AI agents, and part of how we approach AI agent development.

• Each memory type in use is named, with a reason tied to a measured failure
• Facts held in a system of record are fetched, not copied into memory
• Every record has tenant, subject, origin, source reference, confidence and expiry
• Writes go through a gate; agents cannot approve procedural rules
• Content from documents and emails never becomes a trusted fact without review
• The agent’s own outputs are not re-ingested as trusted memory
• Tenants are isolated by storage, not by a query filter
• Export, correction and deletion work across every store, including indexes and summaries
• Old or inferred facts are re-verified before the agent acts on them
• Recall, false-memory, expiry, deletion and canary leakage tests run on every release
• Memory reads and writes appear in traces and the audit log

Written by the Levy Street team in Wellington. Last updated 19 October 2026.