@persistio/openclaw-plugin 0.1.8 → 0.2.0

package/README.md

@@ -1,107 +1,121 @@
 # @persistio/openclaw-plugin
 
-OpenClaw plugin for [Persistio](https://persistio.ai) — persistent semantic memory for AI agents.
+OpenClaw-native long-term memory powered by Persistio.
 
-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.
+This is the production Persistio plugin for OpenClaw. Version `0.2.x` promotes the OpenClaw-native memory-slot architecture that was tested separately as `openclaw-persistio-v2`.
 
-## Requirements
+## Design
 
-- A running [Persistio](https://github.com/chriscoveyduck/persistio) instance (`api.persistio.ai` or self-hosted)
-- OpenClaw `>=2026.3.24-beta.2`
+Persistio v2 separates the memory surfaces:
 
-## Installation
+- `memory_recall` lets the model explicitly retrieve durable Persistio memory.
+- `memory_store` stores a deliberate durable fact, preference, decision, or project note.
+- `memory_forget` deletes a known memory id or returns candidate memories for a query.
+- `autoRecall` optionally injects a small bounded memory block before a turn.
+- `autoCapture` optionally captures bounded post-turn messages without awaiting Persistio from the OpenClaw hook.
 
-```bash
-openclaw plugins install npm:@persistio/openclaw-plugin
-openclaw plugins enable openclaw-persistio
-openclaw gateway restart
-openclaw plugins inspect openclaw-persistio --runtime --json
-```
+The plugin registers as an OpenClaw memory plugin and provides prompt guidance. It does not replace OpenClaw's generic `memory_search` / `memory_get` tools in this first v2 package.
 
-To upgrade an existing install, use the same pinned npm source and restart the Gateway:
+## Install
 
 ```bash
-openclaw plugins install npm:@persistio/openclaw-plugin@0.1.8
+openclaw plugins install npm:@persistio/openclaw-plugin@0.2.0
+openclaw plugins enable openclaw-persistio-v2
 openclaw gateway restart
-openclaw plugins inspect openclaw-persistio --runtime --json
 ```
 
-Then register it in your OpenClaw config:
+To test it as the active memory slot:
 
 ```json
 {
   "plugins": {
+    "slots": {
+      "memory": "openclaw-persistio-v2"
+    },
     "entries": {
-      "openclaw-persistio": {
+      "openclaw-persistio-v2": {
         "enabled": true,
         "package": "@persistio/openclaw-plugin",
+        "hooks": {
+          "allowConversationAccess": true
+        },
         "config": {
           "baseURL": "https://api.persistio.ai",
           "apiKey": "your-vault-api-key",
-          "tokenBudget": 400,
-          "recallTopK": 4,
-          "recallTimeout": 1500,
-          "recallMinSimilarity": 0.3,
-          "send": {
+          "autoRecall": true,
+          "autoCapture": true,
+          "recall": {
+            "timeoutMs": 1200,
+            "maxResults": 4,
+            "tokenBudget": 400,
+            "minSimilarity": 0.45,
+            "includePending": false,
+            "includeRelated": false
+          },
+          "capture": {
+            "timeoutMs": 10000,
             "roles": {
               "user": "enabled",
-              "agent": "enabled",
+              "assistant": "bounded",
               "tool": "disabled"
             }
           }
         }
       }
-    },
-    "slots": {
-      "memory": "openclaw-persistio"
     }
   }
 }
 ```
 
+`hooks.allowConversationAccess` is required when `autoCapture` is enabled because the plugin reads the completed conversation snapshot from `agent_end`.
+
 ## Configuration
 
-| Option | Type | Required | Default | Description |
-|---|---|---|---|---|
-| `baseURL` | string | ✅ | — | Base URL of your Persistio instance |
-| `apiKey` | string | ✅ | — | Vault API key |
-| `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 | | `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 |
-| `ingest.skipSubagentSessions` | boolean | | `true` | Skip `agent:*` sessions unless they are `agent:main:*` |
-| `ingest.user.maxCharsPerMessage` | number | | `24000` | Maximum user-message characters considered for ingest before chunking |
-| `ingest.agent.mode` | `"bounded"` or `"raw"` | | `"bounded"` | Assistant ingest shaping mode. `bounded` collapses obvious large noisy blocks before chunking |
-| `ingest.agent.maxCharsPerMessage` | number | | `24000` | Maximum assistant-message characters considered after filtering |
-| `ingest.agent.maxCharsAfterFiltering` | number | | `9000` | Maximum assistant-message characters retained after deterministic filtering |
-| `ingest.agent.maxCharsPerTurn` | number | | `24000` | Maximum assistant-message characters sent from one turn |
-| `send.roles.user` | `"enabled"` or `"disabled"` | | `"enabled"` | Send user messages to Persistio ingest |
-| `send.roles.agent` | `"enabled"` or `"disabled"` | | `"enabled"` | Send agent/assistant messages to Persistio ingest |
-| `send.roles.tool` | `"enabled"` or `"disabled"` | | `"disabled"` | Send tool messages to Persistio ingest |
-
-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.
-
-## Tools exposed
-
-| Tool | Description |
-|---|---|
-| `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
-
-MIT
+| Option | Default | Description |
+|---|---:|---|
+| `autoRecall` | `true` | Inject a small fail-open memory block before the model turn |
+| `autoCapture` | `true` | Capture bounded post-turn messages asynchronously |
+| `recall.timeoutMs` | `1200` | HTTP timeout for recall and recall-bundle calls |
+| `recall.maxResults` | `4` | Maximum memories returned by recall |
+| `recall.tokenBudget` | `400` | Approximate prompt-token budget for auto-recall |
+| `recall.minSimilarity` | unset | Optional Persistio similarity floor |
+| `recall.includePending` | `false` | Include pending candidate memories in hot-path recall |
+| `recall.includeRelated` | `false` | Include graph-related memories in hot-path recall |
+| `recall.queryMaxChars` | `1200` | Maximum latest-user query characters embedded for recall |
+| `capture.timeoutMs` | `10000` | HTTP timeout for post-turn ingest and manual writes |
+| `capture.maxCharsPerTurn` | `6000` | Maximum captured characters per turn |
+| `capture.maxCharsPerMessage` | `3000` | Maximum captured characters per message |
+| `capture.maxChunksPerTurn` | `4` | Maximum chunks sent to Persistio per turn |
+| `capture.maxChunkChars` | `2000` | Maximum characters per capture chunk |
+| `capture.roles.user` | `enabled` | Capture user messages |
+| `capture.roles.assistant` | `bounded` | Capture assistant messages after deterministic noise filtering |
+| `capture.roles.tool` | `disabled` | Capture tool messages |
+
+## Upgrade from 0.1.x
+
+Install the `0.2.x` package, configure `openclaw-persistio-v2`, and point the OpenClaw memory slot at the new plugin id:
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "openclaw-persistio-v2"
+    }
+  }
+}
+```
+
+Keep the old `openclaw-persistio` entry disabled or remove it after confirming the new slot behaves correctly. The v2 id is intentionally distinct so operators opt into the new memory-slot behavior instead of silently changing an existing v1 install.
+
+## Benchmark Posture
+
+For behavioral benchmark work, leave `autoRecall=true` and `autoCapture=true`, keep recall under a tight timeout, and keep `includePending` / `includeRelated` off unless the specific benchmark requires them.
+
+The expected turn shape is:
+
+```text
+OpenClaw turn
+  -> Persistio autoRecall, bounded and fail-open
+  -> model answers with a tiny memory block
+  -> Persistio autoCapture, async and non-blocking
+```

package/dist/capture.d.ts

@@ -0,0 +1,17 @@
+import type { IngestChunk } from './client.js';
+import type { PersistioV2Config } from './config.js';
+export interface PreparedCapture {
+    chunks: IngestChunk[];
+    keys: string[];
+    items: CaptureItem[];
+}
+export interface CaptureItem {
+    key: string;
+    chunks: IngestChunk[];
+}
+export interface PrepareCaptureOptions {
+    shouldIncludeKey?: (key: string) => boolean;
+}
+export declare function prepareCapture(event: {
+    messages?: unknown[];
+}, cfg: PersistioV2Config, options?: PrepareCaptureOptions): PreparedCapture;

package/dist/capture.js

@@ -0,0 +1,112 @@
+import { extractTextFromMessage } from './memory-format.js';
+export function prepareCapture(event, cfg, options = {}) {
+    if (!Array.isArray(event.messages))
+        return { chunks: [], keys: [], items: [] };
+    const chunks = [];
+    const keys = [];
+    const items = [];
+    let turnChars = 0;
+    for (const [index, message] of event.messages.entries()) {
+        const role = normalizeRole(message);
+        if (!role || !shouldCaptureRole(role, cfg))
+            continue;
+        const rawText = extractTextFromMessage(message);
+        const key = messageKey(message, role, rawText, index);
+        if (options.shouldIncludeKey && !options.shouldIncludeKey(key))
+            continue;
+        if (chunks.length >= cfg.capture.maxChunksPerTurn)
+            break;
+        const preparedText = prepareTextForRole(rawText, role, cfg);
+        if (!preparedText)
+            continue;
+        const remainingTurnChars = cfg.capture.maxCharsPerTurn - turnChars;
+        if (remainingTurnChars <= 0)
+            break;
+        const boundedText = truncate(preparedText, Math.min(cfg.capture.maxCharsPerMessage, remainingTurnChars));
+        const itemChunks = [];
+        for (const chunk of chunkText(boundedText, cfg.capture.maxChunkChars)) {
+            if (chunks.length >= cfg.capture.maxChunksPerTurn)
+                break;
+            const ingestChunk = {
+                role,
+                content: chunk,
+                timestamp: resolveTimestamp(message) ?? new Date().toISOString(),
+            };
+            chunks.push(ingestChunk);
+            itemChunks.push(ingestChunk);
+            turnChars += chunk.length;
+        }
+        if (itemChunks.length > 0) {
+            keys.push(key);
+            items.push({ key, chunks: itemChunks });
+        }
+    }
+    return { chunks, keys, items };
+}
+function normalizeRole(message) {
+    if (typeof message !== 'object' || message === null)
+        return null;
+    const role = message['role'];
+    return role === 'user' || role === 'assistant' || role === 'tool' ? role : null;
+}
+function shouldCaptureRole(role, cfg) {
+    if (role === 'user')
+        return cfg.capture.roles.user === 'enabled';
+    if (role === 'assistant')
+        return cfg.capture.roles.assistant !== 'disabled';
+    return cfg.capture.roles.tool === 'enabled';
+}
+function prepareTextForRole(text, role, cfg) {
+    const normalized = normalizeText(text);
+    if (!normalized)
+        return '';
+    if (role !== 'assistant' || cfg.capture.roles.assistant !== 'bounded') {
+        return normalized;
+    }
+    return normalized
+        .replace(/```[\s\S]*?```/g, '[Code block omitted from memory capture]')
+        .replace(/\n(?:[|].*[|]\n){8,}/g, '\n[Large table omitted from memory capture]\n')
+        .replace(/\n(?:[-+].*\n){20,}/g, '\n[Large diff/log omitted from memory capture]\n')
+        .trim();
+}
+function normalizeText(text) {
+    return text
+        .replace(/\r\n?/g, '\n')
+        .replace(/[ \t]+\n/g, '\n')
+        .replace(/\n{4,}/g, '\n\n\n')
+        .trim();
+}
+function chunkText(text, maxChars) {
+    if (text.length <= maxChars)
+        return [text];
+    const chunks = [];
+    for (let start = 0; start < text.length; start += maxChars) {
+        const chunk = text.slice(start, start + maxChars).trim();
+        if (chunk)
+            chunks.push(chunk);
+    }
+    return chunks;
+}
+function truncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    return `${text.slice(0, Math.max(0, maxChars - 3)).trimEnd()}...`;
+}
+function resolveTimestamp(message) {
+    if (typeof message !== 'object' || message === null)
+        return undefined;
+    const value = message['timestamp'];
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' && Number.isFinite(value))
+        return new Date(value).toISOString();
+    return undefined;
+}
+function messageKey(message, role, text, index) {
+    if (typeof message === 'object' && message !== null) {
+        const id = message['id'];
+        if (typeof id === 'string' && id)
+            return `${role}:${id}`;
+    }
+    return `${role}:${index}:${text.slice(0, 300)}`;
+}

package/dist/client.d.ts

@@ -1,78 +1,55 @@
-import type { PersistioIngestPolicy } from './ingest-policy.js';
-export interface PersistioConfig {
-    baseURL: string;
-    apiKey: string;
-    tokenBudget: number;
-    recallTopK: number;
-    recallMinSimilarity?: number;
-    recallTimeout: number;
-    recallIncludePending: boolean;
-    includeRelatedMemories: boolean;
-    ingest: PersistioIngestPolicy;
-    send: PersistioSendConfig;
-}
-export type PersistioSendRoleStatus = 'enabled' | 'disabled';
-export interface PersistioSendConfig {
-    roles: {
-        user: PersistioSendRoleStatus;
-        agent: PersistioSendRoleStatus;
-        tool: PersistioSendRoleStatus;
-    };
-}
+import type { PersistioV2Config } from './config.js';
 export interface PersistioMemory {
     id: string;
     data: string;
     subject: string;
     similarity?: number;
-    categories: string[];
-    confidence: number;
-}
-export interface GetMemoryOptions {
-    includePending?: boolean;
+    confidence?: number;
+    categories?: string[];
+    source?: string;
+    edge_type?: string | null;
 }
 export interface RecallBundle {
     global_user_rules?: string[];
-    user_rules: string[];
-    user_preferences: string[];
-    task_patterns: string[];
-    workflows: string[];
-    project: string[];
-    constraints: string[];
-    decisions: string[];
-    system_facts: string[];
-    domain_knowledge: string[];
+    user_rules?: string[];
+    user_preferences?: string[];
+    task_patterns?: string[];
+    workflows?: string[];
+    project?: string[];
+    constraints?: string[];
+    decisions?: string[];
+    system_facts?: string[];
+    domain_knowledge?: string[];
 }
 export interface RecallBundleResponse {
-    bundle: RecallBundle;
+    bundle?: RecallBundle;
     related_bundle?: RecallBundle;
 }
-export interface RecallBundleOptions {
-    includeRelated?: boolean;
+export interface RecallResult {
+    memories: PersistioMemory[];
+    relatedMemories: PersistioMemory[];
+}
+export interface IngestChunk {
+    role: string;
+    content: string;
+    timestamp: string;
 }
 export declare class PersistioTimeoutError extends Error {
     constructor(operation: string, timeoutMs: number);
 }
 export declare class PersistioClient {
+    private readonly config;
     private readonly baseURL;
     private readonly apiKey;
-    private readonly recallTopK;
-    private readonly recallMinSimilarity?;
-    private readonly recallTimeout;
-    private readonly recallIncludePending;
-    private readonly includeRelatedMemories;
-    private readonly ingestTimeout;
-    private readonly writeTimeout;
-    constructor(config: PersistioConfig);
+    constructor(config: PersistioV2Config);
+    recall(query: string, options?: {
+        maxResults?: number;
+    }): Promise<RecallResult>;
+    recallBundle(query: string): Promise<RecallBundleResponse>;
+    ingest(sessionId: string, chunks: IngestChunk[]): Promise<void>;
+    storeMemory(data: string, subject: string): Promise<PersistioMemory>;
+    forgetMemory(id: string): Promise<void>;
+    private buildRecallBody;
     private headers;
-    recall(query: string): Promise<PersistioMemory[]>;
-    recallBundle(query: string, topK?: number, options?: RecallBundleOptions): Promise<RecallBundleResponse>;
-    ingest(sessionId: string, chunks: Array<{
-        role: string;
-        content: string;
-        timestamp: string;
-    }>): Promise<void>;
-    addMemory(data: string, subject: string): Promise<void>;
-    deleteMemory(id: string): Promise<void>;
-    getMemory(id: string, options?: GetMemoryOptions): Promise<PersistioMemory | null>;
-    listMemories(): Promise<PersistioMemory[]>;
 }
+export declare function withRequestDeadline<T>(operation: string, timeoutMs: number, run: (signal: AbortSignal) => Promise<T>): Promise<T>;

package/dist/client.js

@@ -5,42 +5,17 @@ export class PersistioTimeoutError extends Error {
     }
 }
 export class PersistioClient {
+    config;
     baseURL;
     apiKey;
-    recallTopK;
-    recallMinSimilarity;
-    recallTimeout;
-    recallIncludePending;
-    includeRelatedMemories;
-    ingestTimeout;
-    writeTimeout;
     constructor(config) {
+        this.config = config;
         this.baseURL = config.baseURL.replace(/\/$/, '');
         this.apiKey = config.apiKey;
-        this.recallTopK = config.recallTopK;
-        this.recallMinSimilarity = config.recallMinSimilarity;
-        this.recallTimeout = config.recallTimeout;
-        this.recallIncludePending = config.recallIncludePending;
-        this.includeRelatedMemories = config.includeRelatedMemories;
-        this.ingestTimeout = config.ingest.timeoutMs;
-        this.writeTimeout = config.ingest.timeoutMs;
     }
-    headers() {
-        return {
-            'Content-Type': 'application/json',
-            'Authorization': `Bearer ${this.apiKey}`,
-        };
-    }
-    async recall(query) {
-        return withRequestDeadline('recall', this.recallTimeout, async (signal) => {
-            const body = {
-                query,
-                top_k: this.recallTopK,
-                include_pending: this.recallIncludePending
-            };
-            if (typeof this.recallMinSimilarity === 'number') {
-                body.min_similarity = this.recallMinSimilarity;
-            }
+    async recall(query, options = {}) {
+        return withRequestDeadline('recall', this.config.recall.timeoutMs, async (signal) => {
+            const body = this.buildRecallBody(query, options.maxResults);
             const res = await fetch(`${this.baseURL}/v1/recall`, {
                 method: 'POST',
                 headers: this.headers(),
@@ -48,22 +23,19 @@ export class PersistioClient {
                 signal,
             });
             if (!res.ok)
-                throw new Error(`Persistio recall failed: ${res.status}`);
+                throw new Error(await formatHttpError('recall', res));
             const data = await res.json();
-            return data.memories ?? [];
+            return {
+                memories: Array.isArray(data.memories) ? data.memories : [],
+                relatedMemories: Array.isArray(data.related_memories) ? data.related_memories : [],
+            };
         });
     }
-    async recallBundle(query, topK, options = {}) {
-        return withRequestDeadline('recallBundle', this.recallTimeout, async (signal) => {
+    async recallBundle(query) {
+        return withRequestDeadline('recallBundle', this.config.recall.timeoutMs, async (signal) => {
             const body = {
-                query,
-                top_k: topK ?? this.recallTopK,
-                include_pending: this.recallIncludePending,
-                include_related: options.includeRelated ?? this.includeRelatedMemories
+                ...this.buildRecallBody(query, this.config.recall.maxResults),
             };
-            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(),
@@ -71,15 +43,14 @@ export class PersistioClient {
                 signal,
             });
             if (!res.ok)
-                throw new Error(`Persistio recallBundle failed: ${res.status}`);
-            const data = await res.json();
-            return data;
+                throw new Error(await formatHttpError('recallBundle', res));
+            return await res.json();
         });
     }
     async ingest(sessionId, chunks) {
         if (chunks.length === 0)
             return;
-        await withRequestDeadline('ingest', this.ingestTimeout, async (signal) => {
+        await withRequestDeadline('ingest', this.config.capture.timeoutMs, async (signal) => {
             const res = await fetch(`${this.baseURL}/v1/ingest`, {
                 method: 'POST',
                 headers: this.headers(),
@@ -90,8 +61,8 @@ export class PersistioClient {
                 throw new Error(await formatHttpError('ingest', res));
         });
     }
-    async addMemory(data, subject) {
-        await withRequestDeadline('addMemory', this.writeTimeout, async (signal) => {
+    async storeMemory(data, subject) {
+        return withRequestDeadline('memory_store', this.config.capture.timeoutMs, async (signal) => {
             const res = await fetch(`${this.baseURL}/v1/memories`, {
                 method: 'POST',
                 headers: this.headers(),
@@ -99,48 +70,41 @@ export class PersistioClient {
                 signal,
             });
             if (!res.ok)
-                throw new Error(`Persistio addMemory failed: ${res.status}`);
+                throw new Error(await formatHttpError('memory_store', res));
+            return await res.json();
         });
     }
-    async deleteMemory(id) {
-        await withRequestDeadline('deleteMemory', this.writeTimeout, async (signal) => {
-            const res = await fetch(`${this.baseURL}/v1/memories/${id}`, {
+    async forgetMemory(id) {
+        await withRequestDeadline('memory_forget', this.config.capture.timeoutMs, async (signal) => {
+            const res = await fetch(`${this.baseURL}/v1/memories/${encodeURIComponent(id)}`, {
                 method: 'DELETE',
                 headers: this.headers(),
                 signal,
             });
             if (!res.ok)
-                throw new Error(`Persistio deleteMemory failed: ${res.status}`);
+                throw new Error(await formatHttpError('memory_forget', res));
         });
     }
-    async getMemory(id, options = {}) {
-        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();
-        });
+    buildRecallBody(query, maxResults = this.config.recall.maxResults) {
+        const body = {
+            query,
+            top_k: maxResults,
+            include_pending: this.config.recall.includePending,
+            include_related: this.config.recall.includeRelated,
+        };
+        if (typeof this.config.recall.minSimilarity === 'number') {
+            body.min_similarity = this.config.recall.minSimilarity;
+        }
+        return body;
     }
-    async listMemories() {
-        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 ?? [];
-        });
+    headers() {
+        return {
+            'Content-Type': 'application/json',
+            'Authorization': `Bearer ${this.apiKey}`,
+        };
     }
 }
-async function withRequestDeadline(operation, timeoutMs, run) {
+export async function withRequestDeadline(operation, timeoutMs, run) {
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
         return run(new AbortController().signal);
     }
@@ -167,9 +131,7 @@ async function withRequestDeadline(operation, timeoutMs, run) {
     }
 }
 function isAbortLikeError(err) {
-    if (!(err instanceof Error))
-        return false;
-    return err.name === 'AbortError' || err.name === 'TimeoutError';
+    return err instanceof Error && (err.name === 'AbortError' || err.name === 'TimeoutError');
 }
 async function formatHttpError(operation, res) {
     let detail = '';
@@ -177,7 +139,7 @@ async function formatHttpError(operation, res) {
         detail = (await res.text()).trim().slice(0, 500);
     }
     catch {
-        // Ignore response body read failures; the status is still actionable.
+        // Status code is still useful if the body cannot be read.
     }
     return detail
         ? `Persistio ${operation} failed: ${res.status} ${detail}`