@ppagent/memory 0.4.2 → 0.4.5

package/dist/cli.js

@@ -52,8 +52,16 @@ function resolveConfig(config) {
     ),
     contextUsageRatio: ratio(config.contextUsageRatio ?? 0.75, "contextUsageRatio"),
     precompressionRatio: ratio(config.precompressionRatio ?? 0.75, "precompressionRatio"),
-    compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.5, "compressionBatchRatio"),
+    compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.7, "compressionBatchRatio"),
     compressionBatchTokenLimit: Math.max(0, Math.floor(config.compressionBatchTokenLimit ?? 0)),
+    compressionMaxRetries: nonNegativeInt(
+      config.compressionMaxRetries ?? 2,
+      "compressionMaxRetries"
+    ),
+    compressionRetryBaseDelayMs: nonNegativeInt(
+      config.compressionRetryBaseDelayMs ?? 500,
+      "compressionRetryBaseDelayMs"
+    ),
     topicSummaryMaxTokens: positiveInt(
       config.topicSummaryMaxTokens ?? config.detailMaxTokens ?? 2048,
       "topicSummaryMaxTokens"
@@ -101,6 +109,12 @@ function ratio(value, name) {
   }
   return value;
 }
+function nonNegativeInt(value, name) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u975E\u8D1F\u6570`);
+  }
+  return Math.floor(value);
+}
 function positiveInt(value, name) {
   if (!Number.isFinite(value) || value <= 0) {
     throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u6B63\u6570`);
@@ -134,6 +148,136 @@ function countTokens(text) {
   return encoder.encode(text).length;
 }
 
+// src/history-image.ts
+var OMIT_IMAGE = Symbol("omit-history-image");
+var IMAGE_PART_TYPES = /* @__PURE__ */ new Set([
+  "image",
+  "image-data",
+  "image-url",
+  "image-file-id",
+  "image-file-reference",
+  "input-image",
+  "output-image"
+]);
+function sanitizeRawHistoryFields(message) {
+  const partsResult = sanitizeValue(message.parts ?? []);
+  const payloadResult = sanitizeValue(message.payload);
+  const contextResult = sanitizeValue(message.contextPayload);
+  const metadataResult = sanitizeValue(message.metadata ?? {});
+  const payload = optionalSanitizedValue(payloadResult);
+  const contextPayload = optionalSanitizedValue(contextResult);
+  return {
+    parts: Array.isArray(partsResult.value) ? partsResult.value : [],
+    ...payload !== void 0 && { payload },
+    ...contextPayload !== void 0 && { contextPayload },
+    metadata: isRecord(metadataResult.value) ? metadataResult.value : {},
+    removedImages: partsResult.removedImages + payloadResult.removedImages + contextResult.removedImages + metadataResult.removedImages
+  };
+}
+function sanitizeStoredMessageImages(message) {
+  const parsed = {
+    content: message.content,
+    parts: parseArray(message.parts),
+    ...message.payload !== void 0 && { payload: parseValue(message.payload) },
+    ...message.contextPayload !== void 0 && {
+      contextPayload: parseValue(message.contextPayload)
+    },
+    metadata: parseObject(message.metadata)
+  };
+  const sanitized = sanitizeRawHistoryFields(parsed);
+  if (sanitized.removedImages === 0) {
+    return { message, changed: false, removedImages: 0 };
+  }
+  const parts = JSON.stringify(sanitized.parts);
+  const payload = sanitized.payload === void 0 ? void 0 : JSON.stringify(sanitized.payload);
+  const contextPayload = sanitized.contextPayload === void 0 ? void 0 : JSON.stringify(sanitized.contextPayload);
+  const metadata = JSON.stringify(sanitized.metadata);
+  const usage2 = countTokens(
+    [message.content, parts, metadata, payload ?? "", contextPayload ?? ""].join("\n")
+  );
+  return {
+    message: {
+      ...message,
+      parts,
+      payload,
+      contextPayload,
+      usage: usage2,
+      metadata
+    },
+    changed: true,
+    removedImages: sanitized.removedImages
+  };
+}
+function sanitizeValue(value) {
+  if (typeof value === "string" && /^data:image\//i.test(value.trim())) {
+    return { value: OMIT_IMAGE, removedImages: 1, changed: true };
+  }
+  if (value == null || typeof value !== "object") {
+    return { value, removedImages: 0, changed: false };
+  }
+  if (isImageNode(value)) {
+    return { value: OMIT_IMAGE, removedImages: 1, changed: true };
+  }
+  if (Array.isArray(value)) {
+    const out2 = [];
+    let removedImages2 = 0;
+    let changed2 = false;
+    for (const item of value) {
+      const sanitized = sanitizeValue(item);
+      removedImages2 += sanitized.removedImages;
+      changed2 ||= sanitized.changed;
+      if (sanitized.value !== OMIT_IMAGE) out2.push(sanitized.value);
+    }
+    return { value: changed2 ? out2 : value, removedImages: removedImages2, changed: changed2 };
+  }
+  const out = {};
+  let removedImages = 0;
+  let changed = false;
+  for (const [key, item] of Object.entries(value)) {
+    const sanitized = sanitizeValue(item);
+    removedImages += sanitized.removedImages;
+    changed ||= sanitized.changed;
+    if (sanitized.value !== OMIT_IMAGE) out[key] = sanitized.value;
+  }
+  return { value: changed ? out : value, removedImages, changed };
+}
+function isImageNode(value) {
+  if (!isRecord(value)) return false;
+  const type = normalizeType(value.type);
+  if (IMAGE_PART_TYPES.has(type)) return true;
+  const mediaType = String(value.mediaType ?? value.mimeType ?? "").trim().toLowerCase();
+  return mediaType.startsWith("image/") && (type === "file" || "data" in value || "url" in value || "fileId" in value || "providerReference" in value);
+}
+function normalizeType(value) {
+  return typeof value === "string" ? value.trim().toLowerCase().replaceAll("_", "-") : "";
+}
+function optionalSanitizedValue(result) {
+  if (result.value === OMIT_IMAGE) return void 0;
+  if (result.changed && isEmptyContainer(result.value)) return void 0;
+  return result.value;
+}
+function isEmptyContainer(value) {
+  return Array.isArray(value) ? value.length === 0 : isRecord(value) && Object.keys(value).length === 0;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseValue(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function parseArray(value) {
+  const parsed = parseValue(value);
+  return Array.isArray(parsed) ? parsed : [];
+}
+function parseObject(value) {
+  const parsed = parseValue(value);
+  return isRecord(parsed) ? parsed : {};
+}
+
 // src/db/memory.store.ts
 var MESSAGES_TABLE = "messages";
 var TOPICS_TABLE = "topics";
@@ -159,6 +303,7 @@ function tableDefs(dim) {
         { name: "parts", type: "text", nullable: true },
         // 兼容存量数据
         { name: "payload", type: "text", nullable: true },
+        { name: "context_payload", type: "text", nullable: true },
         { name: "vector", type: "vector" },
         { name: "usage", type: "int" },
         { name: "metadata", type: "text" },
@@ -290,6 +435,7 @@ function messageToRow(m) {
     content: m.content,
     parts: m.parts ?? "[]",
     payload: m.payload ?? null,
+    context_payload: m.contextPayload ?? null,
     vector: m.vector,
     usage: m.usage,
     metadata: m.metadata,
@@ -308,6 +454,7 @@ function rowToMessage(r) {
     parts: r.parts ?? "[]",
     // 旧数据无此列时安全降级
     payload: r.payload ?? void 0,
+    contextPayload: r.context_payload ?? void 0,
     vector: toVector(r.vector),
     usage: positiveNumber(r.usage),
     metadata: r.metadata,
@@ -593,11 +740,28 @@ var MemoryStore = class {
     const messageRows = await this.provider.query(MESSAGES_TABLE);
     report.messagesScanned = messageRows.length;
     for (const row of messageRows) {
+      const sanitized = sanitizeStoredMessageImages(rowToMessage(row)).message;
       const usage2 = countTokens(
-        [row.content, row.parts ?? "[]", row.metadata ?? "{}", row.payload ?? ""].map(String).join("\n")
+        [
+          sanitized.content,
+          sanitized.parts,
+          sanitized.metadata,
+          sanitized.payload ?? "",
+          sanitized.contextPayload ?? ""
+        ].map(String).join("\n")
+      );
+      const values = {
+        parts: sanitized.parts,
+        payload: sanitized.payload ?? null,
+        context_payload: sanitized.contextPayload ?? null,
+        metadata: sanitized.metadata,
+        usage: usage2
+      };
+      const changed = Object.entries(values).some(
+        ([key, value]) => !migrationValueEquals(row[key], value)
       );
-      if (Number(row.usage) === usage2) continue;
-      await this.provider.update(MESSAGES_TABLE, { usage: usage2 }, [
+      if (!changed) continue;
+      await this.provider.update(MESSAGES_TABLE, values, [
         eq("message_id", String(row.message_id))
       ]);
       report.messagesUpdated++;

package/dist/index.d.ts

@@ -61,6 +61,12 @@ interface RawMessage {
     parts?: ContentPart[];
     /** 宿主框架的原始消息载荷；记忆框架仅透明保存和回读。 */
     payload?: unknown;
+    /**
+     * 仅用于下一次模型上下文重放的宿主载荷。
+     * 会透明保存、原样回读并计入原始窗口 token，但不会进入 embedding、全文检索、
+     * Topic 摘要或知识图谱抽取。适合保存 provider-ready 工具协议消息等大体积细节。
+     */
+    contextPayload?: unknown;
     usage?: number;
     metadata?: Record<string, unknown>;
     createdAt?: number;
@@ -78,6 +84,8 @@ interface StoredMessage {
     parts: string;
     /** JSON.stringify(payload)，未提供时为 undefined。 */
     payload?: string;
+    /** JSON.stringify(contextPayload)，未提供时为 undefined。 */
+    contextPayload?: string;
     usage: number;
     metadata: string;
     vector: number[];
@@ -236,6 +244,7 @@ interface MemoryRawMessage {
     content: string;
     parts?: ContentPart[];
     payload?: unknown;
+    contextPayload?: unknown;
     usage: number;
     metadata?: Record<string, unknown>;
     createdAt: number;
@@ -261,6 +270,11 @@ interface GetHistoryWindowOptions {
 /** 固定预算的压缩记忆 + 近期未压缩原始消息。 */
 interface MemoryContextWindow {
     sessionId: string;
+    /**
+     * 当前压缩边界的轻量版本标识。后台/阻塞压缩或 Topic 归并改变窗口时随之变化；
+     * 新增原始消息本身不保证改变该值。
+     */
+    compressionRevision?: string;
     compressedContext: string;
     recentMessages: MemoryRawMessage[];
     usage: MemoryContextWindowUsage;
@@ -407,10 +421,14 @@ interface MemoryConfig {
     contextUsageRatio?: number;
     /** 原始消息达到其可用预算的此比例时后台预压缩，默认 0.75。 */
     precompressionRatio?: number;
-    /** 单次压缩目标占原始消息预算的比例，默认 0.5。 */
+    /** 单次压缩目标占当前未压缩消息 token 总量的比例，默认 0.7（压 7 留 3）。 */
     compressionBatchRatio?: number;
     /** 单次压缩硬上限；0 表示只受 compressionBatchRatio 控制。 */
     compressionBatchTokenLimit?: number;
+    /** 压缩模型返回非法 JSON、缺字段或空摘要时的最大重试次数，默认 2（即最多 3 次）。 */
+    compressionMaxRetries?: number;
+    /** 压缩结果级重试的指数退避基数（毫秒），默认 500；0 表示不等待。 */
+    compressionRetryBaseDelayMs?: number;
     /** 单条 Topic 摘要硬上限，实际长度由重要性决定，默认 2048。 */
     topicSummaryMaxTokens?: number;
     /** 未传 getHistoryWindow 模型窗口时使用，默认 256K。 */

package/dist/index.js

@@ -48,8 +48,16 @@ function resolveConfig(config) {
     ),
     contextUsageRatio: ratio(config.contextUsageRatio ?? 0.75, "contextUsageRatio"),
     precompressionRatio: ratio(config.precompressionRatio ?? 0.75, "precompressionRatio"),
-    compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.5, "compressionBatchRatio"),
+    compressionBatchRatio: ratio(config.compressionBatchRatio ?? 0.7, "compressionBatchRatio"),
     compressionBatchTokenLimit: Math.max(0, Math.floor(config.compressionBatchTokenLimit ?? 0)),
+    compressionMaxRetries: nonNegativeInt(
+      config.compressionMaxRetries ?? 2,
+      "compressionMaxRetries"
+    ),
+    compressionRetryBaseDelayMs: nonNegativeInt(
+      config.compressionRetryBaseDelayMs ?? 500,
+      "compressionRetryBaseDelayMs"
+    ),
     topicSummaryMaxTokens: positiveInt(
       config.topicSummaryMaxTokens ?? config.detailMaxTokens ?? 2048,
       "topicSummaryMaxTokens"
@@ -97,6 +105,12 @@ function ratio(value, name) {
   }
   return value;
 }
+function nonNegativeInt(value, name) {
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u975E\u8D1F\u6570`);
+  }
+  return Math.floor(value);
+}
 function positiveInt(value, name) {
   if (!Number.isFinite(value) || value <= 0) {
     throw new Error(`[MemoryConfig] ${name} \u5FC5\u987B\u662F\u6B63\u6570`);
@@ -255,6 +269,18 @@ import { GrafeoDB } from "@grafeo-db/js";
 import { get_encoding } from "@dqbd/tiktoken";
 
 // src/llm/http.ts
+var HttpRequestError = class extends Error {
+  retryable;
+  attempts;
+  status;
+  constructor(message, options) {
+    super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "HttpRequestError";
+    this.retryable = options.retryable;
+    this.attempts = options.attempts;
+    this.status = options.status;
+  }
+};
 function normalizeFetchError(err, timeoutMs, errorLabel) {
   if (isAbortError(err)) {
     return new Error(`${errorLabel} request timed out after ${timeoutMs}ms`, { cause: err });
@@ -291,15 +317,36 @@ async function postJsonWithRetry(url, headers, body, opts, errorLabel = "HTTP")
         await sleep(backoffDelay(attempt));
         continue;
       }
-      throw lastErr;
+      throw new HttpRequestError(lastErr.message, {
+        retryable: true,
+        attempts: attempt + 1,
+        cause: lastErr
+      });
     }
     clearTimeout(timer);
     if (res.ok) {
-      return await res.json();
+      try {
+        return await res.json();
+      } catch (err) {
+        lastErr = new HttpRequestError(`${errorLabel} returned invalid JSON`, {
+          retryable: true,
+          attempts: attempt + 1,
+          cause: err
+        });
+        if (attempt < opts.maxRetries) {
+          await sleep(backoffDelay(attempt));
+          continue;
+        }
+        throw lastErr;
+      }
     }
     const text = await res.text().catch(() => "");
-    lastErr = new Error(`${errorLabel} error ${res.status}: ${text}`);
     const retryable = res.status >= 500 || res.status === 429;
+    lastErr = new HttpRequestError(`${errorLabel} error ${res.status}: ${text}`, {
+      retryable,
+      attempts: attempt + 1,
+      status: res.status
+    });
     if (retryable && attempt < opts.maxRetries) {
       await sleep(backoffDelay(attempt));
       continue;
@@ -802,6 +849,136 @@ function eq(field, value) {
   return { op: "eq", field, value };
 }
 
+// src/history-image.ts
+var OMIT_IMAGE = Symbol("omit-history-image");
+var IMAGE_PART_TYPES = /* @__PURE__ */ new Set([
+  "image",
+  "image-data",
+  "image-url",
+  "image-file-id",
+  "image-file-reference",
+  "input-image",
+  "output-image"
+]);
+function sanitizeRawHistoryFields(message) {
+  const partsResult = sanitizeValue(message.parts ?? []);
+  const payloadResult = sanitizeValue(message.payload);
+  const contextResult = sanitizeValue(message.contextPayload);
+  const metadataResult = sanitizeValue(message.metadata ?? {});
+  const payload = optionalSanitizedValue(payloadResult);
+  const contextPayload = optionalSanitizedValue(contextResult);
+  return {
+    parts: Array.isArray(partsResult.value) ? partsResult.value : [],
+    ...payload !== void 0 && { payload },
+    ...contextPayload !== void 0 && { contextPayload },
+    metadata: isRecord(metadataResult.value) ? metadataResult.value : {},
+    removedImages: partsResult.removedImages + payloadResult.removedImages + contextResult.removedImages + metadataResult.removedImages
+  };
+}
+function sanitizeStoredMessageImages(message) {
+  const parsed = {
+    content: message.content,
+    parts: parseArray(message.parts),
+    ...message.payload !== void 0 && { payload: parseValue(message.payload) },
+    ...message.contextPayload !== void 0 && {
+      contextPayload: parseValue(message.contextPayload)
+    },
+    metadata: parseObject(message.metadata)
+  };
+  const sanitized = sanitizeRawHistoryFields(parsed);
+  if (sanitized.removedImages === 0) {
+    return { message, changed: false, removedImages: 0 };
+  }
+  const parts = JSON.stringify(sanitized.parts);
+  const payload = sanitized.payload === void 0 ? void 0 : JSON.stringify(sanitized.payload);
+  const contextPayload = sanitized.contextPayload === void 0 ? void 0 : JSON.stringify(sanitized.contextPayload);
+  const metadata = JSON.stringify(sanitized.metadata);
+  const usage = countTokens(
+    [message.content, parts, metadata, payload ?? "", contextPayload ?? ""].join("\n")
+  );
+  return {
+    message: {
+      ...message,
+      parts,
+      payload,
+      contextPayload,
+      usage,
+      metadata
+    },
+    changed: true,
+    removedImages: sanitized.removedImages
+  };
+}
+function sanitizeValue(value) {
+  if (typeof value === "string" && /^data:image\//i.test(value.trim())) {
+    return { value: OMIT_IMAGE, removedImages: 1, changed: true };
+  }
+  if (value == null || typeof value !== "object") {
+    return { value, removedImages: 0, changed: false };
+  }
+  if (isImageNode(value)) {
+    return { value: OMIT_IMAGE, removedImages: 1, changed: true };
+  }
+  if (Array.isArray(value)) {
+    const out2 = [];
+    let removedImages2 = 0;
+    let changed2 = false;
+    for (const item of value) {
+      const sanitized = sanitizeValue(item);
+      removedImages2 += sanitized.removedImages;
+      changed2 ||= sanitized.changed;
+      if (sanitized.value !== OMIT_IMAGE) out2.push(sanitized.value);
+    }
+    return { value: changed2 ? out2 : value, removedImages: removedImages2, changed: changed2 };
+  }
+  const out = {};
+  let removedImages = 0;
+  let changed = false;
+  for (const [key, item] of Object.entries(value)) {
+    const sanitized = sanitizeValue(item);
+    removedImages += sanitized.removedImages;
+    changed ||= sanitized.changed;
+    if (sanitized.value !== OMIT_IMAGE) out[key] = sanitized.value;
+  }
+  return { value: changed ? out : value, removedImages, changed };
+}
+function isImageNode(value) {
+  if (!isRecord(value)) return false;
+  const type = normalizeType(value.type);
+  if (IMAGE_PART_TYPES.has(type)) return true;
+  const mediaType = String(value.mediaType ?? value.mimeType ?? "").trim().toLowerCase();
+  return mediaType.startsWith("image/") && (type === "file" || "data" in value || "url" in value || "fileId" in value || "providerReference" in value);
+}
+function normalizeType(value) {
+  return typeof value === "string" ? value.trim().toLowerCase().replaceAll("_", "-") : "";
+}
+function optionalSanitizedValue(result) {
+  if (result.value === OMIT_IMAGE) return void 0;
+  if (result.changed && isEmptyContainer(result.value)) return void 0;
+  return result.value;
+}
+function isEmptyContainer(value) {
+  return Array.isArray(value) ? value.length === 0 : isRecord(value) && Object.keys(value).length === 0;
+}
+function isRecord(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function parseValue(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+function parseArray(value) {
+  const parsed = parseValue(value);
+  return Array.isArray(parsed) ? parsed : [];
+}
+function parseObject(value) {
+  const parsed = parseValue(value);
+  return isRecord(parsed) ? parsed : {};
+}
+
 // src/db/memory.store.ts
 var MESSAGES_TABLE = "messages";
 var TOPICS_TABLE = "topics";
@@ -827,6 +1004,7 @@ function tableDefs(dim) {
         { name: "parts", type: "text", nullable: true },
         // 兼容存量数据
         { name: "payload", type: "text", nullable: true },
+        { name: "context_payload", type: "text", nullable: true },
         { name: "vector", type: "vector" },
         { name: "usage", type: "int" },
         { name: "metadata", type: "text" },
@@ -958,6 +1136,7 @@ function messageToRow(m) {
     content: m.content,
     parts: m.parts ?? "[]",
     payload: m.payload ?? null,
+    context_payload: m.contextPayload ?? null,
     vector: m.vector,
     usage: m.usage,
     metadata: m.metadata,
@@ -976,6 +1155,7 @@ function rowToMessage(r) {
     parts: r.parts ?? "[]",
     // 旧数据无此列时安全降级
     payload: r.payload ?? void 0,
+    contextPayload: r.context_payload ?? void 0,
     vector: toVector(r.vector),
     usage: positiveNumber(r.usage),
     metadata: r.metadata,
@@ -1261,11 +1441,28 @@ var MemoryStore = class {
     const messageRows = await this.provider.query(MESSAGES_TABLE);
     report.messagesScanned = messageRows.length;
     for (const row of messageRows) {
+      const sanitized = sanitizeStoredMessageImages(rowToMessage(row)).message;
       const usage = countTokens(
-        [row.content, row.parts ?? "[]", row.metadata ?? "{}", row.payload ?? ""].map(String).join("\n")
+        [
+          sanitized.content,
+          sanitized.parts,
+          sanitized.metadata,
+          sanitized.payload ?? "",
+          sanitized.contextPayload ?? ""
+        ].map(String).join("\n")
+      );
+      const values = {
+        parts: sanitized.parts,
+        payload: sanitized.payload ?? null,
+        context_payload: sanitized.contextPayload ?? null,
+        metadata: sanitized.metadata,
+        usage
+      };
+      const changed = Object.entries(values).some(
+        ([key, value]) => !migrationValueEquals(row[key], value)
       );
-      if (Number(row.usage) === usage) continue;
-      await this.provider.update(MESSAGES_TABLE, { usage }, [
+      if (!changed) continue;
+      await this.provider.update(MESSAGES_TABLE, values, [
         eq("message_id", String(row.message_id))
       ]);
       report.messagesUpdated++;
@@ -2086,7 +2283,7 @@ function stripToolCallContent(value) {
   if (Array.isArray(value)) {
     return value.map((item) => stripToolCallContent(item)).filter((item) => item !== OMIT_COMPRESSION_VALUE);
   }
-  if (!isRecord(value)) return value;
+  if (!isRecord2(value)) return value;
   if (isToolCallBlock(value)) return OMIT_COMPRESSION_VALUE;
   const sanitized = {};
   for (const [key, child] of Object.entries(value)) {
@@ -2111,7 +2308,7 @@ function isToolCallBlock(value) {
 function normalizeToolKey(value) {
   return value.replace(/[\s_-]/g, "").toLowerCase();
 }
-function isRecord(value) {
+function isRecord2(value) {
   return value !== null && typeof value === "object";
 }
 
@@ -2212,7 +2409,10 @@ var CompressManager = class {
     const rawLimit = Math.max(1, rawLimitOverride ?? this.rawLimit(entry.lastModelContextTokens));
     const threshold = Math.max(1, Math.floor(rawLimit * this.config.precompressionRatio));
     if (!force && entry.totalTokens < threshold) return;
-    let batchTarget = Math.max(1, Math.floor(rawLimit * this.config.compressionBatchRatio));
+    let batchTarget = Math.max(
+      1,
+      Math.floor(entry.totalTokens * this.config.compressionBatchRatio)
+    );
     if (this.config.compressionBatchTokenLimit > 0) {
       batchTarget = Math.min(batchTarget, this.config.compressionBatchTokenLimit);
     }
@@ -2220,7 +2420,11 @@ var CompressManager = class {
     if (messages.length === 0) return;
     let result;
     try {
-      result = await this.llm.summarizeMessages(messages);
+      result = await this.summarizeWithRetry(
+        sessionId,
+        "raw-message compression",
+        () => this.llm.summarizeMessages(messages)
+      );
     } catch (error) {
       console.error(
         `[CompressManager] LLM compress failed for session ${sessionId}: ${formatError(error)}`
@@ -2228,7 +2432,6 @@ var CompressManager = class {
       throw error;
     }
     const summary = result.summary.trim();
-    if (!summary) throw new Error(`LLM returned an empty summary for session ${sessionId}`);
     const vector = await this.embed.embedOne(summary).catch((error) => {
       console.error(`[CompressManager] Embed topic failed for session ${sessionId}:`, error);
       return [];
@@ -2310,9 +2513,12 @@ var CompressManager = class {
           Math.max(1, tokenLimit - unselectedTokens)
         )
       );
-      const result = await this.llm.summarizeTopics(selected, maxSummaryTokens);
+      const result = await this.summarizeWithRetry(
+        sessionId,
+        "Topic compaction",
+        () => this.llm.summarizeTopics(selected, maxSummaryTokens)
+      );
       const summary = result.summary.trim();
-      if (!summary) throw new Error(`LLM returned an empty Topic rollup for session ${sessionId}`);
       const vector = persist ? await this.embed.embedOne(summary).catch(() => []) : [];
       const first = selected[0];
       const last = selected[selected.length - 1];
@@ -2385,6 +2591,37 @@ var CompressManager = class {
     const embeddings = new Map(names.map((name, index) => [name, vectors[index]]));
     await this.grafeo.upsertEntitiesAndRelations(entities, relations, embeddings);
   }
+  /**
+   * HTTP transport already owns bounded retries for network/timeout/5xx/429.
+   * This outer layer retries semantic compression failures only: malformed model
+   * content, missing fields and empty summaries. That avoids retry multiplication.
+   */
+  async summarizeWithRetry(sessionId, label, operation) {
+    let lastError;
+    for (let attempt = 0; attempt <= this.config.compressionMaxRetries; attempt++) {
+      try {
+        const result = await operation();
+        if (typeof result?.summary !== "string" || !result.summary.trim()) {
+          throw new Error(`${label} returned an empty summary`);
+        }
+        return result;
+      } catch (error) {
+        lastError = error;
+        if (error instanceof HttpRequestError || attempt >= this.config.compressionMaxRetries) {
+          throw error;
+        }
+        const delayMs = Math.min(
+          this.config.compressionRetryBaseDelayMs * 2 ** attempt,
+          8e3
+        );
+        console.warn(
+          `[CompressManager] ${label} failed for session ${sessionId}; retrying ${attempt + 1}/${this.config.compressionMaxRetries} after ${delayMs}ms: ` + formatError(error)
+        );
+        if (delayMs > 0) await delay(delayMs);
+      }
+    }
+    throw lastError;
+  }
 };
 function sumTopicTokens(topics) {
   return topics.reduce((sum, topic) => sum + Math.max(1, topic.tokens), 0);
@@ -2395,6 +2632,9 @@ function topicOrder(a, b) {
 function formatError(error) {
   return error instanceof Error ? error.message : String(error);
 }
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function withTimeout(promise, timeoutMs, label) {
   let timer;
   const timeout = new Promise((_, reject) => {
@@ -3030,9 +3270,14 @@ var SessionCache = class {
     if (messages.length === 0 || targetTokens <= 0) return [];
     const selected = [];
     let tokens = 0;
-    for (const message of messages) {
+    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 += effectiveUsage(message);
+      tokens = nextTokens;
       if (tokens >= targetTokens) break;
     }
     return selected;
@@ -3143,7 +3388,7 @@ function effectiveUsage(message) {
   if (Number.isFinite(message.usage) && message.usage > 0) return Math.floor(message.usage);
   return Math.max(
     1,
-    (message.content.length + (message.parts?.length ?? 0) + message.metadata.length + (message.payload?.length ?? 0)) * 2
+    (message.content.length + (message.parts?.length ?? 0) + message.metadata.length + (message.payload?.length ?? 0) + (message.contextPayload?.length ?? 0)) * 2
   );
 }
 function sumMessageTokens(messages) {
@@ -3277,11 +3522,20 @@ var MemoryManager = class {
       task = (async () => {
         const allTopics = await this.store.getTopicsBySession(sessionId);
         const latestTopic = allTopics.at(-1);
-        const allRawAfterBoundary = latestTopic ? await this.store.getMessagesAfterBoundary(
+        const loadedRawAfterBoundary = latestTopic ? await this.store.getMessagesAfterBoundary(
           sessionId,
           latestTopic.endTime,
           latestTopic.endMessageId
         ) : await this.store.getAllMessagesBySession(sessionId);
+        const sanitizedRows = loadedRawAfterBoundary.map(sanitizeStoredMessageImages);
+        const repaired = sanitizedRows.filter((row) => row.changed);
+        if (repaired.length > 0) {
+          await this.store.upsertMessages(repaired.map((row) => row.message));
+          console.info(
+            `[MemoryManager] stripped ${repaired.reduce((sum, row) => sum + row.removedImages, 0)} historical image block(s) from ${repaired.length} message(s) in session ${sessionId}.`
+          );
+        }
+        const allRawAfterBoundary = sanitizedRows.map((row) => row.message);
         const since = this.config.maxHistoryAgeMs > 0 ? Date.now() - this.config.maxHistoryAgeMs : 0;
         const rawMessages = since > 0 ? allRawAfterBoundary.filter((message) => message.createdAt >= since) : allRawAfterBoundary;
         const session = this.sessionMap.get(sessionId);
@@ -3331,10 +3585,12 @@ var MemoryManager = class {
     const now = Date.now();
     await this.ensureSessionHydrated(sessionId, { chatId, userId });
     const normalized = messages.map((message) => {
-      const parts = JSON.stringify(message.parts ?? []);
-      const metadata = JSON.stringify(message.metadata ?? {});
-      const payload = message.payload === void 0 ? void 0 : JSON.stringify(message.payload);
-      const tokenInput = [message.content, parts, metadata, payload ?? ""].join("\n");
+      const sanitized = sanitizeRawHistoryFields(message);
+      const parts = JSON.stringify(sanitized.parts);
+      const metadata = JSON.stringify(sanitized.metadata);
+      const payload = sanitized.payload === void 0 ? void 0 : JSON.stringify(sanitized.payload);
+      const contextPayload = sanitized.contextPayload === void 0 ? void 0 : JSON.stringify(sanitized.contextPayload);
+      const tokenInput = [message.content, parts, metadata, payload ?? "", contextPayload ?? ""].join("\n");
       return {
         messageId: message.messageId ?? uuidv44(),
         talkerId: message.talkerId ?? "user",
@@ -3345,7 +3601,10 @@ var MemoryManager = class {
         content: message.content,
         parts,
         payload,
-        usage: message.usage ?? countTokens(tokenInput),
+        contextPayload,
+        // Host-provided usage describes the original payload. Once image bytes are
+        // stripped, recalculate against the actual persisted history budget.
+        usage: sanitized.removedImages > 0 ? countTokens(tokenInput) : message.usage ?? countTokens(tokenInput),
         metadata,
         createdAt: message.createdAt ?? now
       };
@@ -3625,6 +3884,7 @@ var MemoryManager = class {
       }
       return {
         sessionId,
+        compressionRevision: buildCompressionRevision(topics, entry.messages),
         compressedContext: this.sessionCache.buildCompressedContext(sessionId, topics),
         recentMessages: entry.messages.map(toMemoryRawMessage),
         usage: {
@@ -3883,23 +4143,36 @@ var MemoryManager = class {
   }
 };
 function toMemoryRawMessage(message) {
-  const parts = safeParseArray(message.parts);
-  const payload = message.payload === void 0 ? void 0 : safeParseValue(message.payload);
+  const sanitized = sanitizeStoredMessageImages(message).message;
+  const parts = safeParseArray(sanitized.parts);
+  const payload = sanitized.payload === void 0 ? void 0 : safeParseValue(sanitized.payload);
+  const contextPayload = sanitized.contextPayload === void 0 ? void 0 : safeParseValue(sanitized.contextPayload);
   return {
-    messageId: message.messageId,
-    talkerId: message.talkerId,
-    chatId: message.chatId,
-    userId: message.userId,
-    sessionId: message.sessionId,
-    type: message.type,
-    content: message.content,
+    messageId: sanitized.messageId,
+    talkerId: sanitized.talkerId,
+    chatId: sanitized.chatId,
+    userId: sanitized.userId,
+    sessionId: sanitized.sessionId,
+    type: sanitized.type,
+    content: sanitized.content,
     ...parts.length > 0 && { parts },
     ...payload !== void 0 && { payload },
-    usage: message.usage,
-    metadata: safeParseObject2(message.metadata),
-    createdAt: message.createdAt
+    ...contextPayload !== void 0 && { contextPayload },
+    usage: sanitized.usage,
+    metadata: safeParseObject2(sanitized.metadata),
+    createdAt: sanitized.createdAt
   };
 }
+function buildCompressionRevision(topics, messages) {
+  const lastTopic = topics.at(-1);
+  const firstRaw = messages.at(0);
+  return [
+    topics.length,
+    lastTopic?.summaryId ?? "none",
+    lastTopic?.updatedAt ?? 0,
+    firstRaw?.messageId ?? "none"
+  ].join(":");
+}
 function sumTopicTokens2(topics) {
   return topics.reduce((sum, topic) => sum + Math.max(1, topic.tokens), 0);
 }

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 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.
+> `@ppagent/memory` is an independent TypeScript/Node.js long-term memory package for AI agents. It stores semantic raw conversation history in a pluggable vector store (LanceDB or SQLite/sqlite-vec, auto-detected per platform), strips historical image payloads, 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`.
 
@@ -154,8 +154,10 @@ const memory = new MemoryManager({
   topicCompactionSyncRatio: 1.25,
   contextUsageRatio: 0.75,
   precompressionRatio: 0.75,
-  compressionBatchRatio: 0.5,
+  compressionBatchRatio: 0.7,
   compressionBatchTokenLimit: 0,
+  compressionMaxRetries: 2,
+  compressionRetryBaseDelayMs: 500,
   topicSummaryMaxTokens: 2048,
   defaultModelContextTokens: 256 * 1024,
   maxHistoryAgeMs: 0,
@@ -327,7 +329,7 @@ Embedding fallback behavior:
 HTTP and retry fields:
 
 - `httpTimeoutMs?: number` - timeout per LLM or embedding HTTP attempt. Default: `60000`.
-- `httpMaxRetries?: number` - retry count after the first attempt for network errors, timeout/abort, HTTP `429`, and HTTP `5xx`. Default: `2`.
+- `httpMaxRetries?: number` - retry count after the first attempt for network errors, timeout/abort, HTTP `429`, HTTP `5xx`, and invalid JSON in a successful HTTP response. Default: `2`.
 - `embeddingBatchSize?: number` - max texts per embedding request. Default: `20`.
 - `embeddingConcurrency?: number` - concurrent embedding batches. Default: `2`.
 
@@ -338,8 +340,10 @@ Conversation memory fields:
 - `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`.
+- `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.
 - `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.
 - `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).
@@ -374,8 +378,10 @@ The package intentionally separates durable base writes from expensive graph con
 `updateChat(messages, opts)`:
 
 - Registers its write synchronously, so a caller may intentionally fire-and-forget it and a following `getHistoryWindow` will still wait for that write.
-- Calculates tokens over `content`, `parts`, `payload`, and `metadata`, embeds the searchable text, and upserts raw messages by stable `messageId` before resolving.
-- Raw-message token usage always counts the complete stored `metadata`. When a raw batch is summarized, common tool-call/tool-result fields are removed only from the temporary LLM compression input; persisted metadata and uncompressed `recentMessages` remain unchanged.
+- 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.
+- 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.
@@ -393,7 +399,7 @@ The package intentionally separates durable base writes from expensive graph con
 
 - 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`.
+- Returns `{ compressionRevision, compressedContext, recentMessages, usage }`. `recentMessages` preserves the sanitized `RawMessage` input shape, including `messageId`, non-image `parts`, `payload`, `contextPayload`, `metadata`, and `createdAt`. `compressionRevision` changes when the returned Topic/raw compression boundary changes and is intended for host observability rather than optimistic locking.
 - 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.
@@ -423,8 +429,9 @@ Use `wait: true` when the next line of code must immediately call `searchKnowled
 - `sessionId?: string` - session id.
 - `type?: "text" | "image" | "file"` - default: `"text"`.
 - `content: string` - required plain text used for embedding and retrieval.
-- `parts?: ContentPart[]` - optional multimodal content parts; stored serialized.
-- `payload?: unknown` - host-framework message payload stored and returned without interpretation.
+- `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.
 - `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.
@@ -618,8 +625,9 @@ Context:
 
 Returns the complete model-history window:
 
+- `compressionRevision?: string` - lightweight identifier for the current Topic/raw compression boundary. Background or blocking compression changes it; ordinary raw appends are not guaranteed to do so.
 - `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.
+- `recentMessages: MemoryRawMessage[]` - all currently uncompressed raw messages in chronological order, preserving sanitized non-image host payload, replay-only context 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.

package/package.json

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