Awesome Memory

Agent memory decision guide

Choose the smallest memory that works.

Memory is a write–manage–read system, not a vector-store checkbox. Start with what the agent must remember, choose the least complex matching pattern, then prove recall improves the task.

  1. Name the memory job
  2. Choose a pattern
  3. Prove it helps

Purpose before storage

Name the memory job

Do not choose a database yet. Write one sentence describing the information that must survive and the decision it should improve.

Working

Finish the current task

Keep plans, tool results, unresolved decisions, and resume state needed now.

Start with
Bounded context and typed checkpoints.
Do not persist
Every intermediate thought or raw tool response.
Search working-memory resources

Factual

Recall what is true

Preserve user preferences, entity facts, decisions, and changing world state.

Start with
Scoped records with source, time, and version.
Do not persist
Unverified inference as durable fact.
Search factual-memory resources

Episodic

Recall what happened

Preserve events, actions, outcomes, feedback, and the order in which they occurred.

Start with
Immutable event IDs and timestamps.
Do not persist
A summary without its supporting episode.
Search episodic-memory resources

Procedural

Reuse what worked

Preserve tested workflows, skills, tool sequences, and recovery procedures.

Start with
Versioned artifacts with scope and tests.
Do not persist
A one-off success as a general rule.
Search procedural-memory resources

Complexity must earn its place

Choose the smallest matching pattern

Start at the top. Move down only when the workload requires the additional structure. Patterns can compose, but each one needs its own write and failure policy.

Five architecture patterns compared by fit, bad fit, controls, and evidence. On small screens, scroll the table horizontally.
Pattern Choose when Bad fit Minimum controls Evidence and catalog
Bounded context + checkpoints A task needs current state, compaction, or deterministic resume. Facts must survive many sessions or be shared across users. Token budget, typed checkpoint, expiry, and resume test. MemGPT
Browse working memory
Retrieval store Many independent text or fact records must be recalled by meaning or exact term. Relationships, contradictions, or changing truth dominate the workload. Write filter, tenant key, provenance, hybrid retrieval, and abstention. LongMemEval
Browse retrieval
Temporal fact graph Facts change, entities relate, or answers require multi-hop and time-aware reasoning. Recall is small, flat, and rarely updated. Event and validity time, conflict rules, source links, and deletion traversal. Zep / Graphiti paper
Browse temporal graphs
Episodic → semantic layers Repeated interactions must become stable facts without losing event history. The system cannot explain or reverse consolidation. Immutable episodes, promotion rule, source links, correction, and rollback. Generative Agents
Browse layered memory
Procedural library Successful actions or workflows repeat across comparable tasks. Tools change quickly or success came from one unreviewed run. Version, applicability scope, executable test, approval, and rollback. Agent Workflow Memory
Browse procedural memory

A fast routing test

  1. No cross-session need? Use bounded context and checkpoints.
  2. Independent records? Start with a retrieval store.
  3. Changing or related facts? Add temporal graph structure.
  4. Events must become durable knowledge? Separate episodes from promoted facts.
  5. Actions repeat? Store tested procedures separately from facts.

Architecture is a hypothesis

Prove memory helps

A relevant retrieval is not a successful agent outcome. Evaluate the full path from write to answer or action, including queries that should not use memory.

Baselines

Compare against less memory

  • No persistent memory.
  • Full context, when feasible.
  • The simplest retrieval-only design.

Task abilities

Test the failures users notice

  • Information extraction and multi-session reasoning.
  • Temporal reasoning and knowledge updates.
  • Abstention when evidence is missing.

System cost

Measure the whole receipt

  • Recall latency at p50 and p95.
  • Input and output tokens per task.
  • Storage footprint and cold-start time.

No-harm checks

Try to make memory fail

  • Stale, contradicted, poisoned, and deleted records.
  • Cross-user and cross-tenant isolation.
  • Tasks where memory should remain unused.

Start with the five abilities defined by LongMemEval, then add workload-specific tasks. Use LoCoMo for long-conversation reasoning coverage. Neither benchmark replaces production traces or deletion tests.

Keep the guide falsifiable

Found a missing pattern or weak claim?

Submit a primary source, name the workload it changes, and state the failure mode. A new pattern belongs here only if it changes a concrete architecture decision.

Suggest evidence Discuss the taxonomy

Primary references

  1. A Survey on the Memory Mechanism of Large Language Model based Agents
  2. MemGPT: Towards LLMs as Operating Systems
  3. Zep: A Temporal Knowledge Graph Architecture for Agent Memory
  4. Generative Agents: Interactive Simulacra of Human Behavior
  5. LongMemEval: Benchmarking Chat Assistants on Long-Term Interactive Memory
  6. Evaluating Very Long-Term Conversational Memory of LLM Agents (LoCoMo)
  7. Agent Workflow Memory

These papers motivate the patterns and evaluation questions. They do not endorse this guide or prove that one implementation is best.