@ppagent/memory 0.4.5 → 0.4.6

package/dist/cli.js

@@ -51,7 +51,7 @@ function resolveConfig(config) {
       "topicCompactionSyncRatio"
     ),
     contextUsageRatio: ratio(config.contextUsageRatio ?? 0.75, "contextUsageRatio"),
-    precompressionRatio: ratio(config.precompressionRatio ?? 0.75, "precompressionRatio"),
+    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(
@@ -62,6 +62,16 @@ function resolveConfig(config) {
       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"
@@ -98,6 +108,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

package/dist/index.d.ts

@@ -2,6 +2,26 @@ type MessageType = "text" | "image" | "file";
 type FactLevel = "user" | "chat";
 type SearchMode = "fast" | "auto" | "all";
 type SearchScope = "session" | "chat" | "user" | "all";
+type CompressionRole = "user" | "assistant" | "tool" | "system";
+type MemoryCompressionKind = "raw" | "topics";
+type MemoryCompressionMode = "background" | "blocking" | "manual" | "startup";
+type MemoryCompressionPhase = "start" | "retry" | "success" | "failure";
+interface MemoryCompressionEvent {
+    sessionId: string;
+    kind: MemoryCompressionKind;
+    mode: MemoryCompressionMode;
+    phase: MemoryCompressionPhase;
+    /** 当前尝试序号，从 1 开始。 */
+    attempt: number;
+    /** 本层最多尝试次数。 */
+    maxAttempts: number;
+    inputTokens?: number;
+    selectedTokens?: number;
+    outputTokens?: number;
+    durationMs?: number;
+    retryKind?: "semantic" | "task";
+    error?: string;
+}
 /**
  * 分页参数（可选）。
  * - offset：起始偏移，从 0 开始（负数按 0 处理）。
@@ -67,6 +87,13 @@ interface RawMessage {
      * Topic 摘要或知识图谱抽取。适合保存 provider-ready 工具协议消息等大体积细节。
      */
     contextPayload?: unknown;
+    /**
+     * 同一个完整对话轮次（含 user、assistant 与 tool 链）应使用相同 id。
+     * 压缩只会在 group 边界切分；省略时按 compressionRole/talkerId 兼容推断。
+     */
+    compressionGroupId?: string;
+    /** 消息在对话轮次中的角色，用于旧数据缺少显式 group id 时推断完整边界。 */
+    compressionRole?: CompressionRole;
     usage?: number;
     metadata?: Record<string, unknown>;
     createdAt?: number;
@@ -245,6 +272,8 @@ interface MemoryRawMessage {
     parts?: ContentPart[];
     payload?: unknown;
     contextPayload?: unknown;
+    compressionGroupId?: string;
+    compressionRole?: CompressionRole;
     usage: number;
     metadata?: Record<string, unknown>;
     createdAt: number;
@@ -419,7 +448,7 @@ interface MemoryConfig {
     topicCompactionSyncRatio?: number;
     /** 模型上下文中允许历史记忆使用的比例，默认 0.75。 */
     contextUsageRatio?: number;
-    /** 原始消息达到其可用预算的此比例时后台预压缩，默认 0.75。 */
+    /** 原始消息达到其可用预算的此比例时后台预压缩，默认 0.6。 */
     precompressionRatio?: number;
     /** 单次压缩目标占当前未压缩消息 token 总量的比例，默认 0.7（压 7 留 3）。 */
     compressionBatchRatio?: number;
@@ -429,6 +458,12 @@ interface MemoryConfig {
     compressionMaxRetries?: number;
     /** 压缩结果级重试的指数退避基数（毫秒），默认 500；0 表示不等待。 */
     compressionRetryBaseDelayMs?: number;
+    /** 后台压缩整任务失败后的最大重试次数，默认 2（即最多执行 3 轮任务）。 */
+    backgroundCompressionMaxRetries?: number;
+    /** 后台压缩整任务重试的指数退避基数（毫秒），默认 1000；0 表示立即重试。 */
+    backgroundCompressionRetryBaseDelayMs?: number;
+    /** 压缩生命周期事件；回调异常会被隔离，不影响记忆读写。 */
+    onCompressionEvent?: (event: MemoryCompressionEvent) => void | Promise<void>;
     /** 单条 Topic 摘要硬上限，实际长度由重要性决定，默认 2048。 */
     topicSummaryMaxTokens?: number;
     /** 未传 getHistoryWindow 模型窗口时使用，默认 256K。 */
@@ -494,6 +529,10 @@ interface MemoryConfig {
      * 不阻塞启动；嵌入式单进程使用时建议保持开启，否则 LanceDB 版本目录会无限膨胀、启动越来越慢。
      */
     autoOptimizeOnInit?: boolean;
+    /** init 后是否在后台幂等执行一次 0.4 历史数据迁移（含历史图片剥离），默认 true。 */
+    autoMigrateLegacyDataOnInit?: boolean;
+    /** init 后是否后台扫描未完成的原始窗口并恢复自动压缩，默认 true。 */
+    autoResumeCompressionOnInit?: boolean;
     /**
      * 运行期定期压实的间隔（毫秒，默认 6 小时；设为 0 或负数关闭定时任务）。
      * 长驻服务不重启时版本仍会随写入累积，靠该定时任务周期性回收。
@@ -688,13 +727,19 @@ declare class MemoryManager {
     private sessionSweepTimer?;
     private optimizeRunning;
     private optimizeTask?;
+    private startupMaintenanceTask?;
     private destroyTask?;
     private readonly hydration;
     private readonly pendingWrites;
     private readonly topicCompactions;
+    private readonly backgroundCompressions;
     private warnedDefaultModelContext;
     constructor(config: MemoryConfig);
     init(): Promise<void>;
+    private runStartupMaintenance;
+    private getPersistedRawTailTokens;
+    private migrateLegacyDataOnce;
+    private legacyMigrationMarkerPath;
     /** 后台压实的统一入口：防重入（上一轮未结束则跳过），失败仅告警不影响服务。*/
     private runBackgroundOptimize;
     /**
@@ -706,6 +751,8 @@ declare class MemoryManager {
     private isSessionBusy;
     private waitForPendingWrites;
     private queueSessionWrite;
+    private scheduleBackgroundCompression;
+    private waitForBackgroundCompressionIdle;
     updateChat(messages: RawMessage[], opts?: UpdateChatOptions): Promise<void>;
     private doUpdateChat;
     flushChat(sessionId?: string, opts?: {
@@ -1023,4 +1070,4 @@ type RelationType = (typeof DEFAULT_RELATION_TYPES)[number];
 declare const KIND_CONVERSATION = "conversation";
 declare const KIND_KNOWLEDGE = "knowledge";
 
-export { type AddDocumentOptions, type BuildGraphMode, type Chunk, type ChunkHit, type ChunkPiece, type CompressOutput, type ContentPart, DEFAULT_NODE_TYPES, DEFAULT_RELATION_TYPES, type Document, type DomainIds, type Entity, type EntityMeta, type Fact, type FactLevel, type Filter, type FilterCondition, type GetHistoryWindowOptions, KIND_CONVERSATION, KIND_KNOWLEDGE, type KnowledgeSearchOptions, type KnowledgeSearchResult, type MemoryBlockingCompressionEvent, type MemoryBlockingCompressionReason, type MemoryConfig, type MemoryContextBudget, type MemoryContextWindow, type MemoryContextWindowUsage, MemoryManager, type MemoryMigrationReport, type MemoryRawMessage, MemoryStore, type MessageType, type NodeType, type PageParams, type Paginated, type ProviderCapabilities, type ProviderKind, type RawMessage, type Relation, type RelationType, type SearchMode, type SearchOptions, type SearchResult, type SearchScope, type Session, type SessionEntry, type SessionSearchOptions, type SessionView, type StorageOptimizeResult, type StoredMessage, type Topic, type UpdateChatOptions, type UpdateEntityOptions, type UpdateSessionOptions, type VectorStoreProvider, calculateContextBudget };
+export { type AddDocumentOptions, type BuildGraphMode, type Chunk, type ChunkHit, type ChunkPiece, type CompressOutput, type CompressionRole, type ContentPart, DEFAULT_NODE_TYPES, DEFAULT_RELATION_TYPES, type Document, type DomainIds, type Entity, type EntityMeta, type Fact, type FactLevel, type Filter, type FilterCondition, type GetHistoryWindowOptions, KIND_CONVERSATION, KIND_KNOWLEDGE, type KnowledgeSearchOptions, type KnowledgeSearchResult, type MemoryBlockingCompressionEvent, type MemoryBlockingCompressionReason, type MemoryCompressionEvent, type MemoryCompressionKind, type MemoryCompressionMode, type MemoryCompressionPhase, type MemoryConfig, type MemoryContextBudget, type MemoryContextWindow, type MemoryContextWindowUsage, MemoryManager, type MemoryMigrationReport, type MemoryRawMessage, MemoryStore, type MessageType, type NodeType, type PageParams, type Paginated, type ProviderCapabilities, type ProviderKind, type RawMessage, type Relation, type RelationType, type SearchMode, type SearchOptions, type SearchResult, type SearchScope, type Session, type SessionEntry, type SessionSearchOptions, type SessionView, type StorageOptimizeResult, type StoredMessage, type Topic, type UpdateChatOptions, type UpdateEntityOptions, type UpdateSessionOptions, type VectorStoreProvider, calculateContextBudget };

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,7 +49,7 @@ function resolveConfig(config) {
       "topicCompactionSyncRatio"
     ),
     contextUsageRatio: ratio(config.contextUsageRatio ?? 0.75, "contextUsageRatio"),
-    precompressionRatio: ratio(config.precompressionRatio ?? 0.75, "precompressionRatio"),
+    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(
@@ -58,6 +60,16 @@ function resolveConfig(config) {
       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"
@@ -94,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
@@ -2315,6 +2329,300 @@ function isRecord2(value) {
 // src/manager/compress.manager.ts
 import { v4 as uuidv4 } from "uuid";
 
+// 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 {};
+  }
+}
+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;
+  }
+  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 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;
+  }
+  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();
+    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;
@@ -2349,6 +2657,20 @@ var Semaphore = class {
   }
 };
 
+// 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) {
@@ -2363,19 +2685,70 @@ var CompressManager = class {
   semaphore;
   sessionChain = /* @__PURE__ */ new Map();
   backgroundGraphs = /* @__PURE__ */ new Set();
-  triggerCompress(sessionId, force = false, waitGraph = false, rawLimit) {
-    return this.enqueueSessionTask(
+  triggerCompress(sessionId, force = false, waitGraph = false, rawLimit, mode = "background") {
+    const startedAt = Date.now();
+    const task = this.enqueueSessionTask(
       sessionId,
-      () => this.doCompress(sessionId, force, waitGraph, rawLimit)
+      () => 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) {
-    return this.enqueueSessionTask(
+  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)
+      () => 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(
@@ -2403,7 +2776,7 @@ var CompressManager = class {
       ]);
     }
   }
-  async doCompress(sessionId, force, waitGraph, rawLimitOverride) {
+  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));
@@ -2418,12 +2791,29 @@ var CompressManager = class {
     }
     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)
+        () => this.llm.summarizeMessages(messages),
+        "raw",
+        mode
       );
     } catch (error) {
       console.error(
@@ -2462,7 +2852,8 @@ var CompressManager = class {
     await this.compactOldTopics(
       sessionId,
       this.config.compressedContextTokenLimit,
-      true
+      true,
+      mode
     );
     const graphTask = this.extractAndPersistGraph(
       messages,
@@ -2480,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);
@@ -2516,7 +2919,9 @@ var CompressManager = class {
       const result = await this.summarizeWithRetry(
         sessionId,
         "Topic compaction",
-        () => this.llm.summarizeTopics(selected, maxSummaryTokens)
+        () => this.llm.summarizeTopics(selected, maxSummaryTokens),
+        "topics",
+        mode
       );
       const summary = result.summary.trim();
       const vector = persist ? await this.embed.embedOne(summary).catch(() => []) : [];
@@ -2555,7 +2960,7 @@ var CompressManager = class {
         transientTopics = [
           ...topics.filter((topic) => !ids.has(topic.summaryId)),
           rollup
-        ].sort(topicOrder);
+        ].sort(topicOrder2);
       }
     }
   }
@@ -2596,7 +3001,7 @@ var CompressManager = class {
    * 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) {
+  async summarizeWithRetry(sessionId, label, operation, kind, mode) {
     let lastError;
     for (let attempt = 0; attempt <= this.config.compressionMaxRetries; attempt++) {
       try {
@@ -2617,6 +3022,16 @@ var CompressManager = class {
         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);
       }
     }
@@ -2626,7 +3041,7 @@ var CompressManager = class {
 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) {
@@ -3192,228 +3607,6 @@ function withTimeout2(promise, timeoutMs, label) {
   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;
-    const selectableCount = messages.length > 1 ? messages.length - 1 : 1;
-    for (const message of messages.slice(0, selectableCount)) {
-      const nextTokens = tokens + effectiveUsage(message);
-      if (selected.length > 0 && Math.abs(targetTokens - tokens) <= Math.abs(targetTokens - nextTokens)) {
-        break;
-      }
-      selected.push(message);
-      tokens = nextTokens;
-      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);
-  }
-  setTopicView(sessionId, tokenLimit, topics) {
-    let views = this.topicViews.get(sessionId);
-    if (!views) {
-      views = /* @__PURE__ */ new Map();
-      this.topicViews.set(sessionId, views);
-    }
-    views.set(tokenLimit, [...topics].map(normalizeTopic).sort(topicOrder2));
-  }
-  buildCompressedContext(sessionId, topics) {
-    return (topics ?? this.getTopics(sessionId)).map((topic) => topic.title ? `## ${topic.title}
-${topic.summary}` : topic.summary).join("\n\n");
-  }
-  /** @deprecated 三级窗口兼容，仅供 0.3.x 调用方过渡。 */
-  buildHistoryWindow(sessionId, groups) {
-    const [detailCount, summaryCount, conciseCount] = this.config.topicRatio;
-    const values = [
-      ...groups.detail.slice(0, detailCount).map((topic) => topic.detail ?? topic.summary),
-      ...groups.summary.slice(0, summaryCount).map((topic) => topic.summary),
-      ...groups.concise.slice(0, conciseCount).map((topic) => topic.concise ?? topic.summary)
-    ];
-    let remaining = this.config.historyWindowTokenLimit;
-    const kept = [];
-    for (const value of values) {
-      const tokens = countTokens(value);
-      if (tokens > remaining) break;
-      kept.push(value);
-      remaining -= tokens;
-    }
-    this.legacyHistoryWindows.set(sessionId, kept.join("\n\n"));
-  }
-  /** @deprecated MemoryManager.getHistoryWindow 返回结构化窗口。 */
-  getHistoryWindow(sessionId) {
-    return this.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 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 topicOrder2(a, b) {
-  return a.endTime - b.endTime || a.summaryId.localeCompare(b.summaryId);
-}
-function normalizeTopic(topic) {
-  const summary = topic.summary || topic.detail || topic.concise || "";
-  return {
-    ...topic,
-    summary,
-    tokens: topic.tokens > 0 ? topic.tokens : Math.max(1, countTokens(summary))
-  };
-}
-
 // src/memory.manager.ts
 var MemoryManager = class {
   config;
@@ -3430,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);
@@ -3488,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) {
@@ -3557,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();
@@ -3574,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;
@@ -3587,7 +3920,7 @@ var MemoryManager = class {
     const normalized = messages.map((message) => {
       const sanitized = sanitizeRawHistoryFields(message);
       const parts = JSON.stringify(sanitized.parts);
-      const metadata = JSON.stringify(sanitized.metadata);
+      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");
@@ -3641,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) {
@@ -3658,7 +3989,8 @@ var MemoryManager = class {
       sid,
       true,
       opts?.waitGraph === true,
-      rawLimit
+      rawLimit,
+      "manual"
     );
     if (opts?.wait) await promise;
   }
@@ -3839,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) {
@@ -3862,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,
@@ -3871,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);
           });
@@ -3903,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;
@@ -3914,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);
@@ -4126,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 () => {
@@ -4147,6 +4492,7 @@ function toMemoryRawMessage(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: sanitized.messageId,
     talkerId: sanitized.talkerId,
@@ -4158,8 +4504,14 @@ function toMemoryRawMessage(message) {
     ...parts.length > 0 && { parts },
     ...payload !== void 0 && { payload },
     ...contextPayload !== void 0 && { contextPayload },
+    ...hints.compressionGroupId !== void 0 && {
+      compressionGroupId: hints.compressionGroupId
+    },
+    ...hints.explicitCompressionRole !== void 0 && {
+      compressionRole: hints.explicitCompressionRole
+    },
     usage: sanitized.usage,
-    metadata: safeParseObject2(sanitized.metadata),
+    metadata: hints.metadata,
     createdAt: sanitized.createdAt
   };
 }
@@ -4199,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,

package/llms.txt

@@ -339,16 +339,22 @@ Conversation memory fields:
 - `compressedContextRatio?: number` - maximum fraction of the usable model-history window assigned to Topics. Default: `0.10`. The effective Topic budget is the smaller of this ratio and `compressedContextTokenLimit`.
 - `topicCompactionSyncRatio?: number` - a cold-start Topic overage blocks `getHistoryWindow` only after it exceeds this multiple of the effective Topic budget, unless Topic plus raw history already exceeds the usable window. Default: `1.25`.
 - `contextUsageRatio?: number` - fraction of the current model context available to conversation history. Default: `0.75`.
-- `precompressionRatio?: number` - start background raw-message compression when raw usage reaches this fraction of its dynamic budget. Default: `0.75`.
-- `compressionBatchRatio?: number` - target fraction of the current uncompressed raw-message tokens compressed from the oldest edge in one batch. Default: `0.7`, leaving the newest approximately `0.3` verbatim; message boundaries are atomic.
+- `precompressionRatio?: number` - start background raw-message compression when raw usage reaches this fraction of its dynamic budget. Default: `0.60`, leaving enough headroom for normal runs while compression finishes.
+- `compressionBatchRatio?: number` - target fraction of the current uncompressed raw-message tokens compressed from the oldest edge in one batch. Default: `0.7`, leaving the newest approximately `0.3` verbatim; complete conversation-group boundaries are atomic.
 - `compressionBatchTokenLimit?: number` - optional hard limit for one compression batch. Default: `0` (ratio only).
 - `compressionMaxRetries?: number` - result-level retry count after the first compression-model attempt when the returned content is malformed, missing a summary, or empty. Default: `2`. Transport failures do not multiply this count because the HTTP layer already owns bounded retries.
 - `compressionRetryBaseDelayMs?: number` - exponential-backoff base for result-level compression retries. Default: `500`; set `0` to retry immediately.
+- `backgroundCompressionMaxRetries?: number` - whole-task retries after a background compression still fails (including exhausted HTTP attempts). Default: `2`, so at most three task waves run.
+- `backgroundCompressionRetryBaseDelayMs?: number` - exponential-backoff base for whole-task background retries. Default: `1000`; set `0` to retry immediately.
+- `onCompressionEvent?: (event) => void | Promise<void>` - receives contained raw/Topic compression `start`, `retry`, `success`, and `failure` lifecycle events with mode, attempts, token counts, latency, and error text. Callback failures never fail memory work.
 - `topicSummaryMaxTokens?: number` - hard maximum for one Topic summary. The LLM uses less for low-value chat and more for facts, experience, decisions, preferences, constraints, and reusable knowledge. Default: `2048`.
 - `defaultModelContextTokens?: number` - used when `getHistoryWindow` receives no model size; a warning is logged. Default: `262144`.
 - `maxHistoryAgeMs?: number` - maximum Topic and raw-message age restored during lazy cold start. Default: `0` (all history).
 - `sessionIdleTtlMs?: number` - idle time before a session cache is released. Persistent data is not deleted. Default: `1800000`.
 - `sessionSweepIntervalMs?: number` - idle cache sweep interval. Default: `60000`.
+- `autoMigrateLegacyDataOnInit?: boolean` - run the idempotent 0.4 storage migration in the background once per data store, including full historical-image stripping. Default: `true`; a sidecar marker prevents a full scan on every restart.
+- `autoResumeCompressionOnInit?: boolean` - scan persisted sessions in the background and resume raw windows that were eligible but not compressed before shutdown/failure. Default: `true`.
+- `restoreConcurrency?: number` - bounded startup migration/recovery scan concurrency. Default: `8`.
 - `maxConcurrentCompressions?: number` - global semaphore limit for concurrent compression and knowledge ingestion tasks. Default: `3`.
 - `entitySimilarityThreshold?: number` - graph entity similarity threshold. Default: `0.92`.
 - `defaultSearchLimit?: number` - default `search` result limit. Default: `10`.
@@ -379,12 +385,14 @@ The package intentionally separates durable base writes from expensive graph con
 
 - Registers its write synchronously, so a caller may intentionally fire-and-forget it and a following `getHistoryWindow` will still wait for that write.
 - Recursively strips known historical image blocks (`image*` content parts and `file` parts with `image/*` media types) from `parts`, `payload`, `contextPayload`, and `metadata`, while preserving adjacent text, tool protocol, and non-image files. Legacy image rows are lazily repaired and written back when a session is first hydrated; the manual migration command performs the same repair.
+- Persists optional `compressionGroupId` / `compressionRole` hints in a reserved internal metadata namespace and removes that namespace again on read. Host metadata remains unchanged.
 - Calculates tokens over the sanitized `content`, `parts`, `payload`, `contextPayload`, and `metadata`, embeds only the searchable text, and upserts raw messages by stable `messageId` before resolving. If image removal changes a host payload, any host-supplied usage is recalculated against the stored form.
 - `contextPayload` is a replay-only host payload: its non-image structure is stored and returned and counts toward the raw budget, but it is excluded from embedding, FTS, Topic-summary input, and conversation graph extraction.
 - Raw-message token usage counts the complete sanitized stored `metadata`. When a raw batch is summarized, common tool-call/tool-result fields are removed only from the temporary LLM compression input; persisted non-image metadata and uncompressed `recentMessages` remain unchanged.
 - Creates or updates the session record.
 - Updates the in-memory session cache.
-- Once `getHistoryWindow` has supplied the current model size, reaching the precompression threshold starts background compression.
+- Reaching the dynamic precompression threshold starts background compression. A failed task is retried with finite exponential backoff, and an unfinished eligible tail is discovered again during the next startup scan.
+- Compression selects an oldest prefix of complete conversation groups. Explicit group ids are authoritative; older rows fall back to `user`/`assistant`/`tool`/`system` role inference. The newest complete group is kept verbatim whenever another group exists.
 - Topic storage and cache replacement finish before conversation graph extraction; graph work remains asynchronous.
 
 `flushChat(sessionId?, opts?)`:
@@ -432,6 +440,8 @@ Use `wait: true` when the next line of code must immediately call `searchKnowled
 - `parts?: ContentPart[]` - optional multimodal content parts; non-image parts are stored serialized.
 - `payload?: unknown` - host-framework message payload stored and returned after recursive historical-image stripping.
 - `contextPayload?: unknown` - replay-only host context stored and returned after recursive historical-image stripping. Its remaining content counts toward the raw history budget but is excluded from retrieval, compression summaries, and graph extraction.
+- `compressionGroupId?: string` - stable id shared by a user message and all assistant/tool messages in the same complete turn. Compression never splits this group.
+- `compressionRole?: "user" | "assistant" | "tool" | "system"` - explicit role used for compatible grouping when no group id is supplied.
 - `usage?: number` - token count; estimated with `tiktoken` if omitted.
 - `metadata?: Record<string, unknown>` - custom metadata stored as JSON.
 - `createdAt?: number` - Unix milliseconds; default is current time.
@@ -528,7 +538,7 @@ Creates the manager and resolves defaults. It does not connect to storage until
 
 ### `init(): Promise<void>`
 
-Initializes tiktoken, the vector store (backend auto-detection happens here), Grafeo, and the facts cache. Conversation sessions are hydrated lazily on first access and evicted after the configured idle timeout. Always call before using read/write APIs.
+Initializes tiktoken, the vector store (backend auto-detection happens here), Grafeo, and the facts cache. It then starts non-blocking startup maintenance: a marker-guarded full legacy/image migration and a bounded scan that resumes eligible unfinished compression. Conversation sessions remain available immediately and are evicted after the configured idle timeout. Always call before using read/write APIs.
 
 ### `updateChat(messages, opts?): Promise<void>`
 
@@ -737,7 +747,7 @@ Lists documents, optionally filtered by:
 
 ### `destroy(): Promise<void>`
 
-Waits for registered writes, compression, graph work, and storage maintenance, then closes Grafeo and the vector store. It does not delete data.
+Waits for registered writes, startup recovery, finite background compression retries, graph work, and storage maintenance, then closes Grafeo and the vector store. It does not delete data.
 
 ## Common Recipes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ppagent/memory",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "独立记忆系统模块，向量存储支持 LanceDB / SQLite(sqlite-vec) 双后端自动切换 + Grafeo 知识图谱",
   "type": "module",
   "main": "dist/index.js",