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.