How it works
How Mnemo remembers
A memory you can read: a graph of nodes and typed edges in six areas, kept as one append-only journal on your machine. It is searched before every message and written to after every run. This is how, from the internals document.
The loop
Every turn, five steps
- 1
Recall
Before the model sees your message, memory is searched for it and what it finds is attached: facts, earlier sessions, pitfalls with their fixes, skills. Recalled items are candidates, never presented as fact.
- 2
Work
Thinking, text and tool calls stream in as they arrive. It reads before it edits, and a change is checked before it is called done.
- 3
Gate
Every tool call passes the permission gate. Reads run; edits and commands ask, unless your mode or rules say otherwise, and a deny rule always holds.
- 4
Steer
Each tool call and its outcome is logged with its subject. A failure steers memory right away, once per distinct failure, so the same mistake is less likely in the same run.
- 5
Reflect
After the run, a clean run reinforces the memories that fed it, and one grounded reflection writes the session record, new facts, the fixes that worked, and a skill when one was shown.
Want to see one? Step through a whole turn.
The graph
Six areas, like a brain
Every node is filed in an area, each named for the part of the brain it is modelled on. A query is routed to the areas its words point at, but routing only biases the search: a mis-routed query still finds its node.
Episodic
Episodes and their outcomes: what happened in each session, and how it ended.
Semantic
Facts about the project and about you. The default home for a memory.
Procedural
Harnesses and skills: how things are done here, step by step.
Spatial
Where things are: repositories, paths, services.
Salience
Pain markers: what hurt, so it is recalled before it hurts again.
Executive
Steering decisions: what was decided about how to work.
Nodes and edges
A node is a list of facts with a history
A node has a kind (aspect, task episode, entity, harness or outcome), an area, a label, its facts and an append-only log. A fact is a key with one current value: writing a new value supersedes the old one, which keeps its id and stays readable as history. Edges are typed, weighted and directed, and count their successes and failures.
SuppliesContextthis memory owes that one correct contextPartOfan aspect belongs to a cluster, such as a projectDerivedFroman episode or outcome cites the memories it usedSupersedesa newer value replaced this one, which is keptActivatedWithrecalled together before: an association that grows with use
The journal
Twelve ways to change it, and none of them erase
State changes only through twelve operations, appended one line each to ~/.mnemo/memory/journal.jsonl. Replaying the journal gives back the graph exactly, so the journal is the source of truth. Several processes share it under a lock, and even deleting a node is soft by default.
CreateNodeAddFactSupersedeFactSetAreaDeleteNodeLinkUnlinkReweightRecordOutcomePushContextCommitLogRecordUsefulness
Recall
What happens to your message first
Embeddings are a deterministic, offline 256-dimension hash by default, or a server you opt in to. Brute force is fine to about 100,000 nodes.