@persistio/openclaw-plugin 0.1.3 → 0.1.5

package/README.md

@@ -25,7 +25,15 @@ 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",
+          "recallMinSimilarity": 0.3,
+          "send": {
+            "roles": {
+              "user": "enabled",
+              "agent": "enabled",
+              "tool": "disabled"
+            }
+          }
         }
       }
     }
@@ -41,7 +49,13 @@ Then register it in your OpenClaw config:
 | `apiKey` | string | ✅ | — | Vault API key |
 | `tokenBudget` | number | | `2000` | Max tokens to inject into the system prompt |
 | `recallTopK` | number | | `10` | Number of memories to retrieve per recall |
+| `recallMinSimilarity` | number from `0` to `1` | | Persistio server default | Optional semantic recall quality floor |
 | `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

@@ -3,7 +3,17 @@ export interface PersistioConfig {
     apiKey: string;
     tokenBudget: number;
     recallTopK: number;
+    recallMinSimilarity?: 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;
@@ -13,7 +23,11 @@ export interface PersistioMemory {
     categories: string[];
     confidence: number;
 }
+export interface GetMemoryOptions {
+    includePending?: boolean;
+}
 export interface RecallBundle {
+    global_user_rules?: string[];
     user_rules: string[];
     user_preferences: string[];
     task_patterns: string[];
@@ -26,16 +40,18 @@ export interface RecallBundle {
 }
 export interface RecallBundleResponse {
     bundle: RecallBundle;
+    related_bundle?: RecallBundle;
 }
 export declare class PersistioClient {
     private readonly baseURL;
     private readonly apiKey;
     private readonly recallTopK;
+    private readonly recallMinSimilarity?;
     private readonly recallTimeout;
     constructor(config: PersistioConfig);
     private headers;
     recall(query: string): Promise<PersistioMemory[]>;
-    recallBundle(query: string, topK?: number): Promise<RecallBundle>;
+    recallBundle(query: string, topK?: number): Promise<RecallBundleResponse>;
     ingest(sessionId: string, chunks: Array<{
         role: string;
         content: string;
@@ -43,5 +59,6 @@ export declare class PersistioClient {
     }>): Promise<void>;
     addMemory(data: string, subject: string): Promise<void>;
     deleteMemory(id: string): Promise<void>;
+    getMemory(id: string, options?: GetMemoryOptions): Promise<PersistioMemory | null>;
     listMemories(): Promise<PersistioMemory[]>;
 }

package/dist/client.js

@@ -2,11 +2,13 @@ export class PersistioClient {
     baseURL;
     apiKey;
     recallTopK;
+    recallMinSimilarity;
     recallTimeout;
     constructor(config) {
         this.baseURL = config.baseURL.replace(/\/$/, '');
         this.apiKey = config.apiKey;
         this.recallTopK = config.recallTopK;
+        this.recallMinSimilarity = config.recallMinSimilarity;
         this.recallTimeout = config.recallTimeout;
     }
     headers() {
@@ -16,10 +18,14 @@ export class PersistioClient {
         };
     }
     async recall(query) {
+        const body = { query, top_k: this.recallTopK, include_pending: true };
+        if (typeof this.recallMinSimilarity === 'number') {
+            body.min_similarity = this.recallMinSimilarity;
+        }
         const res = await fetch(`${this.baseURL}/v1/recall`, {
             method: 'POST',
             headers: this.headers(),
-            body: JSON.stringify({ query, top_k: this.recallTopK }),
+            body: JSON.stringify(body),
             signal: AbortSignal.timeout(this.recallTimeout),
         });
         if (!res.ok)
@@ -28,16 +34,20 @@ export class PersistioClient {
         return data.memories ?? [];
     }
     async recallBundle(query, topK) {
+        const body = { query, top_k: topK ?? this.recallTopK, include_pending: true };
+        if (typeof this.recallMinSimilarity === 'number') {
+            body.min_similarity = this.recallMinSimilarity;
+        }
         const res = await fetch(`${this.baseURL}/v1/recall?format=bundle`, {
             method: 'POST',
             headers: this.headers(),
-            body: JSON.stringify({ query, top_k: topK ?? this.recallTopK }),
+            body: JSON.stringify(body),
             signal: AbortSignal.timeout(this.recallTimeout),
         });
         if (!res.ok)
             throw new Error(`Persistio recallBundle failed: ${res.status}`);
         const data = await res.json();
-        return data.bundle;
+        return data;
     }
     async ingest(sessionId, chunks) {
         if (chunks.length === 0)
@@ -67,6 +77,17 @@ export class PersistioClient {
         if (!res.ok)
             throw new Error(`Persistio deleteMemory failed: ${res.status}`);
     }
+    async getMemory(id, options = {}) {
+        const query = options.includePending ? '?include_pending=true' : '';
+        const res = await fetch(`${this.baseURL}/v1/memories/${id}${query}`, {
+            headers: this.headers(),
+        });
+        if (res.status === 404)
+            return null;
+        if (!res.ok)
+            throw new Error(`Persistio getMemory failed: ${res.status}`);
+        return await res.json();
+    }
     async listMemories() {
         const res = await fetch(`${this.baseURL}/v1/memories`, {
             headers: this.headers(),

package/dist/index.js

@@ -1,6 +1,35 @@
 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 resolveRecallMinSimilarity(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1
+        ? value
+        : undefined;
+}
 function resolveConfig(raw) {
     const c = (raw ?? {});
     return {
@@ -8,7 +37,9 @@ function resolveConfig(raw) {
         apiKey: typeof c['apiKey'] === 'string' ? c['apiKey'] : '',
         tokenBudget: typeof c['tokenBudget'] === 'number' ? c['tokenBudget'] : 2000,
         recallTopK: typeof c['recallTopK'] === 'number' ? c['recallTopK'] : 10,
+        recallMinSimilarity: resolveRecallMinSimilarity(c['recallMinSimilarity']),
         recallTimeout: typeof c['recallTimeout'] === 'number' ? c['recallTimeout'] : 5000,
+        send: resolveSendConfig(c),
     };
 }
 function estimateTokens(text) {
@@ -77,7 +108,7 @@ function buildRecallQuery(event) {
     parts.push(`[task: ${taskType}]`);
     return truncate(parts.join('\n'), 600);
 }
-function buildMemoryBlock(bundle, budget) {
+function buildMemoryBlock(bundle, budget, relatedBundle) {
     const sections = [
         { title: 'Behavioural rules', items: bundle.user_rules },
         { title: 'Preferences', items: bundle.user_preferences },
@@ -89,6 +120,9 @@ function buildMemoryBlock(bundle, budget) {
         { title: 'System facts', items: bundle.system_facts },
         { title: 'Domain knowledge', items: bundle.domain_knowledge },
     ];
+    if (relatedBundle) {
+        sections.push({ title: 'Related behavioural rules', items: relatedBundle.user_rules }, { title: 'Related preferences', items: relatedBundle.user_preferences }, { title: 'Related task patterns', items: relatedBundle.task_patterns }, { title: 'Related workflows', items: relatedBundle.workflows }, { title: 'Related project', items: relatedBundle.project }, { title: 'Related constraints', items: relatedBundle.constraints }, { title: 'Related decisions', items: relatedBundle.decisions }, { title: 'Related system facts', items: relatedBundle.system_facts }, { title: 'Related domain knowledge', items: relatedBundle.domain_knowledge });
+    }
     const intro = 'Use the following as prior context and preferences. If they conflict with current instructions, follow the current instructions.';
     const lines = [intro];
     let used = estimateTokens(intro);
@@ -117,13 +151,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 +187,72 @@ 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 });
@@ -216,8 +326,7 @@ function createMemorySearchManager(config) {
             if (!memoryId) {
                 throw new Error(`Unsupported Persistio memory path: ${params.relPath}`);
             }
-            const memories = await client.listMemories();
-            const memory = memories.find((item) => item.id === memoryId);
+            const memory = await client.getMemory(memoryId, { includePending: true });
             if (!memory) {
                 throw new Error(`Persistio memory not found: ${memoryId}`);
             }
@@ -275,6 +384,8 @@ export default definePluginEntry({
             return;
         }
         const client = createClient(cfg);
+        const sentMessageKeysBySession = new Map();
+        const pendingMessageKeysBySession = new Map();
         api.registerMemoryCapability({
             runtime: createMemoryRuntime(cfg),
         });
@@ -286,8 +397,8 @@ export default definePluginEntry({
         api.on('before_prompt_build', async (event) => {
             try {
                 const query = buildRecallQuery(event);
-                const bundle = await client.recallBundle(query);
-                const block = buildMemoryBlock(bundle, cfg.tokenBudget);
+                const recall = await client.recallBundle(query);
+                const block = buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
                 if (!block)
                     return;
                 return { appendSystemContext: block };
@@ -307,26 +418,37 @@ export default definePluginEntry({
                 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.3",
+  "version": "0.1.5",
   "kind": "memory",
   "activation": {
     "onStartup": true
@@ -31,8 +31,46 @@
       "recallTopK": {
         "type": "number"
       },
+      "recallMinSimilarity": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      },
       "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.3",
+  "version": "0.1.5",
   "description": "OpenClaw plugin for Persistio \u2014 persistent semantic memory for AI agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,7 +41,8 @@
     }
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "node test/config-schema.test.mjs"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.0"

package/src/client.ts

@@ -3,7 +3,19 @@ export interface PersistioConfig {
   apiKey: string;
   tokenBudget: number;
   recallTopK: number;
+  recallMinSimilarity?: number;
   recallTimeout: number;
+  send: PersistioSendConfig;
+}
+
+export type PersistioSendRoleStatus = 'enabled' | 'disabled';
+
+export interface PersistioSendConfig {
+  roles: {
+    user: PersistioSendRoleStatus;
+    agent: PersistioSendRoleStatus;
+    tool: PersistioSendRoleStatus;
+  };
 }
 
 export interface PersistioMemory {
@@ -15,7 +27,12 @@ export interface PersistioMemory {
   confidence: number;
 }
 
+export interface GetMemoryOptions {
+  includePending?: boolean;
+}
+
 export interface RecallBundle {
+  global_user_rules?: string[];
   user_rules: string[];
   user_preferences: string[];
   task_patterns: string[];
@@ -29,18 +46,21 @@ export interface RecallBundle {
 
 export interface RecallBundleResponse {
   bundle: RecallBundle;
+  related_bundle?: RecallBundle;
 }
 
 export class PersistioClient {
   private readonly baseURL: string;
   private readonly apiKey: string;
   private readonly recallTopK: number;
+  private readonly recallMinSimilarity?: number;
   private readonly recallTimeout: number;
 
   constructor(config: PersistioConfig) {
     this.baseURL = config.baseURL.replace(/\/$/, '');
     this.apiKey = config.apiKey;
     this.recallTopK = config.recallTopK;
+    this.recallMinSimilarity = config.recallMinSimilarity;
     this.recallTimeout = config.recallTimeout;
   }
 
@@ -52,10 +72,15 @@ export class PersistioClient {
   }
 
   async recall(query: string): Promise<PersistioMemory[]> {
+    const body: Record<string, unknown> = { query, top_k: this.recallTopK, include_pending: true };
+    if (typeof this.recallMinSimilarity === 'number') {
+      body.min_similarity = this.recallMinSimilarity;
+    }
+
     const res = await fetch(`${this.baseURL}/v1/recall`, {
       method: 'POST',
       headers: this.headers(),
-      body: JSON.stringify({ query, top_k: this.recallTopK }),
+      body: JSON.stringify(body),
       signal: AbortSignal.timeout(this.recallTimeout),
     });
     if (!res.ok) throw new Error(`Persistio recall failed: ${res.status}`);
@@ -63,16 +88,21 @@ export class PersistioClient {
     return data.memories ?? [];
   }
 
-  async recallBundle(query: string, topK?: number): Promise<RecallBundle> {
+  async recallBundle(query: string, topK?: number): Promise<RecallBundleResponse> {
+    const body: Record<string, unknown> = { query, top_k: topK ?? this.recallTopK, include_pending: true };
+    if (typeof this.recallMinSimilarity === 'number') {
+      body.min_similarity = this.recallMinSimilarity;
+    }
+
     const res = await fetch(`${this.baseURL}/v1/recall?format=bundle`, {
       method: 'POST',
       headers: this.headers(),
-      body: JSON.stringify({ query, top_k: topK ?? this.recallTopK }),
+      body: JSON.stringify(body),
       signal: AbortSignal.timeout(this.recallTimeout),
     });
     if (!res.ok) throw new Error(`Persistio recallBundle failed: ${res.status}`);
     const data = await res.json() as RecallBundleResponse;
-    return data.bundle;
+    return data;
   }
 
   async ingest(sessionId: string, chunks: Array<{ role: string; content: string; timestamp: string }>): Promise<void> {
@@ -102,6 +132,16 @@ export class PersistioClient {
     if (!res.ok) throw new Error(`Persistio deleteMemory failed: ${res.status}`);
   }
 
+  async getMemory(id: string, options: GetMemoryOptions = {}): Promise<PersistioMemory | null> {
+    const query = options.includePending ? '?include_pending=true' : '';
+    const res = await fetch(`${this.baseURL}/v1/memories/${id}${query}`, {
+      headers: this.headers(),
+    });
+    if (res.status === 404) return null;
+    if (!res.ok) throw new Error(`Persistio getMemory failed: ${res.status}`);
+    return await res.json() as PersistioMemory;
+  }
+
   async listMemories(): Promise<PersistioMemory[]> {
     const res = await fetch(`${this.baseURL}/v1/memories`, {
       headers: this.headers(),

package/src/index.ts

@@ -8,6 +8,47 @@ import type {
 import { Type } from '@sinclair/typebox';
 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 resolveRecallMinSimilarity(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1
+    ? value
+    : undefined;
+}
+
 function resolveConfig(raw: unknown): PersistioConfig {
   const c = (raw ?? {}) as Record<string, unknown>;
   return {
@@ -15,7 +56,9 @@ function resolveConfig(raw: unknown): PersistioConfig {
     apiKey: typeof c['apiKey'] === 'string' ? c['apiKey'] : '',
     tokenBudget: typeof c['tokenBudget'] === 'number' ? c['tokenBudget'] : 2000,
     recallTopK: typeof c['recallTopK'] === 'number' ? c['recallTopK'] : 10,
+    recallMinSimilarity: resolveRecallMinSimilarity(c['recallMinSimilarity']),
     recallTimeout: typeof c['recallTimeout'] === 'number' ? c['recallTimeout'] : 5000,
+    send: resolveSendConfig(c),
   };
 }
 
@@ -90,7 +133,7 @@ function buildRecallQuery(event: { prompt?: string; messages?: unknown[] }): str
   return truncate(parts.join('\n'), 600);
 }
 
-function buildMemoryBlock(bundle: RecallBundle, budget: number): string {
+function buildMemoryBlock(bundle: RecallBundle, budget: number, relatedBundle?: RecallBundle): string {
   const sections: Array<{ title: string; items: string[] }> = [
     { title: 'Behavioural rules', items: bundle.user_rules },
     { title: 'Preferences', items: bundle.user_preferences },
@@ -102,6 +145,19 @@ function buildMemoryBlock(bundle: RecallBundle, budget: number): string {
     { title: 'System facts', items: bundle.system_facts },
     { title: 'Domain knowledge', items: bundle.domain_knowledge },
   ];
+  if (relatedBundle) {
+    sections.push(
+      { title: 'Related behavioural rules', items: relatedBundle.user_rules },
+      { title: 'Related preferences', items: relatedBundle.user_preferences },
+      { title: 'Related task patterns', items: relatedBundle.task_patterns },
+      { title: 'Related workflows', items: relatedBundle.workflows },
+      { title: 'Related project', items: relatedBundle.project },
+      { title: 'Related constraints', items: relatedBundle.constraints },
+      { title: 'Related decisions', items: relatedBundle.decisions },
+      { title: 'Related system facts', items: relatedBundle.system_facts },
+      { title: 'Related domain knowledge', items: relatedBundle.domain_knowledge },
+    );
+  }
 
   const intro = 'Use the following as prior context and preferences. If they conflict with current instructions, follow the current instructions.';
   const lines: string[] = [intro];
@@ -136,12 +192,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
@@ -160,6 +226,83 @@ 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 {
@@ -260,8 +403,7 @@ function createMemorySearchManager(config: PersistioConfig): MemorySearchManager
         throw new Error(`Unsupported Persistio memory path: ${params.relPath}`);
       }
 
-      const memories = await client.listMemories();
-      const memory = memories.find((item) => item.id === memoryId);
+      const memory = await client.getMemory(memoryId, { includePending: true });
       if (!memory) {
         throw new Error(`Persistio memory not found: ${memoryId}`);
       }
@@ -329,6 +471,8 @@ export default definePluginEntry({
     }
 
     const client = createClient(cfg);
+    const sentMessageKeysBySession = new Map<string, SessionMessageKeyStore>();
+    const pendingMessageKeysBySession = new Map<string, SessionMessageKeyStore>();
     api.registerMemoryCapability({
       runtime: createMemoryRuntime(cfg),
     });
@@ -341,8 +485,8 @@ export default definePluginEntry({
     api.on('before_prompt_build', async (event) => {
       try {
         const query = buildRecallQuery(event);
-        const bundle = await client.recallBundle(query);
-        const block = buildMemoryBlock(bundle, cfg.tokenBudget);
+        const recall = await client.recallBundle(query);
+        const block = buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
         if (!block) return;
         return { appendSystemContext: block };
       } catch (err) {
@@ -360,27 +504,38 @@ export default definePluginEntry({
         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)}`);
       }