dreamd
The plain files in your repo are the memory. dreamd is the local server that reads and writes them.
Drop a .agent/ folder in the project. Claude Code, Cursor, Cline, and other MCP-aware harnesses share it. What one agent learns, the next already knows. You can cat, grep, and git diff every byte. Durable appends go through MCP / the daemon so the writer stays single-writer.
This is not "another memory product." It is a storage-model wedge: the filesystem is the source of truth, and the MCP tools (search_nodes / append_node) are a thin interface over those files.
Where dreamd fits. dreamd is one of three sibling repositories that make one product: dreamOS, the first computer you can hand your keys to — it acts on your behalf, it is structurally incapable of doing what you did not allow, and it can prove what it did. The kernel under it is momo; the sandbox beside it is aegis. momo's charter (its RFC-009, amended by RFC-011, accepted 2026-09-26) records dreamd as the Linux-hosted proof of one of the product's pillars: memory as plain files a person owns, with provenance — in the product's words, the Memory. The same amendment names the rule the provenance ledger grows toward — every effect can be traced to the data that caused it, and no datum can cause an effect above its own trust label — as a design with its own spec first. Nothing in v0.1 implements a trust label: source_harness is asserted by the caller, the ledger (docs/provenance.md) is a format only, and SECURITY.md says plainly that injected lessons are not filtered. The momo repository is private until the kernel's first public release, and the product is not announced, previewed or marketed before its v1; this paragraph is a pointer, not a launch.
Open core: Apache-2.0 core today, self-hosted only. Premium features may ship later. Do not read this as free-forever for everything.
npx -y dreamd-mcp setup
npx -y dreamd-mcp
First run prints a local-only privacy disclosure. setup prompts for harness choice when it has a TTY.
The moment it earns its name
~/project $ npx -y dreamd-mcp setup
# Claude Code, Tuesday:
you > axum keeps blowing up when I unwrap in route handlers
claude> filed under rust::error_handling::axum_rejection
# Cursor, Friday, fresh session:
you > why is this build failing?
cursor> You're unwrapping in a route handler. dreamd has a
lesson from Tuesday: axum needs IntoResponse on
custom Error types. Try `?` and a typed error.
No re-explaining. No re-pasting. Same .agent/ folder, every harness.
Install
npm (recommended)
npx -y dreamd-mcp setup
npx -y dreamd-mcp
stdio stays the default transport. dreamd mcp --bind 127.0.0.1:<port> is the 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.
Requires 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
git clone https://github.com/botzrDev/dreamd.git
cd dreamd
cargo install --path crates/dreamd-cli
See CONTRIBUTING.md for the full dev setup.
Quick start (< 30 seconds)
If ~/your-project is a brand-new folder, run git init first (or make sure it contains one of the supported root sentinels).
cd ~/your-project
npx -y dreamd-mcp setup
npx -y dreamd-mcp watch
Reload your harness. setup already wired the dreamd MCP server, so the harness spawns npx -y dreamd-mcp itself — no config to copy by hand.
Ask the agent to search memory for something you just learned. It calls search_nodes and recalls prior context.
cat .agent/episodic/AGENT_LEARNINGS.jsonl
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 if you want the dreamd binary.
Adapters: Claude Code · Cursor
What dreamd writes
| Location | Contents | Commit? |
|---|
<project>/.agent/ | Episodic JSONL, semantic lessons, personal prefs | Yes (this is the shared memory) |
<project>/.agent/.dreamd/ | Local index, daemon state, config template | No (gitignored by init) |
~/.agent/registry.toml | Which projects have a store | No |
~/.agent/dreamd.sock | Daemon API socket (while running) | No |
npx -y dreamd-mcp setup (or dreamd setup after a cargo install) scaffolds the store by calling init, then writes the harness MCP config. init is the scaffold primitive and still works on its own when you want the store without touching any MCP config. Both are idempotent. To uninstall from a machine — stop local servers, remove the socket, unregister the current project, clear caches — run npx -y dreamd-mcp uninstall (project .agent/ stores are left in place). Advanced, registry-only: npx -y dreamd-mcp init --uninstall-project unregisters the current project and touches nothing else.
Architecture (one paragraph)
Agents talk to dreamd over MCP (search_nodes, append_node). 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. The coordinator appends to AGENT_LEARNINGS.jsonl and feeds a Tantivy BM25 index. Recall ranks hits with a query-time salience formula (BM25 × age decay × pain × importance × recurrence). Each hit carries source_harness and skill_action, so recall is attributable across harnesses. The dream cycle consolidates episodic learnings into LESSONS.md under WAL protection.
Recall is deliberately lexical (BM25 + salience), including the LESSONS.md document layer indexed alongside episodic events. That is a scope choice, not a scoreboard claim. Vector / embedding recall is later.
Details: ARCHITECTURE.md · SPEC.md · docs/http-api.md
FAQ
Is this the first / only cross-harness memory? No. Other projects exist (including large ones). dreamd owns the storage-model wedge: plain files you already version-control, not a category claim.
Do I need Rust? No for the recommended path. npx -y dreamd-mcp downloads a prebuilt binary. Rust is only required if you build from source.
Where does memory live? In <project>/.agent/. The daemon and index under .agent/.dreamd/ are local and gitignored. You can read and edit the JSONL / Markdown by hand; durable appends should go through the daemon / MCP so the writer stays single-writer.
What if I want a full wipe? See Full fresh store. There is no dreamd reset --all. To uninstall dreamd itself, run dreamd uninstall — details: packages/dreamd-mcp/README.md. That stops running processes and clears caches; removing the per-user service entry (the systemd unit, the LaunchAgent, or — new in v0.1.1 — the Windows Task Scheduler logon task) is the separate dreamd service uninstall, whose optional --purge deletes the daemon home ~/.agent/ and never a per-project .agent/ store (docs/install.md).
Windows? Partial in v0.1.1. dreamd watch serves the HTTP API on loopback TCP with a bearer token from auth.json; POST /api/v1/learn works. The dream cycle and Tantivy index do not — io::write_atomic is still Unsupported there. For consolidate-and-search, use WSL2 or a Linux/macOS host. Details: docs/windows.md.
Is everything free forever? Apache-2.0 core is open. Premium may come later. Self-hosted only in v0.1 (no hosted SaaS).
More troubleshooting: docs/troubleshooting.md.
Roadmap
| When | What |
|---|
| v0.1.0 (2026-08-05) | BM25 lexical recall, Linux + macOS, deterministic dream cycle, npm dreamd-mcp |
| v0.1.1 (2026-09-14) | LLM dream cycle, LESSONS.md semantic layer (still BM25 × salience, not embeddings), Windows watch+learn, dreamd service on Linux / macOS / Windows |
| Next | Windows atomic writes (dream cycle + index), vector recall, WasTrue benchmark publish |
Documentation
Warm recall latency numbers (local Criterion benches) live in PERF.md if you want them. They are not the product pitch.
Status
v0.1.1 is out (GitHub 2026-09-14; npm dreamd-mcp@0.1.1 and MCP Registry io.github.botzrDev/dreamd 0.1.1 on 2026-09-16). CLI commands: setup, init, watch, mcp, dream, doctor, status, service, recall, score, archive, migrate, reset workspace, uninstall, update, version (dreamd --help is the full list; on the npm path use npx -y dreamd-mcp <cmd> — the shim forwards a subset, see packages/dreamd-mcp/README.md). Linux, macOS, and partial Windows (watch + learn; no dream cycle or index). If you upgrade a cargo-installed binary in place (cargo install --path crates/dreamd-cli) and run the daemon under the per-user service, bounce it afterwards with dreamd service restart so the supervisor picks up the new binary (docs/install.md).
| Layer | Status |
|---|
SPEC.md v0.1 | Shipped |
| Reference implementation (daemon, HTTP API, dream cycle, Tantivy recall) | Shipped |
MCP server (dreamd mcp + npx dreamd-mcp shim) | Shipped on npm |
| CI / cross-platform matrix | Lint, test, build, binary-size gate, DCO (Windows jobs are informational) |
| Conformance | Reference-impl alpha suites (scripts/alpha/); no formal certification in v0.1 |
WasTrue benchmark (Oct 2026)
A separate, reproducible eval measuring whether memory systems correctly update superseded facts. dreamd is one row in the table, published regardless of placement. Conflict of interest is disclosed; configs use each maintainer's documented defaults; raw outputs are committed for audit. Methodology: scripts/benchmark/README.md.
Linux and macOS (full). Windows in v0.1.1 is watch + learn over loopback TCP; the dream cycle and Tantivy index stay Unix-only until atomic writes land. See docs/windows.md.
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.