memory-design
/memory-design
Design memory for an LLM agent — what to keep, where to keep it, and when memory hurts more than it helps. Use when the user is adding memory to an agent and mentions short-term memory, long-term memory, episodic, semantic, conversation history, summary memory, vector memory, memory store, mem0, Letta, MemGPT, or asks "should this agent remember?" / "why is the agent recalling the wrong thing?".
- Author
- cobusgreyling ↗
- Repository
- agent-skills ↗
- Licence
- Apache-2.0
- Last repository change
- 08.07.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 08.07.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Design memory for an LLM agent — what to keep, where to keep it, and when memory hurts more than it helps. Use when the user is adding memory to an agent and mentions short-term memory, long-term memory, episodic, semantic, conversation history, summary memory, vector memory, memory store, mem0, Letta, MemGPT, or asks "should this agent remember?" / "why is the agent recalling the wrong thing?".
Triggers from the description
Original author description
Design memory for an LLM agent — what to keep, where to keep it, and when memory hurts more than it helps. Use when the user is adding memory to an agent and mentions short-term memory, long-term memory, episodic, semantic, conversation history, summary memory, vector memory, memory store, mem0, Letta, MemGPT, or asks "should this agent remember?" / "why is the agent recalling the wrong thing?".
How it works
- When to use this skill
- The four memory types
- Decision flow
- Write rules
- Recall rules
- Anti-patterns to flag immediately
- Questions to ask the user
- The hard line
- Why this exists
- References
SKILL.md preview
---
name: memory-design
description: >-
Design memory for an LLM agent — what to keep, where to keep it, and when
memory hurts more than it helps. Use when the user is adding memory to an
agent and mentions short-term memory, long-term memory, episodic, semantic,
conversation history, summary memory, vector memory, memory store, mem0,
Letta, MemGPT, or asks "should this agent remember?" / "why is the agent
recalling the wrong thing?".
tags:
- memory
- architecture
- context-engineering
- production
---
# Memory Design
Memory is the most over-built and under-designed part of an agent.
The default question is "what should the agent remember?" The better question is "what *must* the agent forget so the next turn works?" Memory that doesn't earn its place poisons recall, inflates cost, and produces confidently wrong answers.
## When to use this skill
- The user is adding "memory" to a chatbot, copilot, or task agent.
- The user reports the agent recalling stale, wrong, or irrelevant facts.
- The user is choosing between full-history, summary, vector store, or a memory framework (mem0, Letta, MemGPT, Zep).
- The user is conflating "context window" with "memory" — they are not the same.
## The four memory types
Distinguish before designing. Mixing them is the root cause of most "memory bugs".
- **Working** — current turn's context. Lives in the prompt. Cleared at end of request.
- **Episodic** — what happened in this session / thread. Indexed by time; recalled by recency or relevance.
- **Semantic** — durable facts about the user, project, world. Indexed by entity; recalled by lookup.
- **Procedural** — how to do things (skills, tool-use patterns, workflows). Indexed by task type; recalled by trigger.
Each has a different write rule, retention policy, and recall mechanism. If your design has one memory store, you have a bug waiting.
## Decision flow
Walk this before adding any memory.
1. **Does the task need information beyond the current turn?** → no? Use no memory. Stateless wins on debuggability.
2. **Is the information lifecycle bounded by the session?** → episodic only. Don't persist past session end.
3. **Is the information a stable fact about the user or world?** → semantic. Write through a typed entity store, not a vector dump.
4. **Is the information a learned pattern of how to act?** → procedural. This is a skill or prompt update, not a memory write.
5. **Does recall ever return contradictory items?** → memory needs conflict resolution, not more recall.
6. **Can the agent operate correctly if memory is empty?** → yes? Memory is an enhancement. No? You've designed a brittle dependency.
## Write rules
- **Write at episode boundaries, not turn boundaries.** Per-turn writes flood the store with low-signal noise.
- **Summarise before writing semantic memory.** Raw conversation chunks make the worst long-term store.
- **Type every memory.** `{kind: 'preference', entity: 'user', key: 'tone', value: 'terse'}` beats a free-text blob.
- **Set a TTL.** No memory is forever. Preferences last months; project state lasts weeks; session state lasts hours.
- **Idempotency on write.** "User prefers terse responses" should not appear 40 times in semantic memory.
## Recall rules
- **Filter before ranking.** Entity match, then time window, then relevance. Vector-only recall returns nostalgia.
- **Recall budget per turn.** ≤5 episodic items, ≤10 semantic items. More is noise.
- **Show provenance.** Every recalled item carries `(source, written_at, confidence)`. The agent reasons about staleness.
- **Conflict resolution is part of recall.** When two facts contradict, latest-write wins by default; surface the conflict for high-stakes decisions.
- **Negative recall matters.** "I checked and found nothing about X" is a valid result. Silent empty recall is a bug.
## Anti-patterns to flag immediately
- **One vector store as "the memory".** Different memory types have different shapes; one store flattens them and ruins recall.
- **Dumping conversation history into RAG.** You get the worst of both: stale chunks, no entity grounding, retrieval drift.
- **Writing every turn.** Signal-to-noise collapses; old facts get buried under restatements.
- **Recalling without filtering by user/session.** Cross-tenant leakage; cross-session confusion.
- **No forgetting.** Memory grows; recall degrades; cost climbs. TTL is not optional.
- **Memory framework as architecture.** "We use mem0" is not a memory design; it's a vendor choice.
- **Confusing context window with memory.** Stuffing the prompt is not memory — it's expensive amnesia.
## Questions to ask the user
1. What **decision** does memory enable that's impossible without it? If you can't name one, you don't need memory.
2. Which memory **type** is each piece — working, episodic, semantic, procedural?
3. What's the **write trigger** — every turn, end of session, explicit save, agent-initiated?
4. What's the **recall budget** per turn — count and tokens?
5. What's the **TTL** per memory type?
6. How does the agent **detect** and **resolve** contradictory memories?
7. What's the **eval** for memory — does loading it improve task success, or just inflate latency?
## The hard line
**If memory makes the agent slower or wronger on a held-out task, delete the memory.** Memory is a load-bearing feature; treat it like one. Default to no memory until evidence forces it.
## Why this exists
Most agent "memory" deployments are vector-store retrieval pipelines re-skinned as memory. They retrieve confidently wrong items, contaminate recall, and degrade with use. Designing for the four memory types separately — with explicit write rules, recall budgets, and TTLs — converts memory from a liability into a feature.
## References
- `references/types.md` — working / episodic / semantic / procedural — what each looks like in storage.
- `references/write-and-recall.md` — patterns for write triggers, recall filters, and conflict resolution.
- `references/frameworks.md` — mem0, Letta, MemGPT, Zep — what each does well, where each leaks.
## Related skills
- Memory is not the same as retrieval — [[rag-vs-context-engineering]].
- Memory contents end up in the prompt — [[context-window-hygiene]].
- Memory writes/reads are spans in the trace — [[agent-observability]].
- Memory shape is set by the architecture — [[agent-architecture-patterns]].
- Memory load is part of cost per task — [[agent-cost-modeling]].
Files in this package (3)
- EXAMPLES.md 2 KB
- SKILL.md 6 KB
- TRANSCRIPT.md 4 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · cobusgreyling/agent-skills | 90 | Apache-2.0 |
| nahid-sparktales/agent-dispatcher | 90 | MIT |
Database snapshot: 13.11.2026 · package version 8316b8c36ae1 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90letta
Full-fledged Letta (MemGPT) stateful agent integration for Google Antigravity. Use when managing persistent long-term memory, retrieving past conversational knowledge, querying or editing core memory blocks (human, persona, project), or routing complex tasks through a… - 90conversation-memory
Persistent memory systems for LLM conversations including short-term, long-term, and entity-based memory Use when: conversation memory, remember, memory persistence, long-term memory, chat history. - 100agent-memory-short-long-term-episodic
Use this skill when architecting conversational agent memory buffers, rolling context summarization, and vector-backed episodic recall. - 95ai-agent-memory-systems
Use this skill when the user says 'agent memory', 'long-term memory', 'conversation memory', 'remember user preferences', 'context window full', 'summarize history', 'episodic memory', 'semantic memory'. Designs what an agent keeps in its context window, what it stores… - 100self-improving-systems
Decide whether your agent actually needs persistent memory, feedback loops, or closed-loop learning, then design the smallest thing that pays for itself. Use when the user says "add memory", "give my agent context management", "make my agent learn", "self-improving /… - 90conversation-memory
Persistent memory systems for LLM conversations including short-term, long-term, and entity-based memory Use when: conversation memory, remember, memory persistence, long-term memory, chat history.