@ppagent/memory 0.1.0 → 0.1.1

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 对齐
  */
@@ -249,10 +270,8 @@ 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;
@@ -299,8 +318,6 @@ interface MemoryConfig {
     httpMaxRetries?: number;
     /** embedding 单次请求最多包含的文本条数，超出自动分批（默认 20）。*/
     embeddingBatchSize?: number;
-    /** embedding 批次并发数（默认 2）。*/
-    embeddingConcurrency?: number;
     sessionTokenLimit?: number;
     historyWindowTokenLimit?: number;
     topicRatio?: [number, number, number];
@@ -341,10 +358,6 @@ interface MemoryConfig {
     knowledgeGraphAnchorTopK?: number;
     /** 每个锚点实体一跳扩展的最大关系数（默认 10）*/
     knowledgeGraphHopLimit?: number;
-    /** 文档图谱构建时并发抽取片段数（默认 2）*/
-    graphExtractConcurrency?: number;
-    /** waitGraph=true 时等待图谱构建的整体超时（毫秒，默认 120000）*/
-    graphBuildTimeoutMs?: number;
 }
 interface ResolvedConfig extends Required<MemoryConfig> {
 }
@@ -366,7 +379,6 @@ declare class MemoryManager {
     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>;
@@ -417,19 +429,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 +474,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,12 +519,20 @@ 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;
 }
 
@@ -508,6 +573,8 @@ declare class LanceService {
     }>;
     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;
     }>>;
@@ -591,4 +658,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 StoredMessage, type Topic, type UpdateChatOptions, type UpdateEntityOptions, type UpdateSessionOptions };