@ppagent/memory 0.1.1 → 0.1.4

package/dist/index.js

@@ -25,9 +25,10 @@ function resolveConfig(config) {
     detailMaxTokens: config.detailMaxTokens ?? 2048,
     summaryMaxTokens: config.summaryMaxTokens ?? 512,
     conciseMaxTokens: config.conciseMaxTokens ?? 128,
-    httpTimeoutMs: config.httpTimeoutMs ?? 3e4,
+    httpTimeoutMs: config.httpTimeoutMs ?? 6e4,
     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,
@@ -42,7 +43,13 @@ function resolveConfig(config) {
     knowledgeGraphTriggerScore: config.knowledgeGraphTriggerScore ?? 0.78,
     knowledgeGraphEntityTopK: config.knowledgeGraphEntityTopK ?? 10,
     knowledgeGraphAnchorTopK: config.knowledgeGraphAnchorTopK ?? 3,
-    knowledgeGraphHopLimit: config.knowledgeGraphHopLimit ?? 10
+    knowledgeGraphHopLimit: config.knowledgeGraphHopLimit ?? 10,
+    graphExtractConcurrency: config.graphExtractConcurrency ?? 2,
+    graphBuildTimeoutMs: config.graphBuildTimeoutMs ?? 12e4,
+    autoOptimizeOnInit: config.autoOptimizeOnInit ?? true,
+    autoOptimizeIntervalMs: config.autoOptimizeIntervalMs ?? 6 * 36e5,
+    optimizeVersionRetentionMs: config.optimizeVersionRetentionMs ?? 0,
+    restoreConcurrency: config.restoreConcurrency ?? 8
   };
 }
 
@@ -162,6 +169,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);
 }
@@ -170,7 +187,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, {
@@ -181,12 +200,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) {
@@ -226,27 +245,45 @@ 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 out = [];
+    const batches = [];
     for (let i = 0; i < inputs.length; i += batchSize) {
-      const batch = inputs.slice(i, i + batchSize);
+      batches.push({ index: batches.length, texts: inputs.slice(i, i + batchSize) });
+    }
+    const batchResults = await mapLimit(batches, concurrency, async (batch) => {
       const data = await postJsonWithRetry(
         url,
         { Authorization: `Bearer ${this.config.embeddingApiKey}` },
-        { model: this.config.embeddingModel, input: batch },
+        { model: this.config.embeddingModel, input: batch.texts },
         retryOpts,
         "Embedding API"
       );
-      const sorted = data.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
-      out.push(...sorted);
-    }
-    return out;
+      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);
   }
   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;
@@ -979,6 +1016,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;
@@ -991,6 +1046,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;
@@ -1004,7 +1060,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,
@@ -1020,6 +1075,7 @@ var LanceService = class {
         TOPICS_TABLE,
         topicsSchema(dim)
       );
+      this.isNewTopicsTable = true;
     }
     if (existingTables.includes(FACTS_TABLE)) {
       this.factsTable = await this.conn.openTable(FACTS_TABLE);
@@ -1028,43 +1084,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 的 ?? "[]" 兜底。
@@ -1101,24 +1197,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({
@@ -1160,9 +1252,13 @@ var LanceService = class {
     }
   }
   async getLatestMessages(sessionId, limit) {
+    if (limit <= 0) return [];
     try {
-      const rows = await this.messagesTable.query().where(eqFilter("session_id", sessionId)).limit(limit * 3).toArray();
-      return rows.sort((a, b) => Number(b.created_at) - Number(a.created_at)).slice(0, limit).reverse().map(rowToMessage);
+      const rows = await this.messagesTable.query().where(eqFilter("session_id", sessionId)).orderBy([
+        { columnName: "created_at", ascending: false },
+        { columnName: "message_id", ascending: false }
+      ]).limit(limit).toArray();
+      return rows.reverse().map(rowToMessage);
     } catch {
       return [];
     }
@@ -1251,7 +1347,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;
     }
   }
@@ -1357,7 +1453,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;
     }
   }
@@ -1365,7 +1461,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;
     }
   }
@@ -1488,6 +1584,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",
@@ -1602,7 +1732,7 @@ var LlmService = class {
     return data.choices[0].message;
   }
   // ── 第一步：生成三级摘要（JSON 输出）──────────────────────────────────────────
-  async getSummary(messages) {
+  async summarizeMessages(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
@@ -1624,7 +1754,7 @@ ${formatted}`);
     return { title: parsed.title ?? "", detail: parsed.detail, summary: parsed.summary, concise: parsed.concise };
   }
   // ── 第二步：通过工具调用提取实体和关系 ──────────────────────────────────────
-  async extractEntitiesWithTool(messages) {
+  async extractEntitiesFromMessages(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
@@ -1652,15 +1782,15 @@ ${formatted}`
         }
       }
     } catch (err) {
-      console.error("[LlmService] extractEntitiesWithTool failed:", err);
+      console.error("[LlmService] extractEntitiesFromMessages failed:", err);
     }
     return { entities: [], relations: [] };
   }
   // ── 对外主接口：压缩 + 实体抽取（并发执行两步）────────────────────────────────
   async compress(messages) {
     const [summary, extraction] = await Promise.all([
-      this.getSummary(messages),
-      this.extractEntitiesWithTool(messages)
+      this.summarizeMessages(messages),
+      this.extractEntitiesFromMessages(messages)
     ]);
     return {
       title: summary.title,
@@ -1758,42 +1888,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;
@@ -1812,17 +1906,17 @@ var CompressManager = class {
     this.sessionCache = sessionCache;
     this.semaphore = new Semaphore(config.maxConcurrentCompressions);
   }
-  triggerCompress(sessionId, force = false) {
+  triggerCompress(sessionId, force = false, waitGraph = false) {
     const chain = this.sessionChain.get(sessionId) ?? Promise.resolve();
     const next = chain.then(
-      () => this.semaphore.run(() => this.doCompress(sessionId, force))
+      () => this.semaphore.run(() => this.doCompress(sessionId, force, waitGraph))
     );
     this.sessionChain.set(sessionId, next.catch(() => {
     }));
     return next;
   }
-  async doCompress(sessionId, force) {
-    const messages = this.sessionCache.getSessionMessages(sessionId);
+  async doCompress(sessionId, force, waitGraph) {
+    const messages = this.sessionCache.getSessionMessages(sessionId).slice();
     if (messages.length === 0) return;
     const entry = this.sessionCache.getEntry(sessionId);
     if (!entry) return;
@@ -1830,15 +1924,15 @@ var CompressManager = class {
     const { chatId, userId } = entry.ids;
     const startTime = messages[0].createdAt;
     const endTime = messages[messages.length - 1].createdAt;
-    let compressOutput;
+    let summary;
     try {
-      compressOutput = await this.llm.compress(messages);
+      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, concise, entities, relations } = compressOutput;
-    const topicTextForEmbed = [detail, summary, concise].find((t) => t.length > 0) ?? "";
+    const { title, detail, summary: summaryText, concise } = summary;
+    const topicTextForEmbed = [detail, summaryText, concise].find((t) => t.length > 0) ?? "";
     let topicVector = [];
     try {
       topicVector = await this.embed.embedOne(topicTextForEmbed);
@@ -1852,7 +1946,7 @@ var CompressManager = class {
       chatId,
       title,
       detail,
-      summary,
+      summary: summaryText,
       concise,
       startTime,
       endTime,
@@ -1866,9 +1960,6 @@ 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 {
@@ -1877,6 +1968,19 @@ 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) => ({
@@ -1919,6 +2023,16 @@ 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) => {
+    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";
@@ -2178,20 +2292,29 @@ var KnowledgeManager = class {
       updatedAt: now
     };
     await this.lance.addDocument(doc);
-    const background = this.semaphore.run(
-      () => this.ingestChunksAndGraph(doc, pieces, shouldBuildGraph)
-    );
-    if (opts.wait) {
-      await background;
+    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 {
-      background.catch((err) => {
-        console.error("[KnowledgeManager] background ingest failed:", err);
+      chunkIngest.catch((err) => {
+        console.error("[KnowledgeManager] background chunk ingest failed:", err);
+      });
+    }
+    if (opts.waitGraph) {
+      await withTimeout2(graphBuild, this.config.graphBuildTimeoutMs, "document graph build");
+    } else {
+      graphBuild.catch((err) => {
+        console.error("[KnowledgeManager] background graph build failed:", err);
       });
     }
     return { docId };
   }
-  async ingestChunksAndGraph(doc, pieces, buildGraph) {
-    if (pieces.length === 0) return;
+  async ingestChunks(doc, pieces) {
+    if (pieces.length === 0) return [];
     const redundant = this.config.chunkRedundantIds;
     const embedInputs = pieces.map(
       (p) => p.headingPath ? `${p.headingPath}
@@ -2202,7 +2325,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(),
@@ -2219,17 +2342,12 @@ ${p.content}` : p.content
       createdAt: doc.createdAt
     }));
     await this.lance.addChunks(chunks);
-    if (buildGraph) {
-      await this.buildDocumentGraph(doc, chunks).catch((err) => {
-        console.error("[KnowledgeManager] build graph failed:", err);
-      });
-    }
+    return chunks;
   }
   async buildDocumentGraph(doc, chunks) {
-    let extractedAny = false;
-    for (const chunk of chunks) {
+    const extracted = await mapLimit2(chunks, this.config.graphExtractConcurrency, async (chunk) => {
       const { entities: rawEntities, relations: rawRelations } = await this.llm.extractEntitiesFromText(chunk.content);
-      if (rawEntities.length === 0 && rawRelations.length === 0) continue;
+      if (rawEntities.length === 0 && rawRelations.length === 0) return null;
       const meta = {
         userId: doc.userId,
         chatId: doc.chatId,
@@ -2238,46 +2356,47 @@ ${p.content}` : p.content
         chunkId: chunk.chunkId,
         messageTime: doc.createdAt
       };
-      const entities = rawEntities.map((e) => ({
+      const entities2 = rawEntities.map((e) => ({
         name: e.name,
         type: e.type,
         meta: { ...meta, ...e.meta }
       }));
-      const relations = rawRelations.map((r) => ({
+      const relations2 = rawRelations.map((r) => ({
         from: r.from,
         to: r.to,
         type: r.type,
         happenedAt: r.happenedAt ?? void 0,
         meta: { ...meta, ...r.meta }
       }));
-      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);
-      });
+      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;
     }
+    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) {
@@ -2439,6 +2558,26 @@ 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 {
@@ -2524,6 +2663,8 @@ var MemoryManager = class {
   compressManager;
   knowledgeManager;
   sessionMap = /* @__PURE__ */ new Map();
+  optimizeTimer;
+  optimizeRunning = false;
   constructor(config) {
     this.config = resolveConfig(config);
     this.lance = new LanceService(this.config);
@@ -2558,27 +2699,78 @@ var MemoryManager = class {
       this.sessionMap.set(s.sessionId, this.deserializeSession(s));
     }
     await this.restoreFromStorage();
+    if (this.config.autoOptimizeOnInit) {
+      void this.runBackgroundOptimize(this.config.optimizeVersionRetentionMs);
+    }
+    if (this.config.autoOptimizeIntervalMs > 0) {
+      const retention = Math.max(this.config.optimizeVersionRetentionMs, 6e4);
+      this.optimizeTimer = setInterval(() => {
+        void this.runBackgroundOptimize(retention);
+      }, this.config.autoOptimizeIntervalMs);
+      this.optimizeTimer.unref?.();
+    }
+  }
+  /** 后台压实的统一入口：防重入（上一轮未结束则跳过），失败仅告警不影响服务。*/
+  async runBackgroundOptimize(retentionMs) {
+    if (this.optimizeRunning) return;
+    this.optimizeRunning = true;
+    try {
+      const results = await this.optimizeStorage(retentionMs);
+      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);
+    } finally {
+      this.optimizeRunning = false;
+    }
+  }
+  /**
+   * 手动触发存储压实与历史版本清理（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;
@@ -2653,7 +2845,7 @@ var MemoryManager = class {
   }
   async flushChat(sessionId, opts) {
     const sid = sessionId ?? DEFAULT_SESSION_ID;
-    const promise = this.compressManager.triggerCompress(sid, true);
+    const promise = this.compressManager.triggerCompress(sid, true, opts?.waitGraph === true);
     if (opts?.wait) await promise;
   }
   async updateFacts(content, level, userId, chatId, sessionId) {
@@ -2944,6 +3136,10 @@ var MemoryManager = class {
     return page ? this.knowledgeManager.listDocuments(filter, page) : this.knowledgeManager.listDocuments(filter);
   }
   destroy() {
+    if (this.optimizeTimer) {
+      clearInterval(this.optimizeTimer);
+      this.optimizeTimer = void 0;
+    }
     this.grafeo.close();
   }
 };