How Reverie works

Reverie keeps conclusions, not facts. Each one is the smallest self-contained piece of engineering understanding that could change a future decision.

That TokenManager.refresh() is called before cache.clear() is information. That cache invalidation must follow token refresh, because clearing the cache first serves stale tokens, is a conclusion.

Every candidate faces three questions. So what? Is it a conclusion, not a fact? Future session. Would knowing it change how an engineer approaches a future task? Independence. Is it understandable without the original conversation? Each record holds one conclusion, and a self-review pass rejects anything an engineer could get by reading the code. The extractor keeps conclusions and rejects facts, code descriptions, process steps and summaries. Zero is a valid output.

A kept conclusion is an Engineering Cognition Unit (ECU). It has one of eight types: implication, constraint, principle, decision, observation, pattern, invariant and trade-off. It has one of seven scope levels, from engineering to subsystem, plus a path: engineering, domain, organization, project, repo, module and subsystem. And it has one of six statuses: active, challenged, superseded, deprecated, open_question and archived.

Reverie keeps two stores, called brains. The session brain is per repo and branch. What your agent concludes goes in at once, unreviewed, and ranks slightly lower than reviewed conclusions, so the current session benefits immediately. The canonical brain is reviewed, long-term and shared across projects.

The boundary is hard. Evidence about long-term conclusions waits as pending until its source is accepted.

When the session ends, you review in the terminal: open questions first, then accept, reject or skip, per group or per item. Skipped items carry into the next session.

The one exception. When your agent finds verified evidence about a conclusion it has just retrieved, it can update that conclusion straight away. This is reconsolidation, and the update is recorded on the conclusion. So: nothing extracted from a session becomes long-term memory until you review it, and reconsolidation is the documented exception.

The split came from a practical problem: one store either fills with noise or blocks in-session use. It later turned out to mirror a well-known account of biological memory, fast encoding and slow consolidation. Read the paper →

Confidence. A conclusion starts from a prior set by how it was reached and by its scope. Supporting conclusions raise it and contradicting ones lower it, in log-odds, weighted by similarity and by the other conclusion’s confidence. Every update is stored and can be reversed. Unused conclusions fade at a rate set by scope, and retrieval reinforces them.

Relationships. Conclusions relate in four ways: supports, contradicts, supersedes and depends_on.

Contradictions. A computable pre-check comes first, then adjudication. The existing conclusion is marked challenged, never hidden. After a scope-dependent time it becomes an open_question, and you choose: investigate, prefer one, mark both valid in different contexts, or archive.

Supersession. Accepted wording never changes. A new conclusion replaces the old one, which is frozen, kept and linked. Dependents of a weakened conclusion are challenged.

Step through one example below. A is the conclusion we follow; B supports it and C later contradicts it.

The code has the last word. Each conclusion records the files, symbols and commit at extraction. In the background, Reverie checks them against your repository from time to time. Scope decides what a deletion retires, so principles survive and module-level conclusions don’t:

Conclusions that depend on a retired one are challenged, and you’re told at your next review. Being far behind HEAD is flagged, but it never retires anything.

Your agent asks, after reading the code. Reverie doesn’t load memory at the start of a session. Our first version did, and on our benchmark the agent trusted memory over the code and did worse. EC-Bench →

When your agent asks, in order:

1. Reverie infers a task mode: debugging, implementation, investigation, planning or architecture.
2. It searches both brains.
3. It filters results by status, scope and relevance.
4. It ranks them by similarity, confidence after decay, session activity and how connected a conclusion is.
5. It groups each result with the conclusions that support, contradict or depend on it, or replace it, and fits everything into a budget that depends on the mode.

The agent receives the record in Fig. 3, with a framing note: past engineering understanding, verify against current code. One honest limit: agents don’t always ask when they should. Asking is an instruction in the agent’s instructions file, not something Reverie can enforce.

Storage. One SQLite file at ~/.ec/ec.db, shared by your projects. There is no Reverie account.

Server. A local MCP server, spawned by your agent over stdio. It runs maintenance in the background.

Across agents and models. Memory lives in one file, not inside your agent, so changing the model your agent runs keeps your memory. Agents added later share the same file. Setup instructions are in the repository ↗.

Models and data. Reverie stores memory locally. Extraction and classification use an LLM endpoint: hosted by default, or a local model through Ollama. What it sends there is the prompt, the agent’s reasoning and final output, and candidate pairs of conclusions for classification. The database, the embeddings and retrieval never leave your machine.

In the code, Reverie’s package, commands and tools use the prefix ec, for Engineering Cognition, the research program behind it.