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
}
- 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)