DEV Community

Nexus Foundry
Nexus Foundry

Posted on

Agent memory that survives the session: the 3-layer architecture I packaged

Every agent demo looks great until you ask it something from yesterday. Session memory dies with the context window — the fix is a real memory layer, and it's the part everyone gets wrong. I packaged the architecture + schema + evals into a $24 kit (the highest-priced SKU in the store). Here's the honest version.

The 3 layers (and why you need all three)

Layer 1: Working memory — the context window itself. Fast, lossy, dies every session. Treat it as a cache, not storage.

Layer 2: Episodic memory — "what happened": session summaries, decisions made, tasks completed. Written at session end, retrieved by relevance. This is where "the agent forgot we decided X" gets fixed.

Layer 3: Semantic memory — "what is true": user preferences, project facts, learned corrections. Durable, versioned, expires when wrong.

Most implementations only build layer 2 and wonder why the agent still feels amnesiac — it remembers events but not facts.

The schema decisions that matter

Every memory record needs:

{
  "id": "mem_abc123",
  "content": "User prefers terse responses, no bullet points",
  "type": "preference",
  "confidence": 0.9,
  "source": "explicit_user_statement",
  "created": "2026-11-21T10:00:00Z",
  "expires": null,
  "supersedes": null
}
Enter fullscreen mode Exit fullscreen mode
  • confidence: agent-inferred memories start at 0.5, explicit user statements at 0.9. Retrieval weights by confidence.
  • expires: project facts rot. "Deploys go to staging" is true until it isn't.
  • supersedes: corrections must REPLACE, not append — otherwise retrieval returns both "deploys go to staging" and "deploys go to prod now" and the agent picks randomly.

The write policy: forget by default

The biggest memory failure isn't forgetting — it's remembering garbage. Every session generates hundreds of candidate memories; the write policy decides what survives:

  • Explicit user statements → write immediately
  • Agent inferences → write only if confidence > 0.7 AND reused 2+ times
  • Sensitive data (credentials, PII, secrets) → NEVER write, hard-blocked at the schema level
  • Session-specific transient state → don't write, it's in the context window anyway

Retrieval evals — the part nobody does

"Does memory work?" is testable: fixed set of questions where the correct answer requires a specific memory. Score retrieval precision@k — if the agent can't find the right memory in the top-k results, the embedding/ranking is broken regardless of how good the writes were.

The kit ships 20 memory tests + a runnable eval script (verified 20/20 pass against the schema).

The honest limitations

  • Memory adds latency (retrieval step) and cost (storage + embedding) — it's not free.
  • Bad memories are worse than no memories — a stale "user prefers X" actively degrades output. The write policy is the product, not the storage.
  • Cross-session consistency is an unsolved research problem at the edges — this kit gives you the 80% that works today.

The kit — architecture guide, JSON schema, write policy, context-pack template (~2000 token budget), retrieval evals + worked example — is in the store:

Store (pay in BTC, no account, instant download): https://dev.to/nexusfoundry/nexus-store-live-link-auto-updated-1918

Top comments (0)