@vectorize-io/hindsight-openclaw 0.4.11 → 0.4.12

package/dist/client.d.ts

@@ -1,27 +1,13 @@
 import type { RetainRequest, RetainResponse, RecallRequest, RecallResponse } from './types.js';
-/**
- * Escape a string for use as a single-quoted shell argument.
- *
- * In POSIX shells, single-quoted strings treat ALL characters literally
- * except for the single quote itself. To include a literal single quote,
- * we use the pattern: end quote + escaped quote + start quote = '\''
- *
- * Example: "It's $100" becomes 'It'\''s $100'
- * Shell interprets: 'It' + \' + 's $100' = It's $100
- *
- * This handles ALL shell-special characters including:
- * - $ (variable expansion)
- * - ` (command substitution)
- * - ! (history expansion)
- * - ? * [ ] (glob patterns)
- * - ( ) { } (subshell/brace expansion)
- * - < > | & ; (redirection/control)
- * - \ " # ~ newlines
- *
- * @param arg - The string to escape
- * @returns The escaped string (without surrounding quotes - caller adds those)
- */
-export declare function escapeShellArg(arg: string): string;
+export interface HindsightClientOptions {
+    llmProvider: string;
+    llmApiKey: string;
+    llmModel?: string;
+    embedVersion?: string;
+    embedPackagePath?: string;
+    apiUrl?: string;
+    apiToken?: string;
+}
 export declare class HindsightClient {
     private bankId;
     private llmProvider;
@@ -29,13 +15,24 @@ export declare class HindsightClient {
     private llmModel?;
     private embedVersion;
     private embedPackagePath?;
-    constructor(llmProvider: string, llmApiKey: string, llmModel?: string, embedVersion?: string, embedPackagePath?: string);
+    private apiUrl?;
+    private apiToken?;
+    constructor(opts: HindsightClientOptions);
+    private get httpMode();
     /**
-     * Get the command prefix to run hindsight-embed (either local or from PyPI)
+     * Get the command and base args to run hindsight-embed.
+     * Returns [command, ...baseArgs] for use with execFile/spawn (no shell).
      */
-    private getEmbedCommandPrefix;
+    private getEmbedCommand;
+    private httpHeaders;
     setBankId(bankId: string): void;
     setBankMission(mission: string): Promise<void>;
+    private setBankMissionHttp;
+    private setBankMissionSubprocess;
     retain(request: RetainRequest): Promise<RetainResponse>;
-    recall(request: RecallRequest): Promise<RecallResponse>;
+    private retainHttp;
+    private retainSubprocess;
+    recall(request: RecallRequest, timeoutMs?: number): Promise<RecallResponse>;
+    private recallHttp;
+    private recallSubprocess;
 }

package/dist/client.js

@@ -1,74 +1,98 @@
-import { exec } from 'child_process';
+import { execFile } from 'child_process';
 import { promisify } from 'util';
-const execAsync = promisify(exec);
+import { writeFile, mkdir, rm } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { randomBytes } from 'crypto';
+const execFileAsync = promisify(execFile);
+const MAX_BUFFER = 5 * 1024 * 1024; // 5 MB — large transcripts can exceed default 1 MB
+const DEFAULT_TIMEOUT_MS = 15_000;
+/** Strip null bytes from strings — Node 22 rejects them in execFile() args */
+const sanitize = (s) => s.replace(/\0/g, '');
 /**
- * Escape a string for use as a single-quoted shell argument.
- *
- * In POSIX shells, single-quoted strings treat ALL characters literally
- * except for the single quote itself. To include a literal single quote,
- * we use the pattern: end quote + escaped quote + start quote = '\''
- *
- * Example: "It's $100" becomes 'It'\''s $100'
- * Shell interprets: 'It' + \' + 's $100' = It's $100
- *
- * This handles ALL shell-special characters including:
- * - $ (variable expansion)
- * - ` (command substitution)
- * - ! (history expansion)
- * - ? * [ ] (glob patterns)
- * - ( ) { } (subshell/brace expansion)
- * - < > | & ; (redirection/control)
- * - \ " # ~ newlines
- *
- * @param arg - The string to escape
- * @returns The escaped string (without surrounding quotes - caller adds those)
+ * Sanitize a string for use as a cross-platform filename.
+ * Replaces characters illegal on Windows or Unix with underscores.
  */
-export function escapeShellArg(arg) {
-    // Replace single quotes with the escape sequence: '\''
-    // This ends the current single-quoted string, adds an escaped literal quote,
-    // and starts a new single-quoted string.
-    return arg.replace(/'/g, "'\\''");
+function sanitizeFilename(name) {
+    // Replace characters illegal on Windows (\/:*?"<>|) and control chars
+    return name.replace(/[\\/:*?"<>|\x00-\x1f]/g, '_').slice(0, 200) || 'content';
 }
 export class HindsightClient {
-    bankId = 'default'; // Always use default bank
+    bankId = 'default';
     llmProvider;
     llmApiKey;
     llmModel;
     embedVersion;
     embedPackagePath;
-    constructor(llmProvider, llmApiKey, llmModel, embedVersion = 'latest', embedPackagePath) {
-        this.llmProvider = llmProvider;
-        this.llmApiKey = llmApiKey;
-        this.llmModel = llmModel;
-        this.embedVersion = embedVersion || 'latest';
-        this.embedPackagePath = embedPackagePath;
+    apiUrl;
+    apiToken;
+    constructor(opts) {
+        this.llmProvider = opts.llmProvider;
+        this.llmApiKey = opts.llmApiKey;
+        this.llmModel = opts.llmModel;
+        this.embedVersion = opts.embedVersion || 'latest';
+        this.embedPackagePath = opts.embedPackagePath;
+        this.apiUrl = opts.apiUrl?.replace(/\/$/, ''); // strip trailing slash
+        this.apiToken = opts.apiToken;
+    }
+    get httpMode() {
+        return !!this.apiUrl;
     }
     /**
-     * Get the command prefix to run hindsight-embed (either local or from PyPI)
+     * Get the command and base args to run hindsight-embed.
+     * Returns [command, ...baseArgs] for use with execFile/spawn (no shell).
      */
-    getEmbedCommandPrefix() {
+    getEmbedCommand() {
         if (this.embedPackagePath) {
-            // Local package: uv run --directory <path> hindsight-embed
-            return `uv run --directory ${this.embedPackagePath} hindsight-embed`;
+            return ['uv', 'run', '--directory', this.embedPackagePath, 'hindsight-embed'];
         }
-        else {
-            // PyPI package: uvx hindsight-embed@version
-            const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
-            return `uvx ${embedPackage}`;
+        const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
+        return ['uvx', embedPackage];
+    }
+    httpHeaders() {
+        const headers = { 'Content-Type': 'application/json' };
+        if (this.apiToken) {
+            headers['Authorization'] = `Bearer ${this.apiToken}`;
         }
+        return headers;
     }
     setBankId(bankId) {
         this.bankId = bankId;
     }
+    // --- setBankMission ---
     async setBankMission(mission) {
         if (!mission || mission.trim().length === 0) {
             return;
         }
-        const escapedMission = escapeShellArg(mission);
-        const embedCmd = this.getEmbedCommandPrefix();
-        const cmd = `${embedCmd} --profile openclaw bank mission ${this.bankId} '${escapedMission}'`;
+        if (this.httpMode) {
+            return this.setBankMissionHttp(mission);
+        }
+        return this.setBankMissionSubprocess(mission);
+    }
+    async setBankMissionHttp(mission) {
         try {
-            const { stdout } = await execAsync(cmd);
+            const url = `${this.apiUrl}/v1/default/banks/${encodeURIComponent(this.bankId)}`;
+            const res = await fetch(url, {
+                method: 'PUT',
+                headers: this.httpHeaders(),
+                body: JSON.stringify({ mission }),
+                signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                throw new Error(`HTTP ${res.status}: ${body}`);
+            }
+            console.log(`[Hindsight] Bank mission set via HTTP`);
+        }
+        catch (error) {
+            console.warn(`[Hindsight] Could not set bank mission (bank may not exist yet): ${error}`);
+        }
+    }
+    async setBankMissionSubprocess(mission) {
+        const [cmd, ...baseArgs] = this.getEmbedCommand();
+        const args = [...baseArgs, '--profile', 'openclaw', 'bank', 'mission', this.bankId, sanitize(mission)];
+        try {
+            const { stdout } = await execFileAsync(cmd, args, { maxBuffer: MAX_BUFFER });
             console.log(`[Hindsight] Bank mission set: ${stdout.trim()}`);
         }
         catch (error) {
@@ -76,15 +100,55 @@ export class HindsightClient {
             console.warn(`[Hindsight] Could not set bank mission (bank may not exist yet): ${error}`);
         }
     }
+    // --- retain ---
     async retain(request) {
-        const content = escapeShellArg(request.content);
-        const docId = escapeShellArg(request.document_id || 'conversation');
-        const embedCmd = this.getEmbedCommandPrefix();
-        const cmd = `${embedCmd} --profile openclaw memory retain ${this.bankId} '${content}' --doc-id '${docId}' --async`;
+        if (this.httpMode) {
+            return this.retainHttp(request);
+        }
+        return this.retainSubprocess(request);
+    }
+    async retainHttp(request) {
+        const url = `${this.apiUrl}/v1/default/banks/${encodeURIComponent(this.bankId)}/memories`;
+        const body = {
+            items: [{
+                    content: request.content,
+                    document_id: request.document_id || 'conversation',
+                    metadata: request.metadata,
+                }],
+            async: true,
+        };
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.httpHeaders(),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`Failed to retain memory (HTTP ${res.status}): ${text}`);
+        }
+        const data = await res.json();
+        console.log(`[Hindsight] Retained via HTTP (async): ${JSON.stringify(data).substring(0, 200)}`);
+        return {
+            message: 'Memory queued for background processing',
+            document_id: request.document_id || 'conversation',
+            memory_unit_ids: [],
+        };
+    }
+    async retainSubprocess(request) {
+        const docId = request.document_id || 'conversation';
+        // Write content to a temp file to avoid E2BIG (ARG_MAX) errors when passing
+        // large conversations as arguments.
+        const tempDir = join(tmpdir(), `hindsight_${randomBytes(8).toString('hex')}`);
+        const safeFilename = sanitizeFilename(docId);
+        const tempFile = join(tempDir, `${safeFilename}.txt`);
         try {
-            const { stdout } = await execAsync(cmd);
+            await mkdir(tempDir, { recursive: true });
+            await writeFile(tempFile, sanitize(request.content), 'utf8');
+            const [cmd, ...baseArgs] = this.getEmbedCommand();
+            const args = [...baseArgs, '--profile', 'openclaw', 'memory', 'retain-files', this.bankId, tempFile, '--async'];
+            const { stdout } = await execFileAsync(cmd, args, { maxBuffer: MAX_BUFFER });
             console.log(`[Hindsight] Retained (async): ${stdout.trim()}`);
-            // Return a simple response
             return {
                 message: 'Memory queued for background processing',
                 document_id: docId,
@@ -92,33 +156,57 @@ export class HindsightClient {
             };
         }
         catch (error) {
-            throw new Error(`Failed to retain memory: ${error}`);
+            throw new Error(`Failed to retain memory: ${error}`, { cause: error });
+        }
+        finally {
+            await rm(tempDir, { recursive: true, force: true }).catch(() => { });
+        }
+    }
+    // --- recall ---
+    async recall(request, timeoutMs) {
+        if (this.httpMode) {
+            return this.recallHttp(request, timeoutMs);
+        }
+        return this.recallSubprocess(request, timeoutMs);
+    }
+    async recallHttp(request, timeoutMs) {
+        const url = `${this.apiUrl}/v1/default/banks/${encodeURIComponent(this.bankId)}/memories/recall`;
+        // Defense-in-depth: truncate query to stay under API's 500-token limit
+        const MAX_QUERY_CHARS = 800;
+        const query = request.query.length > MAX_QUERY_CHARS
+            ? (console.warn(`[Hindsight] Truncating recall query from ${request.query.length} to ${MAX_QUERY_CHARS} chars`),
+                request.query.substring(0, MAX_QUERY_CHARS))
+            : request.query;
+        const body = {
+            query,
+            max_tokens: request.max_tokens || 1024,
+        };
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.httpHeaders(),
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(timeoutMs ?? DEFAULT_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`Failed to recall memories (HTTP ${res.status}): ${text}`);
         }
+        return res.json();
     }
-    async recall(request) {
-        const query = escapeShellArg(request.query);
+    async recallSubprocess(request, timeoutMs) {
+        const query = sanitize(request.query);
         const maxTokens = request.max_tokens || 1024;
-        const embedCmd = this.getEmbedCommandPrefix();
-        const cmd = `${embedCmd} --profile openclaw memory recall ${this.bankId} '${query}' --output json --max-tokens ${maxTokens}`;
+        const [cmd, ...baseArgs] = this.getEmbedCommand();
+        const args = [...baseArgs, '--profile', 'openclaw', 'memory', 'recall', this.bankId, query, '--output', 'json', '--max-tokens', String(maxTokens)];
         try {
-            const { stdout } = await execAsync(cmd);
-            // Parse JSON output - returns { entities: {...}, results: [...] }
-            const response = JSON.parse(stdout);
-            const results = response.results || [];
-            return {
-                results: results.map((r) => ({
-                    content: r.text || r.content || '',
-                    score: 1.0, // CLI doesn't return scores
-                    metadata: {
-                        document_id: r.document_id,
-                        chunk_id: r.chunk_id,
-                        ...r.metadata,
-                    },
-                })),
-            };
+            const { stdout } = await execFileAsync(cmd, args, {
+                maxBuffer: MAX_BUFFER,
+                timeout: timeoutMs ?? 30_000, // subprocess gets a longer default
+            });
+            return JSON.parse(stdout);
         }
         catch (error) {
-            throw new Error(`Failed to recall memories: ${error}`);
+            throw new Error(`Failed to recall memories: ${error}`, { cause: error });
         }
     }
 }

package/dist/index.d.ts

@@ -1,4 +1,19 @@
 import type { MoltbotPluginAPI } from './types.js';
 import { HindsightClient } from './client.js';
+/**
+ * Strip plugin-injected memory tags from content to prevent retain feedback loop.
+ * Removes <hindsight_memories> and <relevant_memories> blocks that were injected
+ * during before_agent_start so they don't get re-stored into the memory bank.
+ */
+export declare function stripMemoryTags(content: string): string;
+/**
+ * Extract a recall query from a hook event's rawMessage or prompt.
+ *
+ * Prefers rawMessage (clean user text). Falls back to prompt, stripping
+ * envelope formatting (System: lines, [Channel ...] headers, [from: X] footers).
+ *
+ * Returns null when no usable query (< 5 chars) can be extracted.
+ */
+export declare function extractRecallQuery(rawMessage: string | undefined, prompt: string | undefined): string | null;
 export default function (api: MoltbotPluginAPI): void;
 export declare function getClient(): HindsightClient | null;

package/dist/index.js

@@ -12,15 +12,83 @@ let usingExternalApi = false; // Track if using external API (skip daemon manage
 let currentPluginConfig = null;
 // Track which banks have had their mission set (to avoid re-setting on every request)
 const banksWithMissionSet = new Set();
+const inflightRecalls = new Map();
+const RECALL_TIMEOUT_MS = 10_000;
+// Cooldown + guard to prevent concurrent reinit attempts
+let lastReinitAttempt = 0;
+let isReinitInProgress = false;
+const REINIT_COOLDOWN_MS = 30_000;
+/**
+ * Lazy re-initialization after startup failure.
+ * Called by waitForReady when initPromise rejected but API may now be reachable.
+ * Throttled to one attempt per 30s to avoid hammering a down service.
+ */
+async function lazyReinit() {
+    const now = Date.now();
+    if (now - lastReinitAttempt < REINIT_COOLDOWN_MS || isReinitInProgress) {
+        return;
+    }
+    isReinitInProgress = true;
+    lastReinitAttempt = now;
+    const config = currentPluginConfig;
+    if (!config) {
+        isReinitInProgress = false;
+        return;
+    }
+    const externalApi = detectExternalApi(config);
+    if (!externalApi.apiUrl) {
+        isReinitInProgress = false;
+        return; // Only external API mode supports lazy reinit
+    }
+    console.log('[Hindsight] Attempting lazy re-initialization...');
+    try {
+        await checkExternalApiHealth(externalApi.apiUrl);
+        // Health check passed — set up env vars and create client
+        process.env.HINDSIGHT_EMBED_API_URL = externalApi.apiUrl;
+        if (externalApi.apiToken) {
+            process.env.HINDSIGHT_EMBED_API_TOKEN = externalApi.apiToken;
+        }
+        const llmConfig = detectLLMConfig(config);
+        client = new HindsightClient(buildClientOptions(llmConfig, config, externalApi));
+        const defaultBankId = deriveBankId(undefined, config);
+        client.setBankId(defaultBankId);
+        if (config.bankMission && !config.dynamicBankId) {
+            await client.setBankMission(config.bankMission);
+        }
+        usingExternalApi = true;
+        isInitialized = true;
+        // Replace the rejected initPromise with a resolved one
+        initPromise = Promise.resolve();
+        console.log('[Hindsight] ✓ Lazy re-initialization succeeded');
+    }
+    catch (error) {
+        console.warn(`[Hindsight] Lazy re-initialization failed (will retry in ${REINIT_COOLDOWN_MS / 1000}s):`, error instanceof Error ? error.message : error);
+    }
+    finally {
+        isReinitInProgress = false;
+    }
+}
 // Global access for hooks (Moltbot loads hooks separately)
 if (typeof global !== 'undefined') {
     global.__hindsightClient = {
         getClient: () => client,
         waitForReady: async () => {
-            if (isInitialized)
+            if (isInitialized) {
                 return;
-            if (initPromise)
-                await initPromise;
+            }
+            if (initPromise) {
+                try {
+                    await initPromise;
+                }
+                catch {
+                    // Init failed (e.g., health check timeout at startup).
+                    // Attempt lazy re-initialization so Hindsight recovers
+                    // once the API becomes reachable again.
+                    if (!isInitialized) {
+                        await lazyReinit();
+                    }
+                }
+            }
         },
         /**
          * Get a client configured for a specific agent context.
@@ -28,8 +96,9 @@ if (typeof global !== 'undefined') {
          * Also ensures the bank mission is set on first use.
          */
         getClientForContext: async (ctx) => {
-            if (!client)
+            if (!client) {
                 return null;
+            }
             const config = currentPluginConfig || {};
             const bankId = deriveBankId(ctx, config);
             client.setBankId(bankId);
@@ -55,9 +124,54 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Default bank name (fallback when channel context not available)
 const DEFAULT_BANK_NAME = 'openclaw';
+/**
+ * Strip plugin-injected memory tags from content to prevent retain feedback loop.
+ * Removes <hindsight_memories> and <relevant_memories> blocks that were injected
+ * during before_agent_start so they don't get re-stored into the memory bank.
+ */
+export function stripMemoryTags(content) {
+    content = content.replace(/<hindsight_memories>[\s\S]*?<\/hindsight_memories>/g, '');
+    content = content.replace(/<relevant_memories>[\s\S]*?<\/relevant_memories>/g, '');
+    return content;
+}
+/**
+ * Extract a recall query from a hook event's rawMessage or prompt.
+ *
+ * Prefers rawMessage (clean user text). Falls back to prompt, stripping
+ * envelope formatting (System: lines, [Channel ...] headers, [from: X] footers).
+ *
+ * Returns null when no usable query (< 5 chars) can be extracted.
+ */
+export function extractRecallQuery(rawMessage, prompt) {
+    let recallQuery = rawMessage;
+    if (!recallQuery || typeof recallQuery !== 'string' || recallQuery.trim().length < 5) {
+        recallQuery = prompt;
+        if (!recallQuery || typeof recallQuery !== 'string' || recallQuery.length < 5) {
+            return null;
+        }
+        // Strip envelope-formatted prompts from any channel
+        let cleaned = recallQuery;
+        // Remove leading "System: ..." lines (from prependSystemEvents)
+        cleaned = cleaned.replace(/^(?:System:.*\n)+\n?/, '');
+        // Remove session abort hint
+        cleaned = cleaned.replace(/^Note: The previous agent run was aborted[^\n]*\n\n/, '');
+        // Extract message after [ChannelName ...] envelope header
+        const envelopeMatch = cleaned.match(/\[[A-Z][A-Za-z]*(?:\s[^\]]+)?\]\s*([\s\S]+)$/);
+        if (envelopeMatch) {
+            cleaned = envelopeMatch[1];
+        }
+        // Remove trailing [from: SenderName] metadata (group chats)
+        cleaned = cleaned.replace(/\n\[from:[^\]]*\]\s*$/, '');
+        recallQuery = cleaned.trim() || recallQuery;
+    }
+    const trimmed = recallQuery.trim();
+    if (trimmed.length < 5)
+        return null;
+    return trimmed;
+}
 /**
  * Derive a bank ID from the agent context.
- * Creates channel-specific banks: {messageProvider}-{channelId}
+ * Creates per-user banks: {messageProvider}-{senderId}
  * Falls back to default bank when context is unavailable.
  */
 function deriveBankId(ctx, pluginConfig) {
@@ -68,9 +182,9 @@ function deriveBankId(ctx, pluginConfig) {
             : DEFAULT_BANK_NAME;
     }
     const channelType = ctx?.messageProvider || 'unknown';
-    const channelId = ctx?.channelId || 'default';
-    // Build bank ID: {prefix?}-{channelType}-{channelId}
-    const baseBankId = `${channelType}-${channelId}`;
+    const userId = ctx?.senderId || 'default';
+    // Build bank ID: {prefix?}-{channelType}-{senderId}
+    const baseBankId = `${channelType}-${userId}`;
     return pluginConfig.bankIdPrefix
         ? `${pluginConfig.bankIdPrefix}-${baseBankId}`
         : baseBankId;
@@ -181,22 +295,48 @@ function detectExternalApi(pluginConfig) {
     const apiToken = process.env.HINDSIGHT_EMBED_API_TOKEN || pluginConfig?.hindsightApiToken || null;
     return { apiUrl, apiToken };
 }
+/**
+ * Build HindsightClientOptions from LLM config, plugin config, and external API settings.
+ */
+function buildClientOptions(llmConfig, pluginCfg, externalApi) {
+    return {
+        llmProvider: llmConfig.provider,
+        llmApiKey: llmConfig.apiKey,
+        llmModel: llmConfig.model,
+        embedVersion: pluginCfg.embedVersion,
+        embedPackagePath: pluginCfg.embedPackagePath,
+        apiUrl: externalApi.apiUrl ?? undefined,
+        apiToken: externalApi.apiToken ?? undefined,
+    };
+}
 /**
  * Health check for external Hindsight API.
+ * Retries up to 3 times with 2s delay — container DNS may not be ready on first boot.
  */
 async function checkExternalApiHealth(apiUrl) {
     const healthUrl = `${apiUrl.replace(/\/$/, '')}/health`;
-    console.log(`[Hindsight] Checking external API health at ${healthUrl}...`);
-    try {
-        const response = await fetch(healthUrl, { signal: AbortSignal.timeout(10000) });
-        if (!response.ok) {
-            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    const maxRetries = 3;
+    const retryDelay = 2000;
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            console.log(`[Hindsight] Checking external API health at ${healthUrl}... (attempt ${attempt}/${maxRetries})`);
+            const response = await fetch(healthUrl, { signal: AbortSignal.timeout(10000) });
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+            }
+            const data = await response.json();
+            console.log(`[Hindsight] External API health: ${JSON.stringify(data)}`);
+            return;
+        }
+        catch (error) {
+            if (attempt < maxRetries) {
+                console.log(`[Hindsight] Health check attempt ${attempt} failed, retrying in ${retryDelay}ms...`);
+                await new Promise(resolve => setTimeout(resolve, retryDelay));
+            }
+            else {
+                throw new Error(`Cannot connect to external Hindsight API at ${apiUrl}: ${error}`, { cause: error });
+            }
         }
-        const data = await response.json();
-        console.log(`[Hindsight] External API health: ${JSON.stringify(data)}`);
-    }
-    catch (error) {
-        throw new Error(`Cannot connect to external Hindsight API at ${apiUrl}: ${error}`);
     }
 }
 function getPluginConfig(api) {
@@ -277,9 +417,9 @@ export default function (api) {
                     // External API mode - check health, skip daemon startup
                     console.log('[Hindsight] External API mode - skipping local daemon...');
                     await checkExternalApiHealth(externalApi.apiUrl);
-                    // Initialize client (CLI commands will use external API via env vars)
-                    console.log('[Hindsight] Creating HindsightClient...');
-                    client = new HindsightClient(llmConfig.provider, llmConfig.apiKey, llmConfig.model, pluginConfig.embedVersion, pluginConfig.embedPackagePath);
+                    // Initialize client with direct HTTP mode
+                    console.log('[Hindsight] Creating HindsightClient (HTTP mode)...');
+                    client = new HindsightClient(buildClientOptions(llmConfig, pluginConfig, externalApi));
                     // Set default bank (will be overridden per-request when dynamic bank IDs are enabled)
                     const defaultBankId = deriveBankId(undefined, pluginConfig);
                     console.log(`[Hindsight] Default bank: ${defaultBankId}`);
@@ -300,9 +440,9 @@ export default function (api) {
                     // Start the embedded server
                     console.log('[Hindsight] Starting embedded server...');
                     await embedManager.start();
-                    // Initialize client
-                    console.log('[Hindsight] Creating HindsightClient...');
-                    client = new HindsightClient(llmConfig.provider, llmConfig.apiKey, llmConfig.model, pluginConfig.embedVersion, pluginConfig.embedPackagePath);
+                    // Initialize client (local daemon mode — no apiUrl)
+                    console.log('[Hindsight] Creating HindsightClient (subprocess mode)...');
+                    client = new HindsightClient(buildClientOptions(llmConfig, pluginConfig, { apiUrl: null, apiToken: null }));
                     // Set default bank (will be overridden per-request when dynamic bank IDs are enabled)
                     const defaultBankId = deriveBankId(undefined, pluginConfig);
                     console.log(`[Hindsight] Default bank: ${defaultBankId}`);
@@ -322,7 +462,8 @@ export default function (api) {
                 throw error;
             }
         })();
-        // Don't await - let it initialize in background
+        // Suppress unhandled rejection — service.start() will await and handle errors
+        initPromise.catch(() => { });
         // Register background service for cleanup
         console.log('[Hindsight] Registering service...');
         api.registerService({
@@ -387,7 +528,7 @@ export default function (api) {
                             process.env.HINDSIGHT_EMBED_API_TOKEN = externalApi.apiToken;
                         }
                         await checkExternalApiHealth(externalApi.apiUrl);
-                        client = new HindsightClient(llmConfig.provider, llmConfig.apiKey, llmConfig.model, reinitPluginConfig.embedVersion, reinitPluginConfig.embedPackagePath);
+                        client = new HindsightClient(buildClientOptions(llmConfig, reinitPluginConfig, externalApi));
                         const defaultBankId = deriveBankId(undefined, reinitPluginConfig);
                         client.setBankId(defaultBankId);
                         if (reinitPluginConfig.bankMission && !reinitPluginConfig.dynamicBankId) {
@@ -400,7 +541,7 @@ export default function (api) {
                         // Local daemon mode
                         embedManager = new HindsightEmbedManager(apiPort, llmConfig.provider, llmConfig.apiKey, llmConfig.model, llmConfig.baseUrl, reinitPluginConfig.daemonIdleTimeout, reinitPluginConfig.embedVersion, reinitPluginConfig.embedPackagePath);
                         await embedManager.start();
-                        client = new HindsightClient(llmConfig.provider, llmConfig.apiKey, llmConfig.model, reinitPluginConfig.embedVersion, reinitPluginConfig.embedPackagePath);
+                        client = new HindsightClient(buildClientOptions(llmConfig, reinitPluginConfig, { apiUrl: null, apiToken: null }));
                         const defaultBankId = deriveBankId(undefined, reinitPluginConfig);
                         client.setBankId(defaultBankId);
                         if (reinitPluginConfig.bankMission && !reinitPluginConfig.dynamicBankId) {
@@ -452,31 +593,17 @@ export default function (api) {
                 // Derive bank ID from context
                 const bankId = deriveBankId(ctx, pluginConfig);
                 console.log(`[Hindsight] before_agent_start - bank: ${bankId}, channel: ${ctx?.messageProvider}/${ctx?.channelId}`);
-                // Get the user's latest message for recall
-                // Prefer rawMessage (clean user text) over prompt (envelope-formatted)
-                let prompt = event.rawMessage ?? event.prompt;
-                if (!prompt || typeof prompt !== 'string' || prompt.length < 5) {
-                    return; // Skip very short messages
-                }
-                // Strip envelope-formatted prompts from any channel
-                // The prompt may contain: System: lines, abort hints, [Channel ...] header, [from: ...] suffix
-                let cleaned = prompt;
-                // Remove leading "System: ..." lines (from prependSystemEvents)
-                cleaned = cleaned.replace(/^(?:System:.*\n)+\n?/, '');
-                // Remove session abort hint
-                cleaned = cleaned.replace(/^Note: The previous agent run was aborted[^\n]*\n\n/, '');
-                // Extract message after [ChannelName ...] envelope header
-                // Handles any channel: Telegram, Slack, Discord, WhatsApp, Signal, etc.
-                // Uses [\s\S]+ instead of .+ to support multiline messages
-                const envelopeMatch = cleaned.match(/\[[A-Z][A-Za-z]*(?:\s[^\]]+)?\]\s*([\s\S]+)$/);
-                if (envelopeMatch) {
-                    cleaned = envelopeMatch[1];
+                // Get the user's latest message for recall — only the raw user text, not the full prompt
+                // rawMessage is clean user text; prompt includes envelope, system events, media notes, etc.
+                const extracted = extractRecallQuery(event.rawMessage, event.prompt);
+                if (!extracted) {
+                    return;
                 }
-                // Remove trailing [from: SenderName] metadata (group chats)
-                cleaned = cleaned.replace(/\n\[from:[^\]]*\]\s*$/, '');
-                prompt = cleaned.trim() || prompt;
-                if (prompt.length < 5) {
-                    return; // Skip very short messages after extraction
+                let prompt = extracted;
+                // Truncate — Hindsight API recall has a 500 token limit; 800 chars stays safely under even with non-ASCII
+                const MAX_RECALL_QUERY_CHARS = 800;
+                if (prompt.length > MAX_RECALL_QUERY_CHARS) {
+                    prompt = prompt.substring(0, MAX_RECALL_QUERY_CHARS);
                 }
                 // Wait for client to be ready
                 const clientGlobal = global.__hindsightClient;
@@ -492,11 +619,20 @@ export default function (api) {
                     return;
                 }
                 console.log(`[Hindsight] Auto-recall for bank ${bankId}, prompt: ${prompt.substring(0, 50)}`);
-                // Recall relevant memories
-                const response = await client.recall({
-                    query: prompt,
-                    max_tokens: 2048,
-                });
+                // Recall with deduplication: reuse in-flight request for same bank
+                const recallKey = bankId;
+                const existing = inflightRecalls.get(recallKey);
+                let recallPromise;
+                if (existing) {
+                    console.log(`[Hindsight] Reusing in-flight recall for bank ${bankId}`);
+                    recallPromise = existing;
+                }
+                else {
+                    recallPromise = client.recall({ query: prompt, max_tokens: 2048 }, RECALL_TIMEOUT_MS);
+                    inflightRecalls.set(recallKey, recallPromise);
+                    void recallPromise.catch(() => { }).finally(() => inflightRecalls.delete(recallKey));
+                }
+                const response = await recallPromise;
                 if (!response.results || response.results.length === 0) {
                     console.log('[Hindsight] No memories found for auto-recall');
                     return;
@@ -504,7 +640,7 @@ export default function (api) {
                 // Format memories as JSON with all fields from recall
                 const memoriesJson = JSON.stringify(response.results, null, 2);
                 const contextMessage = `<hindsight_memories>
-Relevant memories from past conversations (score 1=highest, prioritize recent when conflicting):
+Relevant memories from past conversations (prioritize recent when conflicting):
 ${memoriesJson}
 
 User message: ${prompt}
@@ -514,7 +650,15 @@ User message: ${prompt}
                 return { prependContext: contextMessage };
             }
             catch (error) {
-                console.error('[Hindsight] Auto-recall error:', error);
+                if (error instanceof DOMException && error.name === 'TimeoutError') {
+                    console.warn(`[Hindsight] Auto-recall timed out after ${RECALL_TIMEOUT_MS}ms, skipping memory injection`);
+                }
+                else if (error instanceof Error && error.name === 'AbortError') {
+                    console.warn(`[Hindsight] Auto-recall aborted after ${RECALL_TIMEOUT_MS}ms, skipping memory injection`);
+                }
+                else {
+                    console.error('[Hindsight] Auto-recall error:', error);
+                }
                 return;
             }
         });
@@ -565,10 +709,7 @@ User message: ${prompt}
                             .join('\n');
                     }
                     // Strip plugin-injected memory tags to prevent feedback loop
-                    // Remove <hindsight_memories> blocks injected during before_agent_start
-                    content = content.replace(/<hindsight_memories>[\s\S]*?<\/hindsight_memories>/g, '');
-                    // Remove any <relevant_memories> blocks (legacy/alternative format)
-                    content = content.replace(/<relevant_memories>[\s\S]*?<\/relevant_memories>/g, '');
+                    content = stripMemoryTags(content);
                     return `[role: ${role}]\n${content}\n[${role}:end]`;
                 })
                     .join('\n\n');
@@ -585,7 +726,7 @@ User message: ${prompt}
                     document_id: documentId,
                     metadata: {
                         retained_at: new Date().toISOString(),
-                        message_count: event.messages.length,
+                        message_count: String(event.messages.length),
                         channel_type: effectiveCtx?.messageProvider,
                         channel_id: effectiveCtx?.channelId,
                         sender_id: effectiveCtx?.senderId,

package/dist/types.d.ts

@@ -61,15 +61,23 @@ export interface RecallRequest {
 }
 export interface RecallResponse {
     results: MemoryResult[];
+    entities: Record<string, unknown> | null;
+    trace: unknown | null;
+    chunks: unknown | null;
 }
 export interface MemoryResult {
-    content: string;
-    score: number;
-    metadata?: {
-        document_id?: string;
-        created_at?: string;
-        source?: string;
-    };
+    id: string;
+    text: string;
+    type: string;
+    entities: string[];
+    context: string;
+    occurred_start: string | null;
+    occurred_end: string | null;
+    mentioned_at: string | null;
+    document_id: string | null;
+    metadata: Record<string, unknown> | null;
+    chunk_id: string | null;
+    tags: string[];
 }
 export interface CreateBankRequest {
     name: string;

package/openclaw.plugin.json

@@ -57,12 +57,12 @@
       },
       "dynamicBankId": {
         "type": "boolean",
-        "description": "Enable per-channel memory banks. When true, memories are isolated by channel (e.g., slack-C123, telegram-456). When false, all channels share a single 'openclaw' bank.",
+        "description": "Enable per-user memory banks. When true, memories are isolated by user per channel (e.g., slack-U123, telegram-456789). When false, all users share a single 'openclaw' bank.",
         "default": true
       },
       "bankIdPrefix": {
         "type": "string",
-        "description": "Optional prefix for bank IDs (e.g., 'prod' results in 'prod-slack-C123'). Useful for separating environments."
+        "description": "Optional prefix for bank IDs (e.g., 'prod' results in 'prod-slack-U123'). Useful for separating environments."
       }
     },
     "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorize-io/hindsight-openclaw",
-  "version": "0.4.11",
+  "version": "0.4.12",
   "description": "Hindsight memory plugin for OpenClaw - biomimetic long-term memory with fact extraction",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,8 +34,9 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
-    "test": "vitest run",
-    "test:watch": "vitest",
+    "test": "vitest run src",
+    "test:watch": "vitest src",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
     "prepublishOnly": "npm run clean && npm run build"
   },
   "dependencies": {