dreamd

dreamd

仓库中的普通文件就是记忆。dreamd 是读取和写入这些文件的本地服务。

在项目中放入一个 .agent/ 文件夹。Claude Code、Cursor、Cline 以及其他支持 MCP 的运行环境可以共享它。一个 Agent 学到的内容，下一个 Agent 已经知晓。你可以对每个字节运行 cat、grep 和 git diff。持久化追加操作通过 MCP / 守护进程进行，因此写入始终由单一进程负责。

这不是“又一个记忆产品”，而是对存储模型的突破：文件系统是事实来源，MCP 工具（search_nodes / append_node）只是这些文件的轻量接口。

**开放核心：**目前核心采用 Apache-2.0 许可，且只能自托管。未来可能推出高级功能。请勿将此理解为所有功能永久免费。

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

首次运行时会显示一则仅限本地的隐私声明。setup 在检测到 TTY 时会提示选择运行环境。

---

它名副其实的时刻

现场录制，播放速度加快 1.5 倍：Claude Code 写入经验，OpenCode 通过同一个 .agent/ 文件夹将其读回。录制记录：docs/assets/demo.tape。

无需重新解释，无需重新粘贴。同一个 .agent/ 文件夹，适用于所有运行环境。

---

安装

npm（推荐）

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

stdio 仍是默认传输方式。dreamd mcp --bind 127.0.0.1:<port> 会在 /mcp 启动可选的 Streamable HTTP 服务。它未经身份验证，且仅适用于带有 --features mcp-http 的源码构建——详见 docs/mcp-transports.md。

需要项目根目录标记（.git/、Cargo.toml、package.json 或 pyproject.toml）。

检测到 TTY 时，setup 会显示提示。在脚本和非交互式 Shell 中，请传入 --yes --harness claude|cursor|both（--harness none 或 --no-write-mcp 会创建脚手架，但不会修改任何 MCP 配置）。

Cargo / 从源码构建

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

完整的开发环境设置请参见 CONTRIBUTING.md。

---

快速开始（不到 30 秒）

如果 ~/your-project 是一个全新文件夹，请先运行 git init（或确保其中包含一个受支持的根目录标记）。

cd ~/your-project
npx -y dreamd-mcp setup

# Optional: shared daemon (recommended when several agents write)
npx -y dreamd-mcp watch

重新加载你的运行环境。setup 已配置好 dreamd MCP 服务，因此运行环境会自行启动 npx -y dreamd-mcp——无需手动复制配置。

让 Agent 搜索你刚学到的内容。它会调用 search_nodes 并回忆先前的上下文。

cat .agent/episodic/AGENT_LEARNINGS.jsonl
npx -y dreamd-mcp doctor

npm shim 不会将 dreamd 加入 PATH。使用 npm 时，请运行 npx -y dreamd-mcp <cmd>；如果需要 dreamd 二进制文件，请运行 cargo install --path crates/dreamd-cli。shim 只转发部分子命令（运行 npx -y dreamd-mcp --help 可查看列表）；recall、score、status、archive 和 migrate 需要 dreamd 二进制文件。

适配器：Claude Code · Cursor · Cline

---

dreamd 写入的内容

位置	内容	是否提交？
<project>/.agent/	情景 JSONL、语义经验、个人偏好	是（这是共享记忆）
<project>/.agent/.dreamd/	本地索引、守护进程状态、配置模板、记忆分支、溯源账本	否（由 init 加入 gitignore）
~/.agent/registry.toml	哪些项目拥有存储	否
~/.agent/dreamd.sock	守护进程 API 套接字（运行时）	否

npx -y dreamd-mcp setup（或通过 cargo 安装后运行 dreamd setup）会调用 init 搭建存储，然后写入宿主环境的 MCP 配置。init 是搭建存储的基础命令；如果只想要存储而不修改任何 MCP 配置，也可以单独使用。两者都是幂等的。若要从一台机器上卸载——停止本地服务、移除套接字、注销当前项目、清除缓存——请运行 npx -y dreamd-mcp uninstall（项目中的 .agent/ 存储会保留）。高级用法，仅操作注册表：npx -y dreamd-mcp init --uninstall-project 会注销当前项目，不做其他修改。

---

检查和编辑记忆

MCP 接口包含两个工具。其他操作都通过 CLI 对同一批文件执行。除非另有说明，这些命令需要 dreamd 二进制文件；标志说明请参阅 dreamd <cmd> --help。

命令	功能
dreamd recall <query>	以 Markdown 表格形式进行排序搜索。--explain 会打印每条命中的显著性因素；--without <id> / --without-cluster <prefix> 会在 top-k 之前移除命中项（1.0.0）。
dreamd blame <query>	查询哪些已存储记忆影响了查询的排序：id、时间戳、skill_action、bm25、显著性、总分、层级。使用 --json 输出一个紧凑数组。1.0.0 新增；由 npm shim 转发。
dreamd score	仅按显著性列出排名靠前的记忆，不需要查询。
dreamd salience-drift	显著性分布、排名靠前的集群，以及与恰好七天前快照的偏移。1.0.0 新增；由 npm shim 转发。参见 docs/observability.md。
dreamd dream --dry	打印下一周期将写入的 LESSONS.md，但不实际写入。
dreamd memory branch|checkout|branches|delete|diff|bisect	为记忆文件创建快照名称、在快照之间切换、比较两个快照，并对自动生成的 snap-* 快照进行二分搜索。1.0.0 新增；由 npm shim 转发。当 dreamd watch 正在持有实时日志时，checkout 和 bisect 会拒绝执行：Linux 和 macOS 上只要套接字文件存在（包括过期套接字）就会拒绝；Windows 上则在能够成功连接到 server.json 的环回地址时拒绝。参见 docs/branching-guide.md。
dreamd forget <event-id>	移除一条情景事件及提及它的经验状态。--dry-run 不会写入任何内容；--proof <path> 会写入一个 forget-receipt/1.0 JSON 文件（这是收据，不是签名证明）。守护进程运行时会拒绝执行。1.0.0 新增；由 npm shim 转发。
dreamd doctor --provenance	重新计算溯源账本的 Merkle 根，并列出孤立边、缺失边和损坏行。只读。1.0.0 新增。参见 docs/provenance.md。

---

架构（一段话）

Agent 通过 MCP（search_nodes、append_node）与 dreamd 通信。在 Linux 和 macOS 上，MCP 服务通过 Unix 域套接字上的 HTTP 代理到单写入者守护进程（dreamd watch）；如果没有守护进程，则在进程内运行。在 Windows 上，它代理到环回地址上的 dreamd watch；如果该守护进程未运行，则以状态码 2 退出；不提供进程内服务。协调器将内容追加到 AGENT_LEARNINGS.jsonl，并将其送入 Tantivy BM25 索引。召回通过查询时的显著性公式为命中项排序（BM25 × 时间衰减 × 痛点 × 重要性 × 重现次数）。每个命中项都包含 source_harness 和 skill_action，因此可以跨不同 harness 追溯召回来源。梦境周期在 WAL 保护下将情景学习成果整合到 LESSONS.md。

召回有意采用词法检索（BM25 + 显著性），其中包含与情景事件一同建立索引的 LESSONS.md 文档层。这是范围选择，并非排行榜上的成绩宣称。当前未提供向量／嵌入召回：可选的 vectors cargo 功能（默认关闭，不包含在发布二进制文件中）只会下载模型，不会用它进行排序（docs/vectors.md）。

详情：ARCHITECTURE.md · SPEC.md · docs/http-api.md

---

常见问题

这是第一个／唯一一个跨 harness 的记忆工具吗？ 不是。还有其他项目（包括大型项目）。dreamd 的核心定位是存储模型：使用你已经纳入版本控制的纯文本文件，而不是宣称自己开创了一个类别。

我需要 Rust 吗？ 按推荐方式使用时不需要。npx -y dreamd-mcp 会下载预编译二进制文件。只有从源代码构建时才需要 Rust。

记忆存在哪里？ 在 <project>/.agent/ 中。.agent/.dreamd/ 下的守护进程和索引都是本地数据，并已加入 gitignore。你可以手动读取和编辑 JSONL／Markdown；持久化追加操作应通过守护进程／MCP 进行，以确保只有一个写入者。

如果我想彻底清除数据怎么办？ 请参阅完全重置存储。没有 dreamd reset --all 命令。要卸载 dreamd 本身，请运行 dreamd uninstall — 详情见：packages/dreamd-mcp/README.md。此操作会停止正在运行的进程并清除缓存；若要移除每用户的服务条目（systemd 单元、LaunchAgent 或 Windows 任务计划程序登录任务），则需另行运行 dreamd service uninstall。该命令的可选参数 --purge 会删除守护进程主目录 ~/.agent/，但绝不会删除任何项目的 .agent/ 存储（docs/install.md）。

Windows 支持情况如何？ 仅部分支持。dreamd watch 会在环回 TCP 上提供 HTTP API，并使用 auth.json 中的 bearer token；POST /api/v1/learn 可正常使用。梦境周期和 Tantivy 索引则无法运行 — io::write_atomic 在 Windows 上仍会返回 Unsupported。如需整合和搜索，请使用 WSL2 或 Linux/macOS 主机。npm 启动脚本仅会为 Linux x86_64 和 macOS（x86_64／arm64）下载预编译二进制文件，因此在 Windows 原生环境中需要通过 cargo 构建。详情见：docs/windows.md。

所有功能会一直免费吗？ Apache-2.0 核心版是开源的。未来可能推出高级版。仅支持自托管（不提供托管式 SaaS）。

更多故障排除信息：docs/troubleshooting.md。

---

路线图

时间	内容
v0.1.0 (2026-08-05)	BM25 词法召回，Linux + macOS，确定性梦境周期，npm dreamd-mcp
v0.1.1 (2026-09-14)	LLM 梦境周期，LESSONS.md 语义层（仍为 BM25 × 显著性，而非嵌入），Windows 监视+学习，Linux / macOS / Windows 上的 dreamd service
v1.0.0 (2026-10-02)	自 v0.1.1 以来的稳定版本：dreamd memory 分支 / diff / bisect，来源记录 + doctor --provenance，dreamd forget，dreamd blame，recall --without，salience-drift，HTTP 召回中的 explain=1 引用。召回仍为 BM25 × 显著性
v1.0.1 (2026-10-21)	补丁：依赖安全修复（rustls、rustls-webpki、webpki-roots、quinn-proto），以及与 1.0.0 版本树匹配的打印字符串。召回无变化
后续计划	Windows 原子写入（梦境周期 + 索引）、向量召回、发布 WasTrue 基准测试

---

文档

文档	内容
GUIDE.md	20 分钟教程指南
docs/README.md	完整文档索引
docs/http-api.md	REST API（Unix 套接字 / Windows 回环 TCP）
docs/configuration.md	TOML 配置和环境变量
docs/troubleshooting.md	常见故障
docs/glossary.md	领域术语
SPEC.md	磁盘存储契约
docs/salience.md	显著性公式深度解析
docs/branching-guide.md	记忆分支：branch、checkout、diff、bisect
docs/provenance.md	来源记录格式，以及 doctor --provenance 的检查内容
docs/observability.md	召回引用（explain=1）和显著性漂移
docs/spec/	该契约的两页 .agent/ 摘要
ARCHITECTURE.md	工程决策
CONTRIBUTING.md	开发环境设置和 RFC 流程
SECURITY.md	威胁模型
docs/marketing.md	产品故事和定位

本地 Criterion 基准测试的热召回延迟数据见 PERF.md。这些数据不是产品宣传重点。要自行重新运行基准测试，请参阅 docs/benchmarks.md。

---

状态

v1.0.1 已发布（GitHub 标签 v1.0.1，2026-10-21；npm 上的 dreamd-mcp 1.0.1 已发布到 latest 和 next）。这是一个补丁版本：修复依赖项安全问题并更正打印的字符串，不包含新命令（CHANGELOG.md）。MCP Registry 条目 io.github.botzrDev/dreamd 是单独由人工发布的（RELEASING.md）。上方标记为“1.0.0 中新增”的命令需要 1.0.0 或更高版本。CLI 命令：setup、init、watch、mcp、dream、doctor、status、service、recall、blame、score、salience-drift、memory、forget、archive、migrate、reset workspace、vectors、uninstall、update、version（dreamd --help 显示完整列表；使用 npm 方式时请运行 npx -y dreamd-mcp <cmd>——该 shim 只转发部分命令，详见 packages/dreamd-mcp/README.md）。默认构建中，vectors enable 会以状态码 2 退出，且不会改变 recall 行为。支持 Linux、macOS 和部分 Windows 功能（watch + learn；不支持 dream cycle 或 index）。如果你通过 cargo install --path crates/dreamd-cli 原地升级 cargo 安装的二进制文件，并在每用户服务下运行守护进程，请随后执行 dreamd service restart 重启，以便监督进程加载新二进制文件（docs/install.md）。

层级	状态
SPEC.md v0.1	已交付
参考实现（守护进程、HTTP API、dream cycle、Tantivy recall）	已交付
MCP 服务（dreamd mcp + npx dreamd-mcp shim）	已在 npm 上发布
CI / 跨平台矩阵	Lint、test、build、二进制大小门禁、DCO（Windows 作业仅供参考）
一致性验证	参考实现 alpha 测试套件（scripts/alpha/）；未进行正式认证

---

WasTrue 基准测试

一项单独的评测，用于判断记忆系统是否会更新后来发生变化的事实。本仓库中的测试框架只是脚手架，此处未发布结果表格。上方的 Next 列表中列出了发布该表格的计划。脚手架的方法说明见：scripts/benchmark/README.md。

编码 recall 基准

Token 是以空白字符分隔的词。每个片段会完整装入，直到下一个片段会超出预算为止。Stuffing 会保留最新的干扰项。Dreamd 执行一次 dreamd dream --no-llm，然后将 k=32 的 recall 装入相同预算。

python3 scripts/benchmark/coding_oracle.py 输出 dreamd_only=12 both=0 stuffing_only=0 neither=0 n=12 budget_tokens=36。

---

平台

Linux 和 macOS（完整支持）。Windows 支持通过回环 TCP 进行 watch + learn；在原子写入功能实现前，dream cycle 和 Tantivy index 仅支持 Unix。详见 docs/windows.md。

---

dreamd 的定位

dreamd 是三个协作仓库之一，它们共同构成一个产品：dreamOS，第一台你可以放心交出钥匙的电脑——它代表你采取行动，在结构上无法执行你未授权的操作，并且能够证明自己做过什么。其底层内核是 momo；旁边的沙箱是 aegis。momo 的章程（RFC-009，经 RFC-011 修订，于 2026-09-26 接受）将 dreamd 记载为产品支柱之一的 托管于 Linux 的证明：记忆以用户拥有的普通文件形式保存，并带有来源信息——用产品的话来说，就是 The Memory。同一修订还将来源账本的发展目标——每种效果都能追溯到导致它的数据，且任何数据都不能导致超出其自身信任标签的效果——定义为一项应先有独立规范的设计。当前发布的任何内容都没有实现信任标签：source_harness 由调用方声明，来源账本（docs/provenance.md）记录的是衍生关系，而非信任——它没有签名，也没有任何机制会依据它进行限制——并且 SECURITY.md 明确说明，注入的经验不会经过过滤。momo 仓库在内核首次公开发布前保持私有；在产品 v1 发布前，不会宣布、预览或营销该产品；本段只是指引，并非发布公告。

参与贡献

请参阅 CONTRIBUTING.md。参与即表示你同意遵守行为准则。安全问题报告：请参阅 SECURITY.md（请勿公开提交漏洞问题）。

许可证

Apache-2.0。请参阅 LICENSE 和 NOTICE。