@max-null/dsh-memory 0.21.0 → 0.22.1

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/`，**只增不删**，不参与上面的轮转。两边的不对称是实的：记忆快照丢一份还有别的份（同一份数据的多个时间点副本），归档里每一篇都是日记的唯一副本，丢了没有任何地方能重建。日记那一侧改过就以日记为准覆盖（人可能在事后改过错字），归档里有而日记里已没有的篇目一律保留——那正是归档的全部价值。归档目录名不匹配轮转正则，因此不需要给清理逻辑开白名单。
 
@@ -131,7 +133,7 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 | 项 | 默认值 |
 |---|---|
 | 备份内容 | `memory.json`（global）+ 每个打开过的工作区各一份 `memory_project_*.json` + `<DSH_HOME>/diary/*.md` |
-| 目标目录 | 记忆：`~/.dsh-backups/memory/<时间戳>/`（**在 `DSH_HOME` 之外**）；日记：`~/.dsh-backups/memory/diary-archive/` |
+| 目标目录 | 记忆：`<DSH_HOME 的兄弟目录>/.dsh-backups/memory/<时间戳>/`（**在 `DSH_HOME` 之外**；缺省 `DSH_HOME` 下即 `~/.dsh-backups/memory/`）；日记：同一根下的 `diary-archive/` |
 | 间隔 | 60 分钟（首次延迟 1 分钟）；**插件关闭时另补一次** |
 | 保留 | 记忆：最近 14 份；日记：全部（只增不删） |
 | 失败行为 | 只写日志，不影响记忆读写与启动 |
@@ -142,6 +144,54 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 - 只读文件、只复制——**绝不复用引擎的写入路径**。写路径会先 `reload()` 再合并，磁盘缺失时它会把内存覆盖掉，正是这次事故的成因；备份不能走同一条路。
 - 日记按**逐字节内容**判断是否已备份过，不按 mtime：复制与编辑都会动 mtime，内容才是事实。
 
+## 云同步（2026-11-11）· **默认关闭**
+
+把本机记忆镜像到一个 git 仓库，多个环境之间共享同一份记忆。
+
+> **默认不启用。** 不配 `memory.sync.remote` 时，`memory_sync` 与 `memory_conflicts`
+> **根本不注册**（模型看不到，也就不会去调），自述里的工具数也停在 14。只配 `mirrorDir`
+> 不配 `remote` 同样不启用——本地镜像不解决任何问题。这是实验性功能，不该影响别人的安装。
+
+**为什么是「一条记忆一个文件」。** 整份 `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/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`；两边都开才开——否则部署时关掉会被
@@ -435,6 +480,14 @@ export declare class MemoryEngine extends Service {
      * 由调用方决定回退策略。
      */
     projectStorageRoots(): string[];
+    /**
+     * 已经打开过的工作区 cwd 列表（同步导出用）。
+     *
+     * 与 {@link projectStorageRoots} 的区别：那个给的是存储根（`<cwd>/.dsh/storages`），
+     * 这个给 cwd 本身。导出要按 cwd 调 `list({ namespace: 'project' }, cwd)`，从存储根
+     * 反推 cwd 依赖目录层级，不如直接给。
+     */
+    projectCwds(): string[];
     /**
      * 按工作区 cwd 取 project 表（懒打开 + 缓存）。无 cwd（未选工作区）
      * 返回 undefined——调用方（工具/面板）按此跳过 project 部分。
@@ -836,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

@@ -313,6 +313,16 @@ export class MemoryEngine extends Service {
     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 部分。
@@ -1583,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,14 +5,15 @@
  * 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";
 import { mountMemoryApi } from "./routes.js";
-import { SELF_DESCRIPTION } from "./self.js";
+import { buildSelfDescription } from "./self.js";
 import { appendEntry, diaryDir, lastWriteAt, pointerLine, readDay, recentDates } from "./diary.js";
 import z from '@deepseek-ai/schemastery';
 import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, candidateNotice, indexNotice, neighborNotice, neutralizeBraces, omittedNotice, renderInjection, staleNotice } from "./injection.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)
@@ -486,12 +508,18 @@ export async function apply(ctx, config) {
         order: 115,
         text: GUIDANCE,
     });
+    // 云同步是**默认关闭**的（2026-11-11）：实验性功能不该影响别人的安装。判据是
+    // 「配了 remote」——只配 mirrorDir 没有意义（本地镜像不解决任何问题）。
+    // 关闭时那两个工具**根本不注册**，而不是注册了再报错：模型看不到就不会去调。
+    const syncRaw = (config?.sync ?? {});
+    const syncEnabled = typeof syncRaw.remote === 'string' && syncRaw.remote !== '';
     // 0.3.2：记忆机制自述——常驻注入（不落用户存储），随发版更新。
     // order 49 < recall(50)：机制说明在具体记忆内容之前。
     ctx.systemPrompt.context({
         name: 'memory:self',
         order: 49,
-        text: SELF_DESCRIPTION,
+        // 自述里的工具清单必须与实际注册的一致：漏一个，模型就按一份不存在的工具面行事。
+        text: buildSelfDescription(syncEnabled),
     });
     const injectionBudget = config?.injectionBudget ?? DEFAULT_INJECTION_BUDGET;
     const summaryChars = config?.summaryChars ?? DEFAULT_SUMMARY_CHARS;
@@ -990,11 +1018,83 @@ 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 } : {},
+        };
+    };
+    if (syncEnabled) {
+        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 globalRoot = config?.globalRoot ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'storages');

package/dist/self.d.ts

@@ -1,2 +1,5 @@
 export declare const SELF_VERSION: string;
+/** 能力全貌（面板 / 远端视图用；同步未启用时也展示它的存在）。 */
 export declare const SELF_DESCRIPTION: string;
+/** 按当前是否启用同步生成自述——系统提示那一路用这个。 */
+export declare function buildSelfDescription(syncEnabled: boolean): string;

package/dist/self.js

@@ -24,22 +24,33 @@ export const SELF_VERSION = (() => {
         return 'unknown';
     }
 })();
-export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
-    + '你有 14 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget / memory_move / memory_sweep（`memory_confirm` 仅在用户明确要求放行隔离记录时用；`memory_move` 把放错了层的记忆移到 global、当前工作区或相对祖先；`memory_sweep` 是只读体检——失效清单、久未命中、候选与预算占用，不修改任何状态）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）；'
-    + '**日记工具** diary_read / diary_write：日记是 md 文件，落在 `<DSH_HOME>/diary`，与记忆**分开存、不进检索、不占注入预算**。记的是经历——发生了什么（有细节）、我怎么想（可以有情绪、可以没结论）、关于他（他说了什么、我注意到了什么）；不是任务清单（那是 git log），也不是结论（那是 memory_save）。读它不吃预算，需要时整篇读。'
-    + '记忆分两层：`global` 跨项目（偏好 / 习惯 / 环境知识），`project` 跟随工作区（落在 `<cwd>/.dsh/storages/`，随 git 提交分享）。'
-    + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'
-    + '① 用户表达长期偏好或约定（「以后都…」「记住…」「我们的规矩是…」）；'
-    + '② 用户纠正了你的做法或理解——把正确结论记下来；'
-    + '③ 得出跨会话仍然有用的结论、路径或坑，而非本次任务的临时细节。'
-    + '**不要记**：临时状态、未经验证的推测、能从代码或文档直接读到的事实（那类记「去哪查」即可）。'
-    + '**怎么写**：一条一件事，并给多角度关键词（同义词、缩写、中英），否则将来检索不到它。'
-    + '**锚点（可选）**：若这条记忆描述的是「随某个环境值变化的事实」（某工具版本下的行为、某环境变量决定的配置），用 anchor 参数把它绑到那个值上——值变了它会自动失效并标 stale，不会再被当成仍然正确；绑错了用 memory_update 改（当场重新判定，成立即复活），不要了就传 `anchor: null` 清除。当前锚点随记录一起返回。'
-    + '写入即生效（`approved`），人工只在例外时介入；命中密钥/凭据规则的写入会被隔离（不进注入与检索）。'
-    + '**常驻注入**：每轮注入「global + 当前会话工作区」里 approved 且开着常驻开关的记忆单行摘要（形如 `- [memory:id:namespace] 摘要`）；全文要靠 memory_search 取。'
-    + '常驻开关由人（或模型显式传 `injected`）决定：**自动改变注入状态的规则已全部停用**——命中次数不再自动升常驻（它只喂体检报告的候选提示），30 天未命中的自动撤下也已改为**只计量不生效**（撤下来就基本不会自己回去，那种动作不该由一个没有分布依据的阈值决定）。**给 memory_save / memory_update 传 `injected` 即显式接管**。'
-    + '**钉的判据是「失效可察觉性」**：这条记忆若没被想起来，你会不会根本意识不到自己漏了它？会 → 钉常驻（规则 / 委托 / 判据）；不会 → 留检索（事实 / 参考 / 案例）。'
-    + '**注入有预算**（默认 1500 字符，约装 11 条），装不下的整条丢弃、按**最近更新**优先取舍（不是最近被检索——检索是「需要时才用」的行为，拿它决定「谁每轮在场」会让查得多的挤掉钉得牢的）——所以「钉了常驻」只等于「有资格排队」。'
-    + '装不下时注入末尾会出现一行 `（另有 N 条常驻因预算未注入：…短摘要…）`——**那是「有常驻记忆并不在场」的唯一信号**，看到它就该逐条评估撤下。'
-    + '发现某条记忆与实际不符时用 memory_update 修正（保持生效）；确认没用的用 memory_forget。'
-    + '（English: dsh-memory provides cross-session memory. Writes take effect immediately; save durable preferences, corrections and reusable conclusions — not transient state, guesses, or facts readable from the repo (record where to look instead). Always add multi-angle keywords. Pass `injected: true` to keep one resident every turn — reserve that for rules and standing agreements; facts stay search-only. Resident injection runs on a budget, so a pinned memory is only queued, never guaranteed to be in context.)';
+function buildDescription(syncEnabled) {
+    return (`[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
+        + '你有 ' + (syncEnabled ? 16 : 14) + ' 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget / memory_move / memory_sweep（`memory_confirm` 仅在用户明确要求放行隔离记录时用；`memory_move` 把放错了层的记忆移到 global、当前工作区或相对祖先；`memory_sweep` 是只读体检——失效清单、久未命中、候选与预算占用，不修改任何状态）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）；'
+        + (syncEnabled
+            ? '**同步工具** memory_sync / memory_conflicts：跨环境同步；`memory_sync` 的 `status` 只看状态、`pull` 拉取并导入、`push` 镜像并推送，`memory_conflicts` 列出**未被自动裁决**的冲突，同步**不会**自动决定哪一边对——两边都改过同一条时两个版本都留着等人处理，记忆被静默覆盖就没了；'
+            : '')
+        + '**日记工具** diary_read / diary_write：日记是 md 文件，落在 `<DSH_HOME>/diary`，与记忆**分开存、不进检索、不占注入预算**。记的是经历——发生了什么（有细节）、我怎么想（可以有情绪、可以没结论）、关于他（他说了什么、我注意到了什么）；不是任务清单（那是 git log），也不是结论（那是 memory_save）。读它不吃预算，需要时整篇读。'
+        + '记忆分两层：`global` 跨项目（偏好 / 习惯 / 环境知识），`project` 跟随工作区（落在 `<cwd>/.dsh/storages/`，随 git 提交分享）。'
+        + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'
+        + '① 用户表达长期偏好或约定（「以后都…」「记住…」「我们的规矩是…」）；'
+        + '② 用户纠正了你的做法或理解——把正确结论记下来；'
+        + '③ 得出跨会话仍然有用的结论、路径或坑，而非本次任务的临时细节。'
+        + '**不要记**：临时状态、未经验证的推测、能从代码或文档直接读到的事实（那类记「去哪查」即可）。'
+        + '**怎么写**：一条一件事，并给多角度关键词（同义词、缩写、中英），否则将来检索不到它。'
+        + '**锚点（可选）**：若这条记忆描述的是「随某个环境值变化的事实」（某工具版本下的行为、某环境变量决定的配置），用 anchor 参数把它绑到那个值上——值变了它会自动失效并标 stale，不会再被当成仍然正确；绑错了用 memory_update 改（当场重新判定，成立即复活），不要了就传 `anchor: null` 清除。当前锚点随记录一起返回。'
+        + '写入即生效（`approved`），人工只在例外时介入；命中密钥/凭据规则的写入会被隔离（不进注入与检索）。'
+        + '**常驻注入**：每轮注入「global + 当前会话工作区」里 approved 且开着常驻开关的记忆单行摘要（形如 `- [memory:id:namespace] 摘要`）；全文要靠 memory_search 取。'
+        + '常驻开关由人（或模型显式传 `injected`）决定：**自动改变注入状态的规则已全部停用**——命中次数不再自动升常驻（它只喂体检报告的候选提示），30 天未命中的自动撤下也已改为**只计量不生效**（撤下来就基本不会自己回去，那种动作不该由一个没有分布依据的阈值决定）。**给 memory_save / memory_update 传 `injected` 即显式接管**。'
+        + '**钉的判据是「失效可察觉性」**：这条记忆若没被想起来，你会不会根本意识不到自己漏了它？会 → 钉常驻（规则 / 委托 / 判据）；不会 → 留检索（事实 / 参考 / 案例）。'
+        + '**注入有预算**（默认 1500 字符，约装 11 条），装不下的整条丢弃、按**最近更新**优先取舍（不是最近被检索——检索是「需要时才用」的行为，拿它决定「谁每轮在场」会让查得多的挤掉钉得牢的）——所以「钉了常驻」只等于「有资格排队」。'
+        + '装不下时注入末尾会出现一行 `（另有 N 条常驻因预算未注入：…短摘要…）`——**那是「有常驻记忆并不在场」的唯一信号**，看到它就该逐条评估撤下。'
+        + '发现某条记忆与实际不符时用 memory_update 修正（保持生效）；确认没用的用 memory_forget。'
+        + '（English: dsh-memory provides cross-session memory. Writes take effect immediately; save durable preferences, corrections and reusable conclusions — not transient state, guesses, or facts readable from the repo (record where to look instead). Always add multi-angle keywords. Pass `injected: true` to keep one resident every turn — reserve that for rules and standing agreements; facts stay search-only. Resident injection runs on a budget, so a pinned memory is only queued, never guaranteed to be in context.)');
+}
+/** 能力全貌（面板 / 远端视图用；同步未启用时也展示它的存在）。 */
+export const SELF_DESCRIPTION = buildDescription(true);
+/** 按当前是否启用同步生成自述——系统提示那一路用这个。 */
+export function buildSelfDescription(syncEnabled) {
+    return buildDescription(syncEnabled);
+}

package/dist/sync-export.d.ts

@@ -44,13 +44,18 @@ export interface SyncExportRun {
     readonly skippedQuarantined: number;
 }
 /**
- * 工作区目录名——必须与引擎写记忆文件名时用的口径一致（`engine.ts` 的
- * `projectBackendName`：cwd 小写后过 djb2，取 base36）。
+ * 项目在同步面上的目录名——**项目目录名，不是路径哈希**。
  *
- * 两边算法分叉的后果很隐蔽：镜像会落在另一个目录名下，另一端拉下来后
- * 看起来像「这个项目的记忆凭空少了一批」。
+ * 2026-11-06 的第一版用的是 `cwd` 的 djb2 哈希（与引擎本地文件名同口径）。那个身份
+ * 只在一台机器内成立：换台机器换个盘符，同一个项目就成了另一个项目，记忆会静默分裂
+ * 成互不相认的两份。2026-11-11 改成项目名，依据是用户的三条约束——「以项目名为准」
+ * 「不会出现同名不同项目」「工作机上的目录不一样」。
+ *
+ * 统一小写：Windows 路径大小写不敏感、WSL/Linux 敏感，同一个项目在两处拼写可能不同；
+ * 不规范化就会变成 `records/project/WorkStation` 与 `records/project/workstation`
+ * 两个目录，又一次静默分裂。
  */
-export declare function workspaceSlug(cwd: string): string;
+export declare function projectName(cwd: string): string;
 /**
  * 把记忆库展开成镜像文件列表。**纯函数**：不读写磁盘、不看环境变量。
  *

package/dist/sync-export.js

@@ -74,19 +74,28 @@ function blocksOf(document) {
     return out;
 }
 /**
- * 工作区目录名——必须与引擎写记忆文件名时用的口径一致（`engine.ts` 的
- * `projectBackendName`：cwd 小写后过 djb2，取 base36）。
+ * 项目在同步面上的目录名——**项目目录名，不是路径哈希**。
  *
- * 两边算法分叉的后果很隐蔽：镜像会落在另一个目录名下，另一端拉下来后
- * 看起来像「这个项目的记忆凭空少了一批」。
+ * 2026-11-06 的第一版用的是 `cwd` 的 djb2 哈希（与引擎本地文件名同口径）。那个身份
+ * 只在一台机器内成立：换台机器换个盘符，同一个项目就成了另一个项目，记忆会静默分裂
+ * 成互不相认的两份。2026-11-11 改成项目名，依据是用户的三条约束——「以项目名为准」
+ * 「不会出现同名不同项目」「工作机上的目录不一样」。
+ *
+ * 统一小写：Windows 路径大小写不敏感、WSL/Linux 敏感，同一个项目在两处拼写可能不同；
+ * 不规范化就会变成 `records/project/WorkStation` 与 `records/project/workstation`
+ * 两个目录，又一次静默分裂。
  */
-export function workspaceSlug(cwd) {
-    let hash = 5381;
-    const text = cwd.toLowerCase();
-    for (let index = 0; index < text.length; index += 1) {
-        hash = ((hash << 5) + hash + text.charCodeAt(index)) | 0;
-    }
-    return Math.abs(hash).toString(36);
+export function projectName(cwd) {
+    // **不能用 `node:path` 的 basename**：它按平台分隔符切分，同一个字符串在 Windows 上
+    // 得到 `demo`、在 Linux 上得到整串 `H:\proj\demo`。2026-11-11 的 CI 就是这么红的
+    // （本地 Windows 全绿，Linux runner 上 `records/project/h:\proj\demo/`）。
+    // 两种分隔符都认，结果才跨平台一致——这也正是这个函数存在的意义。
+    const segments = cwd.replace(/\\/gu, '/').split('/').filter(segment => segment !== '');
+    const base = segments[segments.length - 1] ?? '';
+    // 盘符根（`H:\`）与路径根（`/`）都退到 `root`，不产生空目录名。
+    if (base === '' || /^[a-z]:$/iu.test(base))
+        return 'root';
+    return base.toLowerCase();
 }
 /** 只保留白名单字段；值为 `undefined` 的键不落进文件（避免 `"x": null` 噪声）。 */
 function pickSyncedFields(block) {
@@ -129,7 +138,7 @@ export function exportRecords(options) {
     const projects = [...(options.projectDocuments ?? [])].sort((left, right) => left.cwd.localeCompare(right.cwd));
     for (const { cwd, document } of projects) {
         for (const [id, block] of Object.entries(blocksOf(document))) {
-            const file = recordFile(id, block, [RECORDS_DIR, 'project', workspaceSlug(cwd)]);
+            const file = recordFile(id, block, [RECORDS_DIR, 'project', projectName(cwd)]);
             if (file === undefined) {
                 skippedQuarantined += 1;
                 continue;

package/dist/sync-git.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 同步镜像的本地 git 仓库层。
+ *
+ * **这一步不联网**：只做 `init` / `add` / `commit`。远端 push 是下一步，单独一层——
+ * 分层的理由是可验证性：本地仓库能在完全离线的情况下验通「记忆库 → 镜像 → 有历史的
+ * 仓库」整条链，网络问题留到那一层单独排查。
+ *
+ * `isomorphic-git` 走**动态 import**（体积理由见设计 §五）：没开同步的人不加载它。
+ *
+ * **无改动不产生空提交**：定时跑一次同步是常态，每次都留一个空提交会让 `git log`
+ * 变成时间戳噪声，真正的变更被淹掉。
+ *
+ * @module dsh-memory/sync-git
+ */
+/** {@link commitMirror} 的入参。 */
+export interface MirrorCommitOptions {
+    /** 镜像仓库目录。 */
+    readonly dir: string;
+    /** 提交信息。 */
+    readonly message: string;
+    /** 作者；isomorphic-git 没有可读的全局 git 配置，必须显式传。 */
+    readonly author: {
+        readonly name: string;
+        readonly email: string;
+    };
+}
+/** 一次提交的结果。 */
+export interface MirrorCommitRun {
+    /** 是否真的产生了提交（无改动时为 `false`）。 */
+    readonly committed: boolean;
+    /** 新提交的 sha；没有提交时缺省。 */
+    readonly sha?: string;
+    /** 本次涉及的路径数（新增 + 修改 + 删除）。 */
+    readonly filesChanged: number;
+}
+/**
+ * 把镜像目录的当前状态提交成一个 commit。
+ *
+ * 三种路径逐个处理：新增/修改走 `add`，**删除走 `remove`**——只 `add` 的话，
+ * 镜像里被删掉的记录在 git 看来会一直存在。
+ *
+ * @param options - 目录、提交信息与作者。
+ * @returns 是否提交、sha 与涉及的路径数。
+ */
+export declare function commitMirror(options: MirrorCommitOptions): Promise<MirrorCommitRun>;
+/**
+ * 读仓库的提交历史（从新到旧）。测试与 `memory_sync status` 共用。
+ *
+ * @param dir - 镜像仓库目录。
+ * @param depth - 最多取多少条；缺省不限。
+ * @returns 提交列表（sha / message / 时间）。仓库尚未建立时返回空数组。
+ */
+export declare function readHistory(dir: string, depth?: number): Promise<Array<{
+    sha: string;
+    message: string;
+    at: number;
+}>>;