@ppagent/memory 0.4.0 → 0.4.1

package/dist/cli.js

@@ -42,6 +42,14 @@ function resolveConfig(config) {
     summaryMaxTokens: config.summaryMaxTokens ?? 512,
     conciseMaxTokens: config.conciseMaxTokens ?? 128,
     compressedContextTokenLimit,
+    compressedContextRatio: ratio(
+      config.compressedContextRatio ?? 0.1,
+      "compressedContextRatio"
+    ),
+    topicCompactionSyncRatio: atLeastOne(
+      config.topicCompactionSyncRatio ?? 1.25,
+      "topicCompactionSyncRatio"
+    ),
     contextUsageRatio: ratio(config.contextUsageRatio ?? 0.75, "contextUsageRatio"),
     precompressionRatio: ratio(config.precompressionRatio ?? 0.75, "precompressionRatio"),
     compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.5, "compressionBatchRatio"),
@@ -99,6 +107,12 @@ function positiveInt(value, name) {
   }
   return Math.floor(value);
 }
+function atLeastOne(value, name) {
+  if (!Number.isFinite(value) || value < 1) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u5927\u4E8E\u7B49\u4E8E 1 \u7684\u6709\u9650\u6570`);
+  }
+  return value;
+}
 
 // src/db/store.types.ts
 function eq(field, value) {

package/dist/index.d.ts

@@ -248,6 +248,16 @@ interface MemoryContextWindowUsage {
     rawTokenLimit: number;
     rawTokens: number;
 }
+type MemoryBlockingCompressionReason = "pending" | "raw" | "topics";
+interface MemoryBlockingCompressionEvent {
+    sessionId: string;
+    phase: "start" | "end";
+    reason: MemoryBlockingCompressionReason;
+}
+interface GetHistoryWindowOptions {
+    /** 仅当前读取确实被压缩阻塞时调用；回调异常不会影响记忆读取。 */
+    onBlockingCompression?: (event: MemoryBlockingCompressionEvent) => void;
+}
 /** 固定预算的压缩记忆 + 近期未压缩原始消息。 */
 interface MemoryContextWindow {
     sessionId: string;
@@ -387,8 +397,12 @@ interface MemoryConfig {
     embeddingBatchSize?: number;
     /** embedding 批次并发数（默认 2）。*/
     embeddingConcurrency?: number;
-    /** 压缩 Topic 在历史窗口中的固定预算，默认 16K。 */
+    /** 压缩 Topic 的全局存储上限，默认 16K。 */
     compressedContextTokenLimit?: number;
+    /** Topic 最多占本次可用模型上下文的比例，默认 0.10。 */
+    compressedContextRatio?: number;
+    /** Topic 超过本次有效预算多少倍后必须同步归并，默认 1.25。 */
+    topicCompactionSyncRatio?: number;
     /** 模型上下文中允许历史记忆使用的比例，默认 0.75。 */
     contextUsageRatio?: number;
     /** 原始消息达到其可用预算的此比例时后台预压缩，默认 0.75。 */
@@ -659,6 +673,7 @@ declare class MemoryManager {
     private destroyTask?;
     private readonly hydration;
     private readonly pendingWrites;
+    private readonly topicCompactions;
     private warnedDefaultModelContext;
     constructor(config: MemoryConfig);
     init(): Promise<void>;
@@ -695,7 +710,9 @@ declare class MemoryManager {
      * 返回 user 级(userId) ∪ chat 级(chatId)，按时间正序拼接。
      */
     getFactsForContext(userId: string, chatId: string): Promise<string>;
-    getHistoryWindow(sessionId: string, modelContextTokens?: number): Promise<MemoryContextWindow>;
+    getHistoryWindow(sessionId: string, modelContextTokens?: number, options?: GetHistoryWindowOptions): Promise<MemoryContextWindow>;
+    private compactTopicsForBudget;
+    private notifyBlockingCompression;
     private calculateWindowUsage;
     private buildScopeFilter;
     private deserializeSession;
@@ -836,6 +853,20 @@ declare class MemoryManager {
     destroy(): Promise<void>;
 }
 
+interface MemoryContextBudget {
+    modelContextTokens: number;
+    usableContextTokens: number;
+    compressedTokenLimit: number;
+    rawTokenLimit: number;
+}
+/**
+ * 统一计算一次 history window 的 Topic / raw 预算。
+ *
+ * Topic 同时受全局质量上限和当前模型比例约束；最后保留至少 1 token raw 空间，
+ * 避免小窗口模型被固定 Topic 上限完全挤空。
+ */
+declare function calculateContextBudget(config: Pick<ResolvedConfig, "contextUsageRatio" | "compressedContextRatio" | "compressedContextTokenLimit">, modelContextTokens: number): MemoryContextBudget;
+
 interface MemoryMigrationReport {
     provider: string;
     topicsScanned: number;
@@ -974,4 +1005,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, KIND_CONVERSATION, KIND_KNOWLEDGE, type KnowledgeSearchOptions, type KnowledgeSearchResult, type MemoryConfig, 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 };
+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 };

package/dist/index.js

@@ -38,6 +38,14 @@ function resolveConfig(config) {
     summaryMaxTokens: config.summaryMaxTokens ?? 512,
     conciseMaxTokens: config.conciseMaxTokens ?? 128,
     compressedContextTokenLimit,
+    compressedContextRatio: ratio(
+      config.compressedContextRatio ?? 0.1,
+      "compressedContextRatio"
+    ),
+    topicCompactionSyncRatio: atLeastOne(
+      config.topicCompactionSyncRatio ?? 1.25,
+      "topicCompactionSyncRatio"
+    ),
     contextUsageRatio: ratio(config.contextUsageRatio ?? 0.75, "contextUsageRatio"),
     precompressionRatio: ratio(config.precompressionRatio ?? 0.75, "precompressionRatio"),
     compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.5, "compressionBatchRatio"),
@@ -95,6 +103,41 @@ function positiveInt(value, name) {
   }
   return Math.floor(value);
 }
+function atLeastOne(value, name) {
+  if (!Number.isFinite(value) || value < 1) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u5927\u4E8E\u7B49\u4E8E 1 \u7684\u6709\u9650\u6570`);
+  }
+  return value;
+}
+
+// src/context-budget.ts
+function calculateContextBudget(config, modelContextTokens) {
+  if (!Number.isFinite(modelContextTokens) || modelContextTokens <= 0) {
+    throw new Error("modelContextTokens \u5FC5\u987B\u662F\u6B63\u6570");
+  }
+  const normalizedModelTokens = Math.floor(modelContextTokens);
+  const usableContextTokens = Math.floor(normalizedModelTokens * config.contextUsageRatio);
+  if (usableContextTokens < 2) {
+    throw new Error(
+      `modelContextTokens=${normalizedModelTokens} \u5728 contextUsageRatio=${config.contextUsageRatio} \u4E0B\u4E0D\u8DB3\u4EE5\u540C\u65F6\u4FDD\u7559 Topic \u4E0E\u539F\u59CB\u6D88\u606F\u9884\u7B97`
+    );
+  }
+  const ratioLimit = Math.max(
+    1,
+    Math.floor(usableContextTokens * config.compressedContextRatio)
+  );
+  const compressedTokenLimit = Math.min(
+    config.compressedContextTokenLimit,
+    ratioLimit,
+    usableContextTokens - 1
+  );
+  return {
+    modelContextTokens: normalizedModelTokens,
+    usableContextTokens,
+    compressedTokenLimit,
+    rawTokenLimit: usableContextTokens - compressedTokenLimit
+  };
+}
 
 // src/constants.ts
 var DEFAULT_NODE_TYPES = [
@@ -1847,16 +1890,16 @@ ${formatted}`,
       tokens: response.completionTokens
     };
   }
-  async summarizeTopics(topics) {
+  async summarizeTopics(topics, maxSummaryTokens = this.config.topicSummaryMaxTokens) {
     const input = topics.map(
       (topic) => `[${new Date(topic.startTime).toISOString()} - ${new Date(topic.endTime).toISOString()}] ${topic.title}
 ${topic.summary}`
     ).join("\n\n");
     const response = await this.chatCompletionWithUsage(
-      `\u4F60\u662F\u8BB0\u5FC6\u5F52\u5E76\u52A9\u624B\u3002\u628A\u4E00\u7EC4\u6309\u65F6\u95F4\u6392\u5217\u7684\u65E7\u4E3B\u9898\u5F52\u5E76\u6210\u4E00\u4E2A\u4E3B\u9898\u3002\u4FDD\u7559\u7A33\u5B9A\u504F\u597D\u3001\u4E8B\u5B9E\u3001\u51B3\u5B9A\u53CA\u7406\u7531\u3001\u957F\u671F\u7EA6\u675F\u3001\u963B\u585E\u4E0E\u53EF\u590D\u7528\u7ECF\u9A8C\uFF1B\u5220\u9664\u91CD\u590D\u5185\u5BB9\u3002summary \u6700\u591A ${this.config.topicSummaryMaxTokens} tokens\u3002\u53EA\u8F93\u51FA JSON\uFF1A{"title":"...","summary":"..."}`,
+      `\u4F60\u662F\u8BB0\u5FC6\u5F52\u5E76\u52A9\u624B\u3002\u628A\u4E00\u7EC4\u6309\u65F6\u95F4\u6392\u5217\u7684\u65E7\u4E3B\u9898\u5F52\u5E76\u6210\u4E00\u4E2A\u4E3B\u9898\u3002\u4FDD\u7559\u7A33\u5B9A\u504F\u597D\u3001\u4E8B\u5B9E\u3001\u51B3\u5B9A\u53CA\u7406\u7531\u3001\u957F\u671F\u7EA6\u675F\u3001\u963B\u585E\u4E0E\u53EF\u590D\u7528\u7ECF\u9A8C\uFF1B\u5220\u9664\u91CD\u590D\u5185\u5BB9\u3002summary \u6700\u591A ${maxSummaryTokens} tokens\u3002\u53EA\u8F93\u51FA JSON\uFF1A{"title":"...","summary":"..."}`,
       input,
       true,
-      this.config.topicSummaryMaxTokens + 128
+      maxSummaryTokens + 128
     );
     const parsed = JSON.parse(response.content);
     return {
@@ -2054,9 +2097,22 @@ var CompressManager = class {
   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)
+    );
+  }
+  /** 按给定预算收敛 Topic；persist=false 时只缓存当前模型使用的临时视图。 */
+  triggerTopicCompaction(sessionId, tokenLimit, persist) {
+    return this.enqueueSessionTask(
+      sessionId,
+      () => this.compactOldTopics(sessionId, Math.max(1, Math.floor(tokenLimit)), persist)
+    );
+  }
+  enqueueSessionTask(sessionId, task) {
     const previous = this.sessionChain.get(sessionId) ?? Promise.resolve();
     const next = previous.then(
-      () => this.semaphore.run(() => this.doCompress(sessionId, force, waitGraph, rawLimit))
+      () => this.semaphore.run(task)
     );
     const settled = next.catch(() => {
     });
@@ -2130,7 +2186,11 @@ var CompressManager = class {
     await this.store.addTopic(topic);
     this.sessionCache.appendTopic(sessionId, topic);
     this.sessionCache.removeMessages(sessionId, messages.map((message) => message.messageId));
-    await this.compactOldTopics(sessionId);
+    await this.compactOldTopics(
+      sessionId,
+      this.config.compressedContextTokenLimit,
+      true
+    );
     const graphTask = this.extractAndPersistGraph(
       messages,
       sessionId,
@@ -2148,29 +2208,42 @@ var CompressManager = class {
       tracked.finally(() => this.backgroundGraphs.delete(tracked));
     }
   }
-  async compactOldTopics(sessionId) {
+  async compactOldTopics(sessionId, tokenLimit, persist) {
+    let transientTopics = persist ? void 0 : this.sessionCache.getTopicView(sessionId, tokenLimit) ?? [...this.sessionCache.getEntry(sessionId)?.topics ?? []];
     while (true) {
       const entry = this.sessionCache.getEntry(sessionId);
-      if (!entry || entry.topicTokens <= this.config.compressedContextTokenLimit) return;
-      const target = Math.max(1, Math.floor(this.config.compressedContextTokenLimit / 2));
+      if (!entry) return;
+      const topics = persist ? entry.topics : transientTopics;
+      const topicTokens = sumTopicTokens(topics);
+      if (topicTokens <= tokenLimit) {
+        if (!persist) this.sessionCache.setTopicView(sessionId, tokenLimit, topics);
+        return;
+      }
+      const target = Math.max(1, Math.floor(topicTokens / 2));
       const selected = [];
-      let tokens = 0;
-      for (const topic of entry.topics) {
+      let selectedTokens = 0;
+      for (const topic of topics) {
         selected.push(topic);
-        tokens += topic.tokens;
-        if (tokens >= target && selected.length >= 2) break;
-      }
-      if (selected.length < 2) {
-        this.sessionCache.setTopics(sessionId, entry.topics, true);
-        return;
+        selectedTokens += topic.tokens;
+        if (selectedTokens >= target && (selected.length >= 2 || topics.length === 1)) break;
       }
+      if (selected.length === 0) return;
       console.info(
-        `[CompressManager] session ${sessionId} compressed Topic context exceeds ${this.config.compressedContextTokenLimit} tokens; compacting ${selected.length} old topics.`
+        `[CompressManager] session ${sessionId} compressed Topic context exceeds ${tokenLimit} tokens; compacting ${selected.length} old topics${persist ? " persistently" : " for a transient model view"}.`
       );
-      const result = await this.llm.summarizeTopics(selected);
+      const unselectedTokens = topicTokens - selectedTokens;
+      const maxSummaryTokens = Math.max(
+        1,
+        Math.min(
+          this.config.topicSummaryMaxTokens,
+          selectedTokens - 1,
+          Math.max(1, tokenLimit - unselectedTokens)
+        )
+      );
+      const result = await this.llm.summarizeTopics(selected, maxSummaryTokens);
       const summary = result.summary.trim();
       if (!summary) throw new Error(`LLM returned an empty Topic rollup for session ${sessionId}`);
-      const vector = await this.embed.embedOne(summary).catch(() => []);
+      const vector = persist ? await this.embed.embedOne(summary).catch(() => []) : [];
       const first = selected[0];
       const last = selected[selected.length - 1];
       const now = Date.now();
@@ -2181,7 +2254,7 @@ var CompressManager = class {
         chatId: entry.ids.chatId,
         title: result.title,
         summary,
-        tokens: result.tokens != null && result.tokens > 0 ? result.tokens : Math.max(1, countTokens(summary)),
+        tokens: Math.max(1, countTokens(summary)),
         startMessageId: first.startMessageId,
         endMessageId: last.endMessageId,
         startTime: first.startTime,
@@ -2191,15 +2264,27 @@ var CompressManager = class {
         recallCount: 0,
         vector
       };
+      if (rollup.tokens >= selectedTokens) {
+        throw new Error(
+          `Topic compaction made no progress for session ${sessionId}: ${selectedTokens} -> ${rollup.tokens} tokens`
+        );
+      }
       const removedIds = selected.map((topic) => topic.summaryId);
-      await this.store.addTopic(rollup);
-      this.sessionCache.replaceTopics(sessionId, removedIds, rollup);
-      await this.store.deleteTopicsByIds(removedIds);
+      if (persist) {
+        await this.store.addTopic(rollup);
+        this.sessionCache.replaceTopics(sessionId, removedIds, rollup);
+        await this.store.deleteTopicsByIds(removedIds);
+      } else {
+        const ids = new Set(removedIds);
+        transientTopics = [
+          ...topics.filter((topic) => !ids.has(topic.summaryId)),
+          rollup
+        ].sort(topicOrder);
+      }
     }
   }
   rawLimit(modelContextTokens = this.config.defaultModelContextTokens) {
-    const usable = Math.floor(modelContextTokens * this.config.contextUsageRatio);
-    return Math.max(1, usable - this.config.compressedContextTokenLimit);
+    return calculateContextBudget(this.config, modelContextTokens).rawTokenLimit;
   }
   async extractAndPersistGraph(messages, sessionId, chatId, userId, endTime) {
     const { entities, relations } = await this.llm.extractEntitiesFromMessages(messages);
@@ -2231,6 +2316,12 @@ var CompressManager = class {
     await this.grafeo.upsertEntitiesAndRelations(entities, relations, embeddings);
   }
 };
+function sumTopicTokens(topics) {
+  return topics.reduce((sum, topic) => sum + Math.max(1, topic.tokens), 0);
+}
+function topicOrder(a, b) {
+  return a.endTime - b.endTime || a.summaryId.localeCompare(b.summaryId);
+}
 function formatError(error) {
   return error instanceof Error ? error.message : String(error);
 }
@@ -2795,6 +2886,7 @@ function withTimeout2(promise, timeoutMs, label) {
 var SessionCache = class {
   config;
   sessions = /* @__PURE__ */ new Map();
+  topicViews = /* @__PURE__ */ new Map();
   legacyHistoryWindows = /* @__PURE__ */ new Map();
   constructor(config) {
     this.config = config;
@@ -2829,7 +2921,7 @@ var SessionCache = class {
     const entry = this.getOrCreateEntry(sessionId, chatId, userId);
     entry.messages = sortMessages(dedupeMessages(messages));
     entry.totalTokens = sumMessageTokens(entry.messages);
-    this.setTopics(sessionId, topics);
+    this.setTopics(sessionId, topics, false);
     return entry;
   }
   upsertMessages(sessionId, messages, chatId, userId) {
@@ -2878,7 +2970,7 @@ var SessionCache = class {
   setTopics(sessionId, topics, truncate = true) {
     const entry = this.sessions.get(sessionId);
     if (!entry) return;
-    const ordered = [...topics].sort(topicOrder);
+    const ordered = [...topics].sort(topicOrder2);
     const kept = [];
     let used = 0;
     for (let i = ordered.length - 1; i >= 0; i--) {
@@ -2890,6 +2982,7 @@ var SessionCache = class {
     entry.topics = kept.reverse();
     entry.topicTokens = used;
     entry.lastAccessAt = Date.now();
+    this.topicViews.delete(sessionId);
   }
   appendTopic(sessionId, topic) {
     const entry = this.sessions.get(sessionId);
@@ -2909,8 +3002,19 @@ var SessionCache = class {
   getTopics(sessionId) {
     return this.getEntry(sessionId)?.topics ?? [];
   }
-  buildCompressedContext(sessionId) {
-    return this.getTopics(sessionId).map((topic) => topic.title ? `## ${topic.title}
+  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 调用方过渡。 */
@@ -2950,6 +3054,7 @@ ${topic.summary}` : topic.summary).join("\n\n");
   }
   delete(sessionId) {
     this.sessions.delete(sessionId);
+    this.topicViews.delete(sessionId);
     this.legacyHistoryWindows.delete(sessionId);
   }
   evictIdle(now, ttlMs, isBusy) {
@@ -2958,6 +3063,7 @@ ${topic.summary}` : topic.summary).join("\n\n");
     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;
@@ -2981,7 +3087,7 @@ function sortMessages(messages) {
     (a, b) => a.createdAt - b.createdAt || a.messageId.localeCompare(b.messageId)
   );
 }
-function topicOrder(a, b) {
+function topicOrder2(a, b) {
   return a.endTime - b.endTime || a.summaryId.localeCompare(b.summaryId);
 }
 function normalizeTopic(topic) {
@@ -3012,6 +3118,7 @@ var MemoryManager = class {
   destroyTask;
   hydration = /* @__PURE__ */ new Map();
   pendingWrites = /* @__PURE__ */ new Map();
+  topicCompactions = /* @__PURE__ */ new Map();
   warnedDefaultModelContext = false;
   constructor(config) {
     this.config = resolveConfig(config);
@@ -3126,7 +3233,7 @@ var MemoryManager = class {
     await task;
   }
   isSessionBusy(sessionId) {
-    return this.hydration.has(sessionId) || this.pendingWrites.has(sessionId) || this.compressManager.isBusy(sessionId);
+    return this.hydration.has(sessionId) || this.pendingWrites.has(sessionId) || [...this.topicCompactions.keys()].some((key) => key.startsWith(`${sessionId}:`)) || this.compressManager.isBusy(sessionId);
   }
   waitForPendingWrites(sessionId) {
     return this.pendingWrites.get(sessionId) ?? Promise.resolve();
@@ -3359,7 +3466,7 @@ var MemoryManager = class {
       (f) => `${new Date(f.updatedAt ?? f.createdAt).toISOString()}\uFF1A${f.key ? `[${f.key}] ` : ""}${f.content}`
     ).join("\n");
   }
-  async getHistoryWindow(sessionId, modelContextTokens) {
+  async getHistoryWindow(sessionId, modelContextTokens, options) {
     let modelTokens = modelContextTokens;
     if (modelTokens == null) {
       modelTokens = this.config.defaultModelContextTokens;
@@ -3378,56 +3485,136 @@ var MemoryManager = class {
     await this.ensureSessionHydrated(sessionId);
     this.sessionCache.setModelContextTokens(sessionId, modelTokens);
     const usageLimits = this.calculateWindowUsage(modelTokens);
-    for (let attempt = 0; attempt < 100; attempt++) {
-      let entry2 = this.sessionCache.getEntry(sessionId);
-      if (entry2.totalTokens <= usageLimits.rawTokenLimit || entry2.messages.length === 0) break;
-      await this.compressManager.waitForIdle(sessionId);
-      entry2 = this.sessionCache.getEntry(sessionId);
-      if (entry2.totalTokens <= usageLimits.rawTokenLimit || entry2.messages.length === 0) break;
-      console.warn(
-        `[MemoryManager] session ${sessionId} raw history (${entry2.totalTokens}) exceeds current model budget (${usageLimits.rawTokenLimit}); waiting for immediate compression.`
-      );
-      const beforeTokens = entry2.totalTokens;
-      await this.compressManager.triggerCompress(
+    let blockingReason;
+    const beginBlocking = (reason) => {
+      if (blockingReason) return;
+      blockingReason = reason;
+      this.notifyBlockingCompression(options, { sessionId, phase: "start", reason });
+    };
+    try {
+      for (let attempt = 0; attempt < 100; attempt++) {
+        let entry2 = this.sessionCache.getEntry(sessionId);
+        if (entry2.totalTokens <= usageLimits.rawTokenLimit || entry2.messages.length === 0) break;
+        if (this.compressManager.isBusy(sessionId)) {
+          beginBlocking("pending");
+          await this.compressManager.waitForIdle(sessionId);
+          entry2 = this.sessionCache.getEntry(sessionId);
+          if (entry2.totalTokens <= usageLimits.rawTokenLimit || entry2.messages.length === 0) break;
+        }
+        beginBlocking("raw");
+        console.warn(
+          `[MemoryManager] session ${sessionId} raw history (${entry2.totalTokens}) exceeds current model budget (${usageLimits.rawTokenLimit}); waiting for immediate compression.`
+        );
+        const beforeTokens = entry2.totalTokens;
+        await this.compressManager.triggerCompress(
+          sessionId,
+          true,
+          false,
+          usageLimits.rawTokenLimit
+        );
+        const after = this.sessionCache.getEntry(sessionId);
+        if (after.messages.length > 0 && after.totalTokens >= beforeTokens) {
+          throw new Error(`Compression made no progress for session ${sessionId}`);
+        }
+      }
+      let entry = this.sessionCache.getEntry(sessionId);
+      if (entry.totalTokens > usageLimits.rawTokenLimit) {
+        throw new Error(`Unable to fit session ${sessionId} into the requested model context`);
+      }
+      let topicView = this.sessionCache.getTopicView(
         sessionId,
-        true,
-        false,
-        usageLimits.rawTokenLimit
+        usageLimits.compressedTokenLimit
       );
-      const after = this.sessionCache.getEntry(sessionId);
-      if (after.messages.length > 0 && after.totalTokens >= beforeTokens) {
-        throw new Error(`Compression made no progress for session ${sessionId}`);
+      if (!topicView && entry.topicTokens > usageLimits.compressedTokenLimit) {
+        const affectsCurrentWindow = entry.topicTokens + entry.totalTokens > usageLimits.usableContextTokens;
+        const materiallyOverLimit = entry.topicTokens > Math.floor(
+          usageLimits.compressedTokenLimit * this.config.topicCompactionSyncRatio
+        );
+        if (affectsCurrentWindow || materiallyOverLimit) {
+          if (this.compressManager.isBusy(sessionId)) beginBlocking("pending");
+          else beginBlocking("topics");
+          await this.compactTopicsForBudget(sessionId, usageLimits.compressedTokenLimit);
+          entry = this.sessionCache.getEntry(sessionId);
+          topicView = this.sessionCache.getTopicView(
+            sessionId,
+            usageLimits.compressedTokenLimit
+          );
+        } else {
+          void this.compactTopicsForBudget(
+            sessionId,
+            usageLimits.compressedTokenLimit
+          ).catch((error) => {
+            console.error(`[MemoryManager] Background Topic compaction failed for ${sessionId}:`, error);
+          });
+        }
+      }
+      const topics = topicView ?? entry.topics;
+      const compressedTokens = sumTopicTokens2(topics);
+      if (compressedTokens + entry.totalTokens > usageLimits.usableContextTokens) {
+        throw new Error(`Unable to fit session ${sessionId} into the requested model context`);
+      }
+      return {
+        sessionId,
+        compressedContext: this.sessionCache.buildCompressedContext(sessionId, topics),
+        recentMessages: entry.messages.map(toMemoryRawMessage),
+        usage: {
+          ...usageLimits,
+          compressedTokens,
+          rawTokens: entry.totalTokens
+        }
+      };
+    } finally {
+      if (blockingReason) {
+        this.notifyBlockingCompression(options, {
+          sessionId,
+          phase: "end",
+          reason: blockingReason
+        });
       }
     }
-    const entry = this.sessionCache.getEntry(sessionId);
-    if (entry.totalTokens > usageLimits.rawTokenLimit) {
-      throw new Error(`Unable to fit session ${sessionId} into the requested model context`);
-    }
-    return {
-      sessionId,
-      compressedContext: this.sessionCache.buildCompressedContext(sessionId),
-      recentMessages: entry.messages.map(toMemoryRawMessage),
-      usage: {
-        ...usageLimits,
-        compressedTokens: entry.topicTokens,
-        rawTokens: entry.totalTokens
+  }
+  compactTopicsForBudget(sessionId, effectiveLimit) {
+    const key = `${sessionId}:${effectiveLimit}`;
+    const existing = this.topicCompactions.get(key);
+    if (existing) return existing;
+    const task = (async () => {
+      let entry = this.sessionCache.getEntry(sessionId);
+      if (!entry) return;
+      if (entry.topicTokens > this.config.compressedContextTokenLimit) {
+        await this.compressManager.triggerTopicCompaction(
+          sessionId,
+          this.config.compressedContextTokenLimit,
+          true
+        );
+        entry = this.sessionCache.getEntry(sessionId);
+      }
+      if (entry && entry.topicTokens > effectiveLimit && !this.sessionCache.getTopicView(sessionId, effectiveLimit)) {
+        await this.compressManager.triggerTopicCompaction(sessionId, effectiveLimit, false);
       }
+    })();
+    this.topicCompactions.set(key, task);
+    const clear = () => {
+      if (this.topicCompactions.get(key) === task) this.topicCompactions.delete(key);
     };
+    void task.then(clear, clear);
+    return task;
   }
-  calculateWindowUsage(modelContextTokens) {
-    const usableContextTokens = Math.floor(modelContextTokens * this.config.contextUsageRatio);
-    const rawTokenLimit = usableContextTokens - this.config.compressedContextTokenLimit;
-    if (rawTokenLimit <= 0) {
-      throw new Error(
-        `modelContextTokens=${modelContextTokens} \u5728 contextUsageRatio=${this.config.contextUsageRatio} \u4E0B\u4E0D\u8DB3\u4EE5\u5BB9\u7EB3 compressedContextTokenLimit=${this.config.compressedContextTokenLimit}`
-      );
+  notifyBlockingCompression(options, event) {
+    const callback = options?.onBlockingCompression;
+    if (!callback) return;
+    try {
+      const returned = callback(event);
+      if (returned && typeof returned.then === "function") {
+        void Promise.resolve(returned).catch((error) => {
+          console.warn("[MemoryManager] onBlockingCompression callback rejected:", error);
+        });
+      }
+    } catch (error) {
+      console.warn("[MemoryManager] onBlockingCompression callback failed:", error);
     }
-    return {
-      modelContextTokens,
-      usableContextTokens,
-      compressedTokenLimit: this.config.compressedContextTokenLimit,
-      rawTokenLimit
-    };
+  }
+  calculateWindowUsage(modelContextTokens) {
+    return calculateContextBudget(this.config, modelContextTokens);
   }
   buildScopeFilter(scope, scopeId) {
     if (scope === "session" && scopeId) return [eq("session_id", scopeId)];
@@ -3609,7 +3796,11 @@ var MemoryManager = class {
       clearInterval(this.sessionSweepTimer);
       this.sessionSweepTimer = void 0;
     }
-    const writes = [...this.pendingWrites.values(), ...this.hydration.values()];
+    const writes = [
+      ...this.pendingWrites.values(),
+      ...this.hydration.values(),
+      ...this.topicCompactions.values()
+    ];
     this.destroyTask = Promise.all(writes).catch(() => {
     }).then(() => this.compressManager.waitForAllIdle()).catch(() => {
     }).then(() => this.optimizeTask).catch(() => {
@@ -3639,6 +3830,9 @@ function toMemoryRawMessage(message) {
     createdAt: message.createdAt
   };
 }
+function sumTopicTokens2(topics) {
+  return topics.reduce((sum, topic) => sum + Math.max(1, topic.tokens), 0);
+}
 function safeParseArray(value) {
   try {
     const parsed = JSON.parse(value);
@@ -3668,5 +3862,6 @@ export {
   KIND_CONVERSATION,
   KIND_KNOWLEDGE,
   MemoryManager,
-  MemoryStore
+  MemoryStore,
+  calculateContextBudget
 };

package/llms.txt

@@ -1,6 +1,6 @@
 # @ppagent/memory
 
-> `@ppagent/memory` is an independent TypeScript/Node.js long-term memory package for AI agents. It stores complete raw conversation messages in a pluggable vector store (LanceDB or SQLite/sqlite-vec, auto-detected per platform), builds importance-aware Topic summaries, returns fixed-budget Topics plus recent uncompressed messages as one context window, extracts and searches entity relationships with Grafeo, supports cached user/chat facts, and ingests Markdown documents as a searchable knowledge base.
+> `@ppagent/memory` is an independent TypeScript/Node.js long-term memory package for AI agents. It stores complete raw conversation messages in a pluggable vector store (LanceDB or SQLite/sqlite-vec, auto-detected per platform), builds importance-aware Topic summaries, returns dynamically budgeted Topics plus recent uncompressed messages as one context window, extracts and searches entity relationships with Grafeo, supports cached user/chat facts, and ingests Markdown documents as a searchable knowledge base.
 
 This file is written for AI coding agents and assistants. Use it as the primary package guide when generating code that depends on `@ppagent/memory`.
 
@@ -150,6 +150,8 @@ const memory = new MemoryManager({
   embeddingConcurrency: 2,
 
   compressedContextTokenLimit: 16 * 1024,
+  compressedContextRatio: 0.10,
+  topicCompactionSyncRatio: 1.25,
   contextUsageRatio: 0.75,
   precompressionRatio: 0.75,
   compressionBatchRatio: 0.5,
@@ -331,7 +333,9 @@ HTTP and retry fields:
 
 Conversation memory fields:
 
-- `compressedContextTokenLimit?: number` - fixed token budget for compressed Topics. Default: `16384`; startup logs a warning above `32768`.
+- `compressedContextTokenLimit?: number` - global storage cap for compressed Topics. Default: `16384`; startup logs a warning above `32768`.
+- `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 raw-message budget compressed in one batch. Default: `0.5`.
@@ -384,13 +388,15 @@ The package intentionally separates durable base writes from expensive graph con
 - `waitGraph: true` waits for graph extraction/persistence too.
 - When `waitGraph: true`, graph waiting is bounded by `graphBuildTimeoutMs` and may throw a timeout error.
 
-`getHistoryWindow(sessionId, modelContextTokens?)`:
+`getHistoryWindow(sessionId, modelContextTokens?, options?)`:
 
 - Lazily hydrates the session from persistent Topics plus raw messages after the newest Topic boundary.
 - Waits for registered message writes. If the hard raw budget is exceeded, it also waits for or starts compression until the returned context fits.
 - Returns `{ compressedContext, recentMessages, usage }`. `recentMessages` preserves the `RawMessage` input shape, including `messageId`, `parts`, `payload`, `metadata`, and `createdAt`.
-- Topic budget is fixed by manager configuration; the raw-message budget is recalculated from the supplied model context size.
-- If accumulated Topics exceed their fixed budget, the oldest approximately half are summarized into one Topic. This Topic-to-Topic rollup does not rebuild graph data.
+- The effective Topic budget is `min(compressedContextTokenLimit, usableContextTokens * compressedContextRatio)`; the remaining usable history budget is reserved for raw messages.
+- Cold hydration always restores all persisted Topics and never silently truncates them. Each rollup summarizes the oldest approximately half of the current Topic tokens; a single oversized Topic is re-summarized by itself.
+- A small Topic-only overage returns immediately and schedules a transient background rollup for the next read. It blocks only when the overage exceeds `topicCompactionSyncRatio` or Topic plus raw history cannot fit the usable window.
+- `options.onBlockingCompression` receives `{ phase: "start" | "end", reason }` only when this read actually waits for compression. Silent precompression and non-blocking Topic rollups do not invoke it. Callback failures are contained.
 
 `addDocument(opts)`:
 
@@ -607,15 +613,17 @@ Context:
 - `chatId?: string`
 - `userId?: string`
 
-### `getHistoryWindow(sessionId, modelContextTokens?): Promise<MemoryContextWindow>`
+### `getHistoryWindow(sessionId, modelContextTokens?, options?): Promise<MemoryContextWindow>`
 
 Returns the complete model-history window:
 
-- `compressedContext: string` - chronological Topic summaries within the fixed compressed budget.
+- `compressedContext: string` - chronological Topic summaries for the current model-size budget. A soft cold-start overage may be returned once while its transient rollup runs in the background.
 - `recentMessages: MemoryRawMessage[]` - all currently uncompressed raw messages in chronological order, preserving the host payload and metadata.
 - `usage` - model size, usable history size, compressed usage, and dynamic raw-message budget/usage.
 
 Pass the active model's context size on every read. Omitting it uses `defaultModelContextTokens` (256K by default) and logs a warning.
+
+Pass `options.onBlockingCompression` when the host needs a foreground-wait UI signal. It is deliberately not a general compression-progress callback.
 
 ### `getRecentMessages(sessionId, limit): Promise<StoredMessage[]>`
 

package/package.json

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