@ppagent/memory 0.4.1 → 0.4.4

package/dist/cli.js

@@ -159,6 +159,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 +291,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 +310,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,
@@ -594,7 +597,13 @@ var MemoryStore = class {
     report.messagesScanned = messageRows.length;
     for (const row of messageRows) {
       const usage2 = countTokens(
-        [row.content, row.parts ?? "[]", row.metadata ?? "{}", row.payload ?? ""].map(String).join("\n")
+        [
+          row.content,
+          row.parts ?? "[]",
+          row.metadata ?? "{}",
+          row.payload ?? "",
+          row.context_payload ?? ""
+        ].map(String).join("\n")
       );
       if (Number(row.usage) === usage2) continue;
       await this.provider.update(MESSAGES_TABLE, { usage: usage2 }, [

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;

package/dist/index.js

@@ -827,6 +827,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 +959,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 +978,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,
@@ -1262,7 +1265,13 @@ var MemoryStore = class {
     report.messagesScanned = messageRows.length;
     for (const row of messageRows) {
       const usage = countTokens(
-        [row.content, row.parts ?? "[]", row.metadata ?? "{}", row.payload ?? ""].map(String).join("\n")
+        [
+          row.content,
+          row.parts ?? "[]",
+          row.metadata ?? "{}",
+          row.payload ?? "",
+          row.context_payload ?? ""
+        ].map(String).join("\n")
       );
       if (Number(row.usage) === usage) continue;
       await this.provider.update(MESSAGES_TABLE, { usage }, [
@@ -1874,7 +1883,7 @@ var LlmService = class {
 
 \u8F93\u51FA\u5FC5\u987B\u662F\u5408\u6CD5\u7684 JSON \u5BF9\u8C61\uFF0C\u4E0D\u8981\u5305\u542B\u4EFB\u4F55 markdown \u6807\u8BB0\uFF0C\u683C\u5F0F\u5982\u4E0B\uFF1A
 {"title": "...", "summary": "..."}`;
-    const formatted = messages.map((m) => formatStoredMessage(m)).join("\n");
+    const formatted = messages.map((m) => formatStoredMessageForCompression(m)).join("\n");
     const response = await this.chatCompletionWithUsage(
       systemPrompt,
       `\u8BF7\u538B\u7F29\u4EE5\u4E0B\u5BF9\u8BDD\uFF1A
@@ -2039,11 +2048,81 @@ ${text}`
 ${context}`, false);
   }
 };
-function formatStoredMessage(message) {
-  const extras = [message.parts, message.metadata, message.payload].filter((value) => value && value !== "[]" && value !== "{}").join(" ");
+function formatStoredMessageForCompression(message) {
+  const metadata = stripToolCallContentFromMetadata(message.metadata);
+  const extras = [message.parts, metadata, message.payload].filter((value) => value && value !== "[]" && value !== "{}").join(" ");
   return `[${new Date(message.createdAt).toISOString()}] ${message.talkerId || "user"}: ${message.content}${extras ? `
 meta=${extras}` : ""}`;
 }
+var OMIT_COMPRESSION_VALUE = Symbol("omit-compression-value");
+var TOOL_CALL_CONTAINER_KEYS = /* @__PURE__ */ new Set([
+  "toolcall",
+  "toolcalls",
+  "toolresult",
+  "toolresults",
+  "tooloutput",
+  "tooloutputs",
+  "toolresponse",
+  "toolresponses",
+  "tooluse",
+  "tooluses",
+  "functioncall",
+  "functioncalls",
+  "functionresponse",
+  "functionresponses"
+]);
+var TOOL_CALL_ID_KEYS = /* @__PURE__ */ new Set(["toolcallid", "tooluseid"]);
+var TOOL_BLOCK_TYPES = /* @__PURE__ */ new Set([
+  "toolcall",
+  "tooloutput",
+  "toolresponse",
+  "toolresult",
+  "tooluse",
+  "functioncall",
+  "functionresponse"
+]);
+function stripToolCallContentFromMetadata(metadata) {
+  if (!metadata || metadata === "{}") return metadata;
+  try {
+    const parsed = JSON.parse(metadata);
+    const sanitized = stripToolCallContent(parsed);
+    return JSON.stringify(sanitized === OMIT_COMPRESSION_VALUE ? {} : sanitized);
+  } catch {
+    return metadata;
+  }
+}
+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 (isToolCallBlock(value)) return OMIT_COMPRESSION_VALUE;
+  const sanitized = {};
+  for (const [key, child] of Object.entries(value)) {
+    const normalizedKey = normalizeToolKey(key);
+    if (TOOL_CALL_CONTAINER_KEYS.has(normalizedKey) || TOOL_CALL_ID_KEYS.has(normalizedKey)) {
+      continue;
+    }
+    const next = stripToolCallContent(child);
+    if (next !== OMIT_COMPRESSION_VALUE) sanitized[key] = next;
+  }
+  return sanitized;
+}
+function isToolCallBlock(value) {
+  const role = typeof value.role === "string" ? normalizeToolKey(value.role) : "";
+  const type = typeof value.type === "string" ? normalizeToolKey(value.type) : "";
+  if (role === "tool" || role === "function") return true;
+  if (TOOL_BLOCK_TYPES.has(type)) return true;
+  const normalizedKeys = new Set(Object.keys(value).map(normalizeToolKey));
+  const hasToolCallId = [...TOOL_CALL_ID_KEYS].some((key) => normalizedKeys.has(key));
+  return hasToolCallId && ["content", "output", "result", "response"].some((key) => normalizedKeys.has(key));
+}
+function normalizeToolKey(value) {
+  return value.replace(/[\s_-]/g, "").toLowerCase();
+}
+function isRecord(value) {
+  return value !== null && typeof value === "object";
+}
 
 // src/manager/compress.manager.ts
 import { v4 as uuidv4 } from "uuid";
@@ -3073,7 +3152,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) {
@@ -3264,7 +3343,8 @@ var MemoryManager = class {
       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 contextPayload = message.contextPayload === void 0 ? void 0 : JSON.stringify(message.contextPayload);
+      const tokenInput = [message.content, parts, metadata, payload ?? "", contextPayload ?? ""].join("\n");
       return {
         messageId: message.messageId ?? uuidv44(),
         talkerId: message.talkerId ?? "user",
@@ -3275,6 +3355,7 @@ var MemoryManager = class {
         content: message.content,
         parts,
         payload,
+        contextPayload,
         usage: message.usage ?? countTokens(tokenInput),
         metadata,
         createdAt: message.createdAt ?? now
@@ -3555,6 +3636,7 @@ var MemoryManager = class {
       }
       return {
         sessionId,
+        compressionRevision: buildCompressionRevision(topics, entry.messages),
         compressedContext: this.sessionCache.buildCompressedContext(sessionId, topics),
         recentMessages: entry.messages.map(toMemoryRawMessage),
         usage: {
@@ -3815,6 +3897,7 @@ var MemoryManager = class {
 function toMemoryRawMessage(message) {
   const parts = safeParseArray(message.parts);
   const payload = message.payload === void 0 ? void 0 : safeParseValue(message.payload);
+  const contextPayload = message.contextPayload === void 0 ? void 0 : safeParseValue(message.contextPayload);
   return {
     messageId: message.messageId,
     talkerId: message.talkerId,
@@ -3825,11 +3908,22 @@ function toMemoryRawMessage(message) {
     content: message.content,
     ...parts.length > 0 && { parts },
     ...payload !== void 0 && { payload },
+    ...contextPayload !== void 0 && { contextPayload },
     usage: message.usage,
     metadata: safeParseObject2(message.metadata),
     createdAt: message.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

@@ -374,7 +374,9 @@ 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.
+- Calculates tokens over `content`, `parts`, `payload`, `contextPayload`, and `metadata`, embeds only the searchable text, and upserts raw messages by stable `messageId` before resolving.
+- `contextPayload` is a replay-only host payload: it is stored and returned unchanged and counts toward the raw budget, but is excluded from embedding, FTS, Topic-summary input, and conversation graph extraction.
+- 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.
 - 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.
@@ -392,7 +394,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 `RawMessage` input shape, including `messageId`, `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.
@@ -424,6 +426,7 @@ Use `wait: true` when the next line of code must immediately call `searchKnowled
 - `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.
+- `contextPayload?: unknown` - replay-only host context stored and returned without interpretation. It 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.
@@ -617,8 +620,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 the 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.1",
+  "version": "0.4.4",
   "description": "独立记忆系统模块，向量存储支持 LanceDB / SQLite(sqlite-vec) 双后端自动切换 + Grafeo 知识图谱",
   "type": "module",
   "main": "dist/index.js",