@vectorize-io/hindsight-openclaw 0.4.19 → 0.5.0

package/dist/client.js

@@ -4,6 +4,7 @@ import { writeFile, mkdir, rm } from 'fs/promises';
 import { tmpdir } from 'os';
 import { join } from 'path';
 import { randomBytes } from 'crypto';
+import * as log from './logger.js';
 const execFileAsync = promisify(execFile);
 const MAX_BUFFER = 5 * 1024 * 1024; // 5 MB — large transcripts can exceed default 1 MB
 const DEFAULT_TIMEOUT_MS = 15_000;
@@ -78,10 +79,10 @@ export class HindsightClient {
                 const body = await res.text().catch(() => '');
                 throw new Error(`HTTP ${res.status}: ${body}`);
             }
-            console.log(`[Hindsight] Bank mission set via HTTP`);
+            log.verbose('bank mission set via HTTP');
         }
         catch (error) {
-            console.warn(`[Hindsight] Could not set bank mission (bank may not exist yet): ${error}`);
+            log.warn(`could not set bank mission (bank may not exist yet): ${error}`);
         }
     }
     async setBankMissionSubprocess(mission) {
@@ -89,11 +90,11 @@ export class HindsightClient {
         const args = [...baseArgs, '--profile', 'openclaw', 'bank', 'mission', this.bankId, sanitize(mission)];
         try {
             const { stdout } = await execFileAsync(cmd, args, { maxBuffer: MAX_BUFFER });
-            console.log(`[Hindsight] Bank mission set: ${stdout.trim()}`);
+            log.verbose(`bank mission set: ${stdout.trim()}`);
         }
         catch (error) {
             // Don't fail if mission set fails - bank might not exist yet, will be created on first retain
-            console.warn(`[Hindsight] Could not set bank mission (bank may not exist yet): ${error}`);
+            log.warn(`could not set bank mission (bank may not exist yet): ${error}`);
         }
     }
     // --- retain ---
@@ -124,7 +125,7 @@ export class HindsightClient {
             throw new Error(`Failed to retain memory (HTTP ${res.status}): ${text}`);
         }
         const data = await res.json();
-        console.log(`[Hindsight] Retained via HTTP (async): ${JSON.stringify(data).substring(0, 200)}`);
+        log.verbose(`retained via HTTP (async): ${JSON.stringify(data).substring(0, 200)}`);
         return {
             message: 'Memory queued for background processing',
             document_id: request.document_id || 'conversation',
@@ -144,7 +145,7 @@ export class HindsightClient {
             const [cmd, ...baseArgs] = this.getEmbedCommand();
             const args = [...baseArgs, '--profile', 'openclaw', 'memory', 'retain-files', this.bankId, tempFile, '--async'];
             const { stdout } = await execFileAsync(cmd, args, { maxBuffer: MAX_BUFFER });
-            console.log(`[Hindsight] Retained (async): ${stdout.trim()}`);
+            log.verbose(`retained (async): ${stdout.trim()}`);
             return {
                 message: 'Memory queued for background processing',
                 document_id: docId,
@@ -170,7 +171,7 @@ export class HindsightClient {
         // Defense-in-depth: truncate query to stay under API's 500-token limit
         const MAX_QUERY_CHARS = 800;
         const query = request.query.length > MAX_QUERY_CHARS
-            ? (console.warn(`[Hindsight] Truncating recall query from ${request.query.length} to ${MAX_QUERY_CHARS} chars`),
+            ? (log.warn(`truncating recall query from ${request.query.length} to ${MAX_QUERY_CHARS} chars`),
                 request.query.substring(0, MAX_QUERY_CHARS))
             : request.query;
         const body = {

package/dist/index.js

@@ -3,11 +3,13 @@ import { HindsightClient } from './client.js';
 import { createHash } from 'crypto';
 import { dirname } from 'path';
 import { fileURLToPath } from 'url';
-// Debug logging: silent by default, enable with debug: true in plugin config
+import * as log from './logger.js';
+import { configureLogger, setApiLogger, stopLogger } from './logger.js';
+// Debug logging: silent by default, enable with debug: true or logLevel: 'debug'
 let debugEnabled = false;
 const debug = (...args) => {
     if (debugEnabled)
-        console.log(...args);
+        log.verbose(args.map(a => typeof a === 'string' ? a.replace(/^\[Hindsight\]\s*/, '') : String(a)).join(' '));
 };
 // Module-level state
 let embedManager = null;
@@ -26,7 +28,7 @@ const MAX_TRACKED_BANK_CLIENTS = 10_000;
 const inflightRecalls = new Map();
 const turnCountBySession = new Map();
 const MAX_TRACKED_SESSIONS = 10_000;
-const RECALL_TIMEOUT_MS = 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();
@@ -93,7 +95,7 @@ async function lazyReinit() {
         debug('[Hindsight] ✓ Lazy re-initialization succeeded');
     }
     catch (error) {
-        console.warn(`[Hindsight] Lazy re-initialization failed (will retry in ${REINIT_COOLDOWN_MS / 1000}s):`, error instanceof Error ? error.message : error);
+        log.warn(`lazy re-init failed (retry in ${REINIT_COOLDOWN_MS / 1000}s): ${error instanceof Error ? error.message : error}`);
     }
     finally {
         isReinitInProgress = false;
@@ -160,7 +162,7 @@ if (typeof global !== 'undefined') {
                 }
                 catch (error) {
                     // Log but don't fail - bank mission is not critical
-                    console.warn(`[Hindsight] Could not set bank mission for ${bankId}: ${error}`);
+                    log.warn(`could not set bank mission for ${bankId}: ${error}`);
                 }
             }
             return bankClient;
@@ -393,7 +395,7 @@ export function deriveBankId(ctx, pluginConfig) {
     const validFields = new Set(['agent', 'channel', 'user', 'provider']);
     for (const f of fields) {
         if (!validFields.has(f)) {
-            console.warn(`[Hindsight] Unknown dynamicBankGranularity field "${f}" — will resolve to "unknown" in bank ID. Valid fields: agent, channel, user, provider`);
+            log.warn(`unknown dynamicBankGranularity field "${f}" — will resolve to "unknown". Valid: agent, channel, user, provider`);
         }
     }
     // Parse sessionKey as fallback when direct context fields are missing
@@ -428,13 +430,13 @@ export function formatMemories(results) {
 }
 // Provider detection from standard env vars
 const PROVIDER_DETECTION = [
-    { name: 'openai', keyEnv: 'OPENAI_API_KEY', defaultModel: 'gpt-4o-mini' },
-    { name: 'anthropic', keyEnv: 'ANTHROPIC_API_KEY', defaultModel: 'claude-3-5-haiku-20241022' },
-    { name: 'gemini', keyEnv: 'GEMINI_API_KEY', defaultModel: 'gemini-2.5-flash' },
-    { name: 'groq', keyEnv: 'GROQ_API_KEY', defaultModel: 'openai/gpt-oss-20b' },
-    { name: 'ollama', keyEnv: '', defaultModel: 'llama3.2' },
-    { name: 'openai-codex', keyEnv: '', defaultModel: 'gpt-5.2-codex' },
-    { name: 'claude-code', keyEnv: '', defaultModel: 'claude-sonnet-4-5-20250929' },
+    { 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)
@@ -450,11 +452,10 @@ function detectLLMConfig(pluginConfig) {
             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`);
         }
-        const providerInfo = PROVIDER_DETECTION.find(p => p.name === overrideProvider);
         return {
             provider: overrideProvider,
             apiKey: overrideKey || '',
-            model: overrideModel || (providerInfo?.defaultModel),
+            model: overrideModel,
             baseUrl: overrideBaseUrl,
             source: 'HINDSIGHT_API_LLM_PROVIDER override',
         };
@@ -481,7 +482,7 @@ function detectLLMConfig(pluginConfig) {
         return {
             provider: pluginConfig.llmProvider,
             apiKey,
-            model: pluginConfig.llmModel || overrideModel || providerInfo?.defaultModel,
+            model: pluginConfig.llmModel || overrideModel,
             baseUrl: overrideBaseUrl,
             source: 'plugin config',
         };
@@ -498,8 +499,8 @@ function detectLLMConfig(pluginConfig) {
             return {
                 provider: providerInfo.name,
                 apiKey,
-                model: overrideModel || providerInfo.defaultModel,
-                baseUrl: overrideBaseUrl, // Only use explicit HINDSIGHT_API_LLM_BASE_URL
+                model: overrideModel,
+                baseUrl: overrideBaseUrl,
                 source: `auto-detected from ${providerInfo.keyEnv}`,
             };
         }
@@ -518,21 +519,20 @@ function detectLLMConfig(pluginConfig) {
     }
     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        # Uses gpt-4o-mini\n` +
-        `  export ANTHROPIC_API_KEY=your-key       # Uses claude-3-5-haiku\n` +
-        `  export GEMINI_API_KEY=your-key          # Uses gemini-2.5-flash\n` +
-        `  export GROQ_API_KEY=your-key            # Uses openai/gpt-oss-20b\n\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", "llmModel": "gpt-4o-mini"\n\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_MODEL=gpt-4o-mini\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` +
-        `Tip: Use a cheap/fast model for memory extraction (e.g., gpt-4o-mini, claude-3-5-haiku, or free models on OpenRouter)`);
+        `The model will be selected automatically by Hindsight. To override: export HINDSIGHT_API_LLM_MODEL=your-model`);
 }
 /**
  * Detect external Hindsight API configuration.
@@ -624,6 +624,8 @@ function getPluginConfig(api) {
         recallPromptPreamble: typeof config.recallPromptPreamble === 'string' && config.recallPromptPreamble.trim().length > 0
             ? config.recallPromptPreamble
             : 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,
         debug: config.debug ?? false,
     };
 }
@@ -632,7 +634,15 @@ export default function (api) {
         debug('[Hindsight] Plugin loading...');
         // Get plugin config first (needed for LLM detection and debug flag)
         const pluginConfig = getPluginConfig(api);
-        debugEnabled = pluginConfig.debug ?? false;
+        // If logLevel is 'debug', also enable legacy debug flag
+        debugEnabled = pluginConfig.debug ?? (pluginConfig.logLevel === 'debug');
+        // Configure structured logger — route through OpenClaw's api.logger for consistent formatting
+        if (api.logger)
+            setApiLogger(api.logger);
+        configureLogger({
+            logLevel: pluginConfig.logLevel ?? (pluginConfig.debug ? 'debug' : 'info'),
+            logSummaryIntervalMs: pluginConfig.logSummaryIntervalMs,
+        });
         // Store config globally for bank ID derivation in hooks
         currentPluginConfig = pluginConfig;
         // Detect LLM configuration (env vars > plugin config > auto-detect)
@@ -700,6 +710,12 @@ export default function (api) {
                         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)');
                 }
@@ -726,12 +742,18 @@ export default function (api) {
                         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) {
-                console.error('[Hindsight] Initialization error:', error);
+                log.error('initialization error', error);
                 throw error;
             }
         })();
@@ -749,7 +771,7 @@ export default function (api) {
                         await initPromise;
                     }
                     catch (error) {
-                        console.error('[Hindsight] Initial initialization failed:', error);
+                        log.error('initial initialization failed', error);
                         // Continue to health check below
                     }
                 }
@@ -763,7 +785,7 @@ export default function (api) {
                             return;
                         }
                         catch (error) {
-                            console.error('[Hindsight] External API health check failed:', error);
+                            log.error('external API health check failed', error);
                             // Reset state for reinitialization attempt
                             client = null;
                             clientOptions = null;
@@ -850,10 +872,11 @@ export default function (api) {
                     clientsByBankId.clear();
                     banksWithMissionSet.clear();
                     isInitialized = false;
+                    stopLogger();
                     debug('[Hindsight] Service stopped');
                 }
                 catch (error) {
-                    console.error('[Hindsight] Service stop error:', error);
+                    log.error('service stop error', error);
                     throw error;
                 }
             },
@@ -949,7 +972,8 @@ export default function (api) {
                     recallPromise = existing;
                 }
                 else {
-                    recallPromise = client.recall({ query: prompt, max_tokens: pluginConfig.recallMaxTokens || 1024, budget: pluginConfig.recallBudget, types: pluginConfig.recallTypes }, RECALL_TIMEOUT_MS);
+                    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);
                     inflightRecalls.set(recallKey, recallPromise);
                     void recallPromise.catch(() => { }).finally(() => inflightRecalls.delete(recallKey));
                 }
@@ -970,19 +994,30 @@ Current time - ${formatCurrentTimeForRecall()}
 ${memoriesFormatted}
 </hindsight_memories>`;
                 debug(`[Hindsight] Auto-recall: Injecting ${results.length} memories from bank ${bankId}`);
-                // Inject recalled memories into system prompt space so they stay hidden from
-                // the end-user transcript/UI while still being available to the model.
-                return { prependSystemContext: contextMessage };
+                log.info(`injecting ${results.length} memories into context (bank: ${bankId})`);
+                log.trackRecall(bankId, results.length);
+                // Inject recalled memories. Position is configurable to preserve prompt caching
+                // when agents have large static system prompts.
+                const position = pluginConfig.recallInjectionPosition || 'prepend';
+                switch (position) {
+                    case 'append':
+                        return { appendSystemContext: contextMessage };
+                    case 'user':
+                        return { prependContext: contextMessage };
+                    case 'prepend':
+                    default:
+                        return { prependSystemContext: contextMessage };
+                }
             }
             catch (error) {
                 if (error instanceof DOMException && error.name === 'TimeoutError') {
-                    console.warn(`[Hindsight] Auto-recall timed out after ${RECALL_TIMEOUT_MS}ms, skipping memory injection`);
+                    log.warn(`[Hindsight] Auto-recall timed out after ${pluginConfig.recallTimeoutMs ?? DEFAULT_RECALL_TIMEOUT_MS}ms, skipping memory injection`);
                 }
                 else if (error instanceof Error && error.name === 'AbortError') {
-                    console.warn(`[Hindsight] Auto-recall aborted after ${RECALL_TIMEOUT_MS}ms, skipping memory injection`);
+                    log.warn(`[Hindsight] Auto-recall aborted after ${pluginConfig.recallTimeoutMs ?? DEFAULT_RECALL_TIMEOUT_MS}ms, skipping memory injection`);
                 }
                 else {
-                    console.error('[Hindsight] Auto-recall error:', error);
+                    log.error('auto-recall error', error);
                 }
                 return;
             }
@@ -1058,14 +1093,14 @@ ${memoriesFormatted}
                 // Wait for client to be ready
                 const clientGlobal = global.__hindsightClient;
                 if (!clientGlobal) {
-                    console.warn('[Hindsight] Client global not found, skipping retain');
+                    log.warn('client global not found, skipping retain');
                     return;
                 }
                 await clientGlobal.waitForReady();
                 // Get client configured for this context's bank (async to handle mission setup)
                 const client = await clientGlobal.getClientForContext(effectiveCtxForRetain);
                 if (!client) {
-                    console.warn('[Hindsight] Client not initialized, skipping retain');
+                    log.warn('client not initialized, skipping retain');
                     return;
                 }
                 // Use unique document ID per conversation (sessionKey + timestamp)
@@ -1084,18 +1119,19 @@ ${memoriesFormatted}
                         sender_id: effectiveCtx?.senderId,
                     },
                 });
+                log.trackRetain(bankId, messageCount);
                 debug(`[Hindsight] Retained ${messageCount} messages to bank ${bankId} for session ${documentId}`);
             }
             catch (error) {
-                console.error('[Hindsight] Error retaining messages:', error);
+                log.error('error retaining messages', error);
             }
         });
         debug('[Hindsight] Hooks registered');
     }
     catch (error) {
-        console.error('[Hindsight] Plugin loading error:', error);
+        log.error('plugin loading error', error);
         if (error instanceof Error) {
-            console.error('[Hindsight] Error stack:', error.stack);
+            log.error('error stack', error.stack);
         }
         throw error;
     }

package/dist/logger.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Hindsight OpenClaw plugin logger.
+ *
+ * Routes output through OpenClaw's api.logger for consistent formatting
+ * with other plugins (same colors/timestamps as mem0, etc.).
+ *
+ * Features:
+ *  - Configurable log level: 'off' | 'error' | 'warning' | 'info' | 'debug'
+ *  - Batched retain/recall summaries instead of per-event spam
+ */
+export type LogLevel = 'off' | 'error' | 'warning' | 'info' | 'debug';
+export interface LoggerConfig {
+    /** Minimum severity to print. Default: 'info' */
+    logLevel?: LogLevel;
+    /** Interval in ms to print batched retain/recall summaries. 0 = print every event. Default: 300000 (5 min) */
+    logSummaryIntervalMs?: number;
+}
+/** Bind to OpenClaw's api.logger for consistent output formatting */
+export declare function setApiLogger(logger: {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}): void;
+export declare function configureLogger(cfg: LoggerConfig): void;
+/** Info-level log (requires 'info' or higher) */
+export declare function info(msg: string): void;
+/** Debug log (requires 'debug') */
+export declare function verbose(msg: string): void;
+/** Warning (requires 'warning' or higher) */
+export declare function warn(msg: string): void;
+/** Error (requires 'error' or higher) */
+export declare function error(msg: string, err?: unknown): void;
+/** Track a retain event for batched summary */
+export declare function trackRetain(bankId: string, messageCount: number): void;
+/** Track a recall event for batched summary */
+export declare function trackRecall(bankId: string, memoriesFound: number): void;
+/** Flush the batched summary to console */
+export declare function flushSummary(): void;
+/** Cleanup (call on plugin stop) */
+export declare function stopLogger(): void;

package/dist/logger.js

@@ -0,0 +1,127 @@
+/**
+ * Hindsight OpenClaw plugin logger.
+ *
+ * Routes output through OpenClaw's api.logger for consistent formatting
+ * with other plugins (same colors/timestamps as mem0, etc.).
+ *
+ * Features:
+ *  - Configurable log level: 'off' | 'error' | 'warning' | 'info' | 'debug'
+ *  - Batched retain/recall summaries instead of per-event spam
+ */
+// Muted blue (38;5;103 = slate/dusty blue from 256-color palette)
+const PREFIX = '\x1b[38;5;103mhindsight:\x1b[0m';
+const LEVEL_RANK = {
+    off: 0,
+    error: 1,
+    warning: 2,
+    info: 3,
+    debug: 4,
+};
+// Output backend — set via setApiLogger, falls back to console
+let apiLogger = {
+    info: (msg) => console.log(msg),
+    warn: (msg) => console.warn(msg),
+    error: (msg) => console.error(msg),
+};
+// Batched summary state
+let retainCount = 0;
+let retainMsgTotal = 0;
+let recallCount = 0;
+let recallMemoriesCount = 0;
+const banksSeen = new Set();
+let lastSummaryTime = Date.now();
+let summaryTimer = null;
+let currentLevel = 'info';
+let currentSummaryIntervalMs = 300_000; // 5 min
+/** Bind to OpenClaw's api.logger for consistent output formatting */
+export function setApiLogger(logger) {
+    apiLogger = logger;
+}
+export function configureLogger(cfg) {
+    currentLevel = cfg.logLevel ?? 'info';
+    currentSummaryIntervalMs = cfg.logSummaryIntervalMs ?? 300_000;
+    // Restart summary timer
+    if (summaryTimer) {
+        clearInterval(summaryTimer);
+        summaryTimer = null;
+    }
+    if (currentSummaryIntervalMs > 0 && LEVEL_RANK[currentLevel] >= LEVEL_RANK['info']) {
+        summaryTimer = setInterval(flushSummary, currentSummaryIntervalMs);
+        summaryTimer.unref?.(); // don't keep process alive
+    }
+}
+function allowed(level) {
+    return LEVEL_RANK[currentLevel] >= LEVEL_RANK[level];
+}
+/** Info-level log (requires 'info' or higher) */
+export function info(msg) {
+    if (!allowed('info'))
+        return;
+    apiLogger.info(`${PREFIX} ${msg}`);
+}
+/** Debug log (requires 'debug') */
+export function verbose(msg) {
+    if (!allowed('debug'))
+        return;
+    apiLogger.info(`${PREFIX} ${msg}`);
+}
+/** Warning (requires 'warning' or higher) */
+export function warn(msg) {
+    if (!allowed('warning'))
+        return;
+    apiLogger.warn(`${PREFIX} ${msg}`);
+}
+/** Error (requires 'error' or higher) */
+export function error(msg, err) {
+    if (!allowed('error'))
+        return;
+    const detail = err instanceof Error ? err.message : (err ? String(err) : '');
+    apiLogger.error(`${PREFIX} ${detail ? `${msg}: ${detail}` : msg}`);
+}
+/** Track a retain event for batched summary */
+export function trackRetain(bankId, messageCount) {
+    retainCount++;
+    retainMsgTotal += messageCount;
+    banksSeen.add(bankId);
+    if (currentSummaryIntervalMs === 0 && allowed('info')) {
+        apiLogger.info(`${PREFIX} auto-retained ${messageCount} messages (bank: ${bankId})`);
+    }
+}
+/** Track a recall event for batched summary */
+export function trackRecall(bankId, memoriesFound) {
+    recallCount++;
+    recallMemoriesCount += memoriesFound;
+    banksSeen.add(bankId);
+    // per-event logging is handled by info() call at the injection site
+}
+/** Flush the batched summary to console */
+export function flushSummary() {
+    if (!allowed('info'))
+        return;
+    if (retainCount === 0 && recallCount === 0)
+        return;
+    const elapsed = Math.round((Date.now() - lastSummaryTime) / 1000);
+    const parts = [];
+    if (recallCount > 0)
+        parts.push(`${recallCount} recalls (${recallMemoriesCount} memories injected)`);
+    if (retainCount > 0)
+        parts.push(`${retainCount} retains (${retainMsgTotal} messages captured)`);
+    const bankList = [...banksSeen];
+    const bankLabel = bankList.length === 1 ? 'bank' : 'banks';
+    const banks = bankList.length > 0 ? ` (${bankLabel}: ${bankList.join(', ')})` : '';
+    apiLogger.info(`${PREFIX} ${parts.join(', ')} in ${elapsed}s${banks}`);
+    retainCount = 0;
+    retainMsgTotal = 0;
+    recallCount = 0;
+    recallMemoriesCount = 0;
+    banksSeen.clear();
+    lastSummaryTime = Date.now();
+}
+/** Cleanup (call on plugin stop) */
+export function stopLogger() {
+    flushSummary();
+    if (summaryTimer) {
+        clearInterval(summaryTimer);
+        summaryTimer = null;
+    }
+}

package/dist/types.d.ts

@@ -1,11 +1,17 @@
 export interface PluginPromptHookResult {
     prependContext?: string;
     prependSystemContext?: string;
+    appendSystemContext?: string;
 }
 export interface MoltbotPluginAPI {
     config: MoltbotConfig;
     registerService(config: ServiceConfig): void;
     on(event: string, handler: (event: any, ctx?: any) => void | Promise<void | PluginPromptHookResult>): void;
+    logger: {
+        info(msg: string): void;
+        warn(msg: string): void;
+        error(msg: string): void;
+    };
 }
 export interface MoltbotConfig {
     agents?: {
@@ -61,9 +67,13 @@ export interface PluginConfig {
     retainOverlapTurns?: number;
     recallTopK?: number;
     recallContextTurns?: number;
+    recallTimeoutMs?: number;
     recallMaxQueryChars?: number;
     recallPromptPreamble?: string;
+    recallInjectionPosition?: 'prepend' | 'append' | 'user';
     debug?: boolean;
+    logLevel?: 'off' | 'error' | 'warning' | 'info' | 'debug';
+    logSummaryIntervalMs?: number;
 }
 export interface ServiceConfig {
     id: string;

package/openclaw.plugin.json

@@ -188,11 +188,34 @@
         "description": "Text shown above recalled memories in the injected context block.",
         "default": "Relevant memories from past conversations (prioritize recent when conflicting). Only use memories that are directly useful to continue this conversation; ignore the rest:"
       },
+      "recallTimeoutMs": {
+        "type": "integer",
+        "minimum": 1000,
+        "description": "Timeout for auto-recall in milliseconds. Increase if recall times out with high budget.",
+        "default": 10000
+      },
+      "recallInjectionPosition": {
+        "type": "string",
+        "enum": ["prepend", "append", "user"],
+        "description": "Where to inject recalled memories. 'prepend' = start of system prompt (default), 'append' = end of system prompt (preserves prompt cache), 'user' = before user message.",
+        "default": "prepend"
+      },
       "debug": {
         "type": "boolean",
-        "description": "Enable debug logging for Hindsight plugin operations.",
+        "description": "Enable debug logging for Hindsight plugin operations. Equivalent to logLevel: 'debug'.",
         "default": false
-      }
+      },
+      "logLevel": {
+        "type": "string",
+        "description": "Console log verbosity. 'off' = no output, 'error' = errors only, 'warning' = errors + warnings, 'info' = key events + periodic summaries, 'debug' = all details.",
+        "enum": ["off", "error", "warning", "info", "debug"],
+        "default": "info"
+      },
+      "logSummaryIntervalMs": {
+        "type": "number",
+        "description": "Interval in ms to batch retain/recall log summaries. 0 = log every event individually. Default: 300000 (5 min).",
+        "default": 300000
+      },
     },
     "additionalProperties": false
   },
@@ -309,8 +332,23 @@
       "label": "Recall Prompt Preamble",
       "placeholder": "Instruction shown above recalled memories in injected context"
     },
+    "recallTimeoutMs": {
+      "label": "Recall Timeout (ms)",
+      "placeholder": "10000 (default)"
+    },
+    "recallInjectionPosition": {
+      "label": "Recall Injection Position",
+      "placeholder": "prepend, append, or user"
+    },
     "debug": {
       "label": "Debug"
-    }
+    },
+    "logLevel": {
+      "label": "Log Level"
+    },
+    "logSummaryIntervalMs": {
+      "label": "Log Summary Interval (ms)",
+      "placeholder": "300000"
+    },
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorize-io/hindsight-openclaw",
-  "version": "0.4.19",
+  "version": "0.5.0",
   "description": "Hindsight memory plugin for OpenClaw - biomimetic long-term memory with fact extraction",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -52,6 +52,7 @@
     "node": ">=22"
   },
   "overrides": {
-    "rollup": "^4.59.0"
+    "rollup": "^4.59.0",
+    "picomatch": ">=2.3.2 <3.0.0 || >=4.0.4"
   }
 }