@ppagent/memory 0.1.4 → 0.4.0

package/dist/index.d.ts

@@ -27,7 +27,7 @@ interface Paginated<T> {
  * 多模态消息的单个内容块，与 OpenAI content part 对齐
  */
 interface ContentPart {
-    type: "text" | "image_url" | "file_url";
+    type: string;
     /** type 为 "text" 时的文本内容 */
     text?: string;
     /** type 为 "image_url" 时的图片信息 */
@@ -39,6 +39,8 @@ interface ContentPart {
         url: string;
         name?: string;
     };
+    /** 保留宿主框架自定义 content part，写入和回读时不丢字段。 */
+    [key: string]: unknown;
 }
 interface RawMessage {
     messageId?: string;
@@ -57,6 +59,8 @@ interface RawMessage {
      * 序列化后存入 LanceDB 的 parts 字段。
      */
     parts?: ContentPart[];
+    /** 宿主框架的原始消息载荷；记忆框架仅透明保存和回读。 */
+    payload?: unknown;
     usage?: number;
     metadata?: Record<string, unknown>;
     createdAt?: number;
@@ -72,6 +76,8 @@ interface StoredMessage {
     content: string;
     /** JSON.stringify(ContentPart[])，纯文本消息为 "[]" */
     parts: string;
+    /** JSON.stringify(payload)，未提供时为 undefined。 */
+    payload?: string;
     usage: number;
     metadata: string;
     vector: number[];
@@ -84,9 +90,17 @@ interface Topic {
     chatId: string;
     /** 压缩时自动生成的主题标题（一句话），存量数据可能为空串 */
     title: string;
-    detail: string;
+    /** 唯一的压缩正文。长度由内容重要性动态决定。 */
     summary: string;
-    concise: string;
+    /** 压缩结果的 token 数；旧数据缺失时由本地 tokenizer 回填。 */
+    tokens: number;
+    /** 本 Topic 覆盖的首尾原始消息 id，便于同毫秒边界精确恢复。 */
+    startMessageId?: string;
+    endMessageId?: string;
+    /** @deprecated 仅用于读取尚未迁移的 0.3.x 数据。 */
+    detail?: string;
+    /** @deprecated 仅用于读取尚未迁移的 0.3.x 数据。 */
+    concise?: string;
     startTime: number;
     endTime: number;
     createdAt: number;
@@ -100,8 +114,12 @@ interface Fact {
     chatId: string;
     sessionId: string;
     userId: string;
+    /** 同一 level/owner 内用于 upsert 的稳定键；旧数据可能为空。 */
+    key?: string;
     content: string;
     createdAt: number;
+    /** 最近一次同 key 更新时刻；旧数据回落 createdAt。 */
+    updatedAt?: number;
 }
 interface EntityMeta {
     messageId?: string;
@@ -179,9 +197,9 @@ interface UpdateEntityOptions {
 interface CompressOutput {
     /** 自动生成的主题标题（一句话） */
     title: string;
-    detail: string;
     summary: string;
-    concise: string;
+    /** 模型报告的摘要输出 token；缺失时由本地 tokenizer 计算。 */
+    tokens?: number;
     entities: Array<{
         name: string;
         type: string;
@@ -198,10 +216,44 @@ interface CompressOutput {
 interface SessionEntry {
     messages: StoredMessage[];
     totalTokens: number;
+    topics: Topic[];
+    topicTokens: number;
     ids: {
         chatId: string;
         userId: string;
     };
+    lastModelContextTokens?: number;
+    lastAccessAt: number;
+}
+/** getHistoryWindow 返回的原始消息；字段形态与 updateChat 输入保持一致。 */
+interface MemoryRawMessage {
+    messageId: string;
+    talkerId: string;
+    chatId: string;
+    userId: string;
+    sessionId: string;
+    type: MessageType;
+    content: string;
+    parts?: ContentPart[];
+    payload?: unknown;
+    usage: number;
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+}
+interface MemoryContextWindowUsage {
+    modelContextTokens: number;
+    usableContextTokens: number;
+    compressedTokenLimit: number;
+    compressedTokens: number;
+    rawTokenLimit: number;
+    rawTokens: number;
+}
+/** 固定预算的压缩记忆 + 近期未压缩原始消息。 */
+interface MemoryContextWindow {
+    sessionId: string;
+    compressedContext: string;
+    recentMessages: MemoryRawMessage[];
+    usage: MemoryContextWindowUsage;
 }
 /** 是否为文档构建知识图谱：true/false 显式控制，"auto" 由内置 LLM 判定 */
 type BuildGraphMode = boolean | "auto";
@@ -264,6 +316,8 @@ interface AddDocumentOptions {
     userId?: string;
     chatId?: string;
     sessionId?: string;
+    /** 内容哈希去重范围；默认 session（兼容旧行为）。 */
+    scope?: SearchScope;
     /** 不传则从首个 H1 / sourceName 推断 */
     title?: string;
     sourceName?: string;
@@ -305,7 +359,18 @@ interface KnowledgeSearchResult {
 }
 
 interface MemoryConfig {
+    /**
+     * 向量存储后端：
+     * - "auto"（默认）：运行时探测 @lancedb/lancedb 原生绑定，可用则 lancedb，否则回退 sqlite
+     *   （覆盖 Intel Mac / musl 等无预编译二进制的平台）。首次选定后写入数据目录 marker 固化，
+     *   避免环境变化导致静默换库（表现为「记忆丢失」）。
+     * - "lancedb" / "sqlite"：显式指定。
+     * 注意：两个后端的数据文件互不相通，切换需自行迁移。
+     */
+    provider?: "auto" | "lancedb" | "sqlite";
     lancedbPath: string;
+    /** sqlite 后端的数据库文件路径（默认 lancedbPath 同级目录下的 memory.sqlite3） */
+    sqlitePath?: string;
     grafeoPath: string;
     embeddingBaseUrl: string;
     embeddingApiKey: string;
@@ -322,16 +387,42 @@ interface MemoryConfig {
     embeddingBatchSize?: number;
     /** embedding 批次并发数（默认 2）。*/
     embeddingConcurrency?: number;
+    /** 压缩 Topic 在历史窗口中的固定预算，默认 16K。 */
+    compressedContextTokenLimit?: number;
+    /** 模型上下文中允许历史记忆使用的比例，默认 0.75。 */
+    contextUsageRatio?: number;
+    /** 原始消息达到其可用预算的此比例时后台预压缩，默认 0.75。 */
+    precompressionRatio?: number;
+    /** 单次压缩目标占原始消息预算的比例，默认 0.5。 */
+    compressionBatchRatio?: number;
+    /** 单次压缩硬上限；0 表示只受 compressionBatchRatio 控制。 */
+    compressionBatchTokenLimit?: number;
+    /** 单条 Topic 摘要硬上限，实际长度由重要性决定，默认 2048。 */
+    topicSummaryMaxTokens?: number;
+    /** 未传 getHistoryWindow 模型窗口时使用，默认 256K。 */
+    defaultModelContextTokens?: number;
+    /** 冷启动最多恢复多久以前的压缩 Topic；0 表示永久。 */
+    maxHistoryAgeMs?: number;
+    /** 会话缓存空闲释放时间，默认 30 分钟；<=0 关闭。 */
+    sessionIdleTtlMs?: number;
+    /** 空闲会话扫描周期，默认 1 分钟。 */
+    sessionSweepIntervalMs?: number;
+    /** @deprecated 0.3.x 原始消息固定阈值；仅为配置兼容保留。 */
     sessionTokenLimit?: number;
+    /** @deprecated 使用 compressedContextTokenLimit。 */
     historyWindowTokenLimit?: number;
+    /** @deprecated 三级 Topic 窗口已移除。 */
     topicRatio?: [number, number, number];
+    /** @deprecated 使用 topicSummaryMaxTokens。 */
     detailMaxTokens?: number;
+    /** 文档摘要仍使用此限制；对话 Topic 使用 topicSummaryMaxTokens。 */
     summaryMaxTokens?: number;
+    /** @deprecated 三级 Topic 窗口已移除。 */
     conciseMaxTokens?: number;
     maxConcurrentCompressions?: number;
     entitySimilarityThreshold?: number;
     defaultSearchLimit?: number;
-    /** 每次召回相当于多少毫秒的时间权重加成（默认 3_600_000 即 1 小时）*/
+    /** @deprecated 连续历史窗口不再按召回热度重排。 */
     recallBoostMs?: number;
     /** 切块策略，目前仅 "markdown-heading"（默认）*/
     chunkStrategy?: "markdown-heading";
@@ -389,7 +480,122 @@ interface MemoryConfig {
 interface ResolvedConfig extends Required<MemoryConfig> {
 }
 
-/** 单表压实结果（compaction + 历史版本清理）*/
+/**
+ * 向量存储后端抽象层的类型定义。
+ *
+ * 设计原则：接口只表达「语义」（结果意味着什么），不表达「机制」（怎么算出来的）。
+ * - 混合检索（RRF 融合）、回退策略、业务重排等组合逻辑在共享域层 memory.store.ts 实现，
+ *   provider 只需提供 vectorSearch / ftsSearch 两个检索原语，保证跨后端行为一致。
+ * - ANN、索引维护、存储压实等机制细节由各 provider 自行决定，接口仅以声明式
+ *   IndexSpec 提示与 capabilities 能力声明的方式暴露。
+ * - 过滤条件为结构化对象（而非 SQL 字符串），各 provider 翻译为自己的方言，
+ *   从根上消除转义/注入问题。
+ */
+type FilterCondition = 
+/** 等值匹配 */
+{
+    op: "eq";
+    field: string;
+    value: string | number;
+}
+/** 数值大于 */
+ | {
+    op: "gt";
+    field: string;
+    value: number;
+}
+/** 数值大于等于 */
+ | {
+    op: "gte";
+    field: string;
+    value: number;
+}
+/** 字段值属于集合。values 为空数组表示「不匹配任何行」 */
+ | {
+    op: "in";
+    field: string;
+    values: string[];
+}
+/**
+ * 匹配序列化为 JSON 字符串的 metadata 列中的键值对。
+ * 语义等同旧 LanceService.buildMetadataFilter 的 LIKE '%"key":value%' 模式：
+ * 仅适合标量值精确匹配，嵌套对象/含特殊字符的值不保证可靠。
+ */
+ | {
+    op: "jsonContains";
+    field: string;
+    key: string;
+    value: string | number | boolean;
+};
+/** 多个条件为 AND 关系。空数组等同于不过滤。 */
+type Filter = FilterCondition[];
+type ColumnType = 
+/** UTF-8 文本 */
+"text"
+/** 32 位整数 */
+ | "int"
+/** 64 位整数（毫秒时间戳等）。JS 侧统一以 number 读写 */
+ | "long"
+/** 定长 float32 向量，维度由 TableDef.vectorDimension 决定 */
+ | "vector";
+interface ColumnDef {
+    name: string;
+    type: ColumnType;
+    /** 默认 false。nullable 列用于 schema 演进的兼容（旧数据无此列） */
+    nullable?: boolean;
+}
+interface IndexSpec {
+    column: string;
+    /**
+     * - scalar：标量索引（btree 等价物），加速等值/范围过滤
+     * - fts：全文检索索引（BM25）
+     * - vector：向量检索加速提示。当前所有 provider 均为精确暴力扫描（ANN 暂不启用，
+     *   见 plans/vector-db-replacement-research.md 决议），该值仅作为将来启用 ANN 的声明位。
+     */
+    kind: "scalar" | "fts" | "vector";
+}
+interface TableDef {
+    name: string;
+    columns: ColumnDef[];
+    /** 有 vector 列时必填 */
+    vectorDimension?: number;
+    indexes: IndexSpec[];
+}
+interface OrderBySpec {
+    column: string;
+    ascending: boolean;
+}
+interface QueryOptions {
+    filter?: Filter;
+    orderBy?: OrderBySpec[];
+    limit?: number;
+    /** 只取指定列（性能优化，如 trendDaily 只读 created_at）。省略取全部列 */
+    select?: string[];
+}
+interface VectorSearchOptions {
+    filter?: Filter;
+    limit: number;
+}
+interface FtsSearchOptions {
+    /** 参与全文匹配的列（须已建 fts 索引） */
+    columns: string[];
+    filter?: Filter;
+    limit: number;
+}
+/** 通用行类型：列名 → 值。vector 列为 number[]，long 列为 number */
+type Row = Record<string, unknown>;
+/**
+ * 向量检索结果附带 _distance（L2 平方距离，越小越相近）。
+ * 各 provider 必须保持相同度量（L2），依赖距离阈值的上层逻辑才能跨后端一致。
+ */
+type ScoredRow = Row & {
+    _distance: number;
+};
+/** FTS 检索结果附带 _score（BM25 相关度，越大越相关；仅用于排序，绝对值跨后端无可比性） */
+type FtsRow = Row & {
+    _score: number;
+};
+/** 单表压实结果。不同后端的语义映射：LanceDB=碎片合并+版本清理；SQLite=incremental vacuum 等 */
 interface StorageOptimizeResult {
     table: string;
     fragmentsRemoved: number;
@@ -398,133 +604,46 @@ interface StorageOptimizeResult {
     oldVersionsRemoved: number;
     bytesRemoved: number;
 }
-declare class LanceService {
-    private readonly config;
-    private conn;
-    private messagesTable;
-    private topicsTable;
-    private factsTable;
-    private sessionsTable;
-    private documentsTable;
-    private chunksTable;
-    private isNewMessagesTable;
-    private isNewTopicsTable;
-    private isNewSessionsTable;
-    private isNewDocumentsTable;
-    private isNewChunksTable;
-    constructor(config: ResolvedConfig);
-    init(): Promise<void>;
-    /**
-     * 按需补齐索引：先经 listIndices 判存在，缺失的列才 createIndex（且 replace:false）。
-     * createIndex 默认 replace:true 会在每次启动时全量重建索引并提交新表版本——
-     * 这正是历史上「启动越来越慢 + _versions 目录膨胀」的根源，绝不可回退到无条件 createIndex。
-     */
-    private ensureIndexes;
-    /**
-     * 存储压实：逐表执行碎片合并 + 清理 retentionMs 之前的历史版本。
-     * 嵌入式场景下 LanceDB 不会自动做这件事，长期运行后版本/碎片无限累积会显著拖慢启动与查询。
-     */
-    optimizeStorage(retentionMs?: number): Promise<StorageOptimizeResult[]>;
-    /**
-     * 为存量 messages 表添加 parts 列（如果缺失）。
-     * LanceDB 0.14+ 支持 addColumns；旧版本会 throw，此时 rowToMessage 的 ?? "[]" 兜底。
-     */
-    private _ensurePartsColumn;
-    /**
-     * 为存量 topics 表添加 title 列（如果缺失）。
-     * 旧版本不支持 addColumns 时忽略，读取时 rowToTopic 的 ?? "" 兜底。
-     */
-    private _ensureTopicTitleColumn;
-    addMessages(messages: StoredMessage[]): Promise<void>;
-    addTopic(topic: Topic): Promise<void>;
-    updateTopicRecallCount(summaryId: string, count: number): Promise<void>;
-    getRecentTopics(chatId: string, userId: string, n1: number, n2: number, n3: number): Promise<{
-        detail: Topic[];
-        summary: Topic[];
-        concise: Topic[];
-    }>;
-    getMessagesSince(sessionId: string, since: number, limit?: number): Promise<StoredMessage[]>;
-    getLatestMessages(sessionId: string, limit: number): Promise<StoredMessage[]>;
-    /** 取某会话的全部消息（按 createdAt 升序），供管理面板分页切片使用 */
-    getAllMessagesBySession(sessionId: string): Promise<StoredMessage[]>;
-    searchMessages(vector: number[], filter?: string, limit?: number): Promise<Array<StoredMessage & {
-        _distance: number;
-    }>>;
-    hybridSearchMessages(query: string, vector: number[], filter?: string, limit?: number): Promise<StoredMessage[]>;
-    hybridSearchTopics(query: string, vector: number[], filter?: string, limit?: number): Promise<Topic[]>;
-    saveFact(fact: Fact): Promise<void>;
-    getAllFacts(): Promise<Fact[]>;
-    getAllSessionIds(): Promise<string[]>;
-    insertSession(session: Session): Promise<void>;
-    upsertSession(session: Session): Promise<void>;
-    getAllSessions(): Promise<Session[]>;
-    deleteSession(sessionId: string): Promise<void>;
-    /** 全量读取 topics（管理面板列表用，不做 recall 加权排序，按 endTime 倒序）*/
-    getAllTopics(): Promise<Topic[]>;
-    /** 删除单条 fact */
-    deleteFact(factId: string): Promise<void>;
-    /** 删除某会话下的全部消息（级联删除会话时使用）*/
-    deleteMessagesBySession(sessionId: string): Promise<void>;
-    /** 删除某会话下的全部 topics（级联删除会话时使用）*/
-    deleteTopicsBySession(sessionId: string): Promise<void>;
-    /** 各表行数统计（概览卡片用）*/
-    countAll(): Promise<{
-        sessions: number;
-        messages: number;
-        topics: number;
-        facts: number;
-    }>;
-    /**
-     * 按天聚合最近 days 天的活跃趋势（概览图表用）。
-     * 返回连续日期序列（含无数据的零值天），按本地日期分桶。
-     */
-    trendDaily(days: number): Promise<{
-        date: string;
-        sessions: number;
-        messages: number;
-        facts: number;
-    }[]>;
-    addDocument(doc: Document): Promise<void>;
-    addChunks(chunks: Chunk[]): Promise<void>;
-    updateDocumentGraphFlag(docId: string, hasGraph: boolean): Promise<void>;
-    getDocument(docId: string): Promise<Document | null>;
-    /** 查找同域同 hash 的文档（去重用）*/
-    findDocumentByHash(contentHash: string, filter?: string): Promise<Document | null>;
-    /** 按域过滤返回 docId 列表（chunkRedundantIds=false 时用于 chunk 过滤）*/
-    getDocIdsByDomain(filter?: string): Promise<string[]>;
-    /** 文档级粗召回：对摘要向量做向量搜索，定位候选文档 */
-    searchDocuments(vector: number[], filter?: string, limit?: number): Promise<Array<Document & {
-        _distance: number;
-    }>>;
-    /** 知识片段混合检索（BM25 + 向量），失败回退纯向量 */
-    searchChunks(query: string, vector: number[], filter?: string, limit?: number): Promise<Chunk[]>;
-    deleteDocument(docId: string): Promise<void>;
-    deleteChunksByDoc(docId: string): Promise<void>;
-    /** 全量读取文档（管理面板用），按更新时间倒序 */
-    getAllDocuments(): Promise<Document[]>;
-    /** 知识库行数统计 */
-    countKnowledge(): Promise<{
-        documents: number;
-        chunks: number;
-    }>;
-    /**
-     * 根据 metadata 字段内容构建 SQL LIKE 过滤条件。
-     *
-     * metadata 以 JSON 字符串存储，此方法将键值对转换为 SQL LIKE 表达式，
-     * 可直接传给 searchMessages / hybridSearchTopics 的 filter 参数。
-     *
-     * 示例：buildMetadataFilter({ env: "prod", version: 2 })
-     *   → `metadata LIKE '%"env":"prod"%' AND metadata LIKE '%"version":2%'`
-     *
-     * 注意：仅适合简单标量值（字符串、数字、布尔）的精确匹配。
-     * 复杂嵌套对象或含空格的 JSON 值可能无法可靠匹配。
-     */
-    static buildMetadataFilter(conditions: Record<string, string | number | boolean>): string;
+interface ProviderCapabilities {
+    /** 是否支持原生 FTS（BM25）。false 时域层混合检索自动降级为纯向量 */
+    fts: boolean;
+    /** 向量检索是否为 ANN 近似（false = 精确暴力）。当前所有 provider 均为 false */
+    ann: boolean;
+    /** optimize() 是否有实际效果（LanceDB 版本回收必需；SQLite 可选） */
+    optimize: boolean;
+}
+/**
+ * 向量存储后端需要实现的最小原语集合。
+ *
+ * 实现约定：
+ * - init 必须幂等：表已存在则打开并按 TableDef 补齐缺失的列（schema 演进）与索引；
+ *   不存在则创建。
+ * - 所有 filter 参数为结构化 Filter，provider 内部翻译为自己的方言并负责转义/参数化。
+ * - vectorSearch 使用 L2 距离，返回按 _distance 升序的前 limit 行。
+ * - ftsSearch 返回按 _score（BM25）降序的前 limit 行；查询词的分词由 provider 负责
+ *   （中文场景 sqlite provider 使用 jieba；lancedb provider 使用 tantivy 内置分词）。
+ * - add/update/delete 需保证同一表内的派生结构（如 sqlite 的 FTS 影子表）事务一致。
+ */
+interface VectorStoreProvider {
+    /** provider 标识，用于日志与数据目录 marker */
+    readonly kind: string;
+    init(tables: TableDef[]): Promise<void>;
+    add(table: string, rows: Row[]): Promise<void>;
+    update(table: string, values: Row, filter: Filter): Promise<void>;
+    deleteWhere(table: string, filter: Filter): Promise<void>;
+    query(table: string, opts?: QueryOptions): Promise<Row[]>;
+    vectorSearch(table: string, vector: number[], opts: VectorSearchOptions): Promise<ScoredRow[]>;
+    ftsSearch(table: string, query: string, opts: FtsSearchOptions): Promise<FtsRow[]>;
+    count(table: string, filter?: Filter): Promise<number>;
+    /** 存储压实与历史版本回收。retentionMs：保留多久内的历史版本（不支持版本概念的后端可忽略） */
+    optimize(retentionMs: number): Promise<StorageOptimizeResult[]>;
+    capabilities(): ProviderCapabilities;
+    close(): Promise<void>;
 }
 
 declare class MemoryManager {
     private readonly config;
-    private readonly lance;
+    private readonly store;
     private readonly grafeo;
     private readonly embed;
     private readonly llm;
@@ -534,7 +653,13 @@ declare class MemoryManager {
     private readonly knowledgeManager;
     private readonly sessionMap;
     private optimizeTimer?;
+    private sessionSweepTimer?;
     private optimizeRunning;
+    private optimizeTask?;
+    private destroyTask?;
+    private readonly hydration;
+    private readonly pendingWrites;
+    private warnedDefaultModelContext;
     constructor(config: MemoryConfig);
     init(): Promise<void>;
     /** 后台压实的统一入口：防重入（上一轮未结束则跳过），失败仅告警不影响服务。*/
@@ -544,13 +669,17 @@ declare class MemoryManager {
      * @param retentionMs 保留多久内的历史版本，默认取配置 optimizeVersionRetentionMs
      */
     optimizeStorage(retentionMs?: number): Promise<StorageOptimizeResult[]>;
-    private restoreFromStorage;
+    private ensureSessionHydrated;
+    private isSessionBusy;
+    private waitForPendingWrites;
+    private queueSessionWrite;
     updateChat(messages: RawMessage[], opts?: UpdateChatOptions): Promise<void>;
+    private doUpdateChat;
     flushChat(sessionId?: string, opts?: {
         wait?: boolean;
         waitGraph?: boolean;
     }): Promise<void>;
-    updateFacts(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string): Promise<void>;
+    updateFacts(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string, key?: string): Promise<void>;
     updateEntity(entities: Entity[], relations: Relation[], context?: UpdateEntityOptions): Promise<void>;
     search(opts: SearchOptions): Promise<SearchResult[]>;
     ask(opts: SearchOptions & {
@@ -566,8 +695,9 @@ declare class MemoryManager {
      * 返回 user 级(userId) ∪ chat 级(chatId)，按时间正序拼接。
      */
     getFactsForContext(userId: string, chatId: string): Promise<string>;
-    getHistoryWindow(sessionId: string): string;
-    private buildLanceFilter;
+    getHistoryWindow(sessionId: string, modelContextTokens?: number): Promise<MemoryContextWindow>;
+    private calculateWindowUsage;
+    private buildScopeFilter;
     private deserializeSession;
     private serializeSession;
     getRecentMessages(sessionId: string, limit: number): Promise<StoredMessage[]>;
@@ -652,7 +782,7 @@ declare class MemoryManager {
     /** 由 chatId 反查所属 userId：优先用会话表映射，兜底用 chat 级 fact 自身。 */
     private resolveChatOwner;
     /** 手动新增一条事实 */
-    addFact(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string): Promise<void>;
+    addFact(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string, key?: string): Promise<void>;
     /** 删除单条事实，返回是否命中 */
     deleteFact(factId: string): Promise<boolean>;
     /**
@@ -703,9 +833,139 @@ declare class MemoryManager {
         chatId?: string;
         sessionId?: string;
     } | undefined, page: PageParams): Promise<Paginated<Document>>;
-    destroy(): void;
+    destroy(): Promise<void>;
 }
 
+interface MemoryMigrationReport {
+    provider: string;
+    topicsScanned: number;
+    topicsUpdated: number;
+    messagesScanned: number;
+    messagesUpdated: number;
+    factsScanned: number;
+    factsUpdated: number;
+}
+/**
+ * 记忆系统的存储域层：保持原 LanceService 的公开方法面，内部组合
+ * VectorStoreProvider 的通用原语实现。业务逻辑（混合检索融合、话题回退、
+ * recall 加权重排）全部在此层，各后端 provider 不感知。
+ */
+declare class MemoryStore {
+    private readonly config;
+    private provider;
+    private readonly providerOverride?;
+    /** provider 省略时在 init() 阶段经 provider.resolver 自动探测创建（测试可显式注入） */
+    constructor(config: ResolvedConfig, provider?: VectorStoreProvider);
+    /** 当前后端 provider 标识（日志/诊断用） */
+    get providerKind(): string;
+    init(): Promise<void>;
+    close(): Promise<void>;
+    /**
+     * 存储压实（碎片合并 + 历史版本清理）。
+     * LanceDB 后端长期运行必须定期执行；SQLite 后端为可选的空间回收。
+     */
+    optimizeStorage(retentionMs?: number): Promise<StorageOptimizeResult[]>;
+    addMessages(messages: StoredMessage[]): Promise<void>;
+    /** 0.3.x → 0.4.x 数据回填；幂等，不调用 LLM、不删除原始消息。 */
+    migrateLegacyData(): Promise<MemoryMigrationReport>;
+    /** message_id 稳定时更新原行，否则新增；用于流式 assistant 消息最终态覆盖。 */
+    upsertMessages(messages: StoredMessage[]): Promise<void>;
+    getMessagesSince(sessionId: string, since: number, limit?: number): Promise<StoredMessage[]>;
+    getMessagesAfterBoundary(sessionId: string, endTime: number, endMessageId?: string): Promise<StoredMessage[]>;
+    getLatestMessages(sessionId: string, limit: number): Promise<StoredMessage[]>;
+    /** 取某会话的全部消息（按 createdAt 升序），供管理面板分页切片使用 */
+    getAllMessagesBySession(sessionId: string): Promise<StoredMessage[]>;
+    searchMessages(vector: number[], filter?: Filter, limit?: number): Promise<Array<StoredMessage & {
+        _distance: number;
+    }>>;
+    hybridSearchMessages(query: string, vector: number[], filter?: Filter, limit?: number): Promise<StoredMessage[]>;
+    hybridSearchTopics(query: string, vector: number[], filter?: Filter, limit?: number): Promise<Topic[]>;
+    /**
+     * 通用混合检索：FTS（BM25）与向量两路各取 limit*HYBRID_OVERFETCH 候选，RRF 融合。
+     * FTS 不可用（后端不支持或查询失败）时降级为纯向量。返回融合后的完整候选序列（未截断）。
+     */
+    private hybridSearch;
+    private keyColumnOf;
+    addTopic(topic: Topic): Promise<void>;
+    updateTopic(topic: Topic): Promise<void>;
+    updateTopicRecallCount(summaryId: string, count: number): Promise<void>;
+    incrementTopicRecallCounts(topics: Topic[]): Promise<void>;
+    getTopicsBySession(sessionId: string, since?: number): Promise<Topic[]>;
+    getRecentTopics(chatId: string, userId: string, n1: number, n2: number, n3: number): Promise<{
+        detail: Topic[];
+        summary: Topic[];
+        concise: Topic[];
+    }>;
+    /** 全量读取 topics（管理面板列表用，不做 recall 加权排序，按 endTime 倒序）*/
+    getAllTopics(): Promise<Topic[]>;
+    deleteTopicsBySession(sessionId: string): Promise<void>;
+    deleteTopicsByIds(summaryIds: string[]): Promise<void>;
+    saveFact(fact: Fact): Promise<void>;
+    updateFact(fact: Fact): Promise<void>;
+    getAllFacts(): Promise<Fact[]>;
+    /** 删除单条 fact */
+    deleteFact(factId: string): Promise<void>;
+    getAllSessionIds(): Promise<string[]>;
+    insertSession(session: Session): Promise<void>;
+    upsertSession(session: Session): Promise<void>;
+    getAllSessions(): Promise<Session[]>;
+    deleteSession(sessionId: string): Promise<void>;
+    /** 删除某会话下的全部消息（级联删除会话时使用）*/
+    deleteMessagesBySession(sessionId: string): Promise<void>;
+    /** 各表行数统计（概览卡片用）*/
+    countAll(): Promise<{
+        sessions: number;
+        messages: number;
+        topics: number;
+        facts: number;
+    }>;
+    /**
+     * 按天聚合最近 days 天的活跃趋势（概览图表用）。
+     * 返回连续日期序列（含无数据的零值天），按本地日期分桶。
+     */
+    trendDaily(days: number): Promise<{
+        date: string;
+        sessions: number;
+        messages: number;
+        facts: number;
+    }[]>;
+    addDocument(doc: Document): Promise<void>;
+    addChunks(chunks: Chunk[]): Promise<void>;
+    updateDocumentGraphFlag(docId: string, hasGraph: boolean): Promise<void>;
+    getDocument(docId: string): Promise<Document | null>;
+    /** 查找同域同 hash 的文档（去重用）*/
+    findDocumentByHash(contentHash: string, filter?: Filter): Promise<Document | null>;
+    /** 按域过滤返回 docId 列表（chunkRedundantIds=false 时用于 chunk 过滤）*/
+    getDocIdsByDomain(filter?: Filter): Promise<string[]>;
+    /** 文档级粗召回：对摘要向量做向量搜索，定位候选文档 */
+    searchDocuments(vector: number[], filter?: Filter, limit?: number): Promise<Array<Document & {
+        _distance: number;
+    }>>;
+    /** 知识片段混合检索（BM25 + 向量），失败回退纯向量 */
+    searchChunks(query: string, vector: number[], filter?: Filter, limit?: number): Promise<Chunk[]>;
+    deleteDocument(docId: string): Promise<void>;
+    deleteChunksByDoc(docId: string): Promise<void>;
+    /** 全量读取文档（管理面板用），按更新时间倒序 */
+    getAllDocuments(): Promise<Document[]>;
+    /** 知识库行数统计 */
+    countKnowledge(): Promise<{
+        documents: number;
+        chunks: number;
+    }>;
+    /**
+     * 根据 metadata 字段内容构建结构化过滤条件。
+     *
+     * metadata 以 JSON 字符串存储，此方法将键值对转换为 jsonContains 条件，
+     * 可直接传给 searchMessages / hybridSearchTopics 的 filter 参数。
+     *
+     * 注意：仅适合简单标量值（字符串、数字、布尔）的精确匹配。
+     * 复杂嵌套对象或含空格的 JSON 值可能无法可靠匹配。
+     */
+    static buildMetadataFilter(conditions: Record<string, string | number | boolean>): Filter;
+}
+
+type ProviderKind = "lancedb" | "sqlite";
+
 declare const DEFAULT_NODE_TYPES: readonly ["Person", "Group", "Organization", "Project", "Task", "Decision", "Plan", "Event", "Product", "Technology", "Data", "Document", "Topic", "Concept", "Preference", "Habit", "Goal", "Skill", "Attribute", "Value", "Status", "Time", "Location", "Resource", "Relationship"];
 declare const DEFAULT_RELATION_TYPES: readonly ["is_a", "part_of", "belongs_to", "contains", "has_member", "mentioned_in", "refers_to", "same_as", "alias_of", "related_to", "associated_with", "uses", "creates", "updates", "buys", "owns", "consumes", "works_on", "prefers", "likes", "dislikes", "interested_in", "favorite", "plans", "decides", "habit_of", "tends_to", "avoids", "skilled_in", "learning", "knows", "friends_with", "married_to", "parent_of", "child_of", "lives_with", "depends_on", "built_with", "integrates_with", "deployed_on", "inputs", "outputs", "trained_on", "predicts", "happens_at", "started_at", "ended_at", "affects", "causes", "leads_to", "improves", "reduces", "assigned_to", "executed_by", "blocks", "completes", "describes", "explains", "references"];
 type NodeType = (typeof DEFAULT_NODE_TYPES)[number];
@@ -714,4 +974,4 @@ type RelationType = (typeof DEFAULT_RELATION_TYPES)[number];
 declare const KIND_CONVERSATION = "conversation";
 declare const KIND_KNOWLEDGE = "knowledge";
 
-export { type AddDocumentOptions, type BuildGraphMode, type Chunk, type ChunkHit, type ChunkPiece, type CompressOutput, type ContentPart, DEFAULT_NODE_TYPES, DEFAULT_RELATION_TYPES, type Document, type DomainIds, type Entity, type EntityMeta, type Fact, type FactLevel, KIND_CONVERSATION, KIND_KNOWLEDGE, type KnowledgeSearchOptions, type KnowledgeSearchResult, LanceService, type MemoryConfig, MemoryManager, type MessageType, type NodeType, type PageParams, type Paginated, type RawMessage, type Relation, type RelationType, type SearchMode, type SearchOptions, type SearchResult, type SearchScope, type Session, type SessionEntry, type SessionSearchOptions, type SessionView, type StorageOptimizeResult, type StoredMessage, type Topic, type UpdateChatOptions, type UpdateEntityOptions, type UpdateSessionOptions };
+export { type AddDocumentOptions, type BuildGraphMode, type Chunk, type ChunkHit, type ChunkPiece, type CompressOutput, type ContentPart, DEFAULT_NODE_TYPES, DEFAULT_RELATION_TYPES, type Document, type DomainIds, type Entity, type EntityMeta, type Fact, type FactLevel, type Filter, type FilterCondition, KIND_CONVERSATION, KIND_KNOWLEDGE, type KnowledgeSearchOptions, type KnowledgeSearchResult, type MemoryConfig, type MemoryContextWindow, type MemoryContextWindowUsage, MemoryManager, type MemoryMigrationReport, type MemoryRawMessage, MemoryStore, type MessageType, type NodeType, type PageParams, type Paginated, type ProviderCapabilities, type ProviderKind, type RawMessage, type Relation, type RelationType, type SearchMode, type SearchOptions, type SearchResult, type SearchScope, type Session, type SessionEntry, type SessionSearchOptions, type SessionView, type StorageOptimizeResult, type StoredMessage, type Topic, type UpdateChatOptions, type UpdateEntityOptions, type UpdateSessionOptions, type VectorStoreProvider };