Agent systems have three memory layers, and confusing them is the main reason an agent “forgets” or “knows too much.”
1. Memory (long-term facts)
Short facts, always valid: “user Ruper, Windows, speaks Russian, likes brevity.” Injected into every context. Keep it compact — it's a cost on every request.
2. Skills (procedural memory)
Instructions “how to do X”, loaded on trigger. Not always injected — only when the task matches the description. This is a new form of code: instructive Markdown with YAML metadata.
3. CLAUDE.md / project context
Project config: stack, commands, rules. Lives in the repo, loaded in sessions with that repo.
Placement rules
- A fact about the user → memory.
- A procedure for a kind of task → skill.
- Project details → CLAUDE.md.
- A temporary TODO → nowhere (in the chat, in a task).
A tiny test: if it's needed in every dialogue — memory. If only for a specific kind of task — skill. If only in this repo — CLAUDE.md.
