dreamd
Agent memory you can audit. When a memory goes bad, trace it to its source, see what it fed, and remove it.
dreamd is local-first, long-term memory for AI agents. Every memory is a line in a file in your repo, every lesson your agents learn cites the events it came from, and each dream cycle commits its lessons to git. When an agent acts on something wrong, you can find the memory that caused it, see which lessons it fed, and take it out, with a receipt.```bash
npx -y dreamd-mcp setup # scaffold .agent/ and wire your harness
npx -y dreamd-mcp # MCP server (stdio): what the harness spawns
Recorded live on dreamd 1.2.0, sped up 1.5x: `blame` finds the event behind a bad answer, `forget` removes it with a receipt, and the same query comes back without it. Tape: docs/assets/blame-forget.tape.
Works today with Claude Code, Cursor, Cline and other MCP-aware harnesses. Self-hosted, single binary, Apache-2.0 core.
If you want agent memory you can trace and undo, star the repo to follow releases. When a memory goes wrong, an issue with the `blame` output helps us fix it.
---
## Why auditable memory
Memory is the layer of an agent stack you usually can't see into. A prompt can be read and a model can be swapped, but when memory goes wrong there is rarely a way to tell what the agent believed, where that belief came from, or what else it touched.
That matters more now that memory is an attack surface. The OWASP Top 10 for Agentic Applications lists **memory and context poisoning (ASI06)**: an attacker, a bad tool result or a plain mistake plants a "fact" that the agent keeps acting on in later sessions. The defenses OWASP points to start with knowing the source of every memory and being able to remove one cleanly (OWASP agentic top 10).
dreamd is built for that response:
| You need to | dreamd gives you |
|---|---|
| See what drove an answer | `dreamd blame ` lists the stored memories behind a recall, with ids, timestamps, source and score. `dreamd recall --explain` prints the salience factors for each hit |
| Know where a lesson came from | Every lesson in `LESSONS.md` cites the episodic events it was promoted from, and the provenance ledger records which event fed which lesson and index entry |
| Check the record is consistent | `dreamd doctor --provenance` recomputes the ledger's Merkle root and lists orphan, missing and corrupt edges. Read-only |
| Remove a bad memory | `dreamd forget ` removes the event and the lesson state that names it. `--dry-run` shows what would change; `--proof ` writes a `forget-receipt/1.0` file |
| Review what agents learned | `.agent/` is committed with your code, and each dream cycle commits its output as `dreamd: cycle YYYY-MM-DD`. Review new lessons with `git diff` or in a pull request, and undo a cycle with `git revert` |
| Read everything yourself | Plain JSONL and Markdown. `cat`, `grep` and `git log` work on every byte |
**What dreamd does not do.** It does not detect or block poisoned writes, and it does not filter injected lesson content (SECURITY.md). `source_harness` is asserted by the caller, not verified. The provenance ledger and the forget receipt are unsigned, and there are no trust labels yet. dreamd makes bad memory traceable and removable; it does not make it impossible. See Roadmap for what comes next.
---
## The audit loop in four commands
Say an agent keeps repeating advice you know is wrong.```bash
# 1. Find the memories behind it
npx -y dreamd-mcp blame "deploy without tests" --explain
# 2. Check the lesson it came from and what that lesson cites
cat .agent/semantic/LESSONS.md
npx -y dreamd-mcp doctor --provenance
# 3. Preview, then remove the bad event (stop the daemon, `npx -y dreamd-mcp watch`, first; forget refuses while it runs)
npx -y dreamd-mcp forget evt_... --dry-run
npx -y dreamd-mcp forget evt_... --proof forget-receipt.json
# 4. Review the change like code
git diff .agent/
After a forget, doctor --provenance reports the removed event's old ledger edges as orphans and exits 1. That is expected: the ledger is append-only, so it keeps the record that the event once existed.
To undo a whole dream cycle instead, git revert its dreamd: cycle commit with the daemon stopped, then run npx -y dreamd-mcp doctor --repair to rebuild the recall index.
Install
npm (recommended)```bash
npx -y dreamd-mcp setup # scaffold .agent/ and write the harness MCP config
npx -y dreamd-mcp # MCP server (stdio): your harness spawns this
stdio is the default transport. `dreamd mcp --bind 127.0.0.1:` is an opt-in Streamable HTTP server at `/mcp`. It is unauthenticated, and it is only in source builds with `--features mcp-http`. See docs/mcp-transports.md.
dreamd needs a project root sentinel (`.git/`, `Cargo.toml`, `package.json` or `pyproject.toml`).
`setup` prompts when it has a TTY. In scripts and non-interactive shells, pass `--yes --harness claude · cursor · both` (`--harness none` or `--no-write-mcp` scaffolds without touching any MCP config).
### Cargo```bash
cargo install dreamd --version ^1.3
That requirement skips the 0.0.0 name reservation on crates.io. 1.3.1 is the first version that installs the binary. Rust 1.95.0 or newer.
From a git checkout, cargo install --path crates/dreamd-cli builds this tree. See CONTRIBUTING.md for the full dev setup.
Quick start (under a minute)
If ~/your-project is a brand-new folder, run git init first.```bash
cd ~/your-project
npx -y dreamd-mcp setup
Optional: shared daemon, recommended when several agents write
npx -y dreamd-mcp watch
Reload your harness. `setup` already wired the dreamd MCP server, so the harness spawns `npx -y dreamd-mcp` itself.
Ask the agent to search memory for something it learned earlier. It calls `search_nodes` and recalls prior context, with the source harness on every hit.```bash
cat .agent/episodic/AGENT_LEARNINGS.jsonl
npx -y dreamd-mcp dream --dry # preview the lesson the next cycle would write
npx -y dreamd-mcp doctor
The npm shim does not put dreamd on PATH. Use npx -y dreamd-mcp on the npm path, or cargo install --path crates/dreamd-cli for the dreamd binary. From 1.2.1 the shim forwards every dreamd command; the 1.2.0 shim did not forward recall, score, status, archive and migrate.
Adapters: Claude Code · Cursor · Cline
Recorded live, sped up 1.5x: Claude Code writes the lesson, OpenCode reads it back through the same .agent/ folder. Tape: docs/assets/demo.tape.
How agents learn
Agents write episodes (what happened, how painful it was, how important) through MCP append_node. The dream cycle clusters episodes by skill_action and promotes a recurring pattern into a lesson in LESSONS.md. With an API key it composes the lesson with an LLM under a $0.10 per-cycle spend cap; without one it writes a deterministic lesson and makes no network call. Either way the lesson cites the events it came from, and every output is staged and committed through one redo WAL, so a crash leaves the store as it was or rolls the cycle forward.
Recall ranks episodes and lessons with BM25 × salience (age decay, pain, importance, recurrence). Recall is deliberately lexical; vector recall is not shipped (docs/vectors.md). Formula: docs/salience.md.
What dreamd writes
| Location | Contents | Commit? |
|---|---|---|
/.agent/ |
Episodic JSONL, semantic lessons, personal prefs | Yes (this is the shared memory) |
/.agent/.dreamd/ |
Local index, daemon state, config.toml, provenance ledger, decay archive (snapshots/), memory branches (branches/) |
No (gitignored by init); git clean -fdX deletes it, see troubleshooting |
~/.agent/registry.toml |
Which projects have a store | No |
~/.agent/dreamd.sock |
Daemon API socket (while running) | No |
~/.agent/star-asked |
Set after setup has asked for a GitHub star, once per user | No |
setup scaffolds the store by calling init, then writes the harness MCP config. Both are idempotent. To uninstall from a machine, run npx -y dreamd-mcp uninstall. On a tty it waits for y; pass --yes in a script. Without a tty and without --yes it exits 2 and changes nothing. Project .agent/ stores are left in place. npx -y is npx's flag, not dreamd's --yes. npx -y dreamd-mcp init --uninstall-project drops only the registry entry; dreamd init puts it back and does not rewrite the store.
All inspection commands
The MCP surface is two tools (search_nodes, append_node). Everything else is CLI over the same files. dreamd --help is the reference for flags.
Command · What it does
dreamd recall · Ranked search as a markdown table. --explain prints the salience factors per hit; --without / --without-cluster drop hits before top-k, so you can see the answer without a suspect memory
dreamd blame · Which stored memories drove a query's ranking: id, timestamp, skill_action, bm25, salience, total, layer. --json for one compact array
dreamd score · Top memories by salience alone, no query
dreamd salience-drift · Salience distribution, top clusters, and drift against the snapshot from seven days earlier. See docs/observability.md
dreamd dream --dry · Print the LESSONS.md the next cycle would write, without writing
dreamd forget · Remove one episodic event and the lesson state that names it. --dry-run writes nothing; --proof writes a forget-receipt/1.0 file (a receipt, not a signed proof). Refuses while the daemon is running
dreamd doctor --provenance · Recompute the provenance ledger's Merkle root and list orphan edges, missing edges and corrupt lines. Read-only. See docs/provenance.md
dreamd memory branch\ · checkout\ · branches\ · delete\ · diff\ · bisect · Deprecated in 1.2.0, removed in 2.0. .agent/ is plain files, so use git. See docs/branching-guide.md
Architecture (one paragraph)
Roadmap
Direction, not dated commitments. Full view: ROADMAP.md.
- Trust labels. A label on every memory saying where it came from and how far to trust it, joined along provenance edges, so a lesson from an untrusted source can't drive a privileged action. Needs its own spec first.
- Signed provenance. Signed forget receipts and membership proofs, as specified in docs/provenance.md.
- Proof of learning. Publish the WasTrue benchmark results (does memory update a fact that later changed?) and measure whether learned lessons actually improve task success over time.
- Vector recall. Hybrid lexical and vector scoring, as derived state over the natural-language record.
- Robots and edge devices. dreamd is one local binary with no cloud dependency, which is the shape an offline robot needs. No robot integration ships today.
Release history
| Version | What |
|---|---|
| v1.3.2 (2026-11-17) | dreamd watch opens a project again when git clean -fdX deletes its .agent/.dreamd/, and no dreamd process writes into a store that replaced its own; an empty dedup key no longer drops learnings; watch no longer deletes a file at DREAMD_SOCK that is not a socket |
| v1.3.1 (2026-11-16) | A failed dream cycle no longer blocks the next one; an event's content can no longer forge a lesson; the first requests to a project, at once or after it idles, no longer fail on the daemon's own writer lock; an idle dreamd mcp session no longer holds a connection to the daemon |
| v1.3.0 (2026-11-07) | Recall ranks the event that has a multi-word query's missing words, and a fat skill_action parent no longer outweighs a more painful child (SPEC.md v0.2); recall hits carry their id; the dream cycle's git commit runs again; a client and a daemon of different versions say so |
| v1.2.2 (2026-11-04) | dreamd setup through npx names npx -y dreamd-mcp … commands, and its card lists everything it wrote with an Undo line for each |
| v1.2.1 (2026-11-03) | Static Linux binary with no glibc requirement (runs on Ubuntu 20.04 and 22.04, Debian 12 and Alpine); fixes from the 1.2.0 torture session; the npm shim forwards every dreamd command |
| v1.2.0 (2026-10-29) | Windows dream cycle and Tantivy index; audit fixes (writer lock, atomic dream cycle, faithful log rewrites, index coverage); deprecates dreamd memory branch commands, vectors enable and dream --auto for removal in 2.0. No 1.1.0 tag |
| v1.0.1 (2026-10-21) | Dependency security fixes |
| v1.0.0 (2026-10-02) | Provenance ledger and doctor --provenance, dreamd forget, dreamd blame, recall --without, salience-drift, explain=1 citations on HTTP recall |
| v0.1.1 (2026-09-14) | LLM dream cycle, LESSONS.md semantic layer, Windows watch and learn, dreamd service |
| v0.1.0 (2026-08-05) | BM25 lexical recall, Linux and macOS, deterministic dream cycle, npm dreamd-mcp |
Full notes: CHANGELOG.md.
FAQ
Other tools store memory as files too. What's different? Files are the substrate, not the feature. dreamd adds the trace: lessons that cite their source events, a provenance ledger you can check, blame for any recall, and forget that removes an event together with the lesson state built from it.
Does dreamd stop memory poisoning? No. It makes a poisoned memory findable and removable, and it keeps a record. It does not screen what agents write. See SECURITY.md.
Do I need Rust? No. npx -y dreamd-mcp downloads a prebuilt binary for Linux x86_64 and macOS. The Linux binary is static, with no glibc requirement, and is checked on Ubuntu 20.04, Ubuntu 22.04, Debian 12 and Alpine 3.20. Rust is only needed to build from source (and for native Windows).
Where does memory live? In /.agent/. The daemon state and index under .agent/.dreamd/ are local and gitignored. You can read and edit the JSONL and Markdown by hand; durable appends should go through the daemon or MCP so there is one writer.
What if I want a full wipe? See Full fresh store. There is no dreamd reset --all. dreamd uninstall asks for y on a tty (--yes in a script) before it stops processes and clears caches. dreamd service uninstall --purge deletes the daemon home ~/.agent/ and never a project .agent/ store (docs/install.md).
Windows?
dreamd watch serves the HTTP API on loopback TCP with a bearer token from auth.json. Learn, the dream cycle and the Tantivy index run there. The directory flush follows the Unix call order and is not a power-loss proof. There is no prebuilt npm binary for Windows. Details: docs/windows.md.
Is everything free forever? The Apache-2.0 core is open, and a single repo stays free. Premium, self-hosted features may come later. There is no hosted SaaS.
More: docs/troubleshooting.md.
Status
v1.3.2 is tagged and published on npm (dreamd-mcp, latest). Linux, macOS and Windows. Commands marked as 1.0.0 features above need 1.0.0 or later. If you upgrade a cargo-installed binary in place and run the daemon under the per-user service, restart it with dreamd service restart (docs/install.md).
| Layer | Status |
|---|---|
SPEC.md v0.2 |
Shipped |
| Reference implementation (daemon, HTTP API, dream cycle, Tantivy recall) | Shipped |
MCP server (dreamd mcp + npx dreamd-mcp shim) |
Shipped on npm |
Provenance ledger, forget, blame |
Shipped (unsigned) |
| Trust labels, signed proofs | Not shipped |
| CI / cross-platform matrix | Lint, test, build, binary-size gate, DCO (Windows jobs are informational) |
Benchmarks
WasTrue tests whether a memory system updates a fact that later changes. The harness here is a scaffold and no results table is published yet (scripts/benchmark/README.md).
Coding recall oracle.
python3 scripts/benchmark/coding_oracle.py printed dreamd_only=12 both=0 stuffing_only=0 neither=0 n=12 budget_tokens=36: after one dreamd dream --no-llm, k=32 recall packed to the same token budget found all 12 episodes that context stuffing missed. It is a small in-repo check, not a general benchmark.
Platforms
Linux, macOS and Windows. Windows serves over loopback TCP. See docs/windows.md.
The prebuilt Linux x86_64 binary is one static build with no glibc requirement, checked on Ubuntu 20.04, Ubuntu 22.04, Debian 12 and Alpine 3.20. Linux arm64 has no prebuilt binary.
Documentation
| Doc | What |
|---|---|
| GUIDE.md | 20-minute walkthrough, including inspect and undo |
| docs/README.md | Full documentation index |
| docs/provenance.md | Provenance ledger format and what doctor --provenance checks |
| docs/observability.md | Recall citations, blame, counterfactual recall and salience drift |
| SECURITY.md | Threat model, including the lesson-injection surface |
| docs/http-api.md | REST API (Unix socket / Windows loopback TCP) |
| docs/configuration.md | TOML config and env vars |
| docs/troubleshooting.md | Common failures |
| SPEC.md | On-disk contract |
| docs/salience.md | Salience formula deep-dive |
| ARCHITECTURE.md | Engineering decisions |
| CONTRIBUTING.md | Dev setup and RFC process |
Support dreamd
dreamd is open source under Apache-2.0 and built by a small team. Sponsorship funds its core maintenance. You can sponsor dreamd on:
- GitHub Sponsors
- Patreon
- Ko-fi
Sponsors
Company sponsors ($250 a month) are listed by logo and Backers ($25 a month) by name on GitHub Sponsors.
Company
None yet.
Backers
None yet.
Contributing
See CONTRIBUTING.md. By participating you agree to the Code of Conduct. Security reports: SECURITY.md (do not open a public issue for vulnerabilities).
License
Apache-2.0. See LICENSE and NOTICE.
