@max-null/dsh-memory 0.4.1 → 0.5.2

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;