Auditable agent memory: lessons cite their sources, and bad memories can be traced and removed.
io.github.botzrDev/dreamd MCP Server
The io.github.botzrDev/dreamd server provides local-first, cross-harness memory for AI coding agents. Its repository description states that plain files in a project act as memory, while the local server reads and writes that content for MCP-compatible agent harnesses.
🛠️ Key Features
Local-first memory stored as plain files in a repo
Reads and writes memory via a local server
MCP-compatible for agent harnesses
🚀 Use Cases
Sharing memory across Claude Code, Cursor, Cline, and other MCP-aware harnesses
Supporting agent workflows that benefit from persisted, repo-scoped context
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
dreamd blame finds the memory behind a bad answer, dreamd forget removes it and writes a receipt, and the same query no longer returns it
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 <query> 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 <event-id> removes the event and the lesson state that names it. --dry-run shows what would change; --proof <path> 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 citescat .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:<port> 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 <cmd> 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.
Claude Code saves a lesson to dreamd; OpenCode, in a fresh session, finds it with search_nodes
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.
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 <cmd> --help is the reference for flags.
Command
What it does
dreamd recall <query>
Ranked search as a markdown table. --explain prints the salience factors per hit; --without <id> / --without-cluster <prefix> drop hits before top-k, so you can see the answer without a suspect memory
dreamd blame <query>
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 <event-id>
Remove one episodic event and the lesson state that names it. --dry-run writes nothing; --proof <path> 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
Deprecated in 1.2.0, removed in 2.0. .agent/ is plain files, so use git. See docs/branching-guide.md
Architecture (one paragraph)
Agents talk to dreamd over MCP. On Linux and macOS the MCP server proxies to a single-writer daemon (dreamd watch) over HTTP on a Unix domain socket, or runs in-process when no daemon is present. On Windows it proxies to loopback dreamd watch and exits 2 when that daemon is down. One writer lock covers every process that writes a project. The coordinator appends to AGENT_LEARNINGS.jsonl and feeds a Tantivy BM25 index; recall ranks hits with the salience formula, and each hit carries source_harness and skill_action. Details: ARCHITECTURE.md · SPEC.md · docs/http-api.md. Warm recall latency (local Criterion benches) is in PERF.md.
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
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 <project>/.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.
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).
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.