@max-null/dsh-memory 0.21.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/`，**只增不删**，不参与上面的轮转。两边的不对称是实的：记忆快照丢一份还有别的份（同一份数据的多个时间点副本），归档里每一篇都是日记的唯一副本，丢了没有任何地方能重建。日记那一侧改过就以日记为准覆盖（人可能在事后改过错字），归档里有而日记里已没有的篇目一律保留——那正是归档的全部价值。归档目录名不匹配轮转正则，因此不需要给清理逻辑开白名单。
 
@@ -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,50 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 - 只读文件、只复制——**绝不复用引擎的写入路径**。写路径会先 `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/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,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,11 +1012,81 @@ 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 globalRoot = config?.globalRoot ?? join(process.env.DSH_HOME ?? join(homedir(), '.dsh'), 'storages');

package/dist/self.js

@@ -25,7 +25,8 @@ export const SELF_VERSION = (() => {
     }
 })();
 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 文件、**永不注入**，走这条通道，不会混进记忆检索）；'
+    + '你有 16 个工具：**记忆工具** 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 文件、**永不注入**，走这条通道，不会混进记忆检索）；'
+    + '**同步工具** 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 提交分享）。'
     + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'

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;
+}>>;

package/dist/sync-git.js

@@ -0,0 +1,88 @@
+/**
+ * 同步镜像的本地 git 仓库层。
+ *
+ * **这一步不联网**：只做 `init` / `add` / `commit`。远端 push 是下一步，单独一层——
+ * 分层的理由是可验证性：本地仓库能在完全离线的情况下验通「记忆库 → 镜像 → 有历史的
+ * 仓库」整条链，网络问题留到那一层单独排查。
+ *
+ * `isomorphic-git` 走**动态 import**（体积理由见设计 §五）：没开同步的人不加载它。
+ *
+ * **无改动不产生空提交**：定时跑一次同步是常态，每次都留一个空提交会让 `git log`
+ * 变成时间戳噪声，真正的变更被淹掉。
+ *
+ * @module dsh-memory/sync-git
+ */
+import { existsSync, mkdirSync } from 'node:fs';
+import * as nodeFs from 'node:fs';
+import { join } from 'node:path';
+/** 仓库默认分支——与 GitHub 侧的约定一致。 */
+const DEFAULT_BRANCH = 'main';
+/** 动态载入 isomorphic-git（体积理由见文件头）。 */
+async function loadGit() {
+    return await import('isomorphic-git');
+}
+/** 确保目录是一个 git 仓库；已初始化时什么都不做。 */
+async function ensureRepo(dir) {
+    mkdirSync(dir, { recursive: true });
+    if (existsSync(join(dir, '.git')))
+        return;
+    const git = await loadGit();
+    await git.init({ fs: nodeFs, dir, defaultBranch: DEFAULT_BRANCH });
+}
+/**
+ * 把镜像目录的当前状态提交成一个 commit。
+ *
+ * 三种路径逐个处理：新增/修改走 `add`，**删除走 `remove`**——只 `add` 的话，
+ * 镜像里被删掉的记录在 git 看来会一直存在。
+ *
+ * @param options - 目录、提交信息与作者。
+ * @returns 是否提交、sha 与涉及的路径数。
+ */
+export async function commitMirror(options) {
+    await ensureRepo(options.dir);
+    const git = await loadGit();
+    // statusMatrix 每行是 [filepath, head, workdir, stage]：
+    // head=1 表示上一个 commit 里有；workdir=0 表示工作区里已经没有。
+    const matrix = await git.statusMatrix({ fs: nodeFs, dir: options.dir });
+    const changed = matrix.filter(([, head, workdir, stage]) => head !== workdir || workdir !== stage);
+    if (changed.length === 0) {
+        return { committed: false, filesChanged: 0 };
+    }
+    for (const [filepath, , workdir] of changed) {
+        if (workdir === 0)
+            await git.remove({ fs: nodeFs, dir: options.dir, filepath });
+        else
+            await git.add({ fs: nodeFs, dir: options.dir, filepath });
+    }
+    const sha = await git.commit({
+        fs: nodeFs,
+        dir: options.dir,
+        message: options.message,
+        author: options.author,
+    });
+    return { committed: true, sha, filesChanged: changed.length };
+}
+/**
+ * 读仓库的提交历史（从新到旧）。测试与 `memory_sync status` 共用。
+ *
+ * @param dir - 镜像仓库目录。
+ * @param depth - 最多取多少条；缺省不限。
+ * @returns 提交列表（sha / message / 时间）。仓库尚未建立时返回空数组。
+ */
+export async function readHistory(dir, depth) {
+    if (!existsSync(join(dir, '.git')))
+        return [];
+    const git = await loadGit();
+    try {
+        const commits = await git.log({ fs: nodeFs, dir, ...depth === undefined ? {} : { depth } });
+        return commits.map(entry => ({
+            sha: entry.oid,
+            message: entry.commit.message.trim(),
+            at: entry.commit.author.timestamp * 1000,
+        }));
+    }
+    catch {
+        // 空仓库（init 之后一个 commit 都没有）会在这里抛；那是正常状态。
+        return [];
+    }
+}