@max-null/dsh-memory 0.17.0 → 0.18.0

package/README.md

@@ -116,6 +116,8 @@ 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` 是"排前"的信号，不是"被检索到"的面；

package/dist/index.js

@@ -99,6 +99,32 @@ 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 名之后
@@ -284,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 是同步回调，只读已
@@ -435,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 },
@@ -448,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),
     }));
@@ -704,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 },
@@ -724,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.17.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": {