@ppagent/memory 0.1.4 → 0.4.0

package/dist/index.js

@@ -2,6 +2,7 @@
 import { v4 as uuidv44 } from "uuid";
 
 // src/config.ts
+import * as path from "node:path";
 function resolveConfig(config) {
   let embeddingBaseUrl = config.embeddingBaseUrl;
   let embeddingApiKey = config.embeddingApiKey;
@@ -15,16 +16,46 @@ 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,
     embeddingApiKey,
+    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,
+    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,
@@ -52,6 +83,18 @@ 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);
+}
 
 // src/constants.ts
 var DEFAULT_NODE_TYPES = [
@@ -711,120 +754,155 @@ var GrafeoService = class _GrafeoService {
   }
 };
 
-// src/db/lance.service.ts
-import * as lancedb from "@lancedb/lancedb";
-import { Field, FixedSizeList, Float32, Int32, Int64, Schema, Utf8 } from "apache-arrow";
-
-// src/db/sql.util.ts
-function escLance(value) {
-  return String(value).replace(/'/g, "''");
-}
-function eqFilter(field, value) {
-  return `${field} = '${escLance(value)}'`;
+// src/db/store.types.ts
+function eq(field, value) {
+  return { op: "eq", field, value };
 }
 
-// src/db/lance.service.ts
+// src/db/memory.store.ts
 var MESSAGES_TABLE = "messages";
 var TOPICS_TABLE = "topics";
 var FACTS_TABLE = "facts";
 var SESSIONS_TABLE = "sessions";
 var DOCUMENTS_TABLE = "documents";
 var CHUNKS_TABLE = "chunks";
-function messagesSchema(dim) {
-  return new Schema([
-    new Field("message_id", new Utf8(), false),
-    new Field("talker_id", new Utf8(), false),
-    new Field("chat_id", new Utf8(), false),
-    new Field("user_id", new Utf8(), false),
-    new Field("session_id", new Utf8(), false),
-    new Field("type", new Utf8(), false),
-    new Field("content", new Utf8(), false),
-    new Field("parts", new Utf8(), true),
-    // nullable，兼容存量数据
-    new Field("vector", new FixedSizeList(dim, new Field("item", new Float32(), false)), false),
-    new Field("usage", new Int32(), false),
-    new Field("metadata", new Utf8(), false),
-    new Field("created_at", new Int64(), false)
-  ]);
-}
-function topicsSchema(dim) {
-  return new Schema([
-    new Field("summary_id", new Utf8(), false),
-    new Field("session_id", new Utf8(), false),
-    new Field("user_id", new Utf8(), false),
-    new Field("chat_id", new Utf8(), false),
-    new Field("title", new Utf8(), true),
-    // nullable，兼容存量数据
-    new Field("detail", new Utf8(), false),
-    new Field("summary", new Utf8(), false),
-    new Field("concise", new Utf8(), false),
-    new Field("vector", new FixedSizeList(dim, new Field("item", new Float32(), false)), false),
-    new Field("start_time", new Int64(), false),
-    new Field("end_time", new Int64(), false),
-    new Field("created_at", new Int64(), false),
-    new Field("updated_at", new Int64(), false),
-    new Field("recall_count", new Int32(), false)
-  ]);
-}
-function factsSchema() {
-  return new Schema([
-    new Field("fact_id", new Utf8(), false),
-    new Field("level", new Utf8(), false),
-    new Field("chat_id", new Utf8(), false),
-    new Field("session_id", new Utf8(), false),
-    new Field("user_id", new Utf8(), false),
-    new Field("content", new Utf8(), false),
-    new Field("created_at", new Int64(), false)
-  ]);
-}
-function sessionsSchema() {
-  return new Schema([
-    new Field("session_id", new Utf8(), false),
-    new Field("chat_id", new Utf8(), false),
-    new Field("user_id", new Utf8(), false),
-    new Field("title", new Utf8(), false),
-    new Field("metadata", new Utf8(), false),
-    new Field("created_at", new Int64(), false),
-    new Field("updated_at", new Int64(), false)
-  ]);
-}
-function documentsSchema(dim) {
-  return new Schema([
-    new Field("doc_id", new Utf8(), false),
-    new Field("user_id", new Utf8(), false),
-    new Field("chat_id", new Utf8(), false),
-    new Field("session_id", new Utf8(), false),
-    new Field("title", new Utf8(), false),
-    new Field("source_name", new Utf8(), false),
-    new Field("full_content", new Utf8(), false),
-    new Field("content_hash", new Utf8(), false),
-    new Field("summary", new Utf8(), false),
-    // vector 列存储文档摘要向量（summaryVector），用于文档级粗召回
-    new Field("vector", new FixedSizeList(dim, new Field("item", new Float32(), false)), false),
-    new Field("chunk_count", new Int32(), false),
-    new Field("has_graph", new Int32(), false),
-    // 0/1 充当布尔
-    new Field("metadata", new Utf8(), false),
-    new Field("created_at", new Int64(), false),
-    new Field("updated_at", new Int64(), false)
-  ]);
+var RRF_K = 60;
+var HYBRID_OVERFETCH = 2;
+function tableDefs(dim) {
+  return [
+    {
+      name: MESSAGES_TABLE,
+      vectorDimension: dim,
+      columns: [
+        { name: "message_id", type: "text" },
+        { name: "talker_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "user_id", type: "text" },
+        { name: "session_id", type: "text" },
+        { name: "type", type: "text" },
+        { 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" },
+        { name: "created_at", type: "long" }
+      ],
+      indexes: [
+        { column: "message_id", kind: "scalar" },
+        { column: "session_id", kind: "scalar" },
+        { column: "content", kind: "fts" },
+        { column: "metadata", kind: "fts" }
+      ]
+    },
+    {
+      name: TOPICS_TABLE,
+      vectorDimension: dim,
+      columns: [
+        { name: "summary_id", type: "text" },
+        { name: "session_id", type: "text" },
+        { name: "user_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "title", type: "text", nullable: true },
+        // 兼容存量数据
+        { name: "detail", type: "text", nullable: true },
+        { name: "summary", 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" },
+        { name: "created_at", type: "long" },
+        { name: "updated_at", type: "long" },
+        { name: "recall_count", type: "int" }
+      ],
+      indexes: [
+        { column: "chat_id", kind: "scalar" },
+        { column: "summary", kind: "fts" }
+      ]
+    },
+    {
+      name: FACTS_TABLE,
+      columns: [
+        { name: "fact_id", type: "text" },
+        { name: "level", type: "text" },
+        { 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: "updated_at", type: "long", nullable: true }
+      ],
+      indexes: []
+    },
+    {
+      name: SESSIONS_TABLE,
+      columns: [
+        { name: "session_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "user_id", type: "text" },
+        { name: "title", type: "text" },
+        { name: "metadata", type: "text" },
+        { name: "created_at", type: "long" },
+        { name: "updated_at", type: "long" }
+      ],
+      indexes: [{ column: "session_id", kind: "scalar" }]
+    },
+    {
+      name: DOCUMENTS_TABLE,
+      vectorDimension: dim,
+      columns: [
+        { name: "doc_id", type: "text" },
+        { name: "user_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "session_id", type: "text" },
+        { name: "title", type: "text" },
+        { name: "source_name", type: "text" },
+        { name: "full_content", type: "text" },
+        { name: "content_hash", type: "text" },
+        { name: "summary", type: "text" },
+        // vector 列存储文档摘要向量（summaryVector），用于文档级粗召回
+        { name: "vector", type: "vector" },
+        { name: "chunk_count", type: "int" },
+        { name: "has_graph", type: "int" },
+        // 0/1 充当布尔
+        { name: "metadata", type: "text" },
+        { name: "created_at", type: "long" },
+        { name: "updated_at", type: "long" }
+      ],
+      indexes: [{ column: "doc_id", kind: "scalar" }]
+    },
+    {
+      name: CHUNKS_TABLE,
+      vectorDimension: dim,
+      columns: [
+        { name: "chunk_id", type: "text" },
+        { name: "doc_id", type: "text" },
+        // user_id/chat_id/session_id：chunkRedundantIds=false 时存空串，仅经 documents join 过滤
+        { name: "user_id", type: "text" },
+        { name: "chat_id", type: "text" },
+        { name: "session_id", type: "text" },
+        { name: "content", type: "text" },
+        { name: "vector", type: "vector" },
+        { name: "heading_path", type: "text" },
+        { name: "ordinal", type: "int" },
+        { name: "tokens", type: "int" },
+        { name: "metadata", type: "text" },
+        { name: "created_at", type: "long" }
+      ],
+      indexes: [
+        { column: "doc_id", kind: "scalar" },
+        { column: "content", kind: "fts" }
+      ]
+    }
+  ];
 }
-function chunksSchema(dim) {
-  return new Schema([
-    new Field("chunk_id", new Utf8(), false),
-    new Field("doc_id", new Utf8(), false),
-    // user_id/chat_id/session_id：chunkRedundantIds=false 时存空串，仅经 documents join 过滤
-    new Field("user_id", new Utf8(), false),
-    new Field("chat_id", new Utf8(), false),
-    new Field("session_id", new Utf8(), false),
-    new Field("content", new Utf8(), false),
-    new Field("vector", new FixedSizeList(dim, new Field("item", new Float32(), false)), false),
-    new Field("heading_path", new Utf8(), false),
-    new Field("ordinal", new Int32(), false),
-    new Field("tokens", new Int32(), false),
-    new Field("metadata", new Utf8(), false),
-    new Field("created_at", new Int64(), false)
-  ]);
+function toVector(v) {
+  return Array.isArray(v) ? v : Array.from(v);
 }
 function messageToRow(m) {
   return {
@@ -836,6 +914,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,
@@ -853,8 +932,9 @@ function rowToMessage(r) {
     content: r.content,
     parts: r.parts ?? "[]",
     // 旧数据无此列时安全降级
-    vector: Array.from(r.vector),
-    usage: Number(r.usage),
+    payload: r.payload ?? void 0,
+    vector: toVector(r.vector),
+    usage: positiveNumber(r.usage),
     metadata: r.metadata,
     createdAt: Number(r.created_at)
   };
@@ -866,9 +946,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,
@@ -884,10 +968,13 @@ function rowToTopic(r) {
     userId: r.user_id,
     chatId: r.chat_id,
     title: r.title ?? "",
-    detail: r.detail,
-    summary: r.summary,
-    concise: r.concise,
-    vector: Array.from(r.vector),
+    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),
     createdAt: Number(r.created_at),
@@ -902,8 +989,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) {
@@ -913,8 +1002,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) {
@@ -969,7 +1060,7 @@ function rowToDocument(r) {
     fullContent: r.full_content,
     contentHash: r.content_hash,
     summary: r.summary,
-    summaryVector: Array.from(r.vector),
+    summaryVector: toVector(r.vector),
     chunkCount: Number(r.chunk_count),
     hasGraph: Number(r.has_graph) === 1,
     metadata: safeParseObject(r.metadata),
@@ -1001,7 +1092,7 @@ function rowToChunk(r) {
     chatId: r.chat_id,
     sessionId: r.session_id,
     content: r.content,
-    vector: Array.from(r.vector),
+    vector: toVector(r.vector),
     headingPath: r.heading_path,
     ordinal: Number(r.ordinal),
     tokens: Number(r.tokens),
@@ -1016,215 +1107,312 @@ 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 {
+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) {
+    list.forEach((row, idx) => {
+      const id = keyOf(row);
+      const inc = 1 / (RRF_K + idx + 1);
+      const entry = acc.get(id);
+      if (entry) entry.score += inc;
+      else acc.set(id, { row, score: inc });
+    });
+  }
+  return [...acc.values()].sort((a, b) => b.score - a.score).map((e) => e.row);
+}
+var MemoryStore = class {
   config;
-  conn;
-  messagesTable;
-  topicsTable;
-  factsTable;
-  sessionsTable;
-  documentsTable;
-  chunksTable;
-  // 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;
-  constructor(config) {
+  provider;
+  providerOverride;
+  /** provider 省略时在 init() 阶段经 provider.resolver 自动探测创建（测试可显式注入） */
+  constructor(config, provider) {
     this.config = config;
+    this.providerOverride = provider;
+  }
+  /** 当前后端 provider 标识（日志/诊断用） */
+  get providerKind() {
+    return this.provider?.kind ?? "uninitialized";
   }
   async init() {
-    this.conn = await lancedb.connect(this.config.lancedbPath);
-    const dim = this.config.embeddingDimension;
-    const existingTables = await this.conn.tableNames();
-    if (existingTables.includes(MESSAGES_TABLE)) {
-      this.messagesTable = await this.conn.openTable(MESSAGES_TABLE);
-      await this._ensurePartsColumn();
+    if (this.providerOverride) {
+      this.provider = this.providerOverride;
     } else {
-      this.messagesTable = await this.conn.createEmptyTable(
-        MESSAGES_TABLE,
-        messagesSchema(dim)
-      );
-      this.isNewMessagesTable = true;
+      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}`);
     }
-    if (existingTables.includes(TOPICS_TABLE)) {
-      this.topicsTable = await this.conn.openTable(TOPICS_TABLE);
-      await this._ensureTopicTitleColumn();
-    } else {
-      this.topicsTable = await this.conn.createEmptyTable(
-        TOPICS_TABLE,
-        topicsSchema(dim)
-      );
-      this.isNewTopicsTable = true;
-    }
-    if (existingTables.includes(FACTS_TABLE)) {
-      this.factsTable = await this.conn.openTable(FACTS_TABLE);
-    } else {
-      this.factsTable = await this.conn.createEmptyTable(FACTS_TABLE, factsSchema());
-    }
-    if (existingTables.includes(SESSIONS_TABLE)) {
-      this.sessionsTable = await this.conn.openTable(SESSIONS_TABLE);
-    } 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);
-    } 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);
-    } else {
-      this.chunksTable = await this.conn.createEmptyTable(CHUNKS_TABLE, chunksSchema(dim));
-      this.isNewChunksTable = true;
-    }
-    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);
+    await this.provider.init(tableDefs(this.config.embeddingDimension));
   }
-  /**
-   * 按需补齐索引：先经 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,
-          fts ? { config: lancedb.Index.fts(), replace: false } : { replace: false }
-        );
-      } catch {
-      }
-    }
+  async close() {
+    await this.provider.close();
   }
   /**
-   * 存储压实：逐表执行碎片合并 + 清理 retentionMs 之前的历史版本。
-   * 嵌入式场景下 LanceDB 不会自动做这件事，长期运行后版本/碎片无限累积会显著拖慢启动与查询。
+   * 存储压实（碎片合并 + 历史版本清理）。
+   * LanceDB 后端长期运行必须定期执行；SQLite 后端为可选的空间回收。
    */
   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)
+    return this.provider.optimize(retentionMs);
+  }
+  // ── messages ───────────────────────────────────────────────────────────────
+  async addMessages(messages) {
+    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 }
+          ]
         });
-      } catch (err) {
-        console.warn(`[LanceService] optimize table "${name}" failed:`, err);
+        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, {
+        filter: [eq("session_id", sessionId), { op: "gt", field: "created_at", value: since }],
+        limit
+      });
+      return rows.sort((a, b) => Number(a.created_at) - Number(b.created_at)).map(rowToMessage);
+    } catch {
+      return [];
     }
-    return results;
   }
-  /**
-   * 为存量 messages 表添加 parts 列（如果缺失）。
-   * LanceDB 0.14+ 支持 addColumns；旧版本会 throw，此时 rowToMessage 的 ?? "[]" 兜底。
-   */
-  async _ensurePartsColumn() {
+  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 {
-      const schema = await this.messagesTable.schema();
-      const hasPartsCol = schema.fields?.some(
-        (f) => f.name === "parts"
-      );
-      if (!hasPartsCol) {
-        await this.messagesTable.addColumns([
-          { name: "parts", valueSql: "CAST(NULL AS STRING)" }
-        ]);
-      }
+      const rows = await this.provider.query(MESSAGES_TABLE, {
+        filter: [eq("session_id", sessionId)],
+        orderBy: [
+          { column: "created_at", ascending: false },
+          { column: "message_id", ascending: false }
+        ],
+        limit
+      });
+      return rows.reverse().map(rowToMessage);
     } catch {
+      return [];
     }
   }
-  /**
-   * 为存量 topics 表添加 title 列（如果缺失）。
-   * 旧版本不支持 addColumns 时忽略，读取时 rowToTopic 的 ?? "" 兜底。
-   */
-  async _ensureTopicTitleColumn() {
+  /** 取某会话的全部消息（按 createdAt 升序），供管理面板分页切片使用 */
+  async getAllMessagesBySession(sessionId) {
     try {
-      const schema = await this.topicsTable.schema();
-      const hasTitleCol = schema.fields?.some(
-        (f) => f.name === "title"
-      );
-      if (!hasTitleCol) {
-        await this.topicsTable.addColumns([
-          { name: "title", valueSql: "CAST(NULL AS STRING)" }
-        ]);
-      }
+      const rows = await this.provider.query(MESSAGES_TABLE, {
+        filter: [eq("session_id", sessionId)]
+      });
+      return rows.sort(
+        (a, b) => Number(a.created_at) - Number(b.created_at) || cmpStr(a.message_id, b.message_id)
+      ).map(rowToMessage);
     } catch {
+      return [];
     }
   }
-  async addMessages(messages) {
-    if (messages.length === 0) return;
-    await this.messagesTable.add(messages.map(messageToRow));
-    if (this.isNewMessagesTable) {
-      await this.ensureIndexes(this.messagesTable, MESSAGES_INDEXES);
-      this.isNewMessagesTable = false;
+  async searchMessages(vector, filter, limit = 10) {
+    const rows = await this.provider.vectorSearch(MESSAGES_TABLE, vector, { filter, limit });
+    return rows.map((r) => ({ ...rowToMessage(r), _distance: r._distance }));
+  }
+  // 对 messages 表执行混合搜索（BM25 + 向量），用于 topics 搜索无结果时的回退
+  async hybridSearchMessages(query, vector, filter, limit = 10) {
+    const fused = await this.hybridSearch(
+      MESSAGES_TABLE,
+      ["content", "metadata"],
+      query,
+      vector,
+      filter,
+      limit
+    );
+    return fused.slice(0, limit).map(rowToMessage);
+  }
+  async hybridSearchTopics(query, vector, filter, limit = 10) {
+    try {
+      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) => ({
+          row: r,
+          score: total - idx + Math.log1p(Number(r.recall_count))
+        })).sort((a, b) => b.score - a.score).map((x) => rowToTopic(x.row));
+      }
+      return [];
+    } catch {
+      return [];
     }
   }
+  /**
+   * 通用混合检索：FTS（BM25）与向量两路各取 limit*HYBRID_OVERFETCH 候选，RRF 融合。
+   * FTS 不可用（后端不支持或查询失败）时降级为纯向量。返回融合后的完整候选序列（未截断）。
+   */
+  async hybridSearch(table, ftsColumns, query, vector, filter, limit) {
+    const fetchN = limit * HYBRID_OVERFETCH;
+    const supportsFts = this.provider.capabilities().fts;
+    const [ftsRows, vecRows] = await Promise.all([
+      supportsFts ? this.provider.ftsSearch(table, query, { columns: ftsColumns, filter, limit: fetchN }).catch(() => []) : Promise.resolve([]),
+      this.provider.vectorSearch(table, vector, { filter, limit: fetchN }).catch(() => [])
+    ]);
+    const keyColumn = this.keyColumnOf(table);
+    return rrfFuse([ftsRows, vecRows], (r) => String(r[keyColumn]));
+  }
+  keyColumnOf(table) {
+    switch (table) {
+      case MESSAGES_TABLE:
+        return "message_id";
+      case TOPICS_TABLE:
+        return "summary_id";
+      case DOCUMENTS_TABLE:
+        return "doc_id";
+      case CHUNKS_TABLE:
+        return "chunk_id";
+      case SESSIONS_TABLE:
+        return "session_id";
+      case FACTS_TABLE:
+        return "fact_id";
+      default:
+        throw new Error(`Unknown table: ${table}`);
+    }
+  }
+  // ── topics ─────────────────────────────────────────────────────────────────
   async addTopic(topic) {
-    await this.topicsTable.add([topicToRow(topic)]);
-    if (this.isNewTopicsTable) {
-      await this.ensureIndexes(this.topicsTable, TOPICS_INDEXES);
-      this.isNewTopicsTable = false;
-    }
+    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.topicsTable.update({
-      values: { recall_count: count, updated_at: Date.now() },
-      where: eqFilter("summary_id", summaryId)
-    });
+    await this.provider.update(
+      TOPICS_TABLE,
+      { recall_count: count, updated_at: Date.now() },
+      [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 = `${eqFilter("chat_id", chatId)} AND ${eqFilter("user_id", userId)}`;
+    const filter = [eq("chat_id", chatId), eq("user_id", userId)];
     const recallBoostMs = this.config.recallBoostMs;
     const fetchTopics = async (count) => {
       if (count <= 0) return [];
       try {
-        const rows = await this.topicsTable.query().where(filter).limit(count * 5).toArray();
+        const rows = await this.provider.query(TOPICS_TABLE, {
+          filter,
+          limit: count * 5
+        });
         return rows.sort((a, b) => {
           const scoreA = Number(a.end_time) + Number(a.recall_count) * recallBoostMs;
           const scoreB = Number(b.end_time) + Number(b.recall_count) * recallBoostMs;
@@ -1241,167 +1429,94 @@ var LanceService = class {
       concise: allTopics.slice(n1 + n2, n1 + n2 + n3)
     };
   }
-  async getMessagesSince(sessionId, since, limit) {
-    try {
-      const q = this.messagesTable.query().where(`${eqFilter("session_id", sessionId)} AND created_at > ${since}`);
-      if (limit) q.limit(limit);
-      const rows = await q.toArray();
-      return rows.sort((a, b) => Number(a.created_at) - Number(b.created_at)).map(rowToMessage);
-    } catch {
-      return [];
-    }
-  }
-  async getLatestMessages(sessionId, limit) {
-    if (limit <= 0) return [];
-    try {
-      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 [];
-    }
-  }
-  /** 取某会话的全部消息（按 createdAt 升序），供管理面板分页切片使用 */
-  async getAllMessagesBySession(sessionId) {
+  /** 全量读取 topics（管理面板列表用，不做 recall 加权排序，按 endTime 倒序）*/
+  async getAllTopics() {
     try {
-      const rows = await this.messagesTable.query().where(eqFilter("session_id", sessionId)).toArray();
-      return rows.sort((a, b) => Number(a.created_at) - Number(b.created_at) || cmpStr(a.message_id, b.message_id)).map(rowToMessage);
+      const rows = await this.provider.query(TOPICS_TABLE);
+      return rows.sort(
+        (a, b) => Number(b.end_time) - Number(a.end_time) || cmpStr(a.summary_id, b.summary_id)
+      ).map(rowToTopic);
     } catch {
       return [];
     }
   }
-  async searchMessages(vector, filter, limit = 10) {
-    const q = this.messagesTable.vectorSearch(vector).limit(limit);
-    if (filter) q.where(filter);
-    const rows = await q.toArray();
-    return rows.map((r) => ({
-      ...rowToMessage(r),
-      _distance: r._distance
-    }));
-  }
-  // 对 messages 表执行混合搜索（BM25 + 向量），用于 topics 搜索无结果时的回退
-  async hybridSearchMessages(query, vector, filter, limit = 10) {
-    try {
-      const q = this.messagesTable.query().fullTextSearch(query).nearestTo(vector).limit(limit);
-      if (filter) q.where(filter);
-      const rows = await q.toArray();
-      return rows.map(rowToMessage);
-    } catch {
-      const rows = await this.searchMessages(vector, filter, limit);
-      return rows.map(({ _distance: _d, ...r }) => r);
-    }
+  async deleteTopicsBySession(sessionId) {
+    await this.provider.deleteWhere(TOPICS_TABLE, [eq("session_id", sessionId)]);
   }
-  async hybridSearchTopics(query, vector, filter, limit = 10) {
-    const recallBoostMs = this.config.recallBoostMs;
-    try {
-      const q = this.topicsTable.query().fullTextSearch(query).nearestTo(vector).limit(limit);
-      if (filter) q.where(filter);
-      const rows = await q.toArray();
-      if (rows.length > 0) {
-        const total = rows.length;
-        return rows.map((r, idx) => ({
-          row: r,
-          score: total - idx + Math.log1p(Number(r.recall_count))
-        })).sort((a, b) => b.score - a.score).map((x) => rowToTopic(x.row));
-      }
-    } catch {
-    }
-    const msgRows = await this.hybridSearchMessages(query, vector, filter, limit);
-    return msgRows.map((r) => ({
-      summaryId: r.messageId,
-      sessionId: r.sessionId,
-      userId: r.userId,
-      chatId: r.chatId,
-      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
-    }));
+  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.factsTable.add([factToRow(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.factsTable.query().toArray();
+      const rows = await this.provider.query(FACTS_TABLE);
       return rows.map(rowToFact);
     } catch {
       return [];
     }
   }
+  /** 删除单条 fact */
+  async deleteFact(factId) {
+    await this.provider.deleteWhere(FACTS_TABLE, [eq("fact_id", factId)]);
+  }
+  // ── sessions ───────────────────────────────────────────────────────────────
   async getAllSessionIds() {
     try {
-      const rows = await this.messagesTable.query().select(["session_id"]).limit(1e4).toArray();
+      const rows = await this.provider.query(MESSAGES_TABLE, {
+        select: ["session_id"],
+        limit: 1e4
+      });
       return [...new Set(rows.map((r) => r.session_id))];
     } catch {
       return [];
     }
   }
   async insertSession(session) {
-    await this.sessionsTable.add([sessionToRow(session)]);
-    if (this.isNewSessionsTable) {
-      await this.ensureIndexes(this.sessionsTable, SESSIONS_INDEXES);
-      this.isNewSessionsTable = false;
-    }
+    await this.provider.add(SESSIONS_TABLE, [sessionToRow(session)]);
   }
   async upsertSession(session) {
-    await this.sessionsTable.delete(eqFilter("session_id", session.sessionId));
-    await this.sessionsTable.add([sessionToRow(session)]);
+    await this.provider.deleteWhere(SESSIONS_TABLE, [eq("session_id", session.sessionId)]);
+    await this.provider.add(SESSIONS_TABLE, [sessionToRow(session)]);
   }
   async getAllSessions() {
     try {
-      const rows = await this.sessionsTable.query().toArray();
+      const rows = await this.provider.query(SESSIONS_TABLE);
       return rows.map(rowToSession);
     } catch {
       return [];
     }
   }
   async deleteSession(sessionId) {
-    await this.sessionsTable.delete(eqFilter("session_id", sessionId));
-  }
-  // ── 管理面板用：全量读取 / 删除 / 计数 ──────────────────────────────────────────────
-  /** 全量读取 topics（管理面板列表用，不做 recall 加权排序，按 endTime 倒序）*/
-  async getAllTopics() {
-    try {
-      const rows = await this.topicsTable.query().toArray();
-      return rows.sort((a, b) => Number(b.end_time) - Number(a.end_time) || cmpStr(a.summary_id, b.summary_id)).map(rowToTopic);
-    } catch {
-      return [];
-    }
-  }
-  /** 删除单条 fact */
-  async deleteFact(factId) {
-    await this.factsTable.delete(eqFilter("fact_id", factId));
+    await this.provider.deleteWhere(SESSIONS_TABLE, [eq("session_id", sessionId)]);
   }
   /** 删除某会话下的全部消息（级联删除会话时使用）*/
   async deleteMessagesBySession(sessionId) {
-    await this.messagesTable.delete(eqFilter("session_id", sessionId));
-  }
-  /** 删除某会话下的全部 topics（级联删除会话时使用）*/
-  async deleteTopicsBySession(sessionId) {
-    await this.topicsTable.delete(eqFilter("session_id", sessionId));
+    await this.provider.deleteWhere(MESSAGES_TABLE, [eq("session_id", sessionId)]);
   }
+  // ── 统计 ───────────────────────────────────────────────────────────────────
   /** 各表行数统计（概览卡片用）*/
   async countAll() {
     const safeCount = async (table) => {
       try {
-        return await table.countRows();
+        return await this.provider.count(table);
       } catch {
         return 0;
       }
     };
     const [sessions, messages, topics, facts] = await Promise.all([
-      safeCount(this.sessionsTable),
-      safeCount(this.messagesTable),
-      safeCount(this.topicsTable),
-      safeCount(this.factsTable)
+      safeCount(SESSIONS_TABLE),
+      safeCount(MESSAGES_TABLE),
+      safeCount(TOPICS_TABLE),
+      safeCount(FACTS_TABLE)
     ]);
     return { sessions, messages, topics, facts };
   }
@@ -1422,16 +1537,20 @@ var LanceService = class {
     };
     const readCreatedAt = async (table) => {
       try {
-        const rows = await table.query().select(["created_at"]).where(`created_at >= ${startMs}`).limit(1e6).toArray();
+        const rows = await this.provider.query(table, {
+          select: ["created_at"],
+          filter: [{ op: "gte", field: "created_at", value: startMs }],
+          limit: 1e6
+        });
         return rows.map((r) => Number(r.created_at)).filter((n) => Number.isFinite(n));
       } catch {
         return [];
       }
     };
     const [sessionTs, messageTs, factTs] = await Promise.all([
-      readCreatedAt(this.sessionsTable),
-      readCreatedAt(this.messagesTable),
-      readCreatedAt(this.factsTable)
+      readCreatedAt(SESSIONS_TABLE),
+      readCreatedAt(MESSAGES_TABLE),
+      readCreatedAt(FACTS_TABLE)
     ]);
     const buckets = /* @__PURE__ */ new Map();
     for (let i = 0; i < days; i++) {
@@ -1451,29 +1570,25 @@ var LanceService = class {
   }
   // ── 知识库：documents / chunks ─────────────────────────────────────────────
   async addDocument(doc) {
-    await this.documentsTable.add([documentToRow(doc)]);
-    if (this.isNewDocumentsTable) {
-      await this.ensureIndexes(this.documentsTable, DOCUMENTS_INDEXES);
-      this.isNewDocumentsTable = false;
-    }
+    await this.provider.add(DOCUMENTS_TABLE, [documentToRow(doc)]);
   }
   async addChunks(chunks) {
     if (chunks.length === 0) return;
-    await this.chunksTable.add(chunks.map(chunkToRow));
-    if (this.isNewChunksTable) {
-      await this.ensureIndexes(this.chunksTable, CHUNKS_INDEXES);
-      this.isNewChunksTable = false;
-    }
+    await this.provider.add(CHUNKS_TABLE, chunks.map(chunkToRow));
   }
   async updateDocumentGraphFlag(docId, hasGraph) {
-    await this.documentsTable.update({
-      values: { has_graph: hasGraph ? 1 : 0, updated_at: Date.now() },
-      where: eqFilter("doc_id", docId)
-    });
+    await this.provider.update(
+      DOCUMENTS_TABLE,
+      { has_graph: hasGraph ? 1 : 0, updated_at: Date.now() },
+      [eq("doc_id", docId)]
+    );
   }
   async getDocument(docId) {
     try {
-      const rows = await this.documentsTable.query().where(eqFilter("doc_id", docId)).limit(1).toArray();
+      const rows = await this.provider.query(DOCUMENTS_TABLE, {
+        filter: [eq("doc_id", docId)],
+        limit: 1
+      });
       if (rows.length === 0) return null;
       return rowToDocument(rows[0]);
     } catch {
@@ -1483,8 +1598,10 @@ var LanceService = class {
   /** 查找同域同 hash 的文档（去重用）*/
   async findDocumentByHash(contentHash, filter) {
     try {
-      const where = filter ? `${eqFilter("content_hash", contentHash)} AND ${filter}` : eqFilter("content_hash", contentHash);
-      const rows = await this.documentsTable.query().where(where).limit(1).toArray();
+      const rows = await this.provider.query(DOCUMENTS_TABLE, {
+        filter: [eq("content_hash", contentHash), ...filter ?? []],
+        limit: 1
+      });
       if (rows.length === 0) return null;
       return rowToDocument(rows[0]);
     } catch {
@@ -1494,9 +1611,11 @@ var LanceService = class {
   /** 按域过滤返回 docId 列表（chunkRedundantIds=false 时用于 chunk 过滤）*/
   async getDocIdsByDomain(filter) {
     try {
-      const q = this.documentsTable.query().select(["doc_id"]).limit(1e5);
-      if (filter) q.where(filter);
-      const rows = await q.toArray();
+      const rows = await this.provider.query(DOCUMENTS_TABLE, {
+        select: ["doc_id"],
+        filter,
+        limit: 1e5
+      });
       return [...new Set(rows.map((r) => r.doc_id))];
     } catch {
       return [];
@@ -1505,13 +1624,8 @@ var LanceService = class {
   /** 文档级粗召回：对摘要向量做向量搜索，定位候选文档 */
   async searchDocuments(vector, filter, limit = 5) {
     try {
-      const q = this.documentsTable.vectorSearch(vector).limit(limit);
-      if (filter) q.where(filter);
-      const rows = await q.toArray();
-      return rows.map((r) => ({
-        ...rowToDocument(r),
-        _distance: r._distance
-      }));
+      const rows = await this.provider.vectorSearch(DOCUMENTS_TABLE, vector, { filter, limit });
+      return rows.map((r) => ({ ...rowToDocument(r), _distance: r._distance }));
     } catch {
       return [];
     }
@@ -1519,32 +1633,30 @@ var LanceService = class {
   /** 知识片段混合检索（BM25 + 向量），失败回退纯向量 */
   async searchChunks(query, vector, filter, limit = 8) {
     try {
-      const q = this.chunksTable.query().fullTextSearch(query).nearestTo(vector).limit(limit);
-      if (filter) q.where(filter);
-      const rows = await q.toArray();
+      const fused = await this.hybridSearch(CHUNKS_TABLE, ["content"], query, vector, filter, limit);
+      if (fused.length > 0) return fused.slice(0, limit).map(rowToChunk);
+    } catch {
+    }
+    try {
+      const rows = await this.provider.vectorSearch(CHUNKS_TABLE, vector, { filter, limit });
       return rows.map(rowToChunk);
     } catch {
-      try {
-        const q = this.chunksTable.vectorSearch(vector).limit(limit);
-        if (filter) q.where(filter);
-        const rows = await q.toArray();
-        return rows.map(rowToChunk);
-      } catch {
-        return [];
-      }
+      return [];
     }
   }
   async deleteDocument(docId) {
-    await this.documentsTable.delete(eqFilter("doc_id", docId));
+    await this.provider.deleteWhere(DOCUMENTS_TABLE, [eq("doc_id", docId)]);
   }
   async deleteChunksByDoc(docId) {
-    await this.chunksTable.delete(eqFilter("doc_id", docId));
+    await this.provider.deleteWhere(CHUNKS_TABLE, [eq("doc_id", docId)]);
   }
   /** 全量读取文档（管理面板用），按更新时间倒序 */
   async getAllDocuments() {
     try {
-      const rows = await this.documentsTable.query().toArray();
-      return rows.sort((a, b) => Number(b.updated_at) - Number(a.updated_at) || cmpStr(a.doc_id, b.doc_id)).map(rowToDocument);
+      const rows = await this.provider.query(DOCUMENTS_TABLE);
+      return rows.sort(
+        (a, b) => Number(b.updated_at) - Number(a.updated_at) || cmpStr(a.doc_id, b.doc_id)
+      ).map(rowToDocument);
     } catch {
       return [];
     }
@@ -1553,68 +1665,33 @@ var LanceService = class {
   async countKnowledge() {
     const safeCount = async (table) => {
       try {
-        return await table.countRows();
+        return await this.provider.count(table);
       } catch {
         return 0;
       }
     };
     const [documents, chunks] = await Promise.all([
-      safeCount(this.documentsTable),
-      safeCount(this.chunksTable)
+      safeCount(DOCUMENTS_TABLE),
+      safeCount(CHUNKS_TABLE)
     ]);
     return { documents, chunks };
   }
   /**
-   * 根据 metadata 字段内容构建 SQL LIKE 过滤条件。
+   * 根据 metadata 字段内容构建结构化过滤条件。
    *
-   * metadata 以 JSON 字符串存储，此方法将键值对转换为 SQL LIKE 表达式，
+   * metadata 以 JSON 字符串存储，此方法将键值对转换为 jsonContains 条件，
    * 可直接传给 searchMessages / hybridSearchTopics 的 filter 参数。
    *
-   * 示例：buildMetadataFilter({ env: "prod", version: 2 })
-   *   → `metadata LIKE '%"env":"prod"%' AND metadata LIKE '%"version":2%'`
-   *
    * 注意：仅适合简单标量值（字符串、数字、布尔）的精确匹配。
    * 复杂嵌套对象或含空格的 JSON 值可能无法可靠匹配。
    */
   static buildMetadataFilter(conditions) {
-    return Object.entries(conditions).map(([key, value]) => {
-      const jsonValue = typeof value === "string" ? `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"` : String(value);
-      return `metadata LIKE '%"${key}":${jsonValue}%'`;
-    }).join(" AND ");
-  }
-};
-
-// 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++;
-    }
+    return Object.entries(conditions).map(([key, value]) => ({
+      op: "jsonContains",
+      field: "metadata",
+      key,
+      value
+    }));
   }
 };
 
@@ -1690,7 +1767,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,
@@ -1701,6 +1781,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}` },
@@ -1708,7 +1789,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) {
@@ -1731,27 +1815,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) {
+    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 ${this.config.topicSummaryMaxTokens} tokens\u3002\u53EA\u8F93\u51FA JSON\uFF1A{"title":"...","summary":"..."}`,
+      input,
+      true,
+      this.config.topicSummaryMaxTokens + 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) {
@@ -1794,9 +1906,8 @@ ${formatted}`
     ]);
     return {
       title: summary.title,
-      detail: summary.detail,
       summary: summary.summary,
-      concise: summary.concise,
+      tokens: summary.tokens,
       entities: extraction.entities,
       relations: extraction.relations
     };
@@ -1885,146 +1996,243 @@ ${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;
-  lance;
-  grafeo;
-  llm;
-  embed;
-  sessionCache;
-  semaphore;
-  sessionChain = /* @__PURE__ */ new Map();
-  constructor(config, lance, grafeo, llm, embed, sessionCache) {
+  constructor(config, store, grafeo, llm, embed, sessionCache) {
     this.config = config;
-    this.lance = lance;
+    this.store = store;
     this.grafeo = grafeo;
     this.llm = llm;
     this.embed = embed;
     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) {
+    const previous = this.sessionChain.get(sessionId) ?? Promise.resolve();
+    const next = previous.then(
+      () => this.semaphore.run(() => this.doCompress(sessionId, force, waitGraph, rawLimit))
     );
-    this.sessionChain.set(sessionId, next.catch(() => {
-    }));
+    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.lance.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.lance.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);
+    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) {
+    while (true) {
+      const entry = this.sessionCache.getEntry(sessionId);
+      if (!entry || entry.topicTokens <= this.config.compressedContextTokenLimit) return;
+      const target = Math.max(1, Math.floor(this.config.compressedContextTokenLimit / 2));
+      const selected = [];
+      let tokens = 0;
+      for (const topic of entry.topics) {
+        selected.push(topic);
+        tokens += topic.tokens;
+        if (tokens >= target && selected.length >= 2) break;
+      }
+      if (selected.length < 2) {
+        this.sessionCache.setTopics(sessionId, entry.topics, true);
+        return;
+      }
+      console.info(
+        `[CompressManager] session ${sessionId} compressed Topic context exceeds ${this.config.compressedContextTokenLimit} tokens; compacting ${selected.length} old topics.`
+      );
+      const result = await this.llm.summarizeTopics(selected);
+      const summary = result.summary.trim();
+      if (!summary) throw new Error(`LLM returned an empty Topic rollup for session ${sessionId}`);
+      const vector = 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: result.tokens != null && result.tokens > 0 ? result.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
+      };
+      const removedIds = selected.map((topic) => topic.summaryId);
+      await this.store.addTopic(rollup);
+      this.sessionCache.replaceTopics(sessionId, removedIds, rollup);
+      await this.store.deleteTopicsByIds(removedIds);
+    }
+  }
+  rawLimit(modelContextTokens = this.config.defaultModelContextTokens) {
+    const usable = Math.floor(modelContextTokens * this.config.contextUsageRatio);
+    return Math.max(1, usable - this.config.compressedContextTokenLimit);
+  }
   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 formatError(error) {
+  return error instanceof Error ? error.message : String(error);
 }
 function withTimeout(promise, timeoutMs, label) {
   let timer;
@@ -2037,13 +2245,13 @@ function withTimeout(promise, timeoutMs, label) {
 // src/manager/fact.cache.ts
 import { v4 as uuidv42 } from "uuid";
 var FactCache = class {
-  lance;
+  store;
   cache = /* @__PURE__ */ new Map();
-  constructor(lance) {
-    this.lance = lance;
+  constructor(store) {
+    this.store = store;
   }
   async init() {
-    const facts = await this.lance.getAllFacts();
+    const facts = await this.store.getAllFacts();
     for (const fact of facts) {
       const key = this.key(fact.level, fact.level === "user" ? fact.userId : fact.chatId);
       const existing = this.cache.get(key) ?? [];
@@ -2054,22 +2262,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.lance.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)) ?? [];
@@ -2078,7 +2294,7 @@ var FactCache = class {
   all() {
     return [...this.cache.values()].flat();
   }
-  /** 删除单条 fact：同步从 LanceDB 与内存缓存中移除。返回是否命中。*/
+  /** 删除单条 fact：同步从存储与内存缓存中移除。返回是否命中。*/
   async remove(factId) {
     let hit = false;
     for (const [k, facts] of this.cache) {
@@ -2091,13 +2307,15 @@ var FactCache = class {
         break;
       }
     }
-    await this.lance.deleteFact(factId);
+    await this.store.deleteFact(factId);
     return hit;
   }
   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");
   }
 };
 
@@ -2235,14 +2453,14 @@ function takeTailTokens(text, overlapTokens) {
 // src/manager/knowledge.manager.ts
 var KnowledgeManager = class {
   config;
-  lance;
+  store;
   grafeo;
   llm;
   embed;
   semaphore;
-  constructor(config, lance, grafeo, llm, embed) {
+  constructor(config, store, grafeo, llm, embed) {
     this.config = config;
-    this.lance = lance;
+    this.store = store;
     this.grafeo = grafeo;
     this.llm = llm;
     this.embed = embed;
@@ -2257,8 +2475,9 @@ var KnowledgeManager = class {
     const now = Date.now();
     const content = opts.content;
     const contentHash = createHash("sha256").update(content).digest("hex");
-    const domainFilter = `user_id = '${esc(userId)}' AND chat_id = '${esc(chatId)}' AND session_id = '${esc(sessionId)}'`;
-    const existing = await this.lance.findDocumentByHash(contentHash, domainFilter);
+    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, {
       maxTokens: this.config.chunkMaxTokens,
@@ -2291,7 +2510,7 @@ var KnowledgeManager = class {
       createdAt: now,
       updatedAt: now
     };
-    await this.lance.addDocument(doc);
+    await this.store.addDocument(doc);
     const chunkIngest = this.semaphore.run(() => this.ingestChunks(doc, pieces));
     const graphBuild = chunkIngest.then((chunks) => {
       if (!shouldBuildGraph) return;
@@ -2341,7 +2560,7 @@ ${p.content}` : p.content
       metadata: {},
       createdAt: doc.createdAt
     }));
-    await this.lance.addChunks(chunks);
+    await this.store.addChunks(chunks);
     return chunks;
   }
   async buildDocumentGraph(doc, chunks) {
@@ -2394,7 +2613,7 @@ ${p.content}` : p.content
       embeddings,
       KIND_KNOWLEDGE
     );
-    await this.lance.updateDocumentGraphFlag(doc.docId, true).catch((err) => {
+    await this.store.updateDocumentGraphFlag(doc.docId, true).catch((err) => {
       console.error(`[KnowledgeManager] Failed to update graph flag for doc ${doc.docId}:`, err);
     });
   }
@@ -2407,11 +2626,11 @@ ${p.content}` : p.content
     const mode = opts.mode ?? "auto";
     const limit = opts.limit ?? this.config.knowledgeTopK;
     const vector = await this.embed.embedOne(opts.query);
-    const docFilter = buildDomainSql(scope, scopeId);
+    const docFilter = buildDomainFilter(scope, scopeId);
     let candidateDocIds;
     const docTitleMap = /* @__PURE__ */ new Map();
     if (this.config.docCoarseTopK > 0) {
-      const coarse = await this.lance.searchDocuments(vector, docFilter, this.config.docCoarseTopK);
+      const coarse = await this.store.searchDocuments(vector, docFilter, this.config.docCoarseTopK);
       if (coarse.length > 0) {
         candidateDocIds = coarse.map((d) => d.docId);
         for (const d of coarse) docTitleMap.set(d.docId, d.title);
@@ -2419,7 +2638,7 @@ ${p.content}` : p.content
     }
     const chunkFilter = await this.buildChunkFilter(scope, scopeId, candidateDocIds);
     if (chunkFilter === NO_MATCH) return empty;
-    const rawChunks = await this.lance.searchChunks(opts.query, vector, chunkFilter, limit);
+    const rawChunks = await this.store.searchChunks(opts.query, vector, chunkFilter, limit);
     const scored = rawChunks.map((c) => ({
       chunkId: c.chunkId,
       docId: c.docId,
@@ -2433,7 +2652,7 @@ ${p.content}` : p.content
       [...docCount.entries()].map(async ([docId, matchedChunkCount]) => {
         let title = docTitleMap.get(docId);
         if (title === void 0) {
-          const d = await this.lance.getDocument(docId);
+          const d = await this.store.getDocument(docId);
           title = d?.title ?? "";
         }
         return { docId, title, matchedChunkCount };
@@ -2481,32 +2700,32 @@ ${p.content}` : p.content
   async buildChunkFilter(scope, scopeId, candidateDocIds) {
     const parts = [];
     if (this.config.chunkRedundantIds) {
-      const domainSql = buildDomainSql(scope, scopeId);
-      if (domainSql) parts.push(domainSql);
-      if (candidateDocIds) parts.push(inSql("doc_id", candidateDocIds));
+      const domain = buildDomainFilter(scope, scopeId);
+      if (domain) parts.push(...domain);
+      if (candidateDocIds) parts.push({ op: "in", field: "doc_id", values: candidateDocIds });
     } else {
       let docIds = candidateDocIds;
       if (scope !== "all") {
-        const domainSql = buildDomainSql(scope, scopeId);
-        const domainDocIds = await this.lance.getDocIdsByDomain(domainSql);
+        const domain = buildDomainFilter(scope, scopeId);
+        const domainDocIds = await this.store.getDocIdsByDomain(domain);
         docIds = docIds ? domainDocIds.filter((id) => docIds.includes(id)) : domainDocIds;
       }
       if (docIds) {
         if (docIds.length === 0) return NO_MATCH;
-        parts.push(inSql("doc_id", docIds));
+        parts.push({ op: "in", field: "doc_id", values: docIds });
       }
     }
-    return parts.length > 0 ? parts.join(" AND ") : void 0;
+    return parts.length > 0 ? parts : void 0;
   }
   // ── 读取 / 删除 ─────────────────────────────────────────────────────────────────
   async getDocument(docId) {
-    return this.lance.getDocument(docId);
+    return this.store.getDocument(docId);
   }
   async deleteDocument(docId) {
-    const existing = await this.lance.getDocument(docId);
+    const existing = await this.store.getDocument(docId);
     if (!existing) return false;
-    await this.lance.deleteDocument(docId);
-    await this.lance.deleteChunksByDoc(docId).catch((err) => {
+    await this.store.deleteDocument(docId);
+    await this.store.deleteChunksByDoc(docId).catch((err) => {
       console.error(`[KnowledgeManager] Failed to delete chunks for doc ${docId}:`, err);
     });
     await this.grafeo.deleteKnowledgeByDoc(docId).catch((err) => {
@@ -2515,7 +2734,7 @@ ${p.content}` : p.content
     return true;
   }
   async listDocuments(filter, page) {
-    let docs = await this.lance.getAllDocuments();
+    let docs = await this.store.getAllDocuments();
     if (filter?.userId) docs = docs.filter((d) => d.userId === filter.userId);
     if (filter?.chatId) docs = docs.filter((d) => d.chatId === filter.chatId);
     if (filter?.sessionId) docs = docs.filter((d) => d.sessionId === filter.sessionId);
@@ -2533,19 +2752,12 @@ function dedupByContent(items) {
   }
   return out;
 }
-function esc(value) {
-  return value.replace(/'/g, "''");
-}
-function buildDomainSql(scope, scopeId) {
-  if (scope === "session" && scopeId) return `session_id = '${esc(scopeId)}'`;
-  if (scope === "chat" && scopeId) return `chat_id = '${esc(scopeId)}'`;
-  if (scope === "user" && scopeId) return `user_id = '${esc(scopeId)}'`;
+function buildDomainFilter(scope, scopeId) {
+  if (scope === "session" && scopeId) return [eq("session_id", scopeId)];
+  if (scope === "chat" && scopeId) return [eq("chat_id", scopeId)];
+  if (scope === "user" && scopeId) return [eq("user_id", scopeId)];
   return void 0;
 }
-function inSql(column, values) {
-  const list = values.map((v) => `'${esc(v)}'`).join(", ");
-  return `${column} IN (${list})`;
-}
 function inferTitle(markdown) {
   const lines = markdown.split(/\r?\n/);
   for (const line of lines) {
@@ -2583,78 +2795,208 @@ function withTimeout2(promise, timeoutMs, label) {
 var SessionCache = class {
   config;
   sessions = /* @__PURE__ */ new Map();
-  historyWindows = /* @__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);
+    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(topicOrder);
+    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();
+  }
+  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 ?? [];
+  }
+  buildCompressedContext(sessionId) {
+    return 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.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);
+      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 topicOrder(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 {
   config;
-  lance;
+  store;
   grafeo;
   embed;
   llm;
@@ -2664,18 +3006,24 @@ var MemoryManager = class {
   knowledgeManager;
   sessionMap = /* @__PURE__ */ new Map();
   optimizeTimer;
+  sessionSweepTimer;
   optimizeRunning = false;
+  optimizeTask;
+  destroyTask;
+  hydration = /* @__PURE__ */ new Map();
+  pendingWrites = /* @__PURE__ */ new Map();
+  warnedDefaultModelContext = false;
   constructor(config) {
     this.config = resolveConfig(config);
-    this.lance = new LanceService(this.config);
+    this.store = new MemoryStore(this.config);
     this.grafeo = new GrafeoService(this.config);
     this.embed = new EmbedService(this.config);
     this.llm = new LlmService(this.config);
     this.sessionCache = new SessionCache(this.config);
-    this.factCache = new FactCache(this.lance);
+    this.factCache = new FactCache(this.store);
     this.compressManager = new CompressManager(
       this.config,
-      this.lance,
+      this.store,
       this.grafeo,
       this.llm,
       this.embed,
@@ -2683,7 +3031,7 @@ var MemoryManager = class {
     );
     this.knowledgeManager = new KnowledgeManager(
       this.config,
-      this.lance,
+      this.store,
       this.grafeo,
       this.llm,
       this.embed
@@ -2691,24 +3039,33 @@ var MemoryManager = class {
   }
   async init() {
     initEncoder();
-    await this.lance.init();
+    await this.store.init();
     await this.grafeo.init();
     await this.factCache.init();
-    const allSessions = await this.lance.getAllSessions();
+    const allSessions = await this.store.getAllSessions();
     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) {
@@ -2734,122 +3091,143 @@ var MemoryManager = class {
    * @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;
-    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, "");
-          }
-        })
-      )
-    );
+    return this.store.optimizeStorage(retentionMs ?? this.config.optimizeVersionRetentionMs);
+  }
+  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.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.lance.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.lance.insertSession(session).catch((err) => {
-        console.error("[MemoryManager] Failed to insert session:", err);
-      });
-    } else {
-      const view = this.sessionMap.get(sessionId);
-      view.updatedAt = now;
-      this.lance.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;
@@ -2885,7 +3263,7 @@ var MemoryManager = class {
     } = opts;
     if (!query.trim()) return [];
     const vector = await this.embed.embedOne(query);
-    const filter = this.buildLanceFilter(scope, scopeId);
+    const filter = this.buildScopeFilter(scope, scopeId);
     let useGraph = false;
     if (mode === "all") {
       useGraph = true;
@@ -2893,16 +3271,32 @@ var MemoryManager = class {
       useGraph = await this.llm.judgeNeedsGraphSearch(query).catch(() => false);
     }
     const tasks = [
-      this.lance.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: t.summaryId,
-            sessionId: t.sessionId,
-            chatId: t.chatId,
-            userId: t.userId
+            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: {
+            messageId: message.messageId,
+            sessionId: message.sessionId,
+            chatId: message.chatId,
+            userId: message.userId,
+            metadata: safeParseObject2(message.metadata)
           }
         }))
       ).catch(() => [])
@@ -2961,15 +3355,84 @@ 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) {
+    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);
+    for (let attempt = 0; attempt < 100; attempt++) {
+      let entry2 = this.sessionCache.getEntry(sessionId);
+      if (entry2.totalTokens <= usageLimits.rawTokenLimit || entry2.messages.length === 0) break;
+      await this.compressManager.waitForIdle(sessionId);
+      entry2 = this.sessionCache.getEntry(sessionId);
+      if (entry2.totalTokens <= usageLimits.rawTokenLimit || entry2.messages.length === 0) break;
+      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}`);
+      }
+    }
+    const entry = this.sessionCache.getEntry(sessionId);
+    if (entry.totalTokens > usageLimits.rawTokenLimit) {
+      throw new Error(`Unable to fit session ${sessionId} into the requested model context`);
+    }
+    return {
+      sessionId,
+      compressedContext: this.sessionCache.buildCompressedContext(sessionId),
+      recentMessages: entry.messages.map(toMemoryRawMessage),
+      usage: {
+        ...usageLimits,
+        compressedTokens: entry.topicTokens,
+        rawTokens: entry.totalTokens
+      }
+    };
   }
-  getHistoryWindow(sessionId) {
-    return this.sessionCache.getHistoryWindow(sessionId);
+  calculateWindowUsage(modelContextTokens) {
+    const usableContextTokens = Math.floor(modelContextTokens * this.config.contextUsageRatio);
+    const rawTokenLimit = usableContextTokens - this.config.compressedContextTokenLimit;
+    if (rawTokenLimit <= 0) {
+      throw new Error(
+        `modelContextTokens=${modelContextTokens} \u5728 contextUsageRatio=${this.config.contextUsageRatio} \u4E0B\u4E0D\u8DB3\u4EE5\u5BB9\u7EB3 compressedContextTokenLimit=${this.config.compressedContextTokenLimit}`
+      );
+    }
+    return {
+      modelContextTokens,
+      usableContextTokens,
+      compressedTokenLimit: this.config.compressedContextTokenLimit,
+      rawTokenLimit
+    };
   }
-  buildLanceFilter(scope, scopeId) {
-    if (scope === "session" && scopeId) return `session_id = '${scopeId}'`;
-    if (scope === "chat" && scopeId) return `chat_id = '${scopeId}'`;
-    if (scope === "user" && scopeId) return `user_id = '${scopeId}'`;
+  buildScopeFilter(scope, scopeId) {
+    if (scope === "session" && scopeId) return [eq("session_id", scopeId)];
+    if (scope === "chat" && scopeId) return [eq("chat_id", scopeId)];
+    if (scope === "user" && scopeId) return [eq("user_id", scopeId)];
     return void 0;
   }
   deserializeSession(s) {
@@ -2980,7 +3443,7 @@ var MemoryManager = class {
   }
   // ── Message queries ──────────────────────────────────────────────────────────
   async getRecentMessages(sessionId, limit) {
-    return this.lance.getLatestMessages(sessionId, limit);
+    return this.store.getLatestMessages(sessionId, limit);
   }
   // ── Session queries (in-memory) ──────────────────────────────────────────────
   getSession(sessionId) {
@@ -3016,17 +3479,18 @@ var MemoryManager = class {
       updatedAt: Date.now()
     };
     this.sessionMap.set(sessionId, updated);
-    await this.lance.upsertSession(this.serializeSession(updated));
+    await this.store.upsertSession(this.serializeSession(updated));
     return updated;
   }
   async deleteSession(sessionId) {
     if (!this.sessionMap.has(sessionId)) return false;
     this.sessionMap.delete(sessionId);
-    await this.lance.deleteSession(sessionId);
-    await this.lance.deleteMessagesBySession(sessionId).catch((err) => {
+    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);
     });
-    await this.lance.deleteTopicsBySession(sessionId).catch((err) => {
+    await this.store.deleteTopicsBySession(sessionId).catch((err) => {
       console.error(`[MemoryManager] Failed to delete topics for session ${sessionId}:`, err);
     });
     return true;
@@ -3035,8 +3499,8 @@ var MemoryManager = class {
   /** 概览统计：各类记忆数据的总量 */
   async stats() {
     const [counts, knowledge, entities, relations] = await Promise.all([
-      this.lance.countAll(),
-      this.lance.countKnowledge(),
+      this.store.countAll(),
+      this.store.countKnowledge(),
       this.grafeo.getAllEntities(),
       this.grafeo.getAllRelations()
     ]);
@@ -3050,7 +3514,7 @@ var MemoryManager = class {
   /** 按天聚合最近 days 天的活跃趋势（概览图表用，含零值天）。days 默认 30，范围 1~365。 */
   async trend(days = 30) {
     const n = Math.min(365, Math.max(1, Math.floor(days)));
-    return this.lance.trendDaily(n);
+    return this.store.trendDaily(n);
   }
   listSessions(filter, page) {
     let results = [...this.sessionMap.values()];
@@ -3061,13 +3525,13 @@ var MemoryManager = class {
   }
   async listMessages(sessionId, limitOrPage) {
     if (typeof limitOrPage === "object") {
-      const all = await this.lance.getAllMessagesBySession(sessionId);
+      const all = await this.store.getAllMessagesBySession(sessionId);
       return paginate(all, limitOrPage);
     }
-    return this.lance.getLatestMessages(sessionId, limitOrPage ?? 100);
+    return this.store.getLatestMessages(sessionId, limitOrPage ?? 100);
   }
   async listTopics(filter, page) {
-    let topics = await this.lance.getAllTopics();
+    let topics = await this.store.getAllTopics();
     if (filter?.sessionId) topics = topics.filter((t) => t.sessionId === filter.sessionId);
     if (filter?.userId) topics = topics.filter((t) => t.userId === filter.userId);
     if (filter?.chatId) topics = topics.filter((t) => t.chatId === filter.chatId);
@@ -3096,8 +3560,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) {
@@ -3136,18 +3600,73 @@ 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();
+    if (this.sessionSweepTimer) {
+      clearInterval(this.sessionSweepTimer);
+      this.sessionSweepTimer = void 0;
+    }
+    const writes = [...this.pendingWrites.values(), ...this.hydration.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 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,
-  LanceService,
-  MemoryManager
+  MemoryManager,
+  MemoryStore
 };