@ppagent/memory 0.4.4 → 0.4.6

package/dist/index.js

@@ -1,4 +1,6 @@
 // src/memory.manager.ts
+import * as fs from "node:fs/promises";
+import * as path2 from "node:path";
 import { v4 as uuidv44 } from "uuid";
 
 // src/config.ts
@@ -47,9 +49,27 @@ function resolveConfig(config) {
       "topicCompactionSyncRatio"
     ),
     contextUsageRatio: ratio(config.contextUsageRatio ?? 0.75, "contextUsageRatio"),
-    precompressionRatio: ratio(config.precompressionRatio ?? 0.75, "precompressionRatio"),
-    compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.5, "compressionBatchRatio"),
+    precompressionRatio: ratio(config.precompressionRatio ?? 0.6, "precompressionRatio"),
+    compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.7, "compressionBatchRatio"),
     compressionBatchTokenLimit: Math.max(0, Math.floor(config.compressionBatchTokenLimit ?? 0)),
+    compressionMaxRetries: nonNegativeInt(
+      config.compressionMaxRetries ?? 2,
+      "compressionMaxRetries"
+    ),
+    compressionRetryBaseDelayMs: nonNegativeInt(
+      config.compressionRetryBaseDelayMs ?? 500,
+      "compressionRetryBaseDelayMs"
+    ),
+    backgroundCompressionMaxRetries: nonNegativeInt(
+      config.backgroundCompressionMaxRetries ?? 2,
+      "backgroundCompressionMaxRetries"
+    ),
+    backgroundCompressionRetryBaseDelayMs: nonNegativeInt(
+      config.backgroundCompressionRetryBaseDelayMs ?? 1e3,
+      "backgroundCompressionRetryBaseDelayMs"
+    ),
+    onCompressionEvent: config.onCompressionEvent ?? (() => {
+    }),
     topicSummaryMaxTokens: positiveInt(
       config.topicSummaryMaxTokens ?? config.detailMaxTokens ?? 2048,
       "topicSummaryMaxTokens"
@@ -86,6 +106,8 @@ function resolveConfig(config) {
     graphExtractConcurrency: config.graphExtractConcurrency ?? 2,
     graphBuildTimeoutMs: config.graphBuildTimeoutMs ?? 12e4,
     autoOptimizeOnInit: config.autoOptimizeOnInit ?? true,
+    autoMigrateLegacyDataOnInit: config.autoMigrateLegacyDataOnInit ?? true,
+    autoResumeCompressionOnInit: config.autoResumeCompressionOnInit ?? true,
     autoOptimizeIntervalMs: config.autoOptimizeIntervalMs ?? 6 * 36e5,
     optimizeVersionRetentionMs: config.optimizeVersionRetentionMs ?? 0,
     restoreConcurrency: config.restoreConcurrency ?? 8
@@ -97,6 +119,12 @@ function ratio(value, name) {
   }
   return value;
 }
+function nonNegativeInt(value, name) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u975E\u8D1F\u6570`);
+  }
+  return Math.floor(value);
+}
 function positiveInt(value, name) {
   if (!Number.isFinite(value) || value <= 0) {
     throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u6B63\u6570`);
@@ -255,6 +283,18 @@ import { GrafeoDB } from "@grafeo-db/js";
 import { get_encoding } from "@dqbd/tiktoken";
 
 // src/llm/http.ts
+var HttpRequestError = class extends Error {
+  retryable;
+  attempts;
+  status;
+  constructor(message, options) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "HttpRequestError";
+    this.retryable = options.retryable;
+    this.attempts = options.attempts;
+    this.status = options.status;
+  }
+};
 function normalizeFetchError(err, timeoutMs, errorLabel) {
   if (isAbortError(err)) {
     return new Error(`${errorLabel} request timed out after ${timeoutMs}ms`, { cause: err });
@@ -291,15 +331,36 @@ async function postJsonWithRetry(url, headers, body, opts, errorLabel = "HTTP")
         await sleep(backoffDelay(attempt));
         continue;
       }
-      throw lastErr;
+      throw new HttpRequestError(lastErr.message, {
+        retryable: true,
+        attempts: attempt + 1,
+        cause: lastErr
+      });
     }
     clearTimeout(timer);
     if (res.ok) {
-      return await res.json();
+      try {
+        return await res.json();
+      } catch (err) {
+        lastErr = new HttpRequestError(`${errorLabel} returned invalid JSON`, {
+          retryable: true,
+          attempts: attempt + 1,
+          cause: err
+        });
+        if (attempt < opts.maxRetries) {
+          await sleep(backoffDelay(attempt));
+          continue;
+        }
+        throw lastErr;
+      }
     }
     const text = await res.text().catch(() => "");
-    lastErr = new Error(`${errorLabel} error ${res.status}: ${text}`);
     const retryable = res.status >= 500 || res.status === 429;
+    lastErr = new HttpRequestError(`${errorLabel} error ${res.status}: ${text}`, {
+      retryable,
+      attempts: attempt + 1,
+      status: res.status
+    });
     if (retryable && attempt < opts.maxRetries) {
       await sleep(backoffDelay(attempt));
       continue;
@@ -802,6 +863,136 @@ function eq(field, value) {
   return { op: "eq", field, value };
 }
 
+// src/history-image.ts
+var OMIT_IMAGE = Symbol("omit-history-image");
+var IMAGE_PART_TYPES = /* @__PURE__ */ new Set([
+  "image",
+  "image-data",
+  "image-url",
+  "image-file-id",
+  "image-file-reference",
+  "input-image",
+  "output-image"
+]);
+function sanitizeRawHistoryFields(message) {
+  const partsResult = sanitizeValue(message.parts ?? []);
+  const payloadResult = sanitizeValue(message.payload);
+  const contextResult = sanitizeValue(message.contextPayload);
+  const metadataResult = sanitizeValue(message.metadata ?? {});
+  const payload = optionalSanitizedValue(payloadResult);
+  const contextPayload = optionalSanitizedValue(contextResult);
+  return {
+    parts: Array.isArray(partsResult.value) ? partsResult.value : [],
+    ...payload !== void 0 && { payload },
+    ...contextPayload !== void 0 && { contextPayload },
+    metadata: isRecord(metadataResult.value) ? metadataResult.value : {},
+    removedImages: partsResult.removedImages + payloadResult.removedImages + contextResult.removedImages + metadataResult.removedImages
+  };
+}
+function sanitizeStoredMessageImages(message) {
+  const parsed = {
+    content: message.content,
+    parts: parseArray(message.parts),
+    ...message.payload !== void 0 && { payload: parseValue(message.payload) },
+    ...message.contextPayload !== void 0 && {
+      contextPayload: parseValue(message.contextPayload)
+    },
+    metadata: parseObject(message.metadata)
+  };
+  const sanitized = sanitizeRawHistoryFields(parsed);
+  if (sanitized.removedImages === 0) {
+    return { message, changed: false, removedImages: 0 };
+  }
+  const parts = JSON.stringify(sanitized.parts);
+  const payload = sanitized.payload === void 0 ? void 0 : JSON.stringify(sanitized.payload);
+  const contextPayload = sanitized.contextPayload === void 0 ? void 0 : JSON.stringify(sanitized.contextPayload);
+  const metadata = JSON.stringify(sanitized.metadata);
+  const usage = countTokens(
+    [message.content, parts, metadata, payload ?? "", contextPayload ?? ""].join("\n")
+  );
+  return {
+    message: {
+      ...message,
+      parts,
+      payload,
+      contextPayload,
+      usage,
+      metadata
+    },
+    changed: true,
+    removedImages: sanitized.removedImages
+  };
+}
+function sanitizeValue(value) {
+  if (typeof value === "string" && /^data:image\//i.test(value.trim())) {
+    return { value: OMIT_IMAGE, removedImages: 1, changed: true };
+  }
+  if (value == null || typeof value !== "object") {
+    return { value, removedImages: 0, changed: false };
+  }
+  if (isImageNode(value)) {
+    return { value: OMIT_IMAGE, removedImages: 1, changed: true };
+  }
+  if (Array.isArray(value)) {
+    const out2 = [];
+    let removedImages2 = 0;
+    let changed2 = false;
+    for (const item of value) {
+      const sanitized = sanitizeValue(item);
+      removedImages2 += sanitized.removedImages;
+      changed2 ||= sanitized.changed;
+      if (sanitized.value !== OMIT_IMAGE) out2.push(sanitized.value);
+    }
+    return { value: changed2 ? out2 : value, removedImages: removedImages2, changed: changed2 };
+  }
+  const out = {};
+  let removedImages = 0;
+  let changed = false;
+  for (const [key, item] of Object.entries(value)) {
+    const sanitized = sanitizeValue(item);
+    removedImages += sanitized.removedImages;
+    changed ||= sanitized.changed;
+    if (sanitized.value !== OMIT_IMAGE) out[key] = sanitized.value;
+  }
+  return { value: changed ? out : value, removedImages, changed };
+}
+function isImageNode(value) {
+  if (!isRecord(value)) return false;
+  const type = normalizeType(value.type);
+  if (IMAGE_PART_TYPES.has(type)) return true;
+  const mediaType = String(value.mediaType ?? value.mimeType ?? "").trim().toLowerCase();
+  return mediaType.startsWith("image/") && (type === "file" || "data" in value || "url" in value || "fileId" in value || "providerReference" in value);
+}
+function normalizeType(value) {
+  return typeof value === "string" ? value.trim().toLowerCase().replaceAll("_", "-") : "";
+}
+function optionalSanitizedValue(result) {
+  if (result.value === OMIT_IMAGE) return void 0;
+  if (result.changed && isEmptyContainer(result.value)) return void 0;
+  return result.value;
+}
+function isEmptyContainer(value) {
+  return Array.isArray(value) ? value.length === 0 : isRecord(value) && Object.keys(value).length === 0;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseValue(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function parseArray(value) {
+  const parsed = parseValue(value);
+  return Array.isArray(parsed) ? parsed : [];
+}
+function parseObject(value) {
+  const parsed = parseValue(value);
+  return isRecord(parsed) ? parsed : {};
+}
+
 // src/db/memory.store.ts
 var MESSAGES_TABLE = "messages";
 var TOPICS_TABLE = "topics";
@@ -1264,17 +1455,28 @@ var MemoryStore = class {
     const messageRows = await this.provider.query(MESSAGES_TABLE);
     report.messagesScanned = messageRows.length;
     for (const row of messageRows) {
+      const sanitized = sanitizeStoredMessageImages(rowToMessage(row)).message;
       const usage = countTokens(
         [
-          row.content,
-          row.parts ?? "[]",
-          row.metadata ?? "{}",
-          row.payload ?? "",
-          row.context_payload ?? ""
+          sanitized.content,
+          sanitized.parts,
+          sanitized.metadata,
+          sanitized.payload ?? "",
+          sanitized.contextPayload ?? ""
         ].map(String).join("\n")
       );
-      if (Number(row.usage) === usage) continue;
-      await this.provider.update(MESSAGES_TABLE, { usage }, [
+      const values = {
+        parts: sanitized.parts,
+        payload: sanitized.payload ?? null,
+        context_payload: sanitized.contextPayload ?? null,
+        metadata: sanitized.metadata,
+        usage
+      };
+      const changed = Object.entries(values).some(
+        ([key, value]) => !migrationValueEquals(row[key], value)
+      );
+      if (!changed) continue;
+      await this.provider.update(MESSAGES_TABLE, values, [
         eq("message_id", String(row.message_id))
       ]);
       report.messagesUpdated++;
@@ -2095,7 +2297,7 @@ function stripToolCallContent(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripToolCallContent(item)).filter((item) => item !== OMIT_COMPRESSION_VALUE);
   }
-  if (!isRecord(value)) return value;
+  if (!isRecord2(value)) return value;
   if (isToolCallBlock(value)) return OMIT_COMPRESSION_VALUE;
   const sanitized = {};
   for (const [key, child] of Object.entries(value)) {
@@ -2120,138 +2322,520 @@ function isToolCallBlock(value) {
 function normalizeToolKey(value) {
   return value.replace(/[\s_-]/g, "").toLowerCase();
 }
-function isRecord(value) {
+function isRecord2(value) {
   return value !== null && typeof value === "object";
 }
 
 // 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();
+// src/compression-message.ts
+var INTERNAL_METADATA_KEY = "__ppagentMemory";
+function addCompressionHints(metadata, message) {
+  const compressionGroupId = normalizeGroupId(message.compressionGroupId);
+  const compressionRole = normalizeRole(message.compressionRole);
+  if (!compressionGroupId && !compressionRole) return metadata;
+  const existing = isRecord3(metadata[INTERNAL_METADATA_KEY]) ? metadata[INTERNAL_METADATA_KEY] : {};
+  return {
+    ...metadata,
+    [INTERNAL_METADATA_KEY]: {
+      ...existing,
+      ...compressionGroupId && { compressionGroupId },
+      ...compressionRole && { compressionRole }
     }
+  };
+}
+function readCompressionHints(message) {
+  const metadata = parseMetadata(message.metadata);
+  const internal = isRecord3(metadata[INTERNAL_METADATA_KEY]) ? metadata[INTERNAL_METADATA_KEY] : {};
+  const { [INTERNAL_METADATA_KEY]: _internal, ...publicMetadata } = metadata;
+  const explicitCompressionRole = normalizeRole(internal.compressionRole);
+  return {
+    metadata: publicMetadata,
+    compressionGroupId: normalizeGroupId(internal.compressionGroupId),
+    explicitCompressionRole,
+    compressionRole: explicitCompressionRole ?? normalizeRole(metadata.role) ?? inferRole(message.talkerId)
+  };
+}
+function inferRole(talkerId) {
+  const normalized = talkerId.trim().toLowerCase();
+  if (normalized === "assistant") return "assistant";
+  if (normalized === "tool") return "tool";
+  if (normalized === "system") return "system";
+  return "user";
+}
+function normalizeGroupId(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function normalizeRole(value) {
+  return value === "user" || value === "assistant" || value === "tool" || value === "system" ? value : void 0;
+}
+function parseMetadata(value) {
+  try {
+    const parsed = JSON.parse(value);
+    return isRecord3(parsed) ? parsed : {};
+  } catch {
+    return {};
   }
-  acquire() {
-    if (this.count > 0) {
-      this.count--;
-      return Promise.resolve();
-    }
-    return new Promise((resolve) => {
-      this.queue.push(resolve);
-    });
+}
+function isRecord3(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+// src/manager/session.cache.ts
+var SessionCache = class {
+  config;
+  sessions = /* @__PURE__ */ new Map();
+  topicViews = /* @__PURE__ */ new Map();
+  legacyHistoryWindows = /* @__PURE__ */ new Map();
+  constructor(config) {
+    this.config = config;
   }
-  release() {
-    const next = this.queue.shift();
-    if (next) {
-      next();
+  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,
+        topics: [],
+        topicTokens: 0,
+        ids: { chatId, userId },
+        lastAccessAt: Date.now()
+      };
+      this.sessions.set(sessionId, entry);
     } else {
-      this.count++;
+      entry.ids = { chatId, userId };
+      entry.lastAccessAt = Date.now();
     }
+    return entry;
   }
-};
-
-// src/manager/compress.manager.ts
-var CompressManager = class {
-  constructor(config, store, grafeo, llm, embed, sessionCache) {
-    this.config = config;
-    this.store = store;
-    this.grafeo = grafeo;
-    this.llm = llm;
-    this.embed = embed;
-    this.sessionCache = sessionCache;
-    this.semaphore = new Semaphore(config.maxConcurrentCompressions);
+  hydrate(sessionId, chatId, userId, messages, topics) {
+    const entry = this.getOrCreateEntry(sessionId, chatId, userId);
+    entry.messages = sortMessages(dedupeMessages(messages));
+    entry.totalTokens = sumMessageTokens(entry.messages);
+    this.setTopics(sessionId, topics, false);
+    return entry;
   }
-  semaphore;
-  sessionChain = /* @__PURE__ */ new Map();
-  backgroundGraphs = /* @__PURE__ */ new Set();
-  triggerCompress(sessionId, force = false, waitGraph = false, rawLimit) {
-    return this.enqueueSessionTask(
-      sessionId,
-      () => this.doCompress(sessionId, force, waitGraph, rawLimit)
-    );
+  upsertMessages(sessionId, messages, chatId, userId) {
+    const entry = this.getOrCreateEntry(sessionId, chatId, userId);
+    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;
   }
-  /** 按给定预算收敛 Topic；persist=false 时只缓存当前模型使用的临时视图。 */
-  triggerTopicCompaction(sessionId, tokenLimit, persist) {
-    return this.enqueueSessionTask(
-      sessionId,
-      () => this.compactOldTopics(sessionId, Math.max(1, Math.floor(tokenLimit)), persist)
-    );
+  /** @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;
   }
-  enqueueSessionTask(sessionId, task) {
-    const previous = this.sessionChain.get(sessionId) ?? Promise.resolve();
-    const next = previous.then(
-      () => this.semaphore.run(task)
-    );
-    const settled = next.catch(() => {
-    });
-    this.sessionChain.set(sessionId, settled);
-    settled.finally(() => {
-      if (this.sessionChain.get(sessionId) === settled) this.sessionChain.delete(sessionId);
-    });
-    return next;
+  /** @deprecated 新压缩链按 messageId 精确移除。 */
+  clearMessages(sessionId, keepAfter) {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    entry.messages = keepAfter == null ? [] : entry.messages.filter((message) => message.createdAt > keepAfter);
+    entry.totalTokens = sumMessageTokens(entry.messages);
   }
-  async waitForIdle(sessionId) {
-    await (this.sessionChain.get(sessionId) ?? Promise.resolve());
+  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();
   }
-  isBusy(sessionId) {
-    return this.sessionChain.has(sessionId);
+  getSessionMessages(sessionId) {
+    return this.getEntry(sessionId)?.messages ?? [];
   }
-  async waitForAllIdle() {
-    while (this.sessionChain.size > 0 || this.backgroundGraphs.size > 0) {
-      await Promise.all([
-        ...this.sessionChain.values(),
-        ...this.backgroundGraphs
-      ]);
+  selectOldestMessageBatch(sessionId, targetTokens) {
+    const messages = this.getSessionMessages(sessionId);
+    if (messages.length === 0 || targetTokens <= 0) return [];
+    const groups = groupConversationMessages(messages);
+    const selectableGroups = groups.length > 1 ? groups.slice(0, -1) : groups;
+    const selected = [];
+    let tokens = 0;
+    for (const group of selectableGroups) {
+      const nextTokens = tokens + sumMessageTokens(group);
+      if (selected.length > 0 && Math.abs(targetTokens - tokens) <= Math.abs(targetTokens - nextTokens)) {
+        break;
+      }
+      selected.push(...group);
+      tokens = nextTokens;
+      if (tokens >= targetTokens) break;
     }
+    return selected;
   }
-  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 {
-      result = await this.llm.summarizeMessages(messages);
-    } catch (error) {
-      console.error(
-        `[CompressManager] LLM compress failed for session ${sessionId}: ${formatError(error)}`
-      );
-      throw error;
+  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;
     }
-    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: entry.ids.userId,
-      chatId: entry.ids.chatId,
-      title: result.title,
-      summary,
+    entry.topics = kept.reverse();
+    entry.topicTokens = used;
+    entry.lastAccessAt = Date.now();
+    this.topicViews.delete(sessionId);
+  }
+  appendTopic(sessionId, topic) {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    this.setTopics(sessionId, [...entry.topics, topic], false);
+  }
+  replaceTopics(sessionId, removedIds, replacement) {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    const ids = new Set(removedIds);
+    this.setTopics(
+      sessionId,
+      [...entry.topics.filter((topic) => !ids.has(topic.summaryId)), replacement],
+      false
+    );
+  }
+  getTopics(sessionId) {
+    return this.getEntry(sessionId)?.topics ?? [];
+  }
+  getTopicView(sessionId, tokenLimit) {
+    return this.topicViews.get(sessionId)?.get(tokenLimit);
+  }
+  setTopicView(sessionId, tokenLimit, topics) {
+    let views = this.topicViews.get(sessionId);
+    if (!views) {
+      views = /* @__PURE__ */ new Map();
+      this.topicViews.set(sessionId, views);
+    }
+    views.set(tokenLimit, [...topics].map(normalizeTopic).sort(topicOrder));
+  }
+  buildCompressedContext(sessionId, topics) {
+    return (topics ?? this.getTopics(sessionId)).map((topic) => topic.title ? `## ${topic.title}
+${topic.summary}` : topic.summary).join("\n\n");
+  }
+  /** @deprecated 三级窗口兼容，仅供 0.3.x 调用方过渡。 */
+  buildHistoryWindow(sessionId, groups) {
+    const [detailCount, summaryCount, conciseCount] = this.config.topicRatio;
+    const values = [
+      ...groups.detail.slice(0, detailCount).map((topic) => topic.detail ?? topic.summary),
+      ...groups.summary.slice(0, summaryCount).map((topic) => topic.summary),
+      ...groups.concise.slice(0, conciseCount).map((topic) => topic.concise ?? topic.summary)
+    ];
+    let remaining = this.config.historyWindowTokenLimit;
+    const kept = [];
+    for (const value of values) {
+      const tokens = countTokens(value);
+      if (tokens > remaining) break;
+      kept.push(value);
+      remaining -= tokens;
+    }
+    this.legacyHistoryWindows.set(sessionId, kept.join("\n\n"));
+  }
+  /** @deprecated MemoryManager.getHistoryWindow 返回结构化窗口。 */
+  getHistoryWindow(sessionId) {
+    return this.legacyHistoryWindows.get(sessionId) ?? this.buildCompressedContext(sessionId);
+  }
+  /** @deprecated 仅为 0.3.x 兼容。 */
+  setHistoryWindow(sessionId, content) {
+    this.legacyHistoryWindows.set(sessionId, content);
+  }
+  setModelContextTokens(sessionId, modelContextTokens) {
+    const entry = this.sessions.get(sessionId);
+    if (!entry) return;
+    entry.lastModelContextTokens = modelContextTokens;
+    entry.lastAccessAt = Date.now();
+  }
+  getAllSessionIds() {
+    return [...this.sessions.keys()];
+  }
+  delete(sessionId) {
+    this.sessions.delete(sessionId);
+    this.topicViews.delete(sessionId);
+    this.legacyHistoryWindows.delete(sessionId);
+  }
+  evictIdle(now, ttlMs, isBusy) {
+    if (ttlMs <= 0) return [];
+    const evicted = [];
+    for (const [sessionId, entry] of this.sessions) {
+      if (now - entry.lastAccessAt < ttlMs || isBusy(sessionId)) continue;
+      this.sessions.delete(sessionId);
+      this.topicViews.delete(sessionId);
+      evicted.push(sessionId);
+    }
+    return evicted;
+  }
+};
+function groupConversationMessages(messages) {
+  const groups = [];
+  let current = [];
+  let explicitGroupId;
+  for (const message of messages) {
+    const hints = readCompressionHints(message);
+    const startsExplicitGroup = hints.compressionGroupId !== explicitGroupId && (hints.compressionGroupId != null || explicitGroupId != null);
+    const startsInferredGroup = hints.compressionGroupId == null && (hints.compressionRole === "user" || hints.compressionRole === "system");
+    if (current.length > 0 && (startsExplicitGroup || startsInferredGroup)) {
+      groups.push(current);
+      current = [];
+    }
+    current.push(message);
+    explicitGroupId = hints.compressionGroupId;
+  }
+  if (current.length > 0) groups.push(current);
+  return groups;
+}
+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) + (message.contextPayload?.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/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/compression-events.ts
+function emitCompressionEvent(config, event) {
+  try {
+    const returned = config.onCompressionEvent(event);
+    if (returned && typeof returned.then === "function") {
+      void Promise.resolve(returned).catch((error) => {
+        console.warn("[memory] onCompressionEvent callback rejected:", error);
+      });
+    }
+  } catch (error) {
+    console.warn("[memory] onCompressionEvent callback failed:", error);
+  }
+}
+
+// src/manager/compress.manager.ts
+var CompressManager = class {
+  constructor(config, store, grafeo, llm, embed, sessionCache) {
+    this.config = config;
+    this.store = store;
+    this.grafeo = grafeo;
+    this.llm = llm;
+    this.embed = embed;
+    this.sessionCache = sessionCache;
+    this.semaphore = new Semaphore(config.maxConcurrentCompressions);
+  }
+  semaphore;
+  sessionChain = /* @__PURE__ */ new Map();
+  backgroundGraphs = /* @__PURE__ */ new Set();
+  triggerCompress(sessionId, force = false, waitGraph = false, rawLimit, mode = "background") {
+    const startedAt = Date.now();
+    const task = this.enqueueSessionTask(
+      sessionId,
+      () => this.doCompress(sessionId, force, waitGraph, rawLimit, mode)
+    );
+    return task.catch((error) => {
+      emitCompressionEvent(this.config, {
+        sessionId,
+        kind: "raw",
+        mode,
+        phase: "failure",
+        attempt: 1,
+        maxAttempts: this.config.compressionMaxRetries + 1,
+        durationMs: Date.now() - startedAt,
+        error: formatError(error)
+      });
+      throw error;
+    });
+  }
+  /** 按给定预算收敛 Topic；persist=false 时只缓存当前模型使用的临时视图。 */
+  triggerTopicCompaction(sessionId, tokenLimit, persist, mode = "background") {
+    const startedAt = Date.now();
+    emitCompressionEvent(this.config, {
+      sessionId,
+      kind: "topics",
+      mode,
+      phase: "start",
+      attempt: 1,
+      maxAttempts: this.config.compressionMaxRetries + 1
+    });
+    const task = this.enqueueSessionTask(
+      sessionId,
+      () => this.compactOldTopics(
+        sessionId,
+        Math.max(1, Math.floor(tokenLimit)),
+        persist,
+        mode
+      )
+    );
+    return task.then(() => {
+      emitCompressionEvent(this.config, {
+        sessionId,
+        kind: "topics",
+        mode,
+        phase: "success",
+        attempt: 1,
+        maxAttempts: this.config.compressionMaxRetries + 1,
+        durationMs: Date.now() - startedAt
+      });
+    }, (error) => {
+      emitCompressionEvent(this.config, {
+        sessionId,
+        kind: "topics",
+        mode,
+        phase: "failure",
+        attempt: 1,
+        maxAttempts: this.config.compressionMaxRetries + 1,
+        durationMs: Date.now() - startedAt,
+        error: formatError(error)
+      });
+      throw error;
+    });
+  }
+  enqueueSessionTask(sessionId, task) {
+    const previous = this.sessionChain.get(sessionId) ?? Promise.resolve();
+    const next = previous.then(
+      () => this.semaphore.run(task)
+    );
+    const settled = next.catch(() => {
+    });
+    this.sessionChain.set(sessionId, settled);
+    settled.finally(() => {
+      if (this.sessionChain.get(sessionId) === settled) this.sessionChain.delete(sessionId);
+    });
+    return next;
+  }
+  async 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
+      ]);
+    }
+  }
+  async doCompress(sessionId, force, waitGraph, rawLimitOverride, mode) {
+    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(entry.totalTokens * 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;
+    const selectedTokens = messages.reduce(
+      (sum, message) => sum + effectiveUsage(message),
+      0
+    );
+    const startedAt = Date.now();
+    emitCompressionEvent(this.config, {
+      sessionId,
+      kind: "raw",
+      mode,
+      phase: "start",
+      attempt: 1,
+      maxAttempts: this.config.compressionMaxRetries + 1,
+      inputTokens: entry.totalTokens,
+      selectedTokens
+    });
+    let result;
+    try {
+      result = await this.summarizeWithRetry(
+        sessionId,
+        "raw-message compression",
+        () => this.llm.summarizeMessages(messages),
+        "raw",
+        mode
+      );
+    } catch (error) {
+      console.error(
+        `[CompressManager] LLM compress failed for session ${sessionId}: ${formatError(error)}`
+      );
+      throw error;
+    }
+    const summary = result.summary.trim();
+    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: 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,
@@ -2268,7 +2852,8 @@ var CompressManager = class {
     await this.compactOldTopics(
       sessionId,
       this.config.compressedContextTokenLimit,
-      true
+      true,
+      mode
     );
     const graphTask = this.extractAndPersistGraph(
       messages,
@@ -2286,8 +2871,20 @@ var CompressManager = class {
       this.backgroundGraphs.add(tracked);
       tracked.finally(() => this.backgroundGraphs.delete(tracked));
     }
+    emitCompressionEvent(this.config, {
+      sessionId,
+      kind: "raw",
+      mode,
+      phase: "success",
+      attempt: 1,
+      maxAttempts: this.config.compressionMaxRetries + 1,
+      inputTokens: entry.totalTokens + selectedTokens,
+      selectedTokens,
+      outputTokens: topic.tokens,
+      durationMs: Date.now() - startedAt
+    });
   }
-  async compactOldTopics(sessionId, tokenLimit, persist) {
+  async compactOldTopics(sessionId, tokenLimit, persist, mode) {
     let transientTopics = persist ? void 0 : this.sessionCache.getTopicView(sessionId, tokenLimit) ?? [...this.sessionCache.getEntry(sessionId)?.topics ?? []];
     while (true) {
       const entry = this.sessionCache.getEntry(sessionId);
@@ -2319,9 +2916,14 @@ var CompressManager = class {
           Math.max(1, tokenLimit - unselectedTokens)
         )
       );
-      const result = await this.llm.summarizeTopics(selected, maxSummaryTokens);
+      const result = await this.summarizeWithRetry(
+        sessionId,
+        "Topic compaction",
+        () => this.llm.summarizeTopics(selected, maxSummaryTokens),
+        "topics",
+        mode
+      );
       const summary = result.summary.trim();
-      if (!summary) throw new Error(`LLM returned an empty Topic rollup for session ${sessionId}`);
       const vector = persist ? await this.embed.embedOne(summary).catch(() => []) : [];
       const first = selected[0];
       const last = selected[selected.length - 1];
@@ -2358,7 +2960,7 @@ var CompressManager = class {
         transientTopics = [
           ...topics.filter((topic) => !ids.has(topic.summaryId)),
           rollup
-        ].sort(topicOrder);
+        ].sort(topicOrder2);
       }
     }
   }
@@ -2394,16 +2996,60 @@ var CompressManager = class {
     const embeddings = new Map(names.map((name, index) => [name, vectors[index]]));
     await this.grafeo.upsertEntitiesAndRelations(entities, relations, embeddings);
   }
+  /**
+   * HTTP transport already owns bounded retries for network/timeout/5xx/429.
+   * This outer layer retries semantic compression failures only: malformed model
+   * content, missing fields and empty summaries. That avoids retry multiplication.
+   */
+  async summarizeWithRetry(sessionId, label, operation, kind, mode) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.config.compressionMaxRetries; attempt++) {
+      try {
+        const result = await operation();
+        if (typeof result?.summary !== "string" || !result.summary.trim()) {
+          throw new Error(`${label} returned an empty summary`);
+        }
+        return result;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof HttpRequestError || attempt >= this.config.compressionMaxRetries) {
+          throw error;
+        }
+        const delayMs = Math.min(
+          this.config.compressionRetryBaseDelayMs * 2 ** attempt,
+          8e3
+        );
+        console.warn(
+          `[CompressManager] ${label} failed for session ${sessionId}; retrying ${attempt + 1}/${this.config.compressionMaxRetries} after ${delayMs}ms: ` + formatError(error)
+        );
+        emitCompressionEvent(this.config, {
+          sessionId,
+          kind,
+          mode,
+          phase: "retry",
+          attempt: attempt + 2,
+          maxAttempts: this.config.compressionMaxRetries + 1,
+          retryKind: "semantic",
+          error: formatError(error)
+        });
+        if (delayMs > 0) await delay(delayMs);
+      }
+    }
+    throw lastError;
+  }
 };
 function sumTopicTokens(topics) {
   return topics.reduce((sum, topic) => sum + Math.max(1, topic.tokens), 0);
 }
-function topicOrder(a, b) {
+function topicOrder2(a, b) {
   return a.endTime - b.endTime || a.summaryId.localeCompare(b.summaryId);
 }
 function formatError(error) {
   return error instanceof Error ? error.message : String(error);
 }
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function withTimeout(promise, timeoutMs, label) {
   let timer;
   const timeout = new Promise((_, reject) => {
@@ -2823,359 +3469,142 @@ ${p.content}` : p.content
         let title = docTitleMap.get(docId);
         if (title === void 0) {
           const d = await this.store.getDocument(docId);
-          title = d?.title ?? "";
-        }
-        return { docId, title, matchedChunkCount };
-      })
-    );
-    const graphHits = await this.searchGraph(mode, vector, scope, scopeId, scored);
-    return { chunks: scored, documents, graphHits };
-  }
-  async searchGraph(mode, vector, scope, scopeId, topChunks) {
-    if (mode === "fast") return [];
-    if (mode === "auto") {
-      const top = topChunks[0];
-      if (!top || top.score < this.config.knowledgeGraphTriggerScore) return [];
-    }
-    const grafeoFilter = {
-      kind: KIND_KNOWLEDGE
-    };
-    if (scope === "user" && scopeId) grafeoFilter.userId = scopeId;
-    if (scope === "chat" && scopeId) grafeoFilter.chatId = scopeId;
-    if (scope === "session" && scopeId) grafeoFilter.sessionId = scopeId;
-    const entities = await this.grafeo.searchEntities(vector, grafeoFilter, this.config.knowledgeGraphEntityTopK).catch(() => []);
-    if (entities.length === 0) return entities;
-    const anchorCount = Math.min(this.config.knowledgeGraphAnchorTopK, entities.length);
-    const relatedArrays = await Promise.all(
-      entities.slice(0, anchorCount).map((e) => {
-        const name = e.meta?.name ?? "";
-        if (!name) return Promise.resolve([]);
-        return this.grafeo.getRelatedEntities(
-          name,
-          grafeoFilter.userId ?? e.meta?.userId ?? "",
-          grafeoFilter.chatId ?? e.meta?.chatId ?? "",
-          this.config.knowledgeGraphHopLimit,
-          KIND_KNOWLEDGE
-        ).catch(() => []);
-      })
-    );
-    return dedupByContent([...entities, ...relatedArrays.flat()]);
-  }
-  /**
-   * 构建片段表的过滤条件。
-   * - chunkRedundantIds=true：直接在 chunks 行的 user_id/chat_id/session_id 上过滤
-   * - false：先按域查 documents 得到 docId，再用 doc_id IN(...) 过滤
-   * 返回 undefined 表示不过滤；返回 NO_MATCH 表示无候选（应直接返回空结果）。
-   */
-  async buildChunkFilter(scope, scopeId, candidateDocIds) {
-    const parts = [];
-    if (this.config.chunkRedundantIds) {
-      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 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({ op: "in", field: "doc_id", values: docIds });
-      }
-    }
-    return parts.length > 0 ? parts : void 0;
-  }
-  // ── 读取 / 删除 ─────────────────────────────────────────────────────────────────
-  async getDocument(docId) {
-    return this.store.getDocument(docId);
-  }
-  async deleteDocument(docId) {
-    const existing = await this.store.getDocument(docId);
-    if (!existing) return false;
-    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) => {
-      console.error(`[KnowledgeManager] Failed to delete knowledge graph for doc ${docId}:`, err);
-    });
-    return true;
-  }
-  async listDocuments(filter, page) {
-    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);
-    return page ? paginate(docs, page) : docs;
-  }
-};
-var NO_MATCH = Symbol("no-match");
-function dedupByContent(items) {
-  const seen = /* @__PURE__ */ new Set();
-  const out = [];
-  for (const item of items) {
-    if (seen.has(item.content)) continue;
-    seen.add(item.content);
-    out.push(item);
-  }
-  return out;
-}
-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 inferTitle(markdown) {
-  const lines = markdown.split(/\r?\n/);
-  for (const line of lines) {
-    const m = /^(#{1,6})\s+(.*)$/.exec(line);
-    if (m && m[2].trim()) return m[2].trim().slice(0, 120);
-  }
-  for (const line of lines) {
-    const t = line.trim();
-    if (t) return t.slice(0, 120);
-  }
-  return void 0;
-}
-async function mapLimit2(items, limit, mapper) {
-  const results = new Array(items.length);
-  let next = 0;
-  const workers = Array.from({ length: Math.min(Math.max(1, limit), items.length) }, async () => {
-    while (true) {
-      const index = next++;
-      if (index >= items.length) return;
-      results[index] = await mapper(items[index], index);
-    }
-  });
-  await Promise.all(workers);
-  return results;
-}
-function withTimeout2(promise, timeoutMs, label) {
-  let timer;
-  const timeout = new Promise((_, reject) => {
-    timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
-  });
-  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
-}
-
-// src/manager/session.cache.ts
-var SessionCache = class {
-  config;
-  sessions = /* @__PURE__ */ new Map();
-  topicViews = /* @__PURE__ */ new Map();
-  legacyHistoryWindows = /* @__PURE__ */ new Map();
-  constructor(config) {
-    this.config = config;
-  }
-  getEntry(sessionId) {
-    const entry = this.sessions.get(sessionId);
-    if (entry) entry.lastAccessAt = Date.now();
-    return entry;
-  }
-  peekEntry(sessionId) {
-    return this.sessions.get(sessionId);
-  }
-  getOrCreateEntry(sessionId, chatId, userId) {
-    let entry = this.sessions.get(sessionId);
-    if (!entry) {
-      entry = {
-        messages: [],
-        totalTokens: 0,
-        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;
-  }
-  hydrate(sessionId, chatId, userId, messages, topics) {
-    const entry = this.getOrCreateEntry(sessionId, chatId, userId);
-    entry.messages = sortMessages(dedupeMessages(messages));
-    entry.totalTokens = sumMessageTokens(entry.messages);
-    this.setTopics(sessionId, topics, false);
-    return entry;
-  }
-  upsertMessages(sessionId, messages, chatId, userId) {
-    const entry = this.getOrCreateEntry(sessionId, chatId, userId);
-    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;
-    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.getEntry(sessionId)?.messages ?? [];
-  }
-  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;
-  }
-  setTopics(sessionId, topics, truncate = true) {
-    const entry = this.sessions.get(sessionId);
-    if (!entry) return;
-    const ordered = [...topics].sort(topicOrder2);
-    const kept = [];
-    let used = 0;
-    for (let i = ordered.length - 1; i >= 0; i--) {
-      const topic = normalizeTopic(ordered[i]);
-      if (truncate && used + topic.tokens > this.config.compressedContextTokenLimit && kept.length > 0) break;
-      kept.push(topic);
-      used += topic.tokens;
-    }
-    entry.topics = kept.reverse();
-    entry.topicTokens = used;
-    entry.lastAccessAt = Date.now();
-    this.topicViews.delete(sessionId);
-  }
-  appendTopic(sessionId, topic) {
-    const entry = this.sessions.get(sessionId);
-    if (!entry) return;
-    this.setTopics(sessionId, [...entry.topics, topic], false);
-  }
-  replaceTopics(sessionId, removedIds, replacement) {
-    const entry = this.sessions.get(sessionId);
-    if (!entry) return;
-    const ids = new Set(removedIds);
-    this.setTopics(
-      sessionId,
-      [...entry.topics.filter((topic) => !ids.has(topic.summaryId)), replacement],
-      false
-    );
-  }
-  getTopics(sessionId) {
-    return this.getEntry(sessionId)?.topics ?? [];
-  }
-  getTopicView(sessionId, tokenLimit) {
-    return this.topicViews.get(sessionId)?.get(tokenLimit);
+          title = d?.title ?? "";
+        }
+        return { docId, title, matchedChunkCount };
+      })
+    );
+    const graphHits = await this.searchGraph(mode, vector, scope, scopeId, scored);
+    return { chunks: scored, documents, graphHits };
   }
-  setTopicView(sessionId, tokenLimit, topics) {
-    let views = this.topicViews.get(sessionId);
-    if (!views) {
-      views = /* @__PURE__ */ new Map();
-      this.topicViews.set(sessionId, views);
+  async searchGraph(mode, vector, scope, scopeId, topChunks) {
+    if (mode === "fast") return [];
+    if (mode === "auto") {
+      const top = topChunks[0];
+      if (!top || top.score < this.config.knowledgeGraphTriggerScore) return [];
     }
-    views.set(tokenLimit, [...topics].map(normalizeTopic).sort(topicOrder2));
-  }
-  buildCompressedContext(sessionId, topics) {
-    return (topics ?? this.getTopics(sessionId)).map((topic) => topic.title ? `## ${topic.title}
-${topic.summary}` : topic.summary).join("\n\n");
+    const grafeoFilter = {
+      kind: KIND_KNOWLEDGE
+    };
+    if (scope === "user" && scopeId) grafeoFilter.userId = scopeId;
+    if (scope === "chat" && scopeId) grafeoFilter.chatId = scopeId;
+    if (scope === "session" && scopeId) grafeoFilter.sessionId = scopeId;
+    const entities = await this.grafeo.searchEntities(vector, grafeoFilter, this.config.knowledgeGraphEntityTopK).catch(() => []);
+    if (entities.length === 0) return entities;
+    const anchorCount = Math.min(this.config.knowledgeGraphAnchorTopK, entities.length);
+    const relatedArrays = await Promise.all(
+      entities.slice(0, anchorCount).map((e) => {
+        const name = e.meta?.name ?? "";
+        if (!name) return Promise.resolve([]);
+        return this.grafeo.getRelatedEntities(
+          name,
+          grafeoFilter.userId ?? e.meta?.userId ?? "",
+          grafeoFilter.chatId ?? e.meta?.chatId ?? "",
+          this.config.knowledgeGraphHopLimit,
+          KIND_KNOWLEDGE
+        ).catch(() => []);
+      })
+    );
+    return dedupByContent([...entities, ...relatedArrays.flat()]);
   }
-  /** @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;
+  /**
+   * 构建片段表的过滤条件。
+   * - chunkRedundantIds=true：直接在 chunks 行的 user_id/chat_id/session_id 上过滤
+   * - false：先按域查 documents 得到 docId，再用 doc_id IN(...) 过滤
+   * 返回 undefined 表示不过滤；返回 NO_MATCH 表示无候选（应直接返回空结果）。
+   */
+  async buildChunkFilter(scope, scopeId, candidateDocIds) {
+    const parts = [];
+    if (this.config.chunkRedundantIds) {
+      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 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({ op: "in", field: "doc_id", values: docIds });
+      }
     }
-    this.legacyHistoryWindows.set(sessionId, kept.join("\n\n"));
-  }
-  /** @deprecated MemoryManager.getHistoryWindow 返回结构化窗口。 */
-  getHistoryWindow(sessionId) {
-    return this.legacyHistoryWindows.get(sessionId) ?? this.buildCompressedContext(sessionId);
-  }
-  /** @deprecated 仅为 0.3.x 兼容。 */
-  setHistoryWindow(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();
+    return parts.length > 0 ? parts : void 0;
   }
-  getAllSessionIds() {
-    return [...this.sessions.keys()];
+  // ── 读取 / 删除 ─────────────────────────────────────────────────────────────────
+  async getDocument(docId) {
+    return this.store.getDocument(docId);
   }
-  delete(sessionId) {
-    this.sessions.delete(sessionId);
-    this.topicViews.delete(sessionId);
-    this.legacyHistoryWindows.delete(sessionId);
+  async deleteDocument(docId) {
+    const existing = await this.store.getDocument(docId);
+    if (!existing) return false;
+    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) => {
+      console.error(`[KnowledgeManager] Failed to delete knowledge graph for doc ${docId}:`, err);
+    });
+    return true;
   }
-  evictIdle(now, ttlMs, isBusy) {
-    if (ttlMs <= 0) return [];
-    const evicted = [];
-    for (const [sessionId, entry] of this.sessions) {
-      if (now - entry.lastAccessAt < ttlMs || isBusy(sessionId)) continue;
-      this.sessions.delete(sessionId);
-      this.topicViews.delete(sessionId);
-      evicted.push(sessionId);
-    }
-    return evicted;
+  async listDocuments(filter, page) {
+    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);
+    return page ? paginate(docs, page) : docs;
   }
 };
-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) + (message.contextPayload?.length ?? 0)) * 2
-  );
-}
-function sumMessageTokens(messages) {
-  return messages.reduce((sum, message) => sum + effectiveUsage(message), 0);
+var NO_MATCH = Symbol("no-match");
+function dedupByContent(items) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const item of items) {
+    if (seen.has(item.content)) continue;
+    seen.add(item.content);
+    out.push(item);
+  }
+  return out;
 }
-function dedupeMessages(messages) {
-  return [...new Map(messages.map((message) => [message.messageId, message])).values()];
+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 sortMessages(messages) {
-  return messages.sort(
-    (a, b) => a.createdAt - b.createdAt || a.messageId.localeCompare(b.messageId)
-  );
+function inferTitle(markdown) {
+  const lines = markdown.split(/\r?\n/);
+  for (const line of lines) {
+    const m = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (m && m[2].trim()) return m[2].trim().slice(0, 120);
+  }
+  for (const line of lines) {
+    const t = line.trim();
+    if (t) return t.slice(0, 120);
+  }
+  return void 0;
 }
-function topicOrder2(a, b) {
-  return a.endTime - b.endTime || a.summaryId.localeCompare(b.summaryId);
+async function mapLimit2(items, limit, mapper) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(Math.max(1, limit), items.length) }, async () => {
+    while (true) {
+      const index = next++;
+      if (index >= items.length) return;
+      results[index] = await mapper(items[index], index);
+    }
+  });
+  await Promise.all(workers);
+  return results;
 }
-function normalizeTopic(topic) {
-  const summary = topic.summary || topic.detail || topic.concise || "";
-  return {
-    ...topic,
-    summary,
-    tokens: topic.tokens > 0 ? topic.tokens : Math.max(1, countTokens(summary))
-  };
+function withTimeout2(promise, timeoutMs, label) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
 }
 
 // src/memory.manager.ts
@@ -3194,10 +3623,12 @@ var MemoryManager = class {
   sessionSweepTimer;
   optimizeRunning = false;
   optimizeTask;
+  startupMaintenanceTask;
   destroyTask;
   hydration = /* @__PURE__ */ new Map();
   pendingWrites = /* @__PURE__ */ new Map();
   topicCompactions = /* @__PURE__ */ new Map();
+  backgroundCompressions = /* @__PURE__ */ new Map();
   warnedDefaultModelContext = false;
   constructor(config) {
     this.config = resolveConfig(config);
@@ -3252,6 +3683,73 @@ var MemoryManager = class {
       }, this.config.sessionSweepIntervalMs);
       this.sessionSweepTimer.unref?.();
     }
+    const sessionIds = allSessions.map((session) => session.sessionId);
+    const maintenance = this.runStartupMaintenance(sessionIds).catch((error) => {
+      console.warn("[MemoryManager] startup maintenance failed (will retry next init):", error);
+    });
+    this.startupMaintenanceTask = maintenance;
+    void maintenance.finally(() => {
+      if (this.startupMaintenanceTask === maintenance) this.startupMaintenanceTask = void 0;
+    });
+  }
+  async runStartupMaintenance(sessionIds) {
+    if (this.config.autoMigrateLegacyDataOnInit) await this.migrateLegacyDataOnce();
+    if (!this.config.autoResumeCompressionOnInit) return;
+    sessionIds = [.../* @__PURE__ */ new Set([...sessionIds, ...await this.store.getAllSessionIds()])];
+    if (sessionIds.length === 0) return;
+    let cursor = 0;
+    const workerCount = Math.min(this.config.restoreConcurrency, sessionIds.length);
+    await Promise.all(Array.from({ length: workerCount }, async () => {
+      while (cursor < sessionIds.length) {
+        const sessionId = sessionIds[cursor++];
+        const rawLimit = this.calculateWindowUsage(
+          this.config.defaultModelContextTokens
+        ).rawTokenLimit;
+        const rawTokens = await this.getPersistedRawTailTokens(sessionId);
+        if (rawTokens >= Math.floor(rawLimit * this.config.precompressionRatio)) {
+          this.scheduleBackgroundCompression(sessionId, rawLimit, "startup");
+        }
+      }
+    }));
+  }
+  async getPersistedRawTailTokens(sessionId) {
+    const topics = await this.store.getTopicsBySession(sessionId);
+    const latestTopic = topics.at(-1);
+    const messages = 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;
+    return messages.reduce(
+      (sum, message) => sum + (since === 0 || message.createdAt >= since ? effectiveUsage(message) : 0),
+      0
+    );
+  }
+  async migrateLegacyDataOnce() {
+    const marker = this.legacyMigrationMarkerPath();
+    try {
+      await fs.access(marker);
+      return;
+    } catch (error) {
+      if (!isMissingFileError(error)) throw error;
+    }
+    const report = await this.store.migrateLegacyData();
+    await fs.mkdir(path2.dirname(marker), { recursive: true });
+    await fs.writeFile(marker, JSON.stringify({ completedAt: Date.now(), report }), {
+      encoding: "utf8",
+      flag: "wx"
+    }).catch((error) => {
+      if (!isExistingFileError(error)) throw error;
+    });
+    if (report.messagesUpdated > 0) {
+      console.info(
+        `[MemoryManager] startup migration repaired ${report.messagesUpdated} historical message(s).`
+      );
+    }
+  }
+  legacyMigrationMarkerPath() {
+    return this.store.providerKind === "sqlite" ? `${this.config.sqlitePath}.ppagent-memory-v04-migrated` : path2.join(this.config.lancedbPath, ".ppagent-memory-v04-migrated");
   }
   /** 后台压实的统一入口：防重入（上一轮未结束则跳过），失败仅告警不影响服务。*/
   async runBackgroundOptimize(retentionMs) {
@@ -3286,11 +3784,20 @@ var MemoryManager = class {
       task = (async () => {
         const allTopics = await this.store.getTopicsBySession(sessionId);
         const latestTopic = allTopics.at(-1);
-        const allRawAfterBoundary = latestTopic ? await this.store.getMessagesAfterBoundary(
+        const loadedRawAfterBoundary = latestTopic ? await this.store.getMessagesAfterBoundary(
           sessionId,
           latestTopic.endTime,
           latestTopic.endMessageId
         ) : await this.store.getAllMessagesBySession(sessionId);
+        const sanitizedRows = loadedRawAfterBoundary.map(sanitizeStoredMessageImages);
+        const repaired = sanitizedRows.filter((row) => row.changed);
+        if (repaired.length > 0) {
+          await this.store.upsertMessages(repaired.map((row) => row.message));
+          console.info(
+            `[MemoryManager] stripped ${repaired.reduce((sum, row) => sum + row.removedImages, 0)} historical image block(s) from ${repaired.length} message(s) in session ${sessionId}.`
+          );
+        }
+        const allRawAfterBoundary = sanitizedRows.map((row) => row.message);
         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);
@@ -3312,7 +3819,7 @@ var MemoryManager = class {
     await task;
   }
   isSessionBusy(sessionId) {
-    return this.hydration.has(sessionId) || this.pendingWrites.has(sessionId) || [...this.topicCompactions.keys()].some((key) => key.startsWith(`${sessionId}:`)) || this.compressManager.isBusy(sessionId);
+    return this.hydration.has(sessionId) || this.pendingWrites.has(sessionId) || this.backgroundCompressions.has(sessionId) || [...this.topicCompactions.keys()].some((key) => key.startsWith(`${sessionId}:`)) || this.compressManager.isBusy(sessionId);
   }
   waitForPendingWrites(sessionId) {
     return this.pendingWrites.get(sessionId) ?? Promise.resolve();
@@ -3329,6 +3836,77 @@ var MemoryManager = class {
     });
     return task;
   }
+  scheduleBackgroundCompression(sessionId, rawLimit, mode) {
+    if (this.backgroundCompressions.has(sessionId)) return;
+    const maxAttempts = this.config.backgroundCompressionMaxRetries + 1;
+    const task = (async () => {
+      for (let round = 0; round < 100; round++) {
+        await this.ensureSessionHydrated(sessionId);
+        const entry = this.sessionCache.getEntry(sessionId);
+        const threshold = Math.max(1, Math.floor(rawLimit * this.config.precompressionRatio));
+        if (!entry || entry.messages.length === 0 || entry.totalTokens < threshold) return;
+        const beforeTokens = entry.totalTokens;
+        let completed = false;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+          try {
+            await this.compressManager.triggerCompress(
+              sessionId,
+              false,
+              false,
+              rawLimit,
+              mode
+            );
+            completed = true;
+            break;
+          } catch (error) {
+            if (attempt >= maxAttempts) {
+              console.error(
+                `[MemoryManager] Background compress exhausted ${maxAttempts} attempt(s) for ${sessionId}:`,
+                error
+              );
+              return;
+            }
+            const delayMs = Math.min(
+              this.config.backgroundCompressionRetryBaseDelayMs * 2 ** (attempt - 1),
+              6e4
+            );
+            emitCompressionEvent(this.config, {
+              sessionId,
+              kind: "raw",
+              mode,
+              phase: "retry",
+              attempt: attempt + 1,
+              maxAttempts,
+              retryKind: "task",
+              error: formatError2(error)
+            });
+            if (delayMs > 0) await unrefDelay(delayMs);
+          }
+        }
+        if (!completed) return;
+        const after = this.sessionCache.getEntry(sessionId);
+        if (!after || after.messages.length === 0 || after.totalTokens < threshold) return;
+        if (after.totalTokens >= beforeTokens) {
+          console.error(`[MemoryManager] Background compression made no progress for ${sessionId}.`);
+          return;
+        }
+      }
+      console.error(`[MemoryManager] Background compression exceeded 100 batches for ${sessionId}.`);
+    })();
+    const settled = task.catch(() => {
+    });
+    this.backgroundCompressions.set(sessionId, settled);
+    void settled.finally(() => {
+      if (this.backgroundCompressions.get(sessionId) === settled) {
+        this.backgroundCompressions.delete(sessionId);
+      }
+    });
+  }
+  async waitForBackgroundCompressionIdle() {
+    while (this.backgroundCompressions.size > 0) {
+      await Promise.all([...this.backgroundCompressions.values()]);
+    }
+  }
   updateChat(messages, opts) {
     if (messages.length === 0) return Promise.resolve();
     const sessionId = opts?.sessionId ?? messages[0]?.sessionId ?? DEFAULT_SESSION_ID;
@@ -3340,10 +3918,11 @@ var MemoryManager = class {
     const now = Date.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 contextPayload = message.contextPayload === void 0 ? void 0 : JSON.stringify(message.contextPayload);
+      const sanitized = sanitizeRawHistoryFields(message);
+      const parts = JSON.stringify(sanitized.parts);
+      const metadata = JSON.stringify(addCompressionHints(sanitized.metadata, message));
+      const payload = sanitized.payload === void 0 ? void 0 : JSON.stringify(sanitized.payload);
+      const contextPayload = sanitized.contextPayload === void 0 ? void 0 : JSON.stringify(sanitized.contextPayload);
       const tokenInput = [message.content, parts, metadata, payload ?? "", contextPayload ?? ""].join("\n");
       return {
         messageId: message.messageId ?? uuidv44(),
@@ -3356,7 +3935,9 @@ var MemoryManager = class {
         parts,
         payload,
         contextPayload,
-        usage: message.usage ?? countTokens(tokenInput),
+        // Host-provided usage describes the original payload. Once image bytes are
+        // stripped, recalculate against the actual persisted history budget.
+        usage: sanitized.removedImages > 0 ? countTokens(tokenInput) : message.usage ?? countTokens(tokenInput),
         metadata,
         createdAt: message.createdAt ?? now
       };
@@ -3393,9 +3974,7 @@ var MemoryManager = class {
       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);
-      });
+      this.scheduleBackgroundCompression(sessionId, rawLimit, "background");
     }
   }
   async flushChat(sessionId, opts) {
@@ -3410,7 +3989,8 @@ var MemoryManager = class {
       sid,
       true,
       opts?.waitGraph === true,
-      rawLimit
+      rawLimit,
+      "manual"
     );
     if (opts?.wait) await promise;
   }
@@ -3591,7 +4171,8 @@ var MemoryManager = class {
           sessionId,
           true,
           false,
-          usageLimits.rawTokenLimit
+          usageLimits.rawTokenLimit,
+          "blocking"
         );
         const after = this.sessionCache.getEntry(sessionId);
         if (after.messages.length > 0 && after.totalTokens >= beforeTokens) {
@@ -3614,7 +4195,11 @@ var MemoryManager = class {
         if (affectsCurrentWindow || materiallyOverLimit) {
           if (this.compressManager.isBusy(sessionId)) beginBlocking("pending");
           else beginBlocking("topics");
-          await this.compactTopicsForBudget(sessionId, usageLimits.compressedTokenLimit);
+          await this.compactTopicsForBudget(
+            sessionId,
+            usageLimits.compressedTokenLimit,
+            "blocking"
+          );
           entry = this.sessionCache.getEntry(sessionId);
           topicView = this.sessionCache.getTopicView(
             sessionId,
@@ -3623,7 +4208,8 @@ var MemoryManager = class {
         } else {
           void this.compactTopicsForBudget(
             sessionId,
-            usageLimits.compressedTokenLimit
+            usageLimits.compressedTokenLimit,
+            "background"
           ).catch((error) => {
             console.error(`[MemoryManager] Background Topic compaction failed for ${sessionId}:`, error);
           });
@@ -3655,7 +4241,7 @@ var MemoryManager = class {
       }
     }
   }
-  compactTopicsForBudget(sessionId, effectiveLimit) {
+  compactTopicsForBudget(sessionId, effectiveLimit, mode) {
     const key = `${sessionId}:${effectiveLimit}`;
     const existing = this.topicCompactions.get(key);
     if (existing) return existing;
@@ -3666,12 +4252,18 @@ var MemoryManager = class {
         await this.compressManager.triggerTopicCompaction(
           sessionId,
           this.config.compressedContextTokenLimit,
-          true
+          true,
+          mode
         );
         entry = this.sessionCache.getEntry(sessionId);
       }
       if (entry && entry.topicTokens > effectiveLimit && !this.sessionCache.getTopicView(sessionId, effectiveLimit)) {
-        await this.compressManager.triggerTopicCompaction(sessionId, effectiveLimit, false);
+        await this.compressManager.triggerTopicCompaction(
+          sessionId,
+          effectiveLimit,
+          false,
+          mode
+        );
       }
     })();
     this.topicCompactions.set(key, task);
@@ -3878,12 +4470,13 @@ var MemoryManager = class {
       clearInterval(this.sessionSweepTimer);
       this.sessionSweepTimer = void 0;
     }
-    const writes = [
+    this.destroyTask = Promise.resolve(this.startupMaintenanceTask).catch(() => {
+    }).then(() => Promise.all([
       ...this.pendingWrites.values(),
       ...this.hydration.values(),
       ...this.topicCompactions.values()
-    ];
-    this.destroyTask = Promise.all(writes).catch(() => {
+    ])).catch(() => {
+    }).then(() => this.waitForBackgroundCompressionIdle()).catch(() => {
     }).then(() => this.compressManager.waitForAllIdle()).catch(() => {
     }).then(() => this.optimizeTask).catch(() => {
     }).then(async () => {
@@ -3895,23 +4488,31 @@ var MemoryManager = class {
   }
 };
 function toMemoryRawMessage(message) {
-  const parts = safeParseArray(message.parts);
-  const payload = message.payload === void 0 ? void 0 : safeParseValue(message.payload);
-  const contextPayload = message.contextPayload === void 0 ? void 0 : safeParseValue(message.contextPayload);
+  const sanitized = sanitizeStoredMessageImages(message).message;
+  const parts = safeParseArray(sanitized.parts);
+  const payload = sanitized.payload === void 0 ? void 0 : safeParseValue(sanitized.payload);
+  const contextPayload = sanitized.contextPayload === void 0 ? void 0 : safeParseValue(sanitized.contextPayload);
+  const hints = readCompressionHints(sanitized);
   return {
-    messageId: message.messageId,
-    talkerId: message.talkerId,
-    chatId: message.chatId,
-    userId: message.userId,
-    sessionId: message.sessionId,
-    type: message.type,
-    content: message.content,
+    messageId: sanitized.messageId,
+    talkerId: sanitized.talkerId,
+    chatId: sanitized.chatId,
+    userId: sanitized.userId,
+    sessionId: sanitized.sessionId,
+    type: sanitized.type,
+    content: sanitized.content,
     ...parts.length > 0 && { parts },
     ...payload !== void 0 && { payload },
     ...contextPayload !== void 0 && { contextPayload },
-    usage: message.usage,
-    metadata: safeParseObject2(message.metadata),
-    createdAt: message.createdAt
+    ...hints.compressionGroupId !== void 0 && {
+      compressionGroupId: hints.compressionGroupId
+    },
+    ...hints.explicitCompressionRole !== void 0 && {
+      compressionRole: hints.explicitCompressionRole
+    },
+    usage: sanitized.usage,
+    metadata: hints.metadata,
+    createdAt: sanitized.createdAt
   };
 }
 function buildCompressionRevision(topics, messages) {
@@ -3950,6 +4551,21 @@ function safeParseValue(value) {
     return value;
   }
 }
+function formatError2(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function isMissingFileError(error) {
+  return error?.code === "ENOENT";
+}
+function isExistingFileError(error) {
+  return error?.code === "EEXIST";
+}
+function unrefDelay(ms) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+  });
+}
 export {
   DEFAULT_NODE_TYPES,
   DEFAULT_RELATION_TYPES,