@max-null/dsh-memory 0.19.1 → 0.21.0

package/README.md

@@ -76,6 +76,18 @@ npm install @max-null/dsh-memory
 
 两个根都可用 config 覆盖（`globalRoot` / `projectRoot`）。`memory_list` / `memory_search` 不带 `namespace` 过滤时会同时查两层。旧版双重前缀文件名（`memory_project_memory_project_<hash>.json`）在打开时自动迁移为规范名。
 
+## 主题（topic，0.20.0）
+
+`namespace` 管「在哪生效」，`topic` 管「这条讲什么」，两者正交：
+
+| 字段 | 回答的问题 | 取值 |
+|---|---|---|
+| `namespace` | 换个项目还成立吗 | `global` / `project` |
+| `kind` | 是记忆还是提示词模板 | `fact` / `prompt` |
+| `topic` | 这条记忆讲什么 | 自由字符串：`见闻` / `约定` / `坑` / `偏好` / `事实` / `判据` … |
+
+`memory_save` 传 `topic` 落库，`memory_list` / `memory_search` 传 `topic` 切片。留空或省略即「未分类」。用它把「自己出去逛到的」（`见闻`）和「一起干活时记下的」分开翻，不必再往正文里手写前缀。
+
 ## 跨工作区可见性（0.10.0 / 0.11.0）
 
 project 记忆按**会话工作区**分文件存放，所以「工作区」就是可见性的边界。0.10.0 起补了三个方向——针对的是同一个盲区：**不知道存在**（检索是有意图的动作，搜不出自己不知道存在的东西）。
@@ -118,7 +130,7 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 
 | 项 | 默认值 |
 |---|---|
-| 备份内容 | `memory.json`（global）+ `memory_project_*.json`（project）+ `<DSH_HOME>/diary/*.md` |
+| 备份内容 | `memory.json`（global）+ 每个打开过的工作区各一份 `memory_project_*.json` + `<DSH_HOME>/diary/*.md` |
 | 目标目录 | 记忆：`~/.dsh-backups/memory/<时间戳>/`（**在 `DSH_HOME` 之外**）；日记：`~/.dsh-backups/memory/diary-archive/` |
 | 间隔 | 60 分钟（首次延迟 1 分钟）；**插件关闭时另补一次** |
 | 保留 | 记忆：最近 14 份；日记：全部（只增不删） |
@@ -126,7 +138,7 @@ DSH 存储层的写入是「读—改—写全量覆盖」，且官方两个后
 
 **边界**：
 
-- 只备份**当前工作区**的 project 文件（`<cwd>/.dsh/storages/`）；其它工作区的 project 记忆不在备份范围。
+- 备份**本轮运行打开过的所有工作区**的 project 文件：来源是引擎按会话 cwd 记下的那份工作区账，每轮备份时现取。**本轮一次都没打开过的工作区不在范围内**——备份是定时任务，没有「当前工作区」可问，打开过的才留得下痕迹。多个工作区给出同名文件时加递增后缀，绝不覆盖。
 - 只读文件、只复制——**绝不复用引擎的写入路径**。写路径会先 `reload()` 再合并，磁盘缺失时它会把内存覆盖掉，正是这次事故的成因；备份不能走同一条路。
 - 日记按**逐字节内容**判断是否已备份过，不按 mtime：复制与编辑都会动 mtime，内容才是事实。
 

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

@@ -81,6 +81,13 @@ export interface MemoryRecord {
     lastUsedAt?: number;
     /** 记录类别（缺省 'fact'）。 */
     kind?: MemoryKind;
+    /**
+     * 记忆主题（0.20.0）：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …
+     *
+     * 与 `kind` 正交：`kind` 分「记忆还是提示词模板」，`topic` 分「这条记忆讲什么」。
+     * 存自由字符串，方便「只翻我出去逛到的那些」这类切片。
+     */
+    topic?: string;
     /** prompt 记录元数据（仅 kind==='prompt'）。 */
     meta?: PromptMetaIndex;
     /**
@@ -93,6 +100,8 @@ export interface MemoryWrite {
     content: string;
     namespace?: MemoryNamespace;
     keywords?: string[];
+    /** 记忆主题（0.20.0）：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …；省略表示未分类。 */
+    topic?: string;
     /** 写入来源（2026-09-15）；缺省 'agent'（主模型写入）。面板等人工路径传 'human'。 */
     source?: MemorySource;
     /**
@@ -115,6 +124,8 @@ export interface MemoryFilter {
     quarantined?: boolean;
     /** 记录类别过滤（0.6.0）；缺省不过滤（工具层显式传 kind='fact' 保持旧行为）。 */
     kind?: MemoryKind;
+    /** 主题过滤（0.20.0）：只取这个 topic 的记录；缺省不过滤。 */
+    topic?: string;
     /**
      * 更新时间下界 / 上界（0.12.0；epoch ms，含端点）。
      *
@@ -349,6 +360,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，之后的显式调用与它合流而非重复扫描。 */
@@ -383,6 +402,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 分享）。 */
@@ -394,6 +422,19 @@ 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 取 project 表（懒打开 + 缓存）。无 cwd（未选工作区）
      * 返回 undefined——调用方（工具/面板）按此跳过 project 部分。

package/dist/engine.js

@@ -145,10 +145,11 @@ function toRecord(id, block) {
         ...block.stale === undefined ? {} : { stale: block.stale },
         ...block.staleReason === undefined ? {} : { staleReason: block.staleReason },
     };
-    // 0.6.0 模板库字段（缺省 fact；prompt 元数据透传）
+    // 0.6.0 模板库字段（缺省 fact；prompt 元数据透传）；0.20.0 起带主题
     return {
         ...base,
         ...block.kind === undefined ? {} : { kind: block.kind },
+        ...block.topic === undefined ? {} : { topic: block.topic },
         ...block.meta === undefined ? {} : { meta: block.meta },
     };
 }
@@ -173,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，之后的显式调用与它合流而非重复扫描。 */
@@ -212,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: {} });
@@ -251,6 +298,21 @@ 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 取 project 表（懒打开 + 缓存）。无 cwd（未选工作区）
      * 返回 undefined——调用方（工具/面板）按此跳过 project 部分。
@@ -322,7 +384,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: {} });
@@ -758,6 +823,8 @@ export class MemoryEngine extends Service {
             ...input.injected === undefined ? {} : { injectedAuto: false },
             // 有效性锚点（可选）：值变了这条记忆会被标 stale，不再被当成仍然正确
             ...input.anchor === undefined ? {} : { anchor: input.anchor },
+            // 主题（0.20.0）：省略即未分类，与 `kind`（fact/prompt）正交
+            ...input.topic === undefined || input.topic.trim() === '' ? {} : { topic: input.topic.trim() },
             ...verdict.quarantined
                 ? { quarantined: true, ...verdict.reason === undefined ? {} : { quarantineReason: verdict.reason } }
                 : {},
@@ -778,7 +845,8 @@ export class MemoryEngine extends Service {
             // 0.12.0：按更新时间筛——与注入排序、注入行的日期标记同一个依据，不制造第二个「新」的定义
             && (filter?.after === undefined || record.updatedAt >= filter.after)
             && (filter?.before === undefined || record.updatedAt <= filter.before)
-            && (filter?.kind === undefined || (record.kind ?? 'fact') === filter.kind));
+            && (filter?.kind === undefined || (record.kind ?? 'fact') === filter.kind)
+            && (filter?.topic === undefined || record.topic === filter.topic));
     }
     /**
      * 关键词检索。每次成功返回的检索都记一条查询日志（⑥ 2026-09-15）——命中与否都记：

package/dist/index.js

@@ -125,6 +125,7 @@ const RECORD_SCHEMA = {
         injected: { type: 'boolean', required: true },
         content: { type: 'string', required: true },
         keywords: { type: 'array', required: true, items: { type: 'string' } },
+        topic: { type: 'string', description: '主题（0.20.0）：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …；缺省表示未分类。' },
         createdAt: { type: 'number', required: true },
         updatedAt: { type: 'number', required: true },
         lastUsedAt: { type: 'number' },
@@ -296,6 +297,7 @@ function recordValue(record) {
         injected: record.injected,
         content: record.content,
         keywords: record.keywords,
+        ...record.topic === undefined ? {} : { topic: record.topic },
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
         ...record.lastUsedAt === undefined ? {} : { lastUsedAt: record.lastUsedAt },
@@ -587,6 +589,7 @@ export async function apply(ctx, config) {
             content: { type: 'string', required: true, description: 'Plaintext memory content.' },
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Where it applies; defaults to global.' },
             keywords: { type: 'array', items: { type: 'string' }, description: 'Explicit searchable anchors for memory_search. Give several angles (synonyms, abbreviations, zh/en) or it will not be found later. 多角度关键词（同义词、缩写、中英），否则将来检索不到它。' },
+            topic: { type: 'string', description: 'What this memory is about, one short word: 见闻 (things noticed while wandering) / 约定 (standing agreement) / 坑 (a pitfall hit) / 偏好 (a preference) / 事实 / 判据. Orthogonal to namespace. 主题：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据；与 namespace 正交，缺省表示未分类。' },
             injected: { type: 'boolean', description: 'Set true to make this memory resident in every turn\'s context, as a deliberate decision that no longer auto-expires. Reserve it for rules, standing agreements and judgement criteria — the kind that must apply even when nobody thinks to search for them. Facts, references and case notes stay search-only (omit it). 设为 true 让这条记忆每轮常驻上下文，且视为有意决定、不再被自动淘汰。只用于规则、长期约定与判据——那些「没人想起来搜也必须生效」的记忆；事实、参考与案例留作按需检索（省略即可）。' },
             anchor: {
                 type: 'object',
@@ -609,6 +612,7 @@ export async function apply(ctx, config) {
                 content: args.content,
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.keywords === undefined ? {} : { keywords: args.keywords },
+                ...args.topic === undefined ? {} : { topic: args.topic },
                 ...args.injected === undefined ? {} : { injected: args.injected },
                 // 参数已由 tool schema 校验，这里的窄化只为过类型
                 ...args.anchor === undefined
@@ -632,6 +636,7 @@ export async function apply(ctx, config) {
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
             status: { type: 'string', enum: ['suggested', 'approved'], description: 'Restrict to one review status. 限定审核状态（suggested=待审核 / approved=已审核）.' },
             injected: { type: 'boolean', description: 'Restrict by the persistent-injection switch. 按常驻注入开关过滤.' },
+            topic: { type: 'string', description: 'Restrict to one topic (见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …). 按主题过滤（0.20.0）.' },
             after: { type: 'string', description: 'Only memories updated at/after this time: `YYYY-MM-DD`, or a relative form like `7d` / `30d`. 只返回此后更新过的记忆（`YYYY-MM-DD`，或相对形式 `7d` / `30d`）.' },
             before: { type: 'string', description: 'Only memories updated at/before this time (same forms as `after`). 只返回此前更新过的记忆（写法同 after）.' },
         },
@@ -647,6 +652,7 @@ export async function apply(ctx, config) {
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.status === undefined ? {} : { status: args.status },
                 ...args.injected === undefined ? {} : { injected: args.injected },
+                ...args.topic === undefined ? {} : { topic: args.topic },
                 ...after === undefined ? {} : { after },
                 ...before === undefined ? {} : { before },
             }, execProjectCwd(exec)).then(records => records.map(recordValue));
@@ -661,6 +667,7 @@ export async function apply(ctx, config) {
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
             status: { type: 'string', enum: ['suggested', 'approved'], description: 'Restrict to one review status. 限定审核状态.' },
             kind: { type: 'string', enum: ['fact', 'prompt'], description: 'Restrict by record kind — fact (memories, default) or prompt (templates; use prompt_search instead). 按记录类别过滤：fact=记忆（默认）/ prompt=模板（模板请用 prompt_search）.' },
+            topic: { type: 'string', description: 'Restrict to one topic (见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 …). 按主题过滤（0.20.0）.' },
             limit: { type: 'integer', default: DEFAULT_SEARCH_LIMIT, description: 'Maximum hits to return (default 20; 0 = no limit; negative falls back to 20). 最多返回条数（默认 20；0 = 不限；负数按 20）.' },
         },
         output: {
@@ -676,6 +683,7 @@ export async function apply(ctx, config) {
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.status === undefined ? {} : { status: args.status },
                 ...args.kind === undefined ? {} : { kind: args.kind },
+                ...args.topic === undefined ? {} : { topic: args.topic },
             }, execProjectCwd(exec)).then(hits => (limit === 0 ? hits : hits.slice(0, limit)).map(hitValue));
         },
         presentCall: args => present('Search memory', 'read', args.query),
@@ -989,25 +997,47 @@ export async function apply(ctx, config) {
         const targetRoot = backup?.targetRoot ?? join(homedir(), '.dsh-backups', 'memory');
         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();
             };
         });
     }

package/dist/schema.d.ts

@@ -63,6 +63,7 @@ export declare const blockSchema: z.ZodObject<{
         fact: "fact";
         prompt: "prompt";
     }>>;
+    topic: z.ZodOptional<z.ZodString>;
     meta: z.ZodOptional<z.ZodObject<{
         seq: z.ZodOptional<z.ZodNumber>;
         name: z.ZodString;

package/dist/schema.js

@@ -45,6 +45,14 @@ export const blockSchema = z.object({
     lastUsedAt: z.number().optional(),
     vector: z.array(z.number()).optional(),
     kind: z.enum(['fact', 'prompt']).optional(),
+    /**
+     * 记忆主题（0.20.0）：见闻 / 约定 / 坑 / 偏好 / 事实 / 判据 … 自由字符串。
+     *
+     * 与 `kind` 正交——`kind` 分「记忆还是提示词模板」（记录类别），`topic` 分「这条记忆讲什么」
+     * （内容主题）。用自由字符串而不是枚举：新增主题不该要求改 schema，而枚举一旦写死，
+     * 存量文件里出现未登记的值会被门三判成不合规、进而整块读不出来。
+     */
+    topic: z.string().optional(),
     meta: z.object({
         seq: z.number().optional(),
         name: z.string(),

package/dist/sync-export.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 同步导出层：把记忆库展开成「一条记忆一个文件」的镜像。
+ *
+ * **为什么需要它**：整份 `memory.json` 放进 git 会撞。2026-11-06 实测：两端各新增一条
+ * 记忆后 merge，`git` 报 `CONFLICT (content)`——两条记录挤在同一个插入点，按「取一边」
+ * 解决会静默丢掉另一端那条，而 git 仍报「合并成功」。改成一条一个文件后同一场景是
+ * `Merge made by the 'ort' strategy`，0 冲突。
+ *
+ * **为什么单独成模块**（与 `schema.ts` 同理由）：本模块只依赖 `node:path`，不 import
+ * cordis / dsh-storage / engine。这样单元测试与离线 CLI 能直接加载它，不必拉起整套
+ * 宿主依赖——否则「用插件自己的能力导出一份镜像」这条在用户环境里跑不起来。
+ *
+ * **同步面不带什么**（见设计文档 §5）：
+ * - `hitCount` / `lastUsedAt`：本地行为统计，每次检索命中都会改。带上它们会让镜像在内容
+ *   毫无变化时持续变脏，git 历史被噪声淹没。
+ * - `vector`：本地嵌入产物，体积大且可从 `content` 重算。
+ * - `quarantined` 的记录**整条不导出**：隔离区的存在理由就是它可能含凭据类内容，
+ *   推到远端仓库等于把那层保护绕开。
+ *
+ * @see docs/设计/2026-11-06-记忆云同步-设计方案.md
+ */
+/** 一条记录在镜像里的位置与内容。 */
+export interface SyncRecordFile {
+    /** 相对导出根的路径，如 `records/global/<uuid>.json`。 */
+    readonly path: string;
+    /** 文件内容（JSON + 末尾换行；已剔除同步面之外的字段）。 */
+    readonly content: string;
+}
+/** 导出的输入：各层记忆库的**解析后**文档。 */
+export interface SyncExportOptions {
+    /** `memory.json` 解析后的对象（global 层）。 */
+    readonly globalDocument: unknown;
+    /** 各工作区的记忆库文档；`cwd` 用于算目录名，须与引擎写入时一致。 */
+    readonly projectDocuments?: ReadonlyArray<{
+        readonly cwd: string;
+        readonly document: unknown;
+    }>;
+}
+/** 一次导出的结果。 */
+export interface SyncExportRun {
+    /** 待写入的记录文件（顺序稳定：global 在前，工作区按 cwd 排序）。 */
+    readonly files: readonly SyncRecordFile[];
+    /** 因处于隔离区而未导出的条数。 */
+    readonly skippedQuarantined: number;
+}
+/**
+ * 工作区目录名——必须与引擎写记忆文件名时用的口径一致（`engine.ts` 的
+ * `projectBackendName`：cwd 小写后过 djb2，取 base36）。
+ *
+ * 两边算法分叉的后果很隐蔽：镜像会落在另一个目录名下，另一端拉下来后
+ * 看起来像「这个项目的记忆凭空少了一批」。
+ */
+export declare function workspaceSlug(cwd: string): string;
+/**
+ * 把记忆库展开成镜像文件列表。**纯函数**：不读写磁盘、不看环境变量。
+ *
+ * @param options - 各层文档。
+ * @returns 待写入的文件与隔离跳过数。
+ */
+export declare function exportRecords(options: SyncExportOptions): SyncExportRun;

package/dist/sync-export.js

@@ -0,0 +1,141 @@
+/**
+ * 同步导出层：把记忆库展开成「一条记忆一个文件」的镜像。
+ *
+ * **为什么需要它**：整份 `memory.json` 放进 git 会撞。2026-11-06 实测：两端各新增一条
+ * 记忆后 merge，`git` 报 `CONFLICT (content)`——两条记录挤在同一个插入点，按「取一边」
+ * 解决会静默丢掉另一端那条，而 git 仍报「合并成功」。改成一条一个文件后同一场景是
+ * `Merge made by the 'ort' strategy`，0 冲突。
+ *
+ * **为什么单独成模块**（与 `schema.ts` 同理由）：本模块只依赖 `node:path`，不 import
+ * cordis / dsh-storage / engine。这样单元测试与离线 CLI 能直接加载它，不必拉起整套
+ * 宿主依赖——否则「用插件自己的能力导出一份镜像」这条在用户环境里跑不起来。
+ *
+ * **同步面不带什么**（见设计文档 §5）：
+ * - `hitCount` / `lastUsedAt`：本地行为统计，每次检索命中都会改。带上它们会让镜像在内容
+ *   毫无变化时持续变脏，git 历史被噪声淹没。
+ * - `vector`：本地嵌入产物，体积大且可从 `content` 重算。
+ * - `quarantined` 的记录**整条不导出**：隔离区的存在理由就是它可能含凭据类内容，
+ *   推到远端仓库等于把那层保护绕开。
+ *
+ * @see docs/设计/2026-11-06-记忆云同步-设计方案.md
+ */
+import { join } from 'node:path';
+/**
+ * 进入同步面的字段白名单。
+ *
+ * 用白名单而不是黑名单：`StoredBlock` 以后还会长出新字段（`topic` 就是 0.20.0 才加的），
+ * 黑名单会让新字段**默认泄漏**进来——而「一个只该存在本地的字段漏进远端仓库」这类事故，
+ * 发现的时候内容已经在别人能拉到的地方了。
+ */
+const SYNCED_FIELDS = [
+    'namespace',
+    'status',
+    'content',
+    'keywords',
+    'createdAt',
+    'updatedAt',
+    'injected',
+    'injectedAuto',
+    'topic',
+    'kind',
+    'anchor',
+    'stale',
+    'staleReason',
+    'source',
+    'meta',
+];
+/** 记录文件的目录名（与清单文件同级）。 */
+const RECORDS_DIR = 'records';
+/** 把 `unknown` 收窄成对象；不是对象返回 `undefined`。 */
+function asObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * 取出一份 unit 文档里的 blocks 表。
+ *
+ * 文档形状是 DSH storage 的 unit 格式：`{ unit, global, tables: { blocks: {...} } }`。
+ * 形状不符时返回空表而不是抛错——镜像导出不该因为一个损坏的库把整个同步卡死，
+ * 条数为 0 会被上层当作「没有可导出的东西」处理。
+ */
+function blocksOf(document) {
+    const doc = asObject(document);
+    const tables = asObject(doc?.tables);
+    const blocks = asObject(tables?.blocks);
+    if (blocks === undefined)
+        return {};
+    const out = {};
+    for (const [id, block] of Object.entries(blocks)) {
+        const value = asObject(block);
+        if (value !== undefined)
+            out[id] = value;
+    }
+    return out;
+}
+/**
+ * 工作区目录名——必须与引擎写记忆文件名时用的口径一致（`engine.ts` 的
+ * `projectBackendName`：cwd 小写后过 djb2，取 base36）。
+ *
+ * 两边算法分叉的后果很隐蔽：镜像会落在另一个目录名下，另一端拉下来后
+ * 看起来像「这个项目的记忆凭空少了一批」。
+ */
+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);
+}
+/** 只保留白名单字段；值为 `undefined` 的键不落进文件（避免 `"x": null` 噪声）。 */
+function pickSyncedFields(block) {
+    const out = {};
+    for (const field of SYNCED_FIELDS) {
+        const value = block[field];
+        if (value !== undefined)
+            out[field] = value;
+    }
+    return out;
+}
+/** 一条记录 → 一个文件；返回 `undefined` 表示这条不该进镜像（隔离区）。 */
+function recordFile(id, block, segments) {
+    if (block.quarantined === true)
+        return undefined;
+    const payload = pickSyncedFields(block);
+    return {
+        path: join(...segments, `${id}.json`),
+        content: `${JSON.stringify(payload, null, 2)}\n`,
+    };
+}
+/**
+ * 把记忆库展开成镜像文件列表。**纯函数**：不读写磁盘、不看环境变量。
+ *
+ * @param options - 各层文档。
+ * @returns 待写入的文件与隔离跳过数。
+ */
+export function exportRecords(options) {
+    const files = [];
+    let skippedQuarantined = 0;
+    for (const [id, block] of Object.entries(blocksOf(options.globalDocument))) {
+        const file = recordFile(id, block, [RECORDS_DIR, 'global']);
+        if (file === undefined) {
+            skippedQuarantined += 1;
+            continue;
+        }
+        files.push(file);
+    }
+    // 工作区按 cwd 排序：让两次导出的文件顺序稳定，git 不必为顺序抖动产生 diff。
+    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)]);
+            if (file === undefined) {
+                skippedQuarantined += 1;
+                continue;
+            }
+            files.push(file);
+        }
+    }
+    return { files, skippedQuarantined };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, writes take effect immediately, signal-driven injection, no embeddings",
   "license": "MIT",
   "publishConfig": {