dreamd — Claude Code MCP server: shared memory for coding agents
A local MCP server that keeps agent memory as plain files inside your repo, so several harnesses read and write the same store.
claude mcp add dreamd -- npx -y dreamd-mcpWhat dreamd does
dreamd puts memory in a .agent/ folder at the project root. Episodic events land in JSONL, semantic lessons and personal preferences sit alongside them. Any MCP-aware harness — Claude, Cursor, Cline and others — points at that same folder, so a lesson one agent records is available to the next one. Everything stays readable: cat it, grep it, diff it in git.
The MCP surface is deliberately small: search_nodes and append_node. The rest is CLI work against the same files — ranked lookup with dreamd recall, ranking breakdown with dreamd blame, salience scoring, memory branches, and single-event removal via dreamd forget. Writes go through the daemon so there is one writer at a time.
Your project needs a root sentinel first: .git/, Cargo.toml, package.json or pyproject.toml. A fresh folder needs git init before setup. The npm shim does not expose the dreamd binary on PATH, so recall, score, status, archive and migrate only work after cargo install --path crates/dreamd-cli. The core is Apache-2.0 and self-hosted.
What it helps with
- carry context across Claude and Cursor sessions without re-explaining
- keep project lessons in files you can review in a diff
- trace which stored memories shaped a search ranking
- switch memory to a snapshot and compare two branches
- drop a single episodic event along with the lesson naming it
Example prompts for the agent
- Search memory for what we already learned about this project's build
- Append a lesson: tests fail without the
DATABASE_URLenvironment variable - Show me which memories drove the ranking for the migrations query
How to install dreamd
Platform CLI
claude mcp add dreamd -- npx -y dreamd-mcpPlatform CLI
codex mcp add dreamd -- npx -y dreamd-mcpConfig file
{
"mcpServers": {
"dreamd": {
"command": "npx",
"args": [
"-y",
"dreamd-mcp"
]
}
}
}Config file
{
"servers": {
"dreamd": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"dreamd-mcp"
]
}
}
}Platform CLI
gemini mcp add dreamd npx -y dreamd-mcpStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about dreamd
How do I install dreamd in Claude Code?
Run claude mcp add dreamd -- npx -y dreamd-mcp and reload the harness. To scaffold the store and write the harness config, run npx -y dreamd-mcp setup first.
What does dreamd do?
It is a local MCP server that reads and writes agent memory in a .agent/ folder inside your project. Two MCP tools are exposed: search_nodes and append_node.
Which files does dreamd write into my project?
.agent/ holds episodic JSONL, semantic lessons and personal preferences — that folder is meant to be committed. Local state under .agent/.dreamd/ stays out of git.
