@aipack-ai/memory 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,836 @@
+import * as _aipack_ai_agent from '@aipack-ai/agent';
+import { BaseExtension, RuntimeHooks, ExtensionContext, BaseTransformer, ContextResource, Extension, ContextTransformer, Tool } from '@aipack-ai/agent';
+export { ContextTransformer, Extension, Tool, ToolResult } from '@aipack-ai/agent';
+
+/**
+ * aipack-memory - 核心类型定义
+ *
+ * 记忆条目、存储契约、检索结果、Embedder 与摘要函数接口。
+ * 不依赖任何外部实现，是整个插件的类型基础。
+ */
+/** 记忆来源 */
+type MemorySource = 'capture' | 'tool' | 'consolidation';
+/**
+ * 单条记忆条目。
+ * 参考 agentmemory：每条记忆含置信度、生命周期、检索统计与可选向量。
+ */
+interface MemoryEntry {
+    /** 唯一标识 */
+    id: string;
+    /** 记忆正文 */
+    content: string;
+    /** 关键词 / 概念标签（用于 BM25 索引与展示） */
+    concepts: string[];
+    /** 置信度 0..1（捕获默认 0.6，摘要 0.8，合并后累加并截断到 1，可衰减） */
+    confidence: number;
+    /** 来源 */
+    source: MemorySource;
+    /** 来源会话 key（capture 时记录） */
+    sessionKey?: string;
+    /** 创建时间（ms 时间戳） */
+    createdAt: number;
+    /** 最后更新时间（ms 时间戳） */
+    updatedAt: number;
+    /** 最后一次被检索注入的时间 */
+    lastRecalledAt?: number;
+    /** 被检索注入次数 */
+    recallCount: number;
+    /** 可选向量（当配置 Embedder 时填充，用于混合检索） */
+    embedding?: number[];
+    /** 过期时间（ms 时间戳），由 save 时的 ttlMs 换算，或直接指定 */
+    expiresAt?: number;
+    /** 额外元数据 */
+    meta?: Record<string, unknown>;
+}
+type MatchedBy = 'bm25' | 'embedding' | 'hybrid';
+interface MemorySearchResult {
+    entry: MemoryEntry;
+    /** 分数：默认检索为 min-max 归一化 0..1；raw 模式（合并器用）为 BM25/cosine 原始分数 */
+    score: number;
+    matchedBy: MatchedBy;
+}
+/**
+ * 向量化接口（可选）。
+ * 默认不提供，退化为纯 BM25 检索（零依赖、零 API Key）。
+ * 用户可自行实现以接入 ollama / @huggingface/transformers / OpenAI embedding 等。
+ */
+interface Embedder {
+    /** 将文本转为向量 */
+    embed(text: string): Promise<number[]>;
+    /** 向量维度（可选，用于校验） */
+    dimension?: number;
+}
+/**
+ * 可选摘要函数（默认关闭，零 token 消耗）。
+ * 提供后，capture 会把整轮对话压成一句精炼记忆与可选概念。
+ * 返回 null 表示放弃摘要（回退到零-LLM 抽取）。
+ */
+type SummarizeFn = (input: {
+    userMessage: string;
+    assistantContent: string;
+    toolsUsed: string[];
+}) => Promise<{
+    summary: string;
+    concepts?: string[];
+} | null>;
+/** Consolidator 的最小契约（避免 store ↔ consolidator 循环依赖） */
+interface ConsolidatorLike {
+    run(options?: ConsolidateOptions): Promise<{
+        merged: number;
+        pruned: number;
+    }>;
+}
+interface ConsolidateOptions {
+    /** 相似度阈值，>= 该值视为可合并（默认 0.85）。按检索原始分数（BM25 raw / cosine）判定 */
+    similarityThreshold?: number;
+    /** 合并后记忆数量上限（保留置信度最高的，默认无限制） */
+    maxMemories?: number;
+    /** 最大保留时长（ms），超过则修剪 */
+    maxAgeMs?: number;
+    /** 最低置信度，低于则修剪（默认 0.1） */
+    minConfidence?: number;
+}
+/** 文件存储选项 */
+interface FileMemoryStoreOptions {
+    /** 存储根目录（支持 ~ 开头，默认 <cwd>/.aipack/memory） */
+    baseDir?: string;
+    /** 过期时间（ms），超过 updatedAt 的记忆在加载时惰性清理 */
+    maxAge?: number;
+}
+/** 保存入参：content/concepts/confidence/source 必填，其余可选；ttlMs 换算为 expiresAt */
+type MemorySaveInput = Pick<MemoryEntry, 'content' | 'concepts' | 'confidence' | 'source'> & Partial<Omit<MemoryEntry, 'content' | 'concepts' | 'confidence' | 'source'>> & {
+    /** 可选 TTL（ms）：保存时换算为 expiresAt = createdAt + ttlMs（优先于显式 expiresAt） */
+    ttlMs?: number;
+};
+/** 记忆系统事件（失败/整理等关键节点，供外部监控与日志） */
+type MemoryEvent = {
+    type: 'store:load';
+    loaded: number;
+    skipped: number;
+    ms: number;
+} | {
+    type: 'store:corrupt';
+    file: string;
+} | {
+    type: 'embedding:error';
+    id?: string;
+    error: string;
+} | {
+    type: 'capture:failed';
+    sessionKey?: string;
+    error: string;
+} | {
+    type: 'consolidate:failed';
+    error: string;
+} | {
+    type: 'consolidate';
+    merged: number;
+    pruned: number;
+    ms: number;
+} | {
+    type: 'prune';
+    removed: number;
+};
+/** 事件接收器（可注入；默认把失败类事件打印到 console.warn） */
+type MemoryEventSink = (event: MemoryEvent) => void;
+/** 记忆库统计快照 */
+interface MemoryStats {
+    /** 记忆总数 */
+    count: number;
+    /** 带向量的条目数 */
+    embeddingCount: number;
+    /** 按来源计数 */
+    bySource: Record<MemorySource, number>;
+    /** 平均置信度 0..1 */
+    avgConfidence: number;
+    /** 检索注入总次数 */
+    recallTotal: number;
+    /** 最近一次被检索注入的时间 */
+    lastRecalledAt?: number;
+    /** 最近一次合并（consolidate）时间 */
+    lastConsolidatedAt?: number;
+}
+/**
+ * 记忆存储适配器接口。
+ * 实现需自行保证 search 的检索能力（内置 BM25Retriever 可复用）。
+ */
+interface MemoryStore {
+    /**
+     * 保存记忆（新建或更新）。
+     * 调用方可省略 id/createdAt/updatedAt/recallCount，由 store 填充。
+     */
+    save(entry: MemorySaveInput): Promise<MemoryEntry>;
+    /** 读取单条 */
+    get(id: string): Promise<MemoryEntry | null>;
+    /** 删除单条，返回是否删除成功 */
+    delete(id: string): Promise<boolean>;
+    /** 列出记忆（按 updatedAt 降序，可限数量） */
+    list(limit?: number): Promise<MemoryEntry[]>;
+    /** 基于查询检索（默认纯 BM25） */
+    search(query: string, limit?: number): Promise<MemorySearchResult[]>;
+    /**
+     * 基于向量检索（可选能力）：返回 cosine 降序的 top-N。
+     * 未配置 embedding 时返回空数组。默认 store 在 config embedder 后可用。
+     */
+    searchVectors(queryVec: number[], limit?: number): Promise<MemorySearchResult[]>;
+    /** 更新某条记忆的检索统计（lastRecalledAt / recallCount++） */
+    touchRecall(id: string, at?: number): Promise<void>;
+    /** 合并相似记忆 + 修剪过期/低置信度，返回合并与修剪计数 */
+    consolidate(options?: ConsolidateOptions): Promise<{
+        merged: number;
+        pruned: number;
+    }>;
+    /** 仅修剪（按 maxAge / minConfidence / expiresAt），返回修剪数量 */
+    prune(options?: {
+        maxAgeMs?: number;
+        minConfidence?: number;
+    }): Promise<number>;
+    /** 记忆总数 */
+    count(): Promise<number>;
+    /** 注入合并器（由插件层装配，用于 consolidate()） */
+    setConsolidator(consolidator: ConsolidatorLike): void;
+    /** 记录最近一次合并时间（驱动增量合并的候选窗口） */
+    markConsolidated(at?: number): void;
+    /** 统计快照（可观测性） */
+    stats(): Promise<MemoryStats>;
+    /** 释放资源（热重载场景；当前实现为无操作占位） */
+    dispose(): void;
+}
+
+/**
+ * 混合检索器：BM25（必选）+ 可选 Embedding（向量）双路独立召回后加权融合。
+ *
+ * 默认无 embedder 时退化为纯 BM25。
+ * 有 embedder 时：
+ *   - BM25 路独立召回 top-`limit*3`
+ *   - 向量路独立召回 top-`limit*3`（依赖 store 的 searchVectors / VectorIndex，
+ *     不受 BM25 候选池封顶 —— 修复「向量召回被 BM25 top-K 限制」问题）
+ *   - 两路各自 min-max 归一化后按权重融合：final = w_bm25 * bm25_norm + w_embed * cos_norm
+ *   - 过滤 < minScore，截 limit
+ *
+ * 兼容路径：
+ *   - 配置了 embedder 但 store 不支持向量检索（无 searchVectors 能力）：
+ *     退化为「BM25 候选 + 向量重排」（旧行为），并在 minScore 处诚实标注。
+ */
+
+/**
+ * 检索器最小契约：任何具备 search(query, limit) 的对象均可作为 BM25 候选源。
+ * BM25Retriever 天然满足此接口；插件层也可用 StoreBackedRetriever 包装自定义 store。
+ */
+interface RetrieverLike {
+    search(query: string, limit?: number): Promise<MemorySearchResult[]>;
+}
+/** 向量检索源契约（由 store 实现，或插件层包装） */
+interface VectorSearchLike {
+    searchVectors(queryVec: number[], limit?: number): Promise<MemorySearchResult[]>;
+}
+interface HybridRetrieverOptions {
+    /** BM25 候选源（BM25Retriever 或任何 RetrieverLike 实现） */
+    bm25: RetrieverLike;
+    /** 可选向量源（store.searchVectors）；有 embedder 但无此源时退化为候选重排 */
+    vector?: VectorSearchLike;
+    embedder?: Embedder;
+    /** BM25 权重，默认 0.5 */
+    bm25Weight?: number;
+    /** embedding 权重，默认 0.5 */
+    embedWeight?: number;
+    /** 注入阶段最低分数阈值，默认 0.1 */
+    minScore?: number;
+}
+interface HybridSearchOptions {
+    /** 覆盖默认 minScore（如注入转换器携带自己的阈值，不再篡改共享 retriever） */
+    minScore?: number;
+    /**
+     * 原始分数模式：不做 min-max 归一化，保留 BM25 / cosine 原始分数。
+     * 供合并器等需要「绝对相似度阈值」的场景使用 —— min-max 会把同一查询内
+     * 的次优分数压到 0，使绝对阈值（如 0.85）失去意义。
+     */
+    raw?: boolean;
+}
+declare class HybridRetriever {
+    bm25: RetrieverLike;
+    vector?: VectorSearchLike;
+    embedder?: Embedder;
+    bm25Weight: number;
+    embedWeight: number;
+    minScore: number;
+    constructor(options: HybridRetrieverOptions);
+    /** 是否启用了向量检索 */
+    get hasEmbedder(): boolean;
+    search(query: string, limit?: number, opts?: HybridSearchOptions): Promise<MemorySearchResult[]>;
+    /** 单路（纯 BM25）：归一化 + 过滤 + 截断 */
+    private fuseSingle;
+    /** 候选重排（兼容路径）：BM25 候选 + 向量 cosine 加权融合 */
+    private rerank;
+    /**
+     * 原始分数融合（raw 模式）：保留检索源原始分数，不做 min-max 归一化，
+     * 供合并器按「绝对相似度阈值」判定可合并项。双路命中时取 max
+     * （任一来源判定相似即相似），避免归一化把次优分数抹平。
+     *
+     * 量纲说明：BM25 分数在 BM25Retriever 层已按 Σidf 归一化到 [0,1]
+     * （完全同文≈1），cosine 本身在 [0,1]，因此这里的绝对阈值（如 0.85）
+     * 对两路统一成立。
+     */
+    private fuseRaw;
+    /** 双路独立召回融合：按 id 取并集，加权求和，再按权重和归一化 */
+    private fuseDual;
+}
+
+/**
+ * 记忆捕获扩展。
+ *
+ * 在 Runtime 生命周期中「静默」捕获每轮对话要点并存为可检索记忆。
+ * 参考 agentmemory 的 capture 阶段。
+ *
+ * 机制：
+ *   - beforeRun：暂存本轮用户消息（单会话，Runtime 持有唯一 sessionKey）。
+ *   - done：与本轮结果配对捕获。sessionKey 来自 ExtensionContext（Runtime 级），
+ *     与结果配对写入记忆库。框架保证同一 Runtime 的 run 串行执行，无并发错配。
+ *   - failed：本轮失败不捕获（仅成功回合入库），无残留状态需清理。
+ *
+ * 每 consolidateEvery 次捕获触发一次合并。
+ */
+
+interface CaptureOptions {
+    enabled?: boolean;
+    /** 可选 LLM 摘要函数（默认关闭，零 token） */
+    summarizeFn?: SummarizeFn;
+    /** 最小用户消息长度（小于则跳过捕获），默认 12 */
+    minLength?: number;
+    /** 概念数上限，默认 8 */
+    maxConcepts?: number;
+    /** content 最大字符数，默认 2000 */
+    maxContentChars?: number;
+    /** 每 N 次捕获触发一次 consolidate（0=不自动，默认 0） */
+    consolidateEvery?: number;
+    /** 捕获记忆 TTL（ms），过期后 prune 时清理 */
+    ttlMs?: number;
+    /** 事件接收器（捕获失败等） */
+    onEvent?: MemoryEventSink;
+}
+declare class MemoryCaptureExtension extends BaseExtension {
+    readonly name = "memory-capture";
+    private store;
+    private summarizeFn?;
+    private minLength;
+    private maxConcepts;
+    private maxContentChars;
+    private consolidateEvery;
+    private ttlMs?;
+    private onEvent?;
+    /** 本轮待捕获的用户消息（sessionKey -> 请求信息） */
+    private pending;
+    /** 捕获计数（用于触发 consolidate） */
+    private captureCount;
+    constructor(store: MemoryStore, options?: CaptureOptions);
+    protected setup(hooks: RuntimeHooks, context: ExtensionContext): void;
+    private captureFromResult;
+}
+
+interface InjectionOptions {
+    /** 注入 top-K，默认 5 */
+    maxMemories?: number;
+    /** 最低分数阈值，默认 0.1 */
+    minScore?: number;
+    /** 可选：对检索 query 做变换（如抽取提问主体） */
+    queryTransform?: (latestUserText: string) => string;
+    /** 可选：命中记忆后的回调（插件层装配为 store.touchRecall，更新检索统计） */
+    onRecall?: (ids: string[]) => void | Promise<void>;
+}
+declare class MemoryInjectionTransformer extends BaseTransformer {
+    readonly name = "memory-injection";
+    private retriever;
+    private maxMemories;
+    private minScore;
+    private queryTransform?;
+    private onRecall?;
+    constructor(retriever: HybridRetriever, options?: InjectionOptions);
+    protected run(resources: ContextResource[], _context: _aipack_ai_agent.TransformContext): Promise<ContextResource[]>;
+    /** 从资源中抽取纯文本（兼容 string 与 ContentBlock[]） */
+    private extractUserText;
+    private isTextBlock;
+    /** 剥除单个资源中的 sentinel 块，返回新资源（若无需剥除返回原资源） */
+    private stripResource;
+    /** 把记忆块前插进资源内容 */
+    private injectIntoResource;
+    /** 重建资源（保持 id/type/role/timestamp/dependencies/meta/pinned，替换 content） */
+    private rebuildResource;
+}
+
+/**
+ * 插件聚合入口：createMemoryPlugin(options) → { store, retriever, extensions, transformers, tools, install() }
+ *
+ * 把 MemoryStore + HybridRetriever + MemoryCaptureExtension + MemoryInjectionTransformer
+ * + Consolidator + memory tools 装配成一个开箱即用的插件。
+ *
+ * 用法（aipack.config.js）：
+ *   import { createMemoryPlugin } from '@aipack-ai/memory';
+ *   const mem = createMemoryPlugin({ baseDir: '~/.aipack/memory' });
+ *   const r = mem.install();
+ *   export default {
+ *     ...,                          // provider, model, systemPrompt, sessions...
+ *     extensions: r.extensions,
+ *     transformers: r.transformers,
+ *     tools: r.tools,
+ *   };
+ *
+ * 默认配置：FileMemoryStore（持久化）+ 纯 BM25 检索（零依赖）+ 自动捕获 + 自动注入 + 4 个记忆工具。
+ * 提供 embedder 后自动升级为 BM25 + 向量混合检索（双路独立召回）；提供 summarizeFn 后 capture 走 LLM 摘要。
+ */
+
+interface MemoryPluginOptions {
+    /** FileMemoryStore 存储目录（支持 ~ 开头），默认 <cwd>/.aipack/memory */
+    baseDir?: string;
+    /** 自定义 store（覆盖默认 FileMemoryStore；需自行保证 search 能力） */
+    store?: MemoryStore;
+    /** 注入 top-K 上限，默认 5 */
+    maxMemories?: number;
+    /** 最低相关度阈值，默认 0.1 */
+    minScore?: number;
+    /** 捕获开关 / 选项，默认 true */
+    capture?: boolean | CaptureOptions;
+    /** 注入开关 / 选项，默认 true */
+    inject?: boolean | InjectionOptions;
+    /** 记忆工具开关，默认 true */
+    tools?: boolean;
+    /** 可选向量化器，配置后启用 BM25 + 向量混合检索 */
+    embedder?: Embedder;
+    /** 可选 LLM 摘要函数，配置后 capture 走 LLM 摘要（默认零-LLM 要点抽取） */
+    summarizeFn?: SummarizeFn;
+    /** 每 N 次捕获自动触发一次 consolidate（0=不自动，默认 0） */
+    consolidateEvery?: number;
+    /** 捕获记忆 TTL（ms），过期后 prune 清理 */
+    captureTtlMs?: number;
+    /** save_memory 工具保存的记忆 TTL（ms），过期后 prune 清理 */
+    toolTtlMs?: number;
+    /** 事件接收器（失败/整理/统计等关键节点；默认打印失败告警） */
+    onEvent?: MemoryEventSink;
+}
+interface MemoryPlugin {
+    /** 装配好的 store（可直接编程式调用 save/search/consolidate 等） */
+    store: MemoryStore;
+    /** 装配好的混合检索器 */
+    retriever: HybridRetriever;
+    /** 扩展列表（capture） */
+    extensions: Extension[];
+    /** 转换器列表（injection） */
+    transformers: ContextTransformer[];
+    /** 工具列表（save/search/list/delete） */
+    tools: Tool[];
+    /** 返回 { extensions, transformers, tools }，供 aipack.config.js 展开 */
+    install(): {
+        extensions: Extension[];
+        transformers: ContextTransformer[];
+        tools: Tool[];
+    };
+    /** 释放资源（热重载场景） */
+    dispose(): void;
+}
+declare function createMemoryPlugin(options?: MemoryPluginOptions): MemoryPlugin;
+
+/**
+ * BM25 倒排索引与检索器（零依赖）。
+ *
+ * 经典 BM25 公式：
+ *   score(q, d) = Σ_t idf(t) * (tf(t,d) * (k1+1)) / (tf(t,d) + k1*(1 - b + b*|d|/avgdl))
+ *   idf(t) = ln((N - df(t) + 0.5) / (df(t) + 0.5) + 1)
+ *
+ * 分数不归一化（由 HybridRetriever 负责 min-max 归一化）。
+ */
+
+interface BM25Options {
+    /** 词频饱和参数，默认 1.5 */
+    k1?: number;
+    /** 文档长度归一化参数，默认 0.75 */
+    b?: number;
+}
+declare class BM25Index {
+    private k1;
+    private b;
+    /** 文档集合 */
+    private docs;
+    /** 倒排表：token -> 文档 id 集合 */
+    private inverted;
+    private totalLength;
+    constructor(options?: BM25Options);
+    /** 平均文档长度 */
+    private get avgdl();
+    /** 文档总数 */
+    get size(): number;
+    /** 添加或替换文档（同 id 覆盖） */
+    add(id: string, tokens: string[]): void;
+    /** 移除文档 */
+    remove(id: string): void;
+    /** 清空索引 */
+    clear(): void;
+    /**
+     * 检索：返回 top-N 的 {id, score}（按分数降序）。
+     * 只扫描 query token 命中的文档，避免全量计算。
+     */
+    search(queryTokens: string[], limit?: number): Array<{
+        id: string;
+        score: number;
+    }>;
+    /**
+     * 单个 token 的 idf（未出现返回 0）。
+     * 供上层计算查询的理论满分（完全同文、tf=1、len≈avgdl 时的分数），
+     * 把无界 BM25 原始分规范化为 [0,1] 相似度。
+     */
+    idf(token: string): number;
+}
+/**
+ * 基于 BM25Index 的检索器，包装为 MemorySearchResult。
+ * entries 与 index 由外部维护（store 持有并增量同步）。
+ *
+ * 分数语义：BM25 原始分无界（取决于词频/idf 与库规模），与 embedding 的
+ * cosine 相似度（0..1）量纲不匹配 —— 若直接作为绝对相似度与
+ * similarityThreshold（如 0.85）比较，合并几乎永远不会触发。这里除以
+ * 查询的理论满分（Σidf，即完全同文时的分数）并截断到 [0,1]：
+ * 完全同文 ≈ 1，部分命中按比例衰减，使绝对阈值对 BM25 / cosine 统一成立。
+ * 该变换是单调的，对普通检索路径的 min-max 归一化幂等（排序不变）。
+ */
+declare class BM25Retriever {
+    private index;
+    private entries;
+    constructor(index: BM25Index, entries: Map<string, MemoryEntry>);
+    search(query: string, limit?: number): Promise<MemorySearchResult[]>;
+}
+
+/**
+ * 内存索引：维护 entries 集合 + BM25 倒排索引，供两个 store 复用。
+ *
+ * 职责：get / list / count / search / add / remove。
+ * 不负责持久化（由具体 store 处理）。
+ */
+
+declare class MemoryIndex {
+    private entries;
+    private index;
+    /** 独立向量索引：保证向量召回不被 BM25 候选池封顶 */
+    private vectors;
+    private retriever;
+    /** 共享底层索引与条目表，返回一个 BM25Retriever（与 store 实时同步） */
+    getRetriever(): BM25Retriever;
+    get(id: string): MemoryEntry | null;
+    /** 全部条目（updatedAt 降序） */
+    all(): MemoryEntry[];
+    list(limit?: number): MemoryEntry[];
+    count(): number;
+    /** 索引内容 = content + concepts（提升概念命中） */
+    add(entry: MemoryEntry): void;
+    remove(id: string): boolean;
+    clear(): void;
+    search(query: string, limit?: number): Promise<MemorySearchResult[]>;
+    searchVectors(queryVec: number[], limit?: number): Promise<MemorySearchResult[]>;
+    /** 统计快照 */
+    stats(): MemoryStats;
+}
+
+/**
+ * 文件记忆存储（默认实现）。
+ *
+ * 每条记忆一个 JSON 文件：<baseDir>/<encodeURIComponent(id)>.json。
+ * 写入采用 temp + rename 原子替换（镜像 aipack FileSessionStorage）。
+ * 内存缓存 MemoryIndex + BM25 增量索引；首次访问时懒加载并按 maxAge/expiresAt 惰性清理。
+ *
+ * 并发安全：同 id 的写操作（save/delete/touchRecall）经 keyed mutex 串行，
+ * 避免 read-modify-write 竞态（如 embedding 计算期间丢失另一路更新）。
+ *
+ * 加载优化：懒加载时并发批量读文件（默认 64 并发），避免逐文件串行 IO；
+ * 检索要求条目常驻内存（BM25 倒排 + 向量索引），内存占用与记忆规模成正比
+ * （详见 README 限制说明）。
+ */
+
+declare class FileMemoryStore implements MemoryStore {
+    private baseDir;
+    private maxAge?;
+    private idx;
+    private loaded;
+    private loading;
+    private consolidator?;
+    private embedder?;
+    private onEvent?;
+    /** 同 id 写互斥（save/delete/touchRecall） */
+    private writeLocks;
+    private lastConsolidatedAt?;
+    constructor(options?: FileMemoryStoreOptions & {
+        index?: MemoryIndex;
+        embedder?: Embedder;
+        onEvent?: MemoryEventSink;
+    });
+    get dir(): string;
+    setConsolidator(consolidator: ConsolidatorLike): void;
+    /** 懒加载：读取目录所有 JSON → 内存索引。并发安全。 */
+    private ensureLoaded;
+    private entryPath;
+    private writeEntry;
+    save(entry: MemorySaveInput): Promise<MemoryEntry>;
+    get(id: string): Promise<MemoryEntry | null>;
+    delete(id: string): Promise<boolean>;
+    list(limit?: number): Promise<MemoryEntry[]>;
+    search(query: string, limit?: number): Promise<MemorySearchResult[]>;
+    searchVectors(queryVec: number[], limit?: number): Promise<MemorySearchResult[]>;
+    touchRecall(id: string, at?: number): Promise<void>;
+    consolidate(options?: ConsolidateOptions): Promise<{
+        merged: number;
+        pruned: number;
+    }>;
+    prune(options?: {
+        maxAgeMs?: number;
+        minConfidence?: number;
+    }): Promise<number>;
+    count(): Promise<number>;
+    markConsolidated(at?: number): void;
+    stats(): Promise<MemoryStats>;
+    dispose(): void;
+}
+declare function createFileMemoryStore(options?: FileMemoryStoreOptions): MemoryStore;
+
+/**
+ * 内存记忆存储（测试与临时场景）。
+ * 进程退出即丢失，无持久化。API 与 FileMemoryStore 完全一致。
+ *
+ * 并发安全：同 id 的写操作（save/delete/touchRecall）经 keyed mutex 串行，
+ * 避免 embedder 异步计算期间的 read-modify-write 竞态；跨 id 互不阻塞。
+ */
+
+/** 填充默认字段（id / createdAt / updatedAt / recallCount / expiresAt） */
+declare function finalizeEntry(entry: MemorySaveInput, now?: number): MemoryEntry;
+interface InMemoryStoreOptions {
+    /** 可选向量化器：配置后 save 时自动计算 embedding（供混合检索） */
+    embedder?: Embedder;
+    /** 事件接收器（失败/整理等关键节点） */
+    onEvent?: MemoryEventSink;
+}
+declare class InMemoryStore implements MemoryStore {
+    private idx;
+    private consolidator?;
+    private embedder?;
+    private onEvent?;
+    private writeLock;
+    private lastConsolidatedAt?;
+    constructor(options?: InMemoryStoreOptions);
+    setConsolidator(consolidator: ConsolidatorLike): void;
+    save(entry: MemorySaveInput): Promise<MemoryEntry>;
+    get(id: string): Promise<MemoryEntry | null>;
+    delete(id: string): Promise<boolean>;
+    list(limit?: number): Promise<MemoryEntry[]>;
+    search(query: string, limit?: number): Promise<MemorySearchResult[]>;
+    searchVectors(queryVec: number[], limit?: number): Promise<MemorySearchResult[]>;
+    touchRecall(id: string, at?: number): Promise<void>;
+    consolidate(options?: ConsolidateOptions): Promise<{
+        merged: number;
+        pruned: number;
+    }>;
+    prune(options?: {
+        maxAgeMs?: number;
+        minConfidence?: number;
+    }): Promise<number>;
+    count(): Promise<number>;
+    markConsolidated(at?: number): void;
+    stats(): Promise<MemoryStats>;
+    dispose(): void;
+}
+declare function createInMemoryStore(): MemoryStore;
+
+/**
+ * 分词器：支持 latin（小写化 + 按非字母数字分割）与 CJK（逐字符）。
+ * 零依赖，适配中英文混合文本的 BM25 索引。
+ */
+/** 判断字符是否为 CJK 文字：汉字（含扩展/兼容区）、日本假名、韩国谚文 */
+declare function isCJK(ch: string): boolean;
+/**
+ * 常见停用词（中英文小集合），用于概念抽取去停用词。
+ * BM25 索引本身不去停用词（保留其 IDF 权重），仅概念抽取时过滤。
+ */
+declare const STOPWORDS: Set<string>;
+/**
+ * 分词器：支持 latin（小写化 + 按非字母数字分割）与 CJK（字符 bigram）。
+ * 零依赖，适配中日韩英混合文本的 BM25 索引。
+ *
+ * CJK 采用「相邻两字 bigram」而非逐字 unigram：
+ *   - bigram 区分度远高于单字（「数据库」vs「数据科学」共享「数据」但不再全靠
+ *     「数/据」这种高 df 低 idf 的单字强匹配）；
+ *   - 奇数长度 CJK 串尾部遗留单字，保证单字查询仍可命中。
+ * 支持汉字（含扩展/兼容）、日文假名、韩文谚文。
+ */
+/**
+ * 将文本切分为 token 数组。
+ * - latin 部分：小写化后按非字母数字字符分割。
+ * - CJK 部分：相邻两字 bigram（奇数串尾部补单字）。
+ * - 标点 / 空白忽略。
+ */
+declare function tokenize(text: string): string[];
+/** 概念抽取：返回非停用词 token 的频次 top-N（用于记忆 concepts 字段） */
+declare function extractConcepts(text: string, maxConcepts?: number): string[];
+
+/**
+ * Embedder 接口与余弦相似度工具。
+ *
+ * 默认不提供任何 embedder 实现（零依赖、零 API Key）。
+ * 用户可自行实现 Embedder 接入 ollama / @huggingface/transformers / OpenAI 等。
+ */
+
+/** 余弦相似度。任一为零向量返回 0。 */
+declare function cosine(a: number[], b: number[]): number;
+/**
+ * 将一组分数 min-max 归一化到 0..1。
+ * 单元素或全相同时返回等分（避免除零）。
+ */
+declare function minMaxNormalize(scores: number[]): number[];
+
+/**
+ * VectorIndex —— 零依赖简化 ANN（近似最近邻）向量索引。
+ *
+ * 用途：为混合检索提供「独立于 BM25 的向量召回」。
+ * 之前向量检索被 BM25 top-K 候选池封顶，本索引保证向量路可独立召回语义相似
+ * 而关键词不重叠的记忆。
+ *
+ * 策略（按规模取舍）：
+ *   - 默认：精确 brute-force cosine（预计算范数），中小规模（< 5 万条）足够快；
+ *   - 可选 `ivfBuckets`：按主导维度分桶的简化 IVF，查询时探测邻近分桶，
+ *     降低大库扫描量（近似召回，用于更大规模）。
+ *
+ * 共享 entry.embedding 引用（不复制向量），内存开销仅为索引结构本身。
+ */
+/** 向量检索命中 */
+interface VectorSearchResult {
+    id: string;
+    score: number;
+}
+interface VectorIndexOptions {
+    /** IVF 分桶数（0 = 纯 brute-force 精确检索，默认 0） */
+    ivfBuckets?: number;
+}
+declare class VectorIndex {
+    private entries;
+    /** bucket -> id 列表（仅 ivfBuckets > 0 时使用） */
+    private buckets;
+    private dim;
+    private bucketCount;
+    constructor(options?: VectorIndexOptions);
+    get size(): number;
+    /** 添加或替换向量（同 id 覆盖）。维度不一致时忽略，返回是否生效 */
+    add(id: string, vector: number[]): boolean;
+    remove(id: string): boolean;
+    clear(): void;
+    /** 检索 top-k（cosine 降序，score > 0） */
+    search(query: number[], k: number): VectorSearchResult[];
+    /** 主导维度（argmax |v|）分桶 */
+    private bucketOf;
+    /** 从查询桶开始探测邻近分桶，直到凑够 minCandidates */
+    private probeCandidates;
+    private removeFromBucket;
+}
+
+/**
+ * 捕获抽取器：把一轮对话（用户消息 + 助手回答 + 工具）压成一条记忆。
+ *
+ * - 零-LLM 模式（默认）：抽取关键词概念，content 截断为 `Q: ...\nA: ...`。
+ * - LLM 模式（可选 summarizeFn）：调用外部摘要函数，失败回退到零-LLM。
+ */
+
+interface ExtractResult {
+    content: string;
+    concepts: string[];
+    /** 是否经过 LLM 摘要 */
+    summarized: boolean;
+}
+interface ExtractorOptions {
+    /** 概念数上限，默认 8 */
+    maxConcepts?: number;
+    /** content 最大字符数，默认 2000 */
+    maxChars?: number;
+}
+/**
+ * 零-LLM 抽取（要点压缩）：content = 用户首句 + 助手首句 + 工具（截断）。
+ *
+ * 相比直接转储整轮对话：
+ *   - 只保留「提问主体 + 回答主旨」，避免整段原文进索引（防止索引膨胀、
+ *     问题文本干扰检索命中）；
+ *   - concepts = 关键词 top-N（供 BM25 与展示）。
+ */
+declare function extractFromTurn(userMessage: string, assistantContent: string, toolsUsed: string[], options?: ExtractorOptions): ExtractResult;
+/**
+ * 运行抽取：若提供 summarizeFn 则先尝试 LLM 摘要，失败/返回 null 回退到零-LLM。
+ */
+declare function runCaptureExtractor(input: {
+    userMessage: string;
+    assistantContent: string;
+    toolsUsed: string[];
+    summarizeFn?: SummarizeFn;
+}, options?: ExtractorOptions): Promise<ExtractResult>;
+
+/**
+ * 注入哨兵（sentinel）：在 user 消息内容中包裹记忆块。
+ *
+ * 为何用 sentinel 而非 resource.meta：
+ *   aipack 的 messageToResource/resourceToMessage 对 user 消息不保留 meta
+ *   （context-resource/index.ts:30-38, 112-119）。sentinel 是 content 的一部分，
+ *   随消息持久化，下一轮 messagesToResources 重建后仍可在 content 文本中识别并剥离。
+ */
+
+declare const MEMORY_BLOCK_START = "<<<AIPACK_MEMORY>>>";
+declare const MEMORY_BLOCK_END = "<<</AIPACK_MEMORY>>>";
+/** 剥离 sentinel 包裹块（含其后的多余空行），返回干净原文 */
+declare function stripMemoryBlock(text: string): string;
+/** 判断文本是否包含 sentinel 块 */
+declare function hasMemoryBlock(text: string): boolean;
+/** 将若干行用 sentinel 包裹（含头尾换行，便于前插进 content） */
+declare function wrapMemoryBlock(lines: string[]): string;
+/** 由检索结果构造可读的记忆块文本 */
+declare function buildMemoryBlock(results: MemorySearchResult[]): string;
+
+/**
+ * 合并器：去重 / 合并相似记忆 + 修剪过期与低置信度。
+ *
+ * 参考 agentmemory 的 consolidate 阶段：
+ *   - 候选窗口 = 自上次合并以来内容有更新的条目（增量合并，避免每次对全库 N 条
+ *     逐一检索的 O(N²) 塌陷；首次合并或跨进程重启后为全量）。
+ *   - 对每个候选：以其 content 作为 query 检索相似记忆，相似度 >= 阈值则合并。
+ *   - 合并：content 取较长、concepts 并集、置信度取 max + 小奖励（避免旧「累加」
+ *     使置信度快速饱和到 1.0 而丧失排序/修剪信号）。
+ *   - 修剪过期 / 低置信度；超过 maxMemories 时淘汰置信度最低的。
+ */
+
+interface ConsolidatorOptions {
+    similarityThreshold?: number;
+    /** 事件接收器（合并结果/失败） */
+    onEvent?: MemoryEventSink;
+}
+declare class Consolidator implements ConsolidatorLike {
+    private store;
+    private retriever;
+    private similarityThreshold;
+    private onEvent?;
+    constructor(store: MemoryStore, retriever: HybridRetriever, options?: ConsolidatorOptions);
+    run(options?: ConsolidateOptions): Promise<{
+        merged: number;
+        pruned: number;
+    }>;
+}
+
+/**
+ * Agent 可调用的记忆工具。
+ *
+ * 参考 agentmemory 的 MCP 工具（save / recall / sessions 等），
+ * 但以 aipack 原生 Tool 形式提供，parameters 用纯 JSON Schema（不依赖 TypeBox）。
+ *
+ * 工具列表：
+ *   - save_memory(content, concepts?)
+ *   - search_memory(query, limit?)
+ *   - list_memories(limit?)
+ *   - delete_memory(id)
+ */
+
+interface MemoryToolsOptions {
+    /** list_memories 默认返回上限，默认 20 */
+    listLimit?: number;
+    /** search_memory 默认返回上限，默认 5 */
+    searchLimit?: number;
+    /** save_memory 保存的记忆 TTL（ms），过期后 prune 时清理 */
+    saveTtlMs?: number;
+}
+declare function createMemoryTools(store: MemoryStore, options?: MemoryToolsOptions): Tool[];
+
+export { BM25Index, type BM25Options, BM25Retriever, type CaptureOptions, type ConsolidateOptions, Consolidator, type ConsolidatorLike, type ConsolidatorOptions, type Embedder, type ExtractResult, type ExtractorOptions, FileMemoryStore, type FileMemoryStoreOptions, HybridRetriever, type HybridRetrieverOptions, type HybridSearchOptions, InMemoryStore, type InjectionOptions, MEMORY_BLOCK_END, MEMORY_BLOCK_START, type MatchedBy, MemoryCaptureExtension, type MemoryEntry, type MemoryEvent, type MemoryEventSink, MemoryIndex, MemoryInjectionTransformer, type MemoryPlugin, type MemoryPluginOptions, type MemorySaveInput, type MemorySearchResult, type MemorySource, type MemoryStats, type MemoryStore, type MemoryToolsOptions, type RetrieverLike, STOPWORDS, type SummarizeFn, VectorIndex, type VectorIndexOptions, type VectorSearchLike, type VectorSearchResult, buildMemoryBlock, cosine, createFileMemoryStore, createInMemoryStore, createMemoryPlugin, createMemoryTools, extractConcepts, extractFromTurn, finalizeEntry, hasMemoryBlock, isCJK, minMaxNormalize, runCaptureExtractor, stripMemoryBlock, tokenize, wrapMemoryBlock };