Dreamd

io.github.botzrDevPublished by GitHub account botzrDevv1.3.0Updated Nov 8, 2026

Auditable agent memory: lessons cite their sources, and bad memories can be traced and removed.

VerifiedSTDIODesktop onlyKnowledge & MemoryDeveloper Tools

Overview

AI-generated overview

Local-first long-term memory for AI agents: assistants search past events and lessons and append new ones, with every lesson traceable to its sources.

What you can do
  • Search memory across raw episodic events and consolidated lessons, ranked together by relevance and salience
  • Append a precise episodic event when the user corrects the assistant, states a decision, or asks it to remember something
  • Tag entries with a skill_action path and importance/pain scores so recurring patterns can be promoted into lessons
  • Keep memory as plain JSONL and Markdown under the project's .agent folder, so it can be read, diffed and committed with the code
  • Outside MCP, CLI commands inspect recall, blame a query on stored memories, check provenance, and remove a bad event with a receipt
When to use it
Worth adding when you want an assistant to carry context across sessions in a specific project and to be able to show where a recalled belief came from. Useful for teams that want learned lessons reviewed like code in git rather than hidden in a hosted service.
Requirements
Runs as a local stdio process via npx, which downloads a prebuilt binary for Linux x86_64 and macOS; Windows has no prebuilt npm binary. Needs a project root sentinel such as .git, package.json, Cargo.toml or pyproject.toml. Setup scaffolds the .agent folder and writes the harness MCP config. An optional LLM API key enables composed lessons under a per-cycle spend cap; without it lessons are deterministic and no network call is made.
Before you install
Memory is written into the project's .agent folder and is meant to be committed, so anything recorded there enters version control and may be shared with collaborators. The server does not detect or block poisoned writes and does not filter injected lesson content; source_harness is asserted by the caller, not verified, and the provenance ledger and forget receipts are unsigned. The optional HTTP transport is unauthenticated. Removal commands change stored data and refuse while the daemon runs.

Installation

In SourceWeft

  1. Open Dreamd in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

dreamd

[License: Apache 2.0] [MCP-compatible] [Platforms] [Status]

[dreamd MCP server]

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 harnessnpx -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 todreamd gives you
See what drove an answerdreamd 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 fromEvery 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 consistentdreamd doctor --provenance recomputes the ledger's Merkle root and lists orphan, missing and corrupt edges. Read-only
Remove a bad memorydreamd 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 yourselfPlain 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 itnpx -y dreamd-mcp blame "deploy without tests" --explain
# 2. Check the lesson it came from and what that lesson citescat .agent/semantic/LESSONS.mdnpx -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-runnpx -y dreamd-mcp forget evt_... --proof forget-receipt.json
# 4. Review the change like codegit 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 confignpx -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 / from source

bash
git clone https://github.com/botzrDev/dreamd.gitcd dreamdcargo install --path crates/dreamd-cli

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-projectnpx -y dreamd-mcp setup
# Optional: shared daemon, recommended when several agents writenpx -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.jsonlnpx -y dreamd-mcp dream --dry   # preview the lesson the next cycle would writenpx -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.

Adapters: Claude Code · Cursor · Cline

[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.

What dreamd writes

LocationContentsCommit?
<project>/.agent/Episodic JSONL, semantic lessons, personal prefsYes (this is the shared memory)
<project>/.agent/.dreamd/Local index, daemon state, config template, provenance ledgerNo (gitignored by init)
~/.agent/registry.tomlWhich projects have a storeNo
~/.agent/dreamd.sockDaemon API socket (while running)No
~/.agent/star-askedSet after setup has asked for a GitHub star, once per userNo

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.

CommandWhat 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 scoreTop memories by salience alone, no query
dreamd salience-driftSalience distribution, top clusters, and drift against the snapshot from seven days earlier. See docs/observability.md
dreamd dream --dryPrint 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 --provenanceRecompute 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|bisectDeprecated 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

VersionWhat
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 <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.

More: docs/troubleshooting.md.

Status

v1.3.0 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).

LayerStatus
SPEC.md v0.2Shipped
Reference implementation (daemon, HTTP API, dream cycle, Tantivy recall)Shipped
MCP server (dreamd mcp + npx dreamd-mcp shim)Shipped on npm
Provenance ledger, forget, blameShipped (unsigned)
Trust labels, signed proofsNot shipped
CI / cross-platform matrixLint, 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

DocWhat
GUIDE.md20-minute walkthrough, including inspect and undo
docs/README.mdFull documentation index
docs/provenance.mdProvenance ledger format and what doctor --provenance checks
docs/observability.mdRecall citations, blame, counterfactual recall and salience drift
SECURITY.mdThreat model, including the lesson-injection surface
docs/http-api.mdREST API (Unix socket / Windows loopback TCP)
docs/configuration.mdTOML config and env vars
docs/troubleshooting.mdCommon failures
SPEC.mdOn-disk contract
docs/salience.mdSalience formula deep-dive
ARCHITECTURE.mdEngineering decisions
CONTRIBUTING.mdDev 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:

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.

Source: README.md at commit 70e958d

Tools

2

append_node

Append a raw episodic event -- use when: the user corrects you, the user states a decision, note that, remember, log this, save this lesson. Writes AGENT_LEARNINGS.jsonl, not LESSONS.md; lessons come from the dream cycle. Put the user's own words in content. One precise event beats several vague ones. Once this returns, search_nodes includes the event, unless indexing it takes more than one second.

Parameterspaincontentrequiredimportanceskill_actionrequiredsource_harnessrequiredclient_dedup_key

search_nodes

Search memory (events + lessons) at the start of the current task -- use when: the user's request, recall, did we discuss, what did we decide, previously decided. Hits mix raw events (source=episodic, recent/specific) and consolidated lessons (source=semantic, recurring patterns), ranked together by BM25 × salience. There is no layer argument. Each hit has an id: an evt_ id for an event, an lsn_ id for a lesson. Factor citations are on GET /api/v1/recall?explain=1 only; this tool does not take explain. Pass plain words from the user's request: a colon is query syntax, and a skill_action pasted as the query fails. Every memory saved with append_node before the search is included, unless indexing it takes more than one second; then the search answers from what is already indexed.

Parameterskqueryrequired

Version history

8
  1. v1.3.0LatestNov 7, 2026
  2. v1.2.2Nov 4, 2026
  3. v1.2.1Nov 3, 2026
  4. v1.2.0Oct 29, 2026
  5. v1.0.1Oct 22, 2026
  6. v1.0.0Oct 2, 2026
  7. v0.1.1Sep 16, 2026
  8. v0.1.0Sep 16, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts