@max-null/dsh-memory 0.7.2 → 0.8.0

package/README.md

@@ -74,15 +74,18 @@ md 文件是唯一事实源（`~/.dsh/prompt-library/*.md` 为 global；`<worksp
 
 ```
 模型 memory_save     →  status: approved，立即生效；命中密钥/凭据规则则隔离（不进检索也不进注入）
+                        给 injected 则同时钉住常驻（0.8.0），不吃下面两条自动规则
 memory_search        →  关键词/语义召回（只搜记忆；模板走 prompt_search 通道，不会混进候选池）
 命中累计 2 次         →  injected: true（自动打开常驻：global + 当前会话工作区，摘要化 + 预算截断）
-30 天未再命中         →  自动撤下常驻（只撤自动开的；人工动过的开关双向豁免）
+30 天未再命中         →  自动撤下常驻（只撤自动开的；人工或模型显式动过的开关双向豁免）
 人（面板 / 开关）     →  钉住 / 删除 / 放行隔离记录 / 回滚
 memory_forget        →  随时删除（删除始终是人的动作）
 ```
 
 两条自动规则撑起淘汰机制：**反复被检索命中**是它值得每轮付费的证据，**长期不再被命中**则自动退出常驻。两者都不删除任何内容——记忆不会无限累积，也不会被系统自行清空。
 
+自动规则对**低频但关键**的记忆（长期约定、判据、委托）够不着：它们不会被反复检索，够不到阈值；勉强够到也会被 30 天撤下。这类走显式路径——在 `memory_save` / `memory_update` 里给 `injected` 即钉住，写的是与面板开关同一套语义（`injectedAuto: false`），此后不受两条自动规则影响。未审核与已隔离的记录不接受注入。
+
 记忆还可声明**有效性锚点**（环境变量 / 工具清单 / 插件版本）：所绑的值变化后，这条记忆被标记 `stale` 并撤下常驻，检索结果里也带出失效提示——环境变了，旧结论就不再被当成仍然正确。
 
 模型写入不需要人点头，但**人始终能看见并推翻**：面板按「隔离区 / 常驻 / 冷数据」分组，被隔离的记录必须由人放行才会重新进入检索。

package/dist/engine.d.ts

@@ -94,6 +94,12 @@ export interface MemoryWrite {
      * 失效。只用于「随环境变化的事实」（某工具版本下的行为、某环境变量决定的配置）。
      */
     anchor?: MemoryAnchor;
+    /**
+     * 常驻注入（可选，2026-09-18）：显式指定这条记忆是否每轮进上下文。**给值即接管**——
+     * 与 {@link MemoryEngine.setInjected} 同一套语义（写 `injectedAuto: false`，此后不受自动
+     * 升降影响）。省略则维持缺省行为：不注入，且**保留**「被反复命中即自动升常驻」的资格。
+     */
+    injected?: boolean;
 }
 export interface MemoryFilter {
     namespace?: MemoryNamespace;
@@ -104,6 +110,16 @@ export interface MemoryFilter {
     /** 记录类别过滤（0.6.0）；缺省不过滤（工具层显式传 kind='fact' 保持旧行为）。 */
     kind?: MemoryKind;
 }
+/** {@link MemoryEngine.update} 的补丁：省略的字段保持原值（`injected` 省略时连 `injectedAuto` 一起保持）。 */
+export interface MemoryPatch {
+    content?: string;
+    keywords?: string[];
+    /**
+     * 常驻注入（2026-09-18）：给值即接管，与 {@link MemoryEngine.setInjected} 同义（写
+     * `injectedAuto: false`，此后不受自动升降影响）；省略则保持原值。
+     */
+    injected?: boolean;
+}
 export interface MemoryHit {
     record: MemoryRecord;
     score: number;
@@ -218,6 +234,8 @@ export declare class MemoryEngine extends Service {
     private globalTable?;
     /** project 域按工作区 cwd 懒打开 + 缓存（多会话并发各工作区独立）。 */
     private projectTables;
+    /** 进行中的工作区打开（key → promise）：并发调用复用同一次，见 {@link projectTableFor}。 */
+    private readonly projectOpenings;
     private projectFacilities;
     /** backend 只注册一次（registry 重名抛 duplicate；reload 清缓存后不得重复注册）。 */
     private registeredProjectBackends;
@@ -236,11 +254,24 @@ export declare class MemoryEngine extends Service {
     private projectRootFor;
     /** 稳定 backend 名（registry 重名抛错，按 cwd hash 唯一化；只允许 [a-z0-9_]，domain 名校验）。 */
     private projectBackendName;
+    /**
+     * 工作区表是否已经打开（同步判断）。组装路径用它决定「要不要等一次预热」——
+     * 表已打开是常态，那时这条路径不该付出任何异步代价。
+     */
+    projectOpen(projectCwd?: string): boolean;
     /**
      * 按工作区 cwd 取 project 表（懒打开 + 缓存）。无 cwd（未选工作区）
      * 返回 undefined——调用方（工具/面板）按此跳过 project 部分。
+     *
+     * **打开是异步的，调用方却会并发**：预热是 fire-and-forget，注入路径、工具路径、
+     * 面板路径各来一次。底层 unit 句柄只允许一个，两次并发打开会让后到者以
+     * `unit '…' is already open; a unit has exactly one live handle` 失败——而调用方
+     * 普遍把预热失败当无碍吞掉，于是表现为「这一轮工作区记忆缺席」。所以这里复用
+     * 进行中的那次打开。
      */
     private projectTableFor;
+    /** {@link projectTableFor} 的实际打开步骤；并发去重由调用方负责。 */
+    private openProjectTable;
     /**
      * 强制重载存储：关闭全局域与全部已开工作区域后重开（unit 释放后
      * backend 重读文件），放弃内存缓存。供外部编辑记忆文件后刷新
@@ -411,21 +442,22 @@ export declare class MemoryEngine extends Service {
     /** {@link setStatus} 的实现体；必须经 `writeScope` 进入。 */
     private setStatusInner;
     /**
-     * 注入维度开关（0.3.0）：只改 injected，不动审核状态。供 UI 面板
-     * 「常驻注入」开关调用（remote.setInjected）。
+     * 注入维度开关（0.3.0）：只改 injected，不动审核状态。供 UI 面板「常驻注入」开关调用
+     * （remote.setInjected）。2026-09-18 起模型侧有等价路径——`memory_save` / `memory_update`
+     * 的 `injected` 参数，经 {@link remember} / {@link update} 写同一套 `injectedAuto: false`
+     * 语义。差异只在越界处理：本方法对隔离记录**抛错**（用户明确要开，该被告知），
+     * 而写入/更新路径**静默降级为不注入**（那是顺带设置，不该中断整次写入）。
      */
     setInjected(id: MemoryId, injected: boolean, projectCwd?: string): Promise<MemoryRecord>;
     /** {@link setInjected} 的实现体；必须经 `writeScope` 进入。 */
     private setInjectedInner;
     /**
-     * 修改一条记忆的内容/关键词（0.3.1 整理记忆用）。2026-09-15 起：改动**不再**
-     * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态；
-     * `injected` 保留原值。若新内容命中危险规则则转为隔离（与写入路径同一判定）。
+     * 修改一条记忆的内容/关键词/注入位（0.3.1 整理记忆用）。2026-09-15 起：改动**不再**
+     * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态。2026-09-18
+     * 起可改 `injected`：**省略则保留原值**（连 `injectedAuto` 一起不动），给值即接管。若新
+     * 内容命中危险规则则转为隔离（与写入路径同一判定），并连带撤下注入。
      */
-    update(id: MemoryId, patch: {
-        content?: string;
-        keywords?: string[];
-    }, projectCwd?: string): Promise<MemoryRecord>;
+    update(id: MemoryId, patch: MemoryPatch, projectCwd?: string): Promise<MemoryRecord>;
     /** {@link update} 的实现体；必须经 `writeScope` 进入。 */
     private updateInner;
     /**

package/dist/engine.js

@@ -166,6 +166,8 @@ export class MemoryEngine extends Service {
     globalTable;
     /** project 域按工作区 cwd 懒打开 + 缓存（多会话并发各工作区独立）。 */
     projectTables = new Map();
+    /** 进行中的工作区打开（key → promise）：并发调用复用同一次，见 {@link projectTableFor}。 */
+    projectOpenings = new Map();
     projectFacilities = new Map();
     /** backend 只注册一次（registry 重名抛 duplicate；reload 清缓存后不得重复注册）。 */
     registeredProjectBackends = new Set();
@@ -211,9 +213,24 @@ export class MemoryEngine extends Service {
             h = ((h << 5) + h + text.charCodeAt(i)) | 0;
         return `memory_project_${Math.abs(h).toString(36)}`;
     }
+    /**
+     * 工作区表是否已经打开（同步判断）。组装路径用它决定「要不要等一次预热」——
+     * 表已打开是常态，那时这条路径不该付出任何异步代价。
+     */
+    projectOpen(projectCwd) {
+        if (projectCwd === undefined || projectCwd === '')
+            return false;
+        return this.projectTables.has(join(projectCwd));
+    }
     /**
      * 按工作区 cwd 取 project 表（懒打开 + 缓存）。无 cwd（未选工作区）
      * 返回 undefined——调用方（工具/面板）按此跳过 project 部分。
+     *
+     * **打开是异步的，调用方却会并发**：预热是 fire-and-forget，注入路径、工具路径、
+     * 面板路径各来一次。底层 unit 句柄只允许一个，两次并发打开会让后到者以
+     * `unit '…' is already open; a unit has exactly one live handle` 失败——而调用方
+     * 普遍把预热失败当无碍吞掉，于是表现为「这一轮工作区记忆缺席」。所以这里复用
+     * 进行中的那次打开。
      */
     async projectTableFor(projectCwd) {
         if (projectCwd === undefined || projectCwd === '')
@@ -222,6 +239,20 @@ export class MemoryEngine extends Service {
         const cached = this.projectTables.get(key);
         if (cached !== undefined)
             return cached;
+        const inFlight = this.projectOpenings.get(key);
+        if (inFlight !== undefined)
+            return await inFlight;
+        const opening = this.openProjectTable(key);
+        this.projectOpenings.set(key, opening);
+        try {
+            return await opening;
+        }
+        finally {
+            this.projectOpenings.delete(key);
+        }
+    }
+    /** {@link projectTableFor} 的实际打开步骤；并发去重由调用方负责。 */
+    async openProjectTable(key) {
         const backendName = this.projectBackendName(key);
         // 0.5.2：旧实现 domain 名多一层 memory_project_ 前缀（文件名双重前缀，
         // 且 unit 文件头 name 同为旧名）。打开前统一迁移到规范名：
@@ -271,6 +302,9 @@ export class MemoryEngine extends Service {
      * 「放弃内存缓存」这条语义不变，改变的只是「重读完别忘了装回去」。
      */
     async reload() {
+        // 进行中的打开先落地：否则它们会在下面的 clear 之后把表塞回已清空的映射，
+        // 留下「表在映射里但 facility 已关」的半死状态。
+        await Promise.allSettled([...this.projectOpenings.values()]);
         const opened = [...this.projectTables.keys()];
         await this.facility?.closeAll();
         for (const facility of this.projectFacilities.values())
@@ -383,13 +417,16 @@ export class MemoryEngine extends Service {
         const block = {
             namespace,
             status: verdict.quarantined ? 'suggested' : 'approved',
-            injected: false,
+            // 常驻注入（2026-09-18）：显式给值即接管；隔离内容一律不注入
+            injected: verdict.quarantined ? false : input.injected ?? false,
             content: input.content,
             keywords: (input.keywords ?? []).map(keyword => keyword.toLowerCase()),
             createdAt: now,
             updatedAt: now,
             // ⑧ 来源（2026-09-15）：缺省 'agent'——写入这条记忆的就是主模型
             source: input.source ?? 'agent',
+            // 显式指定注入即接管：此后既不被自动降级，也不被自动升级（同 setInjected，2026-09-18）
+            ...input.injected === undefined ? {} : { injectedAuto: false },
             // 有效性锚点（可选）：值变了这条记忆会被标 stale，不再被当成仍然正确
             ...input.anchor === undefined ? {} : { anchor: input.anchor },
             ...verdict.quarantined
@@ -946,8 +983,11 @@ export class MemoryEngine extends Service {
         throw new Error(`cannot set status of unknown memory '${id}'`);
     }
     /**
-     * 注入维度开关（0.3.0）：只改 injected，不动审核状态。供 UI 面板
-     * 「常驻注入」开关调用（remote.setInjected）。
+     * 注入维度开关（0.3.0）：只改 injected，不动审核状态。供 UI 面板「常驻注入」开关调用
+     * （remote.setInjected）。2026-09-18 起模型侧有等价路径——`memory_save` / `memory_update`
+     * 的 `injected` 参数，经 {@link remember} / {@link update} 写同一套 `injectedAuto: false`
+     * 语义。差异只在越界处理：本方法对隔离记录**抛错**（用户明确要开，该被告知），
+     * 而写入/更新路径**静默降级为不注入**（那是顺带设置，不该中断整次写入）。
      */
     async setInjected(id, injected, projectCwd) {
         return this.writeScope(projectCwd, () => this.setInjectedInner(id, injected, projectCwd));
@@ -991,9 +1031,10 @@ export class MemoryEngine extends Service {
         return record;
     }
     /**
-     * 修改一条记忆的内容/关键词（0.3.1 整理记忆用）。2026-09-15 起：改动**不再**
-     * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态；
-     * `injected` 保留原值。若新内容命中危险规则则转为隔离（与写入路径同一判定）。
+     * 修改一条记忆的内容/关键词/注入位（0.3.1 整理记忆用）。2026-09-15 起：改动**不再**
+     * 退回待审核——静默机制下记忆由系统与模型自行维护，更新即保持原有审核状态。2026-09-18
+     * 起可改 `injected`：**省略则保留原值**（连 `injectedAuto` 一起不动），给值即接管。若新
+     * 内容命中危险规则则转为隔离（与写入路径同一判定），并连带撤下注入。
      */
     async update(id, patch, projectCwd) {
         return this.writeScope(projectCwd, () => this.updateInner(id, patch, projectCwd));
@@ -1007,11 +1048,16 @@ export class MemoryEngine extends Service {
                 ? block.keywords
                 : patch.keywords.map(keyword => keyword.toLowerCase());
             const verdict = detectSensitive(content, ...keywords);
+            // 命中危险规则：退回 suggested（不注入）+ 隔离（不检索）双保险；否则保持原状态
+            const status = verdict.quarantined ? 'suggested' : normalized.status;
+            // 常驻注入（2026-09-18）：显式给值即接管；未审核或已隔离一律不注入（与自动升级同一门槛）
+            const injected = status === 'approved' ? patch.injected ?? normalized.injected : false;
             return {
                 ...block,
-                // 命中危险规则：退回 suggested（不注入）+ 隔离（不检索）双保险；否则保持原状态
-                status: verdict.quarantined ? 'suggested' : normalized.status,
-                injected: normalized.injected,
+                status,
+                injected,
+                // 显式改注入即视为有意决定：此后不受自动升降影响（省略时连 injectedAuto 一起保持）
+                ...patch.injected === undefined ? {} : { injectedAuto: false },
                 ...verdict.quarantined
                     ? { quarantined: true, ...verdict.reason === undefined ? {} : { quarantineReason: verdict.reason } }
                     : { quarantined: false, quarantineReason: undefined },
@@ -1020,13 +1066,22 @@ export class MemoryEngine extends Service {
                 updatedAt: Date.now(),
             };
         };
+        // 注入位变化单独发一条事件：客户端与面板据此刷新「常驻」列，只发 status 会漏掉它
+        const publish = (previous, updated) => {
+            const record = toRecord(id, updated);
+            this.ctx.emit('memory/changed', { operation: 'status', id, status: normalizeBlock(updated).status });
+            const wasInjected = normalizeBlock(previous).injected;
+            const isInjected = normalizeBlock(updated).injected;
+            if (isInjected !== wasInjected) {
+                this.ctx.emit('memory/changed', { operation: 'injected', id, injected: isInjected });
+            }
+            return record;
+        };
         const global = this.requireTable('global').get(id);
         if (global !== undefined) {
             const updated = applyPatch(global);
             await this.requireTable('global').put(id, updated);
-            const record = toRecord(id, updated);
-            this.ctx.emit('memory/changed', { operation: 'status', id, status: normalizeBlock(updated).status });
-            return record;
+            return publish(global, updated);
         }
         const project = await this.projectTableFor(projectCwd);
         if (project !== undefined) {
@@ -1034,9 +1089,7 @@ export class MemoryEngine extends Service {
             if (block !== undefined) {
                 const updated = applyPatch(block);
                 await project.put(id, updated);
-                const record = toRecord(id, updated);
-                this.ctx.emit('memory/changed', { operation: 'status', id, status: normalizeBlock(updated).status });
-                return record;
+                return publish(block, updated);
             }
         }
         throw new Error(`cannot update unknown memory '${id}'`);

package/dist/index.js

@@ -159,6 +159,8 @@ export async function apply(ctx, config) {
         order: 49,
         text: SELF_DESCRIPTION,
     });
+    const injectionBudget = config?.injectionBudget ?? DEFAULT_INJECTION_BUDGET;
+    const summaryChars = config?.summaryChars ?? DEFAULT_SUMMARY_CHARS;
     ctx.systemPrompt.context({
         name: 'memory:recall',
         order: 50,
@@ -166,11 +168,34 @@ export async function apply(ctx, config) {
             const cwd = assemblyProjectCwd(assembly);
             if (cwd !== undefined)
                 void memory.ensureProjectOpen(cwd).catch(() => { });
-            const budget = config?.injectionBudget ?? DEFAULT_INJECTION_BUDGET;
-            const summaryChars = config?.summaryChars ?? DEFAULT_SUMMARY_CHARS;
-            return recallText(memory, cwd, budget, summaryChars);
+            return recallText(memory, cwd, injectionBudget, summaryChars);
         },
     });
+    // 上面那条 provider 是**同步**的（`SystemPrompt.context` 的 `text` 类型就是
+    // `string | ((context) => string)`），而工作区表是异步打开的：重启后首次组装时
+    // 它还没打开，工作区记忆会整整缺席一轮（等预热完成，第二轮才回来）。
+    // `system-prompt/assemble` 是异步 waterfall、文档写明「返回值权威」，在这里补一次。
+    //
+    // **不能拿「此刻表是否打开」当作「provider 渲染时表是否打开」的判据**：provider 里那次
+    // 预热的 Promise 可能在 `next()` 的 await 期间就完成了，于是这里看到「已打开」而跳过，
+    // 而 provider 渲染时它还是空的。所以这里总是重渲染一遍——`renderInjection` 是纯函数、
+    // 读的是内存表，代价可忽略；文本没变就原样返回，不动 downstream 看到的对象。
+    ctx.on('system-prompt/assemble', async (assembly, context, next) => {
+        const assembled = await next();
+        const cwd = assemblyProjectCwd(context);
+        if (cwd === undefined || cwd === '')
+            return assembled;
+        if (!memory.projectOpen(cwd))
+            await memory.ensureProjectOpen(cwd).catch(() => undefined);
+        const text = recallText(memory, cwd, injectionBudget, summaryChars);
+        const current = assembled.contexts.find(entry => entry.name === 'memory:recall');
+        if (current === undefined || current.text === text)
+            return assembled;
+        return {
+            ...assembled,
+            contexts: assembled.contexts.map(entry => entry.name === 'memory:recall' ? { ...entry, text } : entry),
+        };
+    });
     // 会话创建即预热对应工作区的 project 表（0.5.1）：让首轮模型请求就
     // 能注入工作区常驻记忆（provider 同步只读已打开的表）。
     // session/created 事件由 dsh-session 提供（可选依赖：无 session 服务
@@ -188,6 +213,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. 多角度关键词（同义词、缩写、中英），否则将来检索不到它。' },
+            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',
                 additionalProperties: false,
@@ -208,6 +234,7 @@ export async function apply(ctx, config) {
                 content: args.content,
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.keywords === undefined ? {} : { keywords: args.keywords },
+                ...args.injected === undefined ? {} : { injected: args.injected },
                 // 参数已由 tool schema 校验，这里的窄化只为过类型
                 ...args.anchor === undefined
                     ? {}
@@ -406,11 +433,12 @@ export async function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'memory_update',
-        description: 'Update the content or keywords of one stored memory (e.g. correcting stale facts). The record keeps its review status and injection switch; content that looks like a credential quarantines it instead. 修改一条记忆的内容或关键词（如修正过时信息）。改动后记忆保持原有审核状态与注入开关；若新内容命中危险规则则转为隔离。',
+        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. 修改一条记忆的内容、关键词或常驻注入开关（如修正过时信息）。改动后记忆保持原有审核状态；若新内容命中危险规则则转为隔离。',
         parameters: {
             id: { type: 'string', required: true, description: 'Exact memory id from memory_list. 记忆 id（来自 memory_list）.' },
             content: { type: 'string', description: 'New content; omit to keep current. 新内容；省略则保留现有内容.' },
             keywords: { type: 'array', items: { type: 'string' }, description: 'New keywords; omit to keep current. 新关键词；省略则保留现有.' },
+            injected: { type: 'boolean', description: 'Set or clear the persistent-injection switch; omit to keep the current value. Setting it records a deliberate decision — the memory stops being auto-promoted or auto-demoted. See memory_save for what deserves residency. 设置或清除常驻注入开关；省略则保持原值。给值即视为有意决定——此后不受自动升降影响。何时该常驻见 memory_save。' },
         },
         output: {
             schema: RECORD_SCHEMA,
@@ -420,6 +448,7 @@ export async function apply(ctx, config) {
             return memory.update(args.id, {
                 ...args.content === undefined ? {} : { content: args.content },
                 ...args.keywords === undefined ? {} : { keywords: args.keywords },
+                ...args.injected === undefined ? {} : { injected: args.injected },
             }, execProjectCwd(exec)).then(recordValue);
         },
         presentCall: args => present('Update memory', 'other', args.id),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.7.2",
+  "version": "0.8.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": {