@persistio/openclaw-plugin 0.1.2 → 0.1.4

package/README.md

@@ -25,7 +25,14 @@ Then register it in your OpenClaw config:
         "package": "@persistio/openclaw-plugin",
         "config": {
           "baseURL": "https://api.persistio.ai",
-          "apiKey": "your-vault-api-key"
+          "apiKey": "your-vault-api-key",
+          "send": {
+            "roles": {
+              "user": "enabled",
+              "agent": "enabled",
+              "tool": "disabled"
+            }
+          }
         }
       }
     }
@@ -42,6 +49,11 @@ Then register it in your OpenClaw config:
 | `tokenBudget` | number | | `2000` | Max tokens to inject into the system prompt |
 | `recallTopK` | number | | `10` | Number of memories to retrieve per recall |
 | `recallTimeout` | number | | `5000` | HTTP timeout for recall requests (ms) |
+| `send.roles.user` | `"enabled"` or `"disabled"` | | `"enabled"` | Send user messages to Persistio ingest |
+| `send.roles.agent` | `"enabled"` or `"disabled"` | | `"enabled"` | Send agent/assistant messages to Persistio ingest |
+| `send.roles.tool` | `"enabled"` or `"disabled"` | | `"disabled"` | Send tool messages to Persistio ingest |
+
+`agent_end` receives a snapshot of the active OpenClaw transcript, so the plugin deduplicates per session and only sends each user, agent, or enabled tool message once per plugin process. Deduplication keys are bounded in memory and expire after 24 hours of session inactivity.
 
 ## Tools exposed
 

package/dist/client.d.ts

@@ -4,6 +4,15 @@ export interface PersistioConfig {
     tokenBudget: number;
     recallTopK: number;
     recallTimeout: number;
+    send: PersistioSendConfig;
+}
+export type PersistioSendRoleStatus = 'enabled' | 'disabled';
+export interface PersistioSendConfig {
+    roles: {
+        user: PersistioSendRoleStatus;
+        agent: PersistioSendRoleStatus;
+        tool: PersistioSendRoleStatus;
+    };
 }
 export interface PersistioMemory {
     id: string;

package/dist/index.js

@@ -1,6 +1,30 @@
 import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
 import { Type } from '@sinclair/typebox';
 import { PersistioClient } from './client.js';
+const DEFAULT_SEND_ROLES = {
+    user: 'enabled',
+    agent: 'enabled',
+    tool: 'disabled',
+};
+const MESSAGE_KEY_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_TRACKED_SESSIONS = 250;
+const MAX_SENT_KEYS_PER_SESSION = 2000;
+function resolveSendConfig(raw) {
+    const send = raw['send'];
+    const roles = typeof send === 'object' && send !== null
+        ? send['roles']
+        : undefined;
+    const rawRoles = typeof roles === 'object' && roles !== null
+        ? roles
+        : {};
+    return {
+        roles: {
+            user: rawRoles['user'] === 'disabled' ? 'disabled' : DEFAULT_SEND_ROLES.user,
+            agent: rawRoles['agent'] === 'disabled' ? 'disabled' : DEFAULT_SEND_ROLES.agent,
+            tool: rawRoles['tool'] === 'enabled' ? 'enabled' : DEFAULT_SEND_ROLES.tool,
+        },
+    };
+}
 function resolveConfig(raw) {
     const c = (raw ?? {});
     return {
@@ -9,6 +33,7 @@ function resolveConfig(raw) {
         tokenBudget: typeof c['tokenBudget'] === 'number' ? c['tokenBudget'] : 2000,
         recallTopK: typeof c['recallTopK'] === 'number' ? c['recallTopK'] : 10,
         recallTimeout: typeof c['recallTimeout'] === 'number' ? c['recallTimeout'] : 5000,
+        send: resolveSendConfig(c),
     };
 }
 function estimateTokens(text) {
@@ -117,13 +142,23 @@ function buildMemoryBlock(bundle, budget) {
     }
     return lines.length > 1 ? lines.join('\n') : '';
 }
+function normalizeRole(role) {
+    if (role === 'user' || role === 'assistant' || role === 'tool')
+        return role;
+    return null;
+}
+function shouldSendRole(role, config) {
+    if (role === 'assistant')
+        return config.send.roles.agent === 'enabled';
+    return config.send.roles[role] === 'enabled';
+}
 /** Extract plain text from a pi-agent-core message content array */
-function extractTextFromMessage(msg) {
+function extractTextFromMessage(msg, allowedRoles = ['user', 'assistant']) {
     if (typeof msg !== 'object' || msg === null)
         return null;
     const m = msg;
-    const role = m['role'];
-    if (role !== 'user' && role !== 'assistant')
+    const role = normalizeRole(m['role']);
+    if (!role || !allowedRoles.includes(role))
         return null;
     const content = m['content'];
     if (!Array.isArray(content)) {
@@ -143,6 +178,193 @@ function extractTextFromMessage(msg) {
     }
     return parts.length > 0 ? parts.join(' ') : null;
 }
+function resolveMessageTimestamp(msg) {
+    if (typeof msg['timestamp'] === 'number')
+        return new Date(msg['timestamp']).toISOString();
+    if (typeof msg['timestamp'] === 'string')
+        return msg['timestamp'];
+    return null;
+}
+function hashString(input) {
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < input.length; i += 1) {
+        hash ^= input.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return (hash >>> 0).toString(16);
+}
+function buildMessageFingerprint(params) {
+    const id = params.msg['id'];
+    if (typeof id === 'string' && id.length > 0) {
+        return `id:${params.sessionId}:${id}`;
+    }
+    const idempotencyKey = params.msg['idempotencyKey'];
+    if (typeof idempotencyKey === 'string' && idempotencyKey.length > 0) {
+        return `idempotency:${params.sessionId}:${idempotencyKey}`;
+    }
+    const timestamp = resolveMessageTimestamp(params.msg);
+    const basis = timestamp ?? `index:${params.index}`;
+    return `content:${params.sessionId}:${basis}:${params.role}:${hashString(params.text)}`;
+}
+function pruneSessionKeyStores(stores, now) {
+    for (const [sessionId, store] of stores) {
+        if (now - store.lastSeen > MESSAGE_KEY_TTL_MS)
+            stores.delete(sessionId);
+    }
+    while (stores.size > MAX_TRACKED_SESSIONS) {
+        const oldest = [...stores.entries()].sort((a, b) => a[1].lastSeen - b[1].lastSeen)[0];
+        if (!oldest)
+            return;
+        stores.delete(oldest[0]);
+    }
+}
+function getSessionKeyStore(stores, sessionId, now) {
+    pruneSessionKeyStores(stores, now);
+    const existing = stores.get(sessionId);
+    if (existing) {
+        existing.lastSeen = now;
+        return existing.keys;
+    }
+    const created = { keys: new Set(), lastSeen: now };
+    stores.set(sessionId, created);
+    return created.keys;
+}
+function rememberKeys(target, keys, limit = Number.POSITIVE_INFINITY) {
+    for (const key of keys) {
+        target.add(key);
+        while (target.size > limit) {
+            const oldest = target.values().next().value;
+            if (!oldest)
+                break;
+            target.delete(oldest);
+        }
+    }
+}
+function forgetKeys(target, keys) {
+    for (const key of keys)
+        target.delete(key);
+}
+const PERSISTIO_MEMORY_PATH_PREFIX = 'persistio://memory/';
+function createClient(config, recallTopK = config.recallTopK) {
+    return new PersistioClient({ ...config, recallTopK });
+}
+function normalizeMemoryScore(memory) {
+    if (typeof memory.similarity === 'number' && Number.isFinite(memory.similarity)) {
+        return memory.similarity;
+    }
+    if (Number.isFinite(memory.confidence)) {
+        return memory.confidence > 1 ? memory.confidence / 100 : memory.confidence;
+    }
+    return 0;
+}
+function buildMemoryPath(id) {
+    return `${PERSISTIO_MEMORY_PATH_PREFIX}${id}`;
+}
+function parseMemoryPath(relPath) {
+    return relPath.startsWith(PERSISTIO_MEMORY_PATH_PREFIX)
+        ? relPath.slice(PERSISTIO_MEMORY_PATH_PREFIX.length)
+        : null;
+}
+function formatMemoryDocument(memory) {
+    const lines = [
+        `Subject: ${memory.subject}`,
+        `Memory ID: ${memory.id}`,
+        `Confidence: ${memory.confidence}`,
+    ];
+    if (memory.categories.length > 0) {
+        lines.push(`Categories: ${memory.categories.join(', ')}`);
+    }
+    lines.push('', memory.data);
+    return lines.join('\n');
+}
+async function probePersistio(client) {
+    try {
+        await client.recall('__openclaw_probe__');
+        return { ok: true };
+    }
+    catch (err) {
+        return { ok: false, error: String(err) };
+    }
+}
+function createMemorySearchManager(config) {
+    const client = createClient(config);
+    return {
+        async search(query, opts) {
+            if (opts?.sources && !opts.sources.includes('memory')) {
+                return [];
+            }
+            const recallTopK = typeof opts?.maxResults === 'number' ? opts.maxResults : config.recallTopK;
+            const recallClient = createClient(config, recallTopK);
+            const memories = await recallClient.recall(query);
+            return memories
+                .map((memory) => {
+                const score = normalizeMemoryScore(memory);
+                return {
+                    path: buildMemoryPath(memory.id),
+                    startLine: 1,
+                    endLine: 1,
+                    score,
+                    vectorScore: typeof memory.similarity === 'number' ? memory.similarity : undefined,
+                    snippet: truncate(memory.data, 400),
+                    source: 'memory',
+                    citation: memory.subject,
+                };
+            })
+                .filter((result) => opts?.minScore === undefined || result.score >= opts.minScore);
+        },
+        async readFile(params) {
+            const memoryId = parseMemoryPath(params.relPath);
+            if (!memoryId) {
+                throw new Error(`Unsupported Persistio memory path: ${params.relPath}`);
+            }
+            const memories = await client.listMemories();
+            const memory = memories.find((item) => item.id === memoryId);
+            if (!memory) {
+                throw new Error(`Persistio memory not found: ${memoryId}`);
+            }
+            const text = formatMemoryDocument(memory);
+            return {
+                path: params.relPath,
+                text,
+                truncated: false,
+                from: params.from ?? 1,
+                lines: params.lines,
+            };
+        },
+        status() {
+            return {
+                backend: 'builtin',
+                provider: 'persistio',
+                sources: ['memory'],
+                vector: {
+                    enabled: true,
+                },
+                custom: {
+                    baseURL: config.baseURL,
+                },
+            };
+        },
+        async probeEmbeddingAvailability() {
+            return probePersistio(client);
+        },
+        async probeVectorAvailability() {
+            const probe = await probePersistio(client);
+            return probe.ok;
+        },
+    };
+}
+function createMemoryRuntime(config) {
+    return {
+        async getMemorySearchManager() {
+            return {
+                manager: createMemorySearchManager(config),
+            };
+        },
+        resolveMemoryBackendConfig() {
+            return { backend: 'builtin' };
+        },
+    };
+}
 export default definePluginEntry({
     id: 'openclaw-persistio',
     name: 'Persistio Memory',
@@ -153,7 +375,12 @@ export default definePluginEntry({
             api.logger?.warn?.('openclaw-persistio: baseURL and apiKey are required. Plugin disabled.');
             return;
         }
-        const client = new PersistioClient(cfg);
+        const client = createClient(cfg);
+        const sentMessageKeysBySession = new Map();
+        const pendingMessageKeysBySession = new Map();
+        api.registerMemoryCapability({
+            runtime: createMemoryRuntime(cfg),
+        });
         // -------------------------------------------------------------------------
         // before_prompt_build — recall relevant memories and inject into context
         // Event: { prompt: string, messages: unknown[] }
@@ -177,30 +404,43 @@ export default definePluginEntry({
         // Event: { runId?, messages: unknown[], success: boolean, error?, durationMs? }
         // Observation only — no return value.
         // -------------------------------------------------------------------------
-        api.on('agent_end', async (event) => {
+        api.on('agent_end', async (event, context) => {
             try {
-                const sessionId = event.runId ?? 'unknown-session';
+                const sessionId = context?.sessionId ?? event.runId ?? 'unknown-session';
+                if (sessionId.startsWith('announce:'))
+                    return;
                 const chunks = [];
-                for (const msg of event.messages) {
+                const chunkKeys = [];
+                const now = Date.now();
+                const sentKeys = getSessionKeyStore(sentMessageKeysBySession, sessionId, now);
+                const pendingKeys = getSessionKeyStore(pendingMessageKeysBySession, sessionId, now);
+                for (const [index, msg] of event.messages.entries()) {
                     const m = msg;
-                    const role = m['role'];
-                    if (role !== 'user' && role !== 'assistant')
+                    const role = normalizeRole(m['role']);
+                    if (!role || !shouldSendRole(role, cfg))
+                        continue;
+                    const text = extractTextFromMessage(msg, ['user', 'assistant', 'tool']);
+                    if (!text || text.length === 0)
+                        continue;
+                    const key = buildMessageFingerprint({ sessionId, msg: m, role, text, index });
+                    if (sentKeys.has(key) || pendingKeys.has(key))
                         continue;
-                    const text = extractTextFromMessage(msg);
-                    const ts = typeof m['timestamp'] === 'number'
-                        ? new Date(m['timestamp']).toISOString()
-                        : typeof m['timestamp'] === 'string'
-                            ? m['timestamp']
-                            : new Date().toISOString();
-                    if (text && text.length > 0) {
-                        chunks.push({ role: role, content: text, timestamp: ts });
-                    }
+                    const ts = resolveMessageTimestamp(m) ?? new Date().toISOString();
+                    chunkKeys.push(key);
+                    chunks.push({ role, content: text, timestamp: ts });
                 }
                 if (chunks.length === 0)
                     return;
-                // Fire and forget — agent_end is async but result is ignored
-                client.ingest(sessionId, chunks).catch((err) => {
+                rememberKeys(pendingKeys, chunkKeys);
+                client.ingest(sessionId, chunks)
+                    .then(() => {
+                    rememberKeys(sentKeys, chunkKeys, MAX_SENT_KEYS_PER_SESSION);
+                })
+                    .catch((err) => {
                     api.logger?.warn?.(`openclaw-persistio: ingest error: ${String(err)}`);
+                })
+                    .finally(() => {
+                    forgetKeys(pendingKeys, chunkKeys);
                 });
             }
             catch (err) {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-persistio",
   "name": "Persistio Memory",
   "description": "Persistent semantic memory for OpenClaw via Persistio",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "kind": "memory",
   "activation": {
     "onStartup": true
@@ -33,6 +33,39 @@
       },
       "recallTimeout": {
         "type": "number"
+      },
+      "send": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "roles": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "user": {
+                "type": "string",
+                "enum": [
+                  "enabled",
+                  "disabled"
+                ]
+              },
+              "agent": {
+                "type": "string",
+                "enum": [
+                  "enabled",
+                  "disabled"
+                ]
+              },
+              "tool": {
+                "type": "string",
+                "enum": [
+                  "enabled",
+                  "disabled"
+                ]
+              }
+            }
+          }
+        }
       }
     },
     "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persistio/openclaw-plugin",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "OpenClaw plugin for Persistio \u2014 persistent semantic memory for AI agents",
   "type": "module",
   "main": "./dist/index.js",

package/src/client.ts

@@ -4,6 +4,17 @@ export interface PersistioConfig {
   tokenBudget: number;
   recallTopK: number;
   recallTimeout: number;
+  send: PersistioSendConfig;
+}
+
+export type PersistioSendRoleStatus = 'enabled' | 'disabled';
+
+export interface PersistioSendConfig {
+  roles: {
+    user: PersistioSendRoleStatus;
+    agent: PersistioSendRoleStatus;
+    tool: PersistioSendRoleStatus;
+  };
 }
 
 export interface PersistioMemory {

package/src/index.ts

@@ -1,6 +1,47 @@
 import { definePluginEntry } from 'openclaw/plugin-sdk/plugin-entry';
+import type {
+  MemoryEmbeddingProbeResult,
+  MemoryProviderStatus,
+  MemorySearchManager,
+  MemorySearchResult,
+} from 'openclaw/plugin-sdk/memory-core-host-engine-storage';
 import { Type } from '@sinclair/typebox';
-import { PersistioClient, type PersistioConfig, type RecallBundle } from './client.js';
+import { PersistioClient, type PersistioConfig, type PersistioMemory, type RecallBundle } from './client.js';
+
+type OpenClawMessageRole = 'user' | 'assistant' | 'tool';
+
+interface SessionMessageKeyStore {
+  keys: Set<string>;
+  lastSeen: number;
+}
+
+const DEFAULT_SEND_ROLES: PersistioConfig['send']['roles'] = {
+  user: 'enabled',
+  agent: 'enabled',
+  tool: 'disabled',
+};
+
+const MESSAGE_KEY_TTL_MS = 24 * 60 * 60 * 1000;
+const MAX_TRACKED_SESSIONS = 250;
+const MAX_SENT_KEYS_PER_SESSION = 2000;
+
+function resolveSendConfig(raw: Record<string, unknown>): PersistioConfig['send'] {
+  const send = raw['send'];
+  const roles = typeof send === 'object' && send !== null
+    ? (send as Record<string, unknown>)['roles']
+    : undefined;
+  const rawRoles = typeof roles === 'object' && roles !== null
+    ? roles as Record<string, unknown>
+    : {};
+
+  return {
+    roles: {
+      user: rawRoles['user'] === 'disabled' ? 'disabled' : DEFAULT_SEND_ROLES.user,
+      agent: rawRoles['agent'] === 'disabled' ? 'disabled' : DEFAULT_SEND_ROLES.agent,
+      tool: rawRoles['tool'] === 'enabled' ? 'enabled' : DEFAULT_SEND_ROLES.tool,
+    },
+  };
+}
 
 function resolveConfig(raw: unknown): PersistioConfig {
   const c = (raw ?? {}) as Record<string, unknown>;
@@ -10,6 +51,7 @@ function resolveConfig(raw: unknown): PersistioConfig {
     tokenBudget: typeof c['tokenBudget'] === 'number' ? c['tokenBudget'] : 2000,
     recallTopK: typeof c['recallTopK'] === 'number' ? c['recallTopK'] : 10,
     recallTimeout: typeof c['recallTimeout'] === 'number' ? c['recallTimeout'] : 5000,
+    send: resolveSendConfig(c),
   };
 }
 
@@ -130,12 +172,22 @@ function buildMemoryBlock(bundle: RecallBundle, budget: number): string {
   return lines.length > 1 ? lines.join('\n') : '';
 }
 
+function normalizeRole(role: unknown): OpenClawMessageRole | null {
+  if (role === 'user' || role === 'assistant' || role === 'tool') return role;
+  return null;
+}
+
+function shouldSendRole(role: OpenClawMessageRole, config: PersistioConfig): boolean {
+  if (role === 'assistant') return config.send.roles.agent === 'enabled';
+  return config.send.roles[role] === 'enabled';
+}
+
 /** Extract plain text from a pi-agent-core message content array */
-function extractTextFromMessage(msg: unknown): string | null {
+function extractTextFromMessage(msg: unknown, allowedRoles: OpenClawMessageRole[] = ['user', 'assistant']): string | null {
   if (typeof msg !== 'object' || msg === null) return null;
   const m = msg as Record<string, unknown>;
-  const role = m['role'];
-  if (role !== 'user' && role !== 'assistant') return null;
+  const role = normalizeRole(m['role']);
+  if (!role || !allowedRoles.includes(role)) return null;
   const content = m['content'];
   if (!Array.isArray(content)) {
     // Some messages have content as a plain string
@@ -154,6 +206,238 @@ function extractTextFromMessage(msg: unknown): string | null {
   return parts.length > 0 ? parts.join(' ') : null;
 }
 
+function resolveMessageTimestamp(msg: Record<string, unknown>): string | null {
+  if (typeof msg['timestamp'] === 'number') return new Date(msg['timestamp']).toISOString();
+  if (typeof msg['timestamp'] === 'string') return msg['timestamp'];
+  return null;
+}
+
+function hashString(input: string): string {
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= input.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16);
+}
+
+function buildMessageFingerprint(params: {
+  sessionId: string;
+  msg: Record<string, unknown>;
+  role: OpenClawMessageRole;
+  text: string;
+  index: number;
+}): string {
+  const id = params.msg['id'];
+  if (typeof id === 'string' && id.length > 0) {
+    return `id:${params.sessionId}:${id}`;
+  }
+
+  const idempotencyKey = params.msg['idempotencyKey'];
+  if (typeof idempotencyKey === 'string' && idempotencyKey.length > 0) {
+    return `idempotency:${params.sessionId}:${idempotencyKey}`;
+  }
+
+  const timestamp = resolveMessageTimestamp(params.msg);
+  const basis = timestamp ?? `index:${params.index}`;
+  return `content:${params.sessionId}:${basis}:${params.role}:${hashString(params.text)}`;
+}
+
+function pruneSessionKeyStores(stores: Map<string, SessionMessageKeyStore>, now: number): void {
+  for (const [sessionId, store] of stores) {
+    if (now - store.lastSeen > MESSAGE_KEY_TTL_MS) stores.delete(sessionId);
+  }
+
+  while (stores.size > MAX_TRACKED_SESSIONS) {
+    const oldest = [...stores.entries()].sort((a, b) => a[1].lastSeen - b[1].lastSeen)[0];
+    if (!oldest) return;
+    stores.delete(oldest[0]);
+  }
+}
+
+function getSessionKeyStore(stores: Map<string, SessionMessageKeyStore>, sessionId: string, now: number): Set<string> {
+  pruneSessionKeyStores(stores, now);
+  const existing = stores.get(sessionId);
+  if (existing) {
+    existing.lastSeen = now;
+    return existing.keys;
+  }
+
+  const created: SessionMessageKeyStore = { keys: new Set(), lastSeen: now };
+  stores.set(sessionId, created);
+  return created.keys;
+}
+
+function rememberKeys(target: Set<string>, keys: string[], limit = Number.POSITIVE_INFINITY): void {
+  for (const key of keys) {
+    target.add(key);
+    while (target.size > limit) {
+      const oldest = target.values().next().value as string | undefined;
+      if (!oldest) break;
+      target.delete(oldest);
+    }
+  }
+}
+
+function forgetKeys(target: Set<string>, keys: string[]): void {
+  for (const key of keys) target.delete(key);
+}
+
+const PERSISTIO_MEMORY_PATH_PREFIX = 'persistio://memory/';
+
+function createClient(config: PersistioConfig, recallTopK = config.recallTopK): PersistioClient {
+  return new PersistioClient({ ...config, recallTopK });
+}
+
+function normalizeMemoryScore(memory: PersistioMemory): number {
+  if (typeof memory.similarity === 'number' && Number.isFinite(memory.similarity)) {
+    return memory.similarity;
+  }
+  if (Number.isFinite(memory.confidence)) {
+    return memory.confidence > 1 ? memory.confidence / 100 : memory.confidence;
+  }
+  return 0;
+}
+
+function buildMemoryPath(id: string): string {
+  return `${PERSISTIO_MEMORY_PATH_PREFIX}${id}`;
+}
+
+function parseMemoryPath(relPath: string): string | null {
+  return relPath.startsWith(PERSISTIO_MEMORY_PATH_PREFIX)
+    ? relPath.slice(PERSISTIO_MEMORY_PATH_PREFIX.length)
+    : null;
+}
+
+function formatMemoryDocument(memory: PersistioMemory): string {
+  const lines = [
+    `Subject: ${memory.subject}`,
+    `Memory ID: ${memory.id}`,
+    `Confidence: ${memory.confidence}`,
+  ];
+
+  if (memory.categories.length > 0) {
+    lines.push(`Categories: ${memory.categories.join(', ')}`);
+  }
+
+  lines.push('', memory.data);
+  return lines.join('\n');
+}
+
+async function probePersistio(client: PersistioClient): Promise<MemoryEmbeddingProbeResult> {
+  try {
+    await client.recall('__openclaw_probe__');
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: String(err) };
+  }
+}
+
+function createMemorySearchManager(config: PersistioConfig): MemorySearchManager {
+  const client = createClient(config);
+
+  return {
+    async search(
+      query: string,
+      opts?: {
+        maxResults?: number;
+        minScore?: number;
+        sessionKey?: string;
+        qmdSearchModeOverride?: 'query' | 'search' | 'vsearch';
+        onDebug?: (debug: unknown) => void;
+        sources?: Array<'memory' | 'sessions'>;
+      },
+    ) {
+      if (opts?.sources && !opts.sources.includes('memory')) {
+        return [];
+      }
+
+      const recallTopK = typeof opts?.maxResults === 'number' ? opts.maxResults : config.recallTopK;
+      const recallClient = createClient(config, recallTopK);
+      const memories = await recallClient.recall(query);
+
+      return memories
+        .map((memory): MemorySearchResult => {
+          const score = normalizeMemoryScore(memory);
+          return {
+            path: buildMemoryPath(memory.id),
+            startLine: 1,
+            endLine: 1,
+            score,
+            vectorScore: typeof memory.similarity === 'number' ? memory.similarity : undefined,
+            snippet: truncate(memory.data, 400),
+            source: 'memory',
+            citation: memory.subject,
+          };
+        })
+        .filter((result) => opts?.minScore === undefined || result.score >= opts.minScore);
+    },
+
+    async readFile(params: {
+      relPath: string;
+      from?: number;
+      lines?: number;
+    }) {
+      const memoryId = parseMemoryPath(params.relPath);
+      if (!memoryId) {
+        throw new Error(`Unsupported Persistio memory path: ${params.relPath}`);
+      }
+
+      const memories = await client.listMemories();
+      const memory = memories.find((item) => item.id === memoryId);
+      if (!memory) {
+        throw new Error(`Persistio memory not found: ${memoryId}`);
+      }
+
+      const text = formatMemoryDocument(memory);
+      return {
+        path: params.relPath,
+        text,
+        truncated: false,
+        from: params.from ?? 1,
+        lines: params.lines,
+      };
+    },
+
+    status(): MemoryProviderStatus {
+      return {
+        backend: 'builtin',
+        provider: 'persistio',
+        sources: ['memory'],
+        vector: {
+          enabled: true,
+        },
+        custom: {
+          baseURL: config.baseURL,
+        },
+      };
+    },
+
+    async probeEmbeddingAvailability() {
+      return probePersistio(client);
+    },
+
+    async probeVectorAvailability() {
+      const probe = await probePersistio(client);
+      return probe.ok;
+    },
+  };
+}
+
+function createMemoryRuntime(config: PersistioConfig) {
+  return {
+    async getMemorySearchManager() {
+      return {
+        manager: createMemorySearchManager(config),
+      };
+    },
+
+    resolveMemoryBackendConfig() {
+      return { backend: 'builtin' as const };
+    },
+  };
+}
+
 export default definePluginEntry({
   id: 'openclaw-persistio',
   name: 'Persistio Memory',
@@ -167,7 +451,12 @@ export default definePluginEntry({
       return;
     }
 
-    const client = new PersistioClient(cfg);
+    const client = createClient(cfg);
+    const sentMessageKeysBySession = new Map<string, SessionMessageKeyStore>();
+    const pendingMessageKeysBySession = new Map<string, SessionMessageKeyStore>();
+    api.registerMemoryCapability({
+      runtime: createMemoryRuntime(cfg),
+    });
 
     // -------------------------------------------------------------------------
     // before_prompt_build — recall relevant memories and inject into context
@@ -191,31 +480,43 @@ export default definePluginEntry({
     // Event: { runId?, messages: unknown[], success: boolean, error?, durationMs? }
     // Observation only — no return value.
     // -------------------------------------------------------------------------
-    api.on('agent_end', async (event) => {
+    api.on('agent_end', async (event, context) => {
       try {
-        const sessionId = event.runId ?? 'unknown-session';
+        const sessionId = context?.sessionId ?? event.runId ?? 'unknown-session';
+        if (sessionId.startsWith('announce:')) return;
         const chunks: Array<{ role: string; content: string; timestamp: string }> = [];
+        const chunkKeys: string[] = [];
+        const now = Date.now();
+        const sentKeys = getSessionKeyStore(sentMessageKeysBySession, sessionId, now);
+        const pendingKeys = getSessionKeyStore(pendingMessageKeysBySession, sessionId, now);
 
-        for (const msg of event.messages) {
+        for (const [index, msg] of event.messages.entries()) {
           const m = msg as Record<string, unknown>;
-          const role = m['role'];
-          if (role !== 'user' && role !== 'assistant') continue;
-          const text = extractTextFromMessage(msg);
-          const ts = typeof m['timestamp'] === 'number'
-            ? new Date(m['timestamp']).toISOString()
-            : typeof m['timestamp'] === 'string'
-              ? m['timestamp']
-              : new Date().toISOString();
-          if (text && text.length > 0) {
-            chunks.push({ role: role as string, content: text, timestamp: ts });
-          }
+          const role = normalizeRole(m['role']);
+          if (!role || !shouldSendRole(role, cfg)) continue;
+          const text = extractTextFromMessage(msg, ['user', 'assistant', 'tool']);
+          if (!text || text.length === 0) continue;
+
+          const key = buildMessageFingerprint({ sessionId, msg: m, role, text, index });
+          if (sentKeys.has(key) || pendingKeys.has(key)) continue;
+
+          const ts = resolveMessageTimestamp(m) ?? new Date().toISOString();
+          chunkKeys.push(key);
+          chunks.push({ role, content: text, timestamp: ts });
         }
 
         if (chunks.length === 0) return;
-        // Fire and forget — agent_end is async but result is ignored
-        client.ingest(sessionId, chunks).catch((err: unknown) => {
-          api.logger?.warn?.(`openclaw-persistio: ingest error: ${String(err)}`);
-        });
+        rememberKeys(pendingKeys, chunkKeys);
+        client.ingest(sessionId, chunks)
+          .then(() => {
+            rememberKeys(sentKeys, chunkKeys, MAX_SENT_KEYS_PER_SESSION);
+          })
+          .catch((err: unknown) => {
+            api.logger?.warn?.(`openclaw-persistio: ingest error: ${String(err)}`);
+          })
+          .finally(() => {
+            forgetKeys(pendingKeys, chunkKeys);
+          });
       } catch (err) {
         api.logger?.warn?.(`openclaw-persistio: agent_end error: ${String(err)}`);
       }