@ppagent/memory 0.3.1 → 0.4.1

package/dist/index.js

@@ -16,6 +16,15 @@ function resolveConfig(config) {
     console.warn("[MemoryConfig] embeddingApiKey \u672A\u914D\u7F6E\uFF0C\u81EA\u52A8\u56DE\u9000\u4F7F\u7528 llmApiKey\u3002");
     embeddingApiKey = config.llmApiKey;
   }
+  const compressedContextTokenLimit = positiveInt(
+    config.compressedContextTokenLimit ?? config.historyWindowTokenLimit ?? 16 * 1024,
+    "compressedContextTokenLimit"
+  );
+  if (compressedContextTokenLimit > 32 * 1024) {
+    console.warn(
+      `[MemoryConfig] compressedContextTokenLimit=${compressedContextTokenLimit} \u8D85\u8FC7 32K\uFF0C\u4F1A\u5360\u7528\u8F83\u591A\u6A21\u578B\u4E0A\u4E0B\u6587\u5E76\u589E\u52A0\u5E38\u9A7B\u5185\u5B58\u3002`
+    );
+  }
   return {
     ...config,
     embeddingBaseUrl,
@@ -23,11 +32,38 @@ function resolveConfig(config) {
     provider: config.provider ?? "auto",
     sqlitePath: config.sqlitePath ?? path.join(path.dirname(config.lancedbPath), "memory.sqlite3"),
     sessionTokenLimit: config.sessionTokenLimit ?? 16386,
-    historyWindowTokenLimit: config.historyWindowTokenLimit ?? 10240,
+    historyWindowTokenLimit: config.historyWindowTokenLimit ?? compressedContextTokenLimit,
     topicRatio: config.topicRatio ?? [1, 5, 20],
     detailMaxTokens: config.detailMaxTokens ?? 2048,
     summaryMaxTokens: config.summaryMaxTokens ?? 512,
     conciseMaxTokens: config.conciseMaxTokens ?? 128,
+    compressedContextTokenLimit,
+    compressedContextRatio: ratio(
+      config.compressedContextRatio ?? 0.1,
+      "compressedContextRatio"
+    ),
+    topicCompactionSyncRatio: atLeastOne(
+      config.topicCompactionSyncRatio ?? 1.25,
+      "topicCompactionSyncRatio"
+    ),
+    contextUsageRatio: ratio(config.contextUsageRatio ?? 0.75, "contextUsageRatio"),
+    precompressionRatio: ratio(config.precompressionRatio ?? 0.75, "precompressionRatio"),
+    compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.5, "compressionBatchRatio"),
+    compressionBatchTokenLimit: Math.max(0, Math.floor(config.compressionBatchTokenLimit ?? 0)),
+    topicSummaryMaxTokens: positiveInt(
+      config.topicSummaryMaxTokens ?? config.detailMaxTokens ?? 2048,
+      "topicSummaryMaxTokens"
+    ),
+    defaultModelContextTokens: positiveInt(
+      config.defaultModelContextTokens ?? 256 * 1024,
+      "defaultModelContextTokens"
+    ),
+    maxHistoryAgeMs: Math.max(0, Math.floor(config.maxHistoryAgeMs ?? 0)),
+    sessionIdleTtlMs: Math.floor(config.sessionIdleTtlMs ?? 30 * 6e4),
+    sessionSweepIntervalMs: positiveInt(
+      config.sessionSweepIntervalMs ?? 6e4,
+      "sessionSweepIntervalMs"
+    ),
     httpTimeoutMs: config.httpTimeoutMs ?? 6e4,
     httpMaxRetries: config.httpMaxRetries ?? 2,
     embeddingBatchSize: config.embeddingBatchSize ?? 20,
@@ -55,6 +91,53 @@ function resolveConfig(config) {
     restoreConcurrency: config.restoreConcurrency ?? 8
   };
 }
+function ratio(value, name) {
+  if (!Number.isFinite(value) || value <= 0 || value > 1) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u5728 (0, 1] \u8303\u56F4\u5185`);
+  }
+  return value;
+}
+function positiveInt(value, name) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u6B63\u6570`);
+  }
+  return Math.floor(value);
+}
+function atLeastOne(value, name) {
+  if (!Number.isFinite(value) || value < 1) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u5927\u4E8E\u7B49\u4E8E 1 \u7684\u6709\u9650\u6570`);
+  }
+  return value;
+}
+
+// src/context-budget.ts
+function calculateContextBudget(config, modelContextTokens) {
+  if (!Number.isFinite(modelContextTokens) || modelContextTokens <= 0) {
+    throw new Error("modelContextTokens \u5FC5\u987B\u662F\u6B63\u6570");
+  }
+  const normalizedModelTokens = Math.floor(modelContextTokens);
+  const usableContextTokens = Math.floor(normalizedModelTokens * config.contextUsageRatio);
+  if (usableContextTokens < 2) {
+    throw new Error(
+      `modelContextTokens=${normalizedModelTokens} \u5728 contextUsageRatio=${config.contextUsageRatio} \u4E0B\u4E0D\u8DB3\u4EE5\u540C\u65F6\u4FDD\u7559 Topic \u4E0E\u539F\u59CB\u6D88\u606F\u9884\u7B97`
+    );
+  }
+  const ratioLimit = Math.max(
+    1,
+    Math.floor(usableContextTokens * config.compressedContextRatio)
+  );
+  const compressedTokenLimit = Math.min(
+    config.compressedContextTokenLimit,
+    ratioLimit,
+    usableContextTokens - 1
+  );
+  return {
+    modelContextTokens: normalizedModelTokens,
+    usableContextTokens,
+    compressedTokenLimit,
+    rawTokenLimit: usableContextTokens - compressedTokenLimit
+  };
+}
 
 // src/constants.ts
 var DEFAULT_NODE_TYPES = [
@@ -743,6 +826,7 @@ function tableDefs(dim) {
         { name: "content", type: "text" },
         { name: "parts", type: "text", nullable: true },
         // 兼容存量数据
+        { name: "payload", type: "text", nullable: true },
         { name: "vector", type: "vector" },
         { name: "usage", type: "int" },
         { name: "metadata", type: "text" },
@@ -765,9 +849,12 @@ function tableDefs(dim) {
         { name: "chat_id", type: "text" },
         { name: "title", type: "text", nullable: true },
         // 兼容存量数据
-        { name: "detail", type: "text" },
+        { name: "detail", type: "text", nullable: true },
         { name: "summary", type: "text" },
-        { name: "concise", type: "text" },
+        { name: "concise", type: "text", nullable: true },
+        { name: "tokens", type: "int", nullable: true },
+        { name: "start_message_id", type: "text", nullable: true },
+        { name: "end_message_id", type: "text", nullable: true },
         { name: "vector", type: "vector" },
         { name: "start_time", type: "long" },
         { name: "end_time", type: "long" },
@@ -777,7 +864,7 @@ function tableDefs(dim) {
       ],
       indexes: [
         { column: "chat_id", kind: "scalar" },
-        { column: "detail", kind: "fts" }
+        { column: "summary", kind: "fts" }
       ]
     },
     {
@@ -788,8 +875,10 @@ function tableDefs(dim) {
         { name: "chat_id", type: "text" },
         { name: "session_id", type: "text" },
         { name: "user_id", type: "text" },
+        { name: "fact_key", type: "text", nullable: true },
         { name: "content", type: "text" },
-        { name: "created_at", type: "long" }
+        { name: "created_at", type: "long" },
+        { name: "updated_at", type: "long", nullable: true }
       ],
       indexes: []
     },
@@ -868,6 +957,7 @@ function messageToRow(m) {
     type: m.type,
     content: m.content,
     parts: m.parts ?? "[]",
+    payload: m.payload ?? null,
     vector: m.vector,
     usage: m.usage,
     metadata: m.metadata,
@@ -885,8 +975,9 @@ function rowToMessage(r) {
     content: r.content,
     parts: r.parts ?? "[]",
     // 旧数据无此列时安全降级
+    payload: r.payload ?? void 0,
     vector: toVector(r.vector),
-    usage: Number(r.usage),
+    usage: positiveNumber(r.usage),
     metadata: r.metadata,
     createdAt: Number(r.created_at)
   };
@@ -898,9 +989,13 @@ function topicToRow(t) {
     user_id: t.userId,
     chat_id: t.chatId,
     title: t.title ?? "",
-    detail: t.detail,
+    // 旧库的 detail/concise 可能仍是 NOT NULL；兼容写入但业务只读取 summary。
+    detail: t.detail ?? t.summary,
     summary: t.summary,
-    concise: t.concise,
+    concise: t.concise ?? t.summary,
+    tokens: t.tokens,
+    start_message_id: t.startMessageId ?? null,
+    end_message_id: t.endMessageId ?? null,
     vector: t.vector,
     start_time: t.startTime,
     end_time: t.endTime,
@@ -916,9 +1011,12 @@ function rowToTopic(r) {
     userId: r.user_id,
     chatId: r.chat_id,
     title: r.title ?? "",
-    detail: r.detail,
-    summary: r.summary,
-    concise: r.concise,
+    summary: r.summary || r.detail || r.concise || "",
+    tokens: positiveNumber(r.tokens),
+    startMessageId: r.start_message_id ?? void 0,
+    endMessageId: r.end_message_id ?? void 0,
+    detail: r.detail ?? void 0,
+    concise: r.concise ?? void 0,
     vector: toVector(r.vector),
     startTime: Number(r.start_time),
     endTime: Number(r.end_time),
@@ -934,8 +1032,10 @@ function factToRow(f) {
     chat_id: f.chatId,
     session_id: f.sessionId,
     user_id: f.userId,
+    fact_key: f.key ?? null,
     content: f.content,
-    created_at: f.createdAt
+    created_at: f.createdAt,
+    updated_at: f.updatedAt ?? f.createdAt
   };
 }
 function rowToFact(r) {
@@ -945,8 +1045,10 @@ function rowToFact(r) {
     chatId: r.chat_id,
     sessionId: r.session_id,
     userId: r.user_id,
+    key: r.fact_key ?? void 0,
     content: r.content,
-    createdAt: Number(r.created_at)
+    createdAt: Number(r.created_at),
+    updatedAt: Number(r.updated_at ?? r.created_at)
   };
 }
 function sessionToRow(s) {
@@ -1048,6 +1150,15 @@ function safeParseObject(s) {
     return {};
   }
 }
+function positiveNumber(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+}
+function migrationValueEquals(current, next) {
+  if (current == null && next == null) return true;
+  if (typeof next === "number") return Number(current) === next;
+  return String(current) === String(next);
+}
 function rrfFuse(lists, keyOf) {
   const acc = /* @__PURE__ */ new Map();
   for (const list of lists) {
@@ -1078,7 +1189,7 @@ var MemoryStore = class {
     if (this.providerOverride) {
       this.provider = this.providerOverride;
     } else {
-      const { createProvider } = await import("./provider.resolver-ZLQ766IO.js");
+      const { createProvider } = await import("./provider.resolver-2KS2YYNV.js");
       this.provider = await createProvider(this.config);
       console.info(`[memory] \u5411\u91CF\u5B58\u50A8\u540E\u7AEF\uFF1A${this.provider.kind}`);
     }
@@ -1099,6 +1210,98 @@ var MemoryStore = class {
     if (messages.length === 0) return;
     await this.provider.add(MESSAGES_TABLE, messages.map(messageToRow));
   }
+  /** 0.3.x → 0.4.x 数据回填；幂等，不调用 LLM、不删除原始消息。 */
+  async migrateLegacyData() {
+    const report = {
+      provider: this.providerKind,
+      topicsScanned: 0,
+      topicsUpdated: 0,
+      messagesScanned: 0,
+      messagesUpdated: 0,
+      factsScanned: 0,
+      factsUpdated: 0
+    };
+    const topicRows = await this.provider.query(TOPICS_TABLE);
+    report.topicsScanned = topicRows.length;
+    const messagesBySession = /* @__PURE__ */ new Map();
+    for (const row of topicRows) {
+      const sessionId = String(row.session_id);
+      let messages = messagesBySession.get(sessionId);
+      if (!messages) {
+        messages = await this.provider.query(MESSAGES_TABLE, {
+          filter: [eq("session_id", sessionId)],
+          orderBy: [
+            { column: "created_at", ascending: true },
+            { column: "message_id", ascending: true }
+          ]
+        });
+        messagesBySession.set(sessionId, messages);
+      }
+      const summary = String(row.summary || row.detail || row.concise || "");
+      const startTime = Number(row.start_time);
+      const endTime = Number(row.end_time);
+      const covered = messages.filter(
+        (message) => Number(message.created_at) >= startTime && Number(message.created_at) <= endTime
+      );
+      const values = {
+        summary,
+        tokens: positiveNumber(row.tokens) || Math.max(1, countTokens(summary)),
+        start_message_id: row.start_message_id ?? covered.at(0)?.message_id ?? null,
+        end_message_id: row.end_message_id ?? covered.at(-1)?.message_id ?? null,
+        updated_at: Number(row.updated_at || Date.now())
+      };
+      const changed = Object.entries(values).some(
+        ([key, value]) => !migrationValueEquals(row[key], value)
+      );
+      if (changed) {
+        await this.provider.update(TOPICS_TABLE, values, [eq("summary_id", String(row.summary_id))]);
+        report.topicsUpdated++;
+      }
+    }
+    const messageRows = await this.provider.query(MESSAGES_TABLE);
+    report.messagesScanned = messageRows.length;
+    for (const row of messageRows) {
+      const usage = countTokens(
+        [row.content, row.parts ?? "[]", row.metadata ?? "{}", row.payload ?? ""].map(String).join("\n")
+      );
+      if (Number(row.usage) === usage) continue;
+      await this.provider.update(MESSAGES_TABLE, { usage }, [
+        eq("message_id", String(row.message_id))
+      ]);
+      report.messagesUpdated++;
+    }
+    const factRows = await this.provider.query(FACTS_TABLE);
+    report.factsScanned = factRows.length;
+    for (const row of factRows) {
+      const updatedAt = Number(row.updated_at || row.created_at);
+      if (Number(row.updated_at) === updatedAt) continue;
+      await this.provider.update(FACTS_TABLE, { updated_at: updatedAt }, [
+        eq("fact_id", String(row.fact_id))
+      ]);
+      report.factsUpdated++;
+    }
+    return report;
+  }
+  /** message_id 稳定时更新原行，否则新增；用于流式 assistant 消息最终态覆盖。 */
+  async upsertMessages(messages) {
+    if (messages.length === 0) return;
+    const ids = messages.map((message) => message.messageId);
+    const existing = await this.provider.query(MESSAGES_TABLE, {
+      filter: [{ op: "in", field: "message_id", values: ids }],
+      select: ["message_id"]
+    });
+    const existingIds = new Set(existing.map((row) => String(row.message_id)));
+    await Promise.all(
+      messages.filter((message) => existingIds.has(message.messageId)).map(
+        (message) => this.provider.update(
+          MESSAGES_TABLE,
+          messageToRow(message),
+          [eq("message_id", message.messageId)]
+        )
+      )
+    );
+    await this.addMessages(messages.filter((message) => !existingIds.has(message.messageId)));
+  }
   async getMessagesSince(sessionId, since, limit) {
     try {
       const rows = await this.provider.query(MESSAGES_TABLE, {
@@ -1110,6 +1313,12 @@ var MemoryStore = class {
       return [];
     }
   }
+  async getMessagesAfterBoundary(sessionId, endTime, endMessageId) {
+    const messages = await this.getAllMessagesBySession(sessionId);
+    return messages.filter(
+      (message) => message.createdAt > endTime || message.createdAt === endTime && endMessageId != null && message.messageId.localeCompare(endMessageId) > 0
+    );
+  }
   async getLatestMessages(sessionId, limit) {
     if (limit <= 0) return [];
     try {
@@ -1157,7 +1366,7 @@ var MemoryStore = class {
   }
   async hybridSearchTopics(query, vector, filter, limit = 10) {
     try {
-      const fused = (await this.hybridSearch(TOPICS_TABLE, ["detail"], query, vector, filter, limit)).slice(0, limit);
+      const fused = (await this.hybridSearch(TOPICS_TABLE, ["summary"], query, vector, filter, limit)).slice(0, limit);
       if (fused.length > 0) {
         const total = fused.length;
         return fused.map((r, idx) => ({
@@ -1165,25 +1374,10 @@ var MemoryStore = class {
           score: total - idx + Math.log1p(Number(r.recall_count))
         })).sort((a, b) => b.score - a.score).map((x) => rowToTopic(x.row));
       }
+      return [];
     } catch {
+      return [];
     }
-    const msgs = await this.hybridSearchMessages(query, vector, filter, limit);
-    return msgs.map((r) => ({
-      summaryId: r.messageId,
-      sessionId: r.sessionId,
-      userId: r.userId,
-      chatId: r.chatId,
-      title: "",
-      detail: r.content,
-      summary: r.content,
-      concise: r.content,
-      startTime: r.createdAt,
-      endTime: r.createdAt,
-      createdAt: r.createdAt,
-      updatedAt: r.createdAt,
-      recallCount: 0,
-      vector: r.vector
-    }));
   }
   /**
    * 通用混合检索：FTS（BM25）与向量两路各取 limit*HYBRID_OVERFETCH 候选，RRF 融合。
@@ -1221,6 +1415,13 @@ var MemoryStore = class {
   async addTopic(topic) {
     await this.provider.add(TOPICS_TABLE, [topicToRow(topic)]);
   }
+  async updateTopic(topic) {
+    await this.provider.update(
+      TOPICS_TABLE,
+      topicToRow(topic),
+      [eq("summary_id", topic.summaryId)]
+    );
+  }
   async updateTopicRecallCount(summaryId, count) {
     await this.provider.update(
       TOPICS_TABLE,
@@ -1228,6 +1429,23 @@ var MemoryStore = class {
       [eq("summary_id", summaryId)]
     );
   }
+  async incrementTopicRecallCounts(topics) {
+    await Promise.all(
+      topics.map((topic) => this.updateTopicRecallCount(topic.summaryId, topic.recallCount + 1))
+    );
+  }
+  async getTopicsBySession(sessionId, since = 0) {
+    try {
+      const filter = [eq("session_id", sessionId)];
+      if (since > 0) filter.push({ op: "gte", field: "end_time", value: since });
+      const rows = await this.provider.query(TOPICS_TABLE, { filter });
+      return rows.sort(
+        (a, b) => Number(a.end_time) - Number(b.end_time) || cmpStr(a.summary_id, b.summary_id)
+      ).map(rowToTopic);
+    } catch {
+      return [];
+    }
+  }
   async getRecentTopics(chatId, userId, n1, n2, n3) {
     const filter = [eq("chat_id", chatId), eq("user_id", userId)];
     const recallBoostMs = this.config.recallBoostMs;
@@ -1268,10 +1486,19 @@ var MemoryStore = class {
   async deleteTopicsBySession(sessionId) {
     await this.provider.deleteWhere(TOPICS_TABLE, [eq("session_id", sessionId)]);
   }
+  async deleteTopicsByIds(summaryIds) {
+    if (summaryIds.length === 0) return;
+    await this.provider.deleteWhere(TOPICS_TABLE, [
+      { op: "in", field: "summary_id", values: summaryIds }
+    ]);
+  }
   // ── facts ──────────────────────────────────────────────────────────────────
   async saveFact(fact) {
     await this.provider.add(FACTS_TABLE, [factToRow(fact)]);
   }
+  async updateFact(fact) {
+    await this.provider.update(FACTS_TABLE, factToRow(fact), [eq("fact_id", fact.factId)]);
+  }
   async getAllFacts() {
     try {
       const rows = await this.provider.query(FACTS_TABLE);
@@ -1511,40 +1738,6 @@ var MemoryStore = 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",
@@ -1617,7 +1810,10 @@ var LlmService = class {
    *   仅在提示词明确要求 JSON 时启用；返回自然语言的调用（如 summarizeSearchResults）
    *   必须传 false，否则部分端点会因 "messages 未含 json 字样" 而 400。
    */
-  async chatCompletion(systemPrompt, userPrompt, jsonMode = true) {
+  async chatCompletion(systemPrompt, userPrompt, jsonMode = true, maxTokens) {
+    return (await this.chatCompletionWithUsage(systemPrompt, userPrompt, jsonMode, maxTokens)).content;
+  }
+  async chatCompletionWithUsage(systemPrompt, userPrompt, jsonMode = true, maxTokens) {
     const url = `${this.config.llmBaseUrl.replace(/\/$/, "")}/chat/completions`;
     const body = {
       model: this.config.llmModel,
@@ -1628,6 +1824,7 @@ var LlmService = class {
       ]
     };
     if (jsonMode) body.response_format = { type: "json_object" };
+    if (maxTokens != null) body.max_tokens = maxTokens;
     const data = await postJsonWithRetry(
       url,
       { Authorization: `Bearer ${this.config.llmApiKey}` },
@@ -1635,7 +1832,10 @@ var LlmService = class {
       { timeoutMs: this.config.httpTimeoutMs, maxRetries: this.config.httpMaxRetries },
       "LLM API"
     );
-    return data.choices[0].message.content ?? "";
+    return {
+      content: data.choices[0].message.content ?? "",
+      completionTokens: data.usage?.completion_tokens
+    };
   }
   // ── 带工具调用的请求 ──────────────────────────────────────────────────────────
   async chatWithTools(systemPrompt, userPrompt) {
@@ -1658,27 +1858,55 @@ var LlmService = class {
     );
     return data.choices[0].message;
   }
-  // ── 第一步：生成三级摘要（JSON 输出）──────────────────────────────────────────
+  // ── 对话 Topic 摘要（JSON 输出）──────────────────────────────────────────────
   async summarizeMessages(messages) {
     const now = (/* @__PURE__ */ new Date()).toISOString();
-    const { detailMaxTokens, summaryMaxTokens, conciseMaxTokens } = this.config;
+    const { topicSummaryMaxTokens } = 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
-\u8BF7\u5BF9\u7ED9\u5B9A\u7684\u5BF9\u8BDD\u5185\u5BB9\u751F\u6210\u4E00\u4E2A\u4E3B\u9898\u6807\u9898\u548C\u4E09\u7EA7\u6458\u8981\u3002
+\u8BF7\u628A\u7ED9\u5B9A\u5BF9\u8BDD\u538B\u7F29\u6210\u4E00\u4E2A\u53EF\u957F\u671F\u590D\u7528\u7684\u4E3B\u9898\u8BB0\u5FC6\u3002
 
 \u8981\u6C42\uFF1A
 - title\uFF1A\u4E3B\u9898\u6807\u9898\uFF0C\u4E00\u53E5\u8BDD\uFF08\u5EFA\u8BAE\u4E0D\u8D85\u8FC7 20 \u5B57\uFF09\uFF0C\u9AD8\u5EA6\u6982\u62EC\u8FD9\u6BB5\u5BF9\u8BDD\u7684\u4E3B\u9898\uFF0C\u7528\u4E8E\u5217\u8868\u5C55\u793A
-- detail\uFF1A\u8BE6\u7EC6\u6458\u8981\uFF0C\u6700\u591A ${detailMaxTokens} tokens\uFF0C\u4FDD\u7559\u5173\u952E\u4E8B\u5B9E\u3001\u4EBA\u7269\u548C\u65F6\u95F4
-- summary\uFF1A\u4E2D\u7B49\u6458\u8981\uFF0C\u6700\u591A ${summaryMaxTokens} tokens
-- concise\uFF1A\u4E00\u4E24\u53E5\u8BDD\u7684\u7B80\u6D01\u6458\u8981\uFF0C\u6700\u591A ${conciseMaxTokens} tokens
+- summary\uFF1A\u552F\u4E00\u7684\u6458\u8981\u6B63\u6587\uFF0C\u6700\u591A ${topicSummaryMaxTokens} tokens
+- \u6839\u636E\u91CD\u8981\u6027\u52A8\u6001\u51B3\u5B9A\u7BC7\u5E45\uFF1A\u7528\u6237\u7A33\u5B9A\u504F\u597D\u3001\u660E\u786E\u4E8B\u5B9E\u3001\u51B3\u5B9A\u4E0E\u7406\u7531\u3001\u957F\u671F\u7EA6\u675F\u3001\u672A\u89E3\u51B3\u963B\u585E\u3001\u53EF\u590D\u7528\u7ECF\u9A8C\u8981\u8BE6\u7EC6\u4FDD\u7559\uFF1B\u91CD\u590D\u8868\u8FF0\u3001\u5BD2\u6684\u548C\u4E00\u6B21\u6027\u8FC7\u7A0B\u53EF\u6781\u77ED\u6216\u7701\u7565
+- \u4FDD\u7559\u8C01\u5728\u4F55\u65F6\u505A\u4E86\u4EC0\u4E48\u3001\u5173\u952E\u6807\u8BC6\u7B26\u3001\u6570\u503C\u3001\u7ED3\u8BBA\u3001\u5931\u8D25\u539F\u56E0\u548C\u540E\u7EED\u52A8\u4F5C\uFF1B\u4E0D\u8981\u865A\u6784
+- metadata\u3001\u7ED3\u6784\u5316 parts \u548C payload \u4E2D\u5F71\u54CD\u8BED\u4E49\u7684\u4FE1\u606F\u540C\u6837\u5C5E\u4E8E\u8BB0\u5FC6\u5185\u5BB9
 
 \u8F93\u51FA\u5FC5\u987B\u662F\u5408\u6CD5\u7684 JSON \u5BF9\u8C61\uFF0C\u4E0D\u8981\u5305\u542B\u4EFB\u4F55 markdown \u6807\u8BB0\uFF0C\u683C\u5F0F\u5982\u4E0B\uFF1A
-{"title": "...", "detail": "...", "summary": "...", "concise": "..."}`;
-    const formatted = messages.map((m) => `[${new Date(m.createdAt).toISOString()}] ${m.talkerId || "user"}: ${m.content}`).join("\n");
-    const raw = await this.chatCompletion(systemPrompt, `\u8BF7\u5BF9\u4EE5\u4E0B\u5BF9\u8BDD\u751F\u6210\u4E3B\u9898\u6807\u9898\u548C\u4E09\u7EA7\u6458\u8981\uFF1A
+{"title": "...", "summary": "..."}`;
+    const formatted = messages.map((m) => formatStoredMessage(m)).join("\n");
+    const response = await this.chatCompletionWithUsage(
+      systemPrompt,
+      `\u8BF7\u538B\u7F29\u4EE5\u4E0B\u5BF9\u8BDD\uFF1A
 
-${formatted}`);
-    const parsed = JSON.parse(raw);
-    return { title: parsed.title ?? "", detail: parsed.detail, summary: parsed.summary, concise: parsed.concise };
+${formatted}`,
+      true,
+      topicSummaryMaxTokens + 128
+    );
+    const parsed = JSON.parse(response.content);
+    return {
+      title: parsed.title ?? "",
+      summary: parsed.summary ?? "",
+      tokens: response.completionTokens
+    };
+  }
+  async summarizeTopics(topics, maxSummaryTokens = this.config.topicSummaryMaxTokens) {
+    const input = topics.map(
+      (topic) => `[${new Date(topic.startTime).toISOString()} - ${new Date(topic.endTime).toISOString()}] ${topic.title}
+${topic.summary}`
+    ).join("\n\n");
+    const response = await this.chatCompletionWithUsage(
+      `\u4F60\u662F\u8BB0\u5FC6\u5F52\u5E76\u52A9\u624B\u3002\u628A\u4E00\u7EC4\u6309\u65F6\u95F4\u6392\u5217\u7684\u65E7\u4E3B\u9898\u5F52\u5E76\u6210\u4E00\u4E2A\u4E3B\u9898\u3002\u4FDD\u7559\u7A33\u5B9A\u504F\u597D\u3001\u4E8B\u5B9E\u3001\u51B3\u5B9A\u53CA\u7406\u7531\u3001\u957F\u671F\u7EA6\u675F\u3001\u963B\u585E\u4E0E\u53EF\u590D\u7528\u7ECF\u9A8C\uFF1B\u5220\u9664\u91CD\u590D\u5185\u5BB9\u3002summary \u6700\u591A ${maxSummaryTokens} tokens\u3002\u53EA\u8F93\u51FA JSON\uFF1A{"title":"...","summary":"..."}`,
+      input,
+      true,
+      maxSummaryTokens + 128
+    );
+    const parsed = JSON.parse(response.content);
+    return {
+      title: parsed.title ?? "\u5386\u53F2\u4E3B\u9898\u5F52\u5E76",
+      summary: parsed.summary ?? "",
+      tokens: response.completionTokens
+    };
   }
   // ── 第二步：通过工具调用提取实体和关系 ──────────────────────────────────────
   async extractEntitiesFromMessages(messages) {
@@ -1721,9 +1949,8 @@ ${formatted}`
     ]);
     return {
       title: summary.title,
-      detail: summary.detail,
       summary: summary.summary,
-      concise: summary.concise,
+      tokens: summary.tokens,
       entities: extraction.entities,
       relations: extraction.relations
     };
@@ -1812,18 +2039,51 @@ ${text}`
 ${context}`, false);
   }
 };
+function formatStoredMessage(message) {
+  const extras = [message.parts, message.metadata, message.payload].filter((value) => value && value !== "[]" && value !== "{}").join(" ");
+  return `[${new Date(message.createdAt).toISOString()}] ${message.talkerId || "user"}: ${message.content}${extras ? `
+meta=${extras}` : ""}`;
+}
 
 // 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;
-  store;
-  grafeo;
-  llm;
-  embed;
-  sessionCache;
-  semaphore;
-  sessionChain = /* @__PURE__ */ new Map();
   constructor(config, store, grafeo, llm, embed, sessionCache) {
     this.config = config;
     this.store = store;
@@ -1833,125 +2093,237 @@ var CompressManager = class {
     this.sessionCache = sessionCache;
     this.semaphore = new Semaphore(config.maxConcurrentCompressions);
   }
-  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, waitGraph))
+  semaphore;
+  sessionChain = /* @__PURE__ */ new Map();
+  backgroundGraphs = /* @__PURE__ */ new Set();
+  triggerCompress(sessionId, force = false, waitGraph = false, rawLimit) {
+    return this.enqueueSessionTask(
+      sessionId,
+      () => this.doCompress(sessionId, force, waitGraph, rawLimit)
     );
-    this.sessionChain.set(sessionId, next.catch(() => {
-    }));
+  }
+  /** 按给定预算收敛 Topic；persist=false 时只缓存当前模型使用的临时视图。 */
+  triggerTopicCompaction(sessionId, tokenLimit, persist) {
+    return this.enqueueSessionTask(
+      sessionId,
+      () => this.compactOldTopics(sessionId, Math.max(1, Math.floor(tokenLimit)), persist)
+    );
+  }
+  enqueueSessionTask(sessionId, task) {
+    const previous = this.sessionChain.get(sessionId) ?? Promise.resolve();
+    const next = previous.then(
+      () => this.semaphore.run(task)
+    );
+    const settled = next.catch(() => {
+    });
+    this.sessionChain.set(sessionId, settled);
+    settled.finally(() => {
+      if (this.sessionChain.get(sessionId) === settled) this.sessionChain.delete(sessionId);
+    });
     return next;
   }
-  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;
-    if (!force && entry.totalTokens < this.config.sessionTokenLimit) return;
-    const { chatId, userId } = entry.ids;
-    const startTime = messages[0].createdAt;
-    const endTime = messages[messages.length - 1].createdAt;
-    let summary;
-    try {
-      summary = await this.llm.summarizeMessages(messages);
-    } catch (err) {
-      console.error(`[CompressManager] LLM compress failed for session ${sessionId}: ${formatError(err)}`);
-      return;
+  async waitForIdle(sessionId) {
+    await (this.sessionChain.get(sessionId) ?? Promise.resolve());
+  }
+  isBusy(sessionId) {
+    return this.sessionChain.has(sessionId);
+  }
+  async waitForAllIdle() {
+    while (this.sessionChain.size > 0 || this.backgroundGraphs.size > 0) {
+      await Promise.all([
+        ...this.sessionChain.values(),
+        ...this.backgroundGraphs
+      ]);
     }
-    const { title, detail, summary: summaryText, concise } = summary;
-    const topicTextForEmbed = [detail, summaryText, concise].find((t) => t.length > 0) ?? "";
-    let topicVector = [];
+  }
+  async doCompress(sessionId, force, waitGraph, rawLimitOverride) {
+    const entry = this.sessionCache.getEntry(sessionId);
+    if (!entry || entry.messages.length === 0) return;
+    const rawLimit = Math.max(1, rawLimitOverride ?? this.rawLimit(entry.lastModelContextTokens));
+    const threshold = Math.max(1, Math.floor(rawLimit * this.config.precompressionRatio));
+    if (!force && entry.totalTokens < threshold) return;
+    let batchTarget = Math.max(1, Math.floor(rawLimit * this.config.compressionBatchRatio));
+    if (this.config.compressionBatchTokenLimit > 0) {
+      batchTarget = Math.min(batchTarget, this.config.compressionBatchTokenLimit);
+    }
+    const messages = this.sessionCache.selectOldestMessageBatch(sessionId, batchTarget);
+    if (messages.length === 0) return;
+    let result;
     try {
-      topicVector = await this.embed.embedOne(topicTextForEmbed);
-    } catch (err) {
-      console.error(`[CompressManager] Embed topic failed:`, err);
+      result = await this.llm.summarizeMessages(messages);
+    } catch (error) {
+      console.error(
+        `[CompressManager] LLM compress failed for session ${sessionId}: ${formatError(error)}`
+      );
+      throw error;
     }
+    const summary = result.summary.trim();
+    if (!summary) throw new Error(`LLM returned an empty summary for session ${sessionId}`);
+    const vector = await this.embed.embedOne(summary).catch((error) => {
+      console.error(`[CompressManager] Embed topic failed for session ${sessionId}:`, error);
+      return [];
+    });
+    const first = messages[0];
+    const last = messages[messages.length - 1];
+    const now = Date.now();
     const topic = {
       summaryId: uuidv4(),
       sessionId,
-      userId,
-      chatId,
-      title,
-      detail,
-      summary: summaryText,
-      concise,
-      startTime,
-      endTime,
-      createdAt: Date.now(),
-      updatedAt: Date.now(),
+      userId: entry.ids.userId,
+      chatId: entry.ids.chatId,
+      title: result.title,
+      summary,
+      tokens: result.tokens != null && result.tokens > 0 ? result.tokens : Math.max(1, countTokens(summary)),
+      startMessageId: first.messageId,
+      endMessageId: last.messageId,
+      startTime: first.createdAt,
+      endTime: last.createdAt,
+      createdAt: now,
+      updatedAt: now,
       recallCount: 0,
-      vector: topicVector
+      vector
     };
-    try {
-      await this.store.addTopic(topic);
-    } catch (err) {
-      console.error(`[CompressManager] Save topic failed:`, err);
-    }
-    this.sessionCache.clearMessages(sessionId, endTime);
-    const [n1, n2, n3] = this.config.topicRatio;
-    try {
-      const topicGroups = await this.store.getRecentTopics(chatId, userId, n1, n2, n3);
-      this.sessionCache.buildHistoryWindow(sessionId, topicGroups);
-    } catch (err) {
-      console.error(`[CompressManager] Rebuild history window failed:`, err);
-    }
-    const graphTask = this.extractAndPersistGraph(messages, sessionId, chatId, userId, endTime);
+    await this.store.addTopic(topic);
+    this.sessionCache.appendTopic(sessionId, topic);
+    this.sessionCache.removeMessages(sessionId, messages.map((message) => message.messageId));
+    await this.compactOldTopics(
+      sessionId,
+      this.config.compressedContextTokenLimit,
+      true
+    );
+    const graphTask = this.extractAndPersistGraph(
+      messages,
+      sessionId,
+      entry.ids.chatId,
+      entry.ids.userId,
+      last.createdAt
+    );
     if (waitGraph) {
       await withTimeout(graphTask, this.config.graphBuildTimeoutMs, "flushChat graph build");
     } else {
-      graphTask.catch((err) => {
-        console.error(`[CompressManager] Background graph persist failed:`, err);
+      const tracked = graphTask.catch((error) => {
+        console.error(`[CompressManager] Background graph persist failed:`, error);
       });
+      this.backgroundGraphs.add(tracked);
+      tracked.finally(() => this.backgroundGraphs.delete(tracked));
+    }
+  }
+  async compactOldTopics(sessionId, tokenLimit, persist) {
+    let transientTopics = persist ? void 0 : this.sessionCache.getTopicView(sessionId, tokenLimit) ?? [...this.sessionCache.getEntry(sessionId)?.topics ?? []];
+    while (true) {
+      const entry = this.sessionCache.getEntry(sessionId);
+      if (!entry) return;
+      const topics = persist ? entry.topics : transientTopics;
+      const topicTokens = sumTopicTokens(topics);
+      if (topicTokens <= tokenLimit) {
+        if (!persist) this.sessionCache.setTopicView(sessionId, tokenLimit, topics);
+        return;
+      }
+      const target = Math.max(1, Math.floor(topicTokens / 2));
+      const selected = [];
+      let selectedTokens = 0;
+      for (const topic of topics) {
+        selected.push(topic);
+        selectedTokens += topic.tokens;
+        if (selectedTokens >= target && (selected.length >= 2 || topics.length === 1)) break;
+      }
+      if (selected.length === 0) return;
+      console.info(
+        `[CompressManager] session ${sessionId} compressed Topic context exceeds ${tokenLimit} tokens; compacting ${selected.length} old topics${persist ? " persistently" : " for a transient model view"}.`
+      );
+      const unselectedTokens = topicTokens - selectedTokens;
+      const maxSummaryTokens = Math.max(
+        1,
+        Math.min(
+          this.config.topicSummaryMaxTokens,
+          selectedTokens - 1,
+          Math.max(1, tokenLimit - unselectedTokens)
+        )
+      );
+      const result = await this.llm.summarizeTopics(selected, maxSummaryTokens);
+      const summary = result.summary.trim();
+      if (!summary) throw new Error(`LLM returned an empty Topic rollup for session ${sessionId}`);
+      const vector = persist ? await this.embed.embedOne(summary).catch(() => []) : [];
+      const first = selected[0];
+      const last = selected[selected.length - 1];
+      const now = Date.now();
+      const rollup = {
+        summaryId: uuidv4(),
+        sessionId,
+        userId: entry.ids.userId,
+        chatId: entry.ids.chatId,
+        title: result.title,
+        summary,
+        tokens: Math.max(1, countTokens(summary)),
+        startMessageId: first.startMessageId,
+        endMessageId: last.endMessageId,
+        startTime: first.startTime,
+        endTime: last.endTime,
+        createdAt: now,
+        updatedAt: now,
+        recallCount: 0,
+        vector
+      };
+      if (rollup.tokens >= selectedTokens) {
+        throw new Error(
+          `Topic compaction made no progress for session ${sessionId}: ${selectedTokens} -> ${rollup.tokens} tokens`
+        );
+      }
+      const removedIds = selected.map((topic) => topic.summaryId);
+      if (persist) {
+        await this.store.addTopic(rollup);
+        this.sessionCache.replaceTopics(sessionId, removedIds, rollup);
+        await this.store.deleteTopicsByIds(removedIds);
+      } else {
+        const ids = new Set(removedIds);
+        transientTopics = [
+          ...topics.filter((topic) => !ids.has(topic.summaryId)),
+          rollup
+        ].sort(topicOrder);
+      }
     }
   }
+  rawLimit(modelContextTokens = this.config.defaultModelContextTokens) {
+    return calculateContextBudget(this.config, modelContextTokens).rawTokenLimit;
+  }
   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) => ({
-      name: e.name,
-      type: e.type,
-      meta: {
-        sessionId,
-        chatId,
-        userId,
-        messageTime,
-        ...e.meta
-      }
+    const entities = rawEntities.map((entity) => ({
+      name: entity.name,
+      type: entity.type,
+      meta: { sessionId, chatId, userId, messageTime, ...entity.meta }
     }));
-    const relations = rawRelations.map((r) => ({
-      from: r.from,
-      to: r.to,
-      type: r.type,
-      happenedAt: r.happenedAt ?? void 0,
-      meta: {
-        sessionId,
-        chatId,
-        userId,
-        messageTime,
-        ...r.meta
-      }
+    const relations = rawRelations.map((relation) => ({
+      from: relation.from,
+      to: relation.to,
+      type: relation.type,
+      happenedAt: relation.happenedAt,
+      meta: { sessionId, chatId, userId, messageTime, ...relation.meta }
     }));
-    const allNames = [.../* @__PURE__ */ new Set([...entities.map((e) => e.name), ...relations.flatMap((r) => [r.from, r.to])])];
-    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(`[CompressManager] Embed entity names failed:`, err);
-      return;
-    }
-    try {
-      await this.grafeo.upsertEntitiesAndRelations(entities, relations, embeddings);
-    } catch (err) {
-      console.error(`[CompressManager] Upsert entities/relations failed:`, err);
-    }
+    const names = [
+      .../* @__PURE__ */ new Set([
+        ...entities.map((entity) => entity.name),
+        ...relations.flatMap((relation) => [relation.from, relation.to])
+      ])
+    ];
+    if (names.length === 0) return;
+    const vectors = await this.embed.embed(names);
+    const embeddings = new Map(names.map((name, index) => [name, vectors[index]]));
+    await this.grafeo.upsertEntitiesAndRelations(entities, relations, embeddings);
   }
 };
-function formatError(err) {
-  return err instanceof Error ? err.message : String(err);
+function sumTopicTokens(topics) {
+  return topics.reduce((sum, topic) => sum + Math.max(1, topic.tokens), 0);
+}
+function topicOrder(a, b) {
+  return a.endTime - b.endTime || a.summaryId.localeCompare(b.summaryId);
+}
+function formatError(error) {
+  return error instanceof Error ? error.message : String(error);
 }
 function withTimeout(promise, timeoutMs, label) {
   let timer;
@@ -1981,22 +2353,30 @@ var FactCache = class {
   key(level, id) {
     return `${level}:${id}`;
   }
-  async add(content, level, userId, chatId, sessionId = "default") {
+  async add(content, level, userId, chatId, sessionId = "default", key) {
+    const id = level === "user" ? userId : chatId;
+    const cacheKey = this.key(level, id);
+    const existing = this.cache.get(cacheKey) ?? [];
+    const normalizedKey = key?.trim() || void 0;
+    const existingIndex = normalizedKey ? existing.findIndex((fact2) => fact2.key === normalizedKey) : -1;
+    const previous = existingIndex >= 0 ? existing[existingIndex] : void 0;
+    const now = Date.now();
     const fact = {
-      factId: uuidv42(),
+      factId: previous?.factId ?? uuidv42(),
       level,
       chatId,
       sessionId,
       userId,
+      key: normalizedKey,
       content,
-      createdAt: Date.now()
+      createdAt: previous?.createdAt ?? now,
+      updatedAt: now
     };
-    await this.store.saveFact(fact);
-    const id = level === "user" ? userId : chatId;
-    const k = this.key(level, id);
-    const existing = this.cache.get(k) ?? [];
-    existing.push(fact);
-    this.cache.set(k, existing);
+    if (previous) await this.store.updateFact(fact);
+    else await this.store.saveFact(fact);
+    if (existingIndex >= 0) existing[existingIndex] = fact;
+    else existing.push(fact);
+    this.cache.set(cacheKey, existing);
   }
   get(level, id) {
     return this.cache.get(this.key(level, id)) ?? [];
@@ -2024,7 +2404,9 @@ var FactCache = class {
   toString(level, id) {
     const facts = this.get(level, id);
     if (facts.length === 0) return "";
-    return facts.sort((a, b) => a.createdAt - b.createdAt).map((f) => `${new Date(f.createdAt).toISOString()}\uFF1A${f.content}`).join("\n");
+    return facts.sort((a, b) => a.createdAt - b.createdAt).map(
+      (f) => `${new Date(f.updatedAt ?? f.createdAt).toISOString()}\uFF1A${f.key ? `[${f.key}] ` : ""}${f.content}`
+    ).join("\n");
   }
 };
 
@@ -2184,11 +2566,8 @@ var KnowledgeManager = class {
     const now = Date.now();
     const content = opts.content;
     const contentHash = createHash("sha256").update(content).digest("hex");
-    const domainFilter = [
-      eq("user_id", userId),
-      eq("chat_id", chatId),
-      eq("session_id", sessionId)
-    ];
+    const dedupeScope = opts.scope ?? "session";
+    const domainFilter = dedupeScope === "user" ? [eq("user_id", userId)] : dedupeScope === "chat" ? [eq("chat_id", chatId)] : [eq("session_id", sessionId)];
     const existing = await this.store.findDocumentByHash(contentHash, domainFilter);
     if (existing) return { docId: existing.docId };
     const pieces = chunkMarkdown(content, {
@@ -2507,73 +2886,218 @@ function withTimeout2(promise, timeoutMs, label) {
 var SessionCache = class {
   config;
   sessions = /* @__PURE__ */ new Map();
-  historyWindows = /* @__PURE__ */ new Map();
+  topicViews = /* @__PURE__ */ new Map();
+  legacyHistoryWindows = /* @__PURE__ */ new Map();
   constructor(config) {
     this.config = config;
   }
   getEntry(sessionId) {
+    const entry = this.sessions.get(sessionId);
+    if (entry) entry.lastAccessAt = Date.now();
+    return entry;
+  }
+  peekEntry(sessionId) {
     return this.sessions.get(sessionId);
   }
   getOrCreateEntry(sessionId, chatId, userId) {
     let entry = this.sessions.get(sessionId);
     if (!entry) {
-      entry = { messages: [], totalTokens: 0, ids: { chatId, userId } };
+      entry = {
+        messages: [],
+        totalTokens: 0,
+        topics: [],
+        topicTokens: 0,
+        ids: { chatId, userId },
+        lastAccessAt: Date.now()
+      };
       this.sessions.set(sessionId, entry);
+    } else {
+      entry.ids = { chatId, userId };
+      entry.lastAccessAt = Date.now();
     }
     return entry;
   }
-  addMessages(sessionId, messages, chatId, userId) {
+  hydrate(sessionId, chatId, userId, messages, topics) {
+    const entry = this.getOrCreateEntry(sessionId, chatId, userId);
+    entry.messages = sortMessages(dedupeMessages(messages));
+    entry.totalTokens = sumMessageTokens(entry.messages);
+    this.setTopics(sessionId, topics, false);
+    return entry;
+  }
+  upsertMessages(sessionId, messages, chatId, userId) {
     const entry = this.getOrCreateEntry(sessionId, chatId, userId);
-    entry.messages.push(...messages);
-    entry.totalTokens += messages.reduce((sum, m) => sum + m.usage, 0);
+    const byId = new Map(entry.messages.map((m) => [m.messageId, m]));
+    for (const message of messages) byId.set(message.messageId, message);
+    entry.messages = sortMessages([...byId.values()]);
+    entry.totalTokens = sumMessageTokens(entry.messages);
+    return entry;
+  }
+  /** @deprecated 0.3.x 单元/API 兼容；新代码使用 upsertMessages。 */
+  addMessages(sessionId, messages, chatId, userId) {
+    const entry = this.upsertMessages(sessionId, messages, chatId, userId);
     return entry.totalTokens >= this.config.sessionTokenLimit;
   }
+  /** @deprecated 新压缩链按 messageId 精确移除。 */
   clearMessages(sessionId, keepAfter) {
     const entry = this.sessions.get(sessionId);
     if (!entry) return;
-    if (keepAfter != null) {
-      entry.messages = entry.messages.filter((m) => m.createdAt > keepAfter);
-      entry.totalTokens = entry.messages.reduce((sum, m) => sum + m.usage, 0);
-    } else {
-      entry.messages = [];
-      entry.totalTokens = 0;
-    }
+    entry.messages = keepAfter == null ? [] : entry.messages.filter((message) => message.createdAt > keepAfter);
+    entry.totalTokens = sumMessageTokens(entry.messages);
+  }
+  removeMessages(sessionId, messageIds) {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    const ids = new Set(messageIds);
+    entry.messages = entry.messages.filter((m) => !ids.has(m.messageId));
+    entry.totalTokens = sumMessageTokens(entry.messages);
+    entry.lastAccessAt = Date.now();
   }
   getSessionMessages(sessionId) {
-    return this.sessions.get(sessionId)?.messages ?? [];
+    return this.getEntry(sessionId)?.messages ?? [];
   }
-  getAllSessionIds() {
-    return [...this.sessions.keys()];
+  selectOldestMessageBatch(sessionId, targetTokens) {
+    const messages = this.getSessionMessages(sessionId);
+    if (messages.length === 0 || targetTokens <= 0) return [];
+    const selected = [];
+    let tokens = 0;
+    for (const message of messages) {
+      selected.push(message);
+      tokens += effectiveUsage(message);
+      if (tokens >= targetTokens) break;
+    }
+    return selected;
   }
-  buildHistoryWindow(sessionId, topicGroups) {
-    const { topicRatio, historyWindowTokenLimit } = this.config;
-    const [n1, n2, n3] = topicRatio;
-    let remaining = historyWindowTokenLimit;
-    const parts = [];
-    const addTopics = (topics, field, max) => {
-      let count = 0;
-      for (const t of topics) {
-        if (count >= max || remaining <= 0) break;
-        const text = t[field];
-        const tokens = countTokens(text);
-        if (tokens > remaining) break;
-        parts.push(text);
-        remaining -= tokens;
-        count++;
-      }
-    };
-    addTopics(topicGroups.detail, "detail", n1);
-    addTopics(topicGroups.summary, "summary", n2);
-    addTopics(topicGroups.concise, "concise", n3);
-    this.historyWindows.set(sessionId, parts.join("\n\n"));
+  setTopics(sessionId, topics, truncate = true) {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    const ordered = [...topics].sort(topicOrder2);
+    const kept = [];
+    let used = 0;
+    for (let i = ordered.length - 1; i >= 0; i--) {
+      const topic = normalizeTopic(ordered[i]);
+      if (truncate && used + topic.tokens > this.config.compressedContextTokenLimit && kept.length > 0) break;
+      kept.push(topic);
+      used += topic.tokens;
+    }
+    entry.topics = kept.reverse();
+    entry.topicTokens = used;
+    entry.lastAccessAt = Date.now();
+    this.topicViews.delete(sessionId);
+  }
+  appendTopic(sessionId, topic) {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    this.setTopics(sessionId, [...entry.topics, topic], false);
+  }
+  replaceTopics(sessionId, removedIds, replacement) {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    const ids = new Set(removedIds);
+    this.setTopics(
+      sessionId,
+      [...entry.topics.filter((topic) => !ids.has(topic.summaryId)), replacement],
+      false
+    );
+  }
+  getTopics(sessionId) {
+    return this.getEntry(sessionId)?.topics ?? [];
+  }
+  getTopicView(sessionId, tokenLimit) {
+    return this.topicViews.get(sessionId)?.get(tokenLimit);
+  }
+  setTopicView(sessionId, tokenLimit, topics) {
+    let views = this.topicViews.get(sessionId);
+    if (!views) {
+      views = /* @__PURE__ */ new Map();
+      this.topicViews.set(sessionId, views);
+    }
+    views.set(tokenLimit, [...topics].map(normalizeTopic).sort(topicOrder2));
+  }
+  buildCompressedContext(sessionId, topics) {
+    return (topics ?? this.getTopics(sessionId)).map((topic) => topic.title ? `## ${topic.title}
+${topic.summary}` : topic.summary).join("\n\n");
+  }
+  /** @deprecated 三级窗口兼容，仅供 0.3.x 调用方过渡。 */
+  buildHistoryWindow(sessionId, groups) {
+    const [detailCount, summaryCount, conciseCount] = this.config.topicRatio;
+    const values = [
+      ...groups.detail.slice(0, detailCount).map((topic) => topic.detail ?? topic.summary),
+      ...groups.summary.slice(0, summaryCount).map((topic) => topic.summary),
+      ...groups.concise.slice(0, conciseCount).map((topic) => topic.concise ?? topic.summary)
+    ];
+    let remaining = this.config.historyWindowTokenLimit;
+    const kept = [];
+    for (const value of values) {
+      const tokens = countTokens(value);
+      if (tokens > remaining) break;
+      kept.push(value);
+      remaining -= tokens;
+    }
+    this.legacyHistoryWindows.set(sessionId, kept.join("\n\n"));
   }
+  /** @deprecated MemoryManager.getHistoryWindow 返回结构化窗口。 */
   getHistoryWindow(sessionId) {
-    return this.historyWindows.get(sessionId) ?? "";
+    return this.legacyHistoryWindows.get(sessionId) ?? this.buildCompressedContext(sessionId);
   }
+  /** @deprecated 仅为 0.3.x 兼容。 */
   setHistoryWindow(sessionId, content) {
-    this.historyWindows.set(sessionId, content);
+    this.legacyHistoryWindows.set(sessionId, content);
+  }
+  setModelContextTokens(sessionId, modelContextTokens) {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    entry.lastModelContextTokens = modelContextTokens;
+    entry.lastAccessAt = Date.now();
+  }
+  getAllSessionIds() {
+    return [...this.sessions.keys()];
+  }
+  delete(sessionId) {
+    this.sessions.delete(sessionId);
+    this.topicViews.delete(sessionId);
+    this.legacyHistoryWindows.delete(sessionId);
+  }
+  evictIdle(now, ttlMs, isBusy) {
+    if (ttlMs <= 0) return [];
+    const evicted = [];
+    for (const [sessionId, entry] of this.sessions) {
+      if (now - entry.lastAccessAt < ttlMs || isBusy(sessionId)) continue;
+      this.sessions.delete(sessionId);
+      this.topicViews.delete(sessionId);
+      evicted.push(sessionId);
+    }
+    return evicted;
   }
 };
+function effectiveUsage(message) {
+  if (Number.isFinite(message.usage) && message.usage > 0) return Math.floor(message.usage);
+  return Math.max(
+    1,
+    (message.content.length + (message.parts?.length ?? 0) + message.metadata.length + (message.payload?.length ?? 0)) * 2
+  );
+}
+function sumMessageTokens(messages) {
+  return messages.reduce((sum, message) => sum + effectiveUsage(message), 0);
+}
+function dedupeMessages(messages) {
+  return [...new Map(messages.map((message) => [message.messageId, message])).values()];
+}
+function sortMessages(messages) {
+  return messages.sort(
+    (a, b) => a.createdAt - b.createdAt || a.messageId.localeCompare(b.messageId)
+  );
+}
+function topicOrder2(a, b) {
+  return a.endTime - b.endTime || a.summaryId.localeCompare(b.summaryId);
+}
+function normalizeTopic(topic) {
+  const summary = topic.summary || topic.detail || topic.concise || "";
+  return {
+    ...topic,
+    summary,
+    tokens: topic.tokens > 0 ? topic.tokens : Math.max(1, countTokens(summary))
+  };
+}
 
 // src/memory.manager.ts
 var MemoryManager = class {
@@ -2588,7 +3112,14 @@ var MemoryManager = class {
   knowledgeManager;
   sessionMap = /* @__PURE__ */ new Map();
   optimizeTimer;
+  sessionSweepTimer;
   optimizeRunning = false;
+  optimizeTask;
+  destroyTask;
+  hydration = /* @__PURE__ */ new Map();
+  pendingWrites = /* @__PURE__ */ new Map();
+  topicCompactions = /* @__PURE__ */ new Map();
+  warnedDefaultModelContext = false;
   constructor(config) {
     this.config = resolveConfig(config);
     this.store = new MemoryStore(this.config);
@@ -2622,17 +3153,26 @@ var MemoryManager = class {
     for (const s of allSessions) {
       this.sessionMap.set(s.sessionId, this.deserializeSession(s));
     }
-    await this.restoreFromStorage();
     if (this.config.autoOptimizeOnInit) {
-      void this.runBackgroundOptimize(this.config.optimizeVersionRetentionMs);
+      this.optimizeTask = 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.optimizeTask = this.runBackgroundOptimize(retention);
       }, this.config.autoOptimizeIntervalMs);
       this.optimizeTimer.unref?.();
     }
+    if (this.config.sessionIdleTtlMs > 0) {
+      this.sessionSweepTimer = setInterval(() => {
+        this.sessionCache.evictIdle(
+          Date.now(),
+          this.config.sessionIdleTtlMs,
+          (sessionId) => this.isSessionBusy(sessionId)
+        );
+      }, this.config.sessionSweepIntervalMs);
+      this.sessionSweepTimer.unref?.();
+    }
   }
   /** 后台压实的统一入口：防重入（上一轮未结束则跳过），失败仅告警不影响服务。*/
   async runBackgroundOptimize(retentionMs) {
@@ -2660,120 +3200,141 @@ var MemoryManager = class {
   async optimizeStorage(retentionMs) {
     return this.store.optimizeStorage(retentionMs ?? this.config.optimizeVersionRetentionMs);
   }
-  async restoreFromStorage() {
-    const [n1, n2, n3] = this.config.topicRatio;
-    const sessionIds = await this.store.getAllSessionIds();
-    if (sessionIds.length === 0) return;
-    const topicsCache = /* @__PURE__ */ new Map();
-    const getTopics = (chatId, userId) => {
-      const key = `${chatId}\0${userId}`;
-      let cached = topicsCache.get(key);
-      if (!cached) {
-        cached = this.store.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.store.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.store.getMessagesSince(sessionId, n1EndTime) : await this.store.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 ensureSessionHydrated(sessionId, fallbackIds) {
+    if (this.sessionCache.peekEntry(sessionId)) return;
+    let task = this.hydration.get(sessionId);
+    if (!task) {
+      task = (async () => {
+        const allTopics = await this.store.getTopicsBySession(sessionId);
+        const latestTopic = allTopics.at(-1);
+        const allRawAfterBoundary = latestTopic ? await this.store.getMessagesAfterBoundary(
+          sessionId,
+          latestTopic.endTime,
+          latestTopic.endMessageId
+        ) : await this.store.getAllMessagesBySession(sessionId);
+        const since = this.config.maxHistoryAgeMs > 0 ? Date.now() - this.config.maxHistoryAgeMs : 0;
+        const rawMessages = since > 0 ? allRawAfterBoundary.filter((message) => message.createdAt >= since) : allRawAfterBoundary;
+        const session = this.sessionMap.get(sessionId);
+        const ids = allRawAfterBoundary.at(-1) ?? latestTopic ?? session ?? fallbackIds ?? { chatId: DEFAULT_CHAT_ID, userId: DEFAULT_USER_ID };
+        const visibleTopics = since > 0 ? allTopics.filter((topic) => topic.endTime >= since) : allTopics;
+        this.sessionCache.hydrate(
+          sessionId,
+          ids.chatId,
+          ids.userId,
+          rawMessages,
+          visibleTopics
+        );
+      })();
+      this.hydration.set(sessionId, task);
+      task.finally(() => {
+        if (this.hydration.get(sessionId) === task) this.hydration.delete(sessionId);
+      });
+    }
+    await task;
   }
-  async updateChat(messages, opts) {
-    if (messages.length === 0) return;
-    const userId = opts?.userId ?? DEFAULT_USER_ID;
-    const chatId = opts?.chatId ?? DEFAULT_CHAT_ID;
-    const sessionId = opts?.sessionId ?? DEFAULT_SESSION_ID;
+  isSessionBusy(sessionId) {
+    return this.hydration.has(sessionId) || this.pendingWrites.has(sessionId) || [...this.topicCompactions.keys()].some((key) => key.startsWith(`${sessionId}:`)) || this.compressManager.isBusy(sessionId);
+  }
+  waitForPendingWrites(sessionId) {
+    return this.pendingWrites.get(sessionId) ?? Promise.resolve();
+  }
+  queueSessionWrite(sessionId, write) {
+    const previous = this.pendingWrites.get(sessionId) ?? Promise.resolve();
+    const task = previous.catch(() => {
+    }).then(write);
+    const settled = task.catch(() => {
+    });
+    this.pendingWrites.set(sessionId, settled);
+    settled.finally(() => {
+      if (this.pendingWrites.get(sessionId) === settled) this.pendingWrites.delete(sessionId);
+    });
+    return task;
+  }
+  updateChat(messages, opts) {
+    if (messages.length === 0) return Promise.resolve();
+    const sessionId = opts?.sessionId ?? messages[0]?.sessionId ?? DEFAULT_SESSION_ID;
+    return this.queueSessionWrite(sessionId, () => this.doUpdateChat(messages, opts, sessionId));
+  }
+  async doUpdateChat(messages, opts, sessionId) {
+    const userId = opts?.userId ?? messages[0]?.userId ?? DEFAULT_USER_ID;
+    const chatId = opts?.chatId ?? messages[0]?.chatId ?? DEFAULT_CHAT_ID;
     const now = Date.now();
-    const withUsage = messages.map((m) => ({
-      messageId: m.messageId ?? uuidv44(),
-      talkerId: m.talkerId ?? "user",
-      chatId: m.chatId ?? chatId,
-      userId: m.userId ?? userId,
-      sessionId: m.sessionId ?? sessionId,
-      type: m.type ?? "text",
-      content: m.content,
-      parts: JSON.stringify(m.parts ?? []),
-      usage: m.usage ?? countTokens(m.content),
-      metadata: JSON.stringify(m.metadata ?? {}),
-      createdAt: m.createdAt ?? now
-    }));
-    let vectors;
-    try {
-      vectors = await this.embed.embed(withUsage.map((m) => m.content));
-    } catch (err) {
-      console.error("[MemoryManager] Embedding failed:", err);
-      throw err;
-    }
-    const stored = withUsage.map((m, i) => ({
-      messageId: m.messageId,
-      talkerId: m.talkerId,
-      chatId: m.chatId,
-      userId: m.userId,
-      sessionId: m.sessionId,
-      type: m.type,
-      content: m.content,
-      parts: m.parts,
-      usage: m.usage,
-      metadata: m.metadata,
-      vector: vectors[i],
-      createdAt: m.createdAt
-    }));
-    await this.store.addMessages(stored);
-    if (!this.sessionMap.has(sessionId)) {
-      const session = {
-        sessionId,
-        chatId,
-        userId,
-        title: opts?.sessionTitle ?? "",
-        metadata: JSON.stringify(opts?.sessionMetadata ?? {}),
-        createdAt: now,
-        updatedAt: now
+    await this.ensureSessionHydrated(sessionId, { chatId, userId });
+    const normalized = messages.map((message) => {
+      const parts = JSON.stringify(message.parts ?? []);
+      const metadata = JSON.stringify(message.metadata ?? {});
+      const payload = message.payload === void 0 ? void 0 : JSON.stringify(message.payload);
+      const tokenInput = [message.content, parts, metadata, payload ?? ""].join("\n");
+      return {
+        messageId: message.messageId ?? uuidv44(),
+        talkerId: message.talkerId ?? "user",
+        chatId: message.chatId ?? chatId,
+        userId: message.userId ?? userId,
+        sessionId: message.sessionId ?? sessionId,
+        type: message.type ?? "text",
+        content: message.content,
+        parts,
+        payload,
+        usage: message.usage ?? countTokens(tokenInput),
+        metadata,
+        createdAt: message.createdAt ?? now
       };
-      this.sessionMap.set(sessionId, this.deserializeSession(session));
-      this.store.insertSession(session).catch((err) => {
-        console.error("[MemoryManager] Failed to insert session:", err);
-      });
-    } else {
-      const view = this.sessionMap.get(sessionId);
-      view.updatedAt = now;
-      this.store.upsertSession(this.serializeSession(view)).catch((err) => {
-        console.error(`[MemoryManager] Failed to upsert session ${sessionId}:`, err);
+    });
+    const vectors = await this.embed.embed(normalized.map((message) => message.content));
+    const stored = normalized.map((message, index) => ({
+      ...message,
+      vector: vectors[index]
+    }));
+    await this.store.upsertMessages(stored);
+    this.sessionCache.upsertMessages(sessionId, stored, chatId, userId);
+    const existing = this.sessionMap.get(sessionId);
+    const session = existing ? {
+      ...this.serializeSession(existing),
+      updatedAt: now,
+      ...opts?.sessionTitle !== void 0 && { title: opts.sessionTitle },
+      ...opts?.sessionMetadata !== void 0 && {
+        metadata: JSON.stringify(opts.sessionMetadata)
+      }
+    } : {
+      sessionId,
+      chatId,
+      userId,
+      title: opts?.sessionTitle ?? "",
+      metadata: JSON.stringify(opts?.sessionMetadata ?? {}),
+      createdAt: now,
+      updatedAt: now
+    };
+    this.sessionMap.set(sessionId, this.deserializeSession(session));
+    if (existing) await this.store.upsertSession(session);
+    else await this.store.insertSession(session);
+    const entry = this.sessionCache.getEntry(sessionId);
+    const rawLimit = this.calculateWindowUsage(
+      entry.lastModelContextTokens ?? this.config.defaultModelContextTokens
+    ).rawTokenLimit;
+    if (entry.totalTokens >= Math.floor(rawLimit * this.config.precompressionRatio)) {
+      void this.compressManager.triggerCompress(sessionId, false, false, rawLimit).catch((error) => {
+        console.error(`[MemoryManager] Background compress failed for ${sessionId}:`, error);
       });
     }
-    (async () => {
-      const overLimit = this.sessionCache.addMessages(sessionId, stored, chatId, userId);
-      if (overLimit) {
-        await this.compressManager.triggerCompress(sessionId).catch((err) => {
-          console.error("[MemoryManager] Background compress failed:", err);
-        });
-      }
-    })();
   }
   async flushChat(sessionId, opts) {
     const sid = sessionId ?? DEFAULT_SESSION_ID;
-    const promise = this.compressManager.triggerCompress(sid, true, opts?.waitGraph === true);
+    await this.waitForPendingWrites(sid);
+    await this.ensureSessionHydrated(sid);
+    const entry = this.sessionCache.getEntry(sid);
+    const rawLimit = this.calculateWindowUsage(
+      entry?.lastModelContextTokens ?? this.config.defaultModelContextTokens
+    ).rawTokenLimit;
+    const promise = this.compressManager.triggerCompress(
+      sid,
+      true,
+      opts?.waitGraph === true,
+      rawLimit
+    );
     if (opts?.wait) await promise;
   }
-  async updateFacts(content, level, userId, chatId, sessionId) {
-    await this.factCache.add(content, level, userId, chatId, sessionId);
+  async updateFacts(content, level, userId, chatId, sessionId, key) {
+    await this.factCache.add(content, level, userId, chatId, sessionId, key);
   }
   async updateEntity(entities, relations, context) {
     if (entities.length === 0 && relations.length === 0) return;
@@ -2817,16 +3378,32 @@ var MemoryManager = class {
       useGraph = await this.llm.judgeNeedsGraphSearch(query).catch(() => false);
     }
     const tasks = [
-      this.store.hybridSearchTopics(query, vector, filter, limit).then(
-        (topics) => topics.map((t) => ({
+      this.store.hybridSearchTopics(query, vector, filter, limit).then((topics) => {
+        void this.store.incrementTopicRecallCounts(topics).catch(() => {
+        });
+        return topics.map((topic, index) => ({
           type: "topic",
-          content: t.detail,
-          score: 1,
+          content: topic.summary,
+          score: 1 / (index + 1),
+          meta: {
+            summaryId: topic.summaryId,
+            sessionId: topic.sessionId,
+            chatId: topic.chatId,
+            userId: topic.userId
+          }
+        }));
+      }).catch(() => []),
+      this.store.hybridSearchMessages(query, vector, filter, limit).then(
+        (messages) => messages.map((message, index) => ({
+          type: "message",
+          content: message.content,
+          score: 1 / (index + 1),
           meta: {
-            summaryId: t.summaryId,
-            sessionId: t.sessionId,
-            chatId: t.chatId,
-            userId: t.userId
+            messageId: message.messageId,
+            sessionId: message.sessionId,
+            chatId: message.chatId,
+            userId: message.userId,
+            metadata: safeParseObject2(message.metadata)
           }
         }))
       ).catch(() => [])
@@ -2885,10 +3462,159 @@ var MemoryManager = class {
       ...this.factCache.get("chat", chatId)
     ].sort((a, b) => a.createdAt - b.createdAt);
     if (merged.length === 0) return "";
-    return merged.map((f) => `${new Date(f.createdAt).toISOString()}\uFF1A${f.content}`).join("\n");
+    return merged.map(
+      (f) => `${new Date(f.updatedAt ?? f.createdAt).toISOString()}\uFF1A${f.key ? `[${f.key}] ` : ""}${f.content}`
+    ).join("\n");
+  }
+  async getHistoryWindow(sessionId, modelContextTokens, options) {
+    let modelTokens = modelContextTokens;
+    if (modelTokens == null) {
+      modelTokens = this.config.defaultModelContextTokens;
+      if (!this.warnedDefaultModelContext) {
+        this.warnedDefaultModelContext = true;
+        console.warn(
+          `[MemoryManager] getHistoryWindow \u672A\u4F20 modelContextTokens\uFF0C\u4F7F\u7528\u9ED8\u8BA4 ${modelTokens} tokens\u3002`
+        );
+      }
+    }
+    if (!Number.isFinite(modelTokens) || modelTokens <= 0) {
+      throw new Error("modelContextTokens \u5FC5\u987B\u662F\u6B63\u6570");
+    }
+    modelTokens = Math.floor(modelTokens);
+    await this.waitForPendingWrites(sessionId);
+    await this.ensureSessionHydrated(sessionId);
+    this.sessionCache.setModelContextTokens(sessionId, modelTokens);
+    const usageLimits = this.calculateWindowUsage(modelTokens);
+    let blockingReason;
+    const beginBlocking = (reason) => {
+      if (blockingReason) return;
+      blockingReason = reason;
+      this.notifyBlockingCompression(options, { sessionId, phase: "start", reason });
+    };
+    try {
+      for (let attempt = 0; attempt < 100; attempt++) {
+        let entry2 = this.sessionCache.getEntry(sessionId);
+        if (entry2.totalTokens <= usageLimits.rawTokenLimit || entry2.messages.length === 0) break;
+        if (this.compressManager.isBusy(sessionId)) {
+          beginBlocking("pending");
+          await this.compressManager.waitForIdle(sessionId);
+          entry2 = this.sessionCache.getEntry(sessionId);
+          if (entry2.totalTokens <= usageLimits.rawTokenLimit || entry2.messages.length === 0) break;
+        }
+        beginBlocking("raw");
+        console.warn(
+          `[MemoryManager] session ${sessionId} raw history (${entry2.totalTokens}) exceeds current model budget (${usageLimits.rawTokenLimit}); waiting for immediate compression.`
+        );
+        const beforeTokens = entry2.totalTokens;
+        await this.compressManager.triggerCompress(
+          sessionId,
+          true,
+          false,
+          usageLimits.rawTokenLimit
+        );
+        const after = this.sessionCache.getEntry(sessionId);
+        if (after.messages.length > 0 && after.totalTokens >= beforeTokens) {
+          throw new Error(`Compression made no progress for session ${sessionId}`);
+        }
+      }
+      let entry = this.sessionCache.getEntry(sessionId);
+      if (entry.totalTokens > usageLimits.rawTokenLimit) {
+        throw new Error(`Unable to fit session ${sessionId} into the requested model context`);
+      }
+      let topicView = this.sessionCache.getTopicView(
+        sessionId,
+        usageLimits.compressedTokenLimit
+      );
+      if (!topicView && entry.topicTokens > usageLimits.compressedTokenLimit) {
+        const affectsCurrentWindow = entry.topicTokens + entry.totalTokens > usageLimits.usableContextTokens;
+        const materiallyOverLimit = entry.topicTokens > Math.floor(
+          usageLimits.compressedTokenLimit * this.config.topicCompactionSyncRatio
+        );
+        if (affectsCurrentWindow || materiallyOverLimit) {
+          if (this.compressManager.isBusy(sessionId)) beginBlocking("pending");
+          else beginBlocking("topics");
+          await this.compactTopicsForBudget(sessionId, usageLimits.compressedTokenLimit);
+          entry = this.sessionCache.getEntry(sessionId);
+          topicView = this.sessionCache.getTopicView(
+            sessionId,
+            usageLimits.compressedTokenLimit
+          );
+        } else {
+          void this.compactTopicsForBudget(
+            sessionId,
+            usageLimits.compressedTokenLimit
+          ).catch((error) => {
+            console.error(`[MemoryManager] Background Topic compaction failed for ${sessionId}:`, error);
+          });
+        }
+      }
+      const topics = topicView ?? entry.topics;
+      const compressedTokens = sumTopicTokens2(topics);
+      if (compressedTokens + entry.totalTokens > usageLimits.usableContextTokens) {
+        throw new Error(`Unable to fit session ${sessionId} into the requested model context`);
+      }
+      return {
+        sessionId,
+        compressedContext: this.sessionCache.buildCompressedContext(sessionId, topics),
+        recentMessages: entry.messages.map(toMemoryRawMessage),
+        usage: {
+          ...usageLimits,
+          compressedTokens,
+          rawTokens: entry.totalTokens
+        }
+      };
+    } finally {
+      if (blockingReason) {
+        this.notifyBlockingCompression(options, {
+          sessionId,
+          phase: "end",
+          reason: blockingReason
+        });
+      }
+    }
   }
-  getHistoryWindow(sessionId) {
-    return this.sessionCache.getHistoryWindow(sessionId);
+  compactTopicsForBudget(sessionId, effectiveLimit) {
+    const key = `${sessionId}:${effectiveLimit}`;
+    const existing = this.topicCompactions.get(key);
+    if (existing) return existing;
+    const task = (async () => {
+      let entry = this.sessionCache.getEntry(sessionId);
+      if (!entry) return;
+      if (entry.topicTokens > this.config.compressedContextTokenLimit) {
+        await this.compressManager.triggerTopicCompaction(
+          sessionId,
+          this.config.compressedContextTokenLimit,
+          true
+        );
+        entry = this.sessionCache.getEntry(sessionId);
+      }
+      if (entry && entry.topicTokens > effectiveLimit && !this.sessionCache.getTopicView(sessionId, effectiveLimit)) {
+        await this.compressManager.triggerTopicCompaction(sessionId, effectiveLimit, false);
+      }
+    })();
+    this.topicCompactions.set(key, task);
+    const clear = () => {
+      if (this.topicCompactions.get(key) === task) this.topicCompactions.delete(key);
+    };
+    void task.then(clear, clear);
+    return task;
+  }
+  notifyBlockingCompression(options, event) {
+    const callback = options?.onBlockingCompression;
+    if (!callback) return;
+    try {
+      const returned = callback(event);
+      if (returned && typeof returned.then === "function") {
+        void Promise.resolve(returned).catch((error) => {
+          console.warn("[MemoryManager] onBlockingCompression callback rejected:", error);
+        });
+      }
+    } catch (error) {
+      console.warn("[MemoryManager] onBlockingCompression callback failed:", error);
+    }
+  }
+  calculateWindowUsage(modelContextTokens) {
+    return calculateContextBudget(this.config, modelContextTokens);
   }
   buildScopeFilter(scope, scopeId) {
     if (scope === "session" && scopeId) return [eq("session_id", scopeId)];
@@ -2946,6 +3672,7 @@ var MemoryManager = class {
   async deleteSession(sessionId) {
     if (!this.sessionMap.has(sessionId)) return false;
     this.sessionMap.delete(sessionId);
+    this.sessionCache.delete(sessionId);
     await this.store.deleteSession(sessionId);
     await this.store.deleteMessagesBySession(sessionId).catch((err) => {
       console.error(`[MemoryManager] Failed to delete messages for session ${sessionId}:`, err);
@@ -3020,8 +3747,8 @@ var MemoryManager = class {
     return this.factCache.all().find((f) => f.chatId === chatId)?.userId;
   }
   /** 手动新增一条事实 */
-  async addFact(content, level, userId, chatId, sessionId) {
-    await this.factCache.add(content, level, userId, chatId, sessionId);
+  async addFact(content, level, userId, chatId, sessionId, key) {
+    await this.factCache.add(content, level, userId, chatId, sessionId, key);
   }
   /** 删除单条事实，返回是否命中 */
   async deleteFact(factId) {
@@ -3060,20 +3787,81 @@ var MemoryManager = class {
     return page ? this.knowledgeManager.listDocuments(filter, page) : this.knowledgeManager.listDocuments(filter);
   }
   destroy() {
+    if (this.destroyTask) return this.destroyTask;
     if (this.optimizeTimer) {
       clearInterval(this.optimizeTimer);
       this.optimizeTimer = void 0;
     }
-    this.grafeo.close();
-    void this.store.close().catch(() => {
+    if (this.sessionSweepTimer) {
+      clearInterval(this.sessionSweepTimer);
+      this.sessionSweepTimer = void 0;
+    }
+    const writes = [
+      ...this.pendingWrites.values(),
+      ...this.hydration.values(),
+      ...this.topicCompactions.values()
+    ];
+    this.destroyTask = Promise.all(writes).catch(() => {
+    }).then(() => this.compressManager.waitForAllIdle()).catch(() => {
+    }).then(() => this.optimizeTask).catch(() => {
+    }).then(async () => {
+      this.grafeo.close();
+      await this.store.close().catch(() => {
+      });
     });
+    return this.destroyTask;
   }
 };
+function toMemoryRawMessage(message) {
+  const parts = safeParseArray(message.parts);
+  const payload = message.payload === void 0 ? void 0 : safeParseValue(message.payload);
+  return {
+    messageId: message.messageId,
+    talkerId: message.talkerId,
+    chatId: message.chatId,
+    userId: message.userId,
+    sessionId: message.sessionId,
+    type: message.type,
+    content: message.content,
+    ...parts.length > 0 && { parts },
+    ...payload !== void 0 && { payload },
+    usage: message.usage,
+    metadata: safeParseObject2(message.metadata),
+    createdAt: message.createdAt
+  };
+}
+function sumTopicTokens2(topics) {
+  return topics.reduce((sum, topic) => sum + Math.max(1, topic.tokens), 0);
+}
+function safeParseArray(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed) ? parsed : [];
+  } catch {
+    return [];
+  }
+}
+function safeParseObject2(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return parsed != null && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+function safeParseValue(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
 export {
   DEFAULT_NODE_TYPES,
   DEFAULT_RELATION_TYPES,
   KIND_CONVERSATION,
   KIND_KNOWLEDGE,
   MemoryManager,
-  MemoryStore
+  MemoryStore,
+  calculateContextBudget
 };