@ppagent/memory 0.1.0 → 0.1.2

package/dist/index.d.ts

@@ -2,6 +2,27 @@ type MessageType = "text" | "image" | "file";
 type FactLevel = "user" | "chat";
 type SearchMode = "fast" | "auto" | "all";
 type SearchScope = "session" | "chat" | "user" | "all";
+/**
+ * 分页参数（可选）。
+ * - offset：起始偏移，从 0 开始（负数按 0 处理）。
+ * - limit：本页最大条数；省略或 <=0 表示「从 offset 起取全部」。
+ */
+interface PageParams {
+    offset?: number;
+    limit?: number;
+}
+/**
+ * 分页结果信封。仅当调用方传入 PageParams 时返回；不传则保持返回纯数组（向后兼容）。
+ * - items：当前页数据。
+ * - total：过滤后、分页前的总条数（供前端计算总页数）。
+ * - offset / limit：实际生效的分页参数（limit 为 0 表示未限制）。
+ */
+interface Paginated<T> {
+    items: T[];
+    total: number;
+    offset: number;
+    limit: number;
+}
 /**
  * 多模态消息的单个内容块，与 OpenAI content part 对齐
  */
@@ -293,7 +314,7 @@ 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;
@@ -345,10 +366,152 @@ interface MemoryConfig {
     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;
@@ -362,6 +525,11 @@ 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?: {
@@ -417,19 +585,39 @@ declare class MemoryManager {
         messages: number;
         facts: number;
     }[]>;
-    /** 列出会话，可选按 userId / chatId 过滤，按更新时间倒序 */
+    /**
+     * 列出会话，可选按 userId / chatId 过滤，按更新时间倒序。
+     * 传入 page 时返回分页信封 {items,total,offset,limit}，不传则返回全量数组（向后兼容）。
+     */
     listSessions(filter?: {
         userId?: string;
         chatId?: string;
     }): SessionView[];
-    /** 列出会话内的消息（按时间正序）*/
+    listSessions(filter: {
+        userId?: string;
+        chatId?: string;
+    } | undefined, page: PageParams): Paginated<SessionView>;
+    /**
+     * 列出会话内的消息（按时间正序）。
+     * 传入 page 时返回分页信封（offset/limit 基于全量消息切片）；
+     * 仅传 limit（number）时保持旧行为：返回最新 limit 条。
+     */
     listMessages(sessionId: string, limit?: number): Promise<StoredMessage[]>;
-    /** 列出主题/摘要，可选按 sessionId / userId / chatId 过滤 */
+    listMessages(sessionId: string, page: PageParams): Promise<Paginated<StoredMessage>>;
+    /**
+     * 列出主题/摘要，可选按 sessionId / userId / chatId 过滤。
+     * 传入 page 时返回分页信封，不传则返回全量数组（向后兼容）。
+     */
     listTopics(filter?: {
         sessionId?: string;
         userId?: string;
         chatId?: string;
     }): Promise<Topic[]>;
+    listTopics(filter: {
+        sessionId?: string;
+        userId?: string;
+        chatId?: string;
+    } | undefined, page: PageParams): Promise<Paginated<Topic>>;
     /**
      * 列出事实，按创建时间倒序。过滤遵循 scope 层级包含语义：
      * - 按 chatId 过滤时，除该 chat 级 facts 外，还包含该 chat 所属 user 的 user 级 facts
@@ -442,16 +630,41 @@ declare class MemoryManager {
         userId?: string;
         chatId?: string;
     }): Fact[];
+    listFacts(filter: {
+        level?: FactLevel;
+        userId?: string;
+        chatId?: string;
+    } | undefined, page: PageParams): Paginated<Fact>;
     /** 由 chatId 反查所属 userId：优先用会话表映射，兜底用 chat 级 fact 自身。 */
     private resolveChatOwner;
     /** 手动新增一条事实 */
     addFact(content: string, level: FactLevel, userId: string, chatId: string, sessionId?: string): Promise<void>;
     /** 删除单条事实，返回是否命中 */
     deleteFact(factId: string): Promise<boolean>;
-    /** 列出全部实体（知识图谱节点）*/
-    listEntities(): Promise<Entity[]>;
-    /** 列出全部关系（知识图谱边）*/
-    listRelations(): Promise<Relation[]>;
+    /**
+     * 列出实体（知识图谱节点），可选按 userId / chatId 过滤。
+     * 传入 page 时返回分页信封，不传则返回数组（向后兼容）。
+     */
+    listEntities(filter?: {
+        userId?: string;
+        chatId?: string;
+    }): Promise<Entity[]>;
+    listEntities(filter: {
+        userId?: string;
+        chatId?: string;
+    } | undefined, page: PageParams): Promise<Paginated<Entity>>;
+    /**
+     * 列出关系（知识图谱边），可选按 userId / chatId 过滤。
+     * 传入 page 时返回分页信封，不传则返回数组（向后兼容）。
+     */
+    listRelations(filter?: {
+        userId?: string;
+        chatId?: string;
+    }): Promise<Relation[]>;
+    listRelations(filter: {
+        userId?: string;
+        chatId?: string;
+    } | undefined, page: PageParams): Promise<Paginated<Relation>>;
     /** 摄入一个文档（markdown）。document 落库即返回，切块/embedding/图谱后台执行（wait=true 可等待）。*/
     addDocument(opts: AddDocumentOptions): Promise<{
         docId: string;
@@ -462,127 +675,23 @@ declare class MemoryManager {
     getDocument(docId: string): Promise<Document | null>;
     /** 删除文档（级联删除其片段与知识图谱痕迹），返回是否命中。*/
     deleteDocument(docId: string): Promise<boolean>;
-    /** 列出文档，可选按 userId / chatId / sessionId 过滤，按更新时间倒序。*/
+    /**
+     * 列出文档，可选按 userId / chatId / sessionId 过滤，按更新时间倒序。
+     * 传入 page 时返回分页信封，不传则返回数组（向后兼容）。
+     */
     listDocuments(filter?: {
         userId?: string;
         chatId?: string;
         sessionId?: string;
     }): Promise<Document[]>;
+    listDocuments(filter: {
+        userId?: string;
+        chatId?: string;
+        sessionId?: string;
+    } | undefined, page: PageParams): Promise<Paginated<Document>>;
     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[]>;
-    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];
@@ -591,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 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 };