@persistio/openclaw-plugin 0.1.4 → 0.1.5

package/README.md

@@ -26,6 +26,7 @@ Then register it in your OpenClaw config:
         "config": {
           "baseURL": "https://api.persistio.ai",
           "apiKey": "your-vault-api-key",
+          "recallMinSimilarity": 0.3,
           "send": {
             "roles": {
               "user": "enabled",
@@ -48,6 +49,7 @@ 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 |

package/dist/client.d.ts

@@ -3,6 +3,7 @@ export interface PersistioConfig {
     apiKey: string;
     tokenBudget: number;
     recallTopK: number;
+    recallMinSimilarity?: number;
     recallTimeout: number;
     send: PersistioSendConfig;
 }
@@ -22,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[];
@@ -35,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;
@@ -52,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

@@ -25,6 +25,11 @@ function resolveSendConfig(raw) {
         },
     };
 }
+function resolveRecallMinSimilarity(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1
+        ? value
+        : undefined;
+}
 function resolveConfig(raw) {
     const c = (raw ?? {});
     return {
@@ -32,6 +37,7 @@ 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),
     };
@@ -102,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 },
@@ -114,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);
@@ -317,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}`);
             }
@@ -389,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 };

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.4",
+  "version": "0.1.5",
   "kind": "memory",
   "activation": {
     "onStartup": true
@@ -31,6 +31,11 @@
       "recallTopK": {
         "type": "number"
       },
+      "recallMinSimilarity": {
+        "type": "number",
+        "minimum": 0,
+        "maximum": 1
+      },
       "recallTimeout": {
         "type": "number"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persistio/openclaw-plugin",
-  "version": "0.1.4",
+  "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,6 +3,7 @@ export interface PersistioConfig {
   apiKey: string;
   tokenBudget: number;
   recallTopK: number;
+  recallMinSimilarity?: number;
   recallTimeout: number;
   send: PersistioSendConfig;
 }
@@ -26,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[];
@@ -40,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;
   }
 
@@ -63,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}`);
@@ -74,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> {
@@ -113,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

@@ -43,6 +43,12 @@ function resolveSendConfig(raw: Record<string, unknown>): PersistioConfig['send'
   };
 }
 
+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 {
@@ -50,6 +56,7 @@ 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),
   };
@@ -126,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 },
@@ -138,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];
@@ -383,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}`);
       }
@@ -466,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) {