# shared-memory-mcp

**让多个 Claude 窗口 / 账号共用一份记忆和一个交接信箱。零依赖、纯本地。**
**One shared notebook and mailbox for several Claude windows or accounts. Zero dependencies, fully local.**

[中文](#中文) · [English](#english)

---

## 中文

### 它解决什么问题

同时开着好几个 Claude（多个桌面窗口、多个账号、桌面版加 Claude Code）时，它们互相看不到对方的对话。
换窗口就要重新交代一遍背景，上一个窗口做到哪、踩过什么坑，下一个窗口一无所知。

这个 MCP 服务器给它们一个共同的"笔记本"和"信箱"：

- **共享记忆**：存下你的偏好、项目、决定，任何窗口都能搜到。
- **交接信箱**：窗口之间留言（不是即时推送，对方调用 `msg_read` 时才看到），按分类（交接、版本、任务……）归档，已读的也能随时翻出来。
- 数据只是本机上的两个 JSONL 文本文件，**不联网、不上传**，你可以直接打开看、备份、删除。

### 安装

需要 Node.js 18+。

```bash
git clone <本仓库地址>
cd shared-memory-mcp
node bin/install.js --lang zh        # 写入 Claude 桌面版的配置（会先备份）
```

然后**完全退出**所有 Claude 桌面版（包括托盘图标）再重新打开。

常用选项：

| 选项 | 作用 |
|---|---|
| `--dir <目录>` | 记忆存放位置，默认 `~/.shared-memory-mcp` |
| `--config <文件>` | 指定某个 `claude_desktop_config.json`，可重复（多开的桌面版各有自己的配置） |
| `--lang zh` | 工具描述用中文（默认英文） |
| `--dry-run` | 只显示会改哪些文件，不真改 |
| `--undo` | 只移除本工具的那一项，其他设置不动 |

每个配置文件修改前都会备份为 `*.bak-时间`。配置文件格式有误时会跳过，不会强行改。

**Claude Code：**

```bash
claude mcp add shared-memory -e SHARED_MEMORY_DIR="$HOME/.shared-memory-mcp" -- node /path/to/shared-memory-mcp/src/server.js
```

多个窗口要共用同一份记忆，只要它们的 `SHARED_MEMORY_DIR` 指向同一个目录。

### 工具

| 工具 | 用途 |
|---|---|
| `memory_save` | 保存一条记忆（可带标签） |
| `memory_search` | 搜索：空格分隔关键词，默认命中任意一个；`match: "all"` 要求全中；可按 `tag` 过滤、限制 `limit` 条 |
| `memory_delete` | 按编号删除 |
| `msg_send` | 给另一个窗口留言，可带分类 |
| `msg_read` | 读发给自己的未读留言并标记已读；`all_history` 看全部往来 |
| `msg_board` | 按分类翻信箱，不管发给谁、读没读过；`list` 查看分类和数量 |

### 让它真的被用起来

模型不会自己想起来调用工具。建议在 Claude 的偏好设置（Settings → Profile）里加几句，例如：

> 每次新对话开始时，先调用 memory_search 查有没有相关记忆，再调用 msg_read 看有没有给我的留言。用户说"记住"的内容一定要用 memory_save 存下来。我的名字叫 <窗口名>。

### 并发与限制

- 所有写入都会先拿一个目录锁，多个窗口同时读写不会互相覆盖（有多进程压力测试）。崩溃留下的锁 30 秒后自动清理。
- 锁依赖本地文件系统，**不要把数据目录放在网盘同步目录或网络共享上同时用**。
- 记忆是**明文**保存的。不要让 Claude 把密码、API Key 之类存进去。
- 搜索是简单的关键词匹配，不是语义搜索。
- 没有任何认证：能读到这个目录的人，就能读到全部记忆。

### 开发

```bash
npm test      # 无依赖，使用 Node 自带的 node:test
```

### 从旧版升级

旧版配置里用 `MEMORY_FILE=<目录>/memories.jsonl` 的写法依然可用，已有的 `memories.jsonl` 和 `messages.jsonl` 不需要迁移。

---

## English

### What it is

When you run several Claude windows or accounts at once (multiple desktop instances, or Desktop plus Claude Code),
they cannot see each other's conversations. This MCP server gives them a shared notebook and a mailbox:

- **Shared memory** – save preferences, projects and decisions; every window can search them.
- **Handoff mailbox** – leave messages for another window (pull-based: the recipient sees them when it calls `msg_read`), filed by topic such as handoff / version / task, browsable later even after they were read.
- Data is two plain JSONL files on your machine. **No network, no upload.** You can open, back up or delete them.

### Install

Requires Node.js 18+.

```bash
git clone <this repo>
cd shared-memory-mcp
node bin/install.js           # edits Claude Desktop config(s), backing them up first
```

Fully quit and reopen Claude Desktop afterwards. Options: `--dir`, `--config` (repeatable, one per Desktop profile), `--lang zh`, `--dry-run`, `--undo` (removes only this server's entry).

Claude Code:

```bash
claude mcp add shared-memory -e SHARED_MEMORY_DIR="$HOME/.shared-memory-mcp" -- node /path/to/shared-memory-mcp/src/server.js
```

Windows that should share memory simply point `SHARED_MEMORY_DIR` at the same folder.

### Tools

`memory_save`, `memory_search` (any/all keywords, tag filter, limit), `memory_delete`, `msg_send`, `msg_read`, `msg_board`.

### Getting the model to use it

Models do not call tools on their own initiative. Add a line to your Claude preferences such as: *"At the start of every conversation call memory_search, then msg_read. Save anything I ask you to remember with memory_save. My window name is <name>."*

### Concurrency and limits

- Every write takes a directory lock, so several processes can share the files safely (covered by multi-process stress tests). Stale locks from crashed processes are cleaned up after 30 s.
- The lock relies on a local filesystem: do not put the data directory on a synced cloud folder or network share that several machines use at the same time.
- Memories are stored in **plain text**. Do not ask Claude to store passwords or API keys.
- Search is plain keyword matching, not semantic search.
- There is no authentication: anyone who can read the directory can read every memory.

### Development

```bash
npm test      # zero dependencies, uses Node's built-in test runner
```

### Upgrading from the first version

Old configs using `MEMORY_FILE=<dir>/memories.jsonl` keep working, and existing `memories.jsonl` / `messages.jsonl` files need no migration.

## License

MIT. Copyright holder in `LICENSE` is a placeholder; fill in your name before publishing.