@max-null/dsh-memory 0.20.0 → 0.22.0

package/README.md

@@ -122,7 +122,9 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 
 **动机**：2026-10-18 的事故——`.dsh` 下的 storages 被外部整目录删除后，本插件的写入路径（读—改—写全量覆盖）在空磁盘上把内存里的 global 记忆覆盖成一条；而当时 `memory.json` **没有任何一份存在于 `.dsh` 之外**，无从恢复。
 
-**机制**：插件启动后每小时（可配）把记忆文件**只读复制**到 `<home>/.dsh-backups/memory/<YYYYMMDD-HHmmss>/`，并写一份 `manifest.json` 记录来源与文件清单。**插件关闭（dispose）时再补一次**——定时器只在运行期间生效，关 DSH 前最后一段变更靠这一次兜住。保留最近 14 份（可配，**只作用于记忆快照**），超期自动清理。
+**机制**：插件启动后每小时（可配）把记忆文件**只读复制**到 `<DSH_HOME 的兄弟目录>/.dsh-backups/memory/<YYYYMMDD-HHmmss>/`，并写一份 `manifest.json` 记录来源与文件清单。**插件关闭（dispose）时再补一次**——定时器只在运行期间生效，关 DSH 前最后一段变更靠这一次兜住。保留最近 14 份（可配，**只作用于记忆快照**），超期自动清理。
+
+默认根**跟着 `DSH_HOME` 走**：缺省 `DSH_HOME=~/.dsh` 时就是 `~/.dsh-backups/memory`；隔离实例（不同 `DSH_HOME`）各自落在自己的兄弟目录，不会把快照混进同一份。同时它仍在 `DSH_HOME` **之外**——2026-10-18 那次事故是整个 `.dsh` 被删，备份必须活在外面。
 
 **日记另走一条路**：`<DSH_HOME>/diary/*.md` 与记忆同一轮复制，但落在**固定目录** `~/.dsh-backups/memory/diary-archive/`，**只增不删**，不参与上面的轮转。两边的不对称是实的：记忆快照丢一份还有别的份（同一份数据的多个时间点副本），归档里每一篇都是日记的唯一副本，丢了没有任何地方能重建。日记那一侧改过就以日记为准覆盖（人可能在事后改过错字），归档里有而日记里已没有的篇目一律保留——那正是归档的全部价值。归档目录名不匹配轮转正则，因此不需要给清理逻辑开白名单。
 
@@ -130,18 +132,62 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 
 | 项 | 默认值 |
 |---|---|
-| 备份内容 | `memory.json`（global）+ `memory_project_*.json`（project）+ `<DSH_HOME>/diary/*.md` |
-| 目标目录 | 记忆：`~/.dsh-backups/memory/<时间戳>/`（**在 `DSH_HOME` 之外**）；日记：`~/.dsh-backups/memory/diary-archive/` |
+| 备份内容 | `memory.json`（global）+ 每个打开过的工作区各一份 `memory_project_*.json` + `<DSH_HOME>/diary/*.md` |
+| 目标目录 | 记忆：`<DSH_HOME 的兄弟目录>/.dsh-backups/memory/<时间戳>/`（**在 `DSH_HOME` 之外**；缺省 `DSH_HOME` 下即 `~/.dsh-backups/memory/`）；日记：同一根下的 `diary-archive/` |
 | 间隔 | 60 分钟（首次延迟 1 分钟）；**插件关闭时另补一次** |
 | 保留 | 记忆：最近 14 份；日记：全部（只增不删） |
 | 失败行为 | 只写日志，不影响记忆读写与启动 |
 
 **边界**：
 
-- 只备份**当前工作区**的 project 文件（`<cwd>/.dsh/storages/`）；其它工作区的 project 记忆不在备份范围。
+- 备份**本轮运行打开过的所有工作区**的 project 文件：来源是引擎按会话 cwd 记下的那份工作区账，每轮备份时现取。**本轮一次都没打开过的工作区不在范围内**——备份是定时任务，没有「当前工作区」可问，打开过的才留得下痕迹。多个工作区给出同名文件时加递增后缀，绝不覆盖。
 - 只读文件、只复制——**绝不复用引擎的写入路径**。写路径会先 `reload()` 再合并，磁盘缺失时它会把内存覆盖掉，正是这次事故的成因；备份不能走同一条路。
 - 日记按**逐字节内容**判断是否已备份过，不按 mtime：复制与编辑都会动 mtime，内容才是事实。
 
+## 云同步（2026-11-11）
+
+把本机记忆镜像到一个 git 仓库，多个环境之间共享同一份记忆。
+
+**为什么是「一条记忆一个文件」。** 整份 `memory.json` 放进 git 会撞：2026-11-06 实测，两端各新增一条记忆后 merge，`git` 报 `CONFLICT (content)`——两条记录挤在同一个插入点，按「取一边」解决会**静默丢掉另一端那条**，而 git 仍报「合并成功」。改成一条一个文件后同一场景是 `Merge made by the 'ort' strategy`，0 冲突。
+
+**项目身份用项目名，不用路径。** 本机 `H:\MaxNull\WorkStation` 与另一台机器 `D:\WorkStation` 是同一个项目——目录名（统一小写）决定它在 `records/project/` 下落到哪。用绝对路径哈希的话，换个盘符就成了另一个项目，记忆会静默分裂成两份互不相认的。
+
+```yaml
+memory:
+  sync:
+    mirrorDir: ''                    # 缺省 <DSH_HOME>/memory-sync
+    remote: ''                       # https 远端；缺省只做本地提交
+    branch: main
+    envName: ''                      # 本环境短名，冲突留证时用作后缀
+```
+
+token **不写进配置**：从环境变量 `DSH_MEMORY_SYNC_TOKEN` 或既有凭据机制取。
+
+| 工具 | 作用 |
+|---|---|
+| `memory_sync` | `status` 只看状态 / `pull` 拉取并导入 / `push` 镜像并推送 |
+| `memory_conflicts` | 列出**未被自动裁决**的冲突 |
+
+**仓库形态**：
+
+```
+<mirrorDir>/
+  records/global/<uuid>.json            一条记忆一个文件
+  records/project/<项目名>/<uuid>.json
+  tombstones/<uuid>.json                forget 留下的痕迹（不删记录文件）
+  conflicts/<uuid>.<env>.json           两边都改过时，两个版本都留着
+```
+
+**边界**：
+
+- **冲突不自动裁决。** 同一条被两个环境同时修改时，两个版本都写进 `conflicts/`，本地版本保留并标记待处理。记忆是长期资产，被静默覆盖的那份就没了。代价是冲突会堆到有人处理为止。
+- **删除留墓碑，不删文件。** `memory_forget` 是**真删**（`table.delete`），而另一端的「刚加、我还没拉到」在本地看起来完全一样。靠「上次同步的 id 快照」（`.sync-state.json`）区分：曾同步过、现在没了才是删除。**首次同步永远不产生墓碑**——那时没有「曾经有过」这个信息。
+- **本地瞬态字段不进镜像**：`hitCount` / `lastUsedAt` 每次检索命中都会改，带上它们会让仓库在内容毫无变化时持续变脏。隔离记录（`quarantined`）**整条不导出**——隔离区的存在理由就是它可能含凭据类内容。
+- **首次同步必须 clone**。本地 `git init` 出来的仓库与远端没有共同祖先，push 会被拒（`not a simple fast-forward`）。这条是 2026-11-11 第一次连真仓库时撞出来的。
+- 传输层用 `isomorphic-git`（纯 JS，走 HTTPS + PAT），**不依赖系统 git**——移动端装的东西会被运行时更新清掉，不该把同步链的地基押在上面。
+
+**没有调度器。** 目前靠模型显式调用 `memory_sync`；`autoPull` / `autoPush` 尚未实现。
+
 ## 使用流程（写入即生效，人为例外干预）
 
 提示词模板库（0.6.0）：`prompt_search / prompt_get / prompt_list / prompt_add` 四个工具管理**模板库**——

package/dist/backup.d.ts

@@ -31,8 +31,14 @@ export interface MemoryBackupConfig {
 export interface MemoryBackupOptions {
     /** global 记忆的根（`$DSH_HOME/storages`）。 */
     globalRoot: string;
-    /** project 记忆的根（`<cwd>/.dsh/storages`）。 */
-    projectRoot: string;
+    /**
+     * project 记忆的根，一个工作区一项（`<cwd>/.dsh/storages`）。
+     *
+     * 是数组而非单值：项目记忆**按工作区分散**，一次运行里通常会打开好几个
+     * （本机实测同时存在 WorkStation / deepseek-harness / seek-soul-in-darkness
+     * 三份各自独立）。只备份一个等于默认放弃其余工作区的历史。
+     */
+    projectRoots: readonly string[];
     /** 日记的根（`$DSH_HOME/diary`）；缺省不备份日记。 */
     diaryRoot?: string;
     /** 备份根目录。 */

package/dist/backup.js

@@ -129,7 +129,7 @@ export function runMemoryBackup(options) {
         ? undefined
         : archiveDiary(options.diaryRoot, options.targetRoot, log);
     const globalFiles = candidateFiles(options.globalRoot, log).map(name => ({ name, from: join(options.globalRoot, name) }));
-    const projectFiles = candidateFiles(options.projectRoot, log).map(name => ({ name, from: join(options.projectRoot, name) }));
+    const projectFiles = options.projectRoots.flatMap(root => candidateFiles(root, log).map(name => ({ name, from: join(root, name) })));
     const sources = [...globalFiles, ...projectFiles];
     if (sources.length === 0) {
         log('memory backup: 没有可备份的记忆文件');
@@ -150,10 +150,22 @@ export function runMemoryBackup(options) {
         return { dir: null, files: [], pruned: [], error: message };
     }
     const files = [];
+    // 多个工作区可能给出同名文件（backend 名由 cwd 哈希得出，不同工作区几乎不会撞，
+    // 但不该把「备份的完整性」押在哈希碰撞概率上）。撞了就加递增后缀，绝不覆盖——
+    // 一次备份里静默少一份，等于这次备份没有做过。
+    const used = new Set();
     for (const source of sources) {
         try {
-            copyFileSync(source.from, join(dir, source.name));
-            files.push(source.name);
+            let name = source.name;
+            for (let suffix = 1; used.has(name); suffix += 1) {
+                name = source.name.replace(/\.json$/u, `-${String(suffix)}.json`);
+            }
+            copyFileSync(source.from, join(dir, name));
+            used.add(name);
+            files.push(name);
+            if (name !== source.name) {
+                log(`memory backup: ${source.from} 与本次快照里的同名文件冲突，落位为 ${name}`);
+            }
         }
         catch (error) {
             log(`memory backup: 复制 ${source.name} 失败: ${reason(error)}`);
@@ -163,7 +175,9 @@ export function runMemoryBackup(options) {
         writeFileSync(join(dir, 'manifest.json'), `${JSON.stringify({
             createdAt: now.toISOString(),
             globalRoot: options.globalRoot,
-            projectRoot: options.projectRoot,
+            // 记全部来源根：事后要判断「某个工作区的记忆到底有没有被备份到」，
+            // 只能靠这份清单——文件名里的哈希反推不出工作区路径。
+            projectRoots: [...options.projectRoots],
             files,
             // 日记不在本次快照目录里，manifest 只记「这一轮归档做了什么」，不列篇名。
             ...(diary === undefined ? {} : { diary: { root: options.diaryRoot, ...diary } }),

package/dist/engine.d.ts

@@ -292,6 +292,45 @@ declare module '@deepseek-ai/cordis' {
         'memory/changed'(change: MemoryChange): void;
     }
 }
+/**
+ * 存储层状态保留旧枚举（auto/suggest）+ injected 可选——旧文件必须能
+ * 过 schema 校验，读时由 normalizeBlock 迁移（一次性兼容转换，不重写文件）。
+ */
+type StoredStatus = MemoryStatus | 'auto' | 'suggest';
+interface StoredBlock {
+    namespace: MemoryNamespace;
+    status: StoredStatus;
+    injected?: boolean;
+    /** 隔离位（2026-09-15）；缺省 = 未隔离。 */
+    quarantined?: boolean;
+    /** 隔离原因（规则名）。 */
+    quarantineReason?: string;
+    /** 命中次数（2026-09-15 淘汰机制）；缺省 0。 */
+    hitCount?: number;
+    /** 写入来源（2026-09-15）；缺省 = 旧记录（来源未知；迁移不动它）。 */
+    source?: MemorySource;
+    /** 注入由信号自动开启（true）还是人工设置（false/缺省）；只有自动开的会被自动降级。 */
+    injectedAuto?: boolean;
+    /** 有效性锚点（2026-09-15）；缺省 = 未绑定锚点。 */
+    anchor?: MemoryAnchor;
+    /** 锚点已失效（会话启动校验写入）；失效只降权并标注，不删除。 */
+    stale?: boolean;
+    /** 失效原因（锚点名 + 声明值 vs 当前值）。 */
+    staleReason?: string;
+    content: string;
+    keywords: string[];
+    createdAt: number;
+    updatedAt: number;
+    lastUsedAt?: number;
+    /** 混合检索向量（0.5.2，仅有 embeddings 配置时生成；明文可读）。 */
+    vector?: number[];
+    /** 记录类别（0.6.0 模板库；缺省 fact）。 */
+    kind?: MemoryKind;
+    /** 记忆主题（0.20.0）：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …；缺省 = 未分类。 */
+    topic?: string;
+    /** prompt 索引元数据（仅 kind==='prompt'）。 */
+    meta?: PromptMetaIndex;
+}
 /**
  * 嵌入能力（0.5.2 混合检索）：缺省不配置 = 纯 BM25（行为不变）；
  * 配置后 memory_search 以 BM25 与语义结果做 RRF 融合，向量持久化到
@@ -330,6 +369,12 @@ export interface MemoryConfig {
      * 实现只读文件、只复制，见 `backup.ts` 的文件头。
      */
     backup?: MemoryBackupConfig;
+    /**
+     * 云同步配置（2026-11-11）：`{ mirrorDir, remote?, branch?, envName? }`。
+     *
+     * 缺省不配 = 不同步。设计见 `docs/设计/2026-11-06-记忆云同步-设计方案.md`。
+     */
+    sync?: unknown;
     /**
      * 日记开关的**部署默认值**（2026-10-24）。运行中的选择在面板里改，写入
      * `$DSH_HOME/memory-settings.json`；两边都开才开——否则部署时关掉会被
@@ -360,6 +405,14 @@ export declare class MemoryEngine extends Service {
     private globalTable?;
     /** project 域按工作区 cwd 懒打开 + 缓存（多会话并发各工作区独立）。 */
     private projectTables;
+    /**
+     * 各 storage backend 的清理函数（摘名 + 关闭）。
+     *
+     * 不挂在独立 effect 上：cordis 的 dispose 后进先出，运行时才注册的那些会比
+     * `memory.domainsClose` 早执行，导致 domain 还握着 unit 时 backend 先关。
+     * 统一由 {@link closeBackends} 在 domain 全部关闭之后按插入顺序执行。
+     */
+    private readonly backendClosers;
     /** 子项目发现缓存（④-B 2026-09-19）：key = 工作区路径；值 = 其直接子目录中带记忆的（按条数降序）。 */
     private readonly neighborCache;
     /** 进行中的子项目发现（key → promise）：预热是 fire-and-forget，之后的显式调用与它合流而非重复扫描。 */
@@ -394,6 +447,15 @@ export declare class MemoryEngine extends Service {
     get lastSweepReport(): SweepReport | undefined;
     constructor(ctx: import('@deepseek-ai/cordis').Context, config?: MemoryConfig);
     protected [Service.init](): Promise<void>;
+    /**
+     * 注册一个 storage backend 并返回它的清理函数（摘名 + 关闭）。
+     *
+     * 清理函数**不立刻挂到 effect 上**，而是交给 {@link closeBackends} 在 domain 全部关闭
+     * 之后统一执行——理由见 `[Service.init]` 的注释。
+     */
+    private registerBackend;
+    /** 依次摘名并关闭所有已注册的 backend；必须由外部保证 domain 已先关闭。 */
+    private closeBackends;
     /** 打开全局存储域（init 与 reload 共用；backend 复用已注册实例）。 */
     private openGlobalFacility;
     /** 工作区 project 存储根（<workspace>/.dsh/storages，随 git 分享）。 */
@@ -405,6 +467,27 @@ export declare class MemoryEngine extends Service {
      * 表已打开是常态，那时这条路径不该付出任何异步代价。
      */
     projectOpen(projectCwd?: string): boolean;
+    /**
+     * 已经打开过的工作区 project 存储根（`<cwd>/.dsh/storages`），供备份遍历。
+     *
+     * 备份是定时任务、没有会话 cwd，所以「现在在哪个工作区」这个问题它答不出来。
+     * 此前它拿 `process.cwd()` 兜底，而那是**进程启动目录**（桌面壳里通常是 profile
+     * 目录），与真实工作区无关——2026-11-05 实测：292 条项目记忆从未进过快照，备份
+     * 一直对着一个空目录反复报成功。
+     *
+     * 打开过的表由会话 cwd 驱动，见过的工作区都留在 {@link projectTables} 里；这是
+     * 备份唯一可靠的工作区来源。返回空数组表示「这次运行还没打开过任何工作区」，
+     * 由调用方决定回退策略。
+     */
+    projectStorageRoots(): string[];
+    /**
+     * 已经打开过的工作区 cwd 列表（同步导出用）。
+     *
+     * 与 {@link projectStorageRoots} 的区别：那个给的是存储根（`<cwd>/.dsh/storages`），
+     * 这个给 cwd 本身。导出要按 cwd 调 `list({ namespace: 'project' }, cwd)`，从存储根
+     * 反推 cwd 依赖目录层级，不如直接给。
+     */
+    projectCwds(): string[];
     /**
      * 按工作区 cwd 取 project 表（懒打开 + 缓存）。无 cwd（未选工作区）
      * 返回 undefined——调用方（工具/面板）按此跳过 project 部分。
@@ -806,6 +889,21 @@ export declare class MemoryEngine extends Service {
      * 起可改 `injected`：**省略则保留原值**（连 `injectedAuto` 一起不动），给值即接管。若新
      * 内容命中危险规则则转为隔离（与写入路径同一判定），并连带撤下注入。
      */
+    /**
+     * 按**指定 id** 写入一条外来记录——同步导入专用。
+     *
+     * 与 {@link remember} 的区别：`remember` 生成新 id 并走内容判定；`adopt` 接收另一端
+     * 记录的 id 与整块内容，原样落进来。**必须保 id**——否则同一件事在五个环境里会变成
+     * 五条互不相干的记忆，而「共享一份记忆」正是同步要达成的事。
+     *
+     * 与 {@link update} 的区别：`update` 只改可编辑字段（content / keywords / injected /
+     * anchor）并把 `updatedAt` 推到当下；`adopt` 连 `createdAt`、`stale`、隔离标记一起搬
+     * ——那是「另一端此刻的完整状态」，不是一次本地编辑。因此也**不重算 `updatedAt`**：
+     * 拿导入时刻覆盖掉原始时间会让冲突判定（按 `updatedAt` 取新）失效。
+     *
+     * 仍然过 `putBlock` 的 schema 校验（门一）：外来数据一样要合规。
+     */
+    adopt(id: MemoryId, block: StoredBlock, projectCwd?: string): Promise<MemoryRecord>;
     update(id: MemoryId, patch: MemoryPatch, projectCwd?: string): Promise<MemoryRecord>;
     /** {@link update} 的实现体；必须经 `writeScope` 进入。 */
     private updateInner;

package/dist/engine.js

@@ -174,6 +174,14 @@ export class MemoryEngine extends Service {
     globalTable;
     /** project 域按工作区 cwd 懒打开 + 缓存（多会话并发各工作区独立）。 */
     projectTables = new Map();
+    /**
+     * 各 storage backend 的清理函数（摘名 + 关闭）。
+     *
+     * 不挂在独立 effect 上：cordis 的 dispose 后进先出，运行时才注册的那些会比
+     * `memory.domainsClose` 早执行，导致 domain 还握着 unit 时 backend 先关。
+     * 统一由 {@link closeBackends} 在 domain 全部关闭之后按插入顺序执行。
+     */
+    backendClosers = [];
     /** 子项目发现缓存（④-B 2026-09-19）：key = 工作区路径；值 = 其直接子目录中带记忆的（按条数降序）。 */
     neighborCache = new Map();
     /** 进行中的子项目发现（key → promise）：预热是 fire-and-forget，之后的显式调用与它合流而非重复扫描。 */
@@ -213,17 +221,55 @@ export class MemoryEngine extends Service {
         this.config = config;
     }
     async [Service.init]() {
-        // backend 只注册一次：registry 对重名注册抛 duplicate-backend
-        // （storage/tests/registry.spec 实测），reload 不得重复注册。
+        // backend 注册是**一个 effect**：`dsh-storage` 的 `BackendRegistry.register()` 契约是
+        // 「registration is an effect: the returned disposer removes the name」。丢掉那个 disposer
+        // 会让名字活过 fiber——issue #3 的真实成因：插件市场的更新流程会在同一进程里重新组合
+        // profile 并做一次构建校验，本 entry 第二次激活时 `register('memory-global', …)` 撞上
+        // 自己上次留下的名字，报 `duplicate-backend`；而那句报错被上层包装成「更新前的构建
+        // 未能验证恢复，请检查该 profile」，把用户引向「配置坏了」这个错误方向。
+        //
+        // **摘名与关闭不能各挂一个 effect**：cordis 的 dispose 后进先出，而 project backend 的
+        // effect 是运行时（`openProjectTable`）才注册的，会比这里晚注册、早执行——于是 domain
+        // 还握着 unit 时 backend 先被关掉，留下没释放的 open-slot，下一个实例打开同一目录
+        // 就失败（表现为「表打开了但一条都读不到」）。所以统一收进一个 closers 列表，
+        // 由本 effect 在**所有 domain 关闭之后**依次执行。
+        //
+        // reload 不重新注册 backend（见 `reload()`：它只重开 domain），所以这样改不改变
+        // reload 的语义——这些 closers 只在 dispose 时触发。
         const globalBackend = new JsonStorageBackend(this.config.globalRoot ?? globalRoot());
-        this.ctx.storage.backend.register('memory-global', globalBackend);
+        this.backendClosers.push(this.registerBackend('memory-global', globalBackend));
         await this.openGlobalFacility();
-        this.ctx.effect(() => () => {
-            void this.facility?.closeAll();
+        this.ctx.effect(() => async () => {
+            await this.facility?.closeAll();
             for (const facility of this.projectFacilities.values())
-                void facility.closeAll();
+                await facility.closeAll();
+            await this.closeBackends();
         }, 'memory.domainsClose');
     }
+    /**
+     * 注册一个 storage backend 并返回它的清理函数（摘名 + 关闭）。
+     *
+     * 清理函数**不立刻挂到 effect 上**，而是交给 {@link closeBackends} 在 domain 全部关闭
+     * 之后统一执行——理由见 `[Service.init]` 的注释。
+     */
+    registerBackend(name, backend) {
+        const unregister = this.ctx.storage.backend.register(name, backend);
+        return async () => {
+            unregister();
+            await backend.close();
+        };
+    }
+    /** 依次摘名并关闭所有已注册的 backend；必须由外部保证 domain 已先关闭。 */
+    async closeBackends() {
+        for (const close of this.backendClosers.splice(0)) {
+            try {
+                await close();
+            }
+            catch {
+                // 清理失败不该让 dispose 整体失败——名字可能已被别处摘掉。
+            }
+        }
+    }
     /** 打开全局存储域（init 与 reload 共用；backend 复用已注册实例）。 */
     async openGlobalFacility() {
         const facility = new DomainFacility(this.ctx, { backend: 'memory-global', routes: {} });
@@ -252,6 +298,31 @@ export class MemoryEngine extends Service {
             return false;
         return this.projectTables.has(join(projectCwd));
     }
+    /**
+     * 已经打开过的工作区 project 存储根（`<cwd>/.dsh/storages`），供备份遍历。
+     *
+     * 备份是定时任务、没有会话 cwd，所以「现在在哪个工作区」这个问题它答不出来。
+     * 此前它拿 `process.cwd()` 兜底，而那是**进程启动目录**（桌面壳里通常是 profile
+     * 目录），与真实工作区无关——2026-11-05 实测：292 条项目记忆从未进过快照，备份
+     * 一直对着一个空目录反复报成功。
+     *
+     * 打开过的表由会话 cwd 驱动，见过的工作区都留在 {@link projectTables} 里；这是
+     * 备份唯一可靠的工作区来源。返回空数组表示「这次运行还没打开过任何工作区」，
+     * 由调用方决定回退策略。
+     */
+    projectStorageRoots() {
+        return [...this.projectTables.keys()].map(cwd => this.projectRootFor(cwd));
+    }
+    /**
+     * 已经打开过的工作区 cwd 列表（同步导出用）。
+     *
+     * 与 {@link projectStorageRoots} 的区别：那个给的是存储根（`<cwd>/.dsh/storages`），
+     * 这个给 cwd 本身。导出要按 cwd 调 `list({ namespace: 'project' }, cwd)`，从存储根
+     * 反推 cwd 依赖目录层级，不如直接给。
+     */
+    projectCwds() {
+        return [...this.projectTables.keys()];
+    }
     /**
      * 按工作区 cwd 取 project 表（懒打开 + 缓存）。无 cwd（未选工作区）
      * 返回 undefined——调用方（工具/面板）按此跳过 project 部分。
@@ -323,7 +394,10 @@ export class MemoryEngine extends Service {
         }
         if (!this.registeredProjectBackends.has(backendName)) {
             const backend = new JsonStorageBackend(root);
-            this.ctx.storage.backend.register(backendName, backend);
+            // 与 `memory-global` 同样走 closers 列表：`registeredProjectBackends` 只能防**同一
+            // 实例**内的重复注册，换一个实例这个 Set 就是空的，挡不住上一个 fiber 残留的名字
+            // （issue #3 里这一点被 `memory-global` 先撞上，所以看不出来）。
+            this.backendClosers.push(this.registerBackend(backendName, backend));
             this.registeredProjectBackends.add(backendName);
         }
         const facility = new DomainFacility(this.ctx, { backend: backendName, routes: {} });
@@ -1519,6 +1593,34 @@ export class MemoryEngine extends Service {
      * 起可改 `injected`：**省略则保留原值**（连 `injectedAuto` 一起不动），给值即接管。若新
      * 内容命中危险规则则转为隔离（与写入路径同一判定），并连带撤下注入。
      */
+    /**
+     * 按**指定 id** 写入一条外来记录——同步导入专用。
+     *
+     * 与 {@link remember} 的区别：`remember` 生成新 id 并走内容判定；`adopt` 接收另一端
+     * 记录的 id 与整块内容，原样落进来。**必须保 id**——否则同一件事在五个环境里会变成
+     * 五条互不相干的记忆，而「共享一份记忆」正是同步要达成的事。
+     *
+     * 与 {@link update} 的区别：`update` 只改可编辑字段（content / keywords / injected /
+     * anchor）并把 `updatedAt` 推到当下；`adopt` 连 `createdAt`、`stale`、隔离标记一起搬
+     * ——那是「另一端此刻的完整状态」，不是一次本地编辑。因此也**不重算 `updatedAt`**：
+     * 拿导入时刻覆盖掉原始时间会让冲突判定（按 `updatedAt` 取新）失效。
+     *
+     * 仍然过 `putBlock` 的 schema 校验（门一）：外来数据一样要合规。
+     */
+    async adopt(id, block, projectCwd) {
+        return this.writeScope(projectCwd, async () => {
+            const table = block.namespace === 'project'
+                ? await this.projectTableFor(projectCwd)
+                : this.requireTable('global');
+            if (table === undefined) {
+                throw new Error('adopt: project memory requires a workspace cwd');
+            }
+            await this.putBlock(table, id, block);
+            const record = toRecord(id, block);
+            this.ctx.emit('memory/changed', { operation: 'remembered', record });
+            return record;
+        });
+    }
     async update(id, patch, projectCwd) {
         return this.writeScope(projectCwd, () => this.updateInner(id, patch, projectCwd));
     }

package/dist/index.d.ts

@@ -33,6 +33,12 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     semanticTopK: z<number, number, "plain">;
     embeddings: z<any, any, "plain">;
     backup: z<any, any, "plain">;
+    /**
+     * 云同步配置（2026-11-11）：`{ mirrorDir, remote?, branch?, envName? }`。
+     *
+     * 缺省不配 = 不同步。设计见 `docs/设计/2026-11-06-记忆云同步-设计方案.md`。
+     */
+    sync: z<any, any, "plain">;
     /**
      * 日记开关。默认开——这是**功能默认，不是采集默认**。
      *
@@ -54,6 +60,12 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     semanticTopK: z<number, number, "plain">;
     embeddings: z<any, any, "plain">;
     backup: z<any, any, "plain">;
+    /**
+     * 云同步配置（2026-11-11）：`{ mirrorDir, remote?, branch?, envName? }`。
+     *
+     * 缺省不配 = 不同步。设计见 `docs/设计/2026-11-06-记忆云同步-设计方案.md`。
+     */
+    sync: z<any, any, "plain">;
     /**
      * 日记开关。默认开——这是**功能默认，不是采集默认**。
      *

package/dist/index.js

@@ -5,9 +5,10 @@
  * model tools, a stable guidance section, and a recall context.
  */
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, dirname } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { MemoryEngine } from "./engine.js";
+import { conflictFiles, syncPull, syncPush, syncStatus } from "./sync-service.js";
 import { MemoryGateway } from "./remote.js";
 import { runMemoryBackup } from "./backup.js";
 import { ANCHOR_KINDS } from "./anchors.js";
@@ -43,6 +44,12 @@ export const Config = z.object({
     semanticTopK: z.number(),
     embeddings: z.any(),
     backup: z.any(),
+    /**
+     * 云同步配置（2026-11-11）：`{ mirrorDir, remote?, branch?, envName? }`。
+     *
+     * 缺省不配 = 不同步。设计见 `docs/设计/2026-11-06-记忆云同步-设计方案.md`。
+     */
+    sync: z.any(),
     /**
      * 日记开关。默认开——这是**功能默认，不是采集默认**。
      *
@@ -62,6 +69,21 @@ export const Config = z.object({
  * @param config - 插件配置。
  * @returns 是否启用日记。
  */
+/**
+ * 定时备份的默认根：`DSH_HOME` 的**兄弟目录** `.dsh-backups/memory`。
+ *
+ * 为什么是兄弟目录而不是直接 `homedir()`：隔离实例（不同 `DSH_HOME` 并行跑，比如 dev
+ * 与装版）本该各有自己的备份树。写死 `homedir()` 会让它们的快照混进同一份目录——
+ * 2026-11-07 实测：dev 实例把 `globalRoot` 指向 `home-100` 的快照写进了装版的备份根，
+ * 两份 manifest 混在一起，人工恢复时容易拿错。
+ *
+ * 兄弟目录同时保证它**在 `DSH_HOME` 之外**——2026-10-18 那次事故是整个 `.dsh` 被删，
+ * 备份必须活在外面，所以不能退化成 `$DSH_HOME/backups`。
+ */
+function defaultBackupRoot() {
+    const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
+    return join(dirname(dshHome), '.dsh-backups', 'memory');
+}
 function diaryOn(config) {
     const raw = config?.diary;
     if (raw === undefined || raw === null)
@@ -990,32 +1012,124 @@ export async function apply(ctx, config) {
         },
         presentCall: args => present('Read diary', 'read', args.date),
     }));
+    // ── 云同步（2026-11-11）──────────────────────────────────────────────
+    //
+    // **不向模型暴露 git**：模型只说「同步一下 / 看看状态」，具体 add/commit/push 由插件
+    // 决定。把 `git pull --rebase && git add && git commit && git push` 那一串交给模型，
+    // 出错难排查，也容易越权。
+    //
+    // 缺省不启用：没配 `memory.sync` 时这两个工具直接报「未配置」，而不是默默什么都不做——
+    // 静默不动作比报错更坏。
+    const syncConfig = () => {
+        const raw = (config?.sync ?? {});
+        const mirrorDir = typeof raw.mirrorDir === 'string' && raw.mirrorDir !== ''
+            ? raw.mirrorDir
+            : join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'memory-sync');
+        return {
+            mirrorDir,
+            ...typeof raw.remote === 'string' && raw.remote !== '' ? { remote: raw.remote } : {},
+            ...typeof raw.branch === 'string' && raw.branch !== '' ? { branch: raw.branch } : {},
+            ...typeof raw.envName === 'string' && raw.envName !== '' ? { envName: raw.envName } : {},
+        };
+    };
+    ctx.tools.register(defineTool({
+        name: registered('memory_sync'),
+        description: 'Push this machine\'s memories to the sync repo, pull other machines\' memories back, or inspect sync state. Conflicts are never auto-resolved — both versions are kept under conflicts/ for a human to settle. 把本机记忆推到同步仓库 / 拉回其他机器的记忆 / 查看同步状态。冲突不会自动裁决：两边版本都留在 conflicts/ 里等人处理。',
+        parameters: {
+            action: {
+                type: 'string',
+                required: true,
+                enum: ['status', 'pull', 'push'],
+                description: 'status = 只看状态（不读不写）；pull = 拉取并导入；push = 镜像、提交并推送。',
+            },
+        },
+        output: {
+            schema: { type: 'object', additionalProperties: true, properties: {} },
+            render: (_args, value) => renderJson(value),
+        },
+        async execute(args) {
+            const cfg = syncConfig();
+            const run = args.action === 'push'
+                ? await syncPush(memory, cfg)
+                : args.action === 'pull'
+                    ? await syncPull(memory, cfg)
+                    : await syncStatus(cfg);
+            // 工具返回值要求 `Record<string, JsonValue>`；这几个结果都是普通可序列化对象，
+            // 结构化类型对不上而已。走一遍 JSON 往返顺便保证它确实可序列化。
+            return JSON.parse(JSON.stringify(run));
+        },
+        presentCall: args => present('Sync memory', 'other'),
+    }));
+    ctx.tools.register(defineTool({
+        name: registered('memory_conflicts'),
+        description: 'List memory conflicts left by sync. Sync never auto-resolves them: if two machines changed the same memory, both versions were kept. 列出同步留下的记忆冲突。同步不会自动裁决——两端改过同一条时，两个版本都留着。',
+        parameters: {
+            action: {
+                type: 'string',
+                required: true,
+                enum: ['list'],
+                description: 'list = 列出 conflicts/ 下的冲突文件。',
+            },
+        },
+        output: {
+            schema: { type: 'object', additionalProperties: true, properties: {} },
+            render: (_args, value) => renderJson(value),
+        },
+        async execute() {
+            const cfg = syncConfig();
+            const files = conflictFiles(cfg);
+            return { count: files.length, files };
+        },
+        presentCall: () => present('List memory conflicts', 'other'),
+    }));
     // 定时备份（2026-10-18 事故后新增）：只读复制，绝不走引擎的写入路径。
     // 首次延迟 1 分钟避开启动高峰；此后按 `backup.intervalMinutes` 重复；`unref` 不挡进程退出。
     const backup = config?.backup;
     if (backup?.enabled !== false) {
-        const targetRoot = backup?.targetRoot ?? join(homedir(), '.dsh-backups', 'memory');
+        const targetRoot = backup?.targetRoot ?? defaultBackupRoot();
         const intervalMs = Math.max(1, backup?.intervalMinutes ?? 60) * 60_000;
         const keep = Math.max(1, backup?.keep ?? 14);
-        const roots = {
-            globalRoot: config?.globalRoot ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'storages'),
-            projectRoot: config?.projectRoot ?? join(process.cwd(), '.dsh', 'storages'),
-            // 日记在 `storages` 之外，得单独给根——漏了这一项就等于「备份记忆、不备份日记」。
-            diaryRoot: diaryDir(),
+        const globalRoot = config?.globalRoot ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'storages');
+        /**
+         * 本次要备份的 project 根。
+         *
+         * **每次备份时现算**，不能像 `globalRoot` 那样在启动时定死：工作区是随会话逐步
+         * 打开的，启动那一刻引擎里一个都没有，那时算出来永远是空的。
+         *
+         * 三档来源：引擎打开过的工作区（由会话 cwd 驱动，最可靠）、显式配置的
+         * `projectRoot`、两者都空时回退 `process.cwd()`。中间那一档要注意：`MemoryConfig`
+         * 把它注释成「project 记忆的根」，但**引擎实现从不读它**——它只在这里影响备份。
+         * 最后一档只是兜底——它是进程启动目录而非工作区，桌面壳里通常指向 profile
+         * 目录，那正是「项目记忆零快照」的成因（2026-11-05 实测：738 KB / 292 条从未
+         * 进过快照，备份一直对着空目录报成功）。
+         */
+        const projectRoots = () => {
+            const found = new Set(memory.projectStorageRoots());
+            if (config?.projectRoot !== undefined)
+                found.add(config.projectRoot);
+            if (found.size === 0)
+                found.add(join(process.cwd(), '.dsh', 'storages'));
+            return [...found];
+        };
+        const backupOnce = () => {
+            runMemoryBackup({
+                globalRoot,
+                projectRoots: projectRoots(),
+                // 日记在 `storages` 之外，得单独给根——漏了这一项就等于「备份记忆、不备份日记」。
+                diaryRoot: diaryDir(),
+                targetRoot,
+                keep,
+            });
         };
         ctx.effect(() => {
-            const first = setTimeout(() => {
-                runMemoryBackup({ ...roots, targetRoot, keep });
-            }, 60_000);
-            const timer = setInterval(() => {
-                runMemoryBackup({ ...roots, targetRoot, keep });
-            }, intervalMs);
+            const first = setTimeout(backupOnce, 60_000);
+            const timer = setInterval(backupOnce, intervalMs);
             timer.unref();
             return () => {
                 clearTimeout(first);
                 clearInterval(timer);
                 // 关闭时补一次：定时器只在运行期间生效，关 DSH 前最后一段变更靠这里兜住。
-                runMemoryBackup({ ...roots, targetRoot, keep });
+                backupOnce();
             };
         });
     }