@vectorize-io/hindsight-openclaw 0.5.1 → 0.6.0

package/dist/index.js

@@ -1,10 +1,23 @@
-import { HindsightEmbedManager } from './embed-manager.js';
-import { HindsightClient } from './client.js';
+import { HindsightServer } from '@vectorize-io/hindsight-all';
+import { HindsightClient } from '@vectorize-io/hindsight-client';
+import { RetainQueue } from './retain-queue.js';
+import { compileSessionPatterns, matchesSessionPattern } from './session-patterns.js';
 import { createHash } from 'crypto';
-import { dirname } from 'path';
+import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import * as log from './logger.js';
 import { configureLogger, setApiLogger, stopLogger } from './logger.js';
+import { mkdirSync } from 'fs';
+import { homedir } from 'os';
+// Logger adapter that routes the embed wrapper's output through openclaw's
+// batched structured logger so messages share the same prefix and respect
+// the configured log level.
+const embedLogger = {
+    debug: (msg) => log.verbose(msg),
+    info: (msg) => log.info(msg),
+    warn: (msg) => log.warn(msg),
+    error: (msg) => log.error(msg),
+};
 // Debug logging: silent by default, enable with debug: true or logLevel: 'debug'
 let debugEnabled = false;
 const debug = (...args) => {
@@ -12,7 +25,7 @@ const debug = (...args) => {
         log.verbose(args.map(a => typeof a === 'string' ? a.replace(/^\[Hindsight\]\s*/, '') : String(a)).join(' '));
 };
 // Module-level state
-let embedManager = null;
+let hindsightServer = null;
 let client = null;
 let clientOptions = null;
 let initPromise = null;
@@ -20,25 +33,134 @@ let isInitialized = false;
 let usingExternalApi = false; // Track if using external API (skip daemon management)
 // Store the current plugin config for bank ID derivation
 let currentPluginConfig = null;
-// Track which banks have had their mission set (to avoid re-setting on every request)
+// Track which banks have had their mission set (to avoid re-setting on every request).
+// Under the old bespoke client we also cached a client instance per bank because the
+// client carried a mutable bankId. HindsightClient takes bankId as a parameter on every
+// call, so no per-bank caching is needed anymore — one module-level client is enough.
 const banksWithMissionSet = new Set();
-// Use dedicated client instances per bank to avoid cross-session bankId mutation races.
-const clientsByBankId = new Map();
-const MAX_TRACKED_BANK_CLIENTS = 10_000;
 const inflightRecalls = new Map();
+function scopeClient(c, bankId) {
+    return {
+        bankId,
+        async retain(req) {
+            await c.retain(bankId, req.content, {
+                documentId: req.documentId,
+                metadata: toStringMetadata(req.metadata),
+                tags: req.tags,
+                async: true,
+            });
+        },
+        async recall(req, timeoutMs) {
+            const call = c.recall(bankId, req.query, {
+                maxTokens: req.maxTokens,
+                budget: req.budget,
+                types: req.types,
+            });
+            if (!timeoutMs)
+                return call;
+            // The generated client doesn't accept a per-call AbortSignal, so we race
+            // against a TimeoutError here. The before_prompt_build caller already
+            // special-cases `DOMException { name: 'TimeoutError' }` from the old
+            // bespoke client, so we preserve that contract.
+            return Promise.race([
+                call,
+                new Promise((_, reject) => setTimeout(() => reject(new DOMException(`Recall timed out after ${timeoutMs}ms`, 'TimeoutError')), timeoutMs)),
+            ]);
+        },
+        async setMission(mission) {
+            // createBank upserts the reflect mission. openclaw's old setBankMission
+            // went through a dedicated PUT endpoint; this call lands on the same
+            // server-side handler via the non-deprecated path.
+            await c.createBank(bankId, { reflectMission: mission });
+        },
+    };
+}
+/**
+ * The generated client's metadata type is `Record<string, string>`; the
+ * openclaw builder uses `Record<string, unknown>` because some fields come
+ * from optional plugin context. Drop undefined/null, stringify the rest.
+ */
+function toStringMetadata(input) {
+    if (!input)
+        return undefined;
+    const out = {};
+    for (const [k, v] of Object.entries(input)) {
+        if (v === undefined || v === null)
+            continue;
+        out[k] = typeof v === 'string' ? v : String(v);
+    }
+    return out;
+}
 const turnCountBySession = new Map();
 const MAX_TRACKED_SESSIONS = 10_000;
 const DEFAULT_RECALL_TIMEOUT_MS = 10_000;
 // Cache sender IDs discovered in before_prompt_build (where event.prompt has the metadata
 // blocks) so agent_end can look them up — event.messages in agent_end is clean history.
 const senderIdBySession = new Map();
-// Guard against double hook registration on the same api instance
-// Uses a WeakSet so each api instance can only register hooks once
-const registeredApis = new WeakSet();
+const documentSequenceBySession = new Map();
+// Guard against duplicate hook registration within a single runtime load.
+// Do not tie this to api instance identity, which can be brittle across loader phases.
+let hooksRegistered = false;
 // Cooldown + guard to prevent concurrent reinit attempts
 let lastReinitAttempt = 0;
 let isReinitInProgress = false;
 const REINIT_COOLDOWN_MS = 30_000;
+// Retain queue (external API mode only)
+let retainQueue = null;
+let retainQueueFlushTimer = null;
+let isFlushInProgress = false;
+const DEFAULT_FLUSH_INTERVAL_MS = 60_000; // 1 min
+/**
+ * Attempt to flush pending retains from the queue.
+ * Each item is sent exactly as it would have been originally — same bank, payload, metadata.
+ */
+async function flushRetainQueue() {
+    if (!retainQueue || isFlushInProgress)
+        return;
+    const pending = retainQueue.size();
+    if (pending === 0)
+        return;
+    isFlushInProgress = true;
+    let flushed = 0;
+    let failed = 0;
+    try {
+        if (!client)
+            return; // no client yet — can't flush
+        // Cleanup expired items first
+        retainQueue.cleanup();
+        const items = retainQueue.peek(50);
+        const flushedIds = [];
+        for (const item of items) {
+            try {
+                await client.retain(item.bankId, item.content, {
+                    documentId: item.documentId,
+                    metadata: toStringMetadata(item.metadata),
+                    tags: item.tags,
+                    async: true,
+                });
+                flushedIds.push(item.id);
+                flushed++;
+            }
+            catch {
+                // API still down — stop trying this batch
+                failed++;
+                break;
+            }
+        }
+        if (flushedIds.length > 0)
+            retainQueue.removeMany(flushedIds);
+        const remaining = retainQueue.size();
+        if (flushed > 0) {
+            log.info(`queue flush: ${flushed} queued retains delivered${remaining > 0 ? `, ${remaining} still pending` : ', queue empty'}`);
+        }
+        else if (failed > 0) {
+            debug(`[Hindsight] Queue flush: API still unreachable, ${remaining} retains pending`);
+        }
+    }
+    finally {
+        isFlushInProgress = false;
+    }
+}
 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:';
 function formatCurrentTimeForRecall(date = new Date()) {
     const year = date.getUTCFullYear();
@@ -52,19 +174,22 @@ function formatCurrentTimeForRecall(date = new Date()) {
  * 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.
+ * Only works if initialization was attempted at least once (isInitialized guard).
  */
-async function lazyReinit() {
+async function lazyReinit(configOverride) {
     const now = Date.now();
     if (now - lastReinitAttempt < REINIT_COOLDOWN_MS || isReinitInProgress) {
         return;
     }
-    isReinitInProgress = true;
-    lastReinitAttempt = now;
-    const config = currentPluginConfig;
+    const config = configOverride ?? currentPluginConfig;
     if (!config) {
-        isReinitInProgress = false;
+        debug('[Hindsight] lazyReinit skipped - no plugin config available');
         return;
     }
+    // Persist config if we only have it from the live hook registration path.
+    currentPluginConfig = config;
+    isReinitInProgress = true;
+    lastReinitAttempt = now;
     const externalApi = detectExternalApi(config);
     if (!externalApi.apiUrl) {
         isReinitInProgress = false;
@@ -73,20 +198,19 @@ async function lazyReinit() {
     debug('[Hindsight] Attempting lazy re-initialization...');
     try {
         await checkExternalApiHealth(externalApi.apiUrl, externalApi.apiToken);
-        // 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);
         clientOptions = buildClientOptions(llmConfig, config, externalApi);
-        clientsByBankId.clear();
         banksWithMissionSet.clear();
         client = new HindsightClient(clientOptions);
-        const defaultBankId = deriveBankId(undefined, config);
-        client.setBankId(defaultBankId);
-        if (config.bankMission && !config.dynamicBankId) {
-            await client.setBankMission(config.bankMission);
+        if (config.bankMission && usesStaticBank(config)) {
+            const bankId = getStaticBankId(config);
+            try {
+                await scopeClient(client, bankId).setMission(config.bankMission);
+                banksWithMissionSet.add(bankId);
+            }
+            catch (err) {
+                log.warn(`could not set bank mission for ${bankId}: ${err instanceof Error ? err.message : err}`);
+            }
         }
         usingExternalApi = true;
         isInitialized = true;
@@ -109,54 +233,44 @@ if (typeof global !== 'undefined') {
             if (isInitialized) {
                 return;
             }
-            if (initPromise) {
-                try {
-                    await initPromise;
+            // If initPromise is null, it means service.start() hasn't been called yet
+            // (CLI mode, not gateway mode). Hooks should gracefully no-op.
+            if (!initPromise) {
+                if (currentPluginConfig) {
+                    log.warn('waitForReady called before service.start() — attempting lazy initialization fallback');
+                    await lazyReinit(currentPluginConfig);
+                    return;
                 }
-                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();
-                    }
+                log.warn('waitForReady called before service.start() — hooks will no-op (expected in CLI mode)');
+                return;
+            }
+            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.
-         * Derives the bank ID from the context for per-channel isolation.
-         * Also ensures the bank mission is set on first use.
+         * Get a bank-scoped client handle for a specific agent context.
+         * Derives the bank ID from the context for per-channel isolation and
+         * ensures the bank mission is set on first use.
          */
         getClientForContext: async (ctx) => {
-            if (!client) {
+            if (!client)
                 return null;
-            }
             const config = currentPluginConfig || {};
-            if (config.dynamicBankId === false) {
-                return client;
-            }
-            const bankId = deriveBankId(ctx, config);
-            let bankClient = clientsByBankId.get(bankId);
-            if (!bankClient) {
-                if (!clientOptions) {
-                    return null;
-                }
-                bankClient = new HindsightClient(clientOptions);
-                bankClient.setBankId(bankId);
-                clientsByBankId.set(bankId, bankClient);
-                if (clientsByBankId.size > MAX_TRACKED_BANK_CLIENTS) {
-                    const oldestKey = clientsByBankId.keys().next().value;
-                    if (oldestKey) {
-                        clientsByBankId.delete(oldestKey);
-                        banksWithMissionSet.delete(oldestKey);
-                    }
-                }
-            }
-            // Set bank mission on first use of this bank (if configured)
-            if (config.bankMission && config.dynamicBankId && !banksWithMissionSet.has(bankId)) {
+            const bankId = usesStaticBank(config) ? getStaticBankId(config) : deriveBankId(ctx, config);
+            const scoped = scopeClient(client, bankId);
+            // Set bank mission on first use of this bank (if configured).
+            if (config.bankMission && !banksWithMissionSet.has(bankId)) {
                 try {
-                    await bankClient.setBankMission(config.bankMission);
+                    await scoped.setMission(config.bankMission);
                     banksWithMissionSet.add(bankId);
                     debug(`[Hindsight] Set mission for new bank: ${bankId}`);
                 }
@@ -165,7 +279,7 @@ if (typeof global !== 'undefined') {
                     log.warn(`could not set bank mission for ${bankId}: ${error}`);
                 }
             }
-            return bankClient;
+            return scoped;
         },
         getPluginConfig: () => currentPluginConfig,
     };
@@ -175,6 +289,24 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Default bank name (fallback when channel context not available)
 const DEFAULT_BANK_NAME = 'openclaw';
+function getConfiguredBankId(pluginConfig) {
+    if (typeof pluginConfig.bankId !== 'string') {
+        return undefined;
+    }
+    const trimmed = pluginConfig.bankId.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function usesStaticBank(pluginConfig) {
+    return pluginConfig.dynamicBankId === false;
+}
+function getDefaultBankId(pluginConfig) {
+    return pluginConfig.bankIdPrefix ? `${pluginConfig.bankIdPrefix}-${DEFAULT_BANK_NAME}` : DEFAULT_BANK_NAME;
+}
+function getStaticBankId(pluginConfig) {
+    const configuredBankId = getConfiguredBankId(pluginConfig);
+    const baseBankId = configuredBankId || DEFAULT_BANK_NAME;
+    return pluginConfig.bankIdPrefix ? `${pluginConfig.bankIdPrefix}-${baseBankId}` : baseBankId;
+}
 /**
  * Strip plugin-injected memory tags from content to prevent retain feedback loop.
  * Removes <hindsight_memories> and <relevant_memories> blocks that were injected
@@ -370,6 +502,21 @@ export function truncateRecallQuery(query, latestQuery, maxChars) {
  * Format: "agent:{agentId}:{provider}:{channelType}:{channelId}[:{extra}]"
  * Example: "agent:c0der:telegram:group:-1003825475854:topic:42"
  */
+// Some OpenClaw hook contexts populate `ctx.channelId` with the provider name
+// (e.g. "discord") instead of the actual channel ID. Treat those as missing so
+// we fall through to the sessionKey-derived channel. See issue #854.
+const PROVIDER_CHANNEL_ID_TOKENS = new Set([
+    'discord', 'telegram', 'slack', 'matrix', 'whatsapp', 'signal', 'messenger', 'sms', 'email', 'web', 'cli',
+]);
+function sanitizeChannelId(channelId, provider) {
+    if (!channelId)
+        return undefined;
+    if (provider && channelId === provider)
+        return undefined;
+    if (PROVIDER_CHANNEL_ID_TOKENS.has(channelId.toLowerCase()))
+        return undefined;
+    return channelId;
+}
 function parseSessionKey(sessionKey) {
     const parts = sessionKey.split(':');
     if (parts.length < 5 || parts[0] !== 'agent')
@@ -384,11 +531,11 @@ function parseSessionKey(sessionKey) {
 }
 export function deriveBankId(ctx, pluginConfig) {
     if (pluginConfig.dynamicBankId === false) {
-        return pluginConfig.bankIdPrefix ? `${pluginConfig.bankIdPrefix}-openclaw` : 'openclaw';
+        return getStaticBankId(pluginConfig);
     }
     // When no context is available, fall back to the static default bank.
     if (!ctx) {
-        return pluginConfig.bankIdPrefix ? `${pluginConfig.bankIdPrefix}-openclaw` : 'openclaw';
+        return getDefaultBankId(pluginConfig);
     }
     const fields = pluginConfig.dynamicBankGranularity?.length ? pluginConfig.dynamicBankGranularity : ['agent', 'channel', 'user'];
     // Validate field names at runtime — typos silently produce 'unknown' segments
@@ -406,7 +553,7 @@ export function deriveBankId(ctx, pluginConfig) {
     }
     const fieldMap = {
         agent: ctx?.agentId || sessionParsed.agentId || 'default',
-        channel: ctx?.channelId || sessionParsed.channel || 'unknown',
+        channel: sanitizeChannelId(ctx?.channelId, ctx?.messageProvider || sessionParsed.provider) || sessionParsed.channel || 'unknown',
         user: ctx?.senderId || 'anonymous',
         provider: ctx?.messageProvider || sessionParsed.provider || 'unknown',
     };
@@ -428,85 +575,10 @@ export function formatMemories(results) {
     })
         .join('\n\n');
 }
-// Provider detection from standard env vars
-const PROVIDER_DETECTION = [
-    { name: 'openai', keyEnv: 'OPENAI_API_KEY' },
-    { name: 'anthropic', keyEnv: 'ANTHROPIC_API_KEY' },
-    { name: 'gemini', keyEnv: 'GEMINI_API_KEY' },
-    { name: 'groq', keyEnv: 'GROQ_API_KEY' },
-    { name: 'ollama', keyEnv: '' },
-    { name: 'openai-codex', keyEnv: '' },
-    { name: 'claude-code', keyEnv: '' },
-];
-function detectLLMConfig(pluginConfig) {
-    // Override values from HINDSIGHT_API_LLM_* env vars (highest priority)
-    const overrideProvider = process.env.HINDSIGHT_API_LLM_PROVIDER;
-    const overrideModel = process.env.HINDSIGHT_API_LLM_MODEL;
-    const overrideKey = process.env.HINDSIGHT_API_LLM_API_KEY;
-    const overrideBaseUrl = process.env.HINDSIGHT_API_LLM_BASE_URL;
-    // Priority 1: If provider is explicitly set via env var, use that
-    if (overrideProvider) {
-        // Providers that don't require an API key (use OAuth or local models)
-        const noKeyRequired = ['ollama', 'openai-codex', 'claude-code'];
-        if (!overrideKey && !noKeyRequired.includes(overrideProvider)) {
-            throw new Error(`HINDSIGHT_API_LLM_PROVIDER is set to "${overrideProvider}" but HINDSIGHT_API_LLM_API_KEY is not set.\n` +
-                `Please set: export HINDSIGHT_API_LLM_API_KEY=your-api-key`);
-        }
-        return {
-            provider: overrideProvider,
-            apiKey: overrideKey || '',
-            model: overrideModel,
-            baseUrl: overrideBaseUrl,
-            source: 'HINDSIGHT_API_LLM_PROVIDER override',
-        };
-    }
-    // Priority 2: Plugin config llmProvider/llmModel
-    if (pluginConfig?.llmProvider) {
-        const providerInfo = PROVIDER_DETECTION.find(p => p.name === pluginConfig.llmProvider);
-        // Resolve API key: llmApiKeyEnv > provider's standard keyEnv
-        let apiKey = '';
-        if (pluginConfig.llmApiKeyEnv) {
-            apiKey = process.env[pluginConfig.llmApiKeyEnv] || '';
-        }
-        else if (providerInfo?.keyEnv) {
-            apiKey = process.env[providerInfo.keyEnv] || '';
-        }
-        // Providers that don't require an API key (use OAuth or local models)
-        const noKeyRequired = ['ollama', 'openai-codex', 'claude-code'];
-        if (!apiKey && !noKeyRequired.includes(pluginConfig.llmProvider)) {
-            const keySource = pluginConfig.llmApiKeyEnv || providerInfo?.keyEnv || 'unknown';
-            throw new Error(`Plugin config llmProvider is set to "${pluginConfig.llmProvider}" but no API key found.\n` +
-                `Expected env var: ${keySource}\n` +
-                `Set the env var or use llmApiKeyEnv in plugin config to specify a custom env var name.`);
-        }
-        return {
-            provider: pluginConfig.llmProvider,
-            apiKey,
-            model: pluginConfig.llmModel || overrideModel,
-            baseUrl: overrideBaseUrl,
-            source: 'plugin config',
-        };
-    }
-    // Priority 3: Auto-detect from standard provider env vars
-    for (const providerInfo of PROVIDER_DETECTION) {
-        const apiKey = providerInfo.keyEnv ? process.env[providerInfo.keyEnv] : '';
-        // Skip providers that don't use API keys in auto-detection (must be explicitly requested)
-        const noKeyRequired = ['ollama', 'openai-codex', 'claude-code'];
-        if (noKeyRequired.includes(providerInfo.name)) {
-            continue;
-        }
-        if (apiKey) {
-            return {
-                provider: providerInfo.name,
-                apiKey,
-                model: overrideModel,
-                baseUrl: overrideBaseUrl,
-                source: `auto-detected from ${providerInfo.keyEnv}`,
-            };
-        }
-    }
-    // No configuration found - show helpful error
-    // Allow empty LLM config if using external Hindsight API (server handles LLM)
+// Providers that authenticate via OAuth or run locally — no API key needed.
+const NO_KEY_REQUIRED_PROVIDERS = new Set(['ollama', 'openai-codex', 'claude-code']);
+export function detectLLMConfig(pluginConfig) {
+    // External API mode: the daemon handles LLM credentials, plugin doesn't need them.
     const externalApiCheck = detectExternalApi(pluginConfig);
     if (externalApiCheck.apiUrl) {
         return {
@@ -517,42 +589,54 @@ function detectLLMConfig(pluginConfig) {
             source: 'external-api-mode-no-llm',
         };
     }
-    throw new Error(`No LLM configuration found for Hindsight memory plugin.\n\n` +
-        `Option 1: Set a standard provider API key (auto-detect):\n` +
-        `  export OPENAI_API_KEY=sk-your-key\n` +
-        `  export ANTHROPIC_API_KEY=your-key\n` +
-        `  export GEMINI_API_KEY=your-key\n` +
-        `  export GROQ_API_KEY=your-key\n\n` +
-        `Option 2: Use Codex or Claude Code (no API key needed):\n` +
-        `  export HINDSIGHT_API_LLM_PROVIDER=openai-codex    # Requires 'codex auth login'\n` +
-        `  export HINDSIGHT_API_LLM_PROVIDER=claude-code     # Requires Claude Code CLI\n\n` +
-        `Option 3: Set llmProvider in openclaw.json plugin config:\n` +
-        `  "llmProvider": "openai"\n\n` +
-        `Option 4: Override with Hindsight-specific env vars:\n` +
-        `  export HINDSIGHT_API_LLM_PROVIDER=openai\n` +
-        `  export HINDSIGHT_API_LLM_API_KEY=sk-your-key\n` +
-        `  export HINDSIGHT_API_LLM_BASE_URL=https://openrouter.ai/api/v1  # Optional\n\n` +
-        `The model will be selected automatically by Hindsight. To override: export HINDSIGHT_API_LLM_MODEL=your-model`);
+    const provider = pluginConfig?.llmProvider;
+    if (!provider) {
+        throw new Error(`No LLM provider configured for the Hindsight memory plugin.\n\n` +
+            `Set the provider via 'openclaw config set':\n` +
+            `  openclaw config set plugins.entries.hindsight-openclaw.config.llmProvider openai\n\n` +
+            `For providers that need an API key, configure it as a SecretRef so the value\n` +
+            `is read from an env var (or file/exec source) at runtime instead of stored in plain text:\n` +
+            `  openclaw config set plugins.entries.hindsight-openclaw.config.llmApiKey \\\n` +
+            `      --ref-source env --ref-provider default --ref-id OPENAI_API_KEY\n\n` +
+            `Providers that don't need an API key: ${[...NO_KEY_REQUIRED_PROVIDERS].join(', ')}.\n` +
+            `Or point the plugin at an external Hindsight API by setting hindsightApiUrl instead.`);
+    }
+    const apiKey = pluginConfig?.llmApiKey ?? '';
+    if (!apiKey && !NO_KEY_REQUIRED_PROVIDERS.has(provider)) {
+        throw new Error(`llmProvider is set to "${provider}" but llmApiKey is empty.\n\n` +
+            `Configure it via 'openclaw config set' as a SecretRef:\n` +
+            `  openclaw config set plugins.entries.hindsight-openclaw.config.llmApiKey \\\n` +
+            `      --ref-source env --ref-provider default --ref-id OPENAI_API_KEY`);
+    }
+    return {
+        provider,
+        apiKey,
+        model: pluginConfig?.llmModel,
+        baseUrl: pluginConfig?.llmBaseUrl,
+        source: 'plugin config',
+    };
 }
 /**
- * Detect external Hindsight API configuration.
- * Priority: env vars > plugin config
+ * Detect external Hindsight API configuration from plugin config.
  */
-function detectExternalApi(pluginConfig) {
-    const apiUrl = process.env.HINDSIGHT_EMBED_API_URL || pluginConfig?.hindsightApiUrl || null;
-    const apiToken = process.env.HINDSIGHT_EMBED_API_TOKEN || pluginConfig?.hindsightApiToken || null;
-    return { apiUrl, apiToken };
+export function detectExternalApi(pluginConfig) {
+    return {
+        apiUrl: pluginConfig?.hindsightApiUrl ?? null,
+        apiToken: pluginConfig?.hindsightApiToken ?? null,
+    };
 }
 /**
- * Build HindsightClientOptions from LLM config, plugin config, and external API settings.
+ * Build HindsightClientOptions for the generated hindsight-client. In
+ * external-API mode we use the configured URL/token; in local daemon mode
+ * the caller overrides with the daemon's base URL after start().
+ * The llmConfig parameter is currently only consumed by the daemon manager
+ * (via env vars); it's kept on the client builder signature so callers
+ * don't need to branch and so future features can forward it.
  */
-function buildClientOptions(llmConfig, pluginCfg, externalApi) {
+export function buildClientOptions(_llmConfig, _pluginCfg, externalApi) {
     return {
-        llmModel: llmConfig.model,
-        embedVersion: pluginCfg.embedVersion,
-        embedPackagePath: pluginCfg.embedPackagePath,
-        apiUrl: externalApi.apiUrl ?? undefined,
-        apiToken: externalApi.apiToken ?? undefined,
+        baseUrl: externalApi.apiUrl ?? '',
+        apiKey: externalApi.apiToken ?? undefined,
     };
 }
 /**
@@ -600,14 +684,20 @@ function getPluginConfig(api) {
         embedPackagePath: config.embedPackagePath,
         llmProvider: config.llmProvider,
         llmModel: config.llmModel,
-        llmApiKeyEnv: config.llmApiKeyEnv,
+        llmApiKey: config.llmApiKey,
+        llmBaseUrl: config.llmBaseUrl,
         hindsightApiUrl: config.hindsightApiUrl,
         hindsightApiToken: config.hindsightApiToken,
         apiPort: config.apiPort || 9077,
         // Dynamic bank ID options (default: enabled)
         dynamicBankId: config.dynamicBankId !== false,
+        bankId: typeof config.bankId === 'string' && config.bankId.trim().length > 0 ? config.bankId.trim() : undefined,
         bankIdPrefix: config.bankIdPrefix,
-        excludeProviders: Array.isArray(config.excludeProviders) ? config.excludeProviders : [],
+        retainTags: Array.isArray(config.retainTags) ? config.retainTags.filter((tag) => typeof tag === 'string') : undefined,
+        retainSource: typeof config.retainSource === 'string' && config.retainSource.trim().length > 0 ? config.retainSource.trim() : undefined,
+        excludeProviders: Array.isArray(config.excludeProviders)
+            ? Array.from(new Set(['heartbeat', ...config.excludeProviders.filter((provider) => typeof provider === 'string')]))
+            : ['heartbeat'],
         autoRecall: config.autoRecall !== false, // Default: true (on) — backward compatible
         dynamicBankGranularity: Array.isArray(config.dynamicBankGranularity) ? config.dynamicBankGranularity : undefined,
         autoRetain: config.autoRetain !== false, // Default: true
@@ -626,13 +716,17 @@ function getPluginConfig(api) {
             : DEFAULT_RECALL_PROMPT_PREAMBLE,
         recallInjectionPosition: typeof config.recallInjectionPosition === 'string' && ['prepend', 'append', 'user'].includes(config.recallInjectionPosition) ? config.recallInjectionPosition : undefined,
         recallTimeoutMs: typeof config.recallTimeoutMs === 'number' && config.recallTimeoutMs >= 1000 ? config.recallTimeoutMs : undefined,
+        ignoreSessionPatterns: Array.isArray(config.ignoreSessionPatterns) ? config.ignoreSessionPatterns : [],
+        statelessSessionPatterns: Array.isArray(config.statelessSessionPatterns) ? config.statelessSessionPatterns : [],
+        skipStatelessSessions: config.skipStatelessSessions !== false,
         debug: config.debug ?? false,
     };
 }
 export default function (api) {
     try {
+        log.info('plugin entry invoked');
         debug('[Hindsight] Plugin loading...');
-        // Get plugin config first (needed for LLM detection and debug flag)
+        // Get plugin config first (needed for debug flag and service registration)
         const pluginConfig = getPluginConfig(api);
         // If logLevel is 'debug', also enable legacy debug flag
         debugEnabled = pluginConfig.debug ?? (pluginConfig.logLevel === 'debug');
@@ -645,136 +739,179 @@ export default function (api) {
         });
         // Store config globally for bank ID derivation in hooks
         currentPluginConfig = pluginConfig;
-        // Detect LLM configuration (env vars > plugin config > auto-detect)
-        debug('[Hindsight] Detecting LLM config...');
-        const llmConfig = detectLLMConfig(pluginConfig);
-        const baseUrlInfo = llmConfig.baseUrl ? `, base URL: ${llmConfig.baseUrl}` : '';
-        const modelInfo = llmConfig.model || 'default';
-        if (llmConfig.provider === 'ollama') {
-            debug(`[Hindsight] ✓ Using provider: ${llmConfig.provider}, model: ${modelInfo} (${llmConfig.source})`);
-        }
-        else {
-            debug(`[Hindsight] ✓ Using provider: ${llmConfig.provider}, model: ${modelInfo} (${llmConfig.source}${baseUrlInfo})`);
-        }
-        if (pluginConfig.bankMission) {
-            debug(`[Hindsight] Custom bank mission configured: "${pluginConfig.bankMission.substring(0, 50)}..."`);
-        }
-        // Log dynamic bank ID mode
-        if (pluginConfig.dynamicBankId) {
-            const prefixInfo = pluginConfig.bankIdPrefix ? ` (prefix: ${pluginConfig.bankIdPrefix})` : '';
-            debug(`[Hindsight] ✓ Dynamic bank IDs enabled${prefixInfo} - each channel gets isolated memory`);
-        }
-        else {
-            debug(`[Hindsight] Dynamic bank IDs disabled - using static bank: ${DEFAULT_BANK_NAME}`);
-        }
-        // Detect external API mode
-        const externalApi = detectExternalApi(pluginConfig);
-        // Get API port from config (default: 9077)
-        const apiPort = pluginConfig.apiPort || 9077;
-        if (externalApi.apiUrl) {
-            // External API mode - skip local daemon
-            usingExternalApi = true;
-            debug(`[Hindsight] ✓ Using external API: ${externalApi.apiUrl}`);
-            // Set env vars so CLI commands (uvx hindsight-embed) use external API
-            process.env.HINDSIGHT_EMBED_API_URL = externalApi.apiUrl;
-            if (externalApi.apiToken) {
-                process.env.HINDSIGHT_EMBED_API_TOKEN = externalApi.apiToken;
-                debug('[Hindsight] API token configured');
-            }
-        }
-        else {
-            debug(`[Hindsight] Daemon idle timeout: ${pluginConfig.daemonIdleTimeout}s (0 = never timeout)`);
-            debug(`[Hindsight] API Port: ${apiPort}`);
-        }
-        // Initialize in background (non-blocking)
-        debug('[Hindsight] Starting initialization in background...');
-        initPromise = (async () => {
-            try {
-                if (usingExternalApi && externalApi.apiUrl) {
-                    // External API mode - check health, skip daemon startup
-                    debug('[Hindsight] External API mode - skipping local daemon...');
-                    await checkExternalApiHealth(externalApi.apiUrl, externalApi.apiToken);
-                    // Initialize client with direct HTTP mode
-                    debug('[Hindsight] Creating HindsightClient (HTTP mode)...');
-                    clientOptions = buildClientOptions(llmConfig, pluginConfig, externalApi);
-                    clientsByBankId.clear();
-                    banksWithMissionSet.clear();
-                    client = new HindsightClient(clientOptions);
-                    // Set default bank (will be overridden per-request when dynamic bank IDs are enabled)
-                    const defaultBankId = deriveBankId(undefined, pluginConfig);
-                    debug(`[Hindsight] Default bank: ${defaultBankId}`);
-                    client.setBankId(defaultBankId);
-                    // Note: Bank mission will be set per-bank when dynamic bank IDs are enabled
-                    // For now, set it on the default bank
-                    if (pluginConfig.bankMission && !pluginConfig.dynamicBankId) {
-                        debug(`[Hindsight] Setting bank mission...`);
-                        await client.setBankMission(pluginConfig.bankMission);
-                    }
-                    if (!isInitialized) {
-                        const mode = 'external API';
-                        const autoRecall = pluginConfig.autoRecall !== false;
-                        const autoRetain = pluginConfig.autoRetain !== false;
-                        log.info(`initialized (mode: ${mode}, bank: ${defaultBankId}, autoRecall: ${autoRecall}, autoRetain: ${autoRetain})`);
-                    }
-                    isInitialized = true;
-                    debug('[Hindsight] ✓ Ready (external API mode)');
-                }
-                else {
-                    // Local daemon mode - start hindsight-embed daemon
-                    debug('[Hindsight] Creating HindsightEmbedManager...');
-                    embedManager = new HindsightEmbedManager(apiPort, llmConfig.provider || "", llmConfig.apiKey || "", llmConfig.model, llmConfig.baseUrl, pluginConfig.daemonIdleTimeout, pluginConfig.embedVersion, pluginConfig.embedPackagePath);
-                    // Start the embedded server
-                    debug('[Hindsight] Starting embedded server...');
-                    await embedManager.start();
-                    // Initialize client (local daemon mode — no apiUrl)
-                    debug('[Hindsight] Creating HindsightClient (subprocess mode)...');
-                    clientOptions = buildClientOptions(llmConfig, pluginConfig, { apiUrl: null, apiToken: null });
-                    clientsByBankId.clear();
-                    banksWithMissionSet.clear();
-                    client = new HindsightClient(clientOptions);
-                    // Set default bank (will be overridden per-request when dynamic bank IDs are enabled)
-                    const defaultBankId = deriveBankId(undefined, pluginConfig);
-                    debug(`[Hindsight] Default bank: ${defaultBankId}`);
-                    client.setBankId(defaultBankId);
-                    // Note: Bank mission will be set per-bank when dynamic bank IDs are enabled
-                    // For now, set it on the default bank
-                    if (pluginConfig.bankMission && !pluginConfig.dynamicBankId) {
-                        debug(`[Hindsight] Setting bank mission...`);
-                        await client.setBankMission(pluginConfig.bankMission);
-                    }
-                    if (!isInitialized) {
-                        const mode = 'local daemon';
-                        const autoRecall = pluginConfig.autoRecall !== false;
-                        const autoRetain = pluginConfig.autoRetain !== false;
-                        log.info(`initialized (mode: ${mode}, bank: ${defaultBankId}, autoRecall: ${autoRecall}, autoRetain: ${autoRetain})`);
-                    }
-                    isInitialized = true;
-                    debug('[Hindsight] ✓ Ready');
-                }
-            }
-            catch (error) {
-                log.error('initialization error', error);
-                throw error;
-            }
-        })();
-        // Suppress unhandled rejection — service.start() will await and handle errors
-        initPromise.catch(() => { });
+        debug('[Hindsight] Plugin loaded successfully (deferred heavy init to gateway start)');
         // Register background service for cleanup
+        // IMPORTANT: Heavy initialization (LLM detection, daemon start, API health checks)
+        // happens in service.start() which is ONLY called on gateway start,
+        // not on every CLI command.
         debug('[Hindsight] Registering service...');
+        log.info('registering plugin service');
         api.registerService({
             id: 'hindsight-memory',
             async start() {
-                debug('[Hindsight] Service start called...');
-                // Wait for background init if still pending
-                if (initPromise) {
+                log.info('service.start invoked');
+                debug('[Hindsight] Service start called - beginning heavy initialization...');
+                // Detect LLM configuration (env vars > plugin config > auto-detect)
+                debug('[Hindsight] Detecting LLM config...');
+                const llmConfig = detectLLMConfig(pluginConfig);
+                const baseUrlInfo = llmConfig.baseUrl ? `, base URL: ${llmConfig.baseUrl}` : '';
+                const modelInfo = llmConfig.model || 'default';
+                if (llmConfig.provider === 'ollama') {
+                    debug(`[Hindsight] ✓ Using provider: ${llmConfig.provider}, model: ${modelInfo} (${llmConfig.source})`);
+                }
+                else {
+                    debug(`[Hindsight] ✓ Using provider: ${llmConfig.provider}, model: ${modelInfo} (${llmConfig.source}${baseUrlInfo})`);
+                }
+                if (pluginConfig.bankMission) {
+                    debug(`[Hindsight] Custom bank mission configured: "${pluginConfig.bankMission.substring(0, 50)}..."`);
+                }
+                // Log bank ID mode
+                if (pluginConfig.dynamicBankId) {
+                    const prefixInfo = pluginConfig.bankIdPrefix ? ` (prefix: ${pluginConfig.bankIdPrefix})` : '';
+                    debug(`[Hindsight] ✓ Dynamic bank IDs enabled${prefixInfo} - each channel gets isolated memory`);
+                }
+                else {
+                    const sourceInfo = getConfiguredBankId(pluginConfig) ? 'configured' : 'default';
+                    debug(`[Hindsight] Dynamic bank IDs disabled - using ${sourceInfo} static bank: ${getStaticBankId(pluginConfig)}`);
+                }
+                // Detect external API mode
+                const externalApi = detectExternalApi(pluginConfig);
+                // Get API port from config (default: 9077)
+                const apiPort = pluginConfig.apiPort || 9077;
+                if (externalApi.apiUrl) {
+                    // External API mode - skip local daemon
+                    usingExternalApi = true;
+                    debug(`[Hindsight] ✓ Using external API: ${externalApi.apiUrl}`);
+                    // Initialize retain queue (external API mode only)
                     try {
-                        await initPromise;
+                        const queueDir = pluginConfig.retainQueuePath
+                            ? dirname(pluginConfig.retainQueuePath)
+                            : join(homedir(), '.openclaw', 'data');
+                        mkdirSync(queueDir, { recursive: true });
+                        const queuePath = pluginConfig.retainQueuePath || join(queueDir, 'hindsight-retain-queue.jsonl');
+                        const queueFlushInterval = pluginConfig.retainQueueFlushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+                        const queueMaxAge = pluginConfig.retainQueueMaxAgeMs ?? -1;
+                        retainQueue = new RetainQueue({ filePath: queuePath, maxAgeMs: queueMaxAge });
+                        const pending = retainQueue.size();
+                        if (pending > 0) {
+                            log.info(`retain queue: ${pending} items pending from previous session, will flush shortly`);
+                        }
+                        debug(`[Hindsight] Retain queue initialized: ${queuePath}`);
+                        // Periodic flush timer
+                        if (queueFlushInterval > 0) {
+                            retainQueueFlushTimer = setInterval(flushRetainQueue, queueFlushInterval);
+                            retainQueueFlushTimer.unref?.();
+                        }
                     }
                     catch (error) {
-                        log.error('initial initialization failed', error);
-                        // Continue to health check below
+                        log.warn(`could not initialize retain queue: ${error}`);
+                    }
+                    if (externalApi.apiToken) {
+                        debug('[Hindsight] API token configured');
                     }
                 }
+                else {
+                    debug(`[Hindsight] Daemon idle timeout: ${pluginConfig.daemonIdleTimeout}s (0 = never timeout)`);
+                    debug(`[Hindsight] API Port: ${apiPort}`);
+                }
+                // Initialize (runs synchronously in service.start())
+                debug('[Hindsight] Starting initialization...');
+                initPromise = (async () => {
+                    try {
+                        if (usingExternalApi && externalApi.apiUrl) {
+                            // External API mode - check health, skip daemon startup
+                            debug('[Hindsight] External API mode - skipping local daemon...');
+                            await checkExternalApiHealth(externalApi.apiUrl, externalApi.apiToken);
+                            // Initialize client for external API
+                            debug('[Hindsight] Creating HindsightClient (external API)...');
+                            clientOptions = buildClientOptions(llmConfig, pluginConfig, externalApi);
+                            banksWithMissionSet.clear();
+                            client = new HindsightClient(clientOptions);
+                            const defaultBankId = deriveBankId(undefined, pluginConfig);
+                            debug(`[Hindsight] Default bank: ${defaultBankId}`);
+                            // Note: Bank mission will be set per-bank when dynamic bank IDs are enabled
+                            // For now, set it on the static default bank only.
+                            if (pluginConfig.bankMission && usesStaticBank(pluginConfig)) {
+                                debug(`[Hindsight] Setting bank mission...`);
+                                try {
+                                    await scopeClient(client, defaultBankId).setMission(pluginConfig.bankMission);
+                                    banksWithMissionSet.add(defaultBankId);
+                                }
+                                catch (err) {
+                                    log.warn(`could not set bank mission for ${defaultBankId}: ${err instanceof Error ? err.message : err}`);
+                                }
+                            }
+                            if (!isInitialized) {
+                                const mode = 'external API';
+                                const autoRecall = pluginConfig.autoRecall !== false;
+                                const autoRetain = pluginConfig.autoRetain !== false;
+                                log.info(`initialized (mode: ${mode}, bank: ${defaultBankId}, autoRecall: ${autoRecall}, autoRetain: ${autoRetain})`);
+                            }
+                            isInitialized = true;
+                            debug('[Hindsight] ✓ Ready (external API mode)');
+                        }
+                        else {
+                            // Local daemon mode - start hindsight-embed daemon
+                            debug('[Hindsight] Creating HindsightServer...');
+                            hindsightServer = new HindsightServer({
+                                profile: 'openclaw',
+                                port: apiPort,
+                                embedVersion: pluginConfig.embedVersion,
+                                embedPackagePath: pluginConfig.embedPackagePath,
+                                env: {
+                                    HINDSIGHT_API_LLM_PROVIDER: llmConfig.provider || '',
+                                    HINDSIGHT_API_LLM_API_KEY: llmConfig.apiKey || '',
+                                    HINDSIGHT_API_LLM_MODEL: llmConfig.model,
+                                    HINDSIGHT_API_LLM_BASE_URL: llmConfig.baseUrl,
+                                    HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT: String(pluginConfig.daemonIdleTimeout ?? 0),
+                                },
+                                logger: embedLogger,
+                            });
+                            // Start the embedded server
+                            debug('[Hindsight] Starting embedded server...');
+                            await hindsightServer.start();
+                            // Initialize client pointed at the local daemon URL
+                            debug('[Hindsight] Creating HindsightClient (local daemon)...');
+                            clientOptions = { baseUrl: hindsightServer.getBaseUrl() };
+                            banksWithMissionSet.clear();
+                            client = new HindsightClient(clientOptions);
+                            const defaultBankId = deriveBankId(undefined, pluginConfig);
+                            debug(`[Hindsight] Default bank: ${defaultBankId}`);
+                            // Note: Bank mission will be set per-bank when dynamic bank IDs are enabled
+                            // For now, set it on the static default bank only.
+                            if (pluginConfig.bankMission && usesStaticBank(pluginConfig)) {
+                                debug(`[Hindsight] Setting bank mission...`);
+                                try {
+                                    await scopeClient(client, defaultBankId).setMission(pluginConfig.bankMission);
+                                    banksWithMissionSet.add(defaultBankId);
+                                }
+                                catch (err) {
+                                    log.warn(`could not set bank mission for ${defaultBankId}: ${err instanceof Error ? err.message : err}`);
+                                }
+                            }
+                            if (!isInitialized) {
+                                const mode = 'local daemon';
+                                const autoRecall = pluginConfig.autoRecall !== false;
+                                const autoRetain = pluginConfig.autoRetain !== false;
+                                log.info(`initialized (mode: ${mode}, bank: ${defaultBankId}, autoRecall: ${autoRecall}, autoRetain: ${autoRetain})`);
+                            }
+                            isInitialized = true;
+                            debug('[Hindsight] ✓ Ready');
+                        }
+                    }
+                    catch (error) {
+                        log.error('initialization error', error);
+                        throw error;
+                    }
+                })();
+                // Wait for initialization to complete
+                try {
+                    await initPromise;
+                }
+                catch (error) {
+                    log.error('initial initialization failed', error);
+                    // Continue to health check below
+                }
                 // External API mode: check external API health
                 if (usingExternalApi) {
                     const externalApi = detectExternalApi(pluginConfig);
@@ -789,7 +926,6 @@ export default function (api) {
                             // Reset state for reinitialization attempt
                             client = null;
                             clientOptions = null;
-                            clientsByBankId.clear();
                             banksWithMissionSet.clear();
                             isInitialized = false;
                         }
@@ -797,18 +933,17 @@ export default function (api) {
                 }
                 else {
                     // Local daemon mode: check daemon health (handles SIGUSR1 restart case)
-                    if (embedManager && isInitialized) {
-                        const healthy = await embedManager.checkHealth();
+                    if (hindsightServer && isInitialized) {
+                        const healthy = await hindsightServer.checkHealth();
                         if (healthy) {
                             debug('[Hindsight] Daemon is healthy');
                             return;
                         }
                         debug('[Hindsight] Daemon is not responding - reinitializing...');
                         // Reset state for reinitialization
-                        embedManager = null;
+                        hindsightServer = null;
                         client = null;
                         clientOptions = null;
-                        clientsByBankId.clear();
                         banksWithMissionSet.clear();
                         isInitialized = false;
                     }
@@ -824,35 +959,52 @@ export default function (api) {
                     if (externalApi.apiUrl) {
                         // External API mode
                         usingExternalApi = true;
-                        process.env.HINDSIGHT_EMBED_API_URL = externalApi.apiUrl;
-                        if (externalApi.apiToken) {
-                            process.env.HINDSIGHT_EMBED_API_TOKEN = externalApi.apiToken;
-                        }
                         await checkExternalApiHealth(externalApi.apiUrl, externalApi.apiToken);
                         clientOptions = buildClientOptions(llmConfig, reinitPluginConfig, externalApi);
-                        clientsByBankId.clear();
                         banksWithMissionSet.clear();
                         client = new HindsightClient(clientOptions);
                         const defaultBankId = deriveBankId(undefined, reinitPluginConfig);
-                        client.setBankId(defaultBankId);
-                        if (reinitPluginConfig.bankMission && !reinitPluginConfig.dynamicBankId) {
-                            await client.setBankMission(reinitPluginConfig.bankMission);
+                        if (reinitPluginConfig.bankMission && usesStaticBank(reinitPluginConfig)) {
+                            try {
+                                await scopeClient(client, defaultBankId).setMission(reinitPluginConfig.bankMission);
+                                banksWithMissionSet.add(defaultBankId);
+                            }
+                            catch (err) {
+                                log.warn(`could not set bank mission for ${defaultBankId}: ${err instanceof Error ? err.message : err}`);
+                            }
                         }
                         isInitialized = true;
                         debug('[Hindsight] Reinitialization complete (external API mode)');
                     }
                     else {
                         // Local daemon mode
-                        embedManager = new HindsightEmbedManager(apiPort, llmConfig.provider || "", llmConfig.apiKey || "", llmConfig.model, llmConfig.baseUrl, reinitPluginConfig.daemonIdleTimeout, reinitPluginConfig.embedVersion, reinitPluginConfig.embedPackagePath);
-                        await embedManager.start();
-                        clientOptions = buildClientOptions(llmConfig, reinitPluginConfig, { apiUrl: null, apiToken: null });
-                        clientsByBankId.clear();
+                        hindsightServer = new HindsightServer({
+                            profile: 'openclaw',
+                            port: apiPort,
+                            embedVersion: reinitPluginConfig.embedVersion,
+                            embedPackagePath: reinitPluginConfig.embedPackagePath,
+                            env: {
+                                HINDSIGHT_API_LLM_PROVIDER: llmConfig.provider || '',
+                                HINDSIGHT_API_LLM_API_KEY: llmConfig.apiKey || '',
+                                HINDSIGHT_API_LLM_MODEL: llmConfig.model,
+                                HINDSIGHT_API_LLM_BASE_URL: llmConfig.baseUrl,
+                                HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT: String(reinitPluginConfig.daemonIdleTimeout ?? 0),
+                            },
+                            logger: embedLogger,
+                        });
+                        await hindsightServer.start();
+                        clientOptions = { baseUrl: hindsightServer.getBaseUrl() };
                         banksWithMissionSet.clear();
                         client = new HindsightClient(clientOptions);
                         const defaultBankId = deriveBankId(undefined, reinitPluginConfig);
-                        client.setBankId(defaultBankId);
-                        if (reinitPluginConfig.bankMission && !reinitPluginConfig.dynamicBankId) {
-                            await client.setBankMission(reinitPluginConfig.bankMission);
+                        if (reinitPluginConfig.bankMission && usesStaticBank(reinitPluginConfig)) {
+                            try {
+                                await scopeClient(client, defaultBankId).setMission(reinitPluginConfig.bankMission);
+                                banksWithMissionSet.add(defaultBankId);
+                            }
+                            catch (err) {
+                                log.warn(`could not set bank mission for ${defaultBankId}: ${err instanceof Error ? err.message : err}`);
+                            }
                         }
                         isInitialized = true;
                         debug('[Hindsight] Reinitialization complete');
@@ -863,13 +1015,25 @@ export default function (api) {
                 try {
                     debug('[Hindsight] Service stopping...');
                     // Only stop daemon if in local mode
-                    if (!usingExternalApi && embedManager) {
-                        await embedManager.stop();
-                        embedManager = null;
+                    if (!usingExternalApi && hindsightServer) {
+                        await hindsightServer.stop();
+                        hindsightServer = null;
+                    }
+                    // Close retain queue
+                    if (retainQueueFlushTimer) {
+                        clearInterval(retainQueueFlushTimer);
+                        retainQueueFlushTimer = null;
+                    }
+                    if (retainQueue) {
+                        const pending = retainQueue.size();
+                        if (pending > 0) {
+                            debug(`[Hindsight] Service stopping with ${pending} queued retains (will resume on next start)`);
+                        }
+                        retainQueue.close();
+                        retainQueue = null;
                     }
                     client = null;
                     clientOptions = null;
-                    clientsByBankId.clear();
                     banksWithMissionSet.clear();
                     isInitialized = false;
                     stopLogger();
@@ -883,12 +1047,13 @@ export default function (api) {
         });
         debug('[Hindsight] Plugin loaded successfully');
         // Register agent hooks for auto-recall and auto-retention
-        if (registeredApis.has(api)) {
-            debug('[Hindsight] Hooks already registered for this api instance, skipping duplicate registration');
+        if (hooksRegistered) {
+            debug('[Hindsight] Hooks already registered in this runtime, skipping duplicate hook registration');
             return;
         }
-        registeredApis.add(api);
+        hooksRegistered = true;
         debug('[Hindsight] Registering agent hooks...');
+        log.info('registering agent hooks');
         // Auto-recall: Inject relevant memories before agent processes the message
         // Hook signature: (event, ctx) where event has {prompt, messages?} and ctx has agent context
         api.on('before_prompt_build', async (event, ctx) => {
@@ -898,6 +1063,23 @@ export default function (api) {
                     debug(`[Hindsight] Skipping recall for excluded provider: ${ctx.messageProvider}`);
                     return;
                 }
+                // Session pattern filtering
+                const sessionKey = ctx?.sessionKey;
+                if (sessionKey) {
+                    const ignorePatterns = compileSessionPatterns(pluginConfig.ignoreSessionPatterns ?? []);
+                    if (ignorePatterns.length > 0 && matchesSessionPattern(sessionKey, ignorePatterns)) {
+                        debug(`[Hindsight] Skipping recall: session '${sessionKey}' matches ignoreSessionPatterns`);
+                        return;
+                    }
+                    const skipStateless = pluginConfig.skipStatelessSessions !== false;
+                    if (skipStateless) {
+                        const statelessPatterns = compileSessionPatterns(pluginConfig.statelessSessionPatterns ?? []);
+                        if (statelessPatterns.length > 0 && matchesSessionPattern(sessionKey, statelessPatterns)) {
+                            debug(`[Hindsight] Skipping recall: session '${sessionKey}' matches statelessSessionPatterns (skipStatelessSessions=true)`);
+                            return;
+                        }
+                    }
+                }
                 // Skip auto-recall when disabled (agent has its own recall tool)
                 if (!pluginConfig.autoRecall) {
                     debug('[Hindsight] Auto-recall disabled via config, skipping');
@@ -973,7 +1155,7 @@ export default function (api) {
                 }
                 else {
                     const recallTimeoutMs = pluginConfig.recallTimeoutMs ?? DEFAULT_RECALL_TIMEOUT_MS;
-                    recallPromise = client.recall({ query: prompt, max_tokens: pluginConfig.recallMaxTokens || 1024, budget: pluginConfig.recallBudget, types: pluginConfig.recallTypes }, recallTimeoutMs);
+                    recallPromise = client.recall({ query: prompt, maxTokens: pluginConfig.recallMaxTokens || 1024, budget: pluginConfig.recallBudget, types: pluginConfig.recallTypes }, recallTimeoutMs);
                     inflightRecalls.set(recallKey, recallPromise);
                     void recallPromise.catch(() => { }).finally(() => inflightRecalls.delete(recallKey));
                 }
@@ -1033,6 +1215,20 @@ ${memoriesFormatted}
                     debug(`[Hindsight] Skipping retain for excluded provider: ${effectiveCtx.messageProvider}`);
                     return;
                 }
+                // Session pattern filtering
+                const agentEndSessionKey = effectiveCtx?.sessionKey;
+                if (agentEndSessionKey) {
+                    const ignorePatterns = compileSessionPatterns(pluginConfig.ignoreSessionPatterns ?? []);
+                    if (ignorePatterns.length > 0 && matchesSessionPattern(agentEndSessionKey, ignorePatterns)) {
+                        debug(`[Hindsight] Skipping retain: session '${agentEndSessionKey}' matches ignoreSessionPatterns`);
+                        return;
+                    }
+                    const statelessPatterns = compileSessionPatterns(pluginConfig.statelessSessionPatterns ?? []);
+                    if (statelessPatterns.length > 0 && matchesSessionPattern(agentEndSessionKey, statelessPatterns)) {
+                        debug(`[Hindsight] Skipping retain: session '${agentEndSessionKey}' matches statelessSessionPatterns`);
+                        return;
+                    }
+                }
                 // Derive bank ID from context — enrich ctx.senderId from the session cache.
                 // event.messages in agent_end is clean history without OpenClaw's metadata blocks;
                 // the sender ID was captured during before_prompt_build where event.prompt has them.
@@ -1103,30 +1299,40 @@ ${memoriesFormatted}
                     log.warn('client not initialized, skipping retain');
                     return;
                 }
-                // Use unique document ID per conversation (sessionKey + timestamp)
-                // Static sessionKey (e.g. "agent:main:main") causes CASCADE delete of old memories
-                const documentId = `${effectiveCtx?.sessionKey || 'session'}-${Date.now()}`;
-                // Retain to Hindsight
-                debug(`[Hindsight] Retaining to bank ${bankId}, document: ${documentId}, chars: ${transcript.length}\n---\n${transcript.substring(0, 500)}${transcript.length > 500 ? '\n...(truncated)' : ''}\n---`);
-                await client.retain({
-                    content: transcript,
-                    document_id: documentId,
-                    metadata: {
-                        retained_at: new Date().toISOString(),
-                        message_count: String(messageCount),
-                        channel_type: effectiveCtx?.messageProvider,
-                        channel_id: effectiveCtx?.channelId,
-                        sender_id: effectiveCtx?.senderId,
-                    },
+                const retainNow = Date.now();
+                const retainRequest = buildRetainRequest(transcript, messageCount, effectiveCtxForRetain, pluginConfig, retainNow, {
+                    retentionScope: retainFullWindow ? 'window' : 'turn',
+                    windowTurns: retainFullWindow ? (pluginConfig.retainEveryNTurns ?? 1) + (pluginConfig.retainOverlapTurns ?? 0) : undefined,
                 });
-                log.trackRetain(bankId, messageCount);
-                debug(`[Hindsight] Retained ${messageCount} messages to bank ${bankId} for session ${documentId}`);
+                // Retain to Hindsight
+                debug(`[Hindsight] Retaining to bank ${bankId}, document: ${retainRequest.documentId}, chars: ${transcript.length}\n---\n${transcript.substring(0, 500)}${transcript.length > 500 ? '\n...(truncated)' : ''}\n---`);
+                try {
+                    await client.retain(retainRequest);
+                    log.trackRetain(bankId, messageCount);
+                    debug(`[Hindsight] Retained ${messageCount} messages to bank ${bankId} for session ${retainRequest.documentId}`);
+                    // After a successful retain, try flushing any queued items
+                    if (retainQueue && retainQueue.size() > 0) {
+                        flushRetainQueue().catch(() => { });
+                    }
+                }
+                catch (retainError) {
+                    // Queue the failed retain for later delivery (external API mode only)
+                    if (retainQueue) {
+                        retainQueue.enqueue(bankId, retainRequest, retainRequest.metadata);
+                        const pending = retainQueue.size();
+                        log.warn(`API unreachable — retain queued (${pending} pending, bank: ${bankId}): ${retainError instanceof Error ? retainError.message : retainError}`);
+                    }
+                    else {
+                        log.error('error retaining messages', retainError);
+                    }
+                }
             }
             catch (error) {
                 log.error('error retaining messages', error);
             }
         });
         debug('[Hindsight] Hooks registered');
+        log.info('agent hooks registered');
     }
     catch (error) {
         log.error('plugin loading error', error);
@@ -1137,6 +1343,68 @@ ${memoriesFormatted}
     }
 }
 // Export client getter for tools
+function sanitizeDocumentIdPart(value, fallback) {
+    const normalized = (value || '').trim();
+    if (!normalized)
+        return fallback;
+    return normalized
+        .replace(/[^a-zA-Z0-9:_-]+/g, '_')
+        .replace(/_+/g, '_')
+        .replace(/^_+|_+$/g, '') || fallback;
+}
+function getSessionDocumentBase(effectiveCtx) {
+    const sessionKeyPart = sanitizeDocumentIdPart(effectiveCtx?.sessionKey, 'session');
+    return `openclaw:${sessionKeyPart}`;
+}
+function nextDocumentSequence(effectiveCtx) {
+    const sequenceKey = effectiveCtx?.sessionKey || 'session';
+    const next = (documentSequenceBySession.get(sequenceKey) || 0) + 1;
+    documentSequenceBySession.set(sequenceKey, next);
+    if (documentSequenceBySession.size > MAX_TRACKED_SESSIONS) {
+        const oldestKey = documentSequenceBySession.keys().next().value;
+        if (oldestKey) {
+            documentSequenceBySession.delete(oldestKey);
+        }
+    }
+    return next;
+}
+function extractThreadId(channelId) {
+    if (!channelId)
+        return undefined;
+    const match = channelId.match(/(?:^|:)topic:([^:]+)$/);
+    return match?.[1];
+}
+export function buildRetainRequest(transcript, messageCount, effectiveCtx, pluginConfig, now = Date.now(), options) {
+    const parsedSession = effectiveCtx?.sessionKey ? parseSessionKey(effectiveCtx.sessionKey) : {};
+    const turnIndex = options?.turnIndex ?? nextDocumentSequence(effectiveCtx);
+    const retentionScope = options?.retentionScope || 'turn';
+    const documentBase = getSessionDocumentBase(effectiveCtx);
+    const documentKind = retentionScope === 'window' ? 'window' : 'turn';
+    const documentId = `${documentBase}:${documentKind}:${String(turnIndex).padStart(6, '0')}`;
+    const provider = effectiveCtx?.messageProvider || parsedSession.provider;
+    const channelId = sanitizeChannelId(effectiveCtx?.channelId, provider) || parsedSession.channel;
+    const threadId = extractThreadId(channelId);
+    return {
+        content: transcript,
+        documentId: documentId,
+        metadata: {
+            retained_at: new Date(now).toISOString(),
+            message_count: String(messageCount),
+            source: pluginConfig.retainSource || 'openclaw',
+            retention_scope: retentionScope,
+            turn_index: String(turnIndex),
+            session_key: effectiveCtx?.sessionKey,
+            agent_id: effectiveCtx?.agentId || parsedSession.agentId,
+            provider,
+            channel_type: effectiveCtx?.messageProvider,
+            channel_id: channelId,
+            thread_id: threadId,
+            sender_id: effectiveCtx?.senderId,
+            ...(options?.windowTurns !== undefined ? { window_turns: String(options.windowTurns) } : {}),
+        },
+        tags: pluginConfig.retainTags && pluginConfig.retainTags.length > 0 ? pluginConfig.retainTags : undefined,
+    };
+}
 export function prepareRetentionTranscript(messages, pluginConfig, retainFullWindow = false) {
     if (!messages || messages.length === 0) {
         return null;