@max-null/dsh-memory 0.6.1 → 0.7.1

package/dist/index.js

@@ -28,6 +28,10 @@ const RECORD_SCHEMA = {
         createdAt: { type: 'number', required: true },
         updatedAt: { type: 'number', required: true },
         lastUsedAt: { type: 'number' },
+        stale: { type: 'boolean', description: '内容可能已过时（锚点失效）：据此行动前先核对现状，核对后用 memory_update 修正或刷新。' },
+        staleReason: { type: 'string' },
+        hitCount: { type: 'number' },
+        quarantined: { type: 'boolean' },
     },
 };
 const HIT_SCHEMA = {
@@ -64,6 +68,10 @@ function recordValue(record) {
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
         ...record.lastUsedAt === undefined ? {} : { lastUsedAt: record.lastUsedAt },
+        ...record.stale === undefined ? {} : { stale: record.stale },
+        ...record.staleReason === undefined ? {} : { staleReason: record.staleReason },
+        hitCount: record.hitCount,
+        ...record.quarantined === true ? { quarantined: true } : {},
     };
 }
 function hitValue(hit) {
@@ -86,13 +94,15 @@ function promptValue(record) {
 // 采用中英双语都写、模型自取——设计文档「风险与注意」）。
 const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and project conventions. '
     + '记忆工具用于跨会话的偏好、习惯与项目约定。'
-    + 'memory_save always records a suggestion (`suggested`) and never makes it effective itself — '
-    + 'a human approves it. memory_save 永远只写入建议（`suggested`），不会自行生效——需人工审核通过。'
+    + '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`）控制。'
     + 'When earlier context may be relevant, call memory_search to recall it — reviewable memories '
-    + '(`suggested`) are searchable too. 相关历史上下文可用 memory_search 检索——待审核的记忆也可检索。'
+    + '相关历史上下文可用 memory_search 检索；被隔离的记录不进检索。'
     + 'Every memory is plaintext and inspectable with memory_list; memory_forget removes one. '
     + '所有记忆均为明文，可用 memory_list 查看；memory_forget 删除一条。'
     + 'Approved + injected memories of the CURRENT session workspace are every-turn injected too. '
@@ -173,11 +183,21 @@ export async function apply(ctx, config) {
     });
     ctx.tools.register(defineTool({
         name: 'memory_save',
-        description: 'Record one cross-session memory as a suggestion. It never becomes effective until a human confirms it; the model must not present a suggestion as confirmed.',
+        description: 'Save one cross-session memory. It takes effect immediately; credential-like content is quarantined instead. Record durable preferences, corrections and reusable conclusions — not transient state, guesses, or facts readable from the repo (record where to look instead). 保存一条跨会话记忆：写入即生效；命中密钥/凭据规则的写入会被隔离。只记长期偏好、纠正与可复用结论——不记临时状态、推测、或能从仓库读到的事实（那类记「去哪查」）。',
         parameters: {
             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.' },
+            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. 多角度关键词（同义词、缩写、中英），否则将来检索不到它。' },
+            anchor: {
+                type: 'object',
+                additionalProperties: false,
+                description: 'Optional validity anchor: bind this memory to a probeable environment value so it auto-expires when that value changes. Use only for facts that depend on the environment (tool behaviour under a specific version, config decided by an env var). 可选锚点：把记忆绑到可探测的环境值，值变了自动失效。只用于「随环境变化的事实」。',
+                properties: {
+                    kind: { type: 'string', required: true, enum: ['env', 'tool-list', 'self-version'], description: 'env = a named environment variable; tool-list = the available tool set; self-version = this plugin version.' },
+                    name: { type: 'string', description: 'For kind=env: the variable name.' },
+                    value: { type: 'string', required: true, description: 'The value probed at write time.' },
+                },
+            },
         },
         output: {
             schema: RECORD_SCHEMA,
@@ -188,6 +208,10 @@ export async function apply(ctx, config) {
                 content: args.content,
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.keywords === undefined ? {} : { keywords: args.keywords },
+                // 参数已由 tool schema 校验，这里的窄化只为过类型
+                ...args.anchor === undefined
+                    ? {}
+                    : { anchor: args.anchor },
             }, execProjectCwd(exec)).then(recordValue);
         },
         presentCall: args => present('Save memory', 'other', args.content),
@@ -215,7 +239,7 @@ export async function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'memory_search',
-        description: 'Recall stored memories by keyword. Deterministic literal matching — a miss means no stored term matched the query. 按关键词检索记忆（中文 2-gram + 关键词加权；配置嵌入时含语义融合；含待审核条目）。',
+        description: 'Recall stored memories by keyword. Deterministic literal matching — a miss means no stored term matched the query. 按关键词检索记忆（中文 2-gram + 关键词加权；配置嵌入时含语义融合；含待审核条目，被隔离的除外）。',
         parameters: {
             query: { type: 'string', required: true, description: 'Keyword query. 关键词查询.' },
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
@@ -382,7 +406,7 @@ 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 is re-marked `suggested` — the human must review it again before it is approved/injected again. 修改一条记忆的内容或关键词（如修正过时信息）。改动后该记忆重置为待审核（suggested），需人工再次审核；常驻注入开关保留原值（审核通过后恢复）。',
+        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. 修改一条记忆的内容或关键词（如修正过时信息）。改动后记忆保持原有审核状态与注入开关；若新内容命中危险规则则转为隔离。',
         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. 新内容；省略则保留现有内容.' },
@@ -402,7 +426,7 @@ export async function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: 'memory_confirm',
-        description: 'Approve a suggested memory so it is marked human-reviewed (`approved`). Approval does NOT enable persistent injection — whether a memory is injected every turn is a separate human-controlled switch (`injected`). Only call this when the human explicitly asks to approve a memory; never self-promote a suggestion. 将待审核记忆标记为已审核（approved）。审核通过不改变注入状态——是否每轮常驻注入由独立的人工开关（injected）控制。仅在用户明确要求审核某条记忆时调用；模型不得自我提升。',
+        description: 'Release a quarantined memory: marks it human-reviewed (`approved`) and clears its quarantine. Under the silent mechanism ordinary writes already take effect by themselves, so call this only when the human explicitly asks to release a quarantined memory. 放行一条被隔离的记忆：标记为已审核并解除隔离。静默机制下普通写入已自行生效，因此仅在用户明确要求放行隔离记忆时调用。',
         parameters: {
             id: { type: 'string', required: true, description: 'Exact memory id from memory_list. 记忆 id（来自 memory_list）.' },
         },

package/dist/quarantine.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 危险内容硬拦（2026-09-15 静默记忆机制第一版）：写入路径上的确定性规则检测。
+ *
+ * 这一类判断不交给模型：凭据一旦进了记忆库，检索就会把它交给模型，而模型无法
+ * 可靠判断「这段是不是密钥」。所以用固定规则拦下，命中即隔离（不注入、不检索），
+ * 由人显式放行或删除——这是设计文档里唯一不由 LLM 承担的判断。
+ *
+ * 误报的代价（一条正常记忆被隔离）小于漏报的代价（密钥进入每轮上下文），
+ * 因此规则偏保守：宁可多拦，且放行只需一次人工动作。
+ */
+/** 隔离判定的结果。 */
+export interface QuarantineVerdict {
+    /** 是否应隔离。 */
+    quarantined: boolean;
+    /** 命中的规则名（诊断与面板展示用）；未命中时为 undefined。 */
+    reason?: string;
+}
+/**
+ * 判定一段文本是否应被隔离。
+ *
+ * @param parts - 参与判定的文本片段（正文与关键词都算：关键词里塞密钥同样会外泄）。
+ * @returns 命中任意规则即 `quarantined: true`，并给出规则名。
+ */
+export declare function detectSensitive(...parts: readonly string[]): QuarantineVerdict;

package/dist/quarantine.js

@@ -0,0 +1,43 @@
+/**
+ * 危险内容硬拦（2026-09-15 静默记忆机制第一版）：写入路径上的确定性规则检测。
+ *
+ * 这一类判断不交给模型：凭据一旦进了记忆库，检索就会把它交给模型，而模型无法
+ * 可靠判断「这段是不是密钥」。所以用固定规则拦下，命中即隔离（不注入、不检索），
+ * 由人显式放行或删除——这是设计文档里唯一不由 LLM 承担的判断。
+ *
+ * 误报的代价（一条正常记忆被隔离）小于漏报的代价（密钥进入每轮上下文），
+ * 因此规则偏保守：宁可多拦，且放行只需一次人工动作。
+ */
+/** 单条规则：名字进诊断，正则做判定。命中任意一条即隔离。 */
+const RULES = [
+    // 常见平台的密钥前缀
+    { name: 'api-key-prefix', pattern: /\b(?:sk|pk|rk)-[A-Za-z0-9_-]{16,}\b/ },
+    { name: 'aws-access-key', pattern: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/ },
+    { name: 'github-token', pattern: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/ },
+    { name: 'slack-token', pattern: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
+    // 私钥块
+    { name: 'private-key-block', pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
+    // 赋值式秘密：password/token/api_key = 值
+    { name: 'assigned-secret', pattern: /\b(?:password|passwd|pwd|secret|token|api[_-]?key|access[_-]?key)\b\s*[:=]\s*\S{6,}/i },
+    // 认证头
+    { name: 'authorization-header', pattern: /\bBearer\s+[A-Za-z0-9._-]{20,}/ },
+    // 带口令的连接串（scheme://user:pass@host）
+    { name: 'credential-url', pattern: /[a-z][a-z0-9+.-]*:\/\/[^\s:/@]+:[^\s:/@]+@/i },
+];
+/**
+ * 判定一段文本是否应被隔离。
+ *
+ * @param parts - 参与判定的文本片段（正文与关键词都算：关键词里塞密钥同样会外泄）。
+ * @returns 命中任意规则即 `quarantined: true`，并给出规则名。
+ */
+export function detectSensitive(...parts) {
+    const text = parts.filter(part => part !== '').join('\n');
+    if (text === '')
+        return { quarantined: false };
+    for (const rule of RULES) {
+        // 规则都是无状态正则（无 /g），test 不会受 lastIndex 影响
+        if (rule.pattern.test(text))
+            return { quarantined: true, reason: rule.name };
+    }
+    return { quarantined: false };
+}

package/dist/query-log.d.ts

@@ -0,0 +1,155 @@
+/**
+ * 查询日志与影响力统计（2026-09-15 静默记忆机制，设计文档 §三.5 / §六.6）。
+ *
+ * 漏检不产生任何事件：「该用却搜不到」与「真没用了」在旧信号里长得一样（反例 4），
+ * 照使用信号沉底会误杀。所以插件必须自己观察自己——记录每次检索的查询与命中数
+ * （有界保留），事后低频反查「这些查询本该命中谁」；同一份数据反过来按**来源**聚合
+ * 影响力（写入量 / 命中数），作为「某来源写入多、命中 0」这类关闭信号的判据（反例 5）。
+ *
+ * 纯文件读写 + 纯函数，不引入依赖。日志是检索路径上的**旁路**：写失败绝不能影响
+ * 检索结果，因此文件读写各自容错，抛错只由调用方处理（引擎侧一律 try/catch）。
+ */
+/** 有界保留条数（设计文档 §六.6「有界保留」，建议最近 200 条）。 */
+export declare const QUERY_LOG_LIMIT = 200;
+/** 单条查询文本的截断上限（字符）——日志只用于反查，不需要全文。 */
+export declare const QUERY_TEXT_LIMIT = 120;
+/** 单次反查报告的查询个数上限（低频反查：一次看一小批就够）。 */
+export declare const GAP_QUERY_LIMIT = 10;
+/** 每个查询给出的候选上限。 */
+export declare const GAP_CANDIDATE_LIMIT = 5;
+/** 记忆来源：'agent' = 主模型写入；'human' = 人工写入。 */
+export type MemorySource = 'agent' | 'human';
+/** 聚合时无来源字段的旧记录归入此组（不猜测，保留「未知历史来源」）。 */
+export declare const UNKNOWN_SOURCE = "unknown";
+/** One recorded `memory_search` call: the query text, how many records it hit, and when. */
+export interface QueryLogEntry {
+    /** 查询文本（已折叠空白并截断）。 */
+    query: string;
+    /** 本次检索的命中条数；0 = 空命中，正是反查的入口。 */
+    hits: number;
+    /** 记录时间（epoch ms）。 */
+    at: number;
+}
+/** 一次查询日志写入（`at` 缺省 = 现在）。 */
+export interface QueryLogInput {
+    query: string;
+    hits: number;
+    at?: number;
+}
+/** 日志文件位置与有界条数。 */
+export interface QueryLogOptions {
+    /** 日志文件绝对路径（与 memory.json 同目录）。 */
+    path: string;
+    /** 有界保留条数；缺省 {@link QUERY_LOG_LIMIT}。 */
+    limit?: number;
+    /** 时钟（测试注入用）；缺省 Date.now。 */
+    now?: () => number;
+}
+/** 一个空命中查询在日志里的累计形态（反查的输入）。 */
+export interface QueryGapSummary {
+    query: string;
+    /** 该查询空命中的次数。 */
+    count: number;
+    /** 最近一次出现的时间。 */
+    lastAt: number;
+}
+/** 查询日志的聚合摘要（纯统计，不读文件）。 */
+export interface QueryLogSummary {
+    /** 日志条数。 */
+    total: number;
+    /** 空命中（hits === 0）的条数。 */
+    misses: number;
+    /** 去重后的空命中查询，最近出现的在前（最多 `limit` 个）。 */
+    gaps: QueryGapSummary[];
+    /** 最近一条日志的时间（0 = 空日志）。 */
+    lastAt: number;
+}
+/** 反查候选：一条可能与查询相关、但检索当时没有命中的记忆。 */
+export interface GapCandidate {
+    /** 记录 id（字符串形态）。 */
+    id: string;
+    /** 记录正文（调用方按需截断）。 */
+    content: string;
+    /** 精确词元命中数：> 0 表示「现在重搜就该命中」。 */
+    exact: number;
+    /** 前缀近似命中的查询词元（如 vue3 ↔ vue）。 */
+    relaxed: string[];
+}
+/** 影响力统计的输入：一条现存记录的来源与影响面。 */
+export interface SourceTallyInput {
+    /** 来源；缺省 = 旧记录（无来源字段）。 */
+    source?: MemorySource;
+    /** 被检索命中的累计次数。 */
+    hitCount: number;
+    /** 是否常驻注入（真正改变每轮决策的那部分）。 */
+    injected: boolean;
+}
+/** 按来源聚合的影响力（设计文档 §六.6 的三个数里的前两个 + 注入面）。 */
+export interface SourceStat {
+    source: MemorySource | typeof UNKNOWN_SOURCE;
+    /** 写入量：现存的该来源记录数。 */
+    writes: number;
+    /** 被检索命中数：现存记录 `hitCount` 合计。 */
+    hits: number;
+    /** 常驻注入条数。 */
+    injected: number;
+}
+/** 查询文本规范化（纯函数）：折叠空白 + 截断。 */
+export declare function normalizeQuery(query: string, limit?: number): string;
+/**
+ * 容错解析（纯函数）：坏 JSON / 坏结构 → 空日志（绝不抛）。
+ * 接受两种形态：裸数组，以及 `{ queries: [...] }`（本模块写出的形态）。
+ */
+export declare function parseQueryLog(text: string): QueryLogEntry[];
+/** 序列化（纯函数）：2 空格缩进 + 尾换行，与仓库其他存储文件一致。 */
+export declare function serializeQueryLog(log: readonly QueryLogEntry[]): string;
+/** 纯函数：追加一条并截到上限（最新的在末尾；返回新数组，不改入参）。 */
+export declare function appendQueryEntry(log: readonly QueryLogEntry[], input: QueryLogInput, limit?: number): QueryLogEntry[];
+/** 聚合摘要（纯函数）：空命中计数 + 去重查询列表（反查入口）。 */
+export declare function summarizeQueryLog(log: readonly QueryLogEntry[], limit?: number): QueryLogSummary;
+/**
+ * 反查排序（纯函数）：把一个空命中的查询与当前记忆库对起来，找出「本应命中」的候选。
+ *
+ * 两档匹配，都只看字面，因此结论可解释：
+ * ①**精确词元**（与检索同一套分词）：命中即代表现在重搜会命中——日志里却是 0，
+ *   说明那条记忆是查询之后才写入的（或当时被过滤挡掉了）；
+ * ②**前缀近似**（长度 ≥ {@link RELAXED_MIN_CHARS} 且互为前缀）：覆盖「vue3 ↔ vue」
+ *   这类标识符/版本号变体——检索按整词比对必然漏，而它往往正是该补 keywords 的那条。
+ *
+ * 两档都无候选 = 知识缺口（这类知识库里确实还没有），本身也是有用信息。
+ */
+export declare function rankGapCandidates(query: string, docs: readonly {
+    id: string;
+    body: string;
+    tags?: string;
+}[], limit?: number): GapCandidate[];
+/**
+ * 按来源聚合影响力（纯函数，设计文档 §六.6 / 反例 5）：写入量与被检索命中数。
+ *
+ * **第三个数的取舍**：设计文档要的「被人工删除数」在这里没有，原因是它无法归属——
+ * 来源字段长在记录上，`memory_forget` 删除记录时来源一起消失，查询日志也不携带来源，
+ * 于是删除量只能数出总数、数不出是谁写的。按「日志里曾经的 id 现已不存在」做差异法
+ * 同样归不到来源（能归的只有还活着的记录，活着的没被删）。要拿到它需要在 `forget()`
+ * 里追加带来源的删除墓碑，第一版不做：先攒前两个数，等真需要判 habit / guardian 时再补。
+ */
+export declare function summarizeSources(records: readonly SourceTallyInput[]): SourceStat[];
+/**
+ * 有界查询日志（文件 + 上面的纯函数）。每次追加都是读-改-写整个文件：单进程内由
+ * 事件循环串行化，多进程并发（两个 DSH 实例）可能丢条目——日志是旁路证据，可接受。
+ */
+export declare class QueryLog {
+    private readonly options;
+    private readonly limit;
+    private readonly now;
+    constructor(options: QueryLogOptions);
+    /** 读日志；文件缺失或损坏 → 空数组（绝不抛）。 */
+    readLog(): QueryLogEntry[];
+    /**
+     * 追加一条（有界：越界丢最旧）。**写失败会抛**——由调用方兜住：
+     * 检索路径上的日志失败绝不能改变检索结果。
+     * @returns 写入后的完整日志（调用方可直接用，不必重读）。
+     */
+    appendQuery(input: QueryLogInput): QueryLogEntry[];
+    /** 聚合摘要（空命中与去重查询列表）。 */
+    summarize(limit?: number): QueryLogSummary;
+}

package/dist/query-log.js

@@ -0,0 +1,220 @@
+/**
+ * 查询日志与影响力统计（2026-09-15 静默记忆机制，设计文档 §三.5 / §六.6）。
+ *
+ * 漏检不产生任何事件：「该用却搜不到」与「真没用了」在旧信号里长得一样（反例 4），
+ * 照使用信号沉底会误杀。所以插件必须自己观察自己——记录每次检索的查询与命中数
+ * （有界保留），事后低频反查「这些查询本该命中谁」；同一份数据反过来按**来源**聚合
+ * 影响力（写入量 / 命中数），作为「某来源写入多、命中 0」这类关闭信号的判据（反例 5）。
+ *
+ * 纯文件读写 + 纯函数，不引入依赖。日志是检索路径上的**旁路**：写失败绝不能影响
+ * 检索结果，因此文件读写各自容错，抛错只由调用方处理（引擎侧一律 try/catch）。
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { tokenize } from "./bm25.js";
+/** 有界保留条数（设计文档 §六.6「有界保留」，建议最近 200 条）。 */
+export const QUERY_LOG_LIMIT = 200;
+/** 单条查询文本的截断上限（字符）——日志只用于反查，不需要全文。 */
+export const QUERY_TEXT_LIMIT = 120;
+/** 单次反查报告的查询个数上限（低频反查：一次看一小批就够）。 */
+export const GAP_QUERY_LIMIT = 10;
+/** 每个查询给出的候选上限。 */
+export const GAP_CANDIDATE_LIMIT = 5;
+/**
+ * 前缀近似匹配的最短词元长度：太短会连出一片噪声（CJK 单字/双字元长度都不足 3，
+ * 因此这一档实质上只对英文与标识符生效）。
+ */
+const RELAXED_MIN_CHARS = 3;
+/** 聚合时无来源字段的旧记录归入此组（不猜测，保留「未知历史来源」）。 */
+export const UNKNOWN_SOURCE = 'unknown';
+/** 查询文本规范化（纯函数）：折叠空白 + 截断。 */
+export function normalizeQuery(query, limit = QUERY_TEXT_LIMIT) {
+    const collapsed = query.replace(/\s+/g, ' ').trim();
+    return collapsed.length <= limit ? collapsed : collapsed.slice(0, limit);
+}
+/**
+ * 逐条校验（纯函数）：结构不对的条目丢弃——日志是辅助证据，
+ * 一条坏记录不该让整份日志失效。
+ */
+function toEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const entry = value;
+    if (typeof entry.query !== 'string' || entry.query.trim() === '')
+        return undefined;
+    if (typeof entry.hits !== 'number' || !Number.isFinite(entry.hits))
+        return undefined;
+    return {
+        query: normalizeQuery(entry.query),
+        hits: Math.max(0, Math.trunc(entry.hits)),
+        at: typeof entry.at === 'number' && Number.isFinite(entry.at) ? entry.at : 0,
+    };
+}
+/**
+ * 容错解析（纯函数）：坏 JSON / 坏结构 → 空日志（绝不抛）。
+ * 接受两种形态：裸数组，以及 `{ queries: [...] }`（本模块写出的形态）。
+ */
+export function parseQueryLog(text) {
+    let document;
+    try {
+        document = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    let raw;
+    if (Array.isArray(document))
+        raw = document;
+    else if (typeof document === 'object' && document !== null)
+        raw = document.queries;
+    else
+        return [];
+    if (!Array.isArray(raw))
+        return [];
+    return raw.map(toEntry).filter((entry) => entry !== undefined);
+}
+/** 序列化（纯函数）：2 空格缩进 + 尾换行，与仓库其他存储文件一致。 */
+export function serializeQueryLog(log) {
+    return `${JSON.stringify({ queries: log }, null, 2)}\n`;
+}
+/** 纯函数：追加一条并截到上限（最新的在末尾；返回新数组，不改入参）。 */
+export function appendQueryEntry(log, input, limit = QUERY_LOG_LIMIT) {
+    const appended = [...log, {
+            query: normalizeQuery(input.query),
+            hits: Math.max(0, Math.trunc(input.hits)),
+            at: input.at ?? Date.now(),
+        }];
+    const cap = Math.max(0, Math.trunc(limit));
+    return appended.length <= cap ? appended : appended.slice(appended.length - cap);
+}
+/** 聚合摘要（纯函数）：空命中计数 + 去重查询列表（反查入口）。 */
+export function summarizeQueryLog(log, limit = GAP_QUERY_LIMIT) {
+    const byQuery = new Map();
+    let misses = 0;
+    let lastAt = 0;
+    for (const entry of log) {
+        if (entry.at > lastAt)
+            lastAt = entry.at;
+        if (entry.hits > 0)
+            continue;
+        misses += 1;
+        const seen = byQuery.get(entry.query);
+        if (seen === undefined) {
+            byQuery.set(entry.query, { query: entry.query, count: 1, lastAt: entry.at });
+            continue;
+        }
+        seen.count += 1;
+        if (entry.at > seen.lastAt)
+            seen.lastAt = entry.at;
+    }
+    const gaps = [...byQuery.values()]
+        .sort((left, right) => right.lastAt - left.lastAt)
+        .slice(0, Math.max(0, Math.trunc(limit)));
+    return { total: log.length, misses, gaps, lastAt };
+}
+/**
+ * 反查排序（纯函数）：把一个空命中的查询与当前记忆库对起来，找出「本应命中」的候选。
+ *
+ * 两档匹配，都只看字面，因此结论可解释：
+ * ①**精确词元**（与检索同一套分词）：命中即代表现在重搜会命中——日志里却是 0，
+ *   说明那条记忆是查询之后才写入的（或当时被过滤挡掉了）；
+ * ②**前缀近似**（长度 ≥ {@link RELAXED_MIN_CHARS} 且互为前缀）：覆盖「vue3 ↔ vue」
+ *   这类标识符/版本号变体——检索按整词比对必然漏，而它往往正是该补 keywords 的那条。
+ *
+ * 两档都无候选 = 知识缺口（这类知识库里确实还没有），本身也是有用信息。
+ */
+export function rankGapCandidates(query, docs, limit = GAP_CANDIDATE_LIMIT) {
+    const queryTerms = [...new Set(tokenize(query))];
+    if (queryTerms.length === 0)
+        return [];
+    const candidates = [];
+    for (const doc of docs) {
+        const docTerms = new Set(tokenize(doc.tags === undefined ? doc.body : `${doc.body} ${doc.tags}`));
+        const exact = queryTerms.filter(term => docTerms.has(term)).length;
+        const relaxed = [];
+        for (const term of queryTerms) {
+            if (docTerms.has(term) || term.length < RELAXED_MIN_CHARS)
+                continue;
+            for (const candidate of docTerms) {
+                if (candidate.length < RELAXED_MIN_CHARS)
+                    continue;
+                if (candidate.startsWith(term) || term.startsWith(candidate)) {
+                    relaxed.push(term);
+                    break;
+                }
+            }
+        }
+        if (exact === 0 && relaxed.length === 0)
+            continue;
+        candidates.push({ id: doc.id, content: doc.body, exact, relaxed });
+    }
+    return candidates
+        .sort((left, right) => right.exact - left.exact
+        || right.relaxed.length - left.relaxed.length
+        || left.id.localeCompare(right.id))
+        .slice(0, Math.max(0, Math.trunc(limit)));
+}
+/**
+ * 按来源聚合影响力（纯函数，设计文档 §六.6 / 反例 5）：写入量与被检索命中数。
+ *
+ * **第三个数的取舍**：设计文档要的「被人工删除数」在这里没有，原因是它无法归属——
+ * 来源字段长在记录上，`memory_forget` 删除记录时来源一起消失，查询日志也不携带来源，
+ * 于是删除量只能数出总数、数不出是谁写的。按「日志里曾经的 id 现已不存在」做差异法
+ * 同样归不到来源（能归的只有还活着的记录，活着的没被删）。要拿到它需要在 `forget()`
+ * 里追加带来源的删除墓碑，第一版不做：先攒前两个数，等真需要判 habit / guardian 时再补。
+ */
+export function summarizeSources(records) {
+    const stats = new Map();
+    for (const record of records) {
+        const source = record.source ?? UNKNOWN_SOURCE;
+        const stat = stats.get(source) ?? { source, writes: 0, hits: 0, injected: 0 };
+        stat.writes += 1;
+        stat.hits += Math.max(0, Math.trunc(record.hitCount));
+        if (record.injected)
+            stat.injected += 1;
+        stats.set(source, stat);
+    }
+    const order = ['agent', 'human', UNKNOWN_SOURCE];
+    return [...stats.values()]
+        .sort((left, right) => order.indexOf(left.source) - order.indexOf(right.source));
+}
+/**
+ * 有界查询日志（文件 + 上面的纯函数）。每次追加都是读-改-写整个文件：单进程内由
+ * 事件循环串行化，多进程并发（两个 DSH 实例）可能丢条目——日志是旁路证据，可接受。
+ */
+export class QueryLog {
+    options;
+    limit;
+    now;
+    constructor(options) {
+        this.options = options;
+        this.limit = options.limit ?? QUERY_LOG_LIMIT;
+        this.now = options.now ?? Date.now;
+    }
+    /** 读日志；文件缺失或损坏 → 空数组（绝不抛）。 */
+    readLog() {
+        try {
+            if (!existsSync(this.options.path))
+                return [];
+            return parseQueryLog(readFileSync(this.options.path, 'utf8'));
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * 追加一条（有界：越界丢最旧）。**写失败会抛**——由调用方兜住：
+     * 检索路径上的日志失败绝不能改变检索结果。
+     * @returns 写入后的完整日志（调用方可直接用，不必重读）。
+     */
+    appendQuery(input) {
+        const next = appendQueryEntry(this.readLog(), { ...input, at: input.at ?? this.now() }, this.limit);
+        mkdirSync(dirname(this.options.path), { recursive: true });
+        writeFileSync(this.options.path, serializeQueryLog(next));
+        return next;
+    }
+    /** 聚合摘要（空命中与去重查询列表）。 */
+    summarize(limit) {
+        return summarizeQueryLog(this.readLog(), limit);
+    }
+}

package/dist/routes.js

@@ -135,6 +135,8 @@ export function mountMemoryApi(ctx) {
                 ...filter?.namespace !== undefined && typeof filter.namespace === 'string' ? { namespace: filter.namespace } : {},
                 ...filter?.status !== undefined && typeof filter.status === 'string' ? { status: filter.status } : {},
                 ...filter?.injected !== undefined && typeof filter.injected === 'boolean' ? { injected: filter.injected } : {},
+                // 隔离过滤（2026-09-15）：引擎缺省排除隔离记录，面板要显式带 true 才取得到隔离区
+                ...filter?.quarantined !== undefined && typeof filter.quarantined === 'boolean' ? { quarantined: filter.quarantined } : {},
             }, cwdOf(record));
         },
         'reload': async (payload) => {

package/dist/self.d.ts

@@ -1 +1,2 @@
+export declare const SELF_VERSION: string;
 export declare const SELF_DESCRIPTION: string;

package/dist/self.js

@@ -4,7 +4,7 @@
  * 版本号动态读取 package.json（"只跟随 dsh-memory 组件发版变动"）。
  */
 import { createRequire } from 'node:module';
-const SELF_VERSION = (() => {
+export const SELF_VERSION = (() => {
     try {
         // dist/index.js 位于包根 package.json 同级（../package.json）
         const require = createRequire(import.meta.url);
@@ -15,12 +15,16 @@ const SELF_VERSION = (() => {
         return 'unknown';
     }
 })();
-export const SELF_DESCRIPTION = `[记忆系统自述] 当前环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
-    + '工作机制：①记忆以明文 JSON 存储（global→$DSH_HOME/storages、工作区→会话工作区 .dsh/storages 随 git 分享）；'
-    + '②模型写入即 suggested（待审核），仅人工审核（memory_confirm）后才 approved；'
-    + '③每轮注入 system prompt 的 = 「global 的 approved + injected」+「当前会话工作区的 approved + injected」，逐条为单行摘要（内容全文靠 memory_search 检索），并受注入预算限制（超预算按最近更新优先，省略条数在面板「注入预览」可见；常驻注入由用户控制，审核≠注入）；'
-    + '④工作区记忆按会话工作区路由（存储跟随仓库），memory_search 为 BM25 检索（中文 2-gram + 关键词加权，可配置语义融合），可检索任意状态（含待审核条目，可先评估再引用）；'
-    + '⑤修正过时内容用 memory_update（改动重置待审核，注入开关保留）。'
-    + `可用记忆工具共 6 个：memory_save / memory_list / memory_search / memory_confirm / memory_forget / memory_update。`
-    + '使用建议：相关历史上下文先 memory_search 检索再引用；新习惯/约定用 memory_save 写入（落在待审核）。'
-    + '（中/英文同义：This environment has a cross-session memory service; write suggestions via memory_save, retrieve via memory_search, and expect human review before approved.)';
+export const SELF_DESCRIPTION = `[记忆系统自述] 本环境内置跨会话记忆服务（dsh-memory v${SELF_VERSION}）。`
+    + '你有 6 个记忆工具：memory_save / memory_search / memory_list / memory_update / memory_confirm / memory_forget。'
+    + '**何时写入**（不必刻意找机会，遇到下面这些就动手）：'
+    + '① 用户表达长期偏好或约定（「以后都…」「记住…」「我们的规矩是…」）；'
+    + '② 用户纠正了你的做法或理解——把正确结论记下来；'
+    + '③ 得出跨会话仍然有用的结论、路径或坑，而非本次任务的临时细节。'
+    + '**不要记**：临时状态、未经验证的推测、能从代码或文档直接读到的事实（那类记「去哪查」即可）。'
+    + '**怎么写**：一条一件事，并给多角度关键词（同义词、缩写、中英），否则将来检索不到它。'
+    + '**锚点（可选）**：若这条记忆描述的是「随某个环境值变化的事实」（某工具版本下的行为、某环境变量决定的配置），用 anchor 参数把它绑到那个值上——值变了它会自动失效并标 stale，不会再被当成仍然正确。'
+    + '写入即生效（`approved`），人工只在例外时介入；命中密钥/凭据规则的写入会被隔离（不进注入与检索）。'
+    + '每轮注入的是「global + 当前会话工作区」里已生效且开着常驻开关的记忆摘要（受预算限制，超预算按最近更新优先）；全文要靠 memory_search。'
+    + '发现某条记忆与实际不符时用 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.)';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.6.1",
-  "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, human-owned, no embeddings",
+  "version": "0.7.1",
+  "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": {
     "access": "public"
@@ -22,7 +22,9 @@
     "client.js",
     "cordis.patch.yml",
     "README.md",
-    "LICENSE", "docs/shots"],
+    "LICENSE",
+    "docs/shots"
+  ],
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"