@ppagent/memory 0.4.2 → 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 }, [
@@ -3143,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) {
@@ -3334,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",
@@ -3345,6 +3355,7 @@ var MemoryManager = class {
         content: message.content,
         parts,
         payload,
+        contextPayload,
         usage: message.usage ?? countTokens(tokenInput),
         metadata,
         createdAt: message.createdAt ?? now
@@ -3625,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: {
@@ -3885,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,
@@ -3895,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,8 @@ 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.
@@ -393,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.
@@ -425,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.
@@ -618,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.2",
+  "version": "0.4.4",
   "description": "独立记忆系统模块，向量存储支持 LanceDB / SQLite(sqlite-vec) 双后端自动切换 + Grafeo 知识图谱",
   "type": "module",
   "main": "dist/index.js",