@max-null/dsh-memory 0.9.2 → 0.11.0

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,15 +356,178 @@ export class MemoryEngine extends Service {
         const key = join(projectCwd);
         return join(this.projectRootFor(key), `${this.projectBackendName(key)}.json`);
     }
-    /** 记录当前指纹，作为「这就是我们造成的状态」的基准（写入完成后调用）。 */
-    noteStoreStamps(projectCwd) {
-        const global = this.globalStoreFile();
-        this.storeStamps.set(global, MemoryEngine.fileStamp(global));
+    /**
+     * 工作区链（④-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;
+    }
+    /**
+     * 写入协调覆盖的存储文件：global + **全部已打开的工作区表** + 本次 cwd。
+     *
+     * 记录（{@link noteStoreStamps}）与比对（{@link refreshForWrite}）必须共用这一个定义——
+     * 两边各写一份正是漂移的来源：在此之前比对侧只列 global + cwd，而 ④-A 把**读**路径扩到了
+     * 祖先链（`projectChain`），于是被缓存过的祖先层「指纹记下了却从不被检查」——外部改动看不见，
+     * 下一次写回把它**整份覆盖**。**读扩到哪，门就得跟着扩到哪。**
+     */
+    storeScopeFiles(projectCwd) {
+        const files = [this.globalStoreFile()];
         const scopes = new Set(this.projectTables.keys());
         if (projectCwd !== undefined && projectCwd !== '')
             scopes.add(join(projectCwd));
-        for (const key of scopes) {
-            const file = this.projectStoreFile(key);
+        for (const key of scopes)
+            files.push(this.projectStoreFile(key));
+        return files;
+    }
+    /** 记录当前指纹，作为「这就是我们造成的状态」的基准（写入完成后调用）。 */
+    noteStoreStamps(projectCwd) {
+        for (const file of this.storeScopeFiles(projectCwd)) {
             this.storeStamps.set(file, MemoryEngine.fileStamp(file));
         }
     }
@@ -371,10 +540,7 @@ export class MemoryEngine extends Service {
             this.noteStoreStamps(projectCwd);
             return;
         }
-        const files = [this.globalStoreFile()];
-        if (projectCwd !== undefined && projectCwd !== '')
-            files.push(this.projectStoreFile(projectCwd));
-        for (const file of files) {
+        for (const file of this.storeScopeFiles(projectCwd)) {
             if (MemoryEngine.fileStamp(file) === this.storeStamps.get(file))
                 continue;
             await this.reload();
@@ -601,14 +767,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 +793,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,52 +1110,129 @@ 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;
     }
+    /**
+     * 把一条记忆移到另一层（迭代设计 §3.2）。**两个方向共用一个操作**：向上提到祖先层或
+     * `global`，向下把误放高层的降回它真正属于的工作区。
+     *
+     * 原设计（`memory_promote`）只允许向上，理由是「往下或横向会让原本能看见的人失明」。
+     * 但**移动的本意就是改变谁能看见**——那不是副作用，是目的。所以约束从「禁止方向」
+     * 换成「让后果可见」：返回值里的 `sourceStillSees` 就是那个后果。
+     */
+    async move(id, to, projectCwd) {
+        return this.writeScope(projectCwd, () => this.moveInner(id, to, projectCwd));
+    }
+    /** {@link move} 的实现体；必须经 `writeScope` 进入。 */
+    async moveInner(id, to, projectCwd) {
+        const target = MemoryEngine.resolveTarget(to, projectCwd);
+        const found = await this.locateWithKey(id, projectCwd);
+        if (found === undefined)
+            throw new Error(`cannot move unknown memory '${id}'`);
+        const destination = target.kind === 'global'
+            ? this.requireTable('global')
+            : await this.projectTableFor(target.key);
+        if (destination === undefined)
+            throw new Error('cannot move a project memory without a workspace cwd');
+        if (destination === found.table)
+            throw new Error(`memory '${id}' is already stored in '${to}'`);
+        // 先写目标、再删源：中间态里它同时存在于两处（重复好过丢失），而两次写同处一个
+        // writeScope，外部看不到中间态。
+        await destination.put(id, found.block);
+        await found.table.delete(id);
+        // 继承只向上，而 global 人人可见——所以「移进 global」与「移进自己的某个祖先」都能
+        // 让源层继续看得见它；反过来（global → 某工作区、祖先 → 后代）就是缩小范围。
+        const sourceStillSees = target.kind === 'global'
+            || (found.key !== 'global' && MemoryEngine.isAncestorOrSelf(target.key, found.key));
+        const movedTo = target.kind === 'global' ? 'global' : target.key;
+        this.ctx.emit('memory/changed', { operation: 'moved', id, from: found.key, to: movedTo });
+        return { id, from: found.key, to: movedTo, sourceStillSees };
+    }
+    /** 按 id 定位记录**并带上它所在的层**（`locateRecord` 只返回表，而移动必须知道来源层）。 */
+    async locateWithKey(id, projectCwd) {
+        const global = this.requireTable('global');
+        const globalBlock = global.get(id);
+        if (globalBlock !== undefined)
+            return { key: 'global', table: global, block: globalBlock };
+        for (const { key, table } of await this.projectChainTables(projectCwd)) {
+            const block = table.get(id);
+            if (block !== undefined)
+                return { key, table, block };
+        }
+        return undefined;
+    }
+    /**
+     * 解析 `memory_move` 的目标：`global`、`self` / `.`（当前 cwd），或相对祖先（`..`、`../..`）。
+     *
+     * 用**相对深度**而不是绝对路径，是为了和来源标记 `scope`（`..` / `../..`）说同一套话。
+     * 允许落在**还没有记忆文件**的祖先层——移动是显式动作，在那儿创建文件正是目的，
+     * 不是 `projectChain` 要避免的那种副作用。
+     */
+    static resolveTarget(to, projectCwd) {
+        const raw = to.trim();
+        if (raw === 'global')
+            return { kind: 'global' };
+        if (projectCwd === undefined || projectCwd === '') {
+            throw new Error('moving a memory into a workspace layer needs a session cwd');
+        }
+        if (raw === 'self' || raw === '.')
+            return { kind: 'workspace', key: join(projectCwd) };
+        const parts = raw.split(/[\\/]/).filter(part => part !== '' && part !== '.');
+        if (!parts.every(part => part === '..')) {
+            throw new Error(`unknown move target '${to}' — use 'global', 'self', or a relative ancestor ('..', '../..')`);
+        }
+        let key = join(projectCwd);
+        for (let i = 0; i < parts.length; i++) {
+            const parent = dirname(key);
+            if (parent === key)
+                throw new Error(`move target '${to}' points above the filesystem root`);
+            key = parent;
+        }
+        return { kind: 'workspace', key };
+    }
+    /** `ancestor` 是否就是 `node` 本身或它的祖先——用来判断移动后源层是否仍看得见。 */
+    static isAncestorOrSelf(ancestor, node) {
+        const want = join(ancestor).toLowerCase();
+        let cur = join(node);
+        for (;;) {
+            if (cur.toLowerCase() === want)
+                return true;
+            const parent = dirname(cur);
+            if (parent === cur)
+                return false;
+            cur = parent;
+        }
+    }
     async setStatus(id, status, projectCwd) {
         return this.writeScope(projectCwd, () => this.setStatusInner(id, status, projectCwd));
     }
     /** {@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 +1246,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 +1318,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 +1334,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 +1367,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) {
@@ -94,12 +96,24 @@ function promptValue(record) {
 // 采用中英双语都写、模型自取——设计文档「风险与注意」）。
 // 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`）——记忆由系统与模型自行维护，人工只在例外时介入；'
     + '命中危险内容规则（密钥/凭据）的写入会被隔离。'
+    + '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`（本仓库自己的约定、架构决策、它踩过的坑）。'
+    + 'Record where a conclusion came from, not just the conclusion: the reason it holds, and the situation '
+    + 'that forced it out. A conclusion without its origin is a ruler with no provenance — it looks '
+    + 'self-evident, and self-evident things get applied mechanically. '
+    + '记结论时一并记下**它是怎么来的**——它为什么成立，以及是什么场景把它逼出来的。没有出处的结论像一把'
+    + '没有来历的尺子：看起来天经地义，而天经地义的东西最容易被机械套用。'
     + '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 '
@@ -131,6 +145,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 声明合并提供）。 */
@@ -446,6 +468,31 @@ export async function apply(ctx, config) {
         },
         presentCall: args => present('Forget memory', 'other', args.id),
     }));
+    ctx.tools.register(defineTool({
+        name: 'memory_move',
+        description: 'Move one memory to another layer: `global`, `self` (the current workspace), or a relative ancestor (`..` / `../..`). Use it when a memory sits at the wrong level — a project-specific rule parked in `global` that leaks into unrelated workspaces, or a fact that turned out to hold for sibling projects too. The record keeps its id, and the result reports whether the source layer still sees it. 把一条记忆移到另一层：`global`、`self`（当前工作区）或相对祖先（`..` / `../..`）。用于记忆待错了层——只属于某个项目的规矩躺在 `global` 里、漏进无关工作区，或某条事实其实对兄弟项目也成立。id 保持不变，结果里会报告移动后源层是否仍看得见它。',
+        parameters: {
+            id: { type: 'string', required: true, description: 'Exact memory id from memory_list or memory_search. 要移动的记忆 id。' },
+            to: { type: 'string', required: true, description: 'Target layer: `global`, `self` (current workspace), or a relative ancestor such as `..` / `../..`. 目标层：`global`、`self`（当前工作区），或 `..` / `../..` 这样的相对祖先。' },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    from: { type: 'string', required: true, description: '移动前所在的层（`global` 或工作区路径）。' },
+                    to: { type: 'string', required: true, description: '移动后的层。' },
+                    sourceStillSees: { type: 'boolean', required: true, description: '源层移动后是否仍看得见它。为假表示源层及其下层从此看不见这条记忆。' },
+                },
+            },
+            render: (_args, value) => renderJson(value),
+        },
+        execute(args, exec) {
+            return memory.move(args.id, args.to, execProjectCwd(exec));
+        },
+        presentCall: args => present('Move memory', 'other', `${args.id} → ${args.to}`),
+    }));
     ctx.tools.register(defineTool({
         name: 'memory_update',
         description: 'Update the content, keywords or persistent-injection switch of one stored memory (e.g. correcting stale facts). The record keeps its review status; content that looks like a credential quarantines it instead. 修改一条记忆的内容、关键词或常驻注入开关（如修正过时信息）。改动后记忆保持原有审核状态；若新内容命中危险规则则转为隔离。',