@persistio/openclaw-plugin 0.1.7 → 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
 
@@ -18,6 +18,14 @@ 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:
 
 ```json
@@ -30,6 +38,9 @@ Then register it in your OpenClaw config:
         "config": {
           "baseURL": "https://api.persistio.ai",
           "apiKey": "your-vault-api-key",
+          "tokenBudget": 400,
+          "recallTopK": 4,
+          "recallTimeout": 1500,
           "recallMinSimilarity": 0.3,
           "send": {
             "roles": {
@@ -40,6 +51,9 @@ Then register it in your OpenClaw config:
           }
         }
       }
+    },
+    "slots": {
+      "memory": "openclaw-persistio"
     }
   }
 }
@@ -51,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 |
@@ -70,6 +86,8 @@ Then register it in your OpenClaw config:
 
 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.
@@ -78,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,6 +46,9 @@ export interface RecallBundleResponse {
     bundle: RecallBundle;
     related_bundle?: RecallBundle;
 }
+export interface RecallBundleOptions {
+    includeRelated?: boolean;
+}
 export declare class PersistioTimeoutError extends Error {
     constructor(operation: string, timeoutMs: number);
 }
@@ -53,12 +58,14 @@ export declare class PersistioClient {
     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

@@ -10,6 +10,8 @@ export class PersistioClient {
     recallTopK;
     recallMinSimilarity;
     recallTimeout;
+    recallIncludePending;
+    includeRelatedMemories;
     ingestTimeout;
     writeTimeout;
     constructor(config) {
@@ -18,6 +20,8 @@ export class PersistioClient {
         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;
     }
@@ -29,7 +33,11 @@ export class PersistioClient {
     }
     async recall(query) {
         return withRequestDeadline('recall', this.recallTimeout, async (signal) => {
-            const body = { query, top_k: this.recallTopK, include_pending: true };
+            const body = {
+                query,
+                top_k: this.recallTopK,
+                include_pending: this.recallIncludePending
+            };
             if (typeof this.recallMinSimilarity === 'number') {
                 body.min_similarity = this.recallMinSimilarity;
             }
@@ -45,9 +53,14 @@ export class PersistioClient {
             return data.memories ?? [];
         });
     }
-    async recallBundle(query, topK) {
+    async recallBundle(query, topK, options = {}) {
         return withRequestDeadline('recallBundle', this.recallTimeout, async (signal) => {
-            const body = { query, top_k: topK ?? this.recallTopK, include_pending: true };
+            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;
             }

package/dist/index.js

@@ -13,6 +13,12 @@ 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;
+const DEFAULT_TOKEN_BUDGET = 400;
+const DEFAULT_RECALL_TOP_K = 4;
+const DEFAULT_RECALL_TIMEOUT_MS = 1500;
+const MAX_MEMORY_SEARCH_RESULTS = 8;
+const MAX_PROMPT_MEMORY_ITEM_CHARS = 500;
+const MAX_MEMORY_SNIPPET_CHARS = 360;
 class RecallCircuitBreaker {
     consecutiveFailures = 0;
     openedUntil = 0;
@@ -61,15 +67,28 @@ function resolvePositiveInteger(value, fallback) {
         ? Math.floor(value)
         : fallback;
 }
+function resolveBoolean(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+function resolveOptionalPositiveInteger(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 1
+        ? Math.floor(value)
+        : undefined;
+}
+function clampPositiveInteger(value, min, max) {
+    return Math.min(max, Math.max(min, Math.floor(value)));
+}
 function resolveConfig(raw) {
     const c = (raw ?? {});
     return {
         baseURL: typeof c['baseURL'] === 'string' ? c['baseURL'] : '',
         apiKey: typeof c['apiKey'] === 'string' ? c['apiKey'] : '',
-        tokenBudget: resolvePositiveInteger(c['tokenBudget'], 2000),
-        recallTopK: resolvePositiveInteger(c['recallTopK'], 10),
+        tokenBudget: resolvePositiveInteger(c['tokenBudget'], DEFAULT_TOKEN_BUDGET),
+        recallTopK: resolvePositiveInteger(c['recallTopK'], DEFAULT_RECALL_TOP_K),
         recallMinSimilarity: resolveRecallMinSimilarity(c['recallMinSimilarity']),
-        recallTimeout: resolvePositiveInteger(c['recallTimeout'], 5000),
+        recallTimeout: resolvePositiveInteger(c['recallTimeout'], DEFAULT_RECALL_TIMEOUT_MS),
+        recallIncludePending: resolveBoolean(c['recallIncludePending'], false),
+        includeRelatedMemories: resolveBoolean(c['includeRelatedMemories'], false),
         ingest: resolveIngestPolicy(c['ingest']),
         send: resolveSendConfig(c),
     };
@@ -149,7 +168,7 @@ function buildMemoryBlock(bundle, budget, relatedBundle) {
     if (!bundle || typeof bundle !== 'object')
         return '';
     const sections = [
-        { title: 'Behavioural rules', items: toStringArray(bundle.user_rules) },
+        { title: 'Behavioural rules', items: [...toStringArray(bundle.global_user_rules), ...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) },
@@ -174,10 +193,10 @@ function buildMemoryBlock(bundle, budget, relatedBundle) {
         let tentativeUsed = used + estimateTokens(`\n\n${header}`);
         const includedItems = [];
         for (const item of candidates) {
-            const line = `- ${item}`;
+            const line = `- ${truncate(item.replace(/\s+/g, ' ').trim(), MAX_PROMPT_MEMORY_ITEM_CHARS)}`;
             const cost = estimateTokens(`\n${line}`);
             if (tentativeUsed + cost > budget) {
-                return lines.length > 1 ? lines.join('\n') : '';
+                break;
             }
             includedItems.push(line);
             tentativeUsed += cost;
@@ -353,6 +372,27 @@ async function withPluginDeadline(operation, timeoutMs, run) {
     }
 }
 const PERSISTIO_MEMORY_PATH_PREFIX = 'persistio://memory/';
+function jsonResult(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        details: payload,
+    };
+}
+function buildMemorySearchUnavailableResult(error) {
+    return {
+        results: [],
+        disabled: true,
+        unavailable: true,
+        error,
+        warning: 'Persistio memory retrieval is currently unavailable.',
+        action: 'Continue without memory for this turn.',
+        debug: { backend: 'builtin', provider: 'persistio' },
+    };
+}
+function resolveMemorySearchLimit(params) {
+    const requested = resolveOptionalPositiveInteger(params.maxResults) ?? params.fallback;
+    return clampPositiveInteger(requested, 1, MAX_MEMORY_SEARCH_RESULTS);
+}
 function createClient(config, recallTopK = config.recallTopK) {
     return new PersistioClient({ ...config, recallTopK });
 }
@@ -401,7 +441,7 @@ function createMemorySearchManager(config, recallBreaker, logger) {
             if (opts?.sources && !opts.sources.includes('memory')) {
                 return [];
             }
-            const recallTopK = typeof opts?.maxResults === 'number' ? opts.maxResults : config.recallTopK;
+            const recallTopK = resolveMemorySearchLimit({ maxResults: opts?.maxResults, fallback: config.recallTopK });
             const recallClient = createClient(config, recallTopK);
             const memories = await runGuardedRecall({
                 operation: 'memory search recall',
@@ -420,7 +460,7 @@ function createMemorySearchManager(config, recallBreaker, logger) {
                     endLine: 1,
                     score,
                     vectorScore: typeof memory.similarity === 'number' ? memory.similarity : undefined,
-                    snippet: truncate(memory.data, 400),
+                    snippet: truncate(memory.data.replace(/\s+/g, ' ').trim(), MAX_MEMORY_SNIPPET_CHARS),
                     source: 'memory',
                     citation: memory.subject,
                 };
@@ -437,12 +477,17 @@ function createMemorySearchManager(config, recallBreaker, logger) {
                 throw new Error(`Persistio memory not found: ${memoryId}`);
             }
             const text = formatMemoryDocument(memory);
+            const from = params.from ?? 1;
+            const lines = text.split('\n');
+            const startIndex = Math.max(0, from - 1);
+            const requestedLines = params.lines && params.lines > 0 ? params.lines : 40;
+            const sliced = lines.slice(startIndex, startIndex + requestedLines).join('\n');
             return {
                 path: params.relPath,
-                text,
-                truncated: false,
-                from: params.from ?? 1,
-                lines: params.lines,
+                text: truncate(sliced, 2000),
+                truncated: startIndex + requestedLines < lines.length || sliced.length > 2000,
+                from,
+                lines: requestedLines,
             };
         },
         status() {
@@ -479,6 +524,24 @@ function createMemoryRuntime(config, recallBreaker, logger) {
         },
     };
 }
+function buildPersistioMemoryPromptSection({ availableTools }) {
+    const hasMemorySearch = availableTools.has('memory_search');
+    const hasMemoryGet = availableTools.has('memory_get');
+    if (!hasMemorySearch && !hasMemoryGet)
+        return [];
+    if (hasMemorySearch && hasMemoryGet) {
+        return [
+            '## Memory Recall',
+            'Persistio is the active memory provider. For prior work, decisions, dates, people, preferences, or todos, use memory_search first and memory_get only for a bounded exact read of a returned persistio://memory/<id> path.',
+            '',
+        ];
+    }
+    return [
+        '## Memory Recall',
+        'Persistio is the active memory provider. Use the available memory tool for prior work, decisions, dates, people, preferences, or todos when memory context is needed.',
+        '',
+    ];
+}
 export default definePluginEntry({
     id: 'openclaw-persistio',
     name: 'Persistio Memory',
@@ -494,6 +557,7 @@ export default definePluginEntry({
         const sentMessageKeysBySession = new Map();
         const pendingMessageKeysBySession = new Map();
         api.registerMemoryCapability({
+            promptBuilder: buildPersistioMemoryPromptSection,
             runtime: createMemoryRuntime(cfg, recallBreaker, api.logger),
         });
         // -------------------------------------------------------------------------
@@ -510,8 +574,8 @@ export default definePluginEntry({
                 breaker: recallBreaker,
                 logger: api.logger,
                 run: async () => {
-                    const recall = await client.recallBundle(query);
-                    return buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
+                    const recall = await client.recallBundle(query, undefined, { includeRelated: cfg.includeRelatedMemories });
+                    return buildMemoryBlock(recall.bundle, cfg.tokenBudget, cfg.includeRelatedMemories ? recall.related_bundle : undefined);
                 },
             });
             if (!block)
@@ -615,37 +679,102 @@ export default definePluginEntry({
         // execute(_id: string, params: unknown): Promise<AgentToolResult>
         // AgentToolResult: { content: Array<{ type: "text", text: string }>, details: unknown }
         // -------------------------------------------------------------------------
+        const memoryManager = createMemorySearchManager(cfg, recallBreaker, api.logger);
         api.registerTool({
             name: 'memory_search',
-            label: 'Search Memory',
-            description: 'Search persistent memory for relevant facts from past conversations.',
+            label: 'Memory Search',
+            description: 'Search Persistio semantic memory. Returns bounded structured results with persistio://memory/<id> paths for memory_get.',
             parameters: Type.Object({
-                query: Type.String({ description: 'What to search for' }),
-                top_k: Type.Optional(Type.Number({ description: 'Max results to return' })),
-            }),
+                query: Type.String({ description: 'Search query' }),
+                maxResults: Type.Optional(Type.Number({ description: 'Maximum results to return' })),
+                minScore: Type.Optional(Type.Number({ description: 'Optional minimum score from 0 to 1' })),
+                corpus: Type.Optional(Type.Union([
+                    Type.Literal('memory'),
+                    Type.Literal('wiki'),
+                    Type.Literal('all'),
+                    Type.Literal('sessions'),
+                ], { description: 'Persistio supports memory corpus results' })),
+            }, { additionalProperties: false }),
             async execute(_id, params) {
                 const p = params;
-                const overrideTopK = resolvePositiveInteger(p.top_k, cfg.recallTopK);
-                const overrideCfg = { ...cfg, recallTopK: overrideTopK };
-                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 query = typeof p.query === 'string' ? p.query.trim() : '';
+                if (!query) {
+                    return jsonResult(buildMemorySearchUnavailableResult('memory_search requires a non-empty query'));
+                }
+                const maxResults = resolveMemorySearchLimit({
+                    maxResults: p.maxResults,
+                    fallback: cfg.recallTopK,
                 });
-                const text = memories.length > 0
-                    ? memories.map(m => `- ${m.data} [${m.subject}]`).join('\n')
-                    : 'No memories found.';
-                return { content: [{ type: 'text', text }], details: null };
+                const requestedCorpus = p.corpus ?? 'memory';
+                const sources = requestedCorpus === 'sessions' || requestedCorpus === 'wiki'
+                    ? []
+                    : ['memory'];
+                const startedAt = Date.now();
+                try {
+                    const results = sources.length === 0
+                        ? []
+                        : await memoryManager.search(query, {
+                            maxResults,
+                            minScore: p.minScore,
+                            sources,
+                        });
+                    return jsonResult({
+                        results: results.map((result) => ({ ...result, corpus: 'memory' })),
+                        provider: 'persistio',
+                        model: undefined,
+                        fallback: false,
+                        citations: 'off',
+                        mode: 'persistio',
+                        debug: {
+                            backend: 'builtin',
+                            effectiveMode: 'persistio',
+                            requestedCorpus,
+                            searchMs: Math.max(0, Date.now() - startedAt),
+                            hits: results.length,
+                        },
+                    });
+                }
+                catch (err) {
+                    return jsonResult(buildMemorySearchUnavailableResult(String(err)));
+                }
             },
         });
         api.registerTool({
-            name: 'memory_add',
-            label: 'Add Memory',
-            description: 'Manually store a fact in persistent memory.',
+            name: 'memory_get',
+            label: 'Memory Get',
+            description: 'Read a bounded exact Persistio memory document by persistio://memory/<id> path.',
+            parameters: Type.Object({
+                path: Type.String({ description: 'Memory path returned by memory_search' }),
+                from: Type.Optional(Type.Number({ description: 'Starting line, 1-based' })),
+                lines: Type.Optional(Type.Number({ description: 'Maximum number of lines to return' })),
+                corpus: Type.Optional(Type.Union([
+                    Type.Literal('memory'),
+                    Type.Literal('wiki'),
+                    Type.Literal('all'),
+                ])),
+            }, { additionalProperties: false }),
+            async execute(_id, params) {
+                const p = params;
+                const path = typeof p.path === 'string' ? p.path : '';
+                if (p.corpus === 'wiki') {
+                    return jsonResult({ path, text: '', disabled: true, error: 'Persistio does not provide a wiki corpus' });
+                }
+                try {
+                    return jsonResult(await memoryManager.readFile({
+                        relPath: path,
+                        from: resolveOptionalPositiveInteger(p.from),
+                        lines: resolveOptionalPositiveInteger(p.lines),
+                    }));
+                }
+                catch (err) {
+                    return jsonResult({ path, text: '', disabled: true, error: String(err) });
+                }
+            },
+        });
+        api.registerTool({
+            name: 'persistio_memory_add',
+            label: 'Add Persistio Memory',
+            description: 'Manually store a fact in Persistio memory.',
             parameters: Type.Object({
                 data: Type.String({ description: 'The fact to remember' }),
                 subject: Type.String({ description: 'The entity or topic this fact is about' }),
@@ -657,11 +786,11 @@ export default definePluginEntry({
                 }
                 catch (err) {
                     if (isTimeoutLikeError(err)) {
-                        api.logger?.warn?.(`openclaw-persistio: memory_add timeout after ${cfg.ingest.timeoutMs}ms; outcome is ambiguous`);
+                        api.logger?.warn?.(`openclaw-persistio: 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.',
+                                    text: 'Memory store request timed out; it may still complete. Check persistio_memory_list before retrying.',
                                 }],
                             details: { ambiguous: true },
                         };
@@ -670,11 +799,11 @@ export default definePluginEntry({
                 }
                 return { content: [{ type: 'text', text: 'Memory stored.' }], details: null };
             },
-        });
+        }, { optional: true });
         api.registerTool({
-            name: 'memory_delete',
-            label: 'Delete Memory',
-            description: 'Delete a specific memory by its ID.',
+            name: 'persistio_memory_delete',
+            label: 'Delete Persistio Memory',
+            description: 'Delete a specific Persistio memory by its ID.',
             parameters: Type.Object({
                 id: Type.String({ description: 'The memory ID to delete' }),
             }),
@@ -685,14 +814,14 @@ export default definePluginEntry({
             },
         }, { optional: true });
         api.registerTool({
-            name: 'memory_list',
-            label: 'List Memories',
-            description: 'List all stored memories.',
+            name: 'persistio_memory_list',
+            label: 'List Persistio Memories',
+            description: 'List stored Persistio memories.',
             parameters: Type.Object({}),
             async execute(_id, _params) {
                 const memories = await client.listMemories();
                 const text = memories.length > 0
-                    ? memories.map(m => `[${m.id}] ${m.data} (${m.subject})`).join('\n')
+                    ? memories.map(m => `[${m.id}] ${truncate(m.data.replace(/\s+/g, ' ').trim(), MAX_MEMORY_SNIPPET_CHARS)} (${m.subject})`).join('\n')
                     : 'No memories stored.';
                 return { content: [{ type: 'text', text }], 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.7",
+  "version": "0.1.8",
   "kind": "memory",
   "activation": {
     "onStartup": true
@@ -10,16 +10,20 @@
   "contracts": {
     "tools": [
       "memory_search",
-      "memory_add",
-      "memory_delete",
-      "memory_list"
+      "memory_get",
+      "persistio_memory_add",
+      "persistio_memory_delete",
+      "persistio_memory_list"
     ]
   },
   "toolMetadata": {
-    "memory_delete": {
+    "persistio_memory_add": {
       "optional": true
     },
-    "memory_list": {
+    "persistio_memory_delete": {
+      "optional": true
+    },
+    "persistio_memory_list": {
       "optional": true
     }
   },
@@ -50,6 +54,12 @@
         "type": "number",
         "minimum": 1
       },
+      "recallIncludePending": {
+        "type": "boolean"
+      },
+      "includeRelatedMemories": {
+        "type": "boolean"
+      },
       "ingest": {
         "type": "object",
         "additionalProperties": false,

package/package.json

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

package/src/client.ts

@@ -7,6 +7,8 @@ export interface PersistioConfig {
   recallTopK: number;
   recallMinSimilarity?: number;
   recallTimeout: number;
+  recallIncludePending: boolean;
+  includeRelatedMemories: boolean;
   ingest: PersistioIngestPolicy;
   send: PersistioSendConfig;
 }
@@ -52,6 +54,10 @@ export interface RecallBundleResponse {
   related_bundle?: RecallBundle;
 }
 
+export interface RecallBundleOptions {
+  includeRelated?: boolean;
+}
+
 export class PersistioTimeoutError extends Error {
   constructor(operation: string, timeoutMs: number) {
     super(`Persistio ${operation} timed out after ${timeoutMs}ms`);
@@ -65,6 +71,8 @@ export class PersistioClient {
   private readonly recallTopK: number;
   private readonly recallMinSimilarity?: number;
   private readonly recallTimeout: number;
+  private readonly recallIncludePending: boolean;
+  private readonly includeRelatedMemories: boolean;
   private readonly ingestTimeout: number;
   private readonly writeTimeout: number;
 
@@ -74,6 +82,8 @@ export class PersistioClient {
     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;
   }
@@ -87,7 +97,11 @@ export class PersistioClient {
 
   async recall(query: string): Promise<PersistioMemory[]> {
     return withRequestDeadline('recall', this.recallTimeout, async (signal) => {
-      const body: Record<string, unknown> = { query, top_k: this.recallTopK, include_pending: true };
+      const body: Record<string, unknown> = {
+        query,
+        top_k: this.recallTopK,
+        include_pending: this.recallIncludePending
+      };
       if (typeof this.recallMinSimilarity === 'number') {
         body.min_similarity = this.recallMinSimilarity;
       }
@@ -104,9 +118,14 @@ export class PersistioClient {
     });
   }
 
-  async recallBundle(query: string, topK?: number): Promise<RecallBundleResponse> {
+  async recallBundle(query: string, topK?: number, options: RecallBundleOptions = {}): Promise<RecallBundleResponse> {
     return withRequestDeadline('recallBundle', this.recallTimeout, async (signal) => {
-      const body: Record<string, unknown> = { query, top_k: topK ?? this.recallTopK, include_pending: true };
+      const body: Record<string, unknown> = {
+        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;
       }

package/src/index.ts

@@ -32,6 +32,12 @@ 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;
+const DEFAULT_TOKEN_BUDGET = 400;
+const DEFAULT_RECALL_TOP_K = 4;
+const DEFAULT_RECALL_TIMEOUT_MS = 1500;
+const MAX_MEMORY_SEARCH_RESULTS = 8;
+const MAX_PROMPT_MEMORY_ITEM_CHARS = 500;
+const MAX_MEMORY_SNIPPET_CHARS = 360;
 
 interface PluginLogger {
   debug?: (message: string) => void;
@@ -95,15 +101,31 @@ function resolvePositiveInteger(value: unknown, fallback: number): number {
     : fallback;
 }
 
+function resolveBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === 'boolean' ? value : fallback;
+}
+
+function resolveOptionalPositiveInteger(value: unknown): number | undefined {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 1
+    ? Math.floor(value)
+    : undefined;
+}
+
+function clampPositiveInteger(value: number, min: number, max: number): number {
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
 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: resolvePositiveInteger(c['tokenBudget'], 2000),
-    recallTopK: resolvePositiveInteger(c['recallTopK'], 10),
+    tokenBudget: resolvePositiveInteger(c['tokenBudget'], DEFAULT_TOKEN_BUDGET),
+    recallTopK: resolvePositiveInteger(c['recallTopK'], DEFAULT_RECALL_TOP_K),
     recallMinSimilarity: resolveRecallMinSimilarity(c['recallMinSimilarity']),
-    recallTimeout: resolvePositiveInteger(c['recallTimeout'], 5000),
+    recallTimeout: resolvePositiveInteger(c['recallTimeout'], DEFAULT_RECALL_TIMEOUT_MS),
+    recallIncludePending: resolveBoolean(c['recallIncludePending'], false),
+    includeRelatedMemories: resolveBoolean(c['includeRelatedMemories'], false),
     ingest: resolveIngestPolicy(c['ingest']),
     send: resolveSendConfig(c),
   };
@@ -190,7 +212,7 @@ function buildMemoryBlock(bundle: RecallBundle | undefined, budget: number, rela
   if (!bundle || typeof bundle !== 'object') return '';
 
   const sections: Array<{ title: string; items: string[] }> = [
-    { title: 'Behavioural rules', items: toStringArray(bundle.user_rules) },
+    { title: 'Behavioural rules', items: [...toStringArray(bundle.global_user_rules), ...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) },
@@ -228,10 +250,10 @@ function buildMemoryBlock(bundle: RecallBundle | undefined, budget: number, rela
     const includedItems: string[] = [];
 
     for (const item of candidates) {
-      const line = `- ${item}`;
+      const line = `- ${truncate(item.replace(/\s+/g, ' ').trim(), MAX_PROMPT_MEMORY_ITEM_CHARS)}`;
       const cost = estimateTokens(`\n${line}`);
       if (tentativeUsed + cost > budget) {
-        return lines.length > 1 ? lines.join('\n') : '';
+        break;
       }
       includedItems.push(line);
       tentativeUsed += cost;
@@ -436,6 +458,30 @@ async function withPluginDeadline<T>(
 
 const PERSISTIO_MEMORY_PATH_PREFIX = 'persistio://memory/';
 
+function jsonResult(payload: unknown) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }],
+    details: payload,
+  };
+}
+
+function buildMemorySearchUnavailableResult(error: string) {
+  return {
+    results: [],
+    disabled: true,
+    unavailable: true,
+    error,
+    warning: 'Persistio memory retrieval is currently unavailable.',
+    action: 'Continue without memory for this turn.',
+    debug: { backend: 'builtin', provider: 'persistio' },
+  };
+}
+
+function resolveMemorySearchLimit(params: { maxResults?: number; fallback: number }): number {
+  const requested = resolveOptionalPositiveInteger(params.maxResults) ?? params.fallback;
+  return clampPositiveInteger(requested, 1, MAX_MEMORY_SEARCH_RESULTS);
+}
+
 function createClient(config: PersistioConfig, recallTopK = config.recallTopK): PersistioClient {
   return new PersistioClient({ ...config, recallTopK });
 }
@@ -507,7 +553,7 @@ function createMemorySearchManager(
         return [];
       }
 
-      const recallTopK = typeof opts?.maxResults === 'number' ? opts.maxResults : config.recallTopK;
+      const recallTopK = resolveMemorySearchLimit({ maxResults: opts?.maxResults, fallback: config.recallTopK });
       const recallClient = createClient(config, recallTopK);
       const memories = await runGuardedRecall({
         operation: 'memory search recall',
@@ -527,7 +573,7 @@ function createMemorySearchManager(
             endLine: 1,
             score,
             vectorScore: typeof memory.similarity === 'number' ? memory.similarity : undefined,
-            snippet: truncate(memory.data, 400),
+            snippet: truncate(memory.data.replace(/\s+/g, ' ').trim(), MAX_MEMORY_SNIPPET_CHARS),
             source: 'memory',
             citation: memory.subject,
           };
@@ -551,12 +597,17 @@ function createMemorySearchManager(
       }
 
       const text = formatMemoryDocument(memory);
+      const from = params.from ?? 1;
+      const lines = text.split('\n');
+      const startIndex = Math.max(0, from - 1);
+      const requestedLines = params.lines && params.lines > 0 ? params.lines : 40;
+      const sliced = lines.slice(startIndex, startIndex + requestedLines).join('\n');
       return {
         path: params.relPath,
-        text,
-        truncated: false,
-        from: params.from ?? 1,
-        lines: params.lines,
+        text: truncate(sliced, 2000),
+        truncated: startIndex + requestedLines < lines.length || sliced.length > 2000,
+        from,
+        lines: requestedLines,
       };
     },
 
@@ -599,6 +650,26 @@ function createMemoryRuntime(config: PersistioConfig, recallBreaker: RecallCircu
   };
 }
 
+function buildPersistioMemoryPromptSection({ availableTools }: { availableTools: Set<string> }): string[] {
+  const hasMemorySearch = availableTools.has('memory_search');
+  const hasMemoryGet = availableTools.has('memory_get');
+  if (!hasMemorySearch && !hasMemoryGet) return [];
+
+  if (hasMemorySearch && hasMemoryGet) {
+    return [
+      '## Memory Recall',
+      'Persistio is the active memory provider. For prior work, decisions, dates, people, preferences, or todos, use memory_search first and memory_get only for a bounded exact read of a returned persistio://memory/<id> path.',
+      '',
+    ];
+  }
+
+  return [
+    '## Memory Recall',
+    'Persistio is the active memory provider. Use the available memory tool for prior work, decisions, dates, people, preferences, or todos when memory context is needed.',
+    '',
+  ];
+}
+
 export default definePluginEntry({
   id: 'openclaw-persistio',
   name: 'Persistio Memory',
@@ -617,6 +688,7 @@ export default definePluginEntry({
     const sentMessageKeysBySession = new Map<string, SessionMessageKeyStore>();
     const pendingMessageKeysBySession = new Map<string, SessionMessageKeyStore>();
     api.registerMemoryCapability({
+      promptBuilder: buildPersistioMemoryPromptSection,
       runtime: createMemoryRuntime(cfg, recallBreaker, api.logger),
     });
 
@@ -634,8 +706,12 @@ export default definePluginEntry({
         breaker: recallBreaker,
         logger: api.logger,
         run: async () => {
-          const recall = await client.recallBundle(query);
-          return buildMemoryBlock(recall.bundle, cfg.tokenBudget, recall.related_bundle);
+          const recall = await client.recallBundle(query, undefined, { includeRelated: cfg.includeRelatedMemories });
+          return buildMemoryBlock(
+            recall.bundle,
+            cfg.tokenBudget,
+            cfg.includeRelatedMemories ? recall.related_bundle : undefined,
+          );
         },
       });
       if (!block) return;
@@ -744,38 +820,111 @@ export default definePluginEntry({
     // AgentToolResult: { content: Array<{ type: "text", text: string }>, details: unknown }
     // -------------------------------------------------------------------------
 
+    const memoryManager = createMemorySearchManager(cfg, recallBreaker, api.logger);
+
     api.registerTool({
       name: 'memory_search',
-      label: 'Search Memory',
-      description: 'Search persistent memory for relevant facts from past conversations.',
+      label: 'Memory Search',
+      description: 'Search Persistio semantic memory. Returns bounded structured results with persistio://memory/<id> paths for memory_get.',
       parameters: Type.Object({
-        query: Type.String({ description: 'What to search for' }),
-        top_k: Type.Optional(Type.Number({ description: 'Max results to return' })),
-      }),
+        query: Type.String({ description: 'Search query' }),
+        maxResults: Type.Optional(Type.Number({ description: 'Maximum results to return' })),
+        minScore: Type.Optional(Type.Number({ description: 'Optional minimum score from 0 to 1' })),
+        corpus: Type.Optional(Type.Union([
+          Type.Literal('memory'),
+          Type.Literal('wiki'),
+          Type.Literal('all'),
+          Type.Literal('sessions'),
+        ], { description: 'Persistio supports memory corpus results' })),
+      }, { additionalProperties: false }),
       async execute(_id, params) {
-        const p = params as { query: string; top_k?: number };
-        const overrideTopK = resolvePositiveInteger(p.top_k, cfg.recallTopK);
-        const overrideCfg = { ...cfg, recallTopK: overrideTopK };
-        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 p = params as {
+          query?: string;
+          maxResults?: number;
+          minScore?: number;
+          corpus?: 'memory' | 'wiki' | 'all' | 'sessions';
+        };
+        const query = typeof p.query === 'string' ? p.query.trim() : '';
+        if (!query) {
+          return jsonResult(buildMemorySearchUnavailableResult('memory_search requires a non-empty query'));
+        }
+
+        const maxResults = resolveMemorySearchLimit({
+          maxResults: p.maxResults,
+          fallback: cfg.recallTopK,
         });
-        const text = memories.length > 0
-          ? memories.map(m => `- ${m.data} [${m.subject}]`).join('\n')
-          : 'No memories found.';
-        return { content: [{ type: 'text' as const, text }], details: null };
+        const requestedCorpus = p.corpus ?? 'memory';
+        const sources: Array<'memory' | 'sessions'> = requestedCorpus === 'sessions' || requestedCorpus === 'wiki'
+          ? []
+          : ['memory' as const];
+        const startedAt = Date.now();
+
+        try {
+          const results: MemorySearchResult[] = sources.length === 0
+            ? []
+            : await memoryManager.search(query, {
+              maxResults,
+              minScore: p.minScore,
+              sources,
+            });
+
+          return jsonResult({
+            results: results.map((result) => ({ ...result, corpus: 'memory' })),
+            provider: 'persistio',
+            model: undefined,
+            fallback: false,
+            citations: 'off',
+            mode: 'persistio',
+            debug: {
+              backend: 'builtin',
+              effectiveMode: 'persistio',
+              requestedCorpus,
+              searchMs: Math.max(0, Date.now() - startedAt),
+              hits: results.length,
+            },
+          });
+        } catch (err) {
+          return jsonResult(buildMemorySearchUnavailableResult(String(err)));
+        }
       },
     });
 
     api.registerTool({
-      name: 'memory_add',
-      label: 'Add Memory',
-      description: 'Manually store a fact in persistent memory.',
+      name: 'memory_get',
+      label: 'Memory Get',
+      description: 'Read a bounded exact Persistio memory document by persistio://memory/<id> path.',
+      parameters: Type.Object({
+        path: Type.String({ description: 'Memory path returned by memory_search' }),
+        from: Type.Optional(Type.Number({ description: 'Starting line, 1-based' })),
+        lines: Type.Optional(Type.Number({ description: 'Maximum number of lines to return' })),
+        corpus: Type.Optional(Type.Union([
+          Type.Literal('memory'),
+          Type.Literal('wiki'),
+          Type.Literal('all'),
+        ])),
+      }, { additionalProperties: false }),
+      async execute(_id, params) {
+        const p = params as { path?: string; from?: number; lines?: number; corpus?: 'memory' | 'wiki' | 'all' };
+        const path = typeof p.path === 'string' ? p.path : '';
+        if (p.corpus === 'wiki') {
+          return jsonResult({ path, text: '', disabled: true, error: 'Persistio does not provide a wiki corpus' });
+        }
+        try {
+          return jsonResult(await memoryManager.readFile({
+            relPath: path,
+            from: resolveOptionalPositiveInteger(p.from),
+            lines: resolveOptionalPositiveInteger(p.lines),
+          }));
+        } catch (err) {
+          return jsonResult({ path, text: '', disabled: true, error: String(err) });
+        }
+      },
+    });
+
+    api.registerTool({
+      name: 'persistio_memory_add',
+      label: 'Add Persistio Memory',
+      description: 'Manually store a fact in Persistio memory.',
       parameters: Type.Object({
         data: Type.String({ description: 'The fact to remember' }),
         subject: Type.String({ description: 'The entity or topic this fact is about' }),
@@ -787,12 +936,12 @@ export default definePluginEntry({
         } catch (err) {
           if (isTimeoutLikeError(err)) {
             api.logger?.warn?.(
-              `openclaw-persistio: memory_add timeout after ${cfg.ingest.timeoutMs}ms; outcome is ambiguous`,
+              `openclaw-persistio: 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.',
+                text: 'Memory store request timed out; it may still complete. Check persistio_memory_list before retrying.',
               }],
               details: { ambiguous: true },
             };
@@ -801,12 +950,12 @@ export default definePluginEntry({
         }
         return { content: [{ type: 'text' as const, text: 'Memory stored.' }], details: null };
       },
-    });
+    }, { optional: true });
 
     api.registerTool({
-      name: 'memory_delete',
-      label: 'Delete Memory',
-      description: 'Delete a specific memory by its ID.',
+      name: 'persistio_memory_delete',
+      label: 'Delete Persistio Memory',
+      description: 'Delete a specific Persistio memory by its ID.',
       parameters: Type.Object({
         id: Type.String({ description: 'The memory ID to delete' }),
       }),
@@ -818,14 +967,14 @@ export default definePluginEntry({
     }, { optional: true });
 
     api.registerTool({
-      name: 'memory_list',
-      label: 'List Memories',
-      description: 'List all stored memories.',
+      name: 'persistio_memory_list',
+      label: 'List Persistio Memories',
+      description: 'List stored Persistio memories.',
       parameters: Type.Object({}),
       async execute(_id, _params) {
         const memories = await client.listMemories();
         const text = memories.length > 0
-          ? memories.map(m => `[${m.id}] ${m.data} (${m.subject})`).join('\n')
+          ? memories.map(m => `[${m.id}] ${truncate(m.data.replace(/\s+/g, ' ').trim(), MAX_MEMORY_SNIPPET_CHARS)} (${m.subject})`).join('\n')
           : 'No memories stored.';
         return { content: [{ type: 'text' as const, text }], details: null };
       },