Reverie

Reverie is engineering memory for coding agents. While you and your agent work, it captures the engineering conclusions you reach — invariants, root causes, decisions, corrected assumptions — and brings them back in a later conversation, after they've been reviewed by you and grounded in your code.

Everything lives in one SQLite file on your machine. Reverie is an MCP server: it plugs into Claude Code, Codex CLI, Cursor, OpenCode and Gemini CLI (see Supported harnesses for honest status per harness).

Install

Requires Python 3.12, pip, and git.

Easiest — an isolated environment on your PATH (pipx or uv):

pipx install reverie         # or: uv tool install reverie
reverie install              # configure your agents + ~/.reverie

Plain pip works just as well — install into a virtualenv and run the CLI from there:

python -m venv ~/.reverie-venv
source ~/.reverie-venv/bin/activate     # Windows: .venv\Scripts\activate
pip install reverie
reverie install

Both layouts work. The installer writes the absolute path of the reverie-mcp script into every harness config — harnesses launch MCP servers outside your virtualenv, so a bare command name is not enough. It then starts the written command, performs an MCP initialize handshake, and prints ✓ or ✗ per harness; a failing setup is reported (with the command and the error) instead of "Reverie is ready!". If you later move or delete the environment, reverie status flags the broken path and tells you to re-run reverie install.

reverie install detects which harnesses you have, wires the MCP server into each, writes the agent instructions and the /reverie-review / /reverie-status commands, creates ~/.reverie, detects an LLM API key in your environment (or offers Ollama for local-only), and prints a per-harness summary of exactly what it wrote. Non-interactive: reverie install --all (every detected harness) or --only claude_code,codex; --dry-run previews everything without writing.

Provide a key for one of the supported providers before the step 2 prompt, or choose "Local via Ollama" — see Model providers.

Related MCP server: Leteo

Quick start

1. Open your agent in any project.

2. The first time, the agent asks once: "Reverie isn't on for this repo. Turn it on? (yes / not now / never)". Your answer is remembered; reverie enable / reverie disable flip it any time.

3. Just code. Sessions are automatic per branch. As your agent works it calls observe when it reaches a real engineering conclusion — not for every edit.

4. Review when you like. Conclusions wait as candidates in one review queue across every branch and repo. Run reverie review in a terminal (a calm one-candidate-at-a-time UI), say "show my Reverie candidates" in the chat, or type /reverie-review. Nothing reaches long-term memory without your decision.

5. That's it. In a future conversation, after your agent reads the relevant code it calls query and past conclusions come back with their confidence, grounding and current status — framed as past understanding to verify, never as authoritative context.

How it works

Observe → extract → review → ground → retrieve. Your agent's reasoning is distilled by a prompted extractor into conclusions (not logs), stored with Bayesian confidence in log-odds space, typed relationships to other conclusions, and grounding references (files, symbols, commit). A background maintainer verifies that grounding against your live repository and lets stale conclusions fade. The long version — pipeline, confidence math, edge types — is at ems-gold-seven.vercel.app/how-it-works; the complete design spec is docs/SPEC.md.

Supported harnesses

"Smoke-tested" means what it says: for Claude Code, Codex, Cursor and Gemini CLI the written shapes are verified against each vendor's current docs and the server is tested over real stdio, but nobody has driven a live session — check docs/SMOKE_TEST.md if you want the checklist. Any other MCP client works with the manual snippet in docs/INSTALLATION.md.

Model providers

One provider serves every LLM call (extraction, relationship classification, mode detection). Configure with reverie install or the llm: block of ~/.reverie/config.yaml:

Switching: reverie install --provider anthropic, or edit llm: in ~/.reverie/config.yaml (provider:, and optionally model:, base_url:, api_key_env:, wire_format:). Everything unset is filled from the registry; anything you set explicitly wins. Per-task models: llm.models.extraction / models.classification / models.mode_detection.

Commands

Full reference with flags, examples and exit behaviour: docs/CLI.md.

Glossary

• Conclusion — one engineering belief Reverie stores, e.g. "authentication correctness depends on optimistic token refresh". Stored internally as an Engineering Cognition Unit (ECU) — the schema-level name you'll see in code, exports and the spec.

• Session memory — conclusions captured in the current (repo, branch) context. Automatic, per branch, never closed by you.

• Long-term memory — the Canonical Brain: conclusions you accepted in review, promoted with their relationship edges, shared across branches and repos.

• Review — the human gate. Captured conclusions wait as candidates; only your accept promotes one into long-term memory. Review in the terminal, in the chat, or with /reverie-review.

• Confidence — a 0–1 Bayesian belief strength (computed in log-odds space), set by the conclusion's source type and scope, strengthened by corroboration and retrieval.

• Decay — confidence fades slowly over time (faster for narrow scopes); retrieval reinforcement resets the clock. Narrow, unused conclusions fade first.

• Grounding — every conclusion references files, symbols and the commit it was made on; a background maintainer verifies those against your live repository and deprecates conclusions whose grounding vanished.

• Repo enablement — per-repo on/off state (undecided / enabled / disabled), remembered globally, asked once.

• Engineering Cognition — the research programme this work is part of; the benchmark is EC-Bench.

Privacy and data

• What stays local: everything. The brain is one SQLite file, ~/.reverie/reverie.db (config, agent instructions and slash commands live beside it). No account, no cloud, no telemetry.

• What leaves your machine: only what the LLM features need — the extraction prompt, your agent's reasoning and output, and candidate conclusion pairs for classification — sent to the endpoint you configure. Pick Ollama and nothing leaves your machine at all.

• API keys are read from environment variables only; Reverie never writes them anywhere.

• Export / import: reverie export writes one ZIP (consistent snapshot + manifest); reverie import restores it (--replace takes an automatic backup first). Benchmark outputs, DBs and logs are gitignored — nothing from ~/.reverie is committed.

Uninstall

reverie uninstall                 # removes the harness entries; keeps ~/.reverie
reverie uninstall --delete-data   # also removes ~/.reverie (final export first)

Uninstall shows the full plan — every harness entry it will remove, and whether data will be exported and deleted — and asks one confirmation before touching anything (--yes skips it; the export-before-delete rule always holds). It removes only Reverie's own entries, byte-reverses its merges, and never guesses at edited files. The last step prints the pip uninstall reverie command to run by hand (the running package can't remove itself).

Research and contributing

Reverie ships with EC-Bench (bench/), a harness that runs a real agent through sequential sessions on a target repository with and without memory and judges the transcripts. Honest status: EC-Bench has not shown a clear advantage yet — it is published as a research instrument, not as proof. Method and results: ems-gold-seven.vercel.app/research.

Contributions are welcome — start with CONTRIBUTING.md for setup and ground rules, and the code of conduct.

License

Apache-2.0 © 2026 Mudit Sarda. The extraction prompt (reverie/prompts/extractor_prompt.md) is separately MIT-licensed.

Citation

@software{reverie2026,
  author  = {Sarda, Mudit},
  title   = {Reverie},
  year    = {2026},
  url     = {https://ems-gold-seven.vercel.app/},
  version = {0.2.0}
}

Machine-readable metadata: CITATION.cff.