@max-null/dsh-memory 0.16.0 → 0.18.0

package/README.md

@@ -116,7 +116,12 @@ md 文件是唯一事实源（`~/.dsh/prompt-library/*.md` 为 global；`<worksp
 ```
 模型 memory_save     →  status: approved，立即生效；命中密钥/凭据规则则隔离（不进检索也不进注入）
                         给 injected 则同时钉住常驻（0.8.0），不受自动规则影响
+                        钉成常驻时返回 `resident`（total / injected / omitted / budget）——
+                        钉的那一刻就知道挤掉了几条，不必等下一轮的出局诊断行
 memory_search        →  关键词/语义召回（只搜记忆；模板走 prompt_search 通道，不会混进候选池）
+                        默认最多返回 20 条，`limit: 0` 取消上限；条数等于 limit 时可能还有更多
+                        命中记账只记 BM25 前 5 名——`hitCount` 是"排前"的信号，不是"被检索到"的面；
+                        一次查询的真实命中数看 `query-log.json` 的 `hits` 字段
 人（面板 / 开关）     →  钉住 / 删除 / 放行隔离记录 / 回滚
 memory_forget        →  随时删除（删除始终是人的动作）
 ```

package/dist/index.js

@@ -99,6 +99,38 @@ const HIT_SCHEMA = {
         score: { type: 'number', required: true },
     },
 };
+/**
+ * `memory_save` / `memory_update` 的输出：记录本体 +（操作后仍是常驻时）预算占用快照。
+ *
+ * 单列一份而不往 {@link RECORD_SCHEMA} 里加：`memory_list` 一次返回全库，每条都带
+ * 一份占用快照既冗余，也与「这条记录本身」无关。预算快照只在**钉入/仍常驻**时出现，
+ * 因为那正是「挤掉别人」这个决定发生的那一刻——钉完再等下一轮的出局诊断行，人已经
+ * 想不起来是哪一次钉入造成的。
+ */
+const SAVED_RECORD_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        ...RECORD_SCHEMA.properties,
+        resident: {
+            type: 'object',
+            additionalProperties: false,
+            description: '钉入之后的常驻注入占用（仅当该记录为常驻时出现）：total 候选条数、injected 本轮实际进场、omitted 被预算挤出、budget 字符预算。',
+            properties: {
+                total: { type: 'number', required: true },
+                injected: { type: 'number', required: true },
+                omitted: { type: 'number', required: true },
+                budget: { type: 'number' },
+            },
+        },
+    },
+};
+/**
+ * `memory_search` 的默认返回上限（0 = 不限）。宽查询会命中大半个库（本机 279 条库实测
+ * 命中面 35%–84%），返回体随库线性增长；20 条仍覆盖"有答案价值"的部分，20 名之后
+ * 分数已趋同（设计依据见 docs/设计/2026-10-21-memory-search-结果截断-设计方案.md）。
+ */
+const DEFAULT_SEARCH_LIMIT = 20;
 /**
  * 体检报告的输出（0.12.0）：四类清单一律只读。`summary` 与注入行同量级，直接念给人听
  * 不失真——这个工具的主要用法就是「你问起时我念给你看」。
@@ -278,6 +310,21 @@ const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and pr
     + 'When the library grows, call memory_sweep for a read-only health check (stale records with reasons, '
     + 'long-unused ones, candidates that keep being retrieved without being pinned, and budget usage). '
     + '库变大之后用 memory_sweep 做只读体检——失效记录（带原因）、久未命中、被反复检索却未常驻的候选、以及预算占用。';
+/**
+ * 钉入常驻后的预算占用快照（`memory_save` / `memory_update` 输出用）。刻意复用注入侧的
+ * `renderInjection`：两处各算一套的话，「工具里显示的占用」与「下一轮实际注入」会给出
+ * 不同的数字，而人恰恰是拿前者的数字去判断要不要钉的。
+ */
+function residentUsage(memory, projectCwd, budget, summaryChars) {
+    const records = memory.recallRecords(projectCwd);
+    const rendered = renderInjection(records, budget, summaryChars);
+    return {
+        total: records.length,
+        injected: rendered.lines.length,
+        omitted: rendered.omitted,
+        ...rendered.budget === null ? {} : { budget: rendered.budget },
+    };
+}
 // 0.5.1：`memory:recall` provider 可经 AssembleContext.agent 拿到当前会话
 // 的 header.cwd——注入 = global + 当前会话工作区的 approved+injected
 // （0.3.4 起工作区记忆就按会话 cwd 路由；provider 是同步回调，只读已
@@ -429,10 +476,11 @@ export async function apply(ctx, config) {
             },
         },
         output: {
-            schema: RECORD_SCHEMA,
+            schema: SAVED_RECORD_SCHEMA,
             render: (_args, value) => renderJson(value),
         },
         execute(args, exec) {
+            const cwd = execProjectCwd(exec);
             return memory.remember({
                 content: args.content,
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
@@ -442,7 +490,14 @@ export async function apply(ctx, config) {
                 ...args.anchor === undefined
                     ? {}
                     : { anchor: args.anchor },
-            }, execProjectCwd(exec)).then(recordValue);
+            }, cwd).then(record => {
+                const value = recordValue(record);
+                // 钉常驻的那一刻就把「挤掉了几条」交给人看：等到下一轮的出局诊断行，
+                // 人已经想不起来是哪一次钉入造成的。
+                return record.injected
+                    ? { ...value, resident: residentUsage(memory, cwd, injectionBudget, summaryChars) }
+                    : value;
+            });
         },
         presentCall: args => present('Save memory', 'other', args.content),
     }));
@@ -476,23 +531,28 @@ export async function apply(ctx, config) {
     }));
     ctx.tools.register(defineTool({
         name: registered('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. Returns at most `limit` hits (default 20; 0 = no limit) — when the count equals limit there may be more. Narrow multi-word queries rank far better than one common token. 按关键词检索记忆（中文 2-gram + 关键词加权；配置嵌入时含语义融合；含待审核条目，被隔离的除外）。最多返回 limit 条（默认 20；0 = 不限），条数等于 limit 时可能还有更多；多词窄查询比单个常用词排序好得多。',
         parameters: {
             query: { type: 'string', required: true, description: 'Keyword query. 关键词查询.' },
             namespace: { type: 'string', enum: ['global', 'project'], description: 'Restrict to one namespace. 限定单个命名空间.' },
             status: { type: 'string', enum: ['suggested', 'approved'], description: 'Restrict to one review status. 限定审核状态.' },
             kind: { type: 'string', enum: ['fact', 'prompt'], description: 'Restrict by record kind — fact (memories, default) or prompt (templates; use prompt_search instead). 按记录类别过滤：fact=记忆（默认）/ prompt=模板（模板请用 prompt_search）.' },
+            limit: { type: 'integer', default: DEFAULT_SEARCH_LIMIT, description: 'Maximum hits to return (default 20; 0 = no limit; negative falls back to 20). 最多返回条数（默认 20；0 = 不限；负数按 20）.' },
         },
         output: {
             schema: { type: 'array', items: HIT_SCHEMA },
             render: (_args, value) => renderJson(value),
         },
         execute(args, exec) {
+            // 截断只在工具层：`memory.search()` 必须保持「全部正分命中」的语义，
+            // prompt_search 依赖它的全量结果给模板排序（本文件下方 prompt_search 的 hitIds）。
+            const requested = args.limit ?? DEFAULT_SEARCH_LIMIT;
+            const limit = requested < 0 ? DEFAULT_SEARCH_LIMIT : requested;
             return memory.search(args.query, {
                 ...args.namespace === undefined ? {} : { namespace: args.namespace },
                 ...args.status === undefined ? {} : { status: args.status },
                 ...args.kind === undefined ? {} : { kind: args.kind },
-            }, execProjectCwd(exec)).then(hits => hits.map(hitValue));
+            }, execProjectCwd(exec)).then(hits => (limit === 0 ? hits : hits.slice(0, limit)).map(hitValue));
         },
         presentCall: args => present('Search memory', 'read', args.query),
     }));
@@ -693,18 +753,25 @@ export async function apply(ctx, config) {
             },
         },
         output: {
-            schema: RECORD_SCHEMA,
+            schema: SAVED_RECORD_SCHEMA,
             render: (_args, value) => renderJson(value),
         },
         execute(args, exec) {
             const cwd = execProjectCwd(exec);
             const id = args.id;
+            const settle = (record) => {
+                const value = recordValue(record);
+                // 改内容也会改变注入占用的字符数：只要这条仍是常驻，就把占用一起交回去。
+                return record.injected
+                    ? { ...value, resident: residentUsage(memory, cwd, injectionBudget, summaryChars) }
+                    : value;
+            };
             // 三种动作互斥，按 retract > supersedes > update 的次序取第一个（与工具描述一致）：
             // 前两个是「标状态」，第三个才是「改内容」。同时给多个时以更重的动作为准。
             if (args.retract !== undefined)
-                return memory.retract(id, args.retract, cwd).then(recordValue);
+                return memory.retract(id, args.retract, cwd).then(settle);
             if (args.supersedes !== undefined)
-                return memory.supersede(id, args.supersedes, cwd).then(recordValue);
+                return memory.supersede(id, args.supersedes, cwd).then(settle);
             return memory.update(id, {
                 ...args.content === undefined ? {} : { content: args.content },
                 ...args.keywords === undefined ? {} : { keywords: args.keywords },
@@ -713,7 +780,7 @@ export async function apply(ctx, config) {
                 ...args.anchor === undefined
                     ? {}
                     : { anchor: args.anchor },
-            }, cwd).then(recordValue);
+            }, cwd).then(settle);
         },
         presentCall: args => present('Update memory', 'other', args.id),
     }));

package/package.json

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