Get started

Cognitive Memory

A memory service for agents. It stores durable facts, holds open the ones that contradict each other, decides what to put in front of a model each turn, and tells you why. The retrieval path is deterministic by design, and the reasoning behind every threshold is written down because the numbers are only defensible with it.

On this page

The shape of it

Most “memory” for agents is a list of strings and a similarity search. That is enough to make a demo feel like recall, and it fails in three specific ways that show up in production.

It cannot hold a contradiction. Two stored claims that cannot both be true are, in a flat list, indistinguishable from two unrelated facts. There is nowhere to put “these disagree” — so one of them quietly wins, and the agent proceeds on a premise the user has already contradicted.

It has no notion of cost. A similarity search returns k results, and k is chosen by whoever wrote the call. As the store grows, so does the prompt, and the material included falls into two groups: things that were relevant, and things that merely looked like they might be. The second group is what Chroma’s 2025 context-rot report measures.

It cannot say why something matched. A cosine score is not an explanation. When a user asks why their agent believes something, the honest answer is a floating point number, which is not an answer.

This service is built around those three gaps. It stores tiers, so cost per turn is a decision rather than an accident. It stores contradictions as first-class rows. And every injection is recorded with the rule that produced it, so the dashboard can show the exact block a model is about to receive.

The model page is the long version of this argument.

How a turn works

Five steps, in this order. The order is the design: capture runs deterministically before anything optional, and the prompt is assembled before the model is called rather than assembled from whatever the model remembered to ask for.

  1. Capture. Deterministic patterns first: URLs, assignments, stated requirements. No model, no refusal, no silent loss. See what gets learned.
  2. Reconcile. Restatements are folded into what is held — but only when the merge keeps every distinctive token, or both entries are kept. See reconciliation.
  3. File. Into a tier. New facts land hot, so the next prompt already has them. See the four tiers.
  4. Plan. A gist line for everything; a full body only for identifiers the message named, unresolved contradictions, and weak domains. See what goes into the prompt.
  5. Inject. Inside a token budget that reports when it truncated.

Measured

pnpm --filter cognitive-memory measure, on 200 stored memories. The interesting figure is the last row: 77% fewer tokens than injecting everything, with recall that does not depend on a model being available.

Measurep50
Recall5.0 ms
Context build2.9 ms
Index + triggers1,320 tokens
Every body3,643 tokens

Every context build is also recorded — the block, the reason each line was included, its token cost, and the identifiers the triggering message named. That is what makes analytics an argument rather than a decoration: 118k tokens is a number with no action attached, and “104k of it was index lines and 2k was full bodies” says the store has nothing worth promoting, which has the opposite fix from raising the ceiling.

The figures are reproduced in self-hosting, with the command that regenerates them.

Where to go next

If you want it working, the quickstart is two calls and a key. If you are deciding whether to trust it, read what goes into the prompt and recall — those two pages are where the design bets are, and both are the ones to check against the code.

The smallest useful integration is a context build before the model runs and a turn recorded after it finishes. Nothing else is required, and nothing else is what makes memory work:

sh
# what the agent should know before it answerscurl -X POST $COGNITIVE_MEMORY_URL/api/v1/context \  -H "Authorization: Bearer $COGNITIVE_MEMORY_KEY" \  -H "content-type: application/json" \  -d '{"userMessage":"deploy ZQ7X4M2K to staging"}'# what it should remember from the finished turncurl -X POST $COGNITIVE_MEMORY_URL/api/v1/turns \  -H "Authorization: Bearer $COGNITIVE_MEMORY_KEY" \  -H "content-type: application/json" \  -d '{"userMessage":"...","assistantResponse":"..."}'