cogito-mem

How it works

Collect, keep, find

Cogi has three jobs. Each message you and Claude exchange is a nut; your memory is Cogi's hollow.

1

Collect

When Claude finishes an answer, a hook passes the new messages to Cogi, in the background. Your chat never waits.

2

Keep

Cogi stores each message word for word with its date, and indexes it two ways: by its words and by its meaning.

3

Find

Asked a question, Cogi searches both ways, merges the results and hands back the best few messages.

Two ways nuts come back

By themselves

With each prompt, Cogi adds what earlier sessions said about it (up to 300 tokens), and nothing when nothing matches well. A new session starts with how the last one in the same project ended.

When Claude asks

When you refer to something earlier, Claude searches the memory itself (memory_query) and reads up to 1,000 tokens. Saying "check your memory" makes sure it does.

The basket: how much comes back

Each search fills a basket of at most 1,000 tokens, about 750 words or a page and a half. Tokens are how AI models count text.

Why tokens, not "5 results"? Messages differ a lot in size, and Claude's room is counted in tokens. On LoCoMo, 1,000 tokens answer as well as the whole conversation (see the results).

The hollow: your memory

Your memory is called yourname-hollow, for example ksirg-hollow. Every Claude Code session, in every project, goes into it, so Claude can recall across sessions and projects. Each session keeps its own label inside, and a search looks through them all.

The status shows what is inside:

Terminal
curl -s localhost:7327/v1/status
"embedder": { "state": "ready", … },
"namespaces": {
  "ksirg-hollow": { "messages": 100, "items": 142, "vectors": 142, "pending": 0 }
}
messagesmessages kept, yours and Claude's
itemsthe pieces they were cut into
vectorspieces already findable by meaning
pendingpieces still waiting for that (usually 0)

To use another name, set COGITO_MEM_NAMESPACE, or install with --config memory_name=…. Changing it starts a new, empty hollow.

What Cogi keeps, and what it skips

Keeps

  • What you type
  • Claude's answers
  • What each turn did: the commands Claude ran (and which failed) and the files it touched
  • When each was said, and in which session

Skips

  • Tool output, file contents and Claude's thinking
  • System messages and the summary of a compacted session
  • Anything you put inside <private>…</private>
  • Secrets: API keys, tokens and passwords become [redacted]
Under the hood