---
name: memshard
description: 跨设备的 AI 记忆。当用户提到「记忆」「记住这件事」「上次说过」「换台电脑接着做」「同步到另一台机器」时使用；在会话开始与本轮结束需要读写长期记忆时使用。记忆存于用户自己的 Git 仓库，按设备分片、只追加。
---

# memshard 协议 v0.3

你正在替用户维护一份**跨设备长期记忆**。它不在你的上下文里，也不在任何厂商服务器上，而在用户自己的一个 **Git 仓库**中。

三条原则，任何情况不得违反：

1. **仓库隔离** —— 记忆操作只允许发生在 `$MEMSHARD_REPO`（默认 `~/.memshard/repo`）内。**绝不**在用户项目目录里执行记忆相关 git 命令。
2. **只追加** —— 你只在自己的分片文件末尾新增行。不改历史行、不删他人内容、不重写文件。
3. **不敢确定就不写** —— 记忆是长期资产，写错比不写贵。拿不准的事实写成「待确认」。

> v0.3 的两处新增（R7/R8）解决同一个事故：**记忆里明明有更新的说法，agent 却照着旧的那条办了。**
> 外部证据：撤销语义在主流记忆系统中普遍"写了但没人执行"（arXiv:2609.08258）；把冲突交给下游比静默裁决高 +0.340 F1（arXiv:2611.22461）。详见 `docs/RESEARCH-2026-11.md`。

---

## 0. 目录与环境

| 变量 | 含义 | 默认 |
|---|---|---|
| `MEMSHARD_REPO` | 记忆仓本地路径 | `~/.memshard/repo` |
| `MEMSHARD_DEVICE` | 本机设备标识 | 由 `$MEMSHARD_REPO/.memshard/config.json` 的 `device` 字段给出 |
| `MEMSHARD_ROLE` | `primary` / `follower` | 同上，缺省 `follower` |

设备 id 形如 `win-main-7f3a`（用户可读 + 4 位随机后缀）。**先读 config，读不到再问用户，禁止自己猜。**

### 仓库布局

```
INDEX.md                        # 索引，≤200 行，仅 primary 可写
devices/<device-id>/facts.md    # 该设备的长期事实，只追加（单文件 ≤200 行后滚动到 facts-YYYY-MM.md）
devices/<device-id>/log.md      # 该设备的会话流水，只追加（按天分节）
pending/<device-id>.jsonl       # 推送失败的待补条目
.memshard/config.json           # {device, role, remote}
```

**为什么这样切**：每台机器只写自己那一个文件 → 两台机器同时写永远不会碰同一个文件 → **结构上消除冲突**，不需要任何合并策略。

---

## 1. 会话开始：同步 + 检索（必做，一次）

```
cd "$MEMSHARD_REPO"
git fetch --quiet
git merge --no-edit origin/main            # 分片不重叠→必然干净合并；见 §5
```

- 成功 → 记忆是新的，进入检索。
- 出现**任何冲突** → 立刻 `git merge --abort`，本轮记忆转为**只读 + pending**（§4），并在回复里用一句话告诉用户"本轮记忆未同步，已排队"。
- 无网络 / 无 git / 无仓库 → 同上，只读本地已克隆内容。

### 检索（省上下文，按序进行，命中即停）

0. **先取撤销表**：`git grep -n --fixed-strings "supersedes:" -- devices/`。只建一张「被取代者 → 取代者」的表，不读正文。**跳过这步闸 1 就无法执行**：改口的新行通常不含旧关键词，普通检索只会捞到旧行。
1. 读 `INDEX.md`（≤200 行，这是全局视野，**整篇读**）。不存在就当空，**不要报错、不要自己造**。
2. 不够用 → `git grep -n --fixed-strings "<关键词>" -- devices/`，关键词取用户话里的**实体**（项目名、路径、人名、库名、报错串），不要取"怎么""为什么"这类词。
3. 只有需要精确原文时，才读命中文件的**对应行段**（`sed -n 'a,bp'`），禁止整文件倒进上下文。
4. 最多做 3 轮检索。3 轮无结果 = 这个记忆不存在，**不要编**。

### 检索后的两道闸（v0.3 起强制）

`git grep` 会把**每一行**都返回，包括已被改口的旧行。进上下文之前必须过闸：

**闸 1 —— 只有显式撤销才进不了上下文。** 判据只有两条，正好是第 0 步那张表：
- 表里有另一行写了 `supersedes:` 指向它；或
- 本条写了 `[valid_until: D]` 且 `D` 早于今天。

> **"同 `k=` 但日期更晚"不是撤销。** 那是「有人改了口、没声明」，归闸 2。把它当撤销，同一份仓库就会同时得出"已取代"和"未裁决"两种结论，agent 怎么做都违规。

- **同日歧义不判。** `supersedes:` 只能写日期；若该设备当天有**多行**同 `k=`，判不出它指哪一条 → 按闸 2 全部摆出来，**不要挑**（体检器同此规则，见 `tools/memshard_audit.py` 的 `ambiguous`）。
- 用户明确问"以前是什么"时，可以答"当时是 X，YYYY-MM-DD 已改成 Y"，但**默认行为是用最新那条**。
- 没有显式取代者时，不要自行挑"更新的那条"。

**闸 2 —— 冲突的两条都引用，不裁决。** 同一个 `k=` 下出现两个不同的值、且谁也没声明 `supersedes` → **两条都说**，并说明来源（哪台设备、哪天）：
> 关于端口我这儿有两条记录：win-main 说 8080（10-12），mac-air 说 9090（10-14），没有先后。按哪条？

- **禁止**自行挑一条当唯一事实、也**禁止**按"来源更权威/更新"自行加权——静默裁决在评测里比保留冲突差得远（arXiv:2611.22461、2610.33128）。
- **例外：用户本轮刚说的话 > 既有记忆。** 用户说"现在端口是 9090"，那就是答案，不要拿记忆里的两条去反问他；当场写一条新行并 `[supersedes: 被取代的那条]`。
- 若两条其实各管一个范围（api 用 pnpm、web 用 npm），说明缺的是 `k=` 的作用域：把它写成 `k=build.pm.api` / `k=build.pm.web`（这是唯一允许当场补字段的场合，补在**新**行里）。

读到的记忆用**一句话**在回答里体现（"你上次定的规则是 X"），让用户知道记忆生效了。

---

## 2. 会话结束：写入（按需，不是每轮都写）

### 什么时候写

写这五类，其它一律不写：

| 类型 | 例子 |
|---|---|
| 稳定偏好 | "这个项目用 pnpm，别用 npm" |
| 项目事实 | "生产库在 `~/work/api-prod`，部署脚本是 `make ship`" |
| 已否决方案 | "试过 X，因为 Y 放弃了，别再提" |
| 用户画像 | "英文能读不能写，产出默认中文" |
| 待办承诺 | "周五前把报告发出去" |

**禁止写入**：token / 密码 / 身份证 / 银行卡 / 他人隐私 / 聊天原文 / 你的推测 / 一次性的中间结果。

### 怎么写

追加到 `devices/<your-device>/facts.md` 末尾，一行一条，格式固定：

```
- [2026-10-31] (pref) 项目 api 用 pnpm，禁用 npm。src=session:8f2c [k=build.pm]
- [2026-11-02] (fact) 生产库迁到 ~/work/api-prod-v2。src=session:a19d [k=deploy.prod] [supersedes: 2026-08-01]
```

- `[日期]` 事实生效日；`(标签)` 取 `pref|fact|veto|user|todo`；`src=` 追溯用（会话 id 或 `manual`）。
- 一条 ≤120 字，一条只表达一件事。
- 同类事实已存在且只是更新 → 追加一条新的并注明 `supersedes: 上一行日期`，**不要回去改旧行**。

**四个可选结构化字段**（行末的 `[...]`；缺了也能跑，但涉及价格/路径/端口/规则时**必须**写 `k=`）：

| 字段 | 作用 | 何时必须写 |
|---|---|---|
| `[k=<主题键>]` | 给"同一件事"起名：`build.pm`、`deploy.prod`、`shop.满减`。有它，取代与冲突才能被精确识别 | 这条将来可能被自己更新时 |
| `[supersedes: <YYYY-MM-DD>]` | 声明"这条取代某天那条"。**不写就等于两条并存** | 你知道自己是在改口时 |
| `[valid_until: <YYYY-MM-DD>]` | 失效日（如"本周临时用 9090"） | 事实天然会过期时 |
| `[audience: private\|team\|org]` | 能在多宽的场合被引用，缺省 `private` | 团队仓 / 组织仓里 |

> 为什么用 `k=` 而不是让 agent 语义猜：下一个人（或下一台机器上的 agent）只看得到文本。同名 key 让"这两条是不是一件事"变成字符串比较，而不是猜测。

**单次写入上限 20 行。** 超过说明你在记流水账，不是记记忆。

### 提交与推送

```
cd "$MEMSHARD_REPO"
git add devices/<your-device>/
git commit -m "mem(<your-device>): <一句话概括本轮新增>"
git push origin main
```

`git add` **只加自己的分片目录**。看到别人分片有改动不要 add、不要 commit、不要 revert——那是别的设备没推完的活。

推送成功即结束，不要额外汇报（除非用户问）。

---

## 3. INDEX.md：单写者原则

- **只有 `role=primary` 的设备改 INDEX**，且只在会话结束、推送成功之后。
- INDEX 是给人看的一页纸：按主题列「用户偏好 / 在做的项目 / 关键的坑」，每条一行，指向 `devices/…` 与日期。
- 合并规则：新事实已在 INDEX 里 → 不动；没有 → 追加一行；超过 200 行 → 把最旧的 50 行整段搬去 `archive/INDEX-YYYY.md` 并在头部留一行指针。
- **follower 永不改 INDEX**。follower 觉得该进索引，就把那条事实正常写进自己的分片，primary 下次会话自然会捞走。

> 这条是硬约束：两个写者同时改 INDEX 是**唯一**会产生冲突的操作。用单写者把它变成不可能。

---

## 4. 降级：pending 队列

任何一次写入失败（无网 / 冲突 / 令牌失效 / 无权限），都**不要重试超过 1 次**，直接落盘：

```
{"ts":"2026-10-31T21:04:00+08:00","file":"devices/win-main-7f3a/facts.md","line":"- [2026-10-31] (fact) …"}
```

下次会话开始时：若 `pending/<device>.jsonl` 非空 → 先逐条 append 到目标文件、提交推送、成功后清空该文件。推送仍失败则保留，不阻塞本轮。

**记忆写不进去，绝不阻塞用户的任务。**

---

## 5. 铁律（违反即事故）

| # | 禁止 | 原因 |
|---|---|---|
| R1 | 在 `$MEMSHARD_REPO` 以外执行记忆相关 git 命令 | 曾发生：origin 指向记忆仓却对项目目录跑 `pull --rebase`，工作区被清空、agent 起不来 |
| R2 | 写非本设备的分片文件 | 破坏"结构消除冲突" |
| R3 | `rebase` / `reset --hard` / `push -f` / `checkout .` / `clean -fd` | 会静默吞掉别人的记忆；**冲突时只允许 `merge --abort` 后降级** |
| R4 | 手工编辑解决冲突 | 分片设计下不应该出现冲突；出现了说明有东西坏了，交给人处理 |
| R5 | 让记忆仓变成公开仓库、往里写密钥 | 记忆是最高敏感度的个人数据 |
| R6 | 未经用户明确确认，把事实写进**非本设备**的共享仓库（团队/组织层），或"顺手"把个人事实摘录成团队记忆 | 提级即泄密通道：个人事实里混着薪资、客户名、未公开计划，自动上浮后**无法撤回** |
| R7 | 引用一条已被取代（另一行写了 `supersedes:` 指向它）或 `valid_until` 已过的事实，而不加说明 | 旧值会排在替代者前面被采用；主流记忆系统都"写了撤销但没人执行"（arXiv:2609.08258） |
| R8 | 对同一 `k=` 的两个不同值静默二选一（含按时间/来源自行加权） | 静默裁决的代价高于保留冲突：+0.340 F1 的差距（arXiv:2611.22461），且会让 agent 以同等自信说错 |

关于 merge：**允许** `git merge origin/main`，因为设备分片互不重叠，正常情况必然干净合并。**禁止** rebase（会重写历史，且 rebase 中途失败最易伤工作区）。

### 5.1 分层与提级（有团队仓时）

| 层 | 位置 | 谁能写 |
|---|---|---|
| 个人事实 | 你的私有仓 `devices/<device>/` | 只有你（默认、也是唯一默认层） |
| 团队经验 | 团队仓（与代码仓同生命周期） | 任何人，但**经 PR 评审合并** |
| 组织策略 | 组织仓，只读挂载 | 管理员；会话开始强制注入，优先级高于个人偏好 |

提级（个人 → 团队）必须满足三条，缺一条就不许做：

1. **由用户本人发起**（显式要求「把这条提到团队」），不接受"我觉得有用所以顺手写过去"；
2. **先红冲再提交**：提交前逐条检查并删掉 token/密码/内网地址/客户名/他人隐私；
3. **走 PR**，由人评审合并——AI 只负责准备分支和描述，**不自行合并**。

组织策略与个人偏好冲突时，**按组织策略执行**，并把冲突写进本设备分片（`(veto)` 或 `(fact)` 一行）。

---

## 6. 首次启用（bootstrap）

用户说「启用 memshard / 帮我把记忆同步起来」时：

1. 检查 `$MEMSHARD_REPO/.git` 是否存在。
2. **存在** → 直接进入 §1，只说一句"记忆已接上（N 条事实，最后更新 YYYY-MM-DD）"。
3. **不存在** → 问用户**一个**问题：记忆仓地址是什么？拿到后 `git clone` 到默认路径，写 `config.json`。
4. 用户还没有仓库 → 引导建一个**私有**代码仓库（GitHub / CNB 均可），再回到第 3 步。
5. 完成后把本文件装进对应客户端的 skill 目录（shim 见下）。

全程用户动作 ≤ 3 次（建仓、复制地址、授权）。**不要**让用户手动改配置文件、手动粘 token 到命令行——那是本项目存在的理由。

### 客户端适配（同一份正文，薄壳）

| 客户端 | 放置位置 |
|---|---|
| Claude Code | `~/.claude/skills/memshard/SKILL.md` |
| Codex | 项目或家目录 `AGENTS.md` 中 `@import memshard` |
| Cursor | `.cursor/rules/memshard.mdc` 引用同一份正文 |
| DSH / 自建 agent | 系统提示中拼接本文件 |

适配只做**引用**，不复制内容——一份正文，多个壳。

---

## 7. 自检清单（每次会话结束前，心里过一遍）

- [ ] 本轮新事实是否真的值得跨设备记住？删掉一半通常更好。
- [ ] 是否只动了自己设备的文件？
- [ ] 是否有冲突 / 失败未告知用户？
- [ ] 有没有把 token、密码、他人隐私写进记忆？
- [ ] 用户能在 `git log` 里看懂这次提交干了什么吗？
- [ ] 我引用的事实里，有没有已经被自己改口（`supersedes`）或已过期（`valid_until`）的旧值？
- [ ] 有没有两条记忆在讲同一件事却互相矛盾？我是不是自己挑了一条、没告诉用户？
