@ppagent/memory 0.1.1 → 0.1.2

package/dist/index.d.ts

@@ -270,8 +270,10 @@ interface AddDocumentOptions {
     metadata?: Record<string, unknown>;
     /** 默认取 config.buildGraphDefault（默认 "auto"）*/
     buildGraph?: BuildGraphMode;
-    /** 默认 false：document 落库即返回；true 则等切块/图谱全部完成 */
+    /** 默认 false：document 落库即返回；true 则等切块落库，文档可检索 */
     wait?: boolean;
+    /** 默认 false：true 时在 wait 的基础上额外等待知识图谱构建完成 */
+    waitGraph?: boolean;
 }
 interface KnowledgeSearchOptions {
     query: string;
@@ -312,12 +314,14 @@ interface MemoryConfig {
     llmBaseUrl: string;
     llmApiKey: string;
     llmModel: string;
-    /** LLM / embedding HTTP 请求超时（毫秒，默认 30000）。超时即中止并按重试策略处理。*/
+    /** LLM / embedding HTTP 请求超时（毫秒，默认 60000）。超时即中止并按重试策略处理。*/
     httpTimeoutMs?: number;
     /** LLM / embedding 请求失败（网络错误/超时/5xx/429）时的最大重试次数（默认 2，即最多请求 3 次）。*/
     httpMaxRetries?: number;
     /** embedding 单次请求最多包含的文本条数，超出自动分批（默认 20）。*/
     embeddingBatchSize?: number;
+    /** embedding 批次并发数（默认 2）。*/
+    embeddingConcurrency?: number;
     sessionTokenLimit?: number;
     historyWindowTokenLimit?: number;
     topicRatio?: [number, number, number];
@@ -358,10 +362,156 @@ interface MemoryConfig {
     knowledgeGraphAnchorTopK?: number;
     /** 每个锚点实体一跳扩展的最大关系数（默认 10）*/
     knowledgeGraphHopLimit?: number;
+    /** 文档图谱构建时并发抽取片段数（默认 2）*/
+    graphExtractConcurrency?: number;
+    /** waitGraph=true 时等待图谱构建的整体超时（毫秒，默认 120000）*/
+    graphBuildTimeoutMs?: number;
+    /**
+     * init 完成后是否后台执行一次存储压实（碎片合并 + 历史版本清理，默认 true）。
+     * 不阻塞启动；嵌入式单进程使用时建议保持开启，否则 LanceDB 版本目录会无限膨胀、启动越来越慢。
+     */
+    autoOptimizeOnInit?: boolean;
+    /** 压实时保留多久内的历史版本（毫秒，默认 0 即仅保留当前版本）。*/
+    optimizeVersionRetentionMs?: number;
+    /** 启动时恢复各会话历史窗口的并发数（默认 8，旧行为为逐会话串行）。*/
+    restoreConcurrency?: number;
 }
 interface ResolvedConfig extends Required<MemoryConfig> {
 }
 
+/** 单表压实结果（compaction + 历史版本清理）*/
+interface StorageOptimizeResult {
+    table: string;
+    fragmentsRemoved: number;
+    fragmentsAdded: number;
+    filesRemoved: number;
+    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;
+}
+
 declare class MemoryManager {
     private readonly config;
     private readonly lance;
@@ -375,10 +525,16 @@ declare class MemoryManager {
     private readonly sessionMap;
     constructor(config: MemoryConfig);
     init(): Promise<void>;
+    /**
+     * 手动触发存储压实与历史版本清理（init 后台会自动执行一次；上层维护任务也可调用）。
+     * @param retentionMs 保留多久内的历史版本，默认取配置 optimizeVersionRetentionMs
+     */
+    optimizeStorage(retentionMs?: number): Promise<StorageOptimizeResult[]>;
     private restoreFromStorage;
     updateChat(messages: RawMessage[], opts?: UpdateChatOptions): Promise<void>;
     flushChat(sessionId?: string, opts?: {
         wait?: boolean;
+        waitGraph?: boolean;
     }): Promise<void>;
     updateFacts(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string): Promise<void>;
     updateEntity(entities: Entity[], relations: Relation[], context?: UpdateEntityOptions): Promise<void>;
@@ -536,120 +692,6 @@ declare class MemoryManager {
     destroy(): void;
 }
 
-declare class LanceService {
-    private readonly config;
-    private conn;
-    private messagesTable;
-    private topicsTable;
-    private factsTable;
-    private sessionsTable;
-    private documentsTable;
-    private chunksTable;
-    private isNewMessagesTable;
-    private isNewSessionsTable;
-    private isNewDocumentsTable;
-    private isNewChunksTable;
-    constructor(config: ResolvedConfig);
-    init(): Promise<void>;
-    private ensureFtsIndexes;
-    /**
-     * 为存量 messages 表添加 parts 列（如果缺失）。
-     * LanceDB 0.14+ 支持 addColumns；旧版本会 throw，此时 rowToMessage 的 ?? "[]" 兜底。
-     */
-    private _ensurePartsColumn;
-    /**
-     * 为存量 topics 表添加 title 列（如果缺失）。
-     * 旧版本不支持 addColumns 时忽略，读取时 rowToTopic 的 ?? "" 兜底。
-     */
-    private _ensureTopicTitleColumn;
-    private ensureScalarIndex;
-    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;
-}
-
 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];
@@ -658,4 +700,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 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, 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 };