@persistio/openclaw-plugin 0.1.6 → 0.1.7

package/README.md

@@ -12,7 +12,10 @@ 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
 ```
 
 Then register it in your OpenClaw config:
@@ -21,7 +24,8 @@ Then register it in your OpenClaw config:
 {
   "plugins": {
     "entries": {
-      "persistio": {
+      "openclaw-persistio": {
+        "enabled": true,
         "package": "@persistio/openclaw-plugin",
         "config": {
           "baseURL": "https://api.persistio.ai",
@@ -64,6 +68,8 @@ 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`.
+
 `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.

package/dist/client.d.ts

@@ -44,6 +44,9 @@ export interface RecallBundleResponse {
     bundle: RecallBundle;
     related_bundle?: RecallBundle;
 }
+export declare class PersistioTimeoutError extends Error {
+    constructor(operation: string, timeoutMs: number);
+}
 export declare class PersistioClient {
     private readonly baseURL;
     private readonly apiKey;
@@ -51,6 +54,7 @@ export declare class PersistioClient {
     private readonly recallMinSimilarity?;
     private readonly recallTimeout;
     private readonly ingestTimeout;
+    private readonly writeTimeout;
     constructor(config: PersistioConfig);
     private headers;
     recall(query: string): Promise<PersistioMemory[]>;

package/dist/client.js

@@ -1,3 +1,9 @@
+export class PersistioTimeoutError extends Error {
+    constructor(operation, timeoutMs) {
+        super(`Persistio ${operation} timed out after ${timeoutMs}ms`);
+        this.name = 'TimeoutError';
+    }
+}
 export class PersistioClient {
     baseURL;
     apiKey;
@@ -5,6 +11,7 @@ export class PersistioClient {
     recallMinSimilarity;
     recallTimeout;
     ingestTimeout;
+    writeTimeout;
     constructor(config) {
         this.baseURL = config.baseURL.replace(/\/$/, '');
         this.apiKey = config.apiKey;
@@ -12,6 +19,7 @@ export class PersistioClient {
         this.recallMinSimilarity = config.recallMinSimilarity;
         this.recallTimeout = config.recallTimeout;
         this.ingestTimeout = config.ingest.timeoutMs;
+        this.writeTimeout = config.ingest.timeoutMs;
     }
     headers() {
         return {
@@ -20,87 +28,136 @@ 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: 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,
+            });
+            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),
+        return withRequestDeadline('recallBundle', this.recallTimeout, async (signal) => {
+            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,
+            });
+            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 {

package/dist/index.js

@@ -10,6 +10,31 @@ const DEFAULT_SEND_ROLES = {
 const MESSAGE_KEY_TTL_MS = 24 * 60 * 60 * 1000;
 const MAX_TRACKED_SESSIONS = 250;
 const MAX_SENT_KEYS_PER_SESSION = 2000;
+const RECALL_CIRCUIT_BREAKER_FAILURE_THRESHOLD = 3;
+const RECALL_CIRCUIT_BREAKER_COOLDOWN_MS = 60_000;
+const RECALL_GUARD_MARGIN_MS = 250;
+class RecallCircuitBreaker {
+    consecutiveFailures = 0;
+    openedUntil = 0;
+    canAttempt(now = Date.now()) {
+        return now >= this.openedUntil;
+    }
+    remainingMs(now = Date.now()) {
+        return Math.max(0, this.openedUntil - now);
+    }
+    recordSuccess() {
+        this.consecutiveFailures = 0;
+        this.openedUntil = 0;
+    }
+    recordFailure(now = Date.now()) {
+        this.consecutiveFailures += 1;
+        if (this.consecutiveFailures >= RECALL_CIRCUIT_BREAKER_FAILURE_THRESHOLD) {
+            this.openedUntil = now + RECALL_CIRCUIT_BREAKER_COOLDOWN_MS;
+            return true;
+        }
+        return false;
+    }
+}
 function resolveSendConfig(raw) {
     const send = raw['send'];
     const roles = typeof send === 'object' && send !== null
@@ -31,15 +56,20 @@ function resolveRecallMinSimilarity(value) {
         ? value
         : undefined;
 }
+function resolvePositiveInteger(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 1
+        ? Math.floor(value)
+        : fallback;
+}
 function resolveConfig(raw) {
     const c = (raw ?? {});
     return {
         baseURL: typeof c['baseURL'] === 'string' ? c['baseURL'] : '',
         apiKey: typeof c['apiKey'] === 'string' ? c['apiKey'] : '',
-        tokenBudget: typeof c['tokenBudget'] === 'number' ? c['tokenBudget'] : 2000,
-        recallTopK: typeof c['recallTopK'] === 'number' ? c['recallTopK'] : 10,
+        tokenBudget: resolvePositiveInteger(c['tokenBudget'], 2000),
+        recallTopK: resolvePositiveInteger(c['recallTopK'], 10),
         recallMinSimilarity: resolveRecallMinSimilarity(c['recallMinSimilarity']),
-        recallTimeout: typeof c['recallTimeout'] === 'number' ? c['recallTimeout'] : 5000,
+        recallTimeout: resolvePositiveInteger(c['recallTimeout'], 5000),
         ingest: resolveIngestPolicy(c['ingest']),
         send: resolveSendConfig(c),
     };
@@ -110,20 +140,27 @@ function buildRecallQuery(event) {
     parts.push(`[task: ${taskType}]`);
     return truncate(parts.join('\n'), 600);
 }
+function toStringArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === 'string')
+        : [];
+}
 function buildMemoryBlock(bundle, budget, relatedBundle) {
+    if (!bundle || typeof bundle !== 'object')
+        return '';
     const sections = [
-        { title: 'Behavioural rules', items: bundle.user_rules },
-        { title: 'Preferences', items: bundle.user_preferences },
-        { title: 'Task patterns', items: bundle.task_patterns },
-        { title: 'Workflows', items: bundle.workflows },
-        { title: 'Project', items: bundle.project },
-        { title: 'Constraints', items: bundle.constraints },
-        { title: 'Decisions', items: bundle.decisions },
-        { title: 'System facts', items: bundle.system_facts },
-        { title: 'Domain knowledge', items: bundle.domain_knowledge },
+        { title: 'Behavioural rules', items: toStringArray(bundle.user_rules) },
+        { title: 'Preferences', items: toStringArray(bundle.user_preferences) },
+        { title: 'Task patterns', items: toStringArray(bundle.task_patterns) },
+        { title: 'Workflows', items: toStringArray(bundle.workflows) },
+        { title: 'Project', items: toStringArray(bundle.project) },
+        { title: 'Constraints', items: toStringArray(bundle.constraints) },
+        { title: 'Decisions', items: toStringArray(bundle.decisions) },
+        { title: 'System facts', items: toStringArray(bundle.system_facts) },
+        { title: 'Domain knowledge', items: toStringArray(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 });
+    if (relatedBundle && typeof relatedBundle === 'object') {
+        sections.push({ title: 'Related behavioural rules', items: toStringArray(relatedBundle.user_rules) }, { title: 'Related preferences', items: toStringArray(relatedBundle.user_preferences) }, { title: 'Related task patterns', items: toStringArray(relatedBundle.task_patterns) }, { title: 'Related workflows', items: toStringArray(relatedBundle.workflows) }, { title: 'Related project', items: toStringArray(relatedBundle.project) }, { title: 'Related constraints', items: toStringArray(relatedBundle.constraints) }, { title: 'Related decisions', items: toStringArray(relatedBundle.decisions) }, { title: 'Related system facts', items: toStringArray(relatedBundle.system_facts) }, { title: 'Related domain knowledge', items: toStringArray(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];
@@ -276,6 +313,45 @@ function isTimeoutLikeError(err) {
     const message = typeof record['message'] === 'string' ? record['message'].toLowerCase() : '';
     return message.includes('timeout') || message.includes('aborted');
 }
+async function runGuardedRecall(args) {
+    const now = Date.now();
+    if (!args.breaker.canAttempt(now)) {
+        args.logger?.warn?.(`openclaw-persistio: ${args.operation} skipped; recall circuit breaker open `
+            + `for ${args.breaker.remainingMs(now)}ms`);
+        return args.fallback;
+    }
+    try {
+        const result = await withPluginDeadline(args.operation, args.timeoutMs + RECALL_GUARD_MARGIN_MS, args.run);
+        args.breaker.recordSuccess();
+        return result;
+    }
+    catch (err) {
+        const opened = args.breaker.recordFailure();
+        args.logger?.warn?.(`openclaw-persistio: ${args.operation} failed open: ${String(err)}`
+            + (opened ? `; recall circuit breaker open for ${RECALL_CIRCUIT_BREAKER_COOLDOWN_MS}ms` : ''));
+        return args.fallback;
+    }
+}
+async function withPluginDeadline(operation, timeoutMs, run) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        return run();
+    }
+    let timeout;
+    const deadline = new Promise((_resolve, reject) => {
+        timeout = setTimeout(() => {
+            const err = new Error(`Persistio ${operation} exceeded plugin deadline after ${timeoutMs}ms`);
+            err.name = 'TimeoutError';
+            reject(err);
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([run(), deadline]);
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+}
 const PERSISTIO_MEMORY_PATH_PREFIX = 'persistio://memory/';
 function createClient(config, recallTopK = config.recallTopK) {
     return new PersistioClient({ ...config, recallTopK });
@@ -318,7 +394,7 @@ async function probePersistio(client) {
         return { ok: false, error: String(err) };
     }
 }
-function createMemorySearchManager(config) {
+function createMemorySearchManager(config, recallBreaker, logger) {
     const client = createClient(config);
     return {
         async search(query, opts) {
@@ -327,7 +403,14 @@ function createMemorySearchManager(config) {
             }
             const recallTopK = typeof opts?.maxResults === 'number' ? opts.maxResults : config.recallTopK;
             const recallClient = createClient(config, recallTopK);
-            const memories = await recallClient.recall(query);
+            const memories = await runGuardedRecall({
+                operation: 'memory search recall',
+                timeoutMs: config.recallTimeout,
+                fallback: [],
+                breaker: recallBreaker,
+                logger,
+                run: () => recallClient.recall(query),
+            });
             return memories
                 .map((memory) => {
                 const score = normalizeMemoryScore(memory);
@@ -384,11 +467,11 @@ function createMemorySearchManager(config) {
         },
     };
 }
-function createMemoryRuntime(config) {
+function createMemoryRuntime(config, recallBreaker, logger) {
     return {
         async getMemorySearchManager() {
             return {
-                manager: createMemorySearchManager(config),
+                manager: createMemorySearchManager(config, recallBreaker, logger),
             };
         },
         resolveMemoryBackendConfig() {
@@ -407,10 +490,11 @@ export default definePluginEntry({
             return;
         }
         const client = createClient(cfg);
+        const recallBreaker = new RecallCircuitBreaker();
         const sentMessageKeysBySession = new Map();
         const pendingMessageKeysBySession = new Map();
         api.registerMemoryCapability({
-            runtime: createMemoryRuntime(cfg),
+            runtime: createMemoryRuntime(cfg, recallBreaker, api.logger),
         });
         // -------------------------------------------------------------------------
         // before_prompt_build — recall relevant memories and inject into context
@@ -418,18 +502,22 @@ export default definePluginEntry({
         // Return: { appendSystemContext?: string }
         // -------------------------------------------------------------------------
         api.on('before_prompt_build', async (event) => {
-            try {
-                const query = buildRecallQuery(event);
-                const recall = await client.recallBundle(query);
-                const block = buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
-                if (!block)
-                    return;
-                return { appendSystemContext: block };
-            }
-            catch (err) {
-                api.logger?.warn?.(`openclaw-persistio: recall error: ${String(err)}`);
-            }
-        });
+            const query = buildRecallQuery(event);
+            const block = await runGuardedRecall({
+                operation: 'before_prompt_build recall',
+                timeoutMs: cfg.recallTimeout,
+                fallback: '',
+                breaker: recallBreaker,
+                logger: api.logger,
+                run: async () => {
+                    const recall = await client.recallBundle(query);
+                    return buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
+                },
+            });
+            if (!block)
+                return;
+            return { appendSystemContext: block };
+        }, { timeoutMs: cfg.recallTimeout + RECALL_GUARD_MARGIN_MS + 250 });
         // -------------------------------------------------------------------------
         // agent_end — ingest new turn messages (fire and forget)
         // Event: { runId?, messages: unknown[], success: boolean, error?, durationMs? }
@@ -537,10 +625,17 @@ export default definePluginEntry({
             }),
             async execute(_id, params) {
                 const p = params;
-                const overrideTopK = typeof p.top_k === 'number' ? p.top_k : cfg.recallTopK;
+                const overrideTopK = resolvePositiveInteger(p.top_k, cfg.recallTopK);
                 const overrideCfg = { ...cfg, recallTopK: overrideTopK };
-                const c = new PersistioClient(overrideCfg);
-                const memories = await c.recall(p.query);
+                const recallClient = createClient(overrideCfg);
+                const memories = await runGuardedRecall({
+                    operation: 'memory_search tool recall',
+                    timeoutMs: cfg.recallTimeout,
+                    fallback: [],
+                    breaker: recallBreaker,
+                    logger: api.logger,
+                    run: () => recallClient.recall(p.query),
+                });
                 const text = memories.length > 0
                     ? memories.map(m => `- ${m.data} [${m.subject}]`).join('\n')
                     : 'No memories found.';
@@ -557,7 +652,22 @@ export default definePluginEntry({
             }),
             async execute(_id, params) {
                 const p = params;
-                await client.addMemory(p.data, p.subject);
+                try {
+                    await client.addMemory(p.data, p.subject);
+                }
+                catch (err) {
+                    if (isTimeoutLikeError(err)) {
+                        api.logger?.warn?.(`openclaw-persistio: memory_add timeout after ${cfg.ingest.timeoutMs}ms; outcome is ambiguous`);
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: 'Memory store request timed out; it may still complete. Check memory_list before retrying.',
+                                }],
+                            details: { ambiguous: true },
+                        };
+                    }
+                    throw err;
+                }
                 return { content: [{ type: 'text', text: 'Memory stored.' }], details: null };
             },
         });

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.6",
+  "version": "0.1.7",
   "kind": "memory",
   "activation": {
     "onStartup": true
@@ -15,6 +15,14 @@
       "memory_list"
     ]
   },
+  "toolMetadata": {
+    "memory_delete": {
+      "optional": true
+    },
+    "memory_list": {
+      "optional": true
+    }
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,
@@ -26,10 +34,12 @@
         "type": "string"
       },
       "tokenBudget": {
-        "type": "number"
+        "type": "number",
+        "minimum": 1
       },
       "recallTopK": {
-        "type": "number"
+        "type": "number",
+        "minimum": 1
       },
       "recallMinSimilarity": {
         "type": "number",
@@ -37,20 +47,24 @@
         "maximum": 1
       },
       "recallTimeout": {
-        "type": "number"
+        "type": "number",
+        "minimum": 1
       },
       "ingest": {
         "type": "object",
         "additionalProperties": false,
         "properties": {
           "timeoutMs": {
-            "type": "number"
+            "type": "number",
+            "minimum": 1
           },
           "maxChunkChars": {
-            "type": "number"
+            "type": "number",
+            "minimum": 256
           },
           "maxChunksPerTurn": {
-            "type": "number"
+            "type": "number",
+            "minimum": 1
           },
           "skipSubagentSessions": {
             "type": "boolean"
@@ -60,7 +74,8 @@
             "additionalProperties": false,
             "properties": {
               "maxCharsPerMessage": {
-                "type": "number"
+                "type": "number",
+                "minimum": 1
               }
             }
           },
@@ -76,22 +91,28 @@
                 ]
               },
               "maxCharsPerMessage": {
-                "type": "number"
+                "type": "number",
+                "minimum": 1
               },
               "maxCharsAfterFiltering": {
-                "type": "number"
+                "type": "number",
+                "minimum": 1
               },
               "maxCharsPerTurn": {
-                "type": "number"
+                "type": "number",
+                "minimum": 1
               },
               "largeBlockThresholdChars": {
-                "type": "number"
+                "type": "number",
+                "minimum": 1
               },
               "largeBlockThresholdLines": {
-                "type": "number"
+                "type": "number",
+                "minimum": 1
               },
               "maxTableRows": {
-                "type": "number"
+                "type": "number",
+                "minimum": 1
               }
             }
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@persistio/openclaw-plugin",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "OpenClaw plugin for Persistio \u2014 persistent semantic memory for AI agents",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,7 +42,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node test/config-schema.test.mjs && node test/ingest-policy.test.mjs"
+    "test": "npm run build && node test/config-schema.test.mjs && node test/ingest-policy.test.mjs && node test/client-timeout.test.mjs"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.0"

package/src/client.ts

@@ -52,6 +52,13 @@ export interface RecallBundleResponse {
   related_bundle?: RecallBundle;
 }
 
+export class PersistioTimeoutError extends Error {
+  constructor(operation: string, timeoutMs: number) {
+    super(`Persistio ${operation} timed out after ${timeoutMs}ms`);
+    this.name = 'TimeoutError';
+  }
+}
+
 export class PersistioClient {
   private readonly baseURL: string;
   private readonly apiKey: string;
@@ -59,6 +66,7 @@ export class PersistioClient {
   private readonly recallMinSimilarity?: number;
   private readonly recallTimeout: number;
   private readonly ingestTimeout: number;
+  private readonly writeTimeout: number;
 
   constructor(config: PersistioConfig) {
     this.baseURL = config.baseURL.replace(/\/$/, '');
@@ -67,6 +75,7 @@ export class PersistioClient {
     this.recallMinSimilarity = config.recallMinSimilarity;
     this.recallTimeout = config.recallTimeout;
     this.ingestTimeout = config.ingest.timeoutMs;
+    this.writeTimeout = config.ingest.timeoutMs;
   }
 
   private headers(): Record<string, string> {
@@ -77,87 +86,141 @@ 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(body),
-      signal: AbortSignal.timeout(this.recallTimeout),
+    return withRequestDeadline('recall', this.recallTimeout, async (signal) => {
+      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(body),
+        signal,
+      });
+      if (!res.ok) throw new Error(`Persistio recall failed: ${res.status}`);
+      const data = await res.json() as { memories: PersistioMemory[] };
+      return data.memories ?? [];
     });
-    if (!res.ok) throw new Error(`Persistio recall failed: ${res.status}`);
-    const data = await res.json() as { memories: PersistioMemory[] };
-    return data.memories ?? [];
   }
 
   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(body),
-      signal: AbortSignal.timeout(this.recallTimeout),
+    return withRequestDeadline('recallBundle', this.recallTimeout, async (signal) => {
+      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(body),
+        signal,
+      });
+      if (!res.ok) throw new Error(`Persistio recallBundle failed: ${res.status}`);
+      const data = await res.json() as RecallBundleResponse;
+      return data;
     });
-    if (!res.ok) throw new Error(`Persistio recallBundle failed: ${res.status}`);
-    const data = await res.json() as RecallBundleResponse;
-    return data;
   }
 
   async ingest(sessionId: string, chunks: Array<{ role: string; content: string; timestamp: string }>): Promise<void> {
     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: string, subject: string): Promise<void> {
-    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: string): Promise<void> {
-    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: 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(),
+    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() as PersistioMemory;
     });
-    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(),
+    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() as { items: PersistioMemory[] };
+      return data.items ?? [];
     });
-    if (!res.ok) throw new Error(`Persistio listMemories failed: ${res.status}`);
-    const data = await res.json() as { items: PersistioMemory[] };
-    return data.items ?? [];
   }
 }
 
+async function withRequestDeadline<T>(
+  operation: string,
+  timeoutMs: number,
+  run: (signal: AbortSignal) => Promise<T>,
+): Promise<T> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return run(new AbortController().signal);
+  }
+
+  const controller = new AbortController();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+
+  const deadline = new Promise<never>((_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: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  return err.name === 'AbortError' || err.name === 'TimeoutError';
+}
+
 async function formatHttpError(operation: string, res: Response): Promise<string> {
   let detail = '';
   try {

package/src/index.ts

@@ -29,6 +29,41 @@ const DEFAULT_SEND_ROLES: PersistioConfig['send']['roles'] = {
 const MESSAGE_KEY_TTL_MS = 24 * 60 * 60 * 1000;
 const MAX_TRACKED_SESSIONS = 250;
 const MAX_SENT_KEYS_PER_SESSION = 2000;
+const RECALL_CIRCUIT_BREAKER_FAILURE_THRESHOLD = 3;
+const RECALL_CIRCUIT_BREAKER_COOLDOWN_MS = 60_000;
+const RECALL_GUARD_MARGIN_MS = 250;
+
+interface PluginLogger {
+  debug?: (message: string) => void;
+  warn?: (message: string) => void;
+}
+
+class RecallCircuitBreaker {
+  private consecutiveFailures = 0;
+  private openedUntil = 0;
+
+  canAttempt(now = Date.now()): boolean {
+    return now >= this.openedUntil;
+  }
+
+  remainingMs(now = Date.now()): number {
+    return Math.max(0, this.openedUntil - now);
+  }
+
+  recordSuccess(): void {
+    this.consecutiveFailures = 0;
+    this.openedUntil = 0;
+  }
+
+  recordFailure(now = Date.now()): boolean {
+    this.consecutiveFailures += 1;
+    if (this.consecutiveFailures >= RECALL_CIRCUIT_BREAKER_FAILURE_THRESHOLD) {
+      this.openedUntil = now + RECALL_CIRCUIT_BREAKER_COOLDOWN_MS;
+      return true;
+    }
+    return false;
+  }
+}
 
 function resolveSendConfig(raw: Record<string, unknown>): PersistioConfig['send'] {
   const send = raw['send'];
@@ -54,15 +89,21 @@ function resolveRecallMinSimilarity(value: unknown): number | undefined {
     : undefined;
 }
 
+function resolvePositiveInteger(value: unknown, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 1
+    ? Math.floor(value)
+    : fallback;
+}
+
 function resolveConfig(raw: unknown): PersistioConfig {
   const c = (raw ?? {}) as Record<string, unknown>;
   return {
     baseURL: typeof c['baseURL'] === 'string' ? c['baseURL'] : '',
     apiKey: typeof c['apiKey'] === 'string' ? c['apiKey'] : '',
-    tokenBudget: typeof c['tokenBudget'] === 'number' ? c['tokenBudget'] : 2000,
-    recallTopK: typeof c['recallTopK'] === 'number' ? c['recallTopK'] : 10,
+    tokenBudget: resolvePositiveInteger(c['tokenBudget'], 2000),
+    recallTopK: resolvePositiveInteger(c['recallTopK'], 10),
     recallMinSimilarity: resolveRecallMinSimilarity(c['recallMinSimilarity']),
-    recallTimeout: typeof c['recallTimeout'] === 'number' ? c['recallTimeout'] : 5000,
+    recallTimeout: resolvePositiveInteger(c['recallTimeout'], 5000),
     ingest: resolveIngestPolicy(c['ingest']),
     send: resolveSendConfig(c),
   };
@@ -139,29 +180,37 @@ function buildRecallQuery(event: { prompt?: string; messages?: unknown[] }): str
   return truncate(parts.join('\n'), 600);
 }
 
-function buildMemoryBlock(bundle: RecallBundle, budget: number, relatedBundle?: RecallBundle): string {
+function toStringArray(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((item): item is string => typeof item === 'string')
+    : [];
+}
+
+function buildMemoryBlock(bundle: RecallBundle | undefined, budget: number, relatedBundle?: RecallBundle): string {
+  if (!bundle || typeof bundle !== 'object') return '';
+
   const sections: Array<{ title: string; items: string[] }> = [
-    { title: 'Behavioural rules', items: bundle.user_rules },
-    { title: 'Preferences', items: bundle.user_preferences },
-    { title: 'Task patterns', items: bundle.task_patterns },
-    { title: 'Workflows', items: bundle.workflows },
-    { title: 'Project', items: bundle.project },
-    { title: 'Constraints', items: bundle.constraints },
-    { title: 'Decisions', items: bundle.decisions },
-    { title: 'System facts', items: bundle.system_facts },
-    { title: 'Domain knowledge', items: bundle.domain_knowledge },
+    { title: 'Behavioural rules', items: toStringArray(bundle.user_rules) },
+    { title: 'Preferences', items: toStringArray(bundle.user_preferences) },
+    { title: 'Task patterns', items: toStringArray(bundle.task_patterns) },
+    { title: 'Workflows', items: toStringArray(bundle.workflows) },
+    { title: 'Project', items: toStringArray(bundle.project) },
+    { title: 'Constraints', items: toStringArray(bundle.constraints) },
+    { title: 'Decisions', items: toStringArray(bundle.decisions) },
+    { title: 'System facts', items: toStringArray(bundle.system_facts) },
+    { title: 'Domain knowledge', items: toStringArray(bundle.domain_knowledge) },
   ];
-  if (relatedBundle) {
+  if (relatedBundle && typeof relatedBundle === 'object') {
     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 },
+      { title: 'Related behavioural rules', items: toStringArray(relatedBundle.user_rules) },
+      { title: 'Related preferences', items: toStringArray(relatedBundle.user_preferences) },
+      { title: 'Related task patterns', items: toStringArray(relatedBundle.task_patterns) },
+      { title: 'Related workflows', items: toStringArray(relatedBundle.workflows) },
+      { title: 'Related project', items: toStringArray(relatedBundle.project) },
+      { title: 'Related constraints', items: toStringArray(relatedBundle.constraints) },
+      { title: 'Related decisions', items: toStringArray(relatedBundle.decisions) },
+      { title: 'Related system facts', items: toStringArray(relatedBundle.system_facts) },
+      { title: 'Related domain knowledge', items: toStringArray(relatedBundle.domain_knowledge) },
     );
   }
 
@@ -329,6 +378,62 @@ function isTimeoutLikeError(err: unknown): boolean {
   return message.includes('timeout') || message.includes('aborted');
 }
 
+async function runGuardedRecall<T>(args: {
+  operation: string;
+  timeoutMs: number;
+  fallback: T;
+  breaker: RecallCircuitBreaker;
+  logger?: PluginLogger;
+  run: () => Promise<T>;
+}): Promise<T> {
+  const now = Date.now();
+  if (!args.breaker.canAttempt(now)) {
+    args.logger?.warn?.(
+      `openclaw-persistio: ${args.operation} skipped; recall circuit breaker open `
+      + `for ${args.breaker.remainingMs(now)}ms`,
+    );
+    return args.fallback;
+  }
+
+  try {
+    const result = await withPluginDeadline(args.operation, args.timeoutMs + RECALL_GUARD_MARGIN_MS, args.run);
+    args.breaker.recordSuccess();
+    return result;
+  } catch (err) {
+    const opened = args.breaker.recordFailure();
+    args.logger?.warn?.(
+      `openclaw-persistio: ${args.operation} failed open: ${String(err)}`
+      + (opened ? `; recall circuit breaker open for ${RECALL_CIRCUIT_BREAKER_COOLDOWN_MS}ms` : ''),
+    );
+    return args.fallback;
+  }
+}
+
+async function withPluginDeadline<T>(
+  operation: string,
+  timeoutMs: number,
+  run: () => Promise<T>,
+): Promise<T> {
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    return run();
+  }
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_resolve, reject) => {
+    timeout = setTimeout(() => {
+      const err = new Error(`Persistio ${operation} exceeded plugin deadline after ${timeoutMs}ms`);
+      err.name = 'TimeoutError';
+      reject(err);
+    }, timeoutMs);
+  });
+
+  try {
+    return await Promise.race([run(), deadline]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
 const PERSISTIO_MEMORY_PATH_PREFIX = 'persistio://memory/';
 
 function createClient(config: PersistioConfig, recallTopK = config.recallTopK): PersistioClient {
@@ -379,7 +484,11 @@ async function probePersistio(client: PersistioClient): Promise<MemoryEmbeddingP
   }
 }
 
-function createMemorySearchManager(config: PersistioConfig): MemorySearchManager {
+function createMemorySearchManager(
+  config: PersistioConfig,
+  recallBreaker: RecallCircuitBreaker,
+  logger?: PluginLogger,
+): MemorySearchManager {
   const client = createClient(config);
 
   return {
@@ -400,7 +509,14 @@ function createMemorySearchManager(config: PersistioConfig): MemorySearchManager
 
       const recallTopK = typeof opts?.maxResults === 'number' ? opts.maxResults : config.recallTopK;
       const recallClient = createClient(config, recallTopK);
-      const memories = await recallClient.recall(query);
+      const memories = await runGuardedRecall({
+        operation: 'memory search recall',
+        timeoutMs: config.recallTimeout,
+        fallback: [],
+        breaker: recallBreaker,
+        logger,
+        run: () => recallClient.recall(query),
+      });
 
       return memories
         .map((memory): MemorySearchResult => {
@@ -469,11 +585,11 @@ function createMemorySearchManager(config: PersistioConfig): MemorySearchManager
   };
 }
 
-function createMemoryRuntime(config: PersistioConfig) {
+function createMemoryRuntime(config: PersistioConfig, recallBreaker: RecallCircuitBreaker, logger?: PluginLogger) {
   return {
     async getMemorySearchManager() {
       return {
-        manager: createMemorySearchManager(config),
+        manager: createMemorySearchManager(config, recallBreaker, logger),
       };
     },
 
@@ -497,10 +613,11 @@ export default definePluginEntry({
     }
 
     const client = createClient(cfg);
+    const recallBreaker = new RecallCircuitBreaker();
     const sentMessageKeysBySession = new Map<string, SessionMessageKeyStore>();
     const pendingMessageKeysBySession = new Map<string, SessionMessageKeyStore>();
     api.registerMemoryCapability({
-      runtime: createMemoryRuntime(cfg),
+      runtime: createMemoryRuntime(cfg, recallBreaker, api.logger),
     });
 
     // -------------------------------------------------------------------------
@@ -509,16 +626,21 @@ export default definePluginEntry({
     // Return: { appendSystemContext?: string }
     // -------------------------------------------------------------------------
     api.on('before_prompt_build', async (event) => {
-      try {
-        const query = buildRecallQuery(event);
-        const recall = await client.recallBundle(query);
-        const block = buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
-        if (!block) return;
-        return { appendSystemContext: block };
-      } catch (err) {
-        api.logger?.warn?.(`openclaw-persistio: recall error: ${String(err)}`);
-      }
-    });
+      const query = buildRecallQuery(event);
+      const block = await runGuardedRecall({
+        operation: 'before_prompt_build recall',
+        timeoutMs: cfg.recallTimeout,
+        fallback: '',
+        breaker: recallBreaker,
+        logger: api.logger,
+        run: async () => {
+          const recall = await client.recallBundle(query);
+          return buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
+        },
+      });
+      if (!block) return;
+      return { appendSystemContext: block };
+    }, { timeoutMs: cfg.recallTimeout + RECALL_GUARD_MARGIN_MS + 250 });
 
     // -------------------------------------------------------------------------
     // agent_end — ingest new turn messages (fire and forget)
@@ -632,10 +754,17 @@ export default definePluginEntry({
       }),
       async execute(_id, params) {
         const p = params as { query: string; top_k?: number };
-        const overrideTopK = typeof p.top_k === 'number' ? p.top_k : cfg.recallTopK;
+        const overrideTopK = resolvePositiveInteger(p.top_k, cfg.recallTopK);
         const overrideCfg = { ...cfg, recallTopK: overrideTopK };
-        const c = new PersistioClient(overrideCfg);
-        const memories = await c.recall(p.query);
+        const recallClient = createClient(overrideCfg);
+        const memories = await runGuardedRecall({
+          operation: 'memory_search tool recall',
+          timeoutMs: cfg.recallTimeout,
+          fallback: [],
+          breaker: recallBreaker,
+          logger: api.logger,
+          run: () => recallClient.recall(p.query),
+        });
         const text = memories.length > 0
           ? memories.map(m => `- ${m.data} [${m.subject}]`).join('\n')
           : 'No memories found.';
@@ -653,7 +782,23 @@ export default definePluginEntry({
       }),
       async execute(_id, params) {
         const p = params as { data: string; subject: string };
-        await client.addMemory(p.data, p.subject);
+        try {
+          await client.addMemory(p.data, p.subject);
+        } catch (err) {
+          if (isTimeoutLikeError(err)) {
+            api.logger?.warn?.(
+              `openclaw-persistio: memory_add timeout after ${cfg.ingest.timeoutMs}ms; outcome is ambiguous`,
+            );
+            return {
+              content: [{
+                type: 'text' as const,
+                text: 'Memory store request timed out; it may still complete. Check memory_list before retrying.',
+              }],
+              details: { ambiguous: true },
+            };
+          }
+          throw err;
+        }
         return { content: [{ type: 'text' as const, text: 'Memory stored.' }], details: null };
       },
     });