hindclaw-openclaw 0.1.0

package/dist/embed-manager.js

@@ -0,0 +1,289 @@
+import { spawn } from 'child_process';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+import { homedir } from 'os';
+export class HindsightEmbedManager {
+    process = null;
+    port;
+    baseUrl;
+    embedDir;
+    llmProvider;
+    llmApiKey;
+    llmModel;
+    llmBaseUrl;
+    daemonIdleTimeout;
+    embedVersion;
+    embedPackagePath;
+    jwtSecret;
+    clientId;
+    constructor(port, llmProvider, llmApiKey, llmModel, llmBaseUrl, daemonIdleTimeout = 0, // Default: never timeout
+    embedVersion = 'latest', // Default: latest
+    embedPackagePath, // Local path to hindsight package
+    jwtSecret, clientId = 'openclaw') {
+        // Use the configured port (default: 9077 from config)
+        this.port = port;
+        this.baseUrl = `http://127.0.0.1:${port}`;
+        this.embedDir = join(homedir(), '.openclaw', 'hindsight-embed');
+        this.llmProvider = llmProvider;
+        this.llmApiKey = llmApiKey;
+        this.llmModel = llmModel;
+        this.llmBaseUrl = llmBaseUrl;
+        this.daemonIdleTimeout = daemonIdleTimeout;
+        this.embedVersion = embedVersion || 'latest';
+        this.embedPackagePath = embedPackagePath;
+        this.jwtSecret = jwtSecret;
+        this.clientId = clientId || 'openclaw';
+    }
+    /**
+     * Get the command to run hindsight-embed (either local or from PyPI)
+     */
+    getEmbedCommand() {
+        const extraPackages = this.getExtraEmbedPackages();
+        if (this.embedPackagePath) {
+            // Local package: uv run --directory <path> hindsight-embed
+            return ['uv', 'run', '--directory', this.embedPackagePath, ...extraPackages.flatMap((pkg) => ['--with', pkg]), 'hindsight-embed'];
+        }
+        else {
+            // PyPI package: uvx hindsight-embed@version
+            const embedPackage = this.embedVersion ? `hindsight-embed@${this.embedVersion}` : 'hindsight-embed@latest';
+            return ['uvx', ...extraPackages.flatMap((pkg) => ['--with', pkg]), embedPackage];
+        }
+    }
+    getExtraEmbedPackages() {
+        const packages = [];
+        if (this.llmProvider === 'claude-code') {
+            packages.push('claude-agent-sdk');
+        }
+        if (this.jwtSecret) {
+            packages.push('hindclaw-extension');
+        }
+        return packages;
+    }
+    async start() {
+        // Skip if daemon is already running (prevents duplicate starts when gateway
+        // loads the plugin multiple times during startup/hot-reload)
+        if (await this.checkHealth()) {
+            console.log(`[Hindsight] Daemon already running on port ${this.port}, skipping start`);
+            return;
+        }
+        console.log(`[Hindsight] Starting hindsight-embed daemon...`);
+        // Build environment variables using standard HINDSIGHT_API_LLM_* variables
+        const env = {
+            ...process.env,
+            HINDSIGHT_API_LLM_PROVIDER: this.llmProvider,
+            HINDSIGHT_API_LLM_API_KEY: this.llmApiKey,
+            HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT: this.jwtSecret ? '0' : this.daemonIdleTimeout.toString(),
+        };
+        if (this.llmModel) {
+            env['HINDSIGHT_API_LLM_MODEL'] = this.llmModel;
+        }
+        // Pass through base URL for OpenAI-compatible providers (OpenRouter, etc.)
+        if (this.llmBaseUrl) {
+            env['HINDSIGHT_API_LLM_BASE_URL'] = this.llmBaseUrl;
+        }
+        // On macOS, force CPU for embeddings/reranker to avoid MPS/Metal issues in daemon mode
+        if (process.platform === 'darwin') {
+            env['HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU'] = '1';
+            env['HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU'] = '1';
+        }
+        if (this.jwtSecret) {
+            const pg0Port = await this.resolvePg0Port();
+            env['HINDSIGHT_API_TENANT_EXTENSION'] = 'hindclaw_ext:HindclawTenant';
+            env['HINDSIGHT_API_OPERATION_VALIDATOR_EXTENSION'] = 'hindclaw_ext:HindclawValidator';
+            env['HINDSIGHT_API_HTTP_EXTENSION'] = 'hindclaw_ext:HindclawHttp';
+            env['HINDCLAW_JWT_SECRET'] = this.jwtSecret;
+            env['HINDCLAW_ADMIN_CLIENTS'] = this.clientId;
+            env['HINDCLAW_DATABASE_URL'] = `postgresql://hindsight:hindsight@localhost:${pg0Port}/hindsight`;
+        }
+        // Configure "openclaw" profile using hindsight-embed configure (non-interactive)
+        console.log('[Hindsight] Configuring "openclaw" profile...');
+        await this.configureProfile(env);
+        // Start hindsight-embed daemon with openclaw profile
+        const embedCmd = this.getEmbedCommand();
+        const startDaemon = spawn(embedCmd[0], [...embedCmd.slice(1), 'daemon', '--profile', 'openclaw', 'start'], {
+            stdio: 'pipe',
+        });
+        // Collect output
+        let output = '';
+        startDaemon.stdout?.on('data', (data) => {
+            const text = data.toString();
+            output += text;
+            console.log(`[Hindsight] ${text.trim()}`);
+        });
+        startDaemon.stderr?.on('data', (data) => {
+            const text = data.toString();
+            output += text;
+            console.error(`[Hindsight] ${text.trim()}`);
+        });
+        // Wait for daemon start command to complete
+        await new Promise((resolve, reject) => {
+            startDaemon.on('exit', (code) => {
+                if (code === 0) {
+                    console.log('[Hindsight] Daemon start command completed');
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Daemon start failed with code ${code}: ${output}`));
+                }
+            });
+            startDaemon.on('error', (error) => {
+                reject(error);
+            });
+        });
+        // Wait for server to be ready
+        await this.waitForReady();
+        console.log('[Hindsight] Daemon is ready');
+    }
+    async stop() {
+        console.log('[Hindsight] Stopping hindsight-embed daemon...');
+        const embedCmd = this.getEmbedCommand();
+        const stopDaemon = spawn(embedCmd[0], [...embedCmd.slice(1), 'daemon', '--profile', 'openclaw', 'stop'], {
+            stdio: 'pipe',
+        });
+        await new Promise((resolve) => {
+            stopDaemon.on('exit', () => {
+                console.log('[Hindsight] Daemon stopped');
+                resolve();
+            });
+            stopDaemon.on('error', (error) => {
+                console.error('[Hindsight] Error stopping daemon:', error);
+                resolve(); // Resolve anyway
+            });
+            // Timeout after 5 seconds
+            setTimeout(() => {
+                console.log('[Hindsight] Daemon stop timeout');
+                resolve();
+            }, 5000);
+        });
+    }
+    async waitForReady(maxAttempts = 30) {
+        console.log('[Hindsight] Waiting for daemon to be ready...');
+        for (let i = 0; i < maxAttempts; i++) {
+            try {
+                const response = await fetch(`${this.baseUrl}/health`);
+                if (response.ok) {
+                    console.log('[Hindsight] Daemon health check passed');
+                    return;
+                }
+            }
+            catch {
+                // Not ready yet
+            }
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+        throw new Error('Hindsight daemon failed to become ready within 30 seconds');
+    }
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    isRunning() {
+        return this.process !== null;
+    }
+    async checkHealth() {
+        try {
+            const response = await fetch(`${this.baseUrl}/health`, { signal: AbortSignal.timeout(2000) });
+            return response.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    async configureProfile(env) {
+        // Build profile create command args with --merge, --port and --env flags
+        // Use --merge to allow updating existing profile
+        const createArgs = ['profile', 'create', 'openclaw', '--merge', '--port', this.port.toString()];
+        // Add all environment variables as --env flags
+        // Must include ALL HINDSIGHT_API_* vars that the daemon reads,
+        // otherwise configureProfile overwrites the profile and drops them.
+        const envVars = [
+            // LLM
+            'HINDSIGHT_API_LLM_PROVIDER',
+            'HINDSIGHT_API_LLM_MODEL',
+            'HINDSIGHT_API_LLM_API_KEY',
+            'HINDSIGHT_API_LLM_BASE_URL',
+            // Embeddings
+            'HINDSIGHT_API_EMBEDDINGS_PROVIDER',
+            'HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL',
+            'HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU',
+            'HINDSIGHT_API_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE',
+            'HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY',
+            'HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL',
+            'HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL',
+            'HINDSIGHT_API_EMBEDDINGS_TEI_URL',
+            'HINDSIGHT_API_EMBEDDINGS_COHERE_API_KEY',
+            'HINDSIGHT_API_EMBEDDINGS_COHERE_MODEL',
+            'HINDSIGHT_API_EMBEDDINGS_COHERE_BASE_URL',
+            'HINDSIGHT_API_EMBEDDINGS_LITELLM_API_BASE',
+            'HINDSIGHT_API_EMBEDDINGS_LITELLM_API_KEY',
+            'HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL',
+            'HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_KEY',
+            'HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_MODEL',
+            'HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_BASE',
+            // Reranker
+            'HINDSIGHT_API_RERANKER_PROVIDER',
+            'HINDSIGHT_API_RERANKER_LOCAL_MODEL',
+            'HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU',
+            'HINDSIGHT_API_RERANKER_FLASHRANK_MODEL',
+            'HINDSIGHT_API_RERANKER_COHERE_API_KEY',
+            'HINDSIGHT_API_RERANKER_COHERE_MODEL',
+            // Daemon
+            'HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT',
+            // Hindclaw extensions
+            'HINDSIGHT_API_TENANT_EXTENSION',
+            'HINDSIGHT_API_OPERATION_VALIDATOR_EXTENSION',
+            'HINDSIGHT_API_HTTP_EXTENSION',
+            'HINDCLAW_JWT_SECRET',
+            'HINDCLAW_ADMIN_CLIENTS',
+            'HINDCLAW_DATABASE_URL',
+        ];
+        for (const envVar of envVars) {
+            if (env[envVar]) {
+                createArgs.push('--env', `${envVar}=${env[envVar]}`);
+            }
+        }
+        // Run profile create command (non-interactive, overwrites if exists)
+        const embedCmd = this.getEmbedCommand();
+        const create = spawn(embedCmd[0], [...embedCmd.slice(1), ...createArgs], {
+            stdio: 'pipe',
+        });
+        let output = '';
+        create.stdout?.on('data', (data) => {
+            const text = data.toString();
+            output += text;
+            console.log(`[Hindsight] ${text.trim()}`);
+        });
+        create.stderr?.on('data', (data) => {
+            const text = data.toString();
+            output += text;
+            console.error(`[Hindsight] ${text.trim()}`);
+        });
+        await new Promise((resolve, reject) => {
+            create.on('exit', (code) => {
+                if (code === 0) {
+                    console.log('[Hindsight] Profile "openclaw" configured successfully');
+                    resolve();
+                }
+                else {
+                    reject(new Error(`Profile create failed with code ${code}: ${output}`));
+                }
+            });
+            create.on('error', (error) => {
+                reject(error);
+            });
+        });
+    }
+    async resolvePg0Port() {
+        const instancePath = join(homedir(), '.pg0', 'instances', 'hindsight-embed-openclaw', 'instance.json');
+        try {
+            const raw = await readFile(instancePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.port === 'number' && Number.isFinite(parsed.port)) {
+                return parsed.port;
+            }
+        }
+        catch {
+            // Fall back to the default local pg0 port when the instance metadata is unavailable.
+        }
+        return 5432;
+    }
+}

package/dist/format.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryResult } from './types.js';
+export declare const DEFAULT_RECALL_PROMPT_PREAMBLE = "Relevant memories from past conversations (prioritize recent when conflicting). Only use memories that are directly useful to continue this conversation; ignore the rest:";
+export declare function formatCurrentTimeForRecall(date?: Date): string;
+export declare function formatMemories(results: MemoryResult[]): string;

package/dist/format.js

@@ -0,0 +1,20 @@
+export const DEFAULT_RECALL_PROMPT_PREAMBLE = 'Relevant memories from past conversations (prioritize recent when conflicting). Only use memories that are directly useful to continue this conversation; ignore the rest:';
+export function formatCurrentTimeForRecall(date = new Date()) {
+    const year = date.getUTCFullYear();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    const hours = String(date.getUTCHours()).padStart(2, '0');
+    const minutes = String(date.getUTCMinutes()).padStart(2, '0');
+    return `${year}-${month}-${day} ${hours}:${minutes}`;
+}
+export function formatMemories(results) {
+    if (!results || results.length === 0)
+        return '';
+    return results
+        .map(r => {
+        const type = r.type ? ` [${r.type}]` : '';
+        const date = r.mentioned_at ? ` (${r.mentioned_at})` : '';
+        return `- ${r.text}${type}${date}`;
+    })
+        .join('\n\n');
+}

package/dist/hooks/recall.d.ts

@@ -0,0 +1,17 @@
+import type { PluginHookAgentContext, PluginConfig, ResolvedConfig, MemoryResult } from '../types.js';
+import type { HindsightClient } from '../client.js';
+export { extractRecallQuery, composeRecallQuery, truncateRecallQuery, } from '../utils.js';
+/** Clear module-level state. Called by service.stop() to prevent stale data after reinit. */
+export declare function resetRecallState(): void;
+/**
+ * Round-robin interleave results from multiple bank recall sets.
+ * Takes one result from each set in turn, handling uneven lengths.
+ */
+export declare function interleaveResults(resultSets: MemoryResult[][]): MemoryResult[];
+/**
+ * Handle the recall hook — supports single-bank, multi-bank, and reflect paths.
+ *
+ * Returns a formatted memory string to prepend to the agent context,
+ * or undefined if no relevant memories were found.
+ */
+export declare function handleRecall(event: any, ctx: PluginHookAgentContext | undefined, agentConfig: ResolvedConfig, client: HindsightClient, pluginConfig: PluginConfig): Promise<string | undefined>;

package/dist/hooks/recall.js

@@ -0,0 +1,230 @@
+import { createHash } from 'crypto';
+import { HindsightHttpError } from '../client.js';
+import { debug } from '../debug.js';
+import { deriveBankId } from '../derive-bank-id.js';
+import { formatMemories, formatCurrentTimeForRecall, DEFAULT_RECALL_PROMPT_PREAMBLE } from '../format.js';
+import { extractRecallQuery, composeRecallQuery, truncateRecallQuery, } from '../utils.js';
+// Re-export utilities for backward compatibility and testing
+export { extractRecallQuery, composeRecallQuery, truncateRecallQuery, } from '../utils.js';
+const RECALL_TIMEOUT_MS = 10_000;
+// ── In-flight recall deduplication (I1) ─────────────────────────────
+// Concurrent recalls for the same bank+query hash reuse one promise.
+// Ported from native index.ts lines 31-33.
+const inflightRecalls = new Map();
+/** Clear module-level state. Called by service.stop() to prevent stale data after reinit. */
+export function resetRecallState() {
+    inflightRecalls.clear();
+}
+/**
+ * Round-robin interleave results from multiple bank recall sets.
+ * Takes one result from each set in turn, handling uneven lengths.
+ */
+export function interleaveResults(resultSets) {
+    const result = [];
+    const maxLen = Math.max(...resultSets.map(s => s.length), 0);
+    for (let i = 0; i < maxLen; i++) {
+        for (const set of resultSets) {
+            if (i < set.length)
+                result.push(set[i]);
+        }
+    }
+    return result;
+}
+/**
+ * Handle the recall hook — supports single-bank, multi-bank, and reflect paths.
+ *
+ * Returns a formatted memory string to prepend to the agent context,
+ * or undefined if no relevant memories were found.
+ */
+export async function handleRecall(event, ctx, agentConfig, client, pluginConfig) {
+    // 1. Determine primary bank
+    const primaryBankId = deriveBankId(ctx, pluginConfig);
+    debug(`[Hindsight] before_prompt_build - bank: ${primaryBankId}, channel: ${ctx?.messageProvider}/${ctx?.channelId}`);
+    debug(`[Hindsight] event keys: ${Object.keys(event ?? {}).join(', ')}`);
+    debug(`[Hindsight] event.context keys: ${Object.keys(event?.context ?? {}).join(', ')}`);
+    // 2. Extract query using full native pipeline (C1)
+    debug(`[Hindsight] extractRecallQuery input lengths - raw: ${event?.rawMessage?.length ?? 0}, prompt: ${event?.prompt?.length ?? 0}`);
+    const extracted = extractRecallQuery(event?.rawMessage, event?.prompt);
+    if (!extracted) {
+        debug('[Hindsight] extractRecallQuery returned null, skipping recall');
+        return undefined;
+    }
+    debug(`[Hindsight] extractRecallQuery result length: ${extracted.length}`);
+    // 3. Compose multi-turn query from session messages
+    const recallContextTurns = agentConfig.recallContextTurns ?? pluginConfig.recallContextTurns ?? 1;
+    const recallMaxQueryChars = agentConfig.recallMaxQueryChars ?? pluginConfig.recallMaxQueryChars ?? 800;
+    const recallRoles = agentConfig.recallRoles ?? pluginConfig.recallRoles ?? ['user', 'assistant'];
+    const sessionMessages = event?.context?.sessionEntry?.messages ?? event?.messages ?? [];
+    const messageCount = sessionMessages.length;
+    debug(`[Hindsight] event.messages count: ${messageCount}, roles: ${sessionMessages.map((m) => m.role).join(',')}`);
+    if (recallContextTurns > 1 && messageCount === 0) {
+        debug('[Hindsight] recallContextTurns > 1 but event.messages is empty — prior context unavailable at before_agent_start for this provider');
+    }
+    const composedQuery = composeRecallQuery(extracted, sessionMessages, recallContextTurns, recallRoles);
+    let query = truncateRecallQuery(composedQuery, extracted, recallMaxQueryChars);
+    // Final defensive cap (matches native)
+    if (query.length > recallMaxQueryChars) {
+        query = query.substring(0, recallMaxQueryChars);
+    }
+    // 4. Determine recall-from banks
+    const recallFrom = agentConfig._recallFrom;
+    // 5. Build common recall params
+    const budget = agentConfig.recallBudget;
+    const maxTokens = agentConfig.recallMaxTokens;
+    const types = agentConfig.recallTypes;
+    const topK = agentConfig.recallTopK;
+    // 6. Reflect path — use reflect instead of recall on primary bank
+    if (agentConfig._reflectOnRecall) {
+        debug(`[Hindsight] Reflect path for bank ${primaryBankId}, query:\n---\n${query}\n---`);
+        try {
+            const response = await client.reflect(primaryBankId, {
+                query,
+                budget: agentConfig._reflectBudget ?? budget,
+                max_tokens: agentConfig._reflectMaxTokens ?? maxTokens,
+            }, ctx);
+            if (!response.text) {
+                debug('[Hindsight] Reflect returned empty text, skipping memory injection');
+                return undefined;
+            }
+            debug(`[Hindsight] Reflect response length: ${response.text.length} chars`);
+            // Wrap in <hindsight_memories> tags (I4)
+            const preamble = agentConfig.recallPromptPreamble ?? DEFAULT_RECALL_PROMPT_PREAMBLE;
+            const timestamp = formatCurrentTimeForRecall();
+            return `<hindsight_memories>\n${preamble}\nCurrent time - ${timestamp}\n\n${response.text}\n</hindsight_memories>`;
+        }
+        catch (error) {
+            if (error instanceof HindsightHttpError && error.status === 403) {
+                debug(`[Hindsight] Reflect denied for bank ${primaryBankId}, skipping`);
+                return undefined;
+            }
+            // I5: Timeout-specific error handling
+            if (error instanceof DOMException && error.name === 'TimeoutError') {
+                console.warn(`[Hindsight] Reflect timed out, skipping memory injection`);
+            }
+            else if (error instanceof Error && error.name === 'AbortError') {
+                console.warn(`[Hindsight] Reflect aborted, skipping memory injection`);
+            }
+            else {
+                console.warn(`[Hindsight] Reflect failed for bank ${primaryBankId}:`, error instanceof Error ? error.message : error);
+            }
+            return undefined;
+        }
+    }
+    // 7. Determine bank list
+    const banks = recallFrom ?? [{ bankId: primaryBankId }];
+    debug(`[Hindsight] Auto-recall for bank ${banks.map(b => b.bankId).join(', ')}, full query:\n---\n${query}\n---`);
+    // 8. Single bank — straightforward recall with deduplication (I1)
+    if (banks.length === 1) {
+        const bank = banks[0];
+        try {
+            const response = await recallWithDedup(client, bank.bankId, {
+                query,
+                budget: bank.budget ?? budget,
+                max_tokens: bank.maxTokens ?? maxTokens,
+                types: bank.types ?? types,
+                tag_groups: (bank.tagGroups ?? []).length > 0 ? bank.tagGroups : undefined,
+            }, ctx);
+            if (!response.results?.length) {
+                debug('[Hindsight] No memories found for auto-recall');
+                return undefined;
+            }
+            debug(`[Hindsight] Raw recall response (${response.results.length} results before topK):\n${response.results.map((r, i) => `  [${i}] score=${r.score?.toFixed(3) ?? 'n/a'} type=${r.type ?? 'n/a'}: ${JSON.stringify(r.content ?? r.text ?? r).substring(0, 200)}`).join('\n')}`);
+            const results = topK ? response.results.slice(0, topK) : response.results;
+            debug(`[Hindsight] After topK (${topK ?? 'unlimited'}): ${results.length} results injected`);
+            const output = formatRecallOutput(results, agentConfig);
+            if (output) {
+                debug(`[Hindsight] Auto-recall: Injecting ${results.length} memories from bank ${bank.bankId}`);
+            }
+            return output;
+        }
+        catch (error) {
+            if (error instanceof HindsightHttpError && error.status === 403) {
+                debug(`[Hindsight] Recall denied for bank ${bank.bankId}, skipping`);
+                return undefined;
+            }
+            // I5: Timeout-specific error handling
+            if (error instanceof DOMException && error.name === 'TimeoutError') {
+                console.warn(`[Hindsight] Recall timed out after ${RECALL_TIMEOUT_MS}ms for bank ${bank.bankId}, skipping memory injection`);
+            }
+            else if (error instanceof Error && error.name === 'AbortError') {
+                console.warn(`[Hindsight] Recall aborted after ${RECALL_TIMEOUT_MS}ms for bank ${bank.bankId}, skipping memory injection`);
+            }
+            else {
+                console.warn(`[Hindsight] Recall failed for bank ${bank.bankId}:`, error instanceof Error ? error.message : error);
+            }
+            return undefined;
+        }
+    }
+    // 9. Multi-bank — parallel recall + interleave (with dedup)
+    debug(`[Hindsight] Multi-bank recall across ${banks.length} banks: ${banks.map(b => b.bankId).join(', ')}`);
+    const results = await Promise.allSettled(banks.map(bank => recallWithDedup(client, bank.bankId, {
+        query,
+        budget: bank.budget ?? budget,
+        max_tokens: bank.maxTokens ?? maxTokens,
+        types: bank.types ?? types,
+        tag_groups: (bank.tagGroups ?? []).length > 0 ? bank.tagGroups : undefined,
+    }, ctx)));
+    const successSets = [];
+    for (const [i, result] of results.entries()) {
+        if (result.status === 'fulfilled' && result.value.results?.length) {
+            debug(`[Hindsight] Bank ${banks[i].bankId}: ${result.value.results.length} results`);
+            successSets.push(result.value.results);
+        }
+        else if (result.status === 'rejected') {
+            const bankId = banks[i].bankId;
+            const err = result.reason;
+            if (err instanceof HindsightHttpError && err.status === 403) {
+                debug(`[Hindsight] Recall denied for bank ${bankId}, skipping`);
+            }
+            else {
+                console.warn(`[Hindsight] Recall failed for bank ${bankId}:`, err instanceof Error ? err.message : err);
+            }
+        }
+        else if (result.status === 'fulfilled') {
+            debug(`[Hindsight] Bank ${banks[i].bankId}: no results`);
+        }
+    }
+    if (successSets.length === 0) {
+        debug('[Hindsight] No memories found for auto-recall (all banks empty)');
+        return undefined;
+    }
+    const merged = interleaveResults(successSets);
+    debug(`[Hindsight] Multi-bank merged: ${merged.length} total results from ${successSets.length} banks`);
+    const output = formatRecallOutput(merged, agentConfig);
+    if (output) {
+        debug(`[Hindsight] Auto-recall: Injecting ${merged.length} memories from ${successSets.length} banks`);
+    }
+    return output;
+}
+/**
+ * Recall with in-flight deduplication (I1).
+ * Concurrent recalls for the same bank+query hash reuse one promise.
+ * Ported from native index.ts lines 1107-1118.
+ */
+async function recallWithDedup(client, bankId, request, ctx) {
+    const normalizedQuery = request.query.trim().toLowerCase().replace(/\s+/g, ' ');
+    const queryHash = createHash('sha256').update(normalizedQuery).digest('hex').slice(0, 16);
+    const recallKey = `${bankId}::${queryHash}`;
+    const existing = inflightRecalls.get(recallKey);
+    if (existing) {
+        debug(`[Hindsight] Reusing in-flight recall for bank ${bankId}`);
+        return existing;
+    }
+    const recallPromise = client.recall(bankId, request, RECALL_TIMEOUT_MS, ctx);
+    inflightRecalls.set(recallKey, recallPromise);
+    void recallPromise.catch(() => { }).finally(() => inflightRecalls.delete(recallKey));
+    return recallPromise;
+}
+/**
+ * Format recall results wrapped in <hindsight_memories> tags (I4).
+ * Native wraps in: <hindsight_memories>\n{content}\n</hindsight_memories>.
+ * This prevents the feedback loop where recalled memories get re-retained.
+ */
+function formatRecallOutput(results, agentConfig) {
+    const formatted = formatMemories(results);
+    if (!formatted)
+        return undefined;
+    const preamble = agentConfig.recallPromptPreamble ?? DEFAULT_RECALL_PROMPT_PREAMBLE;
+    const timestamp = formatCurrentTimeForRecall();
+    return `<hindsight_memories>\n${preamble}\nCurrent time - ${timestamp}\n\n${formatted}\n</hindsight_memories>`;
+}

package/dist/hooks/retain.d.ts

@@ -0,0 +1,26 @@
+import type { HindsightClient } from '../client.js';
+import type { ResolvedConfig, PluginConfig, PluginHookAgentContext } from '../types.js';
+export { stripMemoryTags } from '../utils.js';
+/** Clear module-level state. Called by service.stop() to prevent stale data after reinit. */
+export declare function resetRetainState(): void;
+/**
+ * Prepare a retention transcript from messages.
+ * Ported from native index.ts lines 1292-1359.
+ *
+ * Key differences from our old implementation:
+ * - Finds last user message index and retains only from there (unless retainFullWindow)
+ * - Uses `[role: user]\ncontent\n[user:end]` format (not `user: content`)
+ * - Calls stripMemoryTags() AND stripMetadataEnvelopes() on each message
+ * - Returns `{ transcript, messageCount } | null`
+ * - Rejects transcripts < 10 chars
+ */
+export declare function prepareRetentionTranscript(messages: any[], retainRoles: string[], retainFullWindow?: boolean): {
+    transcript: string;
+    messageCount: number;
+} | null;
+/**
+ * Handle the retain hook — supports chunked retention with turn counting.
+ *
+ * Ported from native index.ts lines 1162-1279.
+ */
+export declare function handleRetain(event: any, ctx: PluginHookAgentContext | undefined, agentConfig: ResolvedConfig, client: HindsightClient, pluginConfig: PluginConfig): Promise<void>;