@persistio/openclaw-plugin 0.1.7 → 0.2.0

package/dist/memory-format.d.ts

@@ -0,0 +1,8 @@
+import type { RecallBundle } from './client.js';
+export declare function normalizeRecallQuery(text: string, maxChars: number): string;
+export declare function extractTextFromMessage(message: unknown): string;
+export declare function buildRecallQuery(event: {
+    prompt?: string;
+    messages?: unknown[];
+}, maxChars: number): string;
+export declare function buildMemoryBlock(bundle: RecallBundle | undefined, tokenBudget: number, relatedBundle?: RecallBundle): string;

package/dist/memory-format.js

@@ -0,0 +1,121 @@
+const BUNDLE_SECTIONS = [
+    { key: 'global_user_rules', title: 'User Rules' },
+    { key: 'user_rules', title: 'User Rules' },
+    { key: 'user_preferences', title: 'User Preferences' },
+    { key: 'constraints', title: 'Constraints' },
+    { key: 'decisions', title: 'Decisions' },
+    { key: 'task_patterns', title: 'Task Patterns' },
+    { key: 'workflows', title: 'Workflows' },
+    { key: 'project', title: 'Project Memory' },
+    { key: 'system_facts', title: 'Facts' },
+    { key: 'domain_knowledge', title: 'Domain Knowledge' },
+];
+export function normalizeRecallQuery(text, maxChars) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= maxChars)
+        return normalized;
+    return `${normalized.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+export function extractTextFromMessage(message) {
+    if (typeof message === 'string')
+        return message;
+    if (typeof message !== 'object' || message === null)
+        return '';
+    const record = message;
+    const content = record['content'];
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content
+        .map((part) => {
+        if (typeof part === 'string')
+            return part;
+        if (typeof part !== 'object' || part === null)
+            return '';
+        const partRecord = part;
+        return partRecord['type'] === 'text' && typeof partRecord['text'] === 'string'
+            ? partRecord['text']
+            : '';
+    })
+        .filter(Boolean)
+        .join('\n');
+}
+export function buildRecallQuery(event, maxChars) {
+    const prompt = typeof event.prompt === 'string' ? event.prompt : '';
+    if (prompt.trim())
+        return normalizeRecallQuery(prompt, maxChars);
+    const latestUser = Array.isArray(event.messages)
+        ? findLatestRoleText(event.messages, 'user')
+        : '';
+    return normalizeRecallQuery(latestUser, maxChars);
+}
+export function buildMemoryBlock(bundle, tokenBudget, relatedBundle) {
+    if ((!bundle && !relatedBundle) || tokenBudget <= 0)
+        return '';
+    const lines = [
+        '## Persistio Memory',
+        'Relevant durable memory:',
+    ];
+    let usedTokens = estimateTokens(lines.join('\n'));
+    for (const section of BUNDLE_SECTIONS) {
+        const items = uniqueStrings([
+            ...arrayStrings(bundle?.[section.key]),
+            ...arrayStrings(relatedBundle?.[section.key]),
+        ]);
+        for (const item of items) {
+            const line = `- ${truncateOneLine(item, 360)}`;
+            const lineTokens = estimateTokens(line);
+            if (usedTokens + lineTokens > tokenBudget) {
+                lines.push('', 'Use these only when relevant. Do not mention memory unless asked.');
+                return lines.join('\n');
+            }
+            lines.push(line);
+            usedTokens += lineTokens;
+        }
+    }
+    if (lines.length <= 2)
+        return '';
+    lines.push('', 'Use these only when relevant. Do not mention memory unless asked.');
+    return lines.join('\n');
+}
+function findLatestRoleText(messages, role) {
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = messages[index];
+        if (typeof message !== 'object' || message === null)
+            continue;
+        const record = message;
+        if (record['role'] !== role)
+            continue;
+        const text = extractTextFromMessage(message).trim();
+        if (text)
+            return text;
+    }
+    return '';
+}
+function arrayStrings(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
+function uniqueStrings(value) {
+    const seen = new Set();
+    const out = [];
+    for (const item of value) {
+        const normalized = item.replace(/\s+/g, ' ').trim();
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    return out;
+}
+function truncateOneLine(text, maxChars) {
+    const normalized = text.replace(/\s+/g, ' ').trim();
+    if (normalized.length <= maxChars)
+        return normalized;
+    return `${normalized.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}

package/openclaw.plugin.json

@@ -1,28 +1,19 @@
 {
-  "id": "openclaw-persistio",
-  "name": "Persistio Memory",
-  "description": "Persistent semantic memory for OpenClaw via Persistio",
-  "version": "0.1.7",
+  "id": "openclaw-persistio-v2",
+  "name": "Persistio Memory v2",
+  "description": "OpenClaw-native long-term memory powered by Persistio",
+  "version": "0.2.0",
   "kind": "memory",
   "activation": {
     "onStartup": true
   },
   "contracts": {
     "tools": [
-      "memory_search",
-      "memory_add",
-      "memory_delete",
-      "memory_list"
+      "memory_recall",
+      "memory_store",
+      "memory_forget"
     ]
   },
-  "toolMetadata": {
-    "memory_delete": {
-      "optional": true
-    },
-    "memory_list": {
-      "optional": true
-    }
-  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -33,24 +24,13 @@
       "apiKey": {
         "type": "string"
       },
-      "tokenBudget": {
-        "type": "number",
-        "minimum": 1
-      },
-      "recallTopK": {
-        "type": "number",
-        "minimum": 1
+      "autoRecall": {
+        "type": "boolean"
       },
-      "recallMinSimilarity": {
-        "type": "number",
-        "minimum": 0,
-        "maximum": 1
+      "autoCapture": {
+        "type": "boolean"
       },
-      "recallTimeout": {
-        "type": "number",
-        "minimum": 1
-      },
-      "ingest": {
+      "recall": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
@@ -58,94 +38,70 @@
             "type": "number",
             "minimum": 1
           },
-          "maxChunkChars": {
+          "maxResults": {
             "type": "number",
-            "minimum": 256
+            "minimum": 1
           },
-          "maxChunksPerTurn": {
+          "tokenBudget": {
             "type": "number",
             "minimum": 1
           },
-          "skipSubagentSessions": {
+          "minSimilarity": {
+            "type": "number",
+            "minimum": 0,
+            "maximum": 1
+          },
+          "includePending": {
             "type": "boolean"
           },
-          "user": {
-            "type": "object",
-            "additionalProperties": false,
-            "properties": {
-              "maxCharsPerMessage": {
-                "type": "number",
-                "minimum": 1
-              }
-            }
+          "includeRelated": {
+            "type": "boolean"
           },
-          "agent": {
-            "type": "object",
-            "additionalProperties": false,
-            "properties": {
-              "mode": {
-                "type": "string",
-                "enum": [
-                  "bounded",
-                  "raw"
-                ]
-              },
-              "maxCharsPerMessage": {
-                "type": "number",
-                "minimum": 1
-              },
-              "maxCharsAfterFiltering": {
-                "type": "number",
-                "minimum": 1
-              },
-              "maxCharsPerTurn": {
-                "type": "number",
-                "minimum": 1
-              },
-              "largeBlockThresholdChars": {
-                "type": "number",
-                "minimum": 1
-              },
-              "largeBlockThresholdLines": {
-                "type": "number",
-                "minimum": 1
-              },
-              "maxTableRows": {
-                "type": "number",
-                "minimum": 1
-              }
-            }
+          "queryMaxChars": {
+            "type": "number",
+            "minimum": 100
           }
         }
       },
-      "send": {
+      "capture": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
+          "timeoutMs": {
+            "type": "number",
+            "minimum": 1
+          },
+          "maxCharsPerTurn": {
+            "type": "number",
+            "minimum": 1
+          },
+          "maxCharsPerMessage": {
+            "type": "number",
+            "minimum": 1
+          },
+          "maxChunksPerTurn": {
+            "type": "number",
+            "minimum": 1
+          },
+          "maxChunkChars": {
+            "type": "number",
+            "minimum": 256
+          },
           "roles": {
             "type": "object",
             "additionalProperties": false,
             "properties": {
               "user": {
                 "type": "string",
-                "enum": [
-                  "enabled",
-                  "disabled"
-                ]
+                "enum": ["enabled", "disabled"]
               },
-              "agent": {
+              "assistant": {
                 "type": "string",
-                "enum": [
-                  "enabled",
-                  "disabled"
-                ]
+                "enum": ["enabled", "bounded", "disabled"]
               },
               "tool": {
                 "type": "string",
-                "enum": [
-                  "enabled",
-                  "disabled"
-                ]
+                "enum": ["enabled", "disabled"]
               }
             }
           }
@@ -156,5 +112,23 @@
       "baseURL",
       "apiKey"
     ]
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "Vault API Key",
+      "sensitive": true
+    },
+    "baseURL": {
+      "label": "Persistio Base URL",
+      "placeholder": "https://api.persistio.ai"
+    },
+    "autoRecall": {
+      "label": "Auto Recall",
+      "help": "Inject a small bounded Persistio memory block before each turn"
+    },
+    "autoCapture": {
+      "label": "Auto Capture",
+      "help": "Capture bounded durable conversation facts after successful turns"
+    }
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@persistio/openclaw-plugin",
-  "version": "0.1.7",
-  "description": "OpenClaw plugin for Persistio \u2014 persistent semantic memory for AI agents",
+  "version": "0.2.0",
+  "description": "OpenClaw-native Persistio long-term memory plugin",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -24,9 +24,8 @@
     "openclaw",
     "openclaw-plugin",
     "memory",
-    "ai",
-    "agents",
-    "persistio"
+    "persistio",
+    "long-term-memory"
   ],
   "openclaw": {
     "extensions": [
@@ -36,22 +35,22 @@
       "./dist/index.js"
     ],
     "compat": {
-      "pluginApi": ">=2026.3.24-beta.2",
-      "minGatewayVersion": "2026.3.24-beta.2"
+      "pluginApi": ">=2026.4.10",
+      "minGatewayVersion": "2026.4.10"
     }
   },
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node test/config-schema.test.mjs && node test/ingest-policy.test.mjs && node test/client-timeout.test.mjs"
+    "test": "npm run build && node test/config.test.mjs && node test/formatting.test.mjs && node test/client-timeout.test.mjs && node test/tool-timeout.test.mjs"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.0"
   },
   "devDependencies": {
-    "typescript": "^5.0.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.3.24-beta.2"
+    "openclaw": ">=2026.4.10"
   }
 }

package/src/capture.ts

@@ -0,0 +1,132 @@
+import type { IngestChunk } from './client.js';
+import type { PersistioV2Config } from './config.js';
+import { extractTextFromMessage } from './memory-format.js';
+
+export interface PreparedCapture {
+  chunks: IngestChunk[];
+  keys: string[];
+  items: CaptureItem[];
+}
+
+export interface CaptureItem {
+  key: string;
+  chunks: IngestChunk[];
+}
+
+export interface PrepareCaptureOptions {
+  shouldIncludeKey?: (key: string) => boolean;
+}
+
+export function prepareCapture(
+  event: { messages?: unknown[] },
+  cfg: PersistioV2Config,
+  options: PrepareCaptureOptions = {},
+): PreparedCapture {
+  if (!Array.isArray(event.messages)) return { chunks: [], keys: [], items: [] };
+
+  const chunks: IngestChunk[] = [];
+  const keys: string[] = [];
+  const items: CaptureItem[] = [];
+  let turnChars = 0;
+
+  for (const [index, message] of event.messages.entries()) {
+    const role = normalizeRole(message);
+    if (!role || !shouldCaptureRole(role, cfg)) continue;
+
+    const rawText = extractTextFromMessage(message);
+    const key = messageKey(message, role, rawText, index);
+    if (options.shouldIncludeKey && !options.shouldIncludeKey(key)) continue;
+
+    if (chunks.length >= cfg.capture.maxChunksPerTurn) break;
+    const preparedText = prepareTextForRole(rawText, role, cfg);
+    if (!preparedText) continue;
+
+    const remainingTurnChars = cfg.capture.maxCharsPerTurn - turnChars;
+    if (remainingTurnChars <= 0) break;
+
+    const boundedText = truncate(preparedText, Math.min(cfg.capture.maxCharsPerMessage, remainingTurnChars));
+    const itemChunks: IngestChunk[] = [];
+    for (const chunk of chunkText(boundedText, cfg.capture.maxChunkChars)) {
+      if (chunks.length >= cfg.capture.maxChunksPerTurn) break;
+      const ingestChunk = {
+        role,
+        content: chunk,
+        timestamp: resolveTimestamp(message) ?? new Date().toISOString(),
+      };
+      chunks.push(ingestChunk);
+      itemChunks.push(ingestChunk);
+      turnChars += chunk.length;
+    }
+    if (itemChunks.length > 0) {
+      keys.push(key);
+      items.push({ key, chunks: itemChunks });
+    }
+  }
+
+  return { chunks, keys, items };
+}
+
+function normalizeRole(message: unknown): 'user' | 'assistant' | 'tool' | null {
+  if (typeof message !== 'object' || message === null) return null;
+  const role = (message as Record<string, unknown>)['role'];
+  return role === 'user' || role === 'assistant' || role === 'tool' ? role : null;
+}
+
+function shouldCaptureRole(role: 'user' | 'assistant' | 'tool', cfg: PersistioV2Config): boolean {
+  if (role === 'user') return cfg.capture.roles.user === 'enabled';
+  if (role === 'assistant') return cfg.capture.roles.assistant !== 'disabled';
+  return cfg.capture.roles.tool === 'enabled';
+}
+
+function prepareTextForRole(text: string, role: 'user' | 'assistant' | 'tool', cfg: PersistioV2Config): string {
+  const normalized = normalizeText(text);
+  if (!normalized) return '';
+  if (role !== 'assistant' || cfg.capture.roles.assistant !== 'bounded') {
+    return normalized;
+  }
+
+  return normalized
+    .replace(/```[\s\S]*?```/g, '[Code block omitted from memory capture]')
+    .replace(/\n(?:[|].*[|]\n){8,}/g, '\n[Large table omitted from memory capture]\n')
+    .replace(/\n(?:[-+].*\n){20,}/g, '\n[Large diff/log omitted from memory capture]\n')
+    .trim();
+}
+
+function normalizeText(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{4,}/g, '\n\n\n')
+    .trim();
+}
+
+function chunkText(text: string, maxChars: number): string[] {
+  if (text.length <= maxChars) return [text];
+  const chunks: string[] = [];
+  for (let start = 0; start < text.length; start += maxChars) {
+    const chunk = text.slice(start, start + maxChars).trim();
+    if (chunk) chunks.push(chunk);
+  }
+  return chunks;
+}
+
+function truncate(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+
+function resolveTimestamp(message: unknown): string | undefined {
+  if (typeof message !== 'object' || message === null) return undefined;
+  const value = (message as Record<string, unknown>)['timestamp'];
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' && Number.isFinite(value)) return new Date(value).toISOString();
+  return undefined;
+}
+
+function messageKey(message: unknown, role: string, text: string, index: number): string {
+  if (typeof message === 'object' && message !== null) {
+    const id = (message as Record<string, unknown>)['id'];
+    if (typeof id === 'string' && id) return `${role}:${id}`;
+  }
+  return `${role}:${index}:${text.slice(0, 300)}`;
+}