@persistio/openclaw-plugin 0.1.5 → 0.1.7

package/src/client.ts

@@ -1,3 +1,5 @@
+import type { PersistioIngestPolicy } from './ingest-policy.js';
+
 export interface PersistioConfig {
   baseURL: string;
   apiKey: string;
@@ -5,6 +7,7 @@ export interface PersistioConfig {
   recallTopK: number;
   recallMinSimilarity?: number;
   recallTimeout: number;
+  ingest: PersistioIngestPolicy;
   send: PersistioSendConfig;
 }
 
@@ -49,12 +52,21 @@ 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;
   private readonly recallTopK: number;
   private readonly recallMinSimilarity?: number;
   private readonly recallTimeout: number;
+  private readonly ingestTimeout: number;
+  private readonly writeTimeout: number;
 
   constructor(config: PersistioConfig) {
     this.baseURL = config.baseURL.replace(/\/$/, '');
@@ -62,6 +74,8 @@ export class PersistioClient {
     this.recallTopK = config.recallTopK;
     this.recallMinSimilarity = config.recallMinSimilarity;
     this.recallTimeout = config.recallTimeout;
+    this.ingestTimeout = config.ingest.timeoutMs;
+    this.writeTimeout = config.ingest.timeoutMs;
   }
 
   private headers(): Record<string, string> {
@@ -72,82 +86,150 @@ 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 }),
+    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(`Persistio ingest failed: ${res.status}`);
   }
 
   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 {
+    detail = (await res.text()).trim().slice(0, 500);
+  } catch {
+    // Ignore response body read failures; the status is still actionable.
+  }
+
+  return detail
+    ? `Persistio ${operation} failed: ${res.status} ${detail}`
+    : `Persistio ${operation} failed: ${res.status}`;
+}

package/src/index.ts

@@ -7,8 +7,13 @@ import type {
 } from 'openclaw/plugin-sdk/memory-core-host-engine-storage';
 import { Type } from '@sinclair/typebox';
 import { PersistioClient, type PersistioConfig, type PersistioMemory, type RecallBundle } from './client.js';
-
-type OpenClawMessageRole = 'user' | 'assistant' | 'tool';
+import {
+  prepareMessageForIngest,
+  resolveIngestPolicy,
+  shouldIngestSession,
+  type OpenClawMessageRole,
+  type OmissionSummary,
+} from './ingest-policy.js';
 
 interface SessionMessageKeyStore {
   keys: Set<string>;
@@ -24,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'];
@@ -49,15 +89,22 @@ 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),
   };
 }
@@ -133,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) },
     );
   }
 
@@ -303,6 +358,82 @@ function forgetKeys(target: Set<string>, keys: string[]): void {
   for (const key of keys) target.delete(key);
 }
 
+function summarizeOmissions(omissions: OmissionSummary[]): string {
+  if (omissions.length === 0) return 'none';
+  const counts = new Map<string, number>();
+  for (const omission of omissions) {
+    counts.set(omission.label, (counts.get(omission.label) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([label, count]) => `${label}:${count}`)
+    .join(',');
+}
+
+function isTimeoutLikeError(err: unknown): boolean {
+  if (typeof err !== 'object' || err === null) return false;
+  const record = err as Record<string, unknown>;
+  const name = typeof record['name'] === 'string' ? record['name'] : '';
+  if (name === 'TimeoutError' || name === 'AbortError') return true;
+  const message = typeof record['message'] === 'string' ? record['message'].toLowerCase() : '';
+  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 {
@@ -353,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 {
@@ -374,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 => {
@@ -443,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),
       };
     },
 
@@ -471,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),
     });
 
     // -------------------------------------------------------------------------
@@ -483,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)
@@ -503,8 +651,18 @@ export default definePluginEntry({
       try {
         const sessionId = context?.sessionId ?? event.runId ?? 'unknown-session';
         if (sessionId.startsWith('announce:')) return;
+        if (!shouldIngestSession(sessionId, cfg.ingest)) {
+          api.logger?.debug?.(`openclaw-persistio: ingest skipped non-main session: ${sessionId}`);
+          return;
+        }
         const chunks: Array<{ role: string; content: string; timestamp: string }> = [];
         const chunkKeys: string[] = [];
+        let agentCharsSent = 0;
+        let originalChars = 0;
+        let preparedChars = 0;
+        let truncatedMessages = 0;
+        let skippedMessages = 0;
+        const omissions: OmissionSummary[] = [];
         const now = Date.now();
         const sentKeys = getSessionKeyStore(sentMessageKeysBySession, sessionId, now);
         const pendingKeys = getSessionKeyStore(pendingMessageKeysBySession, sessionId, now);
@@ -520,17 +678,55 @@ export default definePluginEntry({
           if (sentKeys.has(key) || pendingKeys.has(key)) continue;
 
           const ts = resolveMessageTimestamp(m) ?? new Date().toISOString();
+          const prepared = prepareMessageForIngest({
+            role,
+            text,
+            policy: cfg.ingest,
+            remainingAgentChars: Math.max(0, cfg.ingest.agent.maxCharsPerTurn - agentCharsSent),
+            remainingChunks: Math.max(0, cfg.ingest.maxChunksPerTurn - chunks.length),
+          });
+
+          originalChars += prepared.originalChars;
+          preparedChars += prepared.preparedChars;
+          omissions.push(...prepared.omissions);
+          if (prepared.truncated) truncatedMessages += 1;
+          if (prepared.chunks.length === 0) {
+            skippedMessages += 1;
+            continue;
+          }
+
           chunkKeys.push(key);
-          chunks.push({ role, content: text, timestamp: ts });
+          if (role === 'assistant') {
+            agentCharsSent += prepared.preparedChars;
+          }
+          chunks.push(...prepared.chunks.map((content) => ({ role, content, timestamp: ts })));
+
+          if (chunks.length >= cfg.ingest.maxChunksPerTurn) break;
         }
 
         if (chunks.length === 0) return;
+        if (truncatedMessages > 0 || omissions.length > 0 || skippedMessages > 0) {
+          api.logger?.info?.(
+            `openclaw-persistio: ingest planned session=${sessionId} chunks=${chunks.length} `
+            + `originalChars=${originalChars} preparedChars=${preparedChars} `
+            + `truncatedMessages=${truncatedMessages} skippedMessages=${skippedMessages} `
+            + `omissions=${summarizeOmissions(omissions)}`,
+          );
+        }
         rememberKeys(pendingKeys, chunkKeys);
         client.ingest(sessionId, chunks)
           .then(() => {
             rememberKeys(sentKeys, chunkKeys, MAX_SENT_KEYS_PER_SESSION);
           })
           .catch((err: unknown) => {
+            if (isTimeoutLikeError(err)) {
+              rememberKeys(sentKeys, chunkKeys, MAX_SENT_KEYS_PER_SESSION);
+              api.logger?.warn?.(
+                `openclaw-persistio: ingest timeout after ${cfg.ingest.timeoutMs}ms; `
+                + `outcome is ambiguous, suppressing retry for ${chunkKeys.length} messages in session=${sessionId}`,
+              );
+              return;
+            }
             api.logger?.warn?.(`openclaw-persistio: ingest error: ${String(err)}`);
           })
           .finally(() => {
@@ -558,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.';
@@ -579,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 };
       },
     });