@ppagent/memory 0.1.0 → 0.1.1

package/dist/index.js

@@ -25,10 +25,9 @@ function resolveConfig(config) {
     detailMaxTokens: config.detailMaxTokens ?? 2048,
     summaryMaxTokens: config.summaryMaxTokens ?? 512,
     conciseMaxTokens: config.conciseMaxTokens ?? 128,
-    httpTimeoutMs: config.httpTimeoutMs ?? 6e4,
+    httpTimeoutMs: config.httpTimeoutMs ?? 3e4,
     httpMaxRetries: config.httpMaxRetries ?? 2,
     embeddingBatchSize: config.embeddingBatchSize ?? 20,
-    embeddingConcurrency: config.embeddingConcurrency ?? 2,
     maxConcurrentCompressions: config.maxConcurrentCompressions ?? 3,
     entitySimilarityThreshold: config.entitySimilarityThreshold ?? 0.92,
     defaultSearchLimit: config.defaultSearchLimit ?? 10,
@@ -43,9 +42,7 @@ function resolveConfig(config) {
     knowledgeGraphTriggerScore: config.knowledgeGraphTriggerScore ?? 0.78,
     knowledgeGraphEntityTopK: config.knowledgeGraphEntityTopK ?? 10,
     knowledgeGraphAnchorTopK: config.knowledgeGraphAnchorTopK ?? 3,
-    knowledgeGraphHopLimit: config.knowledgeGraphHopLimit ?? 10,
-    graphExtractConcurrency: config.graphExtractConcurrency ?? 2,
-    graphBuildTimeoutMs: config.graphBuildTimeoutMs ?? 12e4
+    knowledgeGraphHopLimit: config.knowledgeGraphHopLimit ?? 10
   };
 }
 
@@ -229,45 +226,27 @@ var EmbedService = class {
     const inputs = Array.isArray(texts) ? texts : [texts];
     const url = `${this.config.embeddingBaseUrl.replace(/\/$/, "")}/embeddings`;
     const batchSize = Math.max(1, this.config.embeddingBatchSize);
-    const concurrency = Math.max(1, this.config.embeddingConcurrency);
     const retryOpts = { timeoutMs: this.config.httpTimeoutMs, maxRetries: this.config.httpMaxRetries };
-    const batches = [];
+    const out = [];
     for (let i = 0; i < inputs.length; i += batchSize) {
-      batches.push({ index: batches.length, texts: inputs.slice(i, i + batchSize) });
-    }
-    const batchResults = await mapLimit(batches, concurrency, async (batch) => {
+      const batch = inputs.slice(i, i + batchSize);
       const data = await postJsonWithRetry(
         url,
         { Authorization: `Bearer ${this.config.embeddingApiKey}` },
-        { model: this.config.embeddingModel, input: batch.texts },
+        { model: this.config.embeddingModel, input: batch },
         retryOpts,
         "Embedding API"
       );
-      return {
-        index: batch.index,
-        vectors: data.data.sort((a, b) => a.index - b.index).map((d) => d.embedding)
-      };
-    });
-    return batchResults.sort((a, b) => a.index - b.index).flatMap((b) => b.vectors);
+      const sorted = data.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
+      out.push(...sorted);
+    }
+    return out;
   }
   async embedOne(text) {
     const result = await this.embed([text]);
     return result[0];
   }
 };
-async function mapLimit(items, limit, mapper) {
-  const results = new Array(items.length);
-  let next = 0;
-  const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
-    while (true) {
-      const index = next++;
-      if (index >= items.length) return;
-      results[index] = await mapper(items[index], index);
-    }
-  });
-  await Promise.all(workers);
-  return results;
-}
 function cosineSimilarity(a, b) {
   let dot = 0;
   let normA = 0;
@@ -281,8 +260,24 @@ function cosineSimilarity(a, b) {
   return dot / (Math.sqrt(normA) * Math.sqrt(normB));
 }
 
+// src/page.util.ts
+function normalizePage(page) {
+  const offset = Math.max(0, Math.floor(page.offset ?? 0));
+  const limit = page.limit != null && page.limit > 0 ? Math.floor(page.limit) : 0;
+  return { offset, limit };
+}
+function paginate(items, page) {
+  const total = items.length;
+  const { offset, limit } = normalizePage(page);
+  const slice = limit > 0 ? items.slice(offset, offset + limit) : items.slice(offset);
+  return { items: slice, total, offset, limit };
+}
+function cmpStr(a, b) {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
 // src/db/grafeo.service.ts
-var GrafeoService = class {
+var GrafeoService = class _GrafeoService {
   config;
   db;
   constructor(config) {
@@ -459,16 +454,17 @@ var GrafeoService = class {
       const r = row;
       return {
         type: "relation",
-        content: `${r["a.name"]} -[${r["type(r)"]}]-> ${r["b.name"]}`,
+        content: `${r["fromName"]} -[${r["relType"]}]-> ${r["toName"]}`,
         score: 1,
-        meta: { happenedAt: r["r.happenedAt"] }
+        meta: { happenedAt: r["happenedAt"] }
       };
     });
+    const RETURN_CLAUSE = "RETURN a.name AS fromName, type(r) AS relType, b.name AS toName, r.happenedAt AS happenedAt";
     try {
       const result = await this.db.execute(
         `MATCH (a:Entity {name: $name, userId: $userId, chatId: $chatId, kind: $kind})-[r]->(b)
          WHERE r.chatId = $chatId AND r.userId = $userId
-         RETURN a.name, type(r), b.name, r.happenedAt LIMIT $limit`,
+         ${RETURN_CLAUSE} LIMIT $limit`,
         { name: entityName, userId, chatId, kind, limit }
       );
       return mapRows(result.toArray());
@@ -477,7 +473,7 @@ var GrafeoService = class {
     try {
       const result = await this.db.execute(
         `MATCH (a:Entity {name: $name, userId: $userId, chatId: $chatId, kind: $kind})-[r]->(b)
-         RETURN a.name, type(r), b.name, r.happenedAt LIMIT $limit`,
+         ${RETURN_CLAUSE} LIMIT $limit`,
         { name: entityName, userId, chatId, kind, limit }
       );
       return mapRows(result.toArray());
@@ -500,56 +496,176 @@ var GrafeoService = class {
     }
   }
   // ── 管理面板用：全量读取实体 / 关系 ────────────────────────────────────────────────
-  /** 全量读取实体节点（管理面板/知识图谱用，剔除体积大的 embedding 字段）*/
-  async getAllEntities(limit = 1e3) {
+  /**
+   * 构建按域过滤的内联属性子句（如 ` {userId: $userId, chatId: $chatId}`）。
+   * 在 LIMIT 之前生效，避免「先截断再过滤」导致结果不足。
+   */
+  buildScopeMatch(filter, params) {
+    const props = [];
+    if (filter?.userId) {
+      props.push("userId: $userId");
+      params.userId = filter.userId;
+    }
+    if (filter?.chatId) {
+      props.push("chatId: $chatId");
+      params.chatId = filter.chatId;
+    }
+    return props.length > 0 ? ` {${props.join(", ")}}` : "";
+  }
+  // 关系查询的统一 RETURN 子句：用别名（AS）取列，避免函数表达式 type(r)/id(r) 的默认列名
+  // 被归一为 "type(...)"/"id(...)"（按 r["type(r)"] 取会得到 undefined）。id(r) 同时用于 ORDER BY。
+  static RELATION_RETURN = `RETURN a.name AS fromName, b.name AS toName, type(r) AS relType,
+            r.happenedAt AS happenedAt, r.userId AS userId, r.chatId AS chatId,
+            r.sessionId AS sessionId, id(r) AS rid`;
+  /** 节点 → Entity 映射（剔除体积大的 embedding 字段）*/
+  nodeToEntity(node) {
+    const props = node.properties();
+    const { embedding: _embedding, name, userId, chatId, sessionId, ...rest } = props;
+    const type = (node.labels ?? []).filter((l) => l !== "Entity").join(", ") || "\u672A\u77E5";
+    return {
+      name: String(name ?? ""),
+      type,
+      meta: {
+        userId: String(userId ?? ""),
+        chatId: String(chatId ?? ""),
+        sessionId: String(sessionId ?? ""),
+        ...rest
+      }
+    };
+  }
+  /** 关系查询结果行 → Relation 映射（依赖 RELATION_RETURN 的别名列）*/
+  rowToRelation(row) {
+    const r = row;
+    return {
+      from: String(r["fromName"] ?? ""),
+      to: String(r["toName"] ?? ""),
+      type: String(r["relType"] ?? ""),
+      happenedAt: r["happenedAt"] != null ? Number(r["happenedAt"]) : void 0,
+      meta: {
+        userId: String(r["userId"] ?? ""),
+        chatId: String(r["chatId"] ?? ""),
+        sessionId: String(r["sessionId"] ?? "")
+      }
+    };
+  }
+  /** 统计实体数（可选按域过滤），用于分页 total */
+  async countEntities(filter) {
+    try {
+      const params = {};
+      const scope = this.buildScopeMatch(filter, params);
+      const res = await this.db.execute(`MATCH (n:Entity${scope}) RETURN count(n) AS cnt`, params);
+      return Number(res.toArray()[0]?.cnt ?? 0);
+    } catch {
+      return 0;
+    }
+  }
+  /** 统计关系数（可选按域过滤），用于分页 total */
+  async countRelations(filter) {
     try {
-      const result = await this.db.execute(`MATCH (n:Entity) RETURN n LIMIT $limit`, { limit });
+      const params = {};
+      const scope = this.buildScopeMatch(filter, params);
+      const res = await this.db.execute(
+        `MATCH (a:Entity${scope})-[r]->(b:Entity) RETURN count(r) AS cnt`,
+        params
+      );
+      return Number(res.toArray()[0]?.cnt ?? 0);
+    } catch {
+      return 0;
+    }
+  }
+  /**
+   * 全量读取实体节点（管理面板/知识图谱用，剔除体积大的 embedding 字段）。
+   * 可选按 userId / chatId 过滤（在节点属性上匹配，LIMIT 前生效）。
+   * 按节点内部 id 升序，确保「同样条件 → 同样顺序」。
+   * 注意：此方法带安全上限 limit，超出会截断；需要准确 total 与翻页请用 pageEntities。
+   */
+  async getAllEntities(filter, limit = 1e3) {
+    try {
+      const params = { limit };
+      const scope = this.buildScopeMatch(filter, params);
+      const result = await this.db.execute(`MATCH (n:Entity${scope}) RETURN n LIMIT $limit`, params);
       const nodes = result.nodes();
-      return nodes.map((node) => {
-        const props = node.properties();
-        const { embedding: _embedding, name, userId, chatId, sessionId, ...rest } = props;
-        const type = (node.labels ?? []).filter((l) => l !== "Entity").join(", ") || "\u672A\u77E5";
-        return {
-          name: String(name ?? ""),
-          type,
-          meta: {
-            userId: String(userId ?? ""),
-            chatId: String(chatId ?? ""),
-            sessionId: String(sessionId ?? ""),
-            ...rest
-          }
-        };
-      });
+      nodes.sort((a, b) => a.id - b.id);
+      return nodes.map((node) => this.nodeToEntity(node));
     } catch {
       return [];
     }
   }
-  /** 全量读取关系边（管理面板/知识图谱用）*/
-  async getAllRelations(limit = 2e3) {
+  /**
+   * 分页读取实体节点：把 ORDER BY id(n) + SKIP/LIMIT 下推到查询层，并用 count 取准确 total。
+   * 不受 getAllEntities 安全上限约束。返回当前页 items 与过滤后的 total。
+   */
+  async pageEntities(filter, page) {
+    const { offset, limit } = normalizePage(page);
+    try {
+      const total = await this.countEntities(filter);
+      const effLimit = limit > 0 ? limit : Math.max(0, total - offset);
+      if (effLimit <= 0) return { items: [], total };
+      const params = {};
+      const scope = this.buildScopeMatch(filter, params);
+      params.offset = offset;
+      params.limit = effLimit;
+      const res = await this.db.execute(
+        `MATCH (n:Entity${scope}) RETURN id(n) AS nid ORDER BY nid SKIP $offset LIMIT $limit`,
+        params
+      );
+      const items = [];
+      for (const row of res.toArray()) {
+        const nid = Number(row.nid);
+        const node = this.db.getNode(nid);
+        if (node) items.push(this.nodeToEntity(node));
+      }
+      return { items, total };
+    } catch {
+      return { items: [], total: 0 };
+    }
+  }
+  /**
+   * 全量读取关系边（管理面板/知识图谱用）。可选按 userId / chatId 过滤：在源实体节点的域属性上匹配
+   *（关系两端与边均同域，故按源节点过滤即可，且节点内联属性匹配在各 grafeo 版本均可靠）。
+   * 按 id(r) 升序确保顺序确定。
+   * 注意：此方法带安全上限 limit，超出会截断；需要准确 total 与翻页请用 pageRelations。
+   */
+  async getAllRelations(filter, limit = 2e3) {
     try {
+      const params = { limit };
+      const scope = this.buildScopeMatch(filter, params);
       const result = await this.db.execute(
-        `MATCH (a:Entity)-[r]->(b:Entity)
-         RETURN a.name, type(r), b.name, r.happenedAt, r.userId, r.chatId, r.sessionId LIMIT $limit`,
-        { limit }
+        `MATCH (a:Entity${scope})-[r]->(b:Entity)
+         ${_GrafeoService.RELATION_RETURN}
+         ORDER BY rid LIMIT $limit`,
+        params
       );
-      return result.toArray().map((row) => {
-        const r = row;
-        return {
-          from: String(r["a.name"] ?? ""),
-          to: String(r["b.name"] ?? ""),
-          type: String(r["type(r)"] ?? ""),
-          happenedAt: r["r.happenedAt"] != null ? Number(r["r.happenedAt"]) : void 0,
-          meta: {
-            userId: String(r["r.userId"] ?? ""),
-            chatId: String(r["r.chatId"] ?? ""),
-            sessionId: String(r["r.sessionId"] ?? "")
-          }
-        };
-      });
+      return result.toArray().map((row) => this.rowToRelation(row));
     } catch {
       return [];
     }
   }
+  /**
+   * 分页读取关系边：把 ORDER BY id(r) + SKIP/LIMIT 下推到查询层，并用 count 取准确 total。
+   * 不受 getAllRelations 安全上限约束。返回当前页 items 与过滤后的 total。
+   */
+  async pageRelations(filter, page) {
+    const { offset, limit } = normalizePage(page);
+    try {
+      const total = await this.countRelations(filter);
+      const effLimit = limit > 0 ? limit : Math.max(0, total - offset);
+      if (effLimit <= 0) return { items: [], total };
+      const params = {};
+      const scope = this.buildScopeMatch(filter, params);
+      params.offset = offset;
+      params.limit = effLimit;
+      const res = await this.db.execute(
+        `MATCH (a:Entity${scope})-[r]->(b:Entity)
+         ${_GrafeoService.RELATION_RETURN}
+         ORDER BY rid SKIP $offset LIMIT $limit`,
+        params
+      );
+      return { items: res.toArray().map((row) => this.rowToRelation(row)), total };
+    } catch {
+      return { items: [], total: 0 };
+    }
+  }
   close() {
     try {
       this.db.close();
@@ -1051,6 +1167,15 @@ var LanceService = class {
       return [];
     }
   }
+  /** 取某会话的全部消息（按 createdAt 升序），供管理面板分页切片使用 */
+  async getAllMessagesBySession(sessionId) {
+    try {
+      const rows = await this.messagesTable.query().where(eqFilter("session_id", sessionId)).toArray();
+      return rows.sort((a, b) => Number(a.created_at) - Number(b.created_at) || cmpStr(a.message_id, b.message_id)).map(rowToMessage);
+    } catch {
+      return [];
+    }
+  }
   async searchMessages(vector, filter, limit = 10) {
     const q = this.messagesTable.vectorSearch(vector).limit(limit);
     if (filter) q.where(filter);
@@ -1082,8 +1207,7 @@ var LanceService = class {
         const total = rows.length;
         return rows.map((r, idx) => ({
           row: r,
-          // 位置分（越前越高）+ recall_count 加成
-          score: 1 - idx / total + Math.log1p(Number(r.recall_count)) * 0.1
+          score: total - idx + Math.log1p(Number(r.recall_count))
         })).sort((a, b) => b.score - a.score).map((x) => rowToTopic(x.row));
       }
     } catch {
@@ -1151,7 +1275,7 @@ var LanceService = class {
   async getAllTopics() {
     try {
       const rows = await this.topicsTable.query().toArray();
-      return rows.sort((a, b) => Number(b.end_time) - Number(a.end_time)).map(rowToTopic);
+      return rows.sort((a, b) => Number(b.end_time) - Number(a.end_time) || cmpStr(a.summary_id, b.summary_id)).map(rowToTopic);
     } catch {
       return [];
     }
@@ -1324,7 +1448,7 @@ var LanceService = class {
   async getAllDocuments() {
     try {
       const rows = await this.documentsTable.query().toArray();
-      return rows.sort((a, b) => Number(b.updated_at) - Number(a.updated_at)).map(rowToDocument);
+      return rows.sort((a, b) => Number(b.updated_at) - Number(a.updated_at) || cmpStr(a.doc_id, b.doc_id)).map(rowToDocument);
     } catch {
       return [];
     }
@@ -1478,7 +1602,7 @@ var LlmService = class {
     return data.choices[0].message;
   }
   // ── 第一步：生成三级摘要（JSON 输出）──────────────────────────────────────────
-  async summarizeMessages(messages) {
+  async getSummary(messages) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const { detailMaxTokens, summaryMaxTokens, conciseMaxTokens } = this.config;
     const systemPrompt = `\u4F60\u662F\u4E00\u4E2A\u5BF9\u8BDD\u8BB0\u5FC6\u7BA1\u7406\u52A9\u624B\u3002\u5F53\u524D\u7CFB\u7EDF\u65F6\u95F4\uFF1A${now}\u3002
@@ -1500,7 +1624,7 @@ ${formatted}`);
     return { title: parsed.title ?? "", detail: parsed.detail, summary: parsed.summary, concise: parsed.concise };
   }
   // ── 第二步：通过工具调用提取实体和关系 ──────────────────────────────────────
-  async extractEntitiesFromMessages(messages) {
+  async extractEntitiesWithTool(messages) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const systemPrompt = `\u4F60\u662F\u4E00\u4E2A\u5B9E\u4F53\u5173\u7CFB\u62BD\u53D6\u52A9\u624B\u3002\u5F53\u524D\u7CFB\u7EDF\u65F6\u95F4\uFF1A${now}\u3002
 \u68C0\u67E5\u7ED9\u5B9A\u7684\u5BF9\u8BDD\u5185\u5BB9\uFF0C\u5224\u65AD\u5176\u4E2D\u662F\u5426\u5B58\u5728\u503C\u5F97\u8BB0\u5F55\u7684\u547D\u540D\u5B9E\u4F53\uFF08\u4EBA\u7269\u3001\u7EC4\u7EC7\u3001\u9879\u76EE\u3001\u5730\u70B9\u3001\u6280\u672F\u7B49\uFF09\u548C\u5B83\u4EEC\u4E4B\u95F4\u7684\u5173\u7CFB\u3002
@@ -1528,15 +1652,15 @@ ${formatted}`
         }
       }
     } catch (err) {
-      console.error("[LlmService] extractEntitiesFromMessages failed:", err);
+      console.error("[LlmService] extractEntitiesWithTool failed:", err);
     }
     return { entities: [], relations: [] };
   }
   // ── 对外主接口：压缩 + 实体抽取（并发执行两步）────────────────────────────────
   async compress(messages) {
     const [summary, extraction] = await Promise.all([
-      this.summarizeMessages(messages),
-      this.extractEntitiesFromMessages(messages)
+      this.getSummary(messages),
+      this.extractEntitiesWithTool(messages)
     ]);
     return {
       title: summary.title,
@@ -1688,16 +1812,16 @@ var CompressManager = class {
     this.sessionCache = sessionCache;
     this.semaphore = new Semaphore(config.maxConcurrentCompressions);
   }
-  triggerCompress(sessionId, force = false, waitGraph = false) {
+  triggerCompress(sessionId, force = false) {
     const chain = this.sessionChain.get(sessionId) ?? Promise.resolve();
     const next = chain.then(
-      () => this.semaphore.run(() => this.doCompress(sessionId, force, waitGraph))
+      () => this.semaphore.run(() => this.doCompress(sessionId, force))
     );
     this.sessionChain.set(sessionId, next.catch(() => {
     }));
     return next;
   }
-  async doCompress(sessionId, force, waitGraph) {
+  async doCompress(sessionId, force) {
     const messages = this.sessionCache.getSessionMessages(sessionId);
     if (messages.length === 0) return;
     const entry = this.sessionCache.getEntry(sessionId);
@@ -1706,15 +1830,15 @@ var CompressManager = class {
     const { chatId, userId } = entry.ids;
     const startTime = messages[0].createdAt;
     const endTime = messages[messages.length - 1].createdAt;
-    let summary;
+    let compressOutput;
     try {
-      summary = await this.llm.summarizeMessages(messages);
+      compressOutput = await this.llm.compress(messages);
     } catch (err) {
       console.error(`[CompressManager] LLM compress failed for session ${sessionId}:`, err);
       return;
     }
-    const { title, detail, summary: summaryText, concise } = summary;
-    const topicTextForEmbed = [detail, summaryText, concise].find((t) => t.length > 0) ?? "";
+    const { title, detail, summary, concise, entities, relations } = compressOutput;
+    const topicTextForEmbed = [detail, summary, concise].find((t) => t.length > 0) ?? "";
     let topicVector = [];
     try {
       topicVector = await this.embed.embedOne(topicTextForEmbed);
@@ -1728,7 +1852,7 @@ var CompressManager = class {
       chatId,
       title,
       detail,
-      summary: summaryText,
+      summary,
       concise,
       startTime,
       endTime,
@@ -1742,6 +1866,9 @@ var CompressManager = class {
     } catch (err) {
       console.error(`[CompressManager] Save topic failed:`, err);
     }
+    if (entities.length > 0 || relations.length > 0) {
+      await this.persistGraph(entities, relations, sessionId, chatId, userId, endTime);
+    }
     this.sessionCache.clearMessages(sessionId, endTime);
     const [n1, n2, n3] = this.config.topicRatio;
     try {
@@ -1750,19 +1877,6 @@ var CompressManager = class {
     } catch (err) {
       console.error(`[CompressManager] Rebuild history window failed:`, err);
     }
-    const graphTask = this.extractAndPersistGraph(messages, sessionId, chatId, userId, endTime);
-    if (waitGraph) {
-      await withTimeout(graphTask, this.config.graphBuildTimeoutMs, "flushChat graph build");
-    } else {
-      graphTask.catch((err) => {
-        console.error(`[CompressManager] Background graph persist failed:`, err);
-      });
-    }
-  }
-  async extractAndPersistGraph(messages, sessionId, chatId, userId, endTime) {
-    const { entities, relations } = await this.llm.extractEntitiesFromMessages(messages);
-    if (entities.length === 0 && relations.length === 0) return;
-    await this.persistGraph(entities, relations, sessionId, chatId, userId, endTime);
   }
   async persistGraph(rawEntities, rawRelations, sessionId, chatId, userId, messageTime) {
     const entities = rawEntities.map((e) => ({
@@ -1805,13 +1919,6 @@ var CompressManager = class {
     }
   }
 };
-function withTimeout(promise, timeoutMs, label) {
-  let timer;
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
-  });
-  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
-}
 
 // src/manager/fact.cache.ts
 import { v4 as uuidv42 } from "uuid";
@@ -2071,29 +2178,20 @@ var KnowledgeManager = class {
       updatedAt: now
     };
     await this.lance.addDocument(doc);
-    const chunkIngest = this.semaphore.run(() => this.ingestChunks(doc, pieces));
-    const graphBuild = chunkIngest.then((chunks) => {
-      if (!shouldBuildGraph) return;
-      return this.buildDocumentGraph(doc, chunks);
-    });
-    if (opts.wait || opts.waitGraph) {
-      await chunkIngest;
-    } else {
-      chunkIngest.catch((err) => {
-        console.error("[KnowledgeManager] background chunk ingest failed:", err);
-      });
-    }
-    if (opts.waitGraph) {
-      await withTimeout2(graphBuild, this.config.graphBuildTimeoutMs, "document graph build");
+    const background = this.semaphore.run(
+      () => this.ingestChunksAndGraph(doc, pieces, shouldBuildGraph)
+    );
+    if (opts.wait) {
+      await background;
     } else {
-      graphBuild.catch((err) => {
-        console.error("[KnowledgeManager] background graph build failed:", err);
+      background.catch((err) => {
+        console.error("[KnowledgeManager] background ingest failed:", err);
       });
     }
     return { docId };
   }
-  async ingestChunks(doc, pieces) {
-    if (pieces.length === 0) return [];
+  async ingestChunksAndGraph(doc, pieces, buildGraph) {
+    if (pieces.length === 0) return;
     const redundant = this.config.chunkRedundantIds;
     const embedInputs = pieces.map(
       (p) => p.headingPath ? `${p.headingPath}
@@ -2104,7 +2202,7 @@ ${p.content}` : p.content
       vectors = await this.embed.embed(embedInputs);
     } catch (err) {
       console.error("[KnowledgeManager] embed chunks failed:", err);
-      return [];
+      return;
     }
     const chunks = pieces.map((p, i) => ({
       chunkId: uuidv43(),
@@ -2121,12 +2219,17 @@ ${p.content}` : p.content
       createdAt: doc.createdAt
     }));
     await this.lance.addChunks(chunks);
-    return chunks;
+    if (buildGraph) {
+      await this.buildDocumentGraph(doc, chunks).catch((err) => {
+        console.error("[KnowledgeManager] build graph failed:", err);
+      });
+    }
   }
   async buildDocumentGraph(doc, chunks) {
-    const extracted = await mapLimit2(chunks, this.config.graphExtractConcurrency, async (chunk) => {
+    let extractedAny = false;
+    for (const chunk of chunks) {
       const { entities: rawEntities, relations: rawRelations } = await this.llm.extractEntitiesFromText(chunk.content);
-      if (rawEntities.length === 0 && rawRelations.length === 0) return null;
+      if (rawEntities.length === 0 && rawRelations.length === 0) continue;
       const meta = {
         userId: doc.userId,
         chatId: doc.chatId,
@@ -2135,47 +2238,46 @@ ${p.content}` : p.content
         chunkId: chunk.chunkId,
         messageTime: doc.createdAt
       };
-      const entities2 = rawEntities.map((e) => ({
+      const entities = rawEntities.map((e) => ({
         name: e.name,
         type: e.type,
         meta: { ...meta, ...e.meta }
       }));
-      const relations2 = rawRelations.map((r) => ({
+      const relations = rawRelations.map((r) => ({
         from: r.from,
         to: r.to,
         type: r.type,
         happenedAt: r.happenedAt ?? void 0,
         meta: { ...meta, ...r.meta }
       }));
-      return { entities: entities2, relations: relations2 };
-    });
-    const entities = extracted.flatMap((item) => item?.entities ?? []);
-    const relations = extracted.flatMap((item) => item?.relations ?? []);
-    if (entities.length === 0 && relations.length === 0) return;
-    const allNames = [
-      .../* @__PURE__ */ new Set([
-        ...entities.map((e) => e.name),
-        ...relations.flatMap((r) => [r.from, r.to])
-      ])
-    ];
-    if (allNames.length === 0) return;
-    const embeddings = /* @__PURE__ */ new Map();
-    try {
-      const vecs = await this.embed.embed(allNames);
-      allNames.forEach((name, i) => embeddings.set(name, vecs[i]));
-    } catch (err) {
-      console.error("[KnowledgeManager] embed entity names failed:", err);
-      return;
+      const allNames = [
+        .../* @__PURE__ */ new Set([
+          ...entities.map((e) => e.name),
+          ...relations.flatMap((r) => [r.from, r.to])
+        ])
+      ];
+      if (allNames.length === 0) continue;
+      const embeddings = /* @__PURE__ */ new Map();
+      try {
+        const vecs = await this.embed.embed(allNames);
+        allNames.forEach((name, i) => embeddings.set(name, vecs[i]));
+      } catch (err) {
+        console.error("[KnowledgeManager] embed entity names failed:", err);
+        continue;
+      }
+      await this.grafeo.upsertEntitiesAndRelations(
+        entities,
+        relations,
+        embeddings,
+        KIND_KNOWLEDGE
+      );
+      extractedAny = true;
+    }
+    if (extractedAny) {
+      await this.lance.updateDocumentGraphFlag(doc.docId, true).catch((err) => {
+        console.error(`[KnowledgeManager] Failed to update graph flag for doc ${doc.docId}:`, err);
+      });
     }
-    await this.grafeo.upsertEntitiesAndRelations(
-      entities,
-      relations,
-      embeddings,
-      KIND_KNOWLEDGE
-    );
-    await this.lance.updateDocumentGraphFlag(doc.docId, true).catch((err) => {
-      console.error(`[KnowledgeManager] Failed to update graph flag for doc ${doc.docId}:`, err);
-    });
   }
   // ── 检索 ───────────────────────────────────────────────────────────────────────
   async searchKnowledge(opts) {
@@ -2293,12 +2395,12 @@ ${p.content}` : p.content
     });
     return true;
   }
-  async listDocuments(filter) {
+  async listDocuments(filter, page) {
     let docs = await this.lance.getAllDocuments();
     if (filter?.userId) docs = docs.filter((d) => d.userId === filter.userId);
     if (filter?.chatId) docs = docs.filter((d) => d.chatId === filter.chatId);
     if (filter?.sessionId) docs = docs.filter((d) => d.sessionId === filter.sessionId);
-    return docs;
+    return page ? paginate(docs, page) : docs;
   }
 };
 var NO_MATCH = Symbol("no-match");
@@ -2337,26 +2439,6 @@ function inferTitle(markdown) {
   }
   return void 0;
 }
-async function mapLimit2(items, limit, mapper) {
-  const results = new Array(items.length);
-  let next = 0;
-  const workers = Array.from({ length: Math.min(Math.max(1, limit), items.length) }, async () => {
-    while (true) {
-      const index = next++;
-      if (index >= items.length) return;
-      results[index] = await mapper(items[index], index);
-    }
-  });
-  await Promise.all(workers);
-  return results;
-}
-function withTimeout2(promise, timeoutMs, label) {
-  let timer;
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
-  });
-  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
-}
 
 // src/manager/session.cache.ts
 var SessionCache = class {
@@ -2571,7 +2653,7 @@ var MemoryManager = class {
   }
   async flushChat(sessionId, opts) {
     const sid = sessionId ?? DEFAULT_SESSION_ID;
-    const promise = this.compressManager.triggerCompress(sid, true, opts?.waitGraph === true);
+    const promise = this.compressManager.triggerCompress(sid, true);
     if (opts?.wait) await promise;
   }
   async updateFacts(content, level, userId, chatId, sessionId) {
@@ -2778,33 +2860,28 @@ var MemoryManager = class {
     const n = Math.min(365, Math.max(1, Math.floor(days)));
     return this.lance.trendDaily(n);
   }
-  /** 列出会话，可选按 userId / chatId 过滤，按更新时间倒序 */
-  listSessions(filter) {
+  listSessions(filter, page) {
     let results = [...this.sessionMap.values()];
     if (filter?.userId) results = results.filter((s) => s.userId === filter.userId);
     if (filter?.chatId) results = results.filter((s) => s.chatId === filter.chatId);
-    return results.sort((a, b) => b.updatedAt - a.updatedAt);
+    results.sort((a, b) => b.updatedAt - a.updatedAt || cmpStr(a.sessionId, b.sessionId));
+    return page ? paginate(results, page) : results;
   }
-  /** 列出会话内的消息（按时间正序）*/
-  async listMessages(sessionId, limit = 100) {
-    return this.lance.getLatestMessages(sessionId, limit);
+  async listMessages(sessionId, limitOrPage) {
+    if (typeof limitOrPage === "object") {
+      const all = await this.lance.getAllMessagesBySession(sessionId);
+      return paginate(all, limitOrPage);
+    }
+    return this.lance.getLatestMessages(sessionId, limitOrPage ?? 100);
   }
-  /** 列出主题/摘要，可选按 sessionId / userId / chatId 过滤 */
-  async listTopics(filter) {
+  async listTopics(filter, page) {
     let topics = await this.lance.getAllTopics();
     if (filter?.sessionId) topics = topics.filter((t) => t.sessionId === filter.sessionId);
     if (filter?.userId) topics = topics.filter((t) => t.userId === filter.userId);
     if (filter?.chatId) topics = topics.filter((t) => t.chatId === filter.chatId);
-    return topics;
+    return page ? paginate(topics, page) : topics;
   }
-  /**
-   * 列出事实，按创建时间倒序。过滤遵循 scope 层级包含语义：
-   * - 按 chatId 过滤时，除该 chat 级 facts 外，还包含该 chat 所属 user 的 user 级 facts
-   *   （user 级对其下所有 chat/session 生效）。
-   * - 按 userId 过滤时，返回该 user 名下全部 facts（两级都带 userId）。
-   * - level 过滤在层级过滤之后再叠加。
-   */
-  listFacts(filter) {
+  listFacts(filter, page) {
     let facts = this.factCache.all();
     if (filter?.chatId) {
       const chatId = filter.chatId;
@@ -2816,7 +2893,8 @@ var MemoryManager = class {
       facts = facts.filter((f) => f.userId === filter.userId);
     }
     if (filter?.level) facts = facts.filter((f) => f.level === filter.level);
-    return facts.sort((a, b) => b.createdAt - a.createdAt);
+    facts.sort((a, b) => b.createdAt - a.createdAt || cmpStr(a.factId, b.factId));
+    return page ? paginate(facts, page) : facts;
   }
   /** 由 chatId 反查所属 userId：优先用会话表映射，兜底用 chat 级 fact 自身。 */
   resolveChatOwner(chatId) {
@@ -2833,13 +2911,17 @@ var MemoryManager = class {
   async deleteFact(factId) {
     return this.factCache.remove(factId);
   }
-  /** 列出全部实体（知识图谱节点）*/
-  async listEntities() {
-    return this.grafeo.getAllEntities();
+  async listEntities(filter, page) {
+    if (!page) return this.grafeo.getAllEntities(filter);
+    const { offset, limit } = normalizePage(page);
+    const { items, total } = await this.grafeo.pageEntities(filter, page);
+    return { items, total, offset, limit };
   }
-  /** 列出全部关系（知识图谱边）*/
-  async listRelations() {
-    return this.grafeo.getAllRelations();
+  async listRelations(filter, page) {
+    if (!page) return this.grafeo.getAllRelations(filter);
+    const { offset, limit } = normalizePage(page);
+    const { items, total } = await this.grafeo.pageRelations(filter, page);
+    return { items, total, offset, limit };
   }
   // ── 知识库 API ────────────────────────────────────────────────────────────────
   /** 摄入一个文档（markdown）。document 落库即返回，切块/embedding/图谱后台执行（wait=true 可等待）。*/
@@ -2858,9 +2940,8 @@ var MemoryManager = class {
   async deleteDocument(docId) {
     return this.knowledgeManager.deleteDocument(docId);
   }
-  /** 列出文档，可选按 userId / chatId / sessionId 过滤，按更新时间倒序。*/
-  async listDocuments(filter) {
-    return this.knowledgeManager.listDocuments(filter);
+  async listDocuments(filter, page) {
+    return page ? this.knowledgeManager.listDocuments(filter, page) : this.knowledgeManager.listDocuments(filter);
   }
   destroy() {
     this.grafeo.close();