@ppagent/memory 0.1.0 → 0.1.2

package/dist/index.js

@@ -45,7 +45,10 @@ function resolveConfig(config) {
     knowledgeGraphAnchorTopK: config.knowledgeGraphAnchorTopK ?? 3,
     knowledgeGraphHopLimit: config.knowledgeGraphHopLimit ?? 10,
     graphExtractConcurrency: config.graphExtractConcurrency ?? 2,
-    graphBuildTimeoutMs: config.graphBuildTimeoutMs ?? 12e4
+    graphBuildTimeoutMs: config.graphBuildTimeoutMs ?? 12e4,
+    autoOptimizeOnInit: config.autoOptimizeOnInit ?? true,
+    optimizeVersionRetentionMs: config.optimizeVersionRetentionMs ?? 0,
+    restoreConcurrency: config.restoreConcurrency ?? 8
   };
 }
 
@@ -165,6 +168,16 @@ import { GrafeoDB } from "@grafeo-db/js";
 import { get_encoding } from "@dqbd/tiktoken";
 
 // src/llm/http.ts
+function normalizeFetchError(err, timeoutMs, errorLabel) {
+  if (isAbortError(err)) {
+    return new Error(`${errorLabel} request timed out after ${timeoutMs}ms`, { cause: err });
+  }
+  if (err instanceof Error) return err;
+  return new Error(String(err));
+}
+function isAbortError(err) {
+  return typeof err === "object" && err !== null && "name" in err && err.name === "AbortError";
+}
 function backoffDelay(attempt) {
   return Math.min(1e3 * 2 ** attempt, 8e3);
 }
@@ -173,7 +186,9 @@ async function postJsonWithRetry(url, headers, body, opts, errorLabel = "HTTP")
   let lastErr;
   for (let attempt = 0; attempt <= opts.maxRetries; attempt++) {
     const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    const timer = setTimeout(() => {
+      controller.abort(new Error(`${errorLabel} request timed out after ${opts.timeoutMs}ms`));
+    }, opts.timeoutMs);
     let res;
     try {
       res = await fetch(url, {
@@ -184,12 +199,12 @@ async function postJsonWithRetry(url, headers, body, opts, errorLabel = "HTTP")
       });
     } catch (err) {
       clearTimeout(timer);
-      lastErr = err;
+      lastErr = normalizeFetchError(err, opts.timeoutMs, errorLabel);
       if (attempt < opts.maxRetries) {
         await sleep(backoffDelay(attempt));
         continue;
       }
-      throw err;
+      throw lastErr;
     }
     clearTimeout(timer);
     if (res.ok) {
@@ -281,8 +296,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 +490,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 +509,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 +532,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 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 (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 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();
@@ -863,6 +1015,24 @@ function safeParseObject(s) {
     return {};
   }
 }
+var MESSAGES_INDEXES = [
+  { column: "message_id" },
+  { column: "session_id" },
+  { column: "content", fts: true },
+  { column: "metadata", fts: true }
+  // 支持 metadata 内容全文检索
+];
+var TOPICS_INDEXES = [
+  { column: "chat_id" },
+  { column: "detail", fts: true }
+];
+var SESSIONS_INDEXES = [{ column: "session_id" }];
+var DOCUMENTS_INDEXES = [{ column: "doc_id" }];
+var CHUNKS_INDEXES = [
+  { column: "doc_id" },
+  { column: "content", fts: true }
+  // 知识片段混合检索
+];
 var LanceService = class {
   config;
   conn;
@@ -875,6 +1045,7 @@ var LanceService = class {
   // Scalar indexes cannot be created on empty tables (LanceDB btree limitation).
   // These flags defer creation to the first insert.
   isNewMessagesTable = false;
+  isNewTopicsTable = false;
   isNewSessionsTable = false;
   isNewDocumentsTable = false;
   isNewChunksTable = false;
@@ -888,7 +1059,6 @@ var LanceService = class {
     if (existingTables.includes(MESSAGES_TABLE)) {
       this.messagesTable = await this.conn.openTable(MESSAGES_TABLE);
       await this._ensurePartsColumn();
-      await this.ensureScalarIndex(this.messagesTable, "message_id");
     } else {
       this.messagesTable = await this.conn.createEmptyTable(
         MESSAGES_TABLE,
@@ -904,6 +1074,7 @@ var LanceService = class {
         TOPICS_TABLE,
         topicsSchema(dim)
       );
+      this.isNewTopicsTable = true;
     }
     if (existingTables.includes(FACTS_TABLE)) {
       this.factsTable = await this.conn.openTable(FACTS_TABLE);
@@ -912,43 +1083,83 @@ var LanceService = class {
     }
     if (existingTables.includes(SESSIONS_TABLE)) {
       this.sessionsTable = await this.conn.openTable(SESSIONS_TABLE);
-      await this.ensureScalarIndex(this.sessionsTable, "session_id");
     } else {
       this.sessionsTable = await this.conn.createEmptyTable(SESSIONS_TABLE, sessionsSchema());
       this.isNewSessionsTable = true;
     }
     if (existingTables.includes(DOCUMENTS_TABLE)) {
       this.documentsTable = await this.conn.openTable(DOCUMENTS_TABLE);
-      await this.ensureScalarIndex(this.documentsTable, "doc_id");
     } else {
       this.documentsTable = await this.conn.createEmptyTable(DOCUMENTS_TABLE, documentsSchema(dim));
       this.isNewDocumentsTable = true;
     }
     if (existingTables.includes(CHUNKS_TABLE)) {
       this.chunksTable = await this.conn.openTable(CHUNKS_TABLE);
-      await this.ensureScalarIndex(this.chunksTable, "doc_id");
     } else {
       this.chunksTable = await this.conn.createEmptyTable(CHUNKS_TABLE, chunksSchema(dim));
       this.isNewChunksTable = true;
     }
-    await this.ensureFtsIndexes();
+    await this.ensureIndexes(this.messagesTable, MESSAGES_INDEXES);
+    await this.ensureIndexes(this.topicsTable, TOPICS_INDEXES);
+    await this.ensureIndexes(this.sessionsTable, SESSIONS_INDEXES);
+    await this.ensureIndexes(this.documentsTable, DOCUMENTS_INDEXES);
+    await this.ensureIndexes(this.chunksTable, CHUNKS_INDEXES);
   }
-  async ensureFtsIndexes() {
-    const ftsTargets = [
-      { table: this.messagesTable, column: "content" },
-      { table: this.messagesTable, column: "metadata" },
-      // 支持 metadata 内容全文检索
-      { table: this.topicsTable, column: "detail" },
-      { table: this.chunksTable, column: "content" }
-      // 知识片段混合检索
-    ];
-    for (const { table, column } of ftsTargets) {
+  /**
+   * 按需补齐索引：先经 listIndices 判存在，缺失的列才 createIndex（且 replace:false）。
+   * createIndex 默认 replace:true 会在每次启动时全量重建索引并提交新表版本——
+   * 这正是历史上「启动越来越慢 + _versions 目录膨胀」的根源，绝不可回退到无条件 createIndex。
+   */
+  async ensureIndexes(table, specs) {
+    let indexed;
+    try {
+      indexed = new Set((await table.listIndices()).flatMap((i) => i.columns));
+    } catch {
+      indexed = /* @__PURE__ */ new Set();
+    }
+    for (const { column, fts } of specs) {
+      if (indexed.has(column)) continue;
       try {
-        await table.createIndex(column, { config: lancedb.Index.fts() });
+        await table.createIndex(
+          column,
+          fts ? { config: lancedb.Index.fts(), replace: false } : { replace: false }
+        );
       } catch {
       }
     }
   }
+  /**
+   * 存储压实：逐表执行碎片合并 + 清理 retentionMs 之前的历史版本。
+   * 嵌入式场景下 LanceDB 不会自动做这件事，长期运行后版本/碎片无限累积会显著拖慢启动与查询。
+   */
+  async optimizeStorage(retentionMs = 0) {
+    const cutoff = new Date(Date.now() - Math.max(0, retentionMs));
+    const targets = [
+      [MESSAGES_TABLE, this.messagesTable],
+      [TOPICS_TABLE, this.topicsTable],
+      [FACTS_TABLE, this.factsTable],
+      [SESSIONS_TABLE, this.sessionsTable],
+      [DOCUMENTS_TABLE, this.documentsTable],
+      [CHUNKS_TABLE, this.chunksTable]
+    ];
+    const results = [];
+    for (const [name, table] of targets) {
+      try {
+        const stats = await table.optimize({ cleanupOlderThan: cutoff });
+        results.push({
+          table: name,
+          fragmentsRemoved: stats.compaction.fragmentsRemoved,
+          fragmentsAdded: stats.compaction.fragmentsAdded,
+          filesRemoved: stats.compaction.filesRemoved,
+          oldVersionsRemoved: stats.prune.oldVersionsRemoved,
+          bytesRemoved: Number(stats.prune.bytesRemoved)
+        });
+      } catch (err) {
+        console.warn(`[LanceService] optimize table "${name}" failed:`, err);
+      }
+    }
+    return results;
+  }
   /**
    * 为存量 messages 表添加 parts 列（如果缺失）。
    * LanceDB 0.14+ 支持 addColumns；旧版本会 throw，此时 rowToMessage 的 ?? "[]" 兜底。
@@ -985,24 +1196,20 @@ var LanceService = class {
     } catch {
     }
   }
-  // LanceDB btree scalar indexes require at least one row.
-  // For existing tables (opened in init) this is safe; for new tables we defer via isNew*Table flags.
-  async ensureScalarIndex(table, column) {
-    try {
-      await table.createIndex(column);
-    } catch {
-    }
-  }
   async addMessages(messages) {
     if (messages.length === 0) return;
     await this.messagesTable.add(messages.map(messageToRow));
     if (this.isNewMessagesTable) {
-      await this.ensureScalarIndex(this.messagesTable, "message_id");
+      await this.ensureIndexes(this.messagesTable, MESSAGES_INDEXES);
       this.isNewMessagesTable = false;
     }
   }
   async addTopic(topic) {
     await this.topicsTable.add([topicToRow(topic)]);
+    if (this.isNewTopicsTable) {
+      await this.ensureIndexes(this.topicsTable, TOPICS_INDEXES);
+      this.isNewTopicsTable = false;
+    }
   }
   async updateTopicRecallCount(summaryId, count) {
     await this.topicsTable.update({
@@ -1051,6 +1258,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 +1298,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 {
@@ -1127,7 +1342,7 @@ var LanceService = class {
   async insertSession(session) {
     await this.sessionsTable.add([sessionToRow(session)]);
     if (this.isNewSessionsTable) {
-      await this.ensureScalarIndex(this.sessionsTable, "session_id");
+      await this.ensureIndexes(this.sessionsTable, SESSIONS_INDEXES);
       this.isNewSessionsTable = false;
     }
   }
@@ -1151,7 +1366,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 [];
     }
@@ -1233,7 +1448,7 @@ var LanceService = class {
   async addDocument(doc) {
     await this.documentsTable.add([documentToRow(doc)]);
     if (this.isNewDocumentsTable) {
-      await this.ensureScalarIndex(this.documentsTable, "doc_id");
+      await this.ensureIndexes(this.documentsTable, DOCUMENTS_INDEXES);
       this.isNewDocumentsTable = false;
     }
   }
@@ -1241,7 +1456,7 @@ var LanceService = class {
     if (chunks.length === 0) return;
     await this.chunksTable.add(chunks.map(chunkToRow));
     if (this.isNewChunksTable) {
-      await this.ensureScalarIndex(this.chunksTable, "doc_id");
+      await this.ensureIndexes(this.chunksTable, CHUNKS_INDEXES);
       this.isNewChunksTable = false;
     }
   }
@@ -1324,7 +1539,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 [];
     }
@@ -1364,6 +1579,40 @@ var LanceService = class {
   }
 };
 
+// src/manager/semaphore.ts
+var Semaphore = class {
+  count;
+  queue = [];
+  constructor(max) {
+    this.count = max;
+  }
+  async run(fn) {
+    await this.acquire();
+    try {
+      return await fn();
+    } finally {
+      this.release();
+    }
+  }
+  acquire() {
+    if (this.count > 0) {
+      this.count--;
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+  release() {
+    const next = this.queue.shift();
+    if (next) {
+      next();
+    } else {
+      this.count++;
+    }
+  }
+};
+
 // src/llm/llm.service.ts
 var ENTITY_EXTRACTOR_TOOL = {
   type: "function",
@@ -1634,42 +1883,6 @@ ${context}`, false);
 
 // src/manager/compress.manager.ts
 import { v4 as uuidv4 } from "uuid";
-
-// src/manager/semaphore.ts
-var Semaphore = class {
-  count;
-  queue = [];
-  constructor(max) {
-    this.count = max;
-  }
-  async run(fn) {
-    await this.acquire();
-    try {
-      return await fn();
-    } finally {
-      this.release();
-    }
-  }
-  acquire() {
-    if (this.count > 0) {
-      this.count--;
-      return Promise.resolve();
-    }
-    return new Promise((resolve) => {
-      this.queue.push(resolve);
-    });
-  }
-  release() {
-    const next = this.queue.shift();
-    if (next) {
-      next();
-    } else {
-      this.count++;
-    }
-  }
-};
-
-// src/manager/compress.manager.ts
 var CompressManager = class {
   config;
   lance;
@@ -1698,7 +1911,7 @@ var CompressManager = class {
     return next;
   }
   async doCompress(sessionId, force, waitGraph) {
-    const messages = this.sessionCache.getSessionMessages(sessionId);
+    const messages = this.sessionCache.getSessionMessages(sessionId).slice();
     if (messages.length === 0) return;
     const entry = this.sessionCache.getEntry(sessionId);
     if (!entry) return;
@@ -1710,7 +1923,7 @@ var CompressManager = class {
     try {
       summary = await this.llm.summarizeMessages(messages);
     } catch (err) {
-      console.error(`[CompressManager] LLM compress failed for session ${sessionId}:`, err);
+      console.error(`[CompressManager] LLM compress failed for session ${sessionId}: ${formatError(err)}`);
       return;
     }
     const { title, detail, summary: summaryText, concise } = summary;
@@ -1805,6 +2018,9 @@ var CompressManager = class {
     }
   }
 };
+function formatError(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 function withTimeout(promise, timeoutMs, label) {
   let timer;
   const timeout = new Promise((_, reject) => {
@@ -2293,12 +2509,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");
@@ -2476,27 +2692,62 @@ var MemoryManager = class {
       this.sessionMap.set(s.sessionId, this.deserializeSession(s));
     }
     await this.restoreFromStorage();
+    if (this.config.autoOptimizeOnInit) {
+      void this.optimizeStorage().then((results) => {
+        const versions = results.reduce((s, r) => s + r.oldVersionsRemoved, 0);
+        const fragments = results.reduce((s, r) => s + r.fragmentsRemoved, 0);
+        if (versions > 0 || fragments > 0) {
+          console.info(
+            `[MemoryManager] \u540E\u53F0\u5B58\u50A8\u538B\u5B9E\u5B8C\u6210\uFF1A\u6E05\u7406\u5386\u53F2\u7248\u672C ${versions} \u4E2A\uFF0C\u5408\u5E76\u788E\u7247 ${fragments} \u4E2A`
+          );
+        }
+      }).catch((err) => {
+        console.warn("[MemoryManager] \u540E\u53F0\u5B58\u50A8\u538B\u5B9E\u5931\u8D25\uFF08\u4E0D\u5F71\u54CD\u670D\u52A1\uFF09:", err);
+      });
+    }
+  }
+  /**
+   * 手动触发存储压实与历史版本清理（init 后台会自动执行一次；上层维护任务也可调用）。
+   * @param retentionMs 保留多久内的历史版本，默认取配置 optimizeVersionRetentionMs
+   */
+  async optimizeStorage(retentionMs) {
+    return this.lance.optimizeStorage(retentionMs ?? this.config.optimizeVersionRetentionMs);
   }
   async restoreFromStorage() {
     const [n1, n2, n3] = this.config.topicRatio;
     const sessionIds = await this.lance.getAllSessionIds();
     if (sessionIds.length === 0) return;
-    for (const sessionId of sessionIds) {
-      const recentMessages = await this.lance.getLatestMessages(sessionId, 1);
-      if (recentMessages.length === 0) continue;
-      const { chatId, userId } = recentMessages[0];
-      const topicGroups = await this.lance.getRecentTopics(chatId, userId, n1, n2, n3);
-      const n1EndTime = topicGroups.detail.length > 0 ? topicGroups.detail[topicGroups.detail.length - 1].endTime : 0;
-      const rawMessages = n1EndTime > 0 ? await this.lance.getMessagesSince(sessionId, n1EndTime) : await this.lance.getLatestMessages(sessionId, 100);
-      if (rawMessages.length > 0) {
-        this.sessionCache.addMessages(sessionId, rawMessages, chatId, userId);
-      }
-      if (topicGroups.detail.length + topicGroups.summary.length + topicGroups.concise.length > 0) {
-        this.sessionCache.buildHistoryWindow(sessionId, topicGroups);
-      } else {
-        this.sessionCache.setHistoryWindow(sessionId, "");
+    const topicsCache = /* @__PURE__ */ new Map();
+    const getTopics = (chatId, userId) => {
+      const key = `${chatId}\0${userId}`;
+      let cached = topicsCache.get(key);
+      if (!cached) {
+        cached = this.lance.getRecentTopics(chatId, userId, n1, n2, n3);
+        topicsCache.set(key, cached);
       }
-    }
+      return cached;
+    };
+    const sem = new Semaphore(this.config.restoreConcurrency);
+    await Promise.all(
+      sessionIds.map(
+        (sessionId) => sem.run(async () => {
+          const recentMessages = await this.lance.getLatestMessages(sessionId, 1);
+          if (recentMessages.length === 0) return;
+          const { chatId, userId } = recentMessages[0];
+          const topicGroups = await getTopics(chatId, userId);
+          const n1EndTime = topicGroups.detail.length > 0 ? topicGroups.detail[topicGroups.detail.length - 1].endTime : 0;
+          const rawMessages = n1EndTime > 0 ? await this.lance.getMessagesSince(sessionId, n1EndTime) : await this.lance.getLatestMessages(sessionId, 100);
+          if (rawMessages.length > 0) {
+            this.sessionCache.addMessages(sessionId, rawMessages, chatId, userId);
+          }
+          if (topicGroups.detail.length + topicGroups.summary.length + topicGroups.concise.length > 0) {
+            this.sessionCache.buildHistoryWindow(sessionId, topicGroups);
+          } else {
+            this.sessionCache.setHistoryWindow(sessionId, "");
+          }
+        })
+      )
+    );
   }
   async updateChat(messages, opts) {
     if (messages.length === 0) return;
@@ -2778,33 +3029,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 +3062,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 +3080,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 +3109,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();