dsh-prime-memory 0.11.0

package/dist/graph/search.js

@@ -0,0 +1,115 @@
+/**
+ * 图谱节点检索(纯函数,无 I/O):字段加权重叠计分 + 可解释命中输出。
+ *
+ * 与 L1 检索(FTS5/向量)不同,图谱节点量级是"可重建投影"的百~千级,在此
+ * 直接内存打分即可,不建倒排索引(>2k 节点再考虑预建——见规划可延后清单)。
+ *
+ * 设计要点:
+ * - 分词与 L0/L1 共用 util/text.ts 的 tokenize(jieba 词 ∪ 拉丁词 ∪ CJK 二元组),
+ *   查询与文档两侧同源;
+ * - 字段加权:name×6 / aliases×5 / tags×5 / currentState×4 / facts×4 /
+ *   relations×3 / type×2——名称是实体最强身份信号,关系词最弱(邻接噪声);
+ * - facts 只拼 active(superseded 是历史,不该让旧状态把节点拉进结果);
+ * - relations 只取 active 边(superseded 的旧关系同理);
+ * - "仅关系词命中"的结果过滤丢弃:只命中关系名的节点通常是邻接噪声
+ *   (type-only 命中仍保留,保证按"项目/工具"等类型搜索可用);
+ * - score 只用于排序,不是事实置信度;无词法命中返回空,不兜底。
+ */
+import { tokenize } from '../util/text.js';
+import { GRAPH_SEARCH_LIMIT_MAX } from './types.js';
+/** 字段权重(检索命中计分;名称最高、关系词最低)。 */
+export const GRAPH_FIELD_WEIGHTS = {
+    name: 6,
+    aliases: 5,
+    tags: 5,
+    currentState: 4,
+    facts: 4,
+    relations: 3,
+    type: 2,
+};
+/** matchedFields 的中文标签(matchReason 组装)。 */
+const FIELD_LABELS = {
+    name: '名称',
+    aliases: '别名',
+    tags: '标签',
+    currentState: '当前状态',
+    facts: '事实',
+    relations: '关系',
+    type: '类型',
+};
+const FIELD_ORDER = ['name', 'aliases', 'tags', 'currentState', 'facts', 'relations', 'type'];
+/** fact 值渲染进检索文本(数组值空格连接)。 */
+function factValueText(value) {
+    return Array.isArray(value) ? value.join(' ') : value;
+}
+/**
+ * 图谱节点检索:返回按 score 降序的命中(最多 limit 条;limit 钳制 1~20)。
+ * 候选节点 = active | disputed(superseded/archived 不进检索)。
+ */
+export function searchGraphNodes(nodes, edges, query, limit) {
+    const tokens = [...new Set(tokenize(query))];
+    const cappedLimit = Math.min(Math.max(Math.floor(limit) || 5, 1), GRAPH_SEARCH_LIMIT_MAX);
+    if (tokens.length === 0)
+        return [];
+    // nodeId → active 关系词 token 集(先建邻接表,防逐节点全量扫边)
+    const relationTokensByNode = new Map();
+    for (const edge of edges) {
+        if (edge.status !== 'active')
+            continue;
+        let set = relationTokensByNode.get(edge.fromNodeId);
+        if (!set) {
+            set = new Set();
+            relationTokensByNode.set(edge.fromNodeId, set);
+        }
+        for (const t of tokenize(edge.relation))
+            set.add(t);
+        let set2 = relationTokensByNode.get(edge.toNodeId);
+        if (!set2) {
+            set2 = new Set();
+            relationTokensByNode.set(edge.toNodeId, set2);
+        }
+        for (const t of tokenize(edge.relation))
+            set2.add(t);
+    }
+    const results = [];
+    for (const node of nodes) {
+        if (node.status !== 'active' && node.status !== 'disputed')
+            continue;
+        const fieldTokens = {
+            name: new Set(tokenize(node.name)),
+            aliases: new Set(node.aliases.flatMap((a) => tokenize(a))),
+            tags: new Set((node.tags ?? []).flatMap((t) => tokenize(t))),
+            currentState: new Set(tokenize(node.currentState)),
+            facts: new Set(node.facts
+                .filter((f) => f.status === 'active')
+                .flatMap((f) => tokenize(`${f.key} ${factValueText(f.value)}`))),
+            relations: relationTokensByNode.get(node.id) ?? new Set(),
+            type: new Set(tokenize(node.type)),
+        };
+        let score = 0;
+        const matchedFields = [];
+        const matchedTokens = new Set();
+        for (const field of FIELD_ORDER) {
+            let hits = 0;
+            for (const t of tokens) {
+                if (fieldTokens[field].has(t)) {
+                    hits++;
+                    matchedTokens.add(t);
+                }
+            }
+            if (hits > 0) {
+                score += GRAPH_FIELD_WEIGHTS[field] * hits;
+                matchedFields.push(field);
+            }
+        }
+        // 无命中跳过;仅关系词命中 = 邻接噪声,过滤丢弃(type-only 保留)
+        if (matchedFields.length === 0)
+            continue;
+        if (matchedFields.length === 1 && matchedFields[0] === 'relations')
+            continue;
+        const matchReason = `命中${matchedFields.map((f) => FIELD_LABELS[f]).join('/')}「${[...matchedTokens].slice(0, 4).join('、')}」`;
+        results.push({ node, score, matchedFields, matchReason });
+    }
+    results.sort((a, b) => b.score - a.score || (a.node.updatedAt < b.node.updatedAt ? 1 : a.node.updatedAt > b.node.updatedAt ? -1 : a.node.id < b.node.id ? -1 : 1));
+    return results.slice(0, cappedLimit);
+}

package/dist/graph/types.d.ts

@@ -0,0 +1,142 @@
+/**
+ * 知识图谱域模型与投影结果类型。
+ *
+ * 定位:图谱是 L1 记录的可重建投影,不是独立知识库——记录"发生过什么",
+ * 图谱回答"人物/项目/组织/工具/地点现在是什么状态"。每个节点/fact/边都必须
+ * 携带 sourceRecordIds 回链到 L1 记录,任何图谱结论都能沿
+ * `节点/fact → sourceRecordIds → L1 记录 → JSONL 事实源` 追溯。
+ *
+ * 图谱三表(graph_nodes/graph_edges/graph_projection_jobs)可随时 drop 重造
+ * (JSONL → L1 → 投影单向重建),因此这里的类型不承担磁盘契约职责——字段演进
+ * 只要求投影作业重跑,不像 l1_records 的 DDL 那样逐字节冻结。
+ */
+import type { MemoryFamily, MemoryRecord } from '../types.js';
+export type GraphNodeType = 'person' | 'project' | 'organization' | 'tool' | 'place';
+export type GraphRecordStatus = 'active' | 'superseded' | 'disputed' | 'archived';
+export interface GraphFact {
+    id: string;
+    key: string;
+    value: string | string[];
+    status: GraphRecordStatus;
+    validFrom?: string;
+    validTo?: string;
+    confidence: number;
+    sourceRecordIds: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GraphNode {
+    id: string;
+    name: string;
+    type: GraphNodeType;
+    aliases: string[];
+    /** 语义角色标签(检索发现与展示用),只做附加元数据,不替代稳定 type。 */
+    tags?: string[];
+    /** 由全部 active facts 重建的状态串(key: value 逐行)。 */
+    currentState: string;
+    facts: GraphFact[];
+    status: GraphRecordStatus;
+    confidence: number;
+    sourceRecordIds: string[];
+    /** 来源记录的族并集(族过滤的唯一依据):纯档会话只见本族衍生节点,
+     *  auto 会话不过滤。与记录侧 family 三级兜底同源(family ?? type 前缀推导)。 */
+    families: MemoryFamily[];
+    createdAt: string;
+    updatedAt: string;
+}
+export interface GraphEdge {
+    id: string;
+    fromNodeId: string;
+    toNodeId: string;
+    relation: string;
+    status: GraphRecordStatus;
+    validFrom?: string;
+    validTo?: string;
+    confidence: number;
+    sourceRecordIds: string[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** 模型返回的节点提案(ref 是提案内临时引用,边靠它连线)。 */
+export interface GraphNodeProjection {
+    ref: string;
+    name: string;
+    type: GraphNodeType;
+    aliases?: string[];
+    tags?: string[];
+    /** 单行状态描述(入库为 key='状态' 的 fact)。 */
+    state?: string;
+    facts?: Array<{
+        key: string;
+        value: string | string[];
+        sourceRecordIds?: string[];
+    }>;
+    validFrom?: string;
+    validTo?: string;
+    status?: GraphRecordStatus;
+    confidence?: number;
+    sourceRecordIds: string[];
+}
+export interface GraphEdgeProjection {
+    fromRef: string;
+    toRef: string;
+    relation: string;
+    validFrom?: string;
+    validTo?: string;
+    status?: GraphRecordStatus;
+    confidence?: number;
+    sourceRecordIds: string[];
+}
+export interface GraphProjectionResult {
+    reason: string;
+    nodes: GraphNodeProjection[];
+    edges: GraphEdgeProjection[];
+}
+/** 投影作业(持久化状态机 pending → running → completed/failed/dead)。 */
+export interface GraphProjectionJob {
+    id: string;
+    /** 本批唯一事实来源(L1 record id);claim 后按 id 现查记录。 */
+    sourceRecordIds: string[];
+    /** 排序优先级:数值越大越先投(新蒸馏记录 > 存量补投影,见 GRAPH_PRIORITY_NEW)。 */
+    priority: number;
+    projectorVersion: number;
+    status: 'pending' | 'running' | 'completed' | 'failed' | 'dead';
+    attempts: number;
+    /** 指数退避的最早重试时刻(epoch ms;null = 立即可取)。 */
+    nextAttemptAt: number | null;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** 图谱检索单条命中(score 只用于排序,不是事实置信度)。 */
+export interface GraphNodeSearchResult {
+    node: GraphNode;
+    score: number;
+    /** 命中发生在哪些字段(按权重降序;空数组不会出现——无命中不返回)。 */
+    matchedFields: Array<'name' | 'aliases' | 'tags' | 'currentState' | 'facts' | 'relations' | 'type'>;
+    /** 中文可解释匹配说明(面板/工具展示用)。 */
+    matchReason: string;
+}
+/** 投影上下文(claim 时装配,LLM 调用与 complete 共用同一形状)。 */
+export interface GraphProjectionContext {
+    jobId: string;
+    projectorVersion: number;
+    /** 本批唯一事实来源(L1 记录)。 */
+    records: MemoryRecord[];
+    existingNodes: GraphNode[];
+    existingEdges: GraphEdge[];
+}
+/** 投影版本号:提示词/校验语义升级时 +1,旧版本 job 全部作废重投影。 */
+export declare const GRAPH_PROJECTOR_VERSION = 1;
+/** 单 job 认领的记录数上限(批内上下文规模可控)。 */
+export declare const GRAPH_JOB_BATCH = 8;
+/** 新蒸馏记录的投影优先级(存量补投影 ≤9999,永不倒挂)。 */
+export declare const GRAPH_PRIORITY_NEW = 10000;
+/** 存量补投影的优先级(启动/周期补齐;恒低于新蒸馏)。 */
+export declare const GRAPH_PRIORITY_BACKFILL = 100;
+/** 单 job 最大尝试次数:claim 时 +1,达到即转 dead(不再重试)。 */
+export declare const GRAPH_JOB_MAX_ATTEMPTS = 3;
+/** 失败指数退避基数:第 n 次失败后 nextAttemptAt = now + base × 2^(n-1)。 */
+export declare const GRAPH_JOB_BACKOFF_BASE_MS = 60000;
+/** 单次检索返回上限的硬钳制(工具与 RPC 两侧共用同一钳制值)。 */
+export declare const GRAPH_SEARCH_LIMIT_MAX = 20;

package/dist/graph/types.js

@@ -0,0 +1,14 @@
+/** 投影版本号:提示词/校验语义升级时 +1,旧版本 job 全部作废重投影。 */
+export const GRAPH_PROJECTOR_VERSION = 1;
+/** 单 job 认领的记录数上限(批内上下文规模可控)。 */
+export const GRAPH_JOB_BATCH = 8;
+/** 新蒸馏记录的投影优先级(存量补投影 ≤9999,永不倒挂)。 */
+export const GRAPH_PRIORITY_NEW = 10000;
+/** 存量补投影的优先级(启动/周期补齐;恒低于新蒸馏)。 */
+export const GRAPH_PRIORITY_BACKFILL = 100;
+/** 单 job 最大尝试次数:claim 时 +1,达到即转 dead(不再重试)。 */
+export const GRAPH_JOB_MAX_ATTEMPTS = 3;
+/** 失败指数退避基数:第 n 次失败后 nextAttemptAt = now + base × 2^(n-1)。 */
+export const GRAPH_JOB_BACKOFF_BASE_MS = 60_000;
+/** 单次检索返回上限的硬钳制(工具与 RPC 两侧共用同一钳制值)。 */
+export const GRAPH_SEARCH_LIMIT_MAX = 20;

package/dist/hooks/capture.d.ts

@@ -0,0 +1,32 @@
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { MemoryConfig } from '../config.js';
+import type { MemoryRunner } from '../pipeline/runner.js';
+import type { SessionModeStore } from '../store/session-modes.js';
+import type { L0Store } from '../store/l0.js';
+import type { LiveSettingsHandle } from '../settings.js';
+import type { MemoryLogger } from '../types.js';
+export declare function isCaptureRelevant(type: string): boolean;
+/**
+ * 按会话缓冲轮次事件。turn 被消费后剩余前缀为空即删除 Map 条目——
+ * 条目随会话数累积是慢泄漏(每会话残留一个数组引用,宿主长跑不释放)。
+ */
+export declare class CaptureBuffers {
+    private readonly map;
+    /** 活跃缓冲条目数(诊断/冒烟用)。 */
+    get size(): number;
+    push(sid: string, event: SessionEvent): void;
+    /** 取出该 turn 的全部事件(不含 turn/start 自身);无匹配 start 时返回整个缓冲。 */
+    takeTurn(sid: string, turn: number): SessionEvent[];
+}
+/**
+ * 注册 L0 捕获。返回 L0 串行链的冲刷函数(dispose 序在关库前 await,
+ * 排队中的 turn 消息先落盘);capture 关闭时返回 undefined。
+ */
+export declare function registerCapture(ctx: Context, cfg: MemoryConfig, runner: MemoryRunner, l0: L0Store, logger: MemoryLogger, live: LiveSettingsHandle, modes: SessionModeStore): (() => Promise<void>) | undefined;
+/**
+ * 缓冲上限裁剪(防御性;RELEVANT_TYPES 过滤后基本不可达)。
+ * 铁律:进行中轮次(turn/start 之后、turn/end 之前)的事件绝不裁——
+ * 只裁最早一个未闭合 turn/start 之前的已完成前缀。
+ */
+export declare function trimBuffer(buf: SessionEvent[]): void;

package/dist/hooks/capture.js

@@ -0,0 +1,194 @@
+/**
+ * L0 捕获 Hook:订阅 session/event,按轮次缓冲 user/assistant 消息,
+ * turn/end 时清洗并交给 Runner 落盘 + 触发蒸馏。
+ *
+ * 冷启动保护:插件激活时间之前的事件不捕获(防止恢复会话时倾倒全部历史)。
+ */
+import { randomBytes } from 'node:crypto';
+import { blocksToText } from '../util/text.js';
+import { sanitizeText, shouldCaptureL0, stripCodeBlocks } from '../util/sanitize.js';
+/**
+ * 需要进缓冲的事件类型。流式 chunk(text-delta/reasoning 等)一秒钟可达数百条,
+ * 缓冲它们会把 MAX_BUFFER 撑爆、把轮次头部(turn/start + user 消息)裁掉——
+ * 2026-08-16 真实事故:长回复轮次丢失 user 消息。
+ */
+const RELEVANT_TYPES = new Set(['user/message', 'assistant/message', 'turn/start', 'turn/end']);
+export function isCaptureRelevant(type) {
+    return RELEVANT_TYPES.has(type);
+}
+const MAX_BUFFER = 500;
+/**
+ * 按会话缓冲轮次事件。turn 被消费后剩余前缀为空即删除 Map 条目——
+ * 条目随会话数累积是慢泄漏(每会话残留一个数组引用,宿主长跑不释放)。
+ */
+export class CaptureBuffers {
+    map = new Map();
+    /** 活跃缓冲条目数(诊断/冒烟用)。 */
+    get size() {
+        return this.map.size;
+    }
+    push(sid, event) {
+        let buf = this.map.get(sid);
+        if (!buf) {
+            buf = [];
+            this.map.set(sid, buf);
+        }
+        buf.push(event);
+        trimBuffer(buf);
+    }
+    /** 取出该 turn 的全部事件(不含 turn/start 自身);无匹配 start 时返回整个缓冲。 */
+    takeTurn(sid, turn) {
+        const buf = this.map.get(sid);
+        if (!buf)
+            return [];
+        const startIdx = findTurnStart(buf, turn);
+        const turnEvents = startIdx === -1 ? buf : buf.slice(startIdx + 1);
+        const rest = startIdx === -1 ? [] : buf.slice(0, startIdx);
+        if (rest.length === 0)
+            this.map.delete(sid);
+        else
+            this.map.set(sid, rest);
+        return turnEvents;
+    }
+}
+/**
+ * 注册 L0 捕获。返回 L0 串行链的冲刷函数(dispose 序在关库前 await,
+ * 排队中的 turn 消息先落盘);capture 关闭时返回 undefined。
+ */
+export function registerCapture(ctx, cfg, runner, l0, logger, live, modes) {
+    if (!cfg.capture.enabled)
+        return;
+    const startFloor = Date.now();
+    const buffers = new CaptureBuffers();
+    // L0 即时落盘链:turn/end 立刻写,不被蒸馏队列(慢 LLM 调用)阻塞;
+    // 串行化保证同轮次顺序与单次写入(进程退出时排队中的 L0 不再依赖蒸馏完成)
+    let l0Queue = Promise.resolve();
+    ctx.on('session/event', (session, event) => {
+        try {
+            const s = live.get();
+            if (!s.enabled || !s.capture)
+                return;
+            const sid = String(session.id ?? session);
+            // off 档:本会话对记忆系统完全隐身(不缓冲、不写 L0、不蒸馏)
+            if (modes.get(sid) === 'off')
+                return;
+            if (!isCaptureRelevant(event.type))
+                return;
+            if (event.time < startFloor) {
+                // 冷启动保护拦截的 user 消息记 info(罕见,但正是"整轮只剩 assistant"现象的线索)
+                if (event.type === 'user/message') {
+                    logger.info(`[memory] L0 跳过早于插件启动的 user 消息(冷启动保护,早 ${startFloor - event.time}ms)`);
+                }
+                return;
+            }
+            buffers.push(sid, event);
+            if (event.type === 'turn/end') {
+                const turn = event.data.turn;
+                const turnEvents = buffers.takeTurn(sid, turn);
+                const messages = turnEventsToMessages(turnEvents, cfg, logger);
+                if (messages.length > 0) {
+                    const roles = messages.reduce((acc, m) => {
+                        acc[m.role] = (acc[m.role] ?? 0) + 1;
+                        return acc;
+                    }, {});
+                    // 轮末档位生效(中途切档:本轮按 turn/end 时的档位蒸馏)
+                    const mode = modes.get(sid);
+                    if (mode === 'off') {
+                        logger.info(`[memory] turn=${turn} 结束时档位为关闭,本轮不落盘不蒸馏(session=${sid})`);
+                        return;
+                    }
+                    logger.info(`[memory] L0 捕获 turn=${turn} ${messages.length} 条(${Object.entries(roles)
+                        .map(([k, v]) => `${k}=${v}`)
+                        .join('/')} ,session=${sid},mode=${mode})`);
+                    // L0 立刻落盘(不等蒸馏)
+                    const n = messages.length;
+                    l0Queue = l0Queue
+                        .then(() => l0.append(sid, messages))
+                        .then(() => logger.info(`[memory] L0 落盘 ${n} 条`))
+                        .catch((err) => logger.warn(`[memory] L0 落盘失败: ${err instanceof Error ? err.message : String(err)}`));
+                    runner.enqueue(sid, messages, mode);
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(`[memory] session/event 处理失败: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    // 冲刷 = 等待串行链排空(链上每环自带 catch,永不 reject)。
+    // 注:极小概率在 await 期间又入队的新消息会落到链尾——其 JSONL 事实源照写、
+    // DB 写入由 upsert 内部兜底(关库后 warn),下次重建自愈。
+    return () => l0Queue;
+}
+/**
+ * 缓冲上限裁剪(防御性;RELEVANT_TYPES 过滤后基本不可达)。
+ * 铁律:进行中轮次(turn/start 之后、turn/end 之前)的事件绝不裁——
+ * 只裁最早一个未闭合 turn/start 之前的已完成前缀。
+ */
+export function trimBuffer(buf) {
+    if (buf.length <= MAX_BUFFER)
+        return;
+    let openStart = -1;
+    let closed = true;
+    for (let i = 0; i < buf.length; i++) {
+        const t = buf[i].type;
+        if (t === 'turn/start' && closed) {
+            openStart = i;
+            closed = false;
+        }
+        else if (t === 'turn/end') {
+            closed = true;
+            openStart = -1;
+        }
+    }
+    const floorIdx = openStart === -1 ? Math.max(0, buf.length - MAX_BUFFER) : openStart;
+    if (floorIdx > 0)
+        buf.splice(0, floorIdx);
+}
+/** 找到与 turn/end 同 turn 的最后一个 turn/start 的索引(含自身)。 */
+function findTurnStart(buf, turn) {
+    for (let i = buf.length - 1; i >= 0; i--) {
+        const e = buf[i];
+        if (e.type === 'turn/start' && e.data.turn === turn)
+            return i;
+    }
+    return -1;
+}
+/** 把轮次事件转成 L0 消息(仅真实 user 消息 + assistant 消息,清洗过滤)。 */
+function turnEventsToMessages(events, cfg, logger) {
+    const out = [];
+    for (const event of events) {
+        if (event.type === 'user/message') {
+            const msg = event.data;
+            // 只捕获真实用户输入(source.kind === 'user'),跳过插件注入上下文
+            if (msg.source?.kind !== 'user') {
+                logger.info(`[memory] L0 跳过非用户来源消息(source.kind=${msg.source?.kind ?? 'none'})`);
+                continue;
+            }
+            const content = sanitizeText(blocksToText(msg.content));
+            if (shouldCaptureL0(content)) {
+                out.push(makeMessage('user', content, event.time, cfg.capture.maxMessageChars));
+            }
+        }
+        else if (event.type === 'assistant/message') {
+            const data = event.data;
+            let content = sanitizeText(blocksToText(data.message?.content));
+            if (cfg.capture.stripCodeBlocks)
+                content = stripCodeBlocks(content);
+            if (shouldCaptureL0(content)) {
+                out.push(makeMessage('assistant', content, event.time, cfg.capture.maxMessageChars));
+            }
+        }
+    }
+    if (out.length > 0) {
+        logger.debug?.(`[memory] 轮次消息 ${events.length} 事件 → ${out.length} 条(清洗过滤后)`);
+    }
+    return out;
+}
+function makeMessage(role, content, timestamp, maxChars) {
+    return {
+        id: `msg_${Date.now()}_${randomBytes(3).toString('hex')}`,
+        role,
+        content: content.slice(0, maxChars),
+        timestamp,
+    };
+}

package/dist/hooks/recall.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 召回 Hook(消息侧注入版,ADR-0001):
+ * 1. agent/pre-step(waterfall,prepend 注册):有新的用户来源消息到达的步骤
+ *    (轮首 claim 或 steering 插话)→ 检索 L1 → 以合成消息形式注入到用户消息之前。
+ *    注入消息携带插件来源(form: 'recall'),对用户可见、随会话历史持久累积——
+ *    这就是"记忆生效"的显式提示(dsh-time-context 同款官方范式)。
+ *    纯工具步透传;召回超时(recall.timeoutMs 总预算)跳过本轮,绝不阻塞对话。
+ * 2. agent/created:在 agent 作用域注册动态上下文 provider(L3 画像 + L2 场景导航 +
+ *    工具指南——系统提示只保留稳定内容;指南三条件门控:工具开启 && 有内容)。
+ *
+ * 注入内容使用 <relevant-memories> 标签包裹(模型侧语义边界 + 助手回显剥离锚点),
+ * 召回预算(单条/整轮)超限截断并引导模型用记忆工具查全文。
+ * L0 防污染零成本:capture 侧只收 source.kind === 'user' 的消息,注入消息天然被排除。
+ *
+ * 注意:PromptContext.text 是同步函数,画像/场景导航这类异步文件读取必须走内存缓存,
+ * 由定时刷新 + 管线更新后的主动失效来更新。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { MemoryConfig } from '../config.js';
+import type { LiveSettingsHandle } from '../settings.js';
+import type { L1Store } from '../store/l1.js';
+import type { PersonaStore } from '../store/persona.js';
+import type { SceneStore } from '../store/scenes.js';
+import type { SessionModeStore } from '../store/session-modes.js';
+import type { MemoryLogger } from '../types.js';
+import { type OccupancyLedger } from '../util/context-occupancy.js';
+/**
+ * 从会话消息构建召回查询(纯函数):末尾 N 条 + 总长截断,空输入返回空串。
+ * 全史拼接会让 MATCH 表达式随会话长度线性膨胀(整会话累计二次方成本)。
+ */
+export declare function buildRecallQuery(messages: Array<{
+    content: unknown;
+}>, tailMessages?: number, maxChars?: number): string;
+/** 单会话召回统计(悬浮卡信息区数据源;每轮 O(1) 记账,agent/disposed 清理)。
+ *  口径声明:这是"注入统计"而非 bench 的离线 recall@k——运行时没有 ground truth,
+ *  命中率 = hitTurns / injectedTurns。去重语义:全量压制轮计入 hitTurns
+ *  (相关记忆已在模型上下文里,本质是命中而非未命中),injectedTurns 仍计全部
+ *  发生过检索的轮次(保住分母语义与悬浮卡口径连续性)。 */
+import type { RecallSessionStats } from '../contract.js';
+export type { RecallSessionStats } from '../contract.js';
+/** 新建零值统计(首次出现的会话)。 */
+export declare function emptyRecallStats(now?: number): RecallSessionStats;
+export interface RecallHooks {
+    /** 管线更新后调用:画像/场景缓存立即失效并异步刷新。 */
+    invalidateProfile(): void;
+    /** 会话召回统计只读视图(未发生过检索的会话返回 undefined)。 */
+    stats(sessionId: string): RecallSessionStats | undefined;
+    /** 记忆占用账本只读出口:内存优先,miss 时从流水复生(重启后历史会话);从未注入返回 null。 */
+    occupancy(sessionId: string): OccupancyLedger | null;
+    /**
+     * 稳定区份额估算(旧会话回填):按当前画像/导航/指南组词折算 token,
+     * 纯读不记账——旧会话系统提示里"现在大约坐着多少稳定区"的最佳可得估计。
+     */
+    estimateProfileTokens(agentId: string): number;
+    /** 召回份额回填:live 会话 surface 现扫本插件注入,miss 时读盘上日志兜底;
+     *  均不可得返回 null。 */
+    estimateRecallTokens(sessionId: string): Promise<number | null>;
+}
+export declare function registerRecall(ctx: Context, cfg: MemoryConfig, stores: {
+    l1: L1Store;
+    scenes: Record<'chat' | 'work', SceneStore>;
+    persona: Record<'chat' | 'work', PersonaStore>;
+}, logger: MemoryLogger, live: LiveSettingsHandle, modes: SessionModeStore, dataDir: string): RecallHooks;