# dreamd

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/botzrDev/dreamd  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/dreamd

## Description
Local-first, cross-harness memory for AI coding agents.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "dreamd": {
    "command": "npx",
    "args": ["-y","dreamd"]
  }
}
```

## Documentation & README

# dreamd

[![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](./LICENSE)
![MCP-compatible](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)
[![Platforms](https://img.shields.io/badge/platforms-linux%20%7C%20macOS-lightgrey.svg)](#platforms)
[![Status](https://img.shields.io/badge/v0.1.0-released-brightgreen.svg)](#status)

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

**Open core:** Apache-2.0 core today, self-hosted only. Premium features may ship later. Do not read this as free-forever for everything.

```bash
npx -y dreamd-mcp setup   # scaffold .agent/ and wire your harness
npx -y dreamd-mcp         # MCP server (stdio) — what the harness spawns
```

> First run prints a local-only privacy disclosure. `setup` prompts for harness choice when it has a TTY.

---

## The moment it earns its name

```text
~/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)

```bash
npx -y dreamd-mcp setup   # scaffold .agent/ + write the harness MCP config
npx -y dreamd-mcp         # MCP server (stdio) — your harness spawns this
```

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

```bash
git clone https://github.com/botzrDev/dreamd.git
cd dreamd
cargo install --path crates/dreamd-cli
```

See [CONTRIBUTING.md](https://github.com/botzrDev/dreamd/blob/HEAD/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).

```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 — 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.

```bash
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](https://github.com/botzrDev/dreamd/blob/HEAD/adapters/claude-code/README.md) · [Cursor](https://github.com/botzrDev/dreamd/blob/HEAD/adapters/cursor/README.md)

---

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

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

Details: [ARCHITECTURE.md](https://github.com/botzrDev/dreamd/blob/HEAD/ARCHITECTURE.md) · [SPEC.md](https://github.com/botzrDev/dreamd/blob/HEAD/SPEC.md) · [docs/http-api.md](https://github.com/botzrDev/dreamd/blob/HEAD/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](https://github.com/botzrDev/dreamd/blob/HEAD/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](https://github.com/botzrDev/dreamd/blob/HEAD/packages/dreamd-mcp/README.md#uninstall--reset).

**Windows?** Not in v0.1. Linux and macOS only. Windows lifecycle is planned for v0.1.1.

**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](https://github.com/botzrDev/dreamd/blob/HEAD/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** | Windows lifecycle, semantic / embedding recall, LLM-assisted dream cycle (not claimed in v0.1) |
| **Oct 2026** | WasTrue benchmark publish (dreamd is one row; conflict of interest disclosed) |

v0.1.1 features are intentionally not implemented or documented as shipped in v0.1 code.

---

## Documentation

| Doc | What |
|---|---|
| [GUIDE.md](https://github.com/botzrDev/dreamd/blob/HEAD/GUIDE.md) | 20-minute tutorial walkthrough |
| [docs/README.md](https://github.com/botzrDev/dreamd/blob/HEAD/docs/README.md) | Full documentation index |
| [docs/http-api.md](https://github.com/botzrDev/dreamd/blob/HEAD/docs/http-api.md) | REST API over Unix socket |
| [docs/configuration.md](https://github.com/botzrDev/dreamd/blob/HEAD/docs/configuration.md) | TOML config and env vars |
| [docs/troubleshooting.md](https://github.com/botzrDev/dreamd/blob/HEAD/docs/troubleshooting.md) | Common failures |
| [docs/glossary.md](https://github.com/botzrDev/dreamd/blob/HEAD/docs/glossary.md) | Domain terms |
| [SPEC.md](https://github.com/botzrDev/dreamd/blob/HEAD/SPEC.md) | On-disk contract |
| [ARCHITECTURE.md](https://github.com/botzrDev/dreamd/blob/HEAD/ARCHITECTURE.md) | Engineering decisions |
| [CONTRIBUTING.md](https://github.com/botzrDev/dreamd/blob/HEAD/CONTRIBUTING.md) | Dev setup and RFC process |
| [SECURITY.md](https://github.com/botzrDev/dreamd/blob/HEAD/SECURITY.md) | Threat model |
| [docs/marketing.md](https://github.com/botzrDev/dreamd/blob/HEAD/docs/marketing.md) | Product story and positioning |

Warm recall latency numbers (local Criterion benches) live in [PERF.md](https://github.com/botzrDev/dreamd/blob/HEAD/PERF.md) if you want them. They are not the product pitch.

---

## Status

**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](https://github.com/botzrDev/dreamd/blob/HEAD/packages/dreamd-mcp/README.md)). Linux and macOS.

| 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](https://github.com/botzrDev/dreamd/blob/HEAD/scripts/benchmark/README.md).

---

## Platforms

v0.1: Linux and macOS. Windows in v0.1.1.

---

## Contributing

See [CONTRIBUTING.md](https://github.com/botzrDev/dreamd/blob/HEAD/CONTRIBUTING.md). By participating you agree to the [Code of Conduct](https://github.com/botzrDev/dreamd/blob/HEAD/CODE_OF_CONDUCT.md). Security reports: [SECURITY.md](https://github.com/botzrDev/dreamd/blob/HEAD/SECURITY.md) (do not open a public issue for vulnerabilities).

## License

Apache-2.0. See [LICENSE](https://github.com/botzrDev/dreamd/blob/HEAD/LICENSE) and [NOTICE](https://github.com/botzrDev/dreamd/blob/HEAD/NOTICE).