Dreamd

MCP文档知识

提供方 未标注

文档知识 stdio · 本地进程 会话登录 社区 / 第三方 ClaudeCursorVS CodeCline
查看接入方式

Local-first memory shared across coding agents. One `.agent/` folder of plain JSONL and Markdown in the repo, read and written by Claude Code, Cursor and...

一句话选型结论

按资料字段整理

Dreamd 属于文档知识类 MCP 服务器,stdio · 本地进程,会话登录,可直接接入 Claude、Cursor、VS Code 等,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类文档知识 传输方式stdio · 本地进程 鉴权会话登录 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

文档知识
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

记忆

安装与配置

stdio · 本地进程 会话登录
客户端在本机拉起子进程,数据不出本机
npx -y dreamd-mcp setup # scaffold .agent/ and wire your harness npx -y dreamd-mcp # MCP server (stdio): what the harness spawns

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
文档检索问答

在你的文档库里按问题找答案。

知识库读写

把新资料写进知识库,随用随取。

内容整理

把零散资料归纳成结构化笔记。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude、Cursor、VS Code,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好会话登录对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在文档知识场景里让模型直接调用外部能力的人。
  • 已经在用 Claude、Cursor 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Dreamd当前 未标注 stdio · 本地进程 本地部署 有 2026-11-20
dify 未标注 stdio · 本地进程 本地部署 有 2026-04-11
open-webui 未标注 stdio · 本地进程 本地部署 有 2026-04-11
JeecgBoot 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Cherry Studio 未标注 未标注 未标注 无 2026-05-17
mempalace 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

文档知识
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类文档知识本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式会话登录远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-11-20上游最后核验时间

详细介绍

17.3 KB
来自项目仓库与上游目录的原文,未做删改

dreamd

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 harness
npx -y dreamd-mcp # MCP server (stdio): what the harness spawns


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 to | dreamd gives you |
|---|---|
| See what drove an answer | `dreamd blame ` 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 from | Every 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 consistent | `dreamd doctor --provenance` recomputes the ledger's Merkle root and lists orphan, missing and corrupt edges. Read-only |
| Remove a bad memory | `dreamd forget ` removes the event and the lesson state that names it. `--dry-run` shows what would change; `--proof ` 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 yourself | Plain 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 it
npx -y dreamd-mcp blame "deploy without tests" --explain

# 2. Check the lesson it came from and what that lesson cites
cat .agent/semantic/LESSONS.md
npx -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-run
npx -y dreamd-mcp forget evt_... --proof forget-receipt.json

# 4. Review the change like code
git 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 config
npx -y dreamd-mcp # MCP server (stdio): your harness spawns this


stdio is the default transport. `dreamd mcp --bind 127.0.0.1:` 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```bash
cargo install dreamd --version ^1.3

That requirement skips the 0.0.0 name reservation on crates.io. 1.3.1 is the first version that installs the binary. Rust 1.95.0 or newer.

From a git checkout, cargo install --path crates/dreamd-cli builds this tree. 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-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.

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.jsonl
npx -y dreamd-mcp dream --dry   # preview the lesson the next cycle would write
npx -y dreamd-mcp doctor

The npm shim does not put dreamd on PATH. Use npx -y dreamd-mcp 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

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

Location Contents Commit?
/.agent/ Episodic JSONL, semantic lessons, personal prefs Yes (this is the shared memory)
/.agent/.dreamd/ Local index, daemon state, config.toml, provenance ledger, decay archive (snapshots/), memory branches (branches/) No (gitignored by init); git clean -fdX deletes it, see troubleshooting
~/.agent/registry.toml Which projects have a store No
~/.agent/dreamd.sock Daemon API socket (while running) No
~/.agent/star-asked Set after setup has asked for a GitHub star, once per user No

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 --help is the reference for flags.

Command · What it does
dreamd recall · Ranked search as a markdown table. --explain prints the salience factors per hit; --without / --without-cluster drop hits before top-k, so you can see the answer without a suspect memory
dreamd blame · Which stored memories drove a query's ranking: id, timestamp, skill_action, bm25, salience, total, layer. --json for one compact array
dreamd score · Top memories by salience alone, no query
dreamd salience-drift · Salience distribution, top clusters, and drift against the snapshot from seven days earlier. See docs/observability.md
dreamd dream --dry · Print the LESSONS.md the next cycle would write, without writing
dreamd forget · Remove one episodic event and the lesson state that names it. --dry-run writes nothing; --proof writes a forget-receipt/1.0 file (a receipt, not a signed proof). Refuses while the daemon is running
dreamd doctor --provenance · Recompute 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\ · bisect · Deprecated in 1.2.0, removed in 2.0. .agent/ is plain files, so use git. See docs/branching-guide.md


Architecture (one paragraph)


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

Version What
v1.3.2 (2026-11-17) dreamd watch opens a project again when git clean -fdX deletes its .agent/.dreamd/, and no dreamd process writes into a store that replaced its own; an empty dedup key no longer drops learnings; watch no longer deletes a file at DREAMD_SOCK that is not a socket
v1.3.1 (2026-11-16) A failed dream cycle no longer blocks the next one; an event's content can no longer forge a lesson; the first requests to a project, at once or after it idles, no longer fail on the daemon's own writer lock; an idle dreamd mcp session no longer holds a connection to the daemon
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 /.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.2 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).

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

Doc What
GUIDE.md 20-minute walkthrough, including inspect and undo
docs/README.md Full documentation index
docs/provenance.md Provenance ledger format and what doctor --provenance checks
docs/observability.md Recall citations, blame, counterfactual recall and salience drift
SECURITY.md Threat model, including the lesson-injection surface
docs/http-api.md REST API (Unix socket / Windows loopback TCP)
docs/configuration.md TOML config and env vars
docs/troubleshooting.md Common failures
SPEC.md On-disk contract
docs/salience.md Salience formula deep-dive
ARCHITECTURE.md Engineering decisions
CONTRIBUTING.md Dev 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:

  • GitHub Sponsors
  • Patreon
  • Ko-fi

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.

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Dreamd 怎么安装?

在客户端按下面的安装命令接入:npx -y dreamd-mcp setup # scaffold .agent/ and wire your harness npx -y dreamd-mcp # MCP server (stdio): what the harness spawns。装完在客户端配置里引用同一个包或端点。

Dreamd 怎么在 Claude、Cursor、VS Code 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Dreamd 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Dreamd 需要 API Key 吗?

资料标注需要会话登录认证,使用前准备好对应凭据,并按最小权限配置。

Dreamd 支持哪些客户端?

资料标注支持 Claude、Cursor、VS Code、Cline、Codex、Zed;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Dreamd 能提供哪些能力?

资料显示能力标签包括 记忆。具体工具清单以官方文档为准。

Dreamd 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Dreamd 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-11-20。