# 记忆同步（跨设备项目记忆共享）

> 把**项目记忆**（项目关键记忆 KEY、项目日志、关键记忆归档、项目待办）与**全局记忆**（全局记忆、用户档案、每日日志、生活/工作/每日待办）在多台电脑之间同步——在办公室改的结论，回家打开同一项目，记忆已经在了。

---

## 是什么（30 秒）

DSH 的记忆存在本机 `~/.dsh/memories/`，正常情况下只属于这一台电脑。**记忆同步**让指定项目的记忆通过 Git 与远端对账，实现跨设备共享：

- 本机文件永远完整：断网也能读能写，同步只是"攒一批合一次"；
- 想同步的项目才同步（**逐项目开关，默认全部关闭**）——没开过的项目，行为与未安装本模块时完全一致；
- 两台设备**自动认亲**：同一代码仓库地址 = 同一项目，无需任何配置。

## 三个开关（启用层级）

| 层级 | 开关 | 位置 | 默认 | 作用 |
|---|---|---|---|---|
| 模块 | 「记忆同步」 | Memory Evolve 设置 → 配置 | 关 | 让「记忆同步」Tab 可用。**只是模块可见，不代表任何项目开始同步** |
| 项目 | 「本项目同步」 | 记忆同步 Tab | 关 | 当前项目是否参与同步。打开 = 初始化并开始对账；关闭 = 本项目停用（记忆完整保留本地） |
| 轨 | 「同步范围：项目记忆轨」 | 记忆同步 Tab | 开 | 项目记忆（KEY + 项目日志 + 归档 + 项目待办）是否参与；全局记忆另有**四个独立轨开关**（全局记忆/用户档案/每日日志/待办，记忆同步 Tab「全局记忆同步」区，**仅共享记忆仓库可用**，默认关） |

未打开「本项目同步」的项目：不建 Git 仓库、不给条目生成身份证、磁盘状态与未安装本模块时逐字节一致。

## 记忆远端：怎么选

记忆同步 = **一个记忆远端 + 每项目一条专属分支**（`dsh-shared/<项目身份>`，自动命名、跨设备一致）。远端来源一个配置（默认零配置）：

| | 不填地址（默认） | 填共享记忆仓库地址 |
|---|---|---|
| 记忆远端 | **你的主代码仓库**（专属分支，不污染代码） | **共享记忆仓库**——一个专门放记忆的私有仓库，所有项目共用 |
| 项目记忆 | ✅ 同步（专属分支） | ✅ 同步（专属分支，自动转存到此仓库） |
| 全局记忆 | ❌ 不可用（全局记忆不属于任何项目，主代码仓库放不下） | ✅ 可用（每轨一条命名空间分支，独立开关） |
| 隐私 | **代码仓库公开 = 记忆也公开** | 记忆与代码彻底隔离 |
| 老配置 | 一期旧分支（`dsh-shared/memory` / `main`）自动识别、继续沿用，零迁移 | 同左 |

**怎么选**：代码仓库是私有的 → 什么都不用填，点「开始同步」；代码公开（GitHub 开源等）或想独立管理记忆 → 填一个共享记忆仓库地址（一个仓库装所有项目的记忆）。Tab 的「操作」区有可折叠的完整说明，状态卡片会显示当前记忆远端类型。

**切换记忆远端**：本地记忆永远是完整正本，切换只是换对账对象——填了共享仓库地址，本项目记忆自动合并进它的专属分支；清空地址则回到主代码仓库。旧分支留在原仓库不删（留档），需要清理时由你显式确认。

## 全局记忆同步（仅共享记忆仓库）

**全局记忆**（全局记忆 MEMORY.md / 用户档案 USER.md / 每日日志 daily/*.md / 待办 TODOS-life.md、TODOS-work.md、daily/*.todo.md）不属于任何项目——它的跨设备同步需要一个**专属的存放处**：共享记忆仓库（记忆同步 Tab 填了地址后自动初始化，记忆根目录建一个只放全局记忆文件的独立 Git 仓库）。

- **四个独立轨开关**（默认关，opt-in）：全局记忆 / 用户档案 / 每日日志 / 待办——开哪个同步哪个，每轨一条命名空间分支（`dsh-shared/memory-global` / `user` / `daily` / `todo-global`），互不干扰；
- **同步**：记忆同步 Tab「全局记忆同步」区点「同步 / 同步并推送」（推送永远需你显式触发）；
- **不填共享仓库地址的项目**：不出现全局同步区（全局记忆保持纯本地，行为与未安装本模块一致）；
- 每日日志等老全局条目启用同步时按内容确定性补发身份证（双设备同内容同 ID，合并对齐）。

## 日常使用

### 用 GUI（唯一操作通道——记忆同步完全由你在 Tab 手动操作，2026-08-13 起不再提供 AI 命令）

对话页左侧的「记忆同步」Tab：

- **状态卡片**：项目身份、记忆远端类型（主代码仓库 / 共享记忆仓库）、远端分支、未提交 N 条、落后远端 M 个、冲突 K 条、待迁移的旧目录提示；
- **操作按钮**：开始同步（用代码仓库，零配置）、填共享记忆仓库地址（可选）、同步（拉取并合并）、同步并推送（**点击 = 你显式同意推送**）、停用本项目；
- **冲突列表**：两台设备同时改了同一条记忆时出现——每条显示三方版本（共同版本/本机/远端），选「采用本机 / 采用远端 / 两者都要」，解决后自动提交。

## 工作原理（简版）

- 记忆写入照常**实时落盘、完全不碰 Git**——同步是"攒一批合一次"，零写入延迟；
- 每次同步：**拉取远端 → 在内存里三方合并（共同祖先 / 本机 / 远端）→ 原子写回 → 双父提交**。合并规则：各自新增都保留、单侧修改自动采用、双侧都改了同一条才进人工；**Git 冲突符号永远不会出现在记忆文件里**；
- 条目身份证（`[id:xxxx]`，展示层不可见）是跨设备合并的锚点：老记忆启用同步时按内容确定性补发——两台设备上同一条老记忆补发出同一个 ID，才能正确对齐；项目待办使用自己的 tag id（`[id: xxxx]`），合并器同样按 id 对齐；
- 网络操作（fetch/push）在独立子进程执行、超时保护，凭证缺失不会卡死；合并写盘与记忆写入用同一把锁互斥，断电中断后下次同步自动恢复。

## 安全保证

- 记忆机制本身一行不改，同步只是叠加；
- 代码仓库的分支与历史零影响（记忆在专属分支 `dsh-shared/<项目身份>`）；
- 记忆目录误删可从 Git 历史恢复；两个项目不会串记忆（远端身份校验 + 分支决策只认 PROVENANCE.projectId）；
- **推送永远需要你显式触发**（GUI 按钮点击），不存在自动推送；
- 停用同步不删任何数据，随时可重新启用；切换记忆远端不删任何数据，旧分支留档。

## 已知边界

- 一个仓库（含 monorepo）共享一份项目记忆，不做子目录级拆分（二期可加覆盖）；
- 一期老分支（`dsh-shared/memory` / `main`）自动识别兼容、继续沿用；新项目统一走专属分支；
- 全局记忆（用户档案/每日日志/提示词等）的跨设备同步为二期，且仅共享记忆仓库可用；
- `file://` 等本地路径远端无法跨设备共享（自动回退纯本地）；
- 不填地址时记忆随代码仓库走：公开仓库 = 记忆也公开（填共享记忆仓库可隔离）；
- 主仓库更换 remote 地址 → 项目身份变化 → 旧记忆目录成为孤儿（记忆同步 Tab 可查看旧目录并迁移，自动并入为二期；更换前的旧身份目录需人工处理）；
- 本机无 git 或 git 过旧（< 2.28）：自动降级兼容，同步时如实报错并给出指引；
- **Windows 换行（autocrlf）**：Windows Git 默认把 LF 转 CRLF 会破坏记忆文件分隔符——记忆仓库自带 `.gitattributes`（`* -text`）+ 仓库级 `core.autocrlf false` 强制 LF（初始化时写入，随仓库传播）；存量被转成 CRLF 的仓库同步时自动无损归一化，无需人工处理。

## 二期规划（本期未做）

- 定时自动同步（间隔可配）；自动推送（可开关）；
- 删除墓碑机制（删除操作跨设备收敛）；
- pre-push hook 联动（代码推送前可选检查记忆未推送）；
- 记忆 Tab 内嵌状态行。