@persistio/openclaw-plugin 0.1.6 → 0.1.8

package/README.md

@@ -2,7 +2,7 @@
 
 OpenClaw plugin for [Persistio](https://persistio.ai) — persistent semantic memory for AI agents.
 
-Hooks into OpenClaw's `before_prompt_build` and `agent_end` events to automatically recall relevant memories into every prompt and ingest new conversation turns after each run. Exposes `memory_search`, `memory_add`, `memory_delete`, and `memory_list` as agent tools.
+Hooks into OpenClaw's `before_prompt_build` and `agent_end` events to recall a small memory context into prompts and ingest new conversation turns after each run. Registers as an OpenClaw memory provider with compatible `memory_search` and `memory_get` tools, plus optional Persistio management tools under the `persistio_*` namespace.
 
 ## Requirements
 
@@ -12,7 +12,18 @@ Hooks into OpenClaw's `before_prompt_build` and `agent_end` events to automatica
 ## Installation
 
 ```bash
-npm install -g @persistio/openclaw-plugin
+openclaw plugins install npm:@persistio/openclaw-plugin
+openclaw plugins enable openclaw-persistio
+openclaw gateway restart
+openclaw plugins inspect openclaw-persistio --runtime --json
+```
+
+To upgrade an existing install, use the same pinned npm source and restart the Gateway:
+
+```bash
+openclaw plugins install npm:@persistio/openclaw-plugin@0.1.8
+openclaw gateway restart
+openclaw plugins inspect openclaw-persistio --runtime --json
 ```
 
 Then register it in your OpenClaw config:
@@ -21,11 +32,15 @@ Then register it in your OpenClaw config:
 {
   "plugins": {
     "entries": {
-      "persistio": {
+      "openclaw-persistio": {
+        "enabled": true,
         "package": "@persistio/openclaw-plugin",
         "config": {
           "baseURL": "https://api.persistio.ai",
           "apiKey": "your-vault-api-key",
+          "tokenBudget": 400,
+          "recallTopK": 4,
+          "recallTimeout": 1500,
           "recallMinSimilarity": 0.3,
           "send": {
             "roles": {
@@ -36,6 +51,9 @@ Then register it in your OpenClaw config:
           }
         }
       }
+    },
+    "slots": {
+      "memory": "openclaw-persistio"
     }
   }
 }
@@ -47,10 +65,12 @@ Then register it in your OpenClaw config:
 |---|---|---|---|---|
 | `baseURL` | string | ✅ | — | Base URL of your Persistio instance |
 | `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 |
+| `tokenBudget` | number | | `400` | Max tokens to inject into the system prompt |
+| `recallTopK` | number | | `4` | 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) |
+| `recallTimeout` | number | | `1500` | HTTP timeout for recall requests (ms) |
+| `recallIncludePending` | boolean | | `false` | Include fresh candidate memories in recall results |
+| `includeRelatedMemories` | boolean | | `false` | Include graph-related memories in prompt recall bundles |
 | `ingest.timeoutMs` | number | | `30000` | HTTP timeout for ingest requests (ms). Timed-out requests are treated as ambiguous and not retried automatically |
 | `ingest.maxChunkChars` | number | | `6000` | Maximum characters per chunk sent to Persistio |
 | `ingest.maxChunksPerTurn` | number | | `12` | Maximum chunks sent from a single OpenClaw turn |
@@ -64,6 +84,10 @@ Then register it in your OpenClaw config:
 | `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 |
 
+Recall is fail-open by design. If Persistio does not answer within `recallTimeout`, the plugin returns no memory for that turn instead of blocking the OpenClaw lane. After three consecutive recall/search failures it opens a 60 second circuit breaker and skips recall immediately during the cooldown. The plugin also registers a bounded `before_prompt_build` hook timeout; operators can still override this in OpenClaw with `plugins.entries.<id>.hooks.timeouts.before_prompt_build`.
+
+Prompt recall intentionally defaults to a small direct semantic bundle. `includeRelatedMemories` and `recallIncludePending` are opt-in because graph expansion and fresh candidates increase context size and tail latency on interactive channels.
+
 `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.
 
 Assistant ingest is bounded before any network call. By default the plugin skips non-main `agent:*` sessions, collapses oversized code/log/diff/blob/table-shaped assistant content into omission markers, caps assistant ingest per message and per turn, then chunks all ingest content below `ingest.maxChunkChars`. Persistio still performs server-side extraction and curation; the plugin only enforces a deterministic transport-safe shape.
@@ -72,10 +96,11 @@ Assistant ingest is bounded before any network call. By default the plugin skips
 
 | Tool | Description |
 |---|---|
-| `memory_search` | Search memories by semantic query |
-| `memory_add` | Manually store a fact |
-| `memory_delete` | Delete a memory by ID |
-| `memory_list` | List all memories in the vault |
+| `memory_search` | Required OpenClaw-compatible semantic memory search. Returns bounded structured results with `persistio://memory/<id>` paths |
+| `memory_get` | Required OpenClaw-compatible exact memory read for paths returned by `memory_search` |
+| `persistio_memory_add` | Optional manual fact store |
+| `persistio_memory_delete` | Optional memory deletion by ID |
+| `persistio_memory_list` | Optional vault memory listing |
 
 ## License
 

package/dist/client.d.ts

@@ -6,6 +6,8 @@ export interface PersistioConfig {
     recallTopK: number;
     recallMinSimilarity?: number;
     recallTimeout: number;
+    recallIncludePending: boolean;
+    includeRelatedMemories: boolean;
     ingest: PersistioIngestPolicy;
     send: PersistioSendConfig;
 }
@@ -44,17 +46,26 @@ export interface RecallBundleResponse {
     bundle: RecallBundle;
     related_bundle?: RecallBundle;
 }
+export interface RecallBundleOptions {
+    includeRelated?: boolean;
+}
+export declare class PersistioTimeoutError extends Error {
+    constructor(operation: string, timeoutMs: number);
+}
 export declare class PersistioClient {
     private readonly baseURL;
     private readonly apiKey;
     private readonly recallTopK;
     private readonly recallMinSimilarity?;
     private readonly recallTimeout;
+    private readonly recallIncludePending;
+    private readonly includeRelatedMemories;
     private readonly ingestTimeout;
+    private readonly writeTimeout;
     constructor(config: PersistioConfig);
     private headers;
     recall(query: string): Promise<PersistioMemory[]>;
-    recallBundle(query: string, topK?: number): Promise<RecallBundleResponse>;
+    recallBundle(query: string, topK?: number, options?: RecallBundleOptions): Promise<RecallBundleResponse>;
     ingest(sessionId: string, chunks: Array<{
         role: string;
         content: string;

package/dist/client.js

@@ -1,17 +1,29 @@
+export class PersistioTimeoutError extends Error {
+    constructor(operation, timeoutMs) {
+        super(`Persistio ${operation} timed out after ${timeoutMs}ms`);
+        this.name = 'TimeoutError';
+    }
+}
 export class PersistioClient {
     baseURL;
     apiKey;
     recallTopK;
     recallMinSimilarity;
     recallTimeout;
+    recallIncludePending;
+    includeRelatedMemories;
     ingestTimeout;
+    writeTimeout;
     constructor(config) {
         this.baseURL = config.baseURL.replace(/\/$/, '');
         this.apiKey = config.apiKey;
         this.recallTopK = config.recallTopK;
         this.recallMinSimilarity = config.recallMinSimilarity;
         this.recallTimeout = config.recallTimeout;
+        this.recallIncludePending = config.recallIncludePending;
+        this.includeRelatedMemories = config.includeRelatedMemories;
         this.ingestTimeout = config.ingest.timeoutMs;
+        this.writeTimeout = config.ingest.timeoutMs;
     }
     headers() {
         return {
@@ -20,87 +32,145 @@ 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(body),
-            signal: AbortSignal.timeout(this.recallTimeout),
+        return withRequestDeadline('recall', this.recallTimeout, async (signal) => {
+            const body = {
+                query,
+                top_k: this.recallTopK,
+                include_pending: this.recallIncludePending
+            };
+            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(body),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio recall failed: ${res.status}`);
+            const data = await res.json();
+            return data.memories ?? [];
         });
-        if (!res.ok)
-            throw new Error(`Persistio recall failed: ${res.status}`);
-        const data = await res.json();
-        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(body),
-            signal: AbortSignal.timeout(this.recallTimeout),
+    }
+    async recallBundle(query, topK, options = {}) {
+        return withRequestDeadline('recallBundle', this.recallTimeout, async (signal) => {
+            const body = {
+                query,
+                top_k: topK ?? this.recallTopK,
+                include_pending: this.recallIncludePending,
+                include_related: options.includeRelated ?? this.includeRelatedMemories
+            };
+            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(body),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio recallBundle failed: ${res.status}`);
+            const data = await res.json();
+            return data;
         });
-        if (!res.ok)
-            throw new Error(`Persistio recallBundle failed: ${res.status}`);
-        const data = await res.json();
-        return data;
     }
     async ingest(sessionId, chunks) {
         if (chunks.length === 0)
             return;
-        const res = await fetch(`${this.baseURL}/v1/ingest`, {
-            method: 'POST',
-            headers: this.headers(),
-            body: JSON.stringify({ session_id: sessionId, chunks }),
-            signal: AbortSignal.timeout(this.ingestTimeout),
+        await withRequestDeadline('ingest', this.ingestTimeout, async (signal) => {
+            const res = await fetch(`${this.baseURL}/v1/ingest`, {
+                method: 'POST',
+                headers: this.headers(),
+                body: JSON.stringify({ session_id: sessionId, chunks }),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(await formatHttpError('ingest', res));
         });
-        if (!res.ok)
-            throw new Error(await formatHttpError('ingest', res));
     }
     async addMemory(data, subject) {
-        const res = await fetch(`${this.baseURL}/v1/memories`, {
-            method: 'POST',
-            headers: this.headers(),
-            body: JSON.stringify({ data, subject }),
+        await withRequestDeadline('addMemory', this.writeTimeout, async (signal) => {
+            const res = await fetch(`${this.baseURL}/v1/memories`, {
+                method: 'POST',
+                headers: this.headers(),
+                body: JSON.stringify({ data, subject }),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio addMemory failed: ${res.status}`);
         });
-        if (!res.ok)
-            throw new Error(`Persistio addMemory failed: ${res.status}`);
     }
     async deleteMemory(id) {
-        const res = await fetch(`${this.baseURL}/v1/memories/${id}`, {
-            method: 'DELETE',
-            headers: this.headers(),
+        await withRequestDeadline('deleteMemory', this.writeTimeout, async (signal) => {
+            const res = await fetch(`${this.baseURL}/v1/memories/${id}`, {
+                method: 'DELETE',
+                headers: this.headers(),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio deleteMemory failed: ${res.status}`);
         });
-        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(),
+        return withRequestDeadline('getMemory', this.recallTimeout, async (signal) => {
+            const query = options.includePending ? '?include_pending=true' : '';
+            const res = await fetch(`${this.baseURL}/v1/memories/${id}${query}`, {
+                headers: this.headers(),
+                signal,
+            });
+            if (res.status === 404)
+                return null;
+            if (!res.ok)
+                throw new Error(`Persistio getMemory failed: ${res.status}`);
+            return await res.json();
         });
-        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(),
+        return withRequestDeadline('listMemories', this.recallTimeout, async (signal) => {
+            const res = await fetch(`${this.baseURL}/v1/memories`, {
+                headers: this.headers(),
+                signal,
+            });
+            if (!res.ok)
+                throw new Error(`Persistio listMemories failed: ${res.status}`);
+            const data = await res.json();
+            return data.items ?? [];
         });
-        if (!res.ok)
-            throw new Error(`Persistio listMemories failed: ${res.status}`);
-        const data = await res.json();
-        return data.items ?? [];
     }
 }
+async function withRequestDeadline(operation, timeoutMs, run) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return run(new AbortController().signal);
+    }
+    const controller = new AbortController();
+    let timeout;
+    const deadline = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            controller.abort();
+            reject(new PersistioTimeoutError(operation, timeoutMs));
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([run(controller.signal), deadline]);
+    }
+    catch (err) {
+        if (controller.signal.aborted && isAbortLikeError(err)) {
+            throw new PersistioTimeoutError(operation, timeoutMs);
+        }
+        throw err;
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
+function isAbortLikeError(err) {
+    if (!(err instanceof Error))
+        return false;
+    return err.name === 'AbortError' || err.name === 'TimeoutError';
+}
 async function formatHttpError(operation, res) {
     let detail = '';
     try {