Project memory
Decisions, conventions, gotchas, and todos that persist across sessions, linked to code and flagged when it changes.
Agents forget everything between sessions. Project memory is a small store of facts about the codebase that should not be rediscovered every time: why something is done a certain way, what not to touch, what is still to do.
Kinds
| Kind | Example |
|---|---|
decision | Passwords are hashed with argon2, never bcrypt. |
convention | Handlers return Result objects instead of throwing. |
gotcha | parseToken accepts sub.exp only; anything else throws. |
todo | Move notify to the job queue. |
Saving a memory
An agent calls remember; you can use the CLI:
remimem memory add "Never log passwords in authenticateUser." --kind convention --symbol authenticateUserStored memory m_7c03d27f (convention), linked to src/auth.ts authenticateUser.Links tie a memory to code:
--symbol(orsymbolsin the tool) links to one symbol. It must resolve to exactly one; an ambiguous name is reported back and the memory is stored unlinked. Use a qualified name such asUserService.loginto disambiguate.--path(orpaths) links to a whole file.
Both are optional and repeatable. An unlinked memory still works; it is just found by matching the task instead.
When memories appear
get_context puts relevant memories at the top of its answer:
=== Project memory (decisions and conventions recorded for this repo) ===
[convention] m_7c03d27f
Never log passwords in authenticateUser.
(linked: src/auth.ts authenticateUser)A memory is included when:
- It is linked to the results. Linked to a file that is in the results, or to a symbol that is itself one of the results. These are always shown.
- It matches the task. It contains at least half of the task's words (
memoryMinKeywordMatch), or its meaning is close enough (cosine similarity at leastmemoryMinSimilarity, 0.4). One shared word is not enough. At mostmemoryLimit(5) are added this way.
Memory takes at most a quarter of the budget. search_code never adds memories; recall searches them directly.
Staleness
Each link stores a fingerprint of the code it points at. After every index run, a memory whose linked symbol or file changed, or disappeared, is marked stale:
[decision] m_20283783 STALE: linked code has changed since this was writtenStale memories are still shown, marked, so the agent can judge whether they still hold. If the code changes back, the mark goes away. To refresh one, delete it and add it again against the current code.
Sharing through git
Every change is mirrored to .remimem/memory.json, sorted by id with one memory per line:
{
"version": 1,
"memories": [
{"id":"m_20283783","kind":"decision","text":"Passwords are hashed with the fixture salt.","tags":["security"],"createdAt":"...","updatedAt":"...","links":[...]}
]
}That file is the source of truth. Commit it, and teammates get your memories on their next git pull: remimem notices the file changed and loads it. Deleting .remimem/index.db loses nothing; the next index restores memories from the file. Staleness is not stored in the file, because it depends on each person's checkout.
See Sharing memory with a team for the workflow, and how merges behave.
Managing memories
remimem memory list # everything
remimem memory list "password" # search
remimem memory list --kind todo # one kind
remimem memory rm m_7c03d27f # deleteThe agent equivalents are recall and forget.