@max-null/dsh-memory 0.5.0 → 0.5.2

package/README.md

@@ -1,5 +1,9 @@
 # dsh-memory
 
+本插件属于 **`@max-null/*` 插件系列**——这一系列共同构成 **[SSID（思灵 · Seek Soul in Darkness）](https://github.com/Max-Null/seek-soul-in-darkness)** 桌面体验。SSID 是整合它们的盒：`dsh-capture` · `dsh-chat-rail` · `dsh-chinese-thinking` · `dsh-draft-polish` · `dsh-guardian` · `dsh-habit` · `dsh-header-unify` · `dsh-memory` · `dsh-node-appearance` · `dsh-plugin-center` · `dsh-skill-mcp-center` · `dsh-ssid-panels` · `dsh-ssid-zh-ui`。
+
+This plugin belongs to the **`@max-null/*` family** — a set of plugins that together form the **[SSID (思灵 · Seek Soul in Darkness)](https://github.com/Max-Null/seek-soul-in-darkness)** desktop experience.
+
 一个面向 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的**跨会话明文记忆插件**。遵循「一切皆插件」——它不修改 DSH 源码，声明 `name`/`inject`/`apply`，由 Loader 从 `cordis.yml` 加载。
 
 ## 设计原则
@@ -7,7 +11,7 @@
 1. **人是所有者**：模型只能写入 `suggested` 状态的记忆，绝不自我提升；只有人工确认（`setStatus`）才能让记忆生效。
 2. **可观测先于精准**：每条记忆是明文，`memory_list` 随时可见、`memory_forget` 随时删除——不存在"静默暗礁"。
 3. **明文是人机共享的审计窗口**：记忆是可读文本，模型可自检其是否过期或出错（规划中的 v2）。
-4. **确定性且缓存安全**：BM25 关键词检索是存储的纯函数、无 LLM 调用；固定指引进 system-prompt section，`auto` 记忆进 context。
+4. **确定性且缓存安全**：BM25 关键词检索是存储的纯函数、无 LLM 调用；固定指引进 system-prompt section，`approved + injected` 记忆进 recall context（global 全量 + 当前会话工作区），逐条为单行摘要并按注入预算截断（超预算按最近使用优先，省略数在面板可见）。
 
 ## 用法
 
@@ -25,8 +29,9 @@ npm install @max-null/dsh-memory
 ## 提供的服务与工具
 
 - **服务** `ctx.memory`：`remember` / `list` / `search` / `forget` / `setStatus`
-- **工具**：`memory_save`、`memory_list`、`memory_search`、`memory_confirm`、`memory_forget`
-- **注入**：`tool:memory` 指引 section + `memory:recall` 召回 context（`auto` 记忆，带 `[memory:<id>]` 来源标记）
+- **工具**：`memory_save`、`memory_list`、`memory_search`、`memory_confirm`、`memory_forget`、`memory_update`
+- **注入**：`tool:memory` 指引 section + `memory:recall` 召回 context（global 的 `approved + injected` + 当前会话工作区的 `approved + injected`，带 `[memory:<id>:<namespace>]` 来源标记；摘要化 + 预算截断）
+- **检索**：BM25（CJK 单字 + 2-gram，content 与 keywords 字段分离加权；中文多字查询精度显著优于单字切分）；可选语义融合（见「可选配置」）
 
 ## 两层存储（global / project）
 
@@ -35,16 +40,17 @@ npm install @max-null/dsh-memory
 | namespace | 默认位置 | 用途 |
 |---|---|---|
 | `global` | `$DSH_HOME/storages/memory.json` | 跨项目的个人偏好 |
-| `project` | `<cwd>/.dsh/storages/memory_project.json` | 跟随仓库的项目共识，可 git 分享 |
+| `project` | `<cwd>/.dsh/storages/memory_project_<hash>.json` | 跟随仓库的项目共识，可 git 分享 |
 
-两个根都可用 config 覆盖（`globalRoot` / `projectRoot`）。`memory_list` / `memory_search` 不带 `namespace` 过滤时会同时查两层。
+两个根都可用 config 覆盖（`globalRoot` / `projectRoot`）。`memory_list` / `memory_search` 不带 `namespace` 过滤时会同时查两层。旧版双重前缀文件名（`memory_project_memory_project_<hash>.json`）在打开时自动迁移为规范名。
 
 ## 使用流程（人工确认闸门）
 
 ```
 模型 memory_save     →  status: suggested（只是建议，未生效）
-人 memory_confirm    →  status: auto（生效，自动进入每轮的 recall context）
-memory_search        →  随时按关键词召回任意状态的记忆
+人 memory_confirm    →  status: approved（已审核；是否常驻注入由独立开关 injected 决定）
+人（面板/开关）       →  injected: true（每轮注入：global + 当前会话工作区，摘要化 + 预算截断）
+memory_search        →  关键词/语义召回任意状态的记忆（命中标记 lastUsedAt 冷热追踪）
 memory_forget        →  随时删除
 ```
 
@@ -52,15 +58,28 @@ memory_forget        →  随时删除
 
 ## 为什么明文 + BM25，而不是向量检索
 
-向量检索的记忆本体是一串不可读的数字，过期信息会成为**无法观测、无法修复的静默暗礁**；BM25 + 明文让每一次召回都可解释、每一条记忆都可见可删。语义（向量）检索留作 v2 的可选项，且以"可观测 + 可修复"为门槛，而非时间表。
+向量检索的记忆本体是一串不可读的数字，过期信息会成为**无法观测、无法修复的静默暗礁**；BM25 + 明文让每一次召回都可解释、每一条记忆都可见可删。语义（向量）检索作为**可插拔的可选项**（0.5.2，见「可选配置」）——记忆本体仍是明文，向量仅作为检索辅助字段（`vector`，明文可读），且以"可观测 + 可修复"为门槛。
 
-明文还有一层**跟随仓库分享**的好处：`project` 命名空间的记忆落在项目文件夹内（`<cwd>/.dsh/storages/memory_project.json`），随 `git` 提交、分享给所有协作者；`global` 命名空间的记忆留在本地 `$DSH_HOME`。团队的共识（"本项目统一用 Vue3 `<script setup>`"）能沉淀进仓库，而不是散落在每个人的本地。FTS5 的 SQLite 二进制、向量的数字串，都无法这样"跟着仓库走"。
+明文还有一层**跟随仓库分享**的好处：`project` 命名空间的记忆落在项目文件夹内（`<cwd>/.dsh/storages/memory_project_<hash>.json`），随 `git` 提交、分享给所有协作者；`global` 命名空间的记忆留在本地 `$DSH_HOME`。团队的共识（"本项目统一用 Vue3 `<script setup>`"）能沉淀进仓库，而不是散落在每个人的本地。FTS5 的 SQLite 二进制无法这样"跟着仓库走"。
 
-## SSID 系列
+## 可选配置
 
-本插件属于 **`@max-null/*` 插件系列**——这一系列共同构成 **[SSID（思灵 · Seek Soul in Darkness）](https://github.com/Max-Null/seek-soul-in-darkness)** 桌面体验。SSID 是整合它们的盒：`dsh-chat-rail` · `dsh-chinese-thinking` · `dsh-draft-polish` · `dsh-guardian` · `dsh-habit` · `dsh-header-unify` · `dsh-memory` · `dsh-node-appearance` · `dsh-plugin-center` · `dsh-skill-mcp-center` · `dsh-ssid-panels` · `dsh-ssid-zh-ui`。
+在 `cordis.yml` 的 `config` 里传给插件（均可省略）：
 
-This plugin belongs to the **`@max-null/*` family** — a set of plugins that together form the **[SSID (思灵 · Seek Soul in Darkness)](https://github.com/Max-Null/seek-soul-in-darkness)** desktop experience.
+```yaml
+- id: memory
+  name: '@max-null/dsh-memory'
+  config:
+    injectionBudget: 1500        # 常驻注入预算（字符；null = 不限制）
+    summaryChars: 80             # 单条注入摘要截断上限（字符）
+    semanticTopK: 5              # 语义侧参与融合的 topK（仅配置 embeddings 时生效）
+    # 混合语义检索（可插拔；缺省 = 纯 BM25）
+    # embeddings: { embed: '...' 提供 embed(texts) 的宿主函数 或 插件名 ... }
+```
+
+`embeddings` 接受 `{ embed(texts): Promise<number[][]>, similarity? }` 对象——由宿主装配层提供嵌入实现（如 DeepSeek 嵌入端点）；配置后 `memory_search` 以 BM25 + 语义 RRF 融合，向量增量生成并持久化，嵌入调用失败自动降级为纯 BM25。
+
+## SSID 系列
 
 ## 开发
 

package/client.js

@@ -173,7 +173,8 @@ var STRINGS = {
     keywordsLabel: "\u5173\u952E\u8BCD",
     suggested: "\u5F85\u5BA1\u6838",
     approved: "\u5DF2\u5BA1\u6838",
-    refresh: "\u5237\u65B0"
+    refresh: "\u5237\u65B0",
+    coldHint: "\u51B7\u6570\u636E \xB7 \u5EFA\u8BAE\u6309\u9700\u5316"
   },
   en: {
     tabMemory: "Memory",
@@ -197,7 +198,8 @@ var STRINGS = {
     keywordsLabel: "Keywords",
     suggested: "Suggested",
     approved: "Approved",
-    refresh: "Refresh"
+    refresh: "Refresh",
+    coldHint: "Cold \xB7 consider on-demand"
   }
 };
 var localeId = "zh";
@@ -294,11 +296,20 @@ var memoryApi = {
   setInjected(id, injected, cwd) {
     return api("setInjected", { id, injected, ...cwd === void 0 ? {} : { cwd } });
   },
-  injectionPreview() {
-    return api("injectionPreview");
+  injectionPreview(cwd) {
+    return api("injectionPreview", { ...cwd === void 0 ? {} : { cwd } });
   }
 };
 var ORGANIZE_PROMPT = "\u8BF7\u6574\u7406\u6211\u7684\u8BB0\u5FC6\u5E93\uFF1A\u7528 memory_list \u67E5\u770B\u5168\u90E8\u8BB0\u5FC6\u3002\u6574\u7406\u89C4\u5219\uFF08\u5FC5\u987B\u6267\u884C\uFF09\uFF1A\u2460\u540C\u7C7B\u6761\u76EE\u5408\u5E76\u2014\u2014\u5DE5\u4F5C\u4E60\u60EF/\u7EA6\u5B9A\u7C7B\u591A\u6761\u5408\u5E76\u4E3A\u4E00\u6761\uFF08\u5185\u5BB9\u7528 \u2460\u2461\u2462 \u5E76\u5217\uFF0C\u907F\u514D\u788E\u7247\u5316\uFF09\uFF1B\u2461\u4E0E\u300C[\u8BB0\u5FC6\u7CFB\u7EDF\u81EA\u8FF0]\u300D\uFF08\u4F60\u4E0A\u4E0B\u6587\u4E2D\u7684\u8BB0\u5FC6\u673A\u5236\u8BF4\u660E\uFF09\u5185\u5BB9\u91CD\u590D\u7684\u63D2\u4EF6\u4ECB\u7ECD\u6761\u76EE\uFF08\u5982 dsh-memory \u63D2\u4EF6\u53D1\u5E03\u4FE1\u606F\uFF09\u5E94\u5220\u9664\u2014\u2014\u673A\u5236\u8BF4\u660E\u5DF2\u7531\u7CFB\u7EDF\u5E38\u9A7B\u63D0\u4F9B\uFF0C\u65E0\u9700\u7528\u6237\u5B58\u50A8\uFF1B\u2462\u5BF9\u8FC7\u65F6\u3001\u9519\u8BEF\u6216\u5DF2\u53D8\u5316\u7684\u5185\u5BB9\u7528 memory_update \u4FEE\u6B63\uFF08\u4F1A\u91CD\u7F6E\u4E3A\u5F85\u5BA1\u6838\uFF09\uFF1B\u2463\u7CBE\u7B80\u5197\u957F\u5185\u5BB9\uFF0C\u4E3A\u6BCF\u6761\u8865\u5145\u6216\u4FEE\u6B63 keywords\uFF1B\u2464\u9700\u8981\u5220\u9664\u7684\u7528 memory_forget\uFF0C\u9700\u8981\u65B0\u589E\u7684\u7528 memory_save\u3002\u5224\u65AD\u5185\u5BB9\u662F\u5426\u8FC7\u65F6\u7684\u65B9\u6CD5\uFF1A\u628A\u8BB0\u5FC6\u91CC\u63D0\u5230\u7684\u5DE5\u5177\u540D/\u6570\u91CF\u4E0E\u4F60\u5F53\u524D\u5B9E\u9645\u53EF\u7528\u7684\u8BB0\u5FC6\u5DE5\u5177\u5BF9\u7167\u2014\u2014\u4F60\u5F53\u524D\u53EF\u7528\uFF1Amemory_save / memory_list / memory_search / memory_confirm / memory_forget / memory_update\uFF08\u5171 6 \u4E2A\uFF09\uFF1B\u82E5\u8BB0\u5FC6\u4E2D\u7684\u5DE5\u5177\u5217\u8868\u3001\u6570\u91CF\u3001\u6D41\u7A0B\u4E0E\u6B64\u4E0D\u7B26\u5373\u4E3A\u8FC7\u65F6\uFF0C\u7528 memory_update \u4FEE\u6B63\u3002\u6539\u52A8\u5168\u90E8\u843D\u5728 suggested \u7B49\u5F85\u5BA1\u6838\uFF08\u4E0D\u8981\u8C03\u7528 memory_confirm\uFF09\uFF0C\u5B8C\u6210\u540E\u7528\u4E00\u53E5\u8BDD\u6C47\u62A5\u6574\u7406\u7ED3\u679C\u3002";
+var DAY_MS = 864e5;
+var COLD_DAYS = 30;
+function fmtDate(ms) {
+  const date = new Date(ms);
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+}
+function isCold(usedAt, now = Date.now()) {
+  return usedAt === void 0 || now - usedAt > COLD_DAYS * DAY_MS;
+}
 function MemoryView(props) {
   const t = useT();
   const [records, setRecords] = (0, import_react.useState)([]);
@@ -314,7 +325,7 @@ function MemoryView(props) {
       return;
     }
     try {
-      setPreview(await memoryApi.injectionPreview());
+      setPreview(await memoryApi.injectionPreview(props.cwd));
     } catch {
       setPreview(null);
     }
@@ -472,7 +483,7 @@ function MemoryView(props) {
     (0, import_react.createElement)(
       "div",
       { style: ssid.content },
-      // 注入预览（开发者）：self 自述 + 当前注入的记忆 + 上下文占用统计
+      // 注入预览（开发者）：self 自述 + 实际注入行（摘要化+预算）+ 预算使用统计
       previewOpen && preview !== null ? (0, import_react.createElement)(
         "div",
         { style: { ...ssid.card, display: "flex", flexDirection: "column", gap: 6 } },
@@ -482,18 +493,15 @@ function MemoryView(props) {
           (0, import_react.createElement)("span", null, t("contextUsage")),
           (0, import_react.createElement)("span", null, (() => {
             const selfChars = preview.self.length;
-            const injectedChars = preview.injected.reduce((sum, record) => sum + record.content.length + record.keywords.join("").length, 0);
-            const total = selfChars + injectedChars;
+            const total = selfChars + preview.chars;
             const tokens = Math.ceil(total / 2);
-            return `${selfChars}+${injectedChars} \u5B57\u7B26 \u2248 ${tokens} token`;
+            const budgetText = preview.budget === null ? "" : ` / \u9884\u7B97 ${preview.budget}`;
+            const omittedText = preview.omitted > 0 ? `\uFF08\u7701\u7565 ${preview.omitted} \u6761\uFF09` : "";
+            return `${selfChars}+${preview.chars} \u5B57\u7B26${budgetText}${omittedText} \u2248 ${tokens} token`;
           })())
         ),
         (0, import_react.createElement)("div", { style: { ...ssid.text, fontSize: 11, whiteSpace: "pre-wrap", wordBreak: "break-all" } }, preview.self),
-        preview.injected.length === 0 ? (0, import_react.createElement)("div", { style: ssid.muted }, t("empty")) : preview.injected.map((record) => (0, import_react.createElement)(
-          "div",
-          { key: record.id, style: { ...ssid.muted, fontSize: 11 } },
-          `- [memory:${record.id.slice(0, 8)}] ${record.content}`
-        ))
+        preview.lines.length === 0 ? (0, import_react.createElement)("div", { style: ssid.muted }, t("empty")) : preview.lines.map((line, index) => (0, import_react.createElement)("div", { key: index, style: { ...ssid.muted, fontSize: 11 } }, line))
       ) : null,
       // 未选择工作区：工作区视图显示占位（0.3.4 工作区路由语义）
       namespace === "workspace" && (props.cwd === void 0 || props.cwd === "") ? (0, import_react.createElement)("div", { style: ssid.empty }, t("noWorkspace")) : groups.length === 0 ? (0, import_react.createElement)("div", { style: ssid.empty }, t("empty")) : groups.map((group) => (0, import_react.createElement)(
@@ -539,7 +547,7 @@ function MemoryView(props) {
           (0, import_react.createElement)(
             "div",
             { style: { ...ssid.muted, marginTop: 6 } },
-            `${record.namespace} \xB7 ${record.status === "approved" ? t("approved") : t("suggested")}${record.injected ? ` \xB7 ${t("groupInjected")}` : ""}`
+            `${record.namespace} \xB7 ${record.status === "approved" ? t("approved") : t("suggested")}${record.injected ? ` \xB7 ${t("groupInjected")}` : ""}${record.lastUsedAt !== void 0 ? ` \xB7 \u4E0A\u641C ${fmtDate(record.lastUsedAt)}` : ""}${isCold(record.lastUsedAt) ? ` \xB7 ${t("coldHint")}` : ""}`
           ),
           (0, import_react.createElement)(
             "div",

package/dist/bm25.d.ts

@@ -3,7 +3,31 @@
  * store — no model call — so recall is deterministic and a miss is explainable
  * as "no keyword match".
  */
-/** Split text into lowercase terms: English/number runs stay whole, each CJK ideograph its own term. */
+/**
+ * Split text into lowercase terms: English/number runs stay whole; each CJK
+ * ideograph its own term AND each adjacent pair its own bigram (0.5.2) —
+ * bigram raises Chinese multi-char hit precision, single chars keep
+ * single-character queries working.
+ */
 export declare function tokenize(text: string): string[];
 /** Score one query against each document with BM25, in document order. */
 export declare function bm25Scores(query: string, docs: readonly string[]): number[];
+/**
+ * 字段加权 BM25（0.5.2）：body（记忆内容）与 tags（人工关键词）分离打分，
+ * tags 命中 ×TAG_BOOST；用于 memory_search，人工关键词比正文更可检索。
+ */
+export declare function bm25FieldScores(query: string, docs: readonly {
+    body: string;
+    tags?: string;
+}[]): number[];
+/**
+ * RRF（Reciprocal Rank Fusion，0.5.2 混合检索）：按各通道排名倒数融合。
+ * 只依赖排名不依赖分数，两个异构打分通道（BM25 / 余弦相似度）可直接合流。
+ * @param rankings - 每通道一个 id → 排名（0 = 第一）；同一 id 在多个通道的
+ *   分数累加。
+ * @param k - RRF 常数（惯例 60）。
+ * @returns id → 融合分数（按降序排序的数组）。
+ */
+export declare function rrfFuse(rankings: readonly (readonly string[])[], k?: number): Array<[string, number]>;
+/** 余弦相似度（默认 similarity；向量维度不一致返回 0）。 */
+export declare function cosineSimilarity(left: readonly number[], right: readonly number[]): number;

package/dist/bm25.js

@@ -3,12 +3,55 @@
  * store — no model call — so recall is deterministic and a miss is explainable
  * as "no keyword match".
  */
-/** Split text into lowercase terms: English/number runs stay whole, each CJK ideograph its own term. */
+/**
+ * Split text into lowercase terms: English/number runs stay whole; each CJK
+ * ideograph its own term AND each adjacent pair its own bigram (0.5.2) —
+ * bigram raises Chinese multi-char hit precision, single chars keep
+ * single-character queries working.
+ */
 export function tokenize(text) {
-    return text.toLowerCase().match(/[a-z0-9]+|[\u3400-\u9fff]/g) ?? [];
+    const lower = text.toLowerCase();
+    const terms = [];
+    const runs = lower.match(/[a-z0-9]+|[\u3400-\u9fff]+/g) ?? [];
+    for (const run of runs) {
+        if (/^[a-z0-9]/.test(run)) {
+            terms.push(run);
+            continue;
+        }
+        for (let i = 0; i < run.length; i++)
+            terms.push(run[i]);
+        for (let i = 0; i < run.length - 1; i++)
+            terms.push(run.slice(i, i + 2));
+    }
+    return terms;
 }
 const K1 = 1.2;
 const B = 0.75;
+/** 命中 tags（keywords）的 term 频率权重（0.5.2：人工关键词比正文更可检索）。 */
+const TAG_BOOST = 2;
+/** 单文档 BM25 打分（tags 命中 ×TAG_BOOST；文档长度按同一加权核算）。 */
+function scoreDoc(queryTerms, body, tags, documentFrequency, n, averageLength) {
+    let score = 0;
+    const length = body.length + tags.length * TAG_BOOST;
+    for (const term of queryTerms) {
+        let bodyTf = 0;
+        for (const candidate of body)
+            if (candidate === term)
+                bodyTf++;
+        let tagTf = 0;
+        for (const candidate of tags)
+            if (candidate === term)
+                tagTf++;
+        if (bodyTf + tagTf === 0)
+            continue;
+        const frequency = documentFrequency.get(term) ?? 0;
+        const idf = Math.log(1 + (n - frequency + 0.5) / (frequency + 0.5));
+        const weightedTf = bodyTf + tagTf * TAG_BOOST;
+        const denominator = weightedTf + K1 * (1 - B + B * (length / (averageLength || 1)));
+        score += idf * (weightedTf * (K1 + 1)) / denominator;
+    }
+    return score;
+}
 /** Score one query against each document with BM25, in document order. */
 export function bm25Scores(query, docs) {
     const queryTerms = tokenize(query);
@@ -20,23 +63,59 @@ export function bm25Scores(query, docs) {
         }
     }
     const n = docs.length;
-    const totalLength = tokenized.reduce((sum, doc) => sum + doc.length, 0);
-    const averageLength = n === 0 ? 0 : totalLength / n;
-    return tokenized.map((doc) => {
-        let score = 0;
-        for (const term of queryTerms) {
-            let termFrequency = 0;
-            for (const candidate of doc) {
-                if (candidate === term)
-                    termFrequency++;
-            }
-            if (termFrequency === 0)
-                continue;
-            const frequency = documentFrequency.get(term) ?? 0;
-            const idf = Math.log(1 + (n - frequency + 0.5) / (frequency + 0.5));
-            const denominator = termFrequency + K1 * (1 - B + B * (doc.length / (averageLength || 1)));
-            score += idf * (termFrequency * (K1 + 1)) / denominator;
+    const averageLength = n === 0 ? 0 : tokenized.reduce((sum, doc) => sum + doc.length, 0) / n;
+    return tokenized.map(doc => scoreDoc(queryTerms, doc, [], documentFrequency, n, averageLength));
+}
+/**
+ * 字段加权 BM25（0.5.2）：body（记忆内容）与 tags（人工关键词）分离打分，
+ * tags 命中 ×TAG_BOOST；用于 memory_search，人工关键词比正文更可检索。
+ */
+export function bm25FieldScores(query, docs) {
+    const queryTerms = tokenize(query);
+    const bodies = docs.map(doc => tokenize(doc.body));
+    const tags = docs.map(doc => doc.tags === undefined || doc.tags === '' ? [] : tokenize(doc.tags));
+    const documentFrequency = new Map();
+    for (let i = 0; i < bodies.length; i++) {
+        for (const term of new Set([...bodies[i], ...tags[i]])) {
+            documentFrequency.set(term, (documentFrequency.get(term) ?? 0) + 1);
         }
-        return score;
-    });
+    }
+    const n = docs.length;
+    const averageLength = n === 0
+        ? 0
+        : bodies.reduce((sum, body, i) => sum + body.length + tags[i].length * TAG_BOOST, 0) / n;
+    return bodies.map((body, i) => scoreDoc(queryTerms, body, tags[i], documentFrequency, n, averageLength));
+}
+/**
+ * RRF（Reciprocal Rank Fusion，0.5.2 混合检索）：按各通道排名倒数融合。
+ * 只依赖排名不依赖分数，两个异构打分通道（BM25 / 余弦相似度）可直接合流。
+ * @param rankings - 每通道一个 id → 排名（0 = 第一）；同一 id 在多个通道的
+ *   分数累加。
+ * @param k - RRF 常数（惯例 60）。
+ * @returns id → 融合分数（按降序排序的数组）。
+ */
+export function rrfFuse(rankings, k = 60) {
+    const scores = new Map();
+    for (const ranking of rankings) {
+        ranking.forEach((id, rank) => {
+            scores.set(id, (scores.get(id) ?? 0) + 1 / (k + rank + 1));
+        });
+    }
+    return [...scores.entries()].sort((left, right) => right[1] - left[1]);
+}
+/** 余弦相似度（默认 similarity；向量维度不一致返回 0）。 */
+export function cosineSimilarity(left, right) {
+    if (left.length === 0 || left.length !== right.length)
+        return 0;
+    let dot = 0;
+    let leftNorm = 0;
+    let rightNorm = 0;
+    for (let i = 0; i < left.length; i++) {
+        dot += left[i] * right[i];
+        leftNorm += left[i] * left[i];
+        rightNorm += right[i] * right[i];
+    }
+    if (leftNorm === 0 || rightNorm === 0)
+        return 0;
+    return dot / (Math.sqrt(leftNorm) * Math.sqrt(rightNorm));
 }

package/dist/engine.d.ts

@@ -28,6 +28,8 @@ export interface MemoryRecord {
     keywords: string[];
     createdAt: number;
     updatedAt: number;
+    /** 最近一次被 memory_search 命中的时间（0.5.3 冷热追踪）；无则未命中过。 */
+    lastUsedAt?: number;
 }
 export interface MemoryWrite {
     content: string;
@@ -68,12 +70,35 @@ declare module '@deepseek-ai/cordis' {
         'memory/changed'(change: MemoryChange): void;
     }
 }
+/**
+ * 嵌入能力（0.5.2 混合检索）：缺省不配置 = 纯 BM25（行为不变）；
+ * 配置后 memory_search 以 BM25 与语义结果做 RRF 融合，向量持久化到
+ * 存储文件（vector 字段，外部可读），失败自动降级回纯 BM25。
+ */
+export interface MemoryEmbeddings {
+    /** 文本 → 向量（与输入等长，一维浮点数组）。 */
+    embed(texts: readonly string[], signal?: AbortSignal): Promise<readonly number[][]>;
+    /** 相似度函数（缺省余弦相似度）。 */
+    similarity?: (left: readonly number[], right: readonly number[]) => number;
+}
 /** Engine configuration: the two storage roots, defaulted to home and project. */
 export interface MemoryConfig {
     /** Root for `global` memories; defaults to `$DSH_HOME/storages`. */
     globalRoot?: string;
     /** Root for `project` memories; defaults to `<cwd>/.dsh/storages`. */
     projectRoot?: string;
+    /**
+     * 常驻注入预算（字符，0.5.2）：`memory:recall` 每轮注入的摘要总量上限，
+     * 超预算按「最近更新优先」省略（面板提示省略数）。null/0 = 不限制。
+     * 默认 DEFAULT_INJECTION_BUDGET（1500 字符，约 400-700 token）。
+     */
+    injectionBudget?: number | null;
+    /** 单条注入摘要截断上限（字符）；默认 DEFAULT_SUMMARY_CHARS（80）。 */
+    summaryChars?: number;
+    /** 混合语义检索（0.5.2）：缺省纯 BM25；配置后与 BM25 做 RRF 融合。 */
+    embeddings?: MemoryEmbeddings;
+    /** 语义侧参与融合的 topK（0.5.2）；默认 5。 */
+    semanticTopK?: number;
 }
 /**
  * Cross-session plaintext memory over the storage hub, split by namespace:
@@ -115,6 +140,16 @@ export declare class MemoryEngine extends Service {
     remember(input: MemoryWrite, projectCwd?: string): Promise<MemoryRecord>;
     list(filter?: MemoryFilter, projectCwd?: string): Promise<MemoryRecord[]>;
     search(query: string, filter?: MemoryFilter, projectCwd?: string): Promise<MemoryHit[]>;
+    /**
+     * 语义排序（0.5.2）：查询向量 + 候选向量的余弦相似度，仅在有
+     * embeddings 配置时被调用。缺失向量（新增/更新过的记录）在此补生成
+     * 并持久化（vector 字段）；生成失败抛给调用方降级。
+     */
+    private semanticRanking;
+    /** 按已知 id 定位记录所在表（global 优先，其次当前工作区表）。 */
+    private tableOf;
+    /** 命中标记：把 lastUsedAt 写回（命中记录不存在时跳过；不 emit 事件——统计性字段）。 */
+    private markUsed;
     forget(id: MemoryId, projectCwd?: string): Promise<boolean>;
     setStatus(id: MemoryId, status: MemoryStatus, projectCwd?: string): Promise<MemoryRecord>;
     /**
@@ -132,10 +167,19 @@ export declare class MemoryEngine extends Service {
         keywords?: string[];
     }, projectCwd?: string): Promise<MemoryRecord>;
     /**
-     * 注入专用（0.3.4）：systemPrompt context 是同步回调、无会话 cwd 可及，
-     * 只返回 global 的 approved+injected（工作区记忆走检索/面板）。
+     * 预热某工作区的 project 表（异步打开并缓存）。system prompt 的
+     * `memory:recall` provider 是同步回调——只读已打开的表；预热让
+     * 会话创建/首次请求后本轮或下一轮即可注入工作区记忆。
+     */
+    ensureProjectOpen(projectCwd: string): Promise<void>;
+    /**
+     * 注入专用（0.3.4 + 0.5.1）：system prompt 的 `memory:recall` context
+     * provider 可经 AssembleContext.agent 拿到当前会话 header.cwd，因此
+     * 注入 = global 的 approved+injected + 当前会话工作区的 approved+injected。
+     * provider 是同步回调：只读已打开/缓存的表，未打开的工作区本轮为空
+     * （`ensureProjectOpen` 提供预热，工具/面板路径也会打开）。
      */
-    recallRecords(): MemoryRecord[];
+    recallRecords(projectCwd?: string): MemoryRecord[];
     private allRecords;
     private recordsOf;
     private tableFor;

package/dist/engine.js

@@ -5,13 +5,14 @@
  * is always created `suggested` and becomes effective only through `setStatus`.
  */
 import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { Service } from '@deepseek-ai/cordis';
 import { z } from 'zod';
 import { defineDomain, domainTable, DomainFacility } from '@deepseek-ai/dsh-storage-domain';
 import { JsonStorageBackend } from '@deepseek-ai/dsh-storage-json';
-import { bm25Scores } from "./bm25.js";
+import { bm25FieldScores, cosineSimilarity, rrfFuse } from "./bm25.js";
 /** Brand a string as a {@link MemoryId} (compile-time only). */
 export function MemoryId(id) {
     return id;
@@ -24,6 +25,8 @@ const blockSchema = z.object({
     keywords: z.array(z.string()),
     createdAt: z.number(),
     updatedAt: z.number(),
+    lastUsedAt: z.number().optional(),
+    vector: z.array(z.number()).optional(),
 });
 /** Shared table shape; the two domains differ only by name and backend route. */
 function memorySpec(name) {
@@ -33,6 +36,30 @@ function memorySpec(name) {
         tables: { blocks: domainTable(blockSchema) },
     });
 }
+/** 读 unit 文件头的 name（文件不存在 → undefined；非法 JSON/结构异常抛错）。 */
+function unitHeaderName(path) {
+    if (!existsSync(path))
+        return undefined;
+    const document = JSON.parse(readFileSync(path, 'utf8'));
+    return typeof document.unit?.name === 'string' ? document.unit.name : undefined;
+}
+/** 改写 unit 文件头的 name（保持 2 空格缩进 + 尾换行，与 storage-json/format 一致）。 */
+function rewriteUnitName(path, name) {
+    const document = JSON.parse(readFileSync(path, 'utf8'));
+    if (document.unit === undefined)
+        throw new Error(`unit '${path}': missing unit header`);
+    document.unit.name = name;
+    writeFileSync(path, `${JSON.stringify(document, null, 2)}\n`);
+}
+/** 迁移旧 unit 文件：校验头名 → 改写为新名并落位规范路径 → 删除旧文件。 */
+function migrateUnit(legacyPath, canonicalPath, legacyName, canonicalName) {
+    const document = JSON.parse(readFileSync(legacyPath, 'utf8'));
+    if (document.unit?.name !== legacyName)
+        throw new Error(`unit '${legacyPath}': unexpected unit header`);
+    document.unit.name = canonicalName;
+    writeFileSync(canonicalPath, `${JSON.stringify(document, null, 2)}\n`);
+    rmSync(legacyPath);
+}
 /**
  * 旧 schema 迁移（0.3.0，设计文档「迁移规则」）：
  * - 旧 `auto` → approved + injected:true（行为不变：仍常驻注入）
@@ -56,6 +83,7 @@ function toRecord(id, block) {
         keywords: block.keywords,
         createdAt: block.createdAt,
         updatedAt: block.updatedAt,
+        ...block.lastUsedAt === undefined ? {} : { lastUsedAt: block.lastUsedAt },
     };
 }
 /** Harness-home root for `global` memories. */
@@ -130,13 +158,37 @@ export class MemoryEngine extends Service {
         if (cached !== undefined)
             return cached;
         const backendName = this.projectBackendName(key);
+        // 0.5.2：旧实现 domain 名多一层 memory_project_ 前缀（文件名双重前缀，
+        // 且 unit 文件头 name 同为旧名）。打开前统一迁移到规范名：
+        // ①规范名已存在 + 头为旧名（0.5.2 首版只 rename 未改 header 的中间态）→ 改写头；
+        // ②旧名文件存在且头匹配 → 改写头并落位规范名；③其他情况回退旧域名（不动数据）。
+        const legacyDomainName = `memory_project_${backendName}`;
+        const root = this.projectRootFor(key);
+        const canonicalFile = join(root, `${backendName}.json`);
+        const legacyFile = join(root, `${legacyDomainName}.json`);
+        let domainName = backendName;
+        try {
+            const canonicalHeader = unitHeaderName(canonicalFile);
+            if (canonicalHeader === legacyDomainName) {
+                rewriteUnitName(canonicalFile, backendName);
+            }
+            else if (canonicalHeader === undefined && unitHeaderName(legacyFile) === legacyDomainName) {
+                migrateUnit(legacyFile, canonicalFile, legacyDomainName, backendName);
+            }
+            else if (canonicalHeader === undefined && existsSync(legacyFile)) {
+                domainName = legacyDomainName; // 外域/未知内容：保持旧名路径继续打开，不触碰数据
+            }
+        }
+        catch {
+            domainName = legacyDomainName; // 迁移出错：回退旧名打开，数据不动（后续可重试）
+        }
         if (!this.registeredProjectBackends.has(backendName)) {
-            const backend = new JsonStorageBackend(this.projectRootFor(key));
+            const backend = new JsonStorageBackend(root);
             this.ctx.storage.backend.register(backendName, backend);
             this.registeredProjectBackends.add(backendName);
         }
         const facility = new DomainFacility(this.ctx, { backend: backendName, routes: {} });
-        const domain = await facility.open(memorySpec(`memory_project_${backendName}`));
+        const domain = await facility.open(memorySpec(domainName));
         const table = domain.table('blocks');
         this.projectFacilities.set(key, facility);
         this.projectTables.set(key, table);
@@ -186,12 +238,121 @@ export class MemoryEngine extends Service {
     }
     async search(query, filter, projectCwd) {
         const records = await this.list(filter, projectCwd);
-        const docs = records.map(record => `${record.content} ${record.keywords.join(' ')}`);
-        const scores = bm25Scores(query, docs);
-        return records
+        // 0.5.2：content 与 keywords 分离打加权 BM25（人工关键词命中权重更高）
+        const scores = bm25FieldScores(query, records.map(record => ({
+            body: record.content,
+            tags: record.keywords.join(' '),
+        })));
+        const bm25Ranked = records
             .map((record, index) => ({ record, score: scores[index] ?? 0 }))
             .filter(hit => hit.score > 0)
             .sort((left, right) => right.score - left.score);
+        // 0.5.3：命中即标记使用（冷热追踪）——写回按命中快照之后执行，不影响本次结果
+        await this.markUsed(bm25Ranked.map(hit => hit.record.id), projectCwd);
+        // 0.5.2：配置 embeddings 时与语义结果 RRF 融合；缺省/失败降级回纯 BM25
+        if (this.config.embeddings === undefined)
+            return bm25Ranked;
+        try {
+            const semantic = await this.semanticRanking(query, records.map(record => record.id), projectCwd);
+            if (semantic.length === 0)
+                return bm25Ranked;
+            const byId = new Map(records.map(record => [String(record.id), record]));
+            return rrfFuse([
+                bm25Ranked.map(hit => String(hit.record.id)),
+                semantic.map(hit => String(hit.id)),
+            ]).flatMap(([id, score]) => {
+                const record = byId.get(id);
+                return record === undefined ? [] : [{ record, score }];
+            });
+        }
+        catch (error) {
+            // 语义通道失败降级：不影响检索可用性（BM25 结果照常返回）
+            this.ctx.logger?.warn?.(`dsh-memory: semantic search degraded: ${error instanceof Error ? error.message : String(error)}`);
+            return bm25Ranked;
+        }
+    }
+    /**
+     * 语义排序（0.5.2）：查询向量 + 候选向量的余弦相似度，仅在有
+     * embeddings 配置时被调用。缺失向量（新增/更新过的记录）在此补生成
+     * 并持久化（vector 字段）；生成失败抛给调用方降级。
+     */
+    async semanticRanking(query, ids, projectCwd) {
+        const config = this.config.embeddings;
+        if (config === undefined)
+            return [];
+        const similarity = config.similarity ?? cosineSimilarity;
+        const topK = this.config.semanticTopK ?? 5;
+        const queryVector = (await config.embed([query]))?.[0];
+        if (queryVector === undefined)
+            return [];
+        // 缺失向量批量补写（本轮直接用本地生成的向量参与打分，写回不阻塞结果）
+        const missing = [];
+        for (const id of ids) {
+            const table = this.tableOf(id, projectCwd);
+            const block = table?.get(id);
+            if (table === undefined || block === undefined)
+                continue;
+            if (block.vector === undefined)
+                missing.push({ table, id, content: block.content });
+        }
+        const fresh = new Map();
+        if (missing.length > 0) {
+            const vectors = await config.embed(missing.map(missingRecord => missingRecord.content));
+            for (const [index, missingRecord] of missing.entries()) {
+                const vector = vectors[index];
+                if (vector === undefined)
+                    continue;
+                fresh.set(String(missingRecord.id), [...vector]);
+                const block = missingRecord.table.get(missingRecord.id);
+                if (block !== undefined) {
+                    await missingRecord.table.put(missingRecord.id, { ...block, vector: [...vector] });
+                }
+            }
+        }
+        const scored = [];
+        for (const id of ids) {
+            const block = this.tableOf(id, projectCwd)?.get(id);
+            const vector = fresh.get(String(id)) ?? block?.vector;
+            if (vector === undefined)
+                continue;
+            scored.push({ id, score: similarity(queryVector, vector) });
+        }
+        return scored
+            .filter(hit => hit.score > 0)
+            .sort((left, right) => right.score - left.score)
+            .slice(0, topK);
+    }
+    /** 按已知 id 定位记录所在表（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;
+    }
+    /** 命中标记：把 lastUsedAt 写回（命中记录不存在时跳过；不 emit 事件——统计性字段）。 */
+    async markUsed(ids, projectCwd) {
+        if (ids.length === 0)
+            return;
+        const now = Date.now();
+        const global = this.requireTable('global');
+        const project = projectCwd === undefined || projectCwd === ''
+            ? undefined
+            : this.projectTables.get(join(projectCwd));
+        for (const id of ids) {
+            const globalBlock = global.get(id);
+            if (globalBlock !== undefined) {
+                await global.put(id, { ...globalBlock, lastUsedAt: now });
+                continue;
+            }
+            if (project !== undefined) {
+                const block = project.get(id);
+                if (block !== undefined)
+                    await project.put(id, { ...block, lastUsedAt: now });
+            }
+        }
     }
     async forget(id, projectCwd) {
         if (await this.requireTable('global').delete(id)) {
@@ -313,12 +474,32 @@ export class MemoryEngine extends Service {
         throw new Error(`cannot update unknown memory '${id}'`);
     }
     /**
-     * 注入专用（0.3.4）：systemPrompt context 是同步回调、无会话 cwd 可及，
-     * 只返回 global 的 approved+injected（工作区记忆走检索/面板）。
+     * 预热某工作区的 project 表（异步打开并缓存）。system prompt 的
+     * `memory:recall` provider 是同步回调——只读已打开的表；预热让
+     * 会话创建/首次请求后本轮或下一轮即可注入工作区记忆。
      */
-    recallRecords() {
-        return this.recordsOf(this.requireTable('global'))
-            .filter(record => record.status === 'approved' && record.injected);
+    async ensureProjectOpen(projectCwd) {
+        const key = join(projectCwd);
+        if (this.projectTables.has(key))
+            return;
+        await this.projectTableFor(key);
+    }
+    /**
+     * 注入专用（0.3.4 + 0.5.1）：system prompt 的 `memory:recall` context
+     * provider 可经 AssembleContext.agent 拿到当前会话 header.cwd，因此
+     * 注入 = global 的 approved+injected + 当前会话工作区的 approved+injected。
+     * provider 是同步回调：只读已打开/缓存的表，未打开的工作区本轮为空
+     * （`ensureProjectOpen` 提供预热，工具/面板路径也会打开）。
+     */
+    recallRecords(projectCwd) {
+        const injected = (table) => this.recordsOf(table).filter(record => record.status === 'approved' && record.injected);
+        const global = injected(this.requireTable('global'));
+        if (projectCwd === undefined || projectCwd === '')
+            return global;
+        const project = this.projectTables.get(join(projectCwd));
+        if (project === undefined)
+            return global;
+        return [...global, ...injected(project)];
     }
     async allRecords(namespace, projectCwd) {
         if (namespace === 'project') {

package/dist/index.d.ts

@@ -9,7 +9,7 @@ import type { MemoryConfig } from './engine.ts';
 export { MemoryEngine } from './engine.ts';
 export type { MemoryChange, MemoryConfig, MemoryFilter, MemoryHit, MemoryNamespace, MemoryRecord, MemoryStatus, MemoryWrite, } from './engine.ts';
 export { MemoryId } from './engine.ts';
-export { bm25Scores, tokenize } from './bm25.ts';
+export { bm25FieldScores, bm25Scores, cosineSimilarity, rrfFuse, tokenize } from './bm25.ts';
 export declare const name = "dsh-memory";
 export declare const inject: string[];
 export declare function apply(ctx: Context, config?: MemoryConfig): Promise<void>;

package/dist/index.js

@@ -9,9 +9,10 @@ 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, renderInjection } from "./injection.js";
 export { MemoryEngine } from "./engine.js";
 export { MemoryId } from "./engine.js";
-export { bm25Scores, tokenize } from "./bm25.js";
+export { bm25FieldScores, bm25Scores, cosineSimilarity, rrfFuse, tokenize } from "./bm25.js";
 export const name = 'dsh-memory';
 export const inject = ['storage', 'systemPrompt', 'tools', 'webServer', 'webRuntime'];
 const RECORD_SCHEMA = {
@@ -26,6 +27,7 @@ const RECORD_SCHEMA = {
         keywords: { type: 'array', required: true, items: { type: 'string' } },
         createdAt: { type: 'number', required: true },
         updatedAt: { type: 'number', required: true },
+        lastUsedAt: { type: 'number' },
     },
 };
 const HIT_SCHEMA = {
@@ -46,6 +48,7 @@ function recordValue(record) {
         keywords: record.keywords,
         createdAt: record.createdAt,
         updatedAt: record.updatedAt,
+        ...record.lastUsedAt === undefined ? {} : { lastUsedAt: record.lastUsedAt },
     };
 }
 function hitValue(hit) {
@@ -63,16 +66,29 @@ const GUIDANCE = 'Use memory tools for cross-session preferences, habits, and pr
     + 'When earlier context may be relevant, call memory_search to recall it — reviewable memories '
     + '(`suggested`) are searchable too. 相关历史上下文可用 memory_search 检索——待审核的记忆也可检索。'
     + 'Every memory is plaintext and inspectable with memory_list; memory_forget removes one. '
-    + '所有记忆均为明文，可用 memory_list 查看；memory_forget 删除一条。';
-// 0.3.4：注入只注入 global 的 approved+injected（systemPrompt context 是
-// 同步回调、无会话 cwd 可及）；工作区（project）记忆按会话 cwd 路由，靠
-// memory_search / 面板访问。
-function recallText(memory) {
-    const auto = memory.recallRecords();
-    if (auto.length === 0)
+    + '所有记忆均为明文，可用 memory_list 查看；memory_forget 删除一条。'
+    + 'Approved + injected memories of the CURRENT session workspace are every-turn injected too. '
+    + '已审核 + 常驻注入开关打开的工作区记忆也会每轮注入（按当前会话工作区路由）。';
+// 0.5.1：`memory:recall` provider 可经 AssembleContext.agent 拿到当前会话
+// 的 header.cwd——注入 = global + 当前会话工作区的 approved+injected
+// （0.3.4 起工作区记忆就按会话 cwd 路由；provider 是同步回调，只读已
+// 打开/缓存的表，未打开时本轮工作区部分为空，由 ensureProjectOpen 预热）。
+// 0.5.2：注入经摘要化 + 预算截断（renderInjection，纯函数）防上下文膨胀。
+function recallText(memory, projectCwd, budget, summaryChars) {
+    const rendered = renderInjection(memory.recallRecords(projectCwd), budget, summaryChars);
+    if (rendered.lines.length === 0)
         return '';
-    const lines = auto.map(record => `- [memory:${String(record.id)}] ${record.content}`);
-    return `Remembered preferences and conventions — apply these:\n${lines.join('\n')}`;
+    return `Remembered preferences and conventions — apply these:\n${rendered.lines.join('\n')}`;
+}
+/** 从组装上下文取当前 agent 会话的工作区 cwd（AssembleContext.agent 由 dsh-agent 声明合并提供）。 */
+function assemblyProjectCwd(assembly) {
+    return assembly
+        ?.agent?.session?.header?.cwd;
+}
+/** 会话 header 的 cwd（session/created 事件载荷），预热 work 区表用。 */
+function sessionProjectCwd(session) {
+    const cwd = session?.meta?.cwd;
+    return typeof cwd === 'string' && cwd !== '' ? cwd : undefined;
 }
 /** 从工具执行上下文取调用会话的工作区 cwd（0.3.4 工作区路由）。 */
 function execProjectCwd(exec) {
@@ -108,7 +124,24 @@ export async function apply(ctx, config) {
     ctx.systemPrompt.context({
         name: 'memory:recall',
         order: 50,
-        text: () => recallText(memory),
+        text: (assembly) => {
+            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);
+        },
+    });
+    // 会话创建即预热对应工作区的 project 表（0.5.1）：让首轮模型请求就
+    // 能注入工作区常驻记忆（provider 同步只读已打开的表）。
+    // session/created 事件由 dsh-session 提供（可选依赖：无 session 服务
+    // 的环境不派发事件，预热由 provider 路径兜底）。
+    const emitter = ctx;
+    emitter.on?.('session/created', (session) => {
+        const cwd = sessionProjectCwd(session);
+        if (cwd !== undefined)
+            void memory.ensureProjectOpen(cwd).catch(() => { });
     });
     ctx.tools.register(defineTool({
         name: 'memory_save',
@@ -154,7 +187,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. 按关键词检索记忆（含待审核条目）。',
+        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. 限定单个命名空间.' },

package/dist/injection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * 注入渲染（0.5.2）：`memory:recall` 与面板「注入预览」共用的确定性
+ * 渲染——摘要化 + 预算截断。纯函数、无模型调用：注入行 = 每条记忆的
+ * 单行摘要（内容过长取首行截断），超出预算（字符数）时按「最近更新
+ * 优先」贪心保留，省略计数返回给 UI 提示。
+ */
+import type { MemoryRecord } from './engine.ts';
+/** 摘要截断上限（字符）：中英混合场景下 ~40-60 token。 */
+export declare const DEFAULT_SUMMARY_CHARS = 80;
+/** 注入预算（字符）：0.5.2 起默认开启，防常驻注入随记忆增长膨胀上下文。 */
+export declare const DEFAULT_INJECTION_BUDGET = 1500;
+/**
+ * 确定性摘要：取首行，超过 maxChars 截断加省略号。
+ * 空内容/空首行回退为去掉换行后的前 maxChars（保证 any 内容有摘要）。
+ */
+export declare function deriveSummary(content: string, maxChars: number): string;
+/** 一条注入行的渲染文本（与面板预览完全一致）。 */
+export declare function injectionLine(record: MemoryRecord, summaryChars: number): string;
+export interface InjectionRender {
+    /** 实际注入行（已按预算截断、按更新时间降序）。 */
+    lines: string[];
+    /** 生效的预算（字符；null = 无限制）。 */
+    budget: number | null;
+    /** 因预算被省略的候选条数（0 = 全部注入）。 */
+    omitted: number;
+    /** 实际注入的字符数（摘要 + 标记开销之和）。 */
+    chars: number;
+}
+/**
+ * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
+ * updatedAt——最近使用/更新的记忆最先），逐条累加开销直到预算用尽；
+ * 预算为 null 或非正数时全量注入（不过滤）。
+ */
+export declare function renderInjection(records: readonly MemoryRecord[], budget: number | null, summaryChars: number): InjectionRender;

package/dist/injection.js

@@ -0,0 +1,52 @@
+/**
+ * 注入渲染（0.5.2）：`memory:recall` 与面板「注入预览」共用的确定性
+ * 渲染——摘要化 + 预算截断。纯函数、无模型调用：注入行 = 每条记忆的
+ * 单行摘要（内容过长取首行截断），超出预算（字符数）时按「最近更新
+ * 优先」贪心保留，省略计数返回给 UI 提示。
+ */
+/** 摘要截断上限（字符）：中英混合场景下 ~40-60 token。 */
+export const DEFAULT_SUMMARY_CHARS = 80;
+/** 注入预算（字符）：0.5.2 起默认开启，防常驻注入随记忆增长膨胀上下文。 */
+export const DEFAULT_INJECTION_BUDGET = 1500;
+/** 单条注入行的固定标记开销（不含摘要本体）。 */
+const LINE_OVERHEAD = 27;
+/**
+ * 确定性摘要：取首行，超过 maxChars 截断加省略号。
+ * 空内容/空首行回退为去掉换行后的前 maxChars（保证 any 内容有摘要）。
+ */
+export function deriveSummary(content, maxChars) {
+    const firstLine = content.split('\n')[0].trim();
+    if (firstLine !== '') {
+        return firstLine.length <= maxChars ? firstLine : `${firstLine.slice(0, maxChars)}…`;
+    }
+    const collapsed = content.replace(/\s+/g, ' ').trim();
+    if (collapsed === '')
+        return content;
+    return collapsed.length <= maxChars ? collapsed : `${collapsed.slice(0, maxChars)}…`;
+}
+/** 一条注入行的渲染文本（与面板预览完全一致）。 */
+export function injectionLine(record, summaryChars) {
+    return `- [memory:${String(record.id).slice(0, 8)}:${record.namespace}] ${deriveSummary(record.content, summaryChars)}`;
+}
+/**
+ * 由候选记录渲染注入行：按使用序降序（lastUsedAt 优先、缺省回退
+ * updatedAt——最近使用/更新的记忆最先），逐条累加开销直到预算用尽；
+ * 预算为 null 或非正数时全量注入（不过滤）。
+ */
+export function renderInjection(records, budget, summaryChars) {
+    const ordered = [...records].sort((left, right) => (right.lastUsedAt ?? right.updatedAt) - (left.lastUsedAt ?? left.updatedAt));
+    const lines = [];
+    let chars = 0;
+    let omitted = 0;
+    for (const record of ordered) {
+        const text = injectionLine(record, summaryChars);
+        const cost = text.length + LINE_OVERHEAD;
+        if (budget !== null && budget > 0 && chars + cost > budget) {
+            omitted++;
+            continue;
+        }
+        lines.push(text);
+        chars += cost;
+    }
+    return { lines, budget: budget ?? null, omitted, chars };
+}

package/dist/remote.d.ts

@@ -29,12 +29,16 @@ export declare class MemoryGateway extends TypertRemoteService {
     /** Force-reload storage files (external edits; JsonStorageBackend has no watch). */
     reload(cwd?: string): Promise<MemoryRecord[]>;
     /**
-     * 注入预览（0.3.5）：开发者查看当前注入到 system prompt 的记忆内容
-     * ——self 自述 + 实际注入的 global approved+injected 记忆。
+     * 注入预览（0.3.5 + 0.5.2）：开发者查看当前注入到 system prompt 的记忆
+     * 内容——self 自述 + 当前会话工作区（cwd）的 approved+injected 记忆，
+     * 经摘要化 + 预算截断（与 memory:recall 同源渲染）。
      */
-    injectionPreview(): {
+    injectionPreview(cwd?: string, budget?: number | null, summaryChars?: number): Promise<{
         self: string;
-        injected: MemoryRecord[];
-    };
+        lines: string[];
+        budget: number | null;
+        omitted: number;
+        chars: number;
+    }>;
 }
 export default MemoryGateway;

package/dist/remote.js

@@ -43,6 +43,7 @@ var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn,
 import { TypertRemoteService, Remote } from '@deepseek-ai/dsh-typert-protocol';
 import { MemoryId } from "./engine.js";
 import { SELF_DESCRIPTION } from "./self.js";
+import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, renderInjection } from "./injection.js";
 /** Client-callable memory surface; registered as the `memory` Typert namespace. */
 let MemoryGateway = (() => {
     let _classSuper = TypertRemoteService;
@@ -109,11 +110,17 @@ let MemoryGateway = (() => {
             return this.ctx.memory.list({}, cwd);
         }
         /**
-         * 注入预览（0.3.5）：开发者查看当前注入到 system prompt 的记忆内容
-         * ——self 自述 + 实际注入的 global approved+injected 记忆。
+         * 注入预览（0.3.5 + 0.5.2）：开发者查看当前注入到 system prompt 的记忆
+         * 内容——self 自述 + 当前会话工作区（cwd）的 approved+injected 记忆，
+         * 经摘要化 + 预算截断（与 memory:recall 同源渲染）。
          */
-        injectionPreview() {
-            return { self: SELF_DESCRIPTION, injected: this.ctx.memory.recallRecords() };
+        async injectionPreview(cwd, budget, summaryChars) {
+            if (cwd !== undefined)
+                await this.ctx.memory.ensureProjectOpen(cwd);
+            return {
+                self: SELF_DESCRIPTION,
+                ...renderInjection(this.ctx.memory.recallRecords(cwd), budget ?? DEFAULT_INJECTION_BUDGET, summaryChars ?? DEFAULT_SUMMARY_CHARS),
+            };
         }
     };
 })();

package/dist/routes.js

@@ -1,5 +1,6 @@
 import { createRequire } from 'node:module';
 import { SELF_DESCRIPTION } from "./self.js";
+import { DEFAULT_INJECTION_BUDGET, DEFAULT_SUMMARY_CHARS, renderInjection } from "./injection.js";
 const require = createRequire(import.meta.url);
 /** Body size bound of one JSON request. */
 const MAX_BODY_BYTES = 1 << 20;
@@ -168,11 +169,20 @@ export function mountMemoryApi(ctx) {
                 ...record.keywords === undefined ? {} : { keywords: record.keywords },
             }, cwdOf(record));
         },
-        'injectionPreview': () => {
+        'injectionPreview': async (payload) => {
             const memory = ctx.get('memory');
             if (memory === undefined)
                 throw new MemoryApiError('service-unavailable', 'memory service unavailable', 503);
-            return { self: SELF_DESCRIPTION, injected: memory.recallRecords() };
+            const record = payload;
+            const cwd = cwdOf(record);
+            if (cwd !== undefined)
+                await memory.ensureProjectOpen(cwd);
+            // 0.5.2：预览与真实注入同源（renderInjection）——摘要化 + 预算截断一致
+            const budget = typeof record?.budget === 'number' && record.budget > 0
+                ? record.budget
+                : record?.budget === null ? null : DEFAULT_INJECTION_BUDGET;
+            const summaryChars = typeof record?.summaryChars === 'number' && record.summaryChars > 0 ? record.summaryChars : DEFAULT_SUMMARY_CHARS;
+            return { self: SELF_DESCRIPTION, ...renderInjection(memory.recallRecords(cwd), budget, summaryChars) };
         },
     };
     const fence = (req) => isTrusted(req, webRuntime.trustedHosts);

package/dist/self.js

@@ -18,8 +18,8 @@ const SELF_VERSION = (() => {
 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 开关打开」的记忆（常驻注入由用户控制，审核≠注入）；'
-    + '④工作区记忆按会话工作区路由，靠 memory_search 检索（含待审核条目，可先评估再引用）；'
+    + '③每轮注入 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 写入（落在待审核）。'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@max-null/dsh-memory",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Cross-session plaintext memory plugin for the DeepSeek Harness — deterministic BM25 recall, human-owned, no embeddings",
   "license": "MIT",
   "publishConfig": {