Skip to content
⚠️ Before You Start
Risk: High
Duration: 3-4 hours
Last Validated: Not yet validated (draft)
Kind: Decision guide
Risk Note: High (wrong design leaks personal data across users or cannot be erased)

Choose memory layers and stores: short-term, long-term and episodic

Draft outline: not validated

Drafted with AI from official sources on 16 Oct 2026. Do not use on a live system until it is written, dry-run by someone other than the author and signed off (planned 2026-12-08). Author: James · dry-run: Sanjay Sarvesh · sign-off: Prasanna. Work items: AGT-04-T01, AGT-04-T02, AGT-04-T03, AGT-04-T04.

1. Summary

When an agent must remember across turns or sessions, or when an existing memory design is hard to purge or slow.

Risk: High (wrong design leaks personal data across users or cannot be erased). Typical duration: 3-4 hours.

2. When to use and when not to

Use it when: When an agent must remember across turns or sessions, or when an existing memory design is hard to purge or slow.

Do not use it when: to be written by the author.

3. What you must know first

  • Checkpointers hold thread-scoped state; stores hold cross-thread data
  • Store namespaces are tuples such as (tenant, user, 'memories') and support prefix search
  • Store semantic search needs an index with embed, dims and fields
  • Azure AI Search can act as a vector store for long-term memory
  • Azure Managed Redis suits short-lived hot context

4. Options

Outline of the decision process; the author describes each option.

  1. List what the agent must remember and for how long
  2. Map each item to short-term, long-term semantic or episodic memory
  3. Pick the store per layer from the decision YAML defaults
  4. Design keys and namespaces with tenant and user first
  5. Set retention and the purge mechanism per layer
  6. Agree the extraction policy for long-term memory with the DPO
  7. Record the decision and link the erasure runbook

Draft snippet: Memory layers, stores and retention

# docs/decisions/agent-memory.yaml
memory_layers:
  short_term:
    what: conversation and graph state for one thread
    store: LangGraph PostgresSaver on Azure Database for PostgreSQL
    key: thread_id = "<tenant>:<user>:<session>"
    retention_days: 30
  long_term_semantic:
    what: facts and preferences about a user
    store: LangGraph PostgresStore with pgvector index
    namespace: [tenant, user, "preferences"]
    retention_days: 365
    write_policy: extract on session end, user can view and delete
  episodic:
    what: summaries of past tasks used as examples
    store: Azure AI Search index agent-episodes
    filter_field: user_id
    retention_days: 180
  cache:
    what: hot session context
    store: Azure Managed Redis
    ttl_seconds: 3600
privacy:
  pii_in_long_term: minimised, no special category data
  erasure_runbook: PB-AGT-04-03

Snippets to add:

  • snippets/docs/decisions/agent-memory.yaml: Memory layer decision record (yaml)
  • snippets/docs/privacy/memory-data-map.md: Data map template (markdown)

5. Decision table

Situation Choose Why
to be written

To be written by the author from the outline above.

7. Known issues and fixes

Symptom Likely cause Fix
User sees another user's preferences Namespace lacks the user ID Put tenant and user at the start of every namespace and filter on them
Long-term memory full of noise Every message saved as a memory Extract facts at session end with a schema
Erasure takes days Data spread across stores without keys Use consistent tenant and user keys in all layers

8. Monitoring and alerts

Signal Alert when Action
Memory items written per session More than 3x the design figure Review the extraction prompt

9. AWS and open-source equivalents

AgentCore Memory offers short-term events per session and long-term records extracted asynchronously. OpenAI Agents SDK sessions (SQLite, Redis, SQLAlchemy, encrypted) cover short-term history.

10. Validation record

Pending. Planned dry-run scenario: A second engineer designs memory for a sample HR assistant with the guide and must produce namespaces that support per-user erasure and retention for every layer, approved by the DPO reviewer.

11. Sources