How it works
Four tiers
A tier is a cost decision. L0 and L1 are written into the prompt every turn; L2 and L3 cost nothing until something promotes or recalls them.
On this page
A tier is a cost decision
L0 and L1 are written into the prompt every turn. L2 and L3 cost nothing until something promotes or recalls them. That is the whole idea: the per-turn budget is a decision you make about a fact, rather than an accident of how many facts you happen to have.
| Tier | Name | Holds | Cost |
|---|---|---|---|
| L0 | Pinned | Unresolved contradictions, weak domains, correction notices | Full body, always |
| L1 | Hot cache | Newly learned and pre-staged facts | Index line, body on trigger |
| L2 | Warm store | Candidates scored against each turn | Nothing until promoted |
| L3 | Cold archive | Everything else, still recallable | Nothing until recalled |
The register an agent actually stores is URLs, build ids, ports, paths and conventions — short, identifier-shaped, and each one worth a great deal if it is the right one. A tier that puts a full body on all of them would spend the entire budget being right about the least interesting facts held.
New statements land in L1
Immediately, not after a promotion pass. Waiting for a pass added a turn of latency, which meant a fact you taught on one turn was still missing from the very next prompt — the most visible possible way for memory to look broken.
A fact is demoted when it stops earning its place, not on a schedule. Promotion and demotion are both explicit, from the API or the library, and the tier is visible wherever a memory is listed.
Promotion is a decision with a cost attached, which is why it is a decision. PATCH /v1/memories/:id is not something the service does for you on a timer.
What happens when L1 fills up
L1 is capped by the token budget. When the cap bites, the response says truncated: true rather than dropping the tail in silence, and the least recently accessed entries are the ones that lose their place.
A store that is permanently over budget therefore converges on a small hot set of frequently-touched facts. That is a legitimate outcome — and the one thing to check before treating it as a bug is whether the budget is set for the store you have, or the store you had. Analytics separates index spend from body spend, which distinguishes “raise the ceiling” from “promote more”.
The ceiling itself is COGNITIVE_MEMORY_MAX_TOTAL_TOKENS, overridable per organisation; see self-hosting.
What is pinned at L0
L0 is the only tier whose cost does not depend on the budget. Three things land there, and they share a property: the agent is worse off without them, in a way that is not proportional to how interesting they are.
- Unresolved contradictions. The whole point is that the agent sees both sides rather than picking one. See contradictions.
- Weak domains. A domain this agent has been unreliable in, with its known failure patterns. See the self-model.
- Correction notices. When the incoming message pattern-matches an explicit correction, the user is visibly changing their mind, which is the single most reliable signal that an assumption is stale. See what goes into the prompt.
L0 is injected in full regardless of budget, by design. A budget that can silently drop a contradiction is a budget that can resolve one without anyone deciding to.