@max-null/dsh-memory 0.9.1 → 0.10.0

package/README.md

@@ -41,7 +41,7 @@ npm install @max-null/dsh-memory
 
 - **服务** `ctx.memory`：`remember` / `list` / `search` / `forget` / `setStatus`
 - **工具**：`memory_save`、`memory_list`、`memory_search`、`memory_confirm`、`memory_forget`、`memory_update`
-- **注入**：`tool:memory` 指引 section + `memory:recall` 召回 context（global 的 `approved + injected` + 当前会话工作区的 `approved + injected`，带 `[memory:<id>:<namespace>]` 来源标记；摘要化 + 预算截断）
+- **注入**：`tool:memory` 指引 section（工具用法 + 常驻注入判据）+ `memory:self` 机制自述 + `memory:recall` 召回 context（global 的 `approved + injected` + 当前会话工作区的 `approved + injected`，带 `[memory:<id>:<namespace>]` 来源标记；摘要化 + 预算截断）
 - **检索**：BM25（CJK 单字 + 2-gram，content 与 keywords 字段分离加权；中文多字查询精度显著优于单字切分）；可选语义融合（见「可选配置」）
 
 ## 两层存储（global / project）
@@ -55,6 +55,22 @@ npm install @max-null/dsh-memory
 
 两个根都可用 config 覆盖（`globalRoot` / `projectRoot`）。`memory_list` / `memory_search` 不带 `namespace` 过滤时会同时查两层。旧版双重前缀文件名（`memory_project_memory_project_<hash>.json`）在打开时自动迁移为规范名。
 
+## 跨工作区可见性（0.10.0）
+
+project 记忆按**会话工作区**分文件存放，所以「工作区」就是可见性的边界。0.10.0 起补了三个方向——针对的是同一个盲区：**不知道存在**（检索是有意图的动作，搜不出自己不知道存在的东西）。
+
+| 方向 | 机制 | 效果 |
+|---|---|---|
+| 向上 | **祖先链** | 在子目录里开会话能检索到父目录的记忆（反向不行，链是单向向上的），结果带 `..` / `../..` 来源标记 |
+| 向下 | **子项目索引行** | 注入里多一行「本工作区下另有 N 个子项目带记忆：xxx（M 条）——用 memory_search 检索」 |
+| 全局 | **记忆索引行** | 注入里多一行「索引：当前可见 N 条记忆，主题集中在 X(14)、Y(12)…——用 memory_search 检索」 |
+
+三条边界：**写入永远只落当前工作区**（「我在这个项目里记的东西」不该被推理到别处）；但**检索得到的记录就改得动**——`memory_update` / `memory_forget` 同样沿链定位；**注入路径只读当前工作区**（远处的记忆进检索、不进每轮成本）。
+
+后两行**不占注入预算**、自消除（没有内容时整行不出现），且**长度常数级**——不随记忆增长。索引行里的主题取自各条的关键词词频，与检索用的是同一套词汇，所以**索引里出现的词就是能搜到的词**。
+
+**孤儿文件清点**：`node scripts/scan-orphans.mjs [根目录]` 报出「哪些记忆文件当前代码已经打不开」（历史命名遗留：早期无哈希后缀、双重 `memory_project_` 前缀）。**只读，不做任何处置**——旧文件可能含未过隔离检查的内容，处置需人工拍板。
+
 ## 多实例共存（0.7.1）
 
 两个 DSH 实例（例如 DSH web 与 SSiD 桌面壳）可以同时运行、共用同一个 `DSH_HOME`，**记忆不再互相抹掉**。

package/dist/engine.d.ts

@@ -82,6 +82,11 @@ export interface MemoryRecord {
     kind?: MemoryKind;
     /** prompt 记录元数据（仅 kind==='prompt'）。 */
     meta?: PromptMetaIndex;
+    /**
+     * 来源工作区（④-A 2026-09-19）：仅在跨工作区召回时出现——`undefined` = 当前会话
+     * 工作区，`..` / `../..` = 上级工作区。检索结果与注入行据此标出来源，避免「记忆串味」。
+     */
+    scope?: string;
 }
 export interface MemoryWrite {
     content: string;
@@ -234,6 +239,10 @@ export declare class MemoryEngine extends Service {
     private globalTable?;
     /** project 域按工作区 cwd 懒打开 + 缓存（多会话并发各工作区独立）。 */
     private projectTables;
+    /** 子项目发现缓存（④-B 2026-09-19）：key = 工作区路径；值 = 其直接子目录中带记忆的（按条数降序）。 */
+    private readonly neighborCache;
+    /** 进行中的子项目发现（key → promise）：预热是 fire-and-forget，之后的显式调用与它合流而非重复扫描。 */
+    private readonly neighborOpenings;
     /** 进行中的工作区打开（key → promise）：并发调用复用同一次，见 {@link projectTableFor}。 */
     private readonly projectOpenings;
     private projectFacilities;
@@ -295,6 +304,66 @@ export declare class MemoryEngine extends Service {
     private globalStoreFile;
     /** 某工作区记忆的存储文件。 */
     private projectStoreFile;
+    /**
+     * 工作区链（④-A 2026-09-19）：当前 cwd 起向上，收集**记忆文件已存在**的层级。
+     *
+     * 两条约束：
+     * ① **自身始终纳入**（depth 0）——即使文件还不存在，也保持既有行为（`projectTableFor`
+     *    会创建它，会话预热路径同样如此）。
+     * ② **祖先只收文件已存在的**——对不存在的层级打开表会让 JsonStorageBackend **创建**空
+     *    文件，等于在用户每个祖先目录里留一个空记忆文件。
+     *
+     * `depth` 是真实的上级层数（每向上一步 +1，无论该级是否有文件），供来源标记渲染成
+     * `..` / `../..`。路径一律先 `join()` 规范化再算哈希——`projectBackendName` 对字符串
+     * 敏感，`H:\a\b` 与 `H:/a/b` 会得出**不同**的文件名（设计文档 §2.3）。
+     */
+    private projectChain;
+    /**
+     * 打开工作区链上的表（由近及远）。复用 {@link projectTableFor} 的缓存与并发去重——
+     * 链上每级各自一张表，重复调用不会重复打开。
+     */
+    private projectChainTables;
+    /** 来源标记：depth 0（当前工作区）不带标记；祖先渲染为 `..` / `../..`。 */
+    private static scopeLabel;
+    /**
+     * 子项目发现（④-B 2026-09-19）：扫描 cwd 的**直接子目录**（不递归——实测一层即覆盖全部
+     * 实际情况：19 个子目录里 3 个带记忆），找出带记忆文件、且其中有非隔离记录的。
+     *
+     * 结果缓存进 {@link neighborCache}——注入 provider 是同步的，只能读缓存；扫描本身在这个
+     * 异步方法里做，由 `ensureProjectOpen` 预热路径触发。
+     *
+     * 跳过点开头的目录（`.dsh` / `.git` 等不是子项目）；只报条数、不搬运内容——索引行的用途
+     * 是「告诉你去搜」，不是把子项目的记忆变成当前会话的持续成本。
+     */
+    discoverNeighbors(projectCwd: string): Promise<Array<{
+        name: string;
+        count: number;
+    }>>;
+    /** {@link discoverNeighbors} 的实际扫描；并发去重由调用方负责。 */
+    private scanNeighbors;
+    /**
+     * 同步读取已发现的子项目（④-B）：注入 provider 是同步回调，只能读缓存。
+     * 缓存由 {@link discoverNeighbors} 在预热路径填充；未跑过时返回空数组——该轮索引行
+     * 缺席、下一轮补上，与工作区表预热同一套取舍。
+     */
+    neighborsOf(projectCwd?: string): Array<{
+        name: string;
+        count: number;
+    }>;
+    /**
+     * 同步读取索引候选（① 2026-09-19）：global + 工作区链上**已打开**的表里的全部记录。
+     *
+     * 与 {@link recallRecords} 的分工：后者只取 `injected` 的（进注入行），前者取全部
+     * （供索引行统计规模与主题）。同样是同步只读已缓存的表——注入 provider 是同步回调，
+     * 未打开的层级本轮不计入，影响可忽略（链上祖先在检索路径打开后即缓存）。
+     */
+    indexCandidates(projectCwd?: string): MemoryRecord[];
+    /**
+     * 按 id 定位记录所在表：global 优先，其次工作区链（自身 → 祖先，由近及远）。
+     * **异步版**——写路径必须用它：`writeScope` 可能在本次进入前刚 `reload()`，
+     * 那时同步缓存已被清空（同 {@link markUsedInner} 的注释）。
+     */
+    private locateRecord;
     /** 记录当前指纹，作为「这就是我们造成的状态」的基准（写入完成后调用）。 */
     private noteStoreStamps;
     /**
@@ -344,6 +413,7 @@ export declare class MemoryEngine extends Service {
      * 「工具全没了」，让所有 `tool-list` 锚点误失效。
      */
     private anchorProbes;
+    /** 同步版定位：只查**已打开**的表（global + 链上已缓存的工作区表）。 */
     private tableOf;
     /** 命中标记：写回 lastUsedAt 与命中次数，达标即自动升常驻（2026-09-15）。 */
     private markUsed;

package/dist/engine.js

@@ -6,8 +6,9 @@
  */
 import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { readdir } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { Service } from '@deepseek-ai/cordis';
 import { z } from 'zod';
 import { defineDomain, domainTable, DomainFacility } from '@deepseek-ai/dsh-storage-domain';
@@ -166,6 +167,10 @@ export class MemoryEngine extends Service {
     globalTable;
     /** project 域按工作区 cwd 懒打开 + 缓存（多会话并发各工作区独立）。 */
     projectTables = new Map();
+    /** 子项目发现缓存（④-B 2026-09-19）：key = 工作区路径；值 = 其直接子目录中带记忆的（按条数降序）。 */
+    neighborCache = new Map();
+    /** 进行中的子项目发现（key → promise）：预热是 fire-and-forget，之后的显式调用与它合流而非重复扫描。 */
+    neighborOpenings = new Map();
     /** 进行中的工作区打开（key → promise）：并发调用复用同一次，见 {@link projectTableFor}。 */
     projectOpenings = new Map();
     projectFacilities = new Map();
@@ -311,6 +316,7 @@ export class MemoryEngine extends Service {
             await facility.closeAll();
         this.projectTables.clear();
         this.projectFacilities.clear();
+        this.neighborCache.clear(); // ④-B：子项目发现随存储一并作废（外部实例可能刚改过）
         await this.openGlobalFacility();
         for (const key of opened) {
             // 重开失败 = 该工作区退回「未打开」（本轮注入缺这部分，下次访问重试），
@@ -350,6 +356,158 @@ export class MemoryEngine extends Service {
         const key = join(projectCwd);
         return join(this.projectRootFor(key), `${this.projectBackendName(key)}.json`);
     }
+    /**
+     * 工作区链（④-A 2026-09-19）：当前 cwd 起向上，收集**记忆文件已存在**的层级。
+     *
+     * 两条约束：
+     * ① **自身始终纳入**（depth 0）——即使文件还不存在，也保持既有行为（`projectTableFor`
+     *    会创建它，会话预热路径同样如此）。
+     * ② **祖先只收文件已存在的**——对不存在的层级打开表会让 JsonStorageBackend **创建**空
+     *    文件，等于在用户每个祖先目录里留一个空记忆文件。
+     *
+     * `depth` 是真实的上级层数（每向上一步 +1，无论该级是否有文件），供来源标记渲染成
+     * `..` / `../..`。路径一律先 `join()` 规范化再算哈希——`projectBackendName` 对字符串
+     * 敏感，`H:\a\b` 与 `H:/a/b` 会得出**不同**的文件名（设计文档 §2.3）。
+     */
+    projectChain(cwd) {
+        const key = join(cwd);
+        const chain = [{ key, depth: 0 }];
+        let cur = key;
+        let depth = 0;
+        for (;;) {
+            const parent = dirname(cur);
+            if (parent === cur)
+                break; // 到盘根
+            cur = parent;
+            depth += 1;
+            if (existsSync(this.projectStoreFile(cur)))
+                chain.push({ key: cur, depth });
+        }
+        return chain;
+    }
+    /**
+     * 打开工作区链上的表（由近及远）。复用 {@link projectTableFor} 的缓存与并发去重——
+     * 链上每级各自一张表，重复调用不会重复打开。
+     */
+    async projectChainTables(cwd) {
+        if (cwd === undefined || cwd === '')
+            return [];
+        const out = [];
+        for (const { key, depth } of this.projectChain(cwd)) {
+            const table = await this.projectTableFor(key).catch(() => undefined);
+            if (table !== undefined)
+                out.push({ key, depth, table });
+        }
+        return out;
+    }
+    /** 来源标记：depth 0（当前工作区）不带标记；祖先渲染为 `..` / `../..`。 */
+    static scopeLabel(depth) {
+        if (depth === 0)
+            return undefined;
+        return Array.from({ length: depth }, () => '..').join('/');
+    }
+    /**
+     * 子项目发现（④-B 2026-09-19）：扫描 cwd 的**直接子目录**（不递归——实测一层即覆盖全部
+     * 实际情况：19 个子目录里 3 个带记忆），找出带记忆文件、且其中有非隔离记录的。
+     *
+     * 结果缓存进 {@link neighborCache}——注入 provider 是同步的，只能读缓存；扫描本身在这个
+     * 异步方法里做，由 `ensureProjectOpen` 预热路径触发。
+     *
+     * 跳过点开头的目录（`.dsh` / `.git` 等不是子项目）；只报条数、不搬运内容——索引行的用途
+     * 是「告诉你去搜」，不是把子项目的记忆变成当前会话的持续成本。
+     */
+    async discoverNeighbors(projectCwd) {
+        const key = join(projectCwd);
+        const cached = this.neighborCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        // 进行中那次复用：`ensureProjectOpen` 的预热是 fire-and-forget，紧随其后的显式调用
+        // （工具路径 / 测试 / 面板）若各扫一遍，既浪费也可能读到半成品。与 `projectTableFor`
+        // 同一套去重语义。
+        const inFlight = this.neighborOpenings.get(key);
+        if (inFlight !== undefined)
+            return await inFlight;
+        const scan = this.scanNeighbors(key);
+        this.neighborOpenings.set(key, scan);
+        try {
+            return await scan;
+        }
+        finally {
+            this.neighborOpenings.delete(key);
+        }
+    }
+    /** {@link discoverNeighbors} 的实际扫描；并发去重由调用方负责。 */
+    async scanNeighbors(key) {
+        const found = [];
+        let entries = [];
+        try {
+            entries = await readdir(key, { withFileTypes: true });
+        }
+        catch {
+            entries = []; // 目录读不到（不存在 / 无权限）：当作没有子项目，不报错
+        }
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const sub = join(key, entry.name);
+            if (!existsSync(this.projectStoreFile(sub)))
+                continue;
+            const table = await this.projectTableFor(sub).catch(() => undefined);
+            if (table === undefined)
+                continue;
+            const count = this.recordsOf(table).filter(record => record.quarantined !== true).length;
+            if (count > 0)
+                found.push({ name: entry.name, count });
+        }
+        found.sort((left, right) => right.count - left.count);
+        this.neighborCache.set(key, found);
+        return found;
+    }
+    /**
+     * 同步读取已发现的子项目（④-B）：注入 provider 是同步回调，只能读缓存。
+     * 缓存由 {@link discoverNeighbors} 在预热路径填充；未跑过时返回空数组——该轮索引行
+     * 缺席、下一轮补上，与工作区表预热同一套取舍。
+     */
+    neighborsOf(projectCwd) {
+        if (projectCwd === undefined || projectCwd === '')
+            return [];
+        return this.neighborCache.get(join(projectCwd)) ?? [];
+    }
+    /**
+     * 同步读取索引候选（① 2026-09-19）：global + 工作区链上**已打开**的表里的全部记录。
+     *
+     * 与 {@link recallRecords} 的分工：后者只取 `injected` 的（进注入行），前者取全部
+     * （供索引行统计规模与主题）。同样是同步只读已缓存的表——注入 provider 是同步回调，
+     * 未打开的层级本轮不计入，影响可忽略（链上祖先在检索路径打开后即缓存）。
+     */
+    indexCandidates(projectCwd) {
+        const candidates = this.recordsOf(this.requireTable('global'));
+        if (projectCwd === undefined || projectCwd === '')
+            return candidates;
+        for (const { key } of this.projectChain(projectCwd)) {
+            const table = this.projectTables.get(key);
+            if (table !== undefined)
+                candidates.push(...this.recordsOf(table));
+        }
+        return candidates;
+    }
+    /**
+     * 按 id 定位记录所在表：global 优先，其次工作区链（自身 → 祖先，由近及远）。
+     * **异步版**——写路径必须用它：`writeScope` 可能在本次进入前刚 `reload()`，
+     * 那时同步缓存已被清空（同 {@link markUsedInner} 的注释）。
+     */
+    async locateRecord(id, projectCwd) {
+        const global = this.requireTable('global');
+        const globalBlock = global.get(id);
+        if (globalBlock !== undefined)
+            return { table: global, block: globalBlock };
+        for (const { table } of await this.projectChainTables(projectCwd)) {
+            const block = table.get(id);
+            if (block !== undefined)
+                return { table, block };
+        }
+        return undefined;
+    }
     /** 记录当前指纹，作为「这就是我们造成的状态」的基准（写入完成后调用）。 */
     noteStoreStamps(projectCwd) {
         const global = this.globalStoreFile();
@@ -601,14 +759,19 @@ export class MemoryEngine extends Service {
         }
         return { ...(toolNames === undefined ? {} : { toolNames }), selfVersion: SELF_VERSION };
     }
+    /** 同步版定位：只查**已打开**的表（global + 链上已缓存的工作区表）。 */
     tableOf(id, projectCwd) {
         const global = this.requireTable('global');
         if (global.get(id) !== undefined)
             return global;
         if (projectCwd === undefined || projectCwd === '')
             return undefined;
-        const project = this.projectTables.get(join(projectCwd));
-        return project !== undefined && project.get(id) !== undefined ? project : undefined;
+        for (const { key } of this.projectChain(projectCwd)) {
+            const table = this.projectTables.get(key);
+            if (table !== undefined && table.get(id) !== undefined)
+                return table;
+        }
+        return undefined;
     }
     /** 命中标记：写回 lastUsedAt 与命中次数，达标即自动升常驻（2026-09-15）。 */
     async markUsed(ids, projectCwd) {
@@ -622,17 +785,21 @@ export class MemoryEngine extends Service {
         const global = this.requireTable('global');
         // 取表走异步版：`writeScope` 可能在本次进入前刚 `reload()`（外部实例改过存储），
         // 那时同步缓存已被清空——继续读缓存会把 project 侧的命中静默漏记。
-        const project = await this.projectTableFor(projectCwd);
+        // ④-A：链上的祖先表同样纳入。跨工作区命中的条目也要记账——否则它们的
+        // `lastUsedAt` 长期不动，会被 30 天规则误撤（「用得到却没被记录」）。
+        const chainTables = await this.projectChainTables(projectCwd);
         for (const id of ids) {
             const globalBlock = global.get(id);
             if (globalBlock !== undefined) {
                 await this.recordUse(global, id, globalBlock, now);
                 continue;
             }
-            if (project !== undefined) {
-                const block = project.get(id);
-                if (block !== undefined)
-                    await this.recordUse(project, id, block, now);
+            for (const { table } of chainTables) {
+                const block = table.get(id);
+                if (block !== undefined) {
+                    await this.recordUse(table, id, block, now);
+                    break;
+                }
             }
         }
     }
@@ -935,10 +1102,12 @@ export class MemoryEngine extends Service {
             this.ctx.emit('memory/changed', { operation: 'forgotten', id });
             return true;
         }
-        const project = await this.projectTableFor(projectCwd);
-        if (project !== undefined && await project.delete(id)) {
-            this.ctx.emit('memory/changed', { operation: 'forgotten', id });
-            return true;
+        // ④-A：删除要能命中链上的祖先表——「检索得到却删不掉」是最别扭的一种不一致
+        for (const { table } of await this.projectChainTables(projectCwd)) {
+            if (await table.delete(id)) {
+                this.ctx.emit('memory/changed', { operation: 'forgotten', id });
+                return true;
+            }
         }
         return false;
     }
@@ -947,40 +1116,24 @@ export class MemoryEngine extends Service {
     }
     /** {@link setStatus} 的实现体；必须经 `writeScope` 进入。 */
     async setStatusInner(id, status, projectCwd) {
-        const global = this.requireTable('global').get(id);
-        if (global !== undefined) {
-            const updated = {
-                ...global,
-                status,
-                // 旧数据可能缺 injected，写回时补全（读时迁移值）
-                injected: normalizeBlock(global).injected,
-                // 人工放行 = 审核通过并解除隔离（2026-09-15）
-                ...status === 'approved' ? { quarantined: false, quarantineReason: undefined } : {},
-                updatedAt: Date.now(),
-            };
-            await this.requireTable('global').put(id, updated);
-            const record = toRecord(id, updated);
-            this.ctx.emit('memory/changed', { operation: 'status', id, status });
-            return record;
-        }
-        const project = await this.projectTableFor(projectCwd);
-        if (project !== undefined) {
-            const block = project.get(id);
-            if (block !== undefined) {
-                const updated = {
-                    ...block,
-                    status,
-                    injected: normalizeBlock(block).injected,
-                    ...status === 'approved' ? { quarantined: false, quarantineReason: undefined } : {},
-                    updatedAt: Date.now(),
-                };
-                await project.put(id, updated);
-                const record = toRecord(id, updated);
-                this.ctx.emit('memory/changed', { operation: 'status', id, status });
-                return record;
-            }
-        }
-        throw new Error(`cannot set status of unknown memory '${id}'`);
+        // ④-A：定位走工作区链（global 优先，其次自身 → 祖先）——检索得到的记录就该改得动
+        const found = await this.locateRecord(id, projectCwd);
+        if (found === undefined)
+            throw new Error(`cannot set status of unknown memory '${id}'`);
+        const { table, block } = found;
+        const updated = {
+            ...block,
+            status,
+            // 旧数据可能缺 injected，写回时补全（读时迁移值）
+            injected: normalizeBlock(block).injected,
+            // 人工放行 = 审核通过并解除隔离（2026-09-15）
+            ...status === 'approved' ? { quarantined: false, quarantineReason: undefined } : {},
+            updatedAt: Date.now(),
+        };
+        await table.put(id, updated);
+        const record = toRecord(id, updated);
+        this.ctx.emit('memory/changed', { operation: 'status', id, status });
+        return record;
     }
     /**
      * 注入维度开关（0.3.0）：只改 injected，不动审核状态。供 UI 面板「常驻注入」开关调用
@@ -994,19 +1147,8 @@ export class MemoryEngine extends Service {
     }
     /** {@link setInjected} 的实现体；必须经 `writeScope` 进入。 */
     async setInjectedInner(id, injected, projectCwd) {
-        const locate = async () => {
-            const global = this.requireTable('global').get(id);
-            if (global !== undefined)
-                return { table: this.requireTable('global'), block: global };
-            const project = await this.projectTableFor(projectCwd);
-            if (project !== undefined) {
-                const block = project.get(id);
-                if (block !== undefined)
-                    return { table: project, block };
-            }
-            return undefined;
-        };
-        const found = await locate();
+        // ④-A：定位走工作区链（global 优先，其次自身 → 祖先）
+        const found = await this.locateRecord(id, projectCwd);
         if (found === undefined)
             throw new Error(`cannot set injected of unknown memory '${id}'`);
         // 模板永不注入（0.6.0）：prompt 记录拒绝开关（UI 对该类不展示开关，此处兜底）
@@ -1077,22 +1219,14 @@ export class MemoryEngine extends Service {
             }
             return record;
         };
-        const global = this.requireTable('global').get(id);
-        if (global !== undefined) {
-            const updated = applyPatch(global);
-            await this.requireTable('global').put(id, updated);
-            return publish(global, updated);
-        }
-        const project = await this.projectTableFor(projectCwd);
-        if (project !== undefined) {
-            const block = project.get(id);
-            if (block !== undefined) {
-                const updated = applyPatch(block);
-                await project.put(id, updated);
-                return publish(block, updated);
-            }
-        }
-        throw new Error(`cannot update unknown memory '${id}'`);
+        // ④-A：定位走工作区链（global 优先，其次自身 → 祖先）——检索得到的记录就该改得动
+        const found = await this.locateRecord(id, projectCwd);
+        if (found === undefined)
+            throw new Error(`cannot update unknown memory '${id}'`);
+        const { table, block } = found;
+        const updated = applyPatch(block);
+        await table.put(id, updated);
+        return publish(block, updated);
     }
     /**
      * 预热某工作区的 project 表（异步打开并缓存）。system prompt 的
@@ -1101,6 +1235,10 @@ export class MemoryEngine extends Service {
      */
     async ensureProjectOpen(projectCwd) {
         const key = join(projectCwd);
+        // ④-B：子项目发现与表预热相互独立——表可能早已打开，而发现还没跑过。
+        // 注入 provider 是同步的、只能读缓存，所以必须在这条异步预热路径上先把发现做掉。
+        if (!this.neighborCache.has(key))
+            void this.discoverNeighbors(key).catch(() => undefined);
         if (this.projectTables.has(key))
             return;
         await this.projectTableFor(key);
@@ -1130,19 +1268,20 @@ export class MemoryEngine extends Service {
         return [...global, ...injected(project)];
     }
     async allRecords(namespace, projectCwd) {
-        if (namespace === 'project') {
-            const project = await this.projectTableFor(projectCwd);
-            if (project === undefined)
-                return [];
-            return this.recordsOf(project);
-        }
+        // ④-A：project 侧从「当前 cwd 那一张表」扩为「工作区链上的表」（自身 + 已存在的祖先）。
+        // 祖先记录带 scope 标记（`..` / `../..`），让调用方与用户都看得出这条来自哪一级。
+        const projectRecords = async () => {
+            const tables = await this.projectChainTables(projectCwd);
+            return tables.flatMap(({ depth, table }) => {
+                const scope = MemoryEngine.scopeLabel(depth);
+                return this.recordsOf(table).map(record => scope === undefined ? record : { ...record, scope });
+            });
+        };
+        if (namespace === 'project')
+            return projectRecords();
         if (namespace === 'global')
             return this.recordsOf(this.requireTable('global'));
-        const project = await this.projectTableFor(projectCwd);
-        return [
-            ...this.recordsOf(this.requireTable('global')),
-            ...(project === undefined ? [] : this.recordsOf(project)),
-        ];
+        return [...this.recordsOf(this.requireTable('global')), ...await projectRecords()];
     }
     recordsOf(table) {
         return [...table.entries()].map(([id, block]) => toRecord(id, block));

package/dist/index.js

@@ -9,7 +9,7 @@ import { MemoryEngine } from "./engine.js";
 import { MemoryGateway } from "./remote.js";
 import { mountMemoryApi } from "./routes.js";
 import { SELF_DESCRIPTION } from "./self.js";
-import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, omittedNotice, renderInjection } from "./injection.js";
+import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, indexNotice, neighborNotice, omittedNotice, renderInjection } from "./injection.js";
 export { MemoryEngine } from "./engine.js";
 export { MemoryId } from "./engine.js";
 export { bm25FieldScores, bm25Scores, cosineSimilarity, rrfFuse, tokenize } from "./bm25.js";
@@ -32,6 +32,7 @@ const RECORD_SCHEMA = {
         staleReason: { type: 'string' },
         hitCount: { type: 'number' },
         quarantined: { type: 'boolean' },
+        scope: { type: 'string', description: '来源工作区（④-A）：缺省 = 当前会话工作区；`..` / `../..` = 上级工作区。' },
     },
 };
 const HIT_SCHEMA = {
@@ -72,6 +73,7 @@ function recordValue(record) {
         ...record.staleReason === undefined ? {} : { staleReason: record.staleReason },
         hitCount: record.hitCount,
         ...record.quarantined === true ? { quarantined: true } : {},
+        ...record.scope === undefined ? {} : { scope: record.scope },
     };
 }
 function hitValue(hit) {
@@ -92,15 +94,29 @@ function promptValue(record) {
 }
 // 0.3.0：审核语义双语（host 侧 GUIDANCE 无法跟随 DSH locale 动态切换，
 // 采用中英双语都写、模型自取——设计文档「风险与注意」）。
+// 0.9.2：常驻注入不再是「人工开关」——0.8.0 起模型侧可经 `injected` 参数显式钉住。
+// 旧表述会让模型以为自己没有该权限，也与同段「人工只在例外时介入」自相矛盾。
+// 0.10.0：补 namespace 判据——此前只有工具 schema 的 `defaults to global`，全体系没有
+// 任何「该记哪一层」的说明，陌生环境的模型会全写 global，project 层因此永远空着。
 const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and project conventions. '
     + '记忆工具用于跨会话的偏好、习惯与项目约定。'
     + 'memory_save writes a memory that takes effect immediately (`approved`) — memories are maintained '
     + 'by the system and the model, and humans intervene only as exceptions. Credential-like content is '
     + 'quarantined instead. memory_save 写入即生效（`approved`）——记忆由系统与模型自行维护，人工只在例外时介入；'
     + '命中危险内容规则（密钥/凭据）的写入会被隔离。'
-    + 'Approval only marks the content reviewed; whether it is injected every turn is a separate '
-    + 'human-controlled switch (`injected`). 审核通过只代表内容被认可；是否每轮常驻注入由独立的'
-    + '人工开关（`injected`）控制。'
+    + 'Choose the namespace by one question — **does this still hold in a different project?** Yes → `global` '
+    + '(preferences, habits, environment knowledge); no → `project` (this repository\'s own conventions, '
+    + 'architecture decisions, its pitfalls). '
+    + '用一句话选 namespace——**换个项目，这条还成立吗？** 成立 → `global`（偏好、习惯、环境知识）；'
+    + '不成立 → `project`（本仓库自己的约定、架构决策、它踩过的坑）。'
+    + 'Pass `injected: true` on memory_save / memory_update to pin a memory resident in every turn\'s context: '
+    + 'the same switch the settings panel exposes, exempting the record from both automatic rules (promote on '
+    + 'repeated hits, demote after long idle). 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. '
+    + '给 memory_save / memory_update 传 `injected: true` 即把这条钉成每轮常驻——与设置面板是同一个开关，'
+    + '此后不受两条自动规则（反复命中自动开启 / 长期未命中自动撤下）影响。只用于规则、长期约定与判据这类'
+    + '「没人想起来搜也必须生效」的记忆；事实、参考与案例留作按需检索。'
     + 'When earlier context may be relevant, call memory_search to recall it — reviewable memories '
     + '相关历史上下文可用 memory_search 检索；被隔离的记录不进检索。'
     + 'Every memory is plaintext and inspectable with memory_list; memory_forget removes one. '
@@ -124,6 +140,14 @@ function recallText(memory, projectCwd, budget, summaryChars) {
     const notice = omittedNotice(rendered);
     if (notice !== '')
         parts.push(notice);
+    // ① 索引行：给出「库里还有什么、按什么去搜」（不占预算、长度常数级）
+    const index = indexNotice(memory.indexCandidates(projectCwd));
+    if (index !== '')
+        parts.push(index);
+    // ④-B：子项目索引（有才出、不占预算）——补「不知道存在」这个检索的结构性盲区
+    const neighbors = neighborNotice(memory.neighborsOf(projectCwd));
+    if (neighbors !== '')
+        parts.push(neighbors);
     return parts.join('\n');
 }
 /** 从组装上下文取当前 agent 会话的工作区 cwd（AssembleContext.agent 由 dsh-agent 声明合并提供）。 */

package/dist/injection.d.ts

@@ -54,3 +54,33 @@ export declare function renderInjection(records: readonly MemoryRecord[], budget
  * {@link OMITTED_NOTICE_LIMIT} 只列前 N 个。
  */
 export declare function omittedNotice(rendered: InjectionRender): string;
+/** 子项目索引行列出的条数上限（④-B）：超出以 `…` 结尾，防这行本身失控。 */
+export declare const NEIGHBOR_NOTICE_LIMIT = 5;
+/**
+ * 子项目索引行（④-B 2026-09-19）：告诉模型「当前工作区下面还有什么」——它补的是
+ * 「不知道存在」这个检索的结构性盲区，而**不搬运内容**（正文照旧走 memory_search）。
+ *
+ * 与预算诊断行同待遇：**不占注入预算**、自消除（没有子项目记忆时返回空串）。
+ * 只报条数不报 id——这一行的用途是给出**规模与入口**，不是当检索结果用。
+ */
+export declare function neighborNotice(neighbors: ReadonlyArray<{
+    name: string;
+    count: number;
+}>): string;
+/** 索引行列出的主题数上限（① 2026-09-19）：常数级——这行不随库增长。 */
+export declare const INDEX_NOTICE_TOPICS = 5;
+/**
+ * 记忆索引行（① 2026-09-19）：给出「库里还有什么、按什么去搜」。
+ *
+ * 它补的是**检索的结构性盲区**——检索是有意图的动作，不知道某条记忆存在就搜不出它。
+ * 注入行每轮只装得下约 11 条，其余上百条对模型完全不可见；这一行报出**规模与入口**，
+ * 让「不在场」变成「知道存在、需要时去取」。
+ *
+ * 为什么不做成一条常驻记忆（用户最初的设想）：那样它会自己占约 135 字符预算、参与零和
+ * 竞争、可能自己也被挤掉，而且记忆增删后**不会自动更新**（目录与内容不一致且无人察觉）。
+ * 做成系统生成的行则：不占预算、不可能腐化、永远反映当前状态。
+ *
+ * 主题取自各条的 `keywords` 词频——那是记忆写入时被要求「给多角度」的字段，**与检索用的
+ * 是同一套词汇**，所以索引里出现的词就是能搜到的词。同频时按字典序排，保证输出确定。
+ */
+export declare function indexNotice(records: ReadonlyArray<MemoryRecord>): string;

package/dist/injection.js

@@ -30,7 +30,9 @@ export function deriveSummary(content, maxChars) {
 }
 /** 一条注入行的渲染文本（与面板预览完全一致）。 */
 export function injectionLine(record, summaryChars) {
-    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}] ${deriveSummary(record.content, summaryChars)}`;
+    // ④-A：跨工作区召回时带来源标记（`..` / `../..`）；当前工作区不带，保持既有格式
+    const scope = record.scope === undefined ? '' : `@${record.scope}`;
+    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}${scope}] ${deriveSummary(record.content, summaryChars)}`;
 }
 /**
  * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
@@ -75,3 +77,56 @@ export function omittedNotice(rendered) {
     const truncated = rendered.omittedRecords.length > shown.length ? '…' : '';
     return `（另有 ${rendered.omitted} 条常驻因预算未注入：${labels.join('、')}${truncated}）`;
 }
+/** 子项目索引行列出的条数上限（④-B）：超出以 `…` 结尾，防这行本身失控。 */
+export const NEIGHBOR_NOTICE_LIMIT = 5;
+/**
+ * 子项目索引行（④-B 2026-09-19）：告诉模型「当前工作区下面还有什么」——它补的是
+ * 「不知道存在」这个检索的结构性盲区，而**不搬运内容**（正文照旧走 memory_search）。
+ *
+ * 与预算诊断行同待遇：**不占注入预算**、自消除（没有子项目记忆时返回空串）。
+ * 只报条数不报 id——这一行的用途是给出**规模与入口**，不是当检索结果用。
+ */
+export function neighborNotice(neighbors) {
+    if (neighbors.length === 0)
+        return '';
+    const shown = neighbors.slice(0, NEIGHBOR_NOTICE_LIMIT);
+    const labels = shown.map(neighbor => `${neighbor.name}（${neighbor.count} 条）`);
+    const truncated = neighbors.length > shown.length ? '…' : '';
+    return `（本工作区下另有 ${neighbors.length} 个子项目带记忆：${labels.join('、')}${truncated}——用 memory_search 检索）`;
+}
+/** 索引行列出的主题数上限（① 2026-09-19）：常数级——这行不随库增长。 */
+export const INDEX_NOTICE_TOPICS = 5;
+/**
+ * 记忆索引行（① 2026-09-19）：给出「库里还有什么、按什么去搜」。
+ *
+ * 它补的是**检索的结构性盲区**——检索是有意图的动作，不知道某条记忆存在就搜不出它。
+ * 注入行每轮只装得下约 11 条，其余上百条对模型完全不可见；这一行报出**规模与入口**，
+ * 让「不在场」变成「知道存在、需要时去取」。
+ *
+ * 为什么不做成一条常驻记忆（用户最初的设想）：那样它会自己占约 135 字符预算、参与零和
+ * 竞争、可能自己也被挤掉，而且记忆增删后**不会自动更新**（目录与内容不一致且无人察觉）。
+ * 做成系统生成的行则：不占预算、不可能腐化、永远反映当前状态。
+ *
+ * 主题取自各条的 `keywords` 词频——那是记忆写入时被要求「给多角度」的字段，**与检索用的
+ * 是同一套词汇**，所以索引里出现的词就是能搜到的词。同频时按字典序排，保证输出确定。
+ */
+export function indexNotice(records) {
+    const usable = records.filter(record => record.status === 'approved'
+        && record.quarantined !== true
+        && (record.kind ?? 'fact') !== 'prompt');
+    if (usable.length === 0)
+        return '';
+    const counts = new Map();
+    for (const record of usable) {
+        for (const keyword of record.keywords) {
+            counts.set(keyword, (counts.get(keyword) ?? 0) + 1);
+        }
+    }
+    if (counts.size === 0)
+        return '';
+    const topics = [...counts.entries()]
+        .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+        .slice(0, INDEX_NOTICE_TOPICS);
+    const labels = topics.map(([topic, count]) => `${topic}(${count})`);
+    return `（索引：当前可见 ${usable.length} 条记忆，主题集中在 ${labels.join('、')}——用 memory_search 检索）`;
+}

package/dist/self.js

@@ -2,6 +2,9 @@
  * 记忆机制自述（memory:self 注入内容 + 面板「注入预览」共用）。
  * 0.3.2 起：LLM 每轮知道本环境有记忆机制；不落用户存储，随发版更新，
  * 版本号动态读取 package.json（"只跟随 dsh-memory 组件发版变动"）。
+ * 0.9.2：补齐常驻注入机制——`injected` 参数、注入预算上限、预算诊断行的含义。
+ * 0.10.0：修正工具清单（6 → 10，补提示词模板工具）与两层记忆说明——原清单漏了
+ * `prompt_*` 系列，照它读会以为本插件只有记忆工具。
  */
 import { createRequire } from 'node:module';
 export const SELF_VERSION = (() => {
@@ -16,7 +19,8 @@ export const SELF_VERSION = (() => {
     }
 })();
 export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
-    + '你有 6 个记忆工具：memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget。'
+    + '你有 10 个工具：**记忆工具** memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget（`memory_confirm` 仅在用户明确要求放行隔离记录时用）；**提示词模板工具** prompt_search / prompt_get / prompt_list / prompt_add（模板是 md 文件、**永不注入**，走这条通道，不会混进记忆检索）。'
+    + '记忆分两层：`global` 跨项目（偏好 / 习惯 / 环境知识），`project` 跟随工作区（落在 `<cwd>/.dsh/storages/`，随 git 提交分享）。'
     + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'
     + '① 用户表达长期偏好或约定（「以后都…」「记住…」「我们的规矩是…」）；'
     + '② 用户纠正了你的做法或理解——把正确结论记下来；'
@@ -25,6 +29,10 @@ export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话
     + '**怎么写**：一条一件事，并给多角度关键词（同义词、缩写、中英），否则将来检索不到它。'
     + '**锚点（可选）**：若这条记忆描述的是「随某个环境值变化的事实」（某工具版本下的行为、某环境变量决定的配置），用 anchor 参数把它绑到那个值上——值变了它会自动失效并标 stale，不会再被当成仍然正确。'
     + '写入即生效（`approved`），人工只在例外时介入；命中密钥/凭据规则的写入会被隔离（不进注入与检索）。'
-    + '每轮注入的是「global + 当前会话工作区」里已生效且开着常驻开关的记忆摘要（受预算限制，超预算按最近更新优先）；全文要靠 memory_search。'
+    + '**常驻注入**：每轮注入「global + 当前会话工作区」里 approved 且开着常驻开关的记忆单行摘要（形如 `- [memory:id:namespace] 摘要`）；全文要靠 memory_search 取。'
+    + '开关有两条自动规则：命中累计 2 次自动开启、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.)';
+    + '（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.)';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.9.1",
+  "version": "0.10.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": {
@@ -23,7 +23,8 @@
     "cordis.patch.yml",
     "README.md",
     "LICENSE",
-    "docs/shots"
+    "docs/shots",
+    "scripts/scan-orphans.mjs"
   ],
   "dsh": {
     "bundle": {

package/scripts/scan-orphans.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * 孤儿记忆文件清点（④-C 2026-09-19）——**只读，不做任何处置**。
+ *
+ * 背景：project 记忆的文件名是 `memory_project_<djb2(工作区路径)>.json`，而代码只按这个
+ * 名字去找。历史上换过命名（早期无哈希后缀、有过双重 `memory_project_` 前缀），那些旧文件
+ * 因此**永远不会被打开**——不是「等人放行」，是代码已经不认识这个文件名了。实测
+ * （2026-09-19）全工作区 136 条 project 记忆里有 33 条处于这个状态。
+ *
+ * 本脚本回答一个问题：**哪些文件当前代码打不开**。它不迁移、不删除、不修改任何东西。
+ * 处置（归档 / 选择性导入 / 删除）是一次显式的人工动作，理由见设计文档 §3.4：
+ * 旧文件可能含 0.7.0 之前未过 `detectSensitive` 的内容，自动捞出来等于绕过隔离检查。
+ *
+ * 用法：node scripts/scan-orphans.mjs [根目录]（缺省为当前目录）
+ */
+import { readdirSync, existsSync, readFileSync, statSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** 与 engine.ts 的 projectBackendName 逐字一致：djb2 over 小写路径，36 进制。 */
+function projectBackendName(cwd) {
+  let h = 5381
+  const text = cwd.toLowerCase()
+  for (let i = 0; i < text.length; i++) h = ((h << 5) + h + text.charCodeAt(i)) | 0
+  return `memory_project_${Math.abs(h).toString(36)}`
+}
+
+/** 递归找出所有 `.dsh/storages` 目录；跳过 node_modules / .git，限深防跑飞。 */
+function findStorageDirs(root, depth = 0, out = []) {
+  if (depth > 4) return out
+  let entries = []
+  try {
+    entries = readdirSync(root, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name === 'node_modules' || entry.name === '.git') continue
+    const full = join(root, entry.name)
+    if (entry.name === '.dsh') {
+      const storages = join(full, 'storages')
+      if (existsSync(storages)) out.push(storages)
+      continue
+    }
+    findStorageDirs(full, depth + 1, out)
+  }
+  return out
+}
+
+/** 数一个记忆文件里的记录条数；读不出来返回 null（诚实报告「读不了」而不是 0）。 */
+function countRecords(file) {
+  try {
+    const blocks = JSON.parse(readFileSync(file, 'utf8'))?.tables?.blocks ?? {}
+    return Object.values(blocks).filter(block => block && block.content).length
+  } catch {
+    return null
+  }
+}
+
+const root = process.argv[2] ?? process.cwd()
+const storageDirs = findStorageDirs(root)
+
+console.log(`扫描根：${root}`)
+console.log(`发现 ${storageDirs.length} 个 storages 目录\n`)
+
+let orphans = 0
+let orphanRecords = 0
+let healthy = 0
+
+for (const storages of storageDirs) {
+  const workspace = dirname(dirname(storages))
+  const expected = `${projectBackendName(workspace)}.json`
+  let files = []
+  try {
+    files = readdirSync(storages).filter(name => name.startsWith('memory_project') && name.endsWith('.json'))
+  } catch {
+    continue
+  }
+  if (files.length === 0) continue
+
+  const rows = files.map(name => {
+    const file = join(storages, name)
+    return {
+      name,
+      ok: name === expected,
+      count: countRecords(file),
+      size: statSync(file).size,
+      mtime: new Date(statSync(file).mtimeMs).toISOString().slice(0, 10),
+    }
+  })
+  const bad = rows.filter(row => !row.ok)
+  const good = rows.filter(row => row.ok)
+
+  console.log(`── ${workspace}`)
+  console.log(`   期望文件名：${expected}`)
+  for (const row of good) {
+    healthy += 1
+    console.log(`   ✅ ${row.name}  ${row.count ?? '?'} 条  ${row.size}B  ${row.mtime}`)
+  }
+  for (const row of bad) {
+    orphans += 1
+    orphanRecords += row.count ?? 0
+    console.log(`   ⚠️  ${row.name}  ${row.count ?? '?'} 条  ${row.size}B  ${row.mtime}  ← 代码打不开`)
+  }
+  console.log('')
+}
+
+console.log('── 汇总 ──')
+console.log(`能被代码打开：${healthy} 个文件`)
+console.log(`打不开（孤儿）：${orphans} 个文件，共 ${orphanRecords} 条记录`)
+console.log('\n本脚本只清点。处置（归档 / 选择性导入 / 删除）见设计文档 §3.4，需人工拍板后单独执行。')