{
  "markdown": "# dreamd\n\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](./LICENSE)\n![MCP-compatible](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)\n[![Platforms](https://img.shields.io/badge/platforms-linux%20%7C%20macOS-lightgrey.svg)](#platforms)\n[![Status](https://img.shields.io/badge/v0.1.0-released-brightgreen.svg)](#status)\n\n**The plain files in your repo are the memory. dreamd is the local server that reads and writes them.**\n\nDrop 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.\n\nThis 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.\n\n**Open core:** Apache-2.0 core today, self-hosted only. Premium features may ship later. Do not read this as free-forever for everything.\n\n```bash\nnpx -y dreamd-mcp setup   # scaffold .agent/ and wire your harness\nnpx -y dreamd-mcp         # MCP server (stdio) — what the harness spawns\n```\n\n> First run prints a local-only privacy disclosure. `setup` prompts for harness choice when it has a TTY.\n\n---\n\n## The moment it earns its name\n\n```text\n~/project $ npx -y dreamd-mcp setup\n\n# Claude Code, Tuesday:\nyou   > axum keeps blowing up when I unwrap in route handlers\nclaude> filed under rust::error_handling::axum_rejection\n\n# Cursor, Friday, fresh session:\nyou   > why is this build failing?\ncursor> You're unwrapping in a route handler. dreamd has a\n        lesson from Tuesday: axum needs IntoResponse on\n        custom Error types. Try `?` and a typed error.\n```\n\nNo re-explaining. No re-pasting. Same `.agent/` folder, every harness.\n\n---\n\n## Install\n\n### npm (recommended)\n\n```bash\nnpx -y dreamd-mcp setup   # scaffold .agent/ + write the harness MCP config\nnpx -y dreamd-mcp         # MCP server (stdio) — your harness spawns this\n```\n\nRequires a project root sentinel (`.git/`, `Cargo.toml`, `package.json`, or `pyproject.toml`).\n\n`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).\n\n### Cargo / from source\n\n```bash\ngit clone https://github.com/botzrDev/dreamd.git\ncd dreamd\ncargo install --path crates/dreamd-cli\n```\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for the full dev setup.\n\n---\n\n## Quick start (< 30 seconds)\n\nIf `~/your-project` is a brand-new folder, run `git init` first (or make sure it contains one of the supported root sentinels).\n\n```bash\ncd ~/your-project\nnpx -y dreamd-mcp setup\n\n# Optional: shared daemon (recommended when several agents write)\nnpx -y dreamd-mcp watch\n```\n\nReload your harness. `setup` already wired the dreamd MCP server, so the harness spawns `npx -y dreamd-mcp` itself — no config to copy by hand.\n\nAsk the agent to search memory for something you just learned. It calls `search_nodes` and recalls prior context.\n\n```bash\ncat .agent/episodic/AGENT_LEARNINGS.jsonl\nnpx -y dreamd-mcp doctor\n```\n\nThe 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.\n\nAdapters: [Claude Code](./adapters/claude-code/README.md) · [Cursor](./adapters/cursor/README.md)\n\n---\n\n## What dreamd writes\n\n| Location | Contents | Commit? |\n|---|---|---|\n| `<project>/.agent/` | Episodic JSONL, semantic lessons, personal prefs | **Yes** (this is the shared memory) |\n| `<project>/.agent/.dreamd/` | Local index, daemon state, config template | No (gitignored by `init`) |\n| `~/.agent/registry.toml` | Which projects have a store | No |\n| `~/.agent/dreamd.sock` | Daemon API socket (while running) | No |\n\n`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.\n\n---\n\n## Architecture (one paragraph)\n\nAgents 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.\n\nv0.1 recall is deliberately lexical (BM25 + salience). That is a scope choice, not a scoreboard claim. Semantic / embedding recall is out of scope until after v0.1.\n\nDetails: [ARCHITECTURE.md](./ARCHITECTURE.md) · [SPEC.md](./SPEC.md) · [docs/http-api.md](./docs/http-api.md)\n\n---\n\n## FAQ\n\n**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.\n\n**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.\n\n**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.\n\n**What if I want a full wipe?** See [Full fresh store](./docs/troubleshooting.md#how-do-i-reset-or-clear-memory). There is no `dreamd reset --all`. To uninstall dreamd itself, run `dreamd uninstall` — details: [packages/dreamd-mcp/README.md](./packages/dreamd-mcp/README.md#uninstall--reset).\n\n**Windows?** Not in v0.1. Linux and macOS only. Windows lifecycle is planned for v0.1.1.\n\n**Is everything free forever?** Apache-2.0 core is open. Premium may come later. Self-hosted only in v0.1 (no hosted SaaS).\n\nMore troubleshooting: [docs/troubleshooting.md](./docs/troubleshooting.md).\n\n---\n\n## Roadmap\n\n| When | What |\n|---|---|\n| **v0.1.0** (2026-08-05) | BM25 lexical recall, Linux + macOS, deterministic dream cycle, npm `dreamd-mcp` |\n| **v0.1.1** | Windows lifecycle, semantic / embedding recall, LLM-assisted dream cycle (not claimed in v0.1) |\n| **Oct 2026** | WasTrue benchmark publish (dreamd is one row; conflict of interest disclosed) |\n\nv0.1.1 features are intentionally not implemented or documented as shipped in v0.1 code.\n\n---\n\n## Documentation\n\n| Doc | What |\n|---|---|\n| [GUIDE.md](./GUIDE.md) | 20-minute tutorial walkthrough |\n| [docs/README.md](./docs/README.md) | Full documentation index |\n| [docs/http-api.md](./docs/http-api.md) | REST API over Unix socket |\n| [docs/configuration.md](./docs/configuration.md) | TOML config and env vars |\n| [docs/troubleshooting.md](./docs/troubleshooting.md) | Common failures |\n| [docs/glossary.md](./docs/glossary.md) | Domain terms |\n| [SPEC.md](./SPEC.md) | On-disk contract |\n| [ARCHITECTURE.md](./ARCHITECTURE.md) | Engineering decisions |\n| [CONTRIBUTING.md](./CONTRIBUTING.md) | Dev setup and RFC process |\n| [SECURITY.md](./SECURITY.md) | Threat model |\n| [docs/marketing.md](./docs/marketing.md) | Product story and positioning |\n\nWarm recall latency numbers (local Criterion benches) live in [PERF.md](./PERF.md) if you want them. They are not the product pitch.\n\n---\n\n## Status\n\n**v0.1.0 is out.** npm package `dreamd-mcp` has held the `latest` dist-tag since 2026-08-06. CLI commands: `setup`, `init`, `watch`, `mcp`, `dream`, `doctor`, `status`, `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](./packages/dreamd-mcp/README.md)). Linux and macOS.\n\n| Layer | Status |\n|---|---|\n| `SPEC.md` v0.1 | Shipped |\n| Reference implementation (daemon, HTTP API, dream cycle, Tantivy recall) | Shipped |\n| MCP server (`dreamd mcp` + `npx dreamd-mcp` shim) | Shipped on npm |\n| CI / cross-platform matrix | Lint, test, build, binary-size gate, DCO (Windows jobs are informational) |\n| Conformance | Reference-impl alpha suites (`scripts/alpha/`); no formal certification in v0.1 |\n\n---\n\n## WasTrue benchmark (Oct 2026)\n\nA 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](./scripts/benchmark/README.md).\n\n---\n\n## Platforms\n\nv0.1: Linux and macOS. Windows in v0.1.1.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md). By participating you agree to the [Code of Conduct](./CODE_OF_CONDUCT.md). Security reports: [SECURITY.md](./SECURITY.md) (do not open a public issue for vulnerabilities).\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).\n",
  "bytes": 9683,
  "sha": "63e46a490bf10754655269d92d5a06b1ac56d712aa435eb07300288ea03d834e",
  "repo_slug": "botzrdev/dreamd",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_botzrdev_dreamd_bfb2e8ea/readme"
}