@vectorize-io/hindsight-openclaw 0.4.15 → 0.4.17

package/README.md

@@ -24,6 +24,47 @@ openclaw gateway
 
 That's it! The plugin will automatically start capturing and recalling memories.
 
+## Features
+
+- **Auto-capture** and **auto-recall** of memories each turn
+- **Memory isolation** — configurable per agent, channel, user, or provider via `dynamicBankGranularity`
+- **Retention controls** — choose which message roles to retain and toggle auto-retain on/off
+
+## Configuration
+
+Optional settings in `~/.openclaw/openclaw.json` under `plugins.entries.hindsight-openclaw.config`:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `apiPort` | `9077` | Port for the local Hindsight daemon |
+| `daemonIdleTimeout` | `0` | Seconds before daemon shuts down from inactivity (0 = never) |
+| `embedPort` | `0` | Port for `hindsight-embed` server (`0` = auto-assign) |
+| `embedVersion` | `"latest"` | hindsight-embed version |
+| `embedPackagePath` | — | Local path to `hindsight-embed` package for development |
+| `bankMission` | — | Agent identity/purpose stored on the memory bank. Helps the engine understand context for better fact extraction. Set once per bank — not a recall prompt. |
+| `llmProvider` | auto-detect | LLM provider override for memory extraction (`openai`, `anthropic`, `gemini`, `groq`, `ollama`, `openai-codex`, `claude-code`) |
+| `llmModel` | provider default | LLM model override used with `llmProvider` |
+| `llmApiKeyEnv` | provider standard env var | Custom env var name for the provider API key |
+| `dynamicBankId` | `true` | Enable per-context memory banks |
+| `bankIdPrefix` | — | Prefix for bank IDs (e.g. `"prod"`) |
+| `dynamicBankGranularity` | `["agent", "channel", "user"]` | Fields used to derive bank ID. Options: `agent`, `channel`, `user`, `provider` |
+| `excludeProviders` | `[]` | Message providers to skip for recall/retain (e.g. `slack`, `telegram`, `discord`) |
+| `autoRecall` | `true` | Auto-inject memories before each turn. Set to `false` when the agent has its own recall tool. |
+| `autoRetain` | `true` | Auto-retain conversations after each turn |
+| `retainRoles` | `["user", "assistant"]` | Which message roles to retain. Options: `user`, `assistant`, `system`, `tool` |
+| `retainEveryNTurns` | `1` | Retain every Nth turn. `1` = every turn (default). Values > 1 enable chunked retention with a sliding window. |
+| `retainOverlapTurns` | `0` | Extra prior turns included when chunked retention fires. Window = `retainEveryNTurns + retainOverlapTurns`. Only applies when `retainEveryNTurns > 1`. |
+| `recallBudget` | `"mid"` | Recall effort: `low`, `mid`, or `high`. Higher budgets use more retrieval strategies. |
+| `recallMaxTokens` | `1024` | Max tokens for recall response. Controls how much memory context is injected per turn. |
+| `recallTypes` | `["world", "experience"]` | Memory types to recall. Options: `world`, `experience`, `observation`. Excludes verbose `observation` entries by default. |
+| `recallRoles` | `["user", "assistant"]` | Roles included when building prior context for recall query composition. Options: `user`, `assistant`, `system`, `tool`. |
+| `recallTopK` | — | Max number of memories to inject per turn. Applied after API response as a hard cap. |
+| `recallContextTurns` | `1` | Number of user turns to include when composing recall query context. `1` keeps latest-message-only behavior. |
+| `recallMaxQueryChars` | `800` | Maximum character length for the composed recall query before calling recall. |
+| `recallPromptPreamble` | built-in string | Prompt text placed above recalled memories in the injected `<hindsight_memories>` block. |
+| `hindsightApiUrl` | — | External Hindsight API URL (skips local daemon) |
+| `hindsightApiToken` | — | Auth token for external API |
+
 ## Documentation
 
 For full documentation, configuration options, troubleshooting, and development guide, see:

package/dist/client.d.ts

@@ -1,7 +1,5 @@
 import type { RetainRequest, RetainResponse, RecallRequest, RecallResponse } from './types.js';
 export interface HindsightClientOptions {
-    llmProvider: string;
-    llmApiKey: string;
     llmModel?: string;
     embedVersion?: string;
     embedPackagePath?: string;
@@ -10,8 +8,6 @@ export interface HindsightClientOptions {
 }
 export declare class HindsightClient {
     private bankId;
-    private llmProvider;
-    private llmApiKey;
     private llmModel?;
     private embedVersion;
     private embedPackagePath?;

package/dist/client.js

@@ -19,16 +19,12 @@ function sanitizeFilename(name) {
 }
 export class HindsightClient {
     bankId = 'default';
-    llmProvider;
-    llmApiKey;
     llmModel;
     embedVersion;
     embedPackagePath;
     apiUrl;
     apiToken;
     constructor(opts) {
-        this.llmProvider = opts.llmProvider;
-        this.llmApiKey = opts.llmApiKey;
         this.llmModel = opts.llmModel;
         this.embedVersion = opts.embedVersion || 'latest';
         this.embedPackagePath = opts.embedPackagePath;
@@ -181,6 +177,12 @@ export class HindsightClient {
             query,
             max_tokens: request.max_tokens || 1024,
         };
+        if (request.budget) {
+            body.budget = request.budget;
+        }
+        if (request.types) {
+            body.types = request.types;
+        }
         const res = await fetch(url, {
             method: 'POST',
             headers: this.httpHeaders(),

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import type { MoltbotPluginAPI } from './types.js';
+import type { MoltbotPluginAPI, PluginConfig, PluginHookAgentContext, MemoryResult } from './types.js';
 import { HindsightClient } from './client.js';
 /**
  * Strip plugin-injected memory tags from content to prevent retain feedback loop.
@@ -6,6 +6,17 @@ import { HindsightClient } from './client.js';
  * during before_agent_start so they don't get re-stored into the memory bank.
  */
 export declare function stripMemoryTags(content: string): string;
+/**
+ * Extract sender_id from OpenClaw's injected inbound metadata blocks.
+ * Checks both "Conversation info (untrusted metadata)" and "Sender (untrusted metadata)" blocks.
+ * Returns the first sender_id / id string found, or undefined if none.
+ */
+export declare function extractSenderIdFromText(text: string): string | undefined;
+/**
+ * Strip OpenClaw sender/conversation metadata envelopes from message content.
+ * These blocks are injected by OpenClaw but are noise for memory storage and recall.
+ */
+export declare function stripMetadataEnvelopes(content: string): string;
 /**
  * Extract a recall query from a hook event's rawMessage or prompt.
  *
@@ -15,5 +26,14 @@ export declare function stripMemoryTags(content: string): string;
  * Returns null when no usable query (< 5 chars) can be extracted.
  */
 export declare function extractRecallQuery(rawMessage: string | undefined, prompt: string | undefined): string | null;
+export declare function composeRecallQuery(latestQuery: string, messages: any[] | undefined, recallContextTurns: number, recallRoles?: Array<'user' | 'assistant' | 'system' | 'tool'>): string;
+export declare function truncateRecallQuery(query: string, latestQuery: string, maxChars: number): string;
+export declare function deriveBankId(ctx: PluginHookAgentContext | undefined, pluginConfig: PluginConfig): string;
+export declare function formatMemories(results: MemoryResult[]): string;
 export default function (api: MoltbotPluginAPI): void;
+export declare function prepareRetentionTranscript(messages: any[], pluginConfig: PluginConfig, retainFullWindow?: boolean): {
+    transcript: string;
+    messageCount: number;
+} | null;
+export declare function sliceLastTurnsByUserBoundary(messages: any[], turns: number): any[];
 export declare function getClient(): HindsightClient | null;

package/dist/index.js

@@ -1,5 +1,6 @@
 import { HindsightEmbedManager } from './embed-manager.js';
 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
@@ -11,6 +12,7 @@ const debug = (...args) => {
 // Module-level state
 let embedManager = null;
 let client = null;
+let clientOptions = null;
 let initPromise = null;
 let isInitialized = false;
 let usingExternalApi = false; // Track if using external API (skip daemon management)
@@ -18,13 +20,32 @@ let usingExternalApi = false; // Track if using external API (skip daemon manage
 let currentPluginConfig = null;
 // Track which banks have had their mission set (to avoid re-setting on every request)
 const banksWithMissionSet = new Set();
+// 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();
 const turnCountBySession = new Map();
+const MAX_TRACKED_SESSIONS = 10_000;
 const 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();
 // Cooldown + guard to prevent concurrent reinit attempts
 let lastReinitAttempt = 0;
 let isReinitInProgress = false;
 const REINIT_COOLDOWN_MS = 30_000;
+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();
+    const month = String(date.getUTCMonth() + 1).padStart(2, '0');
+    const day = String(date.getUTCDate()).padStart(2, '0');
+    const hours = String(date.getUTCHours()).padStart(2, '0');
+    const minutes = String(date.getUTCMinutes()).padStart(2, '0');
+    return `${year}-${month}-${day} ${hours}:${minutes}`;
+}
 /**
  * Lazy re-initialization after startup failure.
  * Called by waitForReady when initPromise rejected but API may now be reachable.
@@ -56,7 +77,10 @@ async function lazyReinit() {
             process.env.HINDSIGHT_EMBED_API_TOKEN = externalApi.apiToken;
         }
         const llmConfig = detectLLMConfig(config);
-        client = new HindsightClient(buildClientOptions(llmConfig, config, externalApi));
+        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) {
@@ -107,12 +131,30 @@ if (typeof global !== 'undefined') {
                 return null;
             }
             const config = currentPluginConfig || {};
+            if (config.dynamicBankId === false) {
+                return client;
+            }
             const bankId = deriveBankId(ctx, config);
-            client.setBankId(bankId);
+            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)) {
                 try {
-                    await client.setBankMission(config.bankMission);
+                    await bankClient.setBankMission(config.bankMission);
                     banksWithMissionSet.add(bankId);
                     debug(`[Hindsight] Set mission for new bank: ${bankId}`);
                 }
@@ -121,7 +163,7 @@ if (typeof global !== 'undefined') {
                     console.warn(`[Hindsight] Could not set bank mission for ${bankId}: ${error}`);
                 }
             }
-            return client;
+            return bankClient;
         },
         getPluginConfig: () => currentPluginConfig,
     };
@@ -141,6 +183,40 @@ export function stripMemoryTags(content) {
     content = content.replace(/<relevant_memories>[\s\S]*?<\/relevant_memories>/g, '');
     return content;
 }
+/**
+ * Extract sender_id from OpenClaw's injected inbound metadata blocks.
+ * Checks both "Conversation info (untrusted metadata)" and "Sender (untrusted metadata)" blocks.
+ * Returns the first sender_id / id string found, or undefined if none.
+ */
+export function extractSenderIdFromText(text) {
+    if (!text)
+        return undefined;
+    const metaBlockRe = /[\w\s]+\(untrusted metadata\)[^\n]*\n```json\n([\s\S]*?)\n```/gi;
+    let match;
+    while ((match = metaBlockRe.exec(text)) !== null) {
+        try {
+            const obj = JSON.parse(match[1]);
+            const id = obj?.sender_id ?? obj?.id;
+            if (id && typeof id === 'string')
+                return id;
+        }
+        catch {
+            // continue to next block
+        }
+    }
+    return undefined;
+}
+/**
+ * Strip OpenClaw sender/conversation metadata envelopes from message content.
+ * These blocks are injected by OpenClaw but are noise for memory storage and recall.
+ */
+export function stripMetadataEnvelopes(content) {
+    // Strip: ---\n<Label> (untrusted metadata):\n```json\n{...}\n```\n<message>\n---
+    content = content.replace(/^---\n[\w\s]+\(untrusted metadata\)[^\n]*\n```json[\s\S]*?```\n\n?/im, '').replace(/\n---$/, '');
+    // Strip: <Label> (untrusted metadata):\n```json\n{...}\n```  (without --- wrapper)
+    content = content.replace(/[\w\s]+\(untrusted metadata\)[^\n]*\n```json[\s\S]*?```\n?/gim, '');
+    return content.trim();
+}
 /**
  * Extract a recall query from a hook event's rawMessage or prompt.
  *
@@ -150,10 +226,25 @@ export function stripMemoryTags(content) {
  * Returns null when no usable query (< 5 chars) can be extracted.
  */
 export function extractRecallQuery(rawMessage, prompt) {
+    // Reject known metadata/system message patterns — these are not user queries
+    const METADATA_PATTERNS = [
+        /^\s*conversation info\s*\(untrusted metadata\)/i,
+        /^\s*\(untrusted metadata\)/i,
+        /^\s*system:/i,
+    ];
+    const isMetadata = (s) => METADATA_PATTERNS.some(p => p.test(s));
     let recallQuery = rawMessage;
-    if (!recallQuery || typeof recallQuery !== 'string' || recallQuery.trim().length < 5) {
+    // Strip sender metadata envelope before any checks
+    if (recallQuery) {
+        recallQuery = stripMetadataEnvelopes(recallQuery);
+    }
+    if (!recallQuery || typeof recallQuery !== 'string' || recallQuery.trim().length < 5 || isMetadata(recallQuery)) {
         recallQuery = prompt;
-        if (!recallQuery || typeof recallQuery !== 'string' || recallQuery.length < 5) {
+        // Strip metadata envelopes from prompt too, then check if anything useful remains
+        if (recallQuery) {
+            recallQuery = stripMetadataEnvelopes(recallQuery);
+        }
+        if (!recallQuery || recallQuery.length < 5) {
             return null;
         }
         // Strip envelope-formatted prompts from any channel
@@ -169,33 +260,172 @@ export function extractRecallQuery(rawMessage, prompt) {
         }
         // Remove trailing [from: SenderName] metadata (group chats)
         cleaned = cleaned.replace(/\n\[from:[^\]]*\]\s*$/, '');
+        // Strip metadata envelopes again after channel envelope extraction, in case
+        // the metadata block appeared after the [ChannelName] header
+        cleaned = stripMetadataEnvelopes(cleaned);
         recallQuery = cleaned.trim() || recallQuery;
     }
     const trimmed = recallQuery.trim();
-    if (trimmed.length < 5)
+    if (trimmed.length < 5 || isMetadata(trimmed))
         return null;
     return trimmed;
 }
+export function composeRecallQuery(latestQuery, messages, recallContextTurns, recallRoles = ['user', 'assistant']) {
+    const latest = latestQuery.trim();
+    if (recallContextTurns <= 1 || !Array.isArray(messages) || messages.length === 0) {
+        return latest;
+    }
+    const allowedRoles = new Set(recallRoles);
+    const contextualMessages = sliceLastTurnsByUserBoundary(messages, recallContextTurns);
+    const contextLines = contextualMessages
+        .map((msg) => {
+        const role = msg?.role;
+        if (!allowedRoles.has(role)) {
+            return null;
+        }
+        let content = '';
+        if (typeof msg?.content === 'string') {
+            content = msg.content;
+        }
+        else if (Array.isArray(msg?.content)) {
+            content = msg.content
+                .filter((block) => block?.type === 'text' && typeof block?.text === 'string')
+                .map((block) => block.text)
+                .join('\n');
+        }
+        content = stripMemoryTags(content).trim();
+        content = stripMetadataEnvelopes(content);
+        if (!content) {
+            return null;
+        }
+        if (role === 'user' && content === latest) {
+            return null;
+        }
+        return `${role}: ${content}`;
+    })
+        .filter((line) => Boolean(line));
+    if (contextLines.length === 0) {
+        return latest;
+    }
+    return [
+        'Prior context:',
+        contextLines.join('\n'),
+        latest,
+    ].join('\n\n');
+}
+export function truncateRecallQuery(query, latestQuery, maxChars) {
+    if (maxChars <= 0) {
+        return query;
+    }
+    const latest = latestQuery.trim();
+    if (query.length <= maxChars) {
+        return query;
+    }
+    const latestOnly = latest.length <= maxChars ? latest : latest.slice(0, maxChars);
+    if (!query.includes('Prior context:')) {
+        return latestOnly;
+    }
+    // New order: Prior context at top, latest user message at bottom.
+    // Truncate by dropping oldest context lines first to preserve the suffix.
+    const contextMarker = 'Prior context:\n\n';
+    const markerIndex = query.indexOf(contextMarker);
+    if (markerIndex === -1) {
+        return latestOnly;
+    }
+    const suffixMarker = '\n\n' + latest;
+    const suffixIndex = query.lastIndexOf(suffixMarker);
+    if (suffixIndex === -1) {
+        return latestOnly;
+    }
+    const suffix = query.slice(suffixIndex); // \n\n<latest>
+    if (suffix.length >= maxChars) {
+        return latestOnly;
+    }
+    const contextBody = query.slice(markerIndex + contextMarker.length, suffixIndex);
+    const contextLines = contextBody.split('\n').filter(Boolean);
+    const keptContextLines = [];
+    // Add context lines from newest (bottom) to oldest (top), stopping when we exceed maxChars
+    for (let i = contextLines.length - 1; i >= 0; i--) {
+        keptContextLines.unshift(contextLines[i]);
+        const candidate = `${contextMarker}${keptContextLines.join('\n')}${suffix}`;
+        if (candidate.length > maxChars) {
+            keptContextLines.shift();
+            break;
+        }
+    }
+    if (keptContextLines.length > 0) {
+        return `${contextMarker}${keptContextLines.join('\n')}${suffix}`;
+    }
+    return latestOnly;
+}
 /**
  * Derive a bank ID from the agent context.
- * Creates per-user banks: {messageProvider}-{senderId}
+ * Uses configurable dynamicBankGranularity to determine bank segmentation.
  * Falls back to default bank when context is unavailable.
  */
-function deriveBankId(ctx, pluginConfig) {
-    // If dynamic bank ID is disabled, use static bank
+/**
+ * Parse the OpenClaw sessionKey to extract context fields.
+ * Format: "agent:{agentId}:{provider}:{channelType}:{channelId}[:{extra}]"
+ * Example: "agent:c0der:telegram:group:-1003825475854:topic:42"
+ */
+function parseSessionKey(sessionKey) {
+    const parts = sessionKey.split(':');
+    if (parts.length < 5 || parts[0] !== 'agent')
+        return {};
+    // parts[1] = agentId, parts[2] = provider, parts[3] = channelType, parts[4..] = channelId + extras
+    return {
+        agentId: parts[1],
+        provider: parts[2],
+        // Rejoin from channelType onward as the channel identifier (e.g. "group:-1003825475854:topic:42")
+        channel: parts.slice(3).join(':'),
+    };
+}
+export function deriveBankId(ctx, pluginConfig) {
     if (pluginConfig.dynamicBankId === false) {
-        return pluginConfig.bankIdPrefix
-            ? `${pluginConfig.bankIdPrefix}-${DEFAULT_BANK_NAME}`
-            : DEFAULT_BANK_NAME;
-    }
-    const channelType = ctx?.messageProvider || 'unknown';
-    const userId = ctx?.senderId || 'default';
-    // Build bank ID: {prefix?}-{channelType}-{senderId}
-    const baseBankId = `${channelType}-${userId}`;
+        return pluginConfig.bankIdPrefix ? `${pluginConfig.bankIdPrefix}-openclaw` : 'openclaw';
+    }
+    // When no context is available, fall back to the static default bank.
+    if (!ctx) {
+        return pluginConfig.bankIdPrefix ? `${pluginConfig.bankIdPrefix}-openclaw` : 'openclaw';
+    }
+    const fields = pluginConfig.dynamicBankGranularity?.length ? pluginConfig.dynamicBankGranularity : ['agent', 'channel', 'user'];
+    // Validate field names at runtime — typos silently produce 'unknown' segments
+    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`);
+        }
+    }
+    // Parse sessionKey as fallback when direct context fields are missing
+    const sessionParsed = ctx?.sessionKey ? parseSessionKey(ctx.sessionKey) : {};
+    // Warn when 'user' is in active fields but senderId is missing — bank ID will contain "anonymous"
+    if (fields.includes('user') && ctx && !ctx.senderId) {
+        debug('[Hindsight] senderId not available in context — bank ID will use "anonymous". Ensure your OpenClaw provider passes senderId.');
+    }
+    const fieldMap = {
+        agent: ctx?.agentId || sessionParsed.agentId || 'default',
+        channel: ctx?.channelId || sessionParsed.channel || 'unknown',
+        user: ctx?.senderId || 'anonymous',
+        provider: ctx?.messageProvider || sessionParsed.provider || 'unknown',
+    };
+    const baseBankId = fields
+        .map(f => encodeURIComponent(fieldMap[f] || 'unknown'))
+        .join('::');
     return pluginConfig.bankIdPrefix
         ? `${pluginConfig.bankIdPrefix}-${baseBankId}`
         : baseBankId;
 }
+export function formatMemories(results) {
+    if (!results || results.length === 0)
+        return '';
+    return results
+        .map(r => {
+        const type = r.type ? ` [${r.type}]` : '';
+        const date = r.mentioned_at ? ` (${r.mentioned_at})` : '';
+        return `- ${r.text}${type}${date}`;
+    })
+        .join('\n\n');
+}
 // Provider detection from standard env vars
 const PROVIDER_DETECTION = [
     { name: 'openai', keyEnv: 'OPENAI_API_KEY', defaultModel: 'gpt-4o-mini' },
@@ -275,6 +505,17 @@ function detectLLMConfig(pluginConfig) {
         }
     }
     // No configuration found - show helpful error
+    // Allow empty LLM config if using external Hindsight API (server handles LLM)
+    const externalApiCheck = detectExternalApi(pluginConfig);
+    if (externalApiCheck.apiUrl) {
+        return {
+            provider: undefined,
+            apiKey: undefined,
+            model: undefined,
+            baseUrl: undefined,
+            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        # Uses gpt-4o-mini\n` +
@@ -307,8 +548,6 @@ function detectExternalApi(pluginConfig) {
  */
 function buildClientOptions(llmConfig, pluginCfg, externalApi) {
     return {
-        llmProvider: llmConfig.provider,
-        llmApiKey: llmConfig.apiKey,
         llmModel: llmConfig.model,
         embedVersion: pluginCfg.embedVersion,
         embedPackagePath: pluginCfg.embedPackagePath,
@@ -370,7 +609,21 @@ function getPluginConfig(api) {
         bankIdPrefix: config.bankIdPrefix,
         excludeProviders: Array.isArray(config.excludeProviders) ? config.excludeProviders : [],
         autoRecall: config.autoRecall !== false, // Default: true (on) — backward compatible
-        retainEveryNTurns: config.retainEveryNTurns,
+        dynamicBankGranularity: Array.isArray(config.dynamicBankGranularity) ? config.dynamicBankGranularity : undefined,
+        autoRetain: config.autoRetain !== false, // Default: true
+        retainRoles: Array.isArray(config.retainRoles) ? config.retainRoles : undefined,
+        recallBudget: config.recallBudget || 'mid',
+        recallMaxTokens: config.recallMaxTokens || 1024,
+        recallTypes: Array.isArray(config.recallTypes) ? config.recallTypes : ['world', 'experience'],
+        recallRoles: Array.isArray(config.recallRoles) ? config.recallRoles : ['user', 'assistant'],
+        retainEveryNTurns: typeof config.retainEveryNTurns === 'number' && config.retainEveryNTurns >= 1 ? config.retainEveryNTurns : 1,
+        retainOverlapTurns: typeof config.retainOverlapTurns === 'number' && config.retainOverlapTurns >= 0 ? config.retainOverlapTurns : 0,
+        recallTopK: typeof config.recallTopK === 'number' ? config.recallTopK : undefined,
+        recallContextTurns: typeof config.recallContextTurns === 'number' && config.recallContextTurns >= 1 ? config.recallContextTurns : 1,
+        recallMaxQueryChars: typeof config.recallMaxQueryChars === 'number' && config.recallMaxQueryChars >= 1 ? config.recallMaxQueryChars : 800,
+        recallPromptPreamble: typeof config.recallPromptPreamble === 'string' && config.recallPromptPreamble.trim().length > 0
+            ? config.recallPromptPreamble
+            : DEFAULT_RECALL_PROMPT_PREAMBLE,
         debug: config.debug ?? false,
     };
 }
@@ -433,7 +686,10 @@ export default function (api) {
                     await checkExternalApiHealth(externalApi.apiUrl, externalApi.apiToken);
                     // Initialize client with direct HTTP mode
                     debug('[Hindsight] Creating HindsightClient (HTTP mode)...');
-                    client = new HindsightClient(buildClientOptions(llmConfig, pluginConfig, externalApi));
+                    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}`);
@@ -450,13 +706,16 @@ export default function (api) {
                 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);
+                    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)...');
-                    client = new HindsightClient(buildClientOptions(llmConfig, pluginConfig, { apiUrl: null, apiToken: null }));
+                    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}`);
@@ -507,6 +766,9 @@ export default function (api) {
                             console.error('[Hindsight] External API health check failed:', error);
                             // Reset state for reinitialization attempt
                             client = null;
+                            clientOptions = null;
+                            clientsByBankId.clear();
+                            banksWithMissionSet.clear();
                             isInitialized = false;
                         }
                     }
@@ -523,6 +785,9 @@ export default function (api) {
                         // Reset state for reinitialization
                         embedManager = null;
                         client = null;
+                        clientOptions = null;
+                        clientsByBankId.clear();
+                        banksWithMissionSet.clear();
                         isInitialized = false;
                     }
                 }
@@ -542,7 +807,10 @@ export default function (api) {
                             process.env.HINDSIGHT_EMBED_API_TOKEN = externalApi.apiToken;
                         }
                         await checkExternalApiHealth(externalApi.apiUrl, externalApi.apiToken);
-                        client = new HindsightClient(buildClientOptions(llmConfig, reinitPluginConfig, externalApi));
+                        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) {
@@ -553,9 +821,12 @@ export default function (api) {
                     }
                     else {
                         // Local daemon mode
-                        embedManager = new HindsightEmbedManager(apiPort, llmConfig.provider, llmConfig.apiKey, llmConfig.model, llmConfig.baseUrl, reinitPluginConfig.daemonIdleTimeout, reinitPluginConfig.embedVersion, reinitPluginConfig.embedPackagePath);
+                        embedManager = new HindsightEmbedManager(apiPort, llmConfig.provider || "", llmConfig.apiKey || "", llmConfig.model, llmConfig.baseUrl, reinitPluginConfig.daemonIdleTimeout, reinitPluginConfig.embedVersion, reinitPluginConfig.embedPackagePath);
                         await embedManager.start();
-                        client = new HindsightClient(buildClientOptions(llmConfig, reinitPluginConfig, { apiUrl: null, apiToken: null }));
+                        clientOptions = buildClientOptions(llmConfig, reinitPluginConfig, { apiUrl: null, apiToken: null });
+                        clientsByBankId.clear();
+                        banksWithMissionSet.clear();
+                        client = new HindsightClient(clientOptions);
                         const defaultBankId = deriveBankId(undefined, reinitPluginConfig);
                         client.setBankId(defaultBankId);
                         if (reinitPluginConfig.bankMission && !reinitPluginConfig.dynamicBankId) {
@@ -575,6 +846,9 @@ export default function (api) {
                         embedManager = null;
                     }
                     client = null;
+                    clientOptions = null;
+                    clientsByBankId.clear();
+                    banksWithMissionSet.clear();
                     isInitialized = false;
                     debug('[Hindsight] Service stopped');
                 }
@@ -586,19 +860,16 @@ 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');
+            return;
+        }
+        registeredApis.add(api);
         debug('[Hindsight] Registering agent hooks...');
-        // Store session key and context for retention
-        let currentSessionKey;
-        let currentAgentContext;
         // 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_agent_start', async (event, ctx) => {
+        api.on('before_prompt_build', async (event, ctx) => {
             try {
-                // Capture session key and context for use in agent_end
-                if (ctx?.sessionKey) {
-                    currentSessionKey = ctx.sessionKey;
-                }
-                currentAgentContext = ctx;
                 // Check if this provider is excluded
                 if (ctx?.messageProvider && pluginConfig.excludeProviders?.includes(ctx.messageProvider)) {
                     debug(`[Hindsight] Skipping recall for excluded provider: ${ctx.messageProvider}`);
@@ -609,20 +880,49 @@ export default function (api) {
                     debug('[Hindsight] Auto-recall disabled via config, skipping');
                     return;
                 }
-                // Derive bank ID from context
-                const bankId = deriveBankId(ctx, pluginConfig);
-                debug(`[Hindsight] before_agent_start - bank: ${bankId}, channel: ${ctx?.messageProvider}/${ctx?.channelId}`);
+                // Derive bank ID from context — enrich ctx.senderId from the inbound metadata
+                // block when it's missing (agent-phase hooks don't carry senderId in ctx directly).
+                const senderIdFromPrompt = !ctx?.senderId ? extractSenderIdFromText(event.prompt ?? event.rawMessage ?? '') : undefined;
+                const effectiveCtxForRecall = senderIdFromPrompt ? { ...ctx, senderId: senderIdFromPrompt } : ctx;
+                // Cache the resolved sender ID keyed by sessionKey so agent_end can use it.
+                // event.messages in agent_end is clean history without the metadata blocks.
+                const resolvedSenderId = effectiveCtxForRecall?.senderId;
+                const sessionKeyForCache = ctx?.sessionKey;
+                if (resolvedSenderId && sessionKeyForCache) {
+                    senderIdBySession.set(sessionKeyForCache, resolvedSenderId);
+                    if (senderIdBySession.size > MAX_TRACKED_SESSIONS) {
+                        const oldest = senderIdBySession.keys().next().value;
+                        if (oldest)
+                            senderIdBySession.delete(oldest);
+                    }
+                }
+                const bankId = deriveBankId(effectiveCtxForRecall, pluginConfig);
+                debug(`[Hindsight] before_prompt_build - bank: ${bankId}, channel: ${ctx?.messageProvider}/${ctx?.channelId}`);
+                debug(`[Hindsight] event keys: ${Object.keys(event).join(', ')}`);
+                debug(`[Hindsight] event.context keys: ${Object.keys(event.context ?? {}).join(', ')}`);
                 // Get the user's latest message for recall — only the raw user text, not the full prompt
                 // rawMessage is clean user text; prompt includes envelope, system events, media notes, etc.
+                debug(`[Hindsight] extractRecallQuery input lengths - raw: ${event.rawMessage?.length ?? 0}, prompt: ${event.prompt?.length ?? 0}`);
                 const extracted = extractRecallQuery(event.rawMessage, event.prompt);
                 if (!extracted) {
+                    debug('[Hindsight] extractRecallQuery returned null, skipping recall');
                     return;
                 }
-                let prompt = extracted;
-                // Truncate — Hindsight API recall has a 500 token limit; 800 chars stays safely under even with non-ASCII
-                const MAX_RECALL_QUERY_CHARS = 800;
-                if (prompt.length > MAX_RECALL_QUERY_CHARS) {
-                    prompt = prompt.substring(0, MAX_RECALL_QUERY_CHARS);
+                debug(`[Hindsight] extractRecallQuery result length: ${extracted.length}`);
+                const recallContextTurns = pluginConfig.recallContextTurns ?? 1;
+                const recallMaxQueryChars = pluginConfig.recallMaxQueryChars ?? 800;
+                const sessionMessages = event.context?.sessionEntry?.messages ?? event.messages ?? [];
+                const messageCount = sessionMessages.length;
+                debug(`[Hindsight] event.messages count: ${messageCount}, roles: ${sessionMessages.map((m) => m.role).join(',')}`);
+                if (recallContextTurns > 1 && messageCount === 0) {
+                    debug('[Hindsight] recallContextTurns > 1 but event.messages is empty — prior context unavailable at before_agent_start for this provider');
+                }
+                const recallRoles = pluginConfig.recallRoles ?? ['user', 'assistant'];
+                const composedPrompt = composeRecallQuery(extracted, sessionMessages, recallContextTurns, recallRoles);
+                let prompt = truncateRecallQuery(composedPrompt, extracted, recallMaxQueryChars);
+                // Final defensive cap
+                if (prompt.length > recallMaxQueryChars) {
+                    prompt = prompt.substring(0, recallMaxQueryChars);
                 }
                 // Wait for client to be ready
                 const clientGlobal = global.__hindsightClient;
@@ -632,14 +932,16 @@ export default function (api) {
                 }
                 await clientGlobal.waitForReady();
                 // Get client configured for this context's bank (async to handle mission setup)
-                const client = await clientGlobal.getClientForContext(ctx);
+                const client = await clientGlobal.getClientForContext(effectiveCtxForRecall);
                 if (!client) {
                     debug('[Hindsight] Client not initialized, skipping auto-recall');
                     return;
                 }
-                debug(`[Hindsight] Auto-recall for bank ${bankId}, prompt: ${prompt.substring(0, 50)}`);
+                debug(`[Hindsight] Auto-recall for bank ${bankId}, full query:\n---\n${prompt}\n---`);
                 // Recall with deduplication: reuse in-flight request for same bank
-                const recallKey = bankId;
+                const normalizedPrompt = prompt.trim().toLowerCase().replace(/\s+/g, ' ');
+                const queryHash = createHash('sha256').update(normalizedPrompt).digest('hex').slice(0, 16);
+                const recallKey = `${bankId}::${queryHash}`;
                 const existing = inflightRecalls.get(recallKey);
                 let recallPromise;
                 if (existing) {
@@ -647,7 +949,7 @@ export default function (api) {
                     recallPromise = existing;
                 }
                 else {
-                    recallPromise = client.recall({ query: prompt, max_tokens: 2048 }, RECALL_TIMEOUT_MS);
+                    recallPromise = client.recall({ query: prompt, max_tokens: pluginConfig.recallMaxTokens || 1024, budget: pluginConfig.recallBudget, types: pluginConfig.recallTypes }, RECALL_TIMEOUT_MS);
                     inflightRecalls.set(recallKey, recallPromise);
                     void recallPromise.catch(() => { }).finally(() => inflightRecalls.delete(recallKey));
                 }
@@ -656,15 +958,18 @@ export default function (api) {
                     debug('[Hindsight] No memories found for auto-recall');
                     return;
                 }
+                debug(`[Hindsight] Raw recall response (${response.results.length} results before topK):\n${response.results.map((r, i) => `  [${i}] score=${r.score?.toFixed(3) ?? 'n/a'} type=${r.type ?? 'n/a'}: ${JSON.stringify(r.content ?? r.text ?? r).substring(0, 200)}`).join('\n')}`);
+                const results = pluginConfig.recallTopK ? response.results.slice(0, pluginConfig.recallTopK) : response.results;
+                debug(`[Hindsight] After topK (${pluginConfig.recallTopK ?? 'unlimited'}): ${results.length} results injected`);
                 // Format memories as JSON with all fields from recall
-                const memoriesJson = JSON.stringify(response.results, null, 2);
+                const memoriesFormatted = formatMemories(results);
                 const contextMessage = `<hindsight_memories>
-Relevant memories from past conversations (prioritize recent when conflicting):
-${memoriesJson}
+${pluginConfig.recallPromptPreamble || DEFAULT_RECALL_PROMPT_PREAMBLE}
+Current time - ${formatCurrentTimeForRecall()}
 
-User message: ${prompt}
+${memoriesFormatted}
 </hindsight_memories>`;
-                debug(`[Hindsight] Auto-recall: Injecting ${response.results.length} memories from bank ${bankId}`);
+                debug(`[Hindsight] Auto-recall: Injecting ${results.length} memories from bank ${bankId}`);
                 // Inject context before the user message
                 return { prependContext: contextMessage };
             }
@@ -684,91 +989,101 @@ User message: ${prompt}
         // Hook signature: (event, ctx) where event has {messages, success, error?, durationMs?}
         api.on('agent_end', async (event, ctx) => {
             try {
-                // Use context from this hook, or fall back to context captured in before_agent_start
-                const effectiveCtx = ctx || currentAgentContext;
+                // Avoid cross-session contamination: only use context carried by this event.
+                const eventSessionKey = typeof event?.sessionKey === 'string' ? event.sessionKey : undefined;
+                const effectiveCtx = ctx || (eventSessionKey ? { sessionKey: eventSessionKey } : undefined);
                 // Check if this provider is excluded
                 if (effectiveCtx?.messageProvider && pluginConfig.excludeProviders?.includes(effectiveCtx.messageProvider)) {
                     debug(`[Hindsight] Skipping retain for excluded provider: ${effectiveCtx.messageProvider}`);
                     return;
                 }
-                // Derive bank ID from context
-                const bankId = deriveBankId(effectiveCtx, pluginConfig);
+                // 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.
+                const sessionKeyForLookup = effectiveCtx?.sessionKey;
+                const senderIdFromCache = !effectiveCtx?.senderId && sessionKeyForLookup
+                    ? senderIdBySession.get(sessionKeyForLookup)
+                    : undefined;
+                const effectiveCtxForRetain = senderIdFromCache ? { ...effectiveCtx, senderId: senderIdFromCache } : effectiveCtx;
+                const bankId = deriveBankId(effectiveCtxForRetain, pluginConfig);
                 debug(`[Hindsight Hook] agent_end triggered - bank: ${bankId}`);
-                // Check event success and messages
-                if (!event.success || !Array.isArray(event.messages) || event.messages.length === 0) {
-                    debug('[Hindsight Hook] Skipping: success:', event.success, 'messages:', event.messages?.length);
+                if (event.success === false) {
+                    debug('[Hindsight Hook] Agent run failed, skipping retention');
                     return;
                 }
-                // Wait for client to be ready
-                const clientGlobal = global.__hindsightClient;
-                if (!clientGlobal) {
-                    console.warn('[Hindsight] Client global not found, skipping retain');
+                if (!Array.isArray(event.context?.sessionEntry?.messages ?? event.messages) || (event.context?.sessionEntry?.messages ?? event.messages ?? []).length === 0) {
+                    debug('[Hindsight Hook] No messages in event, skipping retention');
                     return;
                 }
-                await clientGlobal.waitForReady();
-                // Get client configured for this context's bank (async to handle mission setup)
-                const client = await clientGlobal.getClientForContext(effectiveCtx);
-                if (!client) {
-                    console.warn('[Hindsight] Client not initialized, skipping retain');
+                if (pluginConfig.autoRetain === false) {
+                    debug('[Hindsight Hook] autoRetain is disabled, skipping retention');
                     return;
                 }
-                // --- Chunked retention: only retain every Nth turn ---
-                const retainEveryN = pluginConfig.retainEveryNTurns ?? 10;
-                let messagesToRetain = event.messages;
+                // Chunked retention: skip non-Nth turns and use a sliding window when firing
+                const retainEveryN = pluginConfig.retainEveryNTurns ?? 1;
+                const allMessages = event.context?.sessionEntry?.messages ?? event.messages ?? [];
+                let messagesToRetain = allMessages;
+                let retainFullWindow = false;
                 if (retainEveryN > 1) {
-                    const sessionTrackingKey = `${bankId}:${effectiveCtx?.sessionKey || currentSessionKey || 'session'}`;
+                    const sessionTrackingKey = `${bankId}:${effectiveCtx?.sessionKey || 'session'}`;
                     const turnCount = (turnCountBySession.get(sessionTrackingKey) || 0) + 1;
                     turnCountBySession.set(sessionTrackingKey, turnCount);
+                    if (turnCountBySession.size > MAX_TRACKED_SESSIONS) {
+                        const oldestKey = turnCountBySession.keys().next().value;
+                        if (oldestKey) {
+                            turnCountBySession.delete(oldestKey);
+                        }
+                    }
                     if (turnCount % retainEveryN !== 0) {
-                        const nextRetain = Math.ceil(turnCount / retainEveryN) * retainEveryN;
-                        debug(`[Hindsight Hook] Skipping retain (turn ${turnCount}, next at ${nextRetain})`);
+                        const nextRetainAt = Math.ceil(turnCount / retainEveryN) * retainEveryN;
+                        debug(`[Hindsight Hook] Turn ${turnCount}/${retainEveryN}, skipping retain (next at turn ${nextRetainAt})`);
                         return;
                     }
-                    // Sliding window: N turns of new content + 2-turn overlap for context continuity
-                    const windowSize = retainEveryN * 2 + 4;
-                    messagesToRetain = event.messages.slice(-windowSize);
-                    debug(`[Hindsight Hook] Chunked retain at turn ${turnCount} \u2014 last ${messagesToRetain.length} msgs`);
-                }
-                // Format messages into a transcript
-                const transcript = messagesToRetain
-                    .map((msg) => {
-                    const role = msg.role || 'unknown';
-                    let content = '';
-                    // Handle different content formats
-                    if (typeof msg.content === 'string') {
-                        content = msg.content;
-                    }
-                    else if (Array.isArray(msg.content)) {
-                        content = msg.content
-                            .filter((block) => block.type === 'text')
-                            .map((block) => block.text)
-                            .join('\n');
-                    }
-                    // Strip plugin-injected memory tags to prevent feedback loop
-                    content = stripMemoryTags(content);
-                    return `[role: ${role}]\n${content}\n[${role}:end]`;
-                })
-                    .join('\n\n');
-                if (!transcript.trim() || transcript.length < 10) {
-                    debug('[Hindsight Hook] Transcript too short, skipping');
+                    // Sliding window in turns: N turns + configured overlap turns.
+                    // We slice by actual turn boundaries (user-role messages), so this
+                    // remains stable even when system/tool messages are present.
+                    const overlapTurns = pluginConfig.retainOverlapTurns ?? 0;
+                    const windowTurns = retainEveryN + overlapTurns;
+                    messagesToRetain = sliceLastTurnsByUserBoundary(allMessages, windowTurns);
+                    retainFullWindow = true;
+                    debug(`[Hindsight Hook] Turn ${turnCount}: chunked retain firing (window: ${windowTurns} turns, ${messagesToRetain.length} messages)`);
+                }
+                const retention = prepareRetentionTranscript(messagesToRetain, pluginConfig, retainFullWindow);
+                if (!retention) {
+                    debug('[Hindsight Hook] No messages to retain (filtered/short/no-user)');
+                    return;
+                }
+                const { transcript, messageCount } = retention;
+                // Wait for client to be ready
+                const clientGlobal = global.__hindsightClient;
+                if (!clientGlobal) {
+                    console.warn('[Hindsight] 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');
                     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 || currentSessionKey || 'session'}-${Date.now()}`;
+                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(messagesToRetain.length),
+                        message_count: String(messageCount),
                         channel_type: effectiveCtx?.messageProvider,
                         channel_id: effectiveCtx?.channelId,
                         sender_id: effectiveCtx?.senderId,
                     },
                 });
-                debug(`[Hindsight] Retained ${messagesToRetain.length} messages to bank ${bankId} for session ${documentId}`);
+                debug(`[Hindsight] Retained ${messageCount} messages to bank ${bankId} for session ${documentId}`);
             }
             catch (error) {
                 console.error('[Hindsight] Error retaining messages:', error);
@@ -785,6 +1100,82 @@ User message: ${prompt}
     }
 }
 // Export client getter for tools
+export function prepareRetentionTranscript(messages, pluginConfig, retainFullWindow = false) {
+    if (!messages || messages.length === 0) {
+        return null;
+    }
+    let targetMessages;
+    if (retainFullWindow) {
+        // Chunked retention: retain the full sliding window (already sliced by caller)
+        targetMessages = messages;
+    }
+    else {
+        // Default: retain only the last turn (user message + assistant responses)
+        let lastUserIdx = -1;
+        for (let i = messages.length - 1; i >= 0; i--) {
+            if (messages[i].role === 'user') {
+                lastUserIdx = i;
+                break;
+            }
+        }
+        if (lastUserIdx === -1) {
+            return null; // No user message found in turn
+        }
+        targetMessages = messages.slice(lastUserIdx);
+    }
+    // Role filtering
+    const allowedRoles = new Set(pluginConfig.retainRoles || ['user', 'assistant']);
+    const filteredMessages = targetMessages.filter((m) => allowedRoles.has(m.role));
+    if (filteredMessages.length === 0) {
+        return null; // No messages to retain
+    }
+    // Format messages into a transcript
+    const transcriptParts = filteredMessages
+        .map((msg) => {
+        const role = msg.role || 'unknown';
+        let content = '';
+        // Handle different content formats
+        if (typeof msg.content === 'string') {
+            content = msg.content;
+        }
+        else if (Array.isArray(msg.content)) {
+            content = msg.content
+                .filter((block) => block.type === 'text')
+                .map((block) => block.text)
+                .join('\n');
+        }
+        // Strip plugin-injected memory tags and metadata envelopes to prevent feedback loop
+        content = stripMemoryTags(content);
+        content = stripMetadataEnvelopes(content);
+        return content.trim() ? `[role: ${role}]\n${content}\n[${role}:end]` : null;
+    })
+        .filter(Boolean);
+    const transcript = transcriptParts.join('\n\n');
+    if (!transcript.trim() || transcript.length < 10) {
+        return null; // Transcript too short
+    }
+    return { transcript, messageCount: transcriptParts.length };
+}
+export function sliceLastTurnsByUserBoundary(messages, turns) {
+    if (!Array.isArray(messages) || messages.length === 0 || turns <= 0) {
+        return [];
+    }
+    let userTurnsSeen = 0;
+    let startIndex = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i]?.role === 'user') {
+            userTurnsSeen += 1;
+            if (userTurnsSeen >= turns) {
+                startIndex = i;
+                break;
+            }
+        }
+    }
+    if (startIndex === -1) {
+        return messages;
+    }
+    return messages.slice(startIndex);
+}
 export function getClient() {
     return client;
 }

package/dist/types.d.ts

@@ -24,6 +24,14 @@ export interface MoltbotConfig {
         };
     };
 }
+export interface PluginHookAgentContext {
+    agentId?: string;
+    sessionKey?: string;
+    workspaceDir?: string;
+    messageProvider?: string;
+    channelId?: string;
+    senderId?: string;
+}
 export interface PluginConfig {
     bankMission?: string;
     embedPort?: number;
@@ -40,7 +48,19 @@ export interface PluginConfig {
     bankIdPrefix?: string;
     excludeProviders?: string[];
     autoRecall?: boolean;
+    dynamicBankGranularity?: Array<'agent' | 'provider' | 'channel' | 'user'>;
+    autoRetain?: boolean;
+    retainRoles?: Array<'user' | 'assistant' | 'system' | 'tool'>;
+    recallBudget?: 'low' | 'mid' | 'high';
+    recallMaxTokens?: number;
+    recallTypes?: Array<'world' | 'experience' | 'observation'>;
+    recallRoles?: Array<'user' | 'assistant' | 'system' | 'tool'>;
     retainEveryNTurns?: number;
+    retainOverlapTurns?: number;
+    recallTopK?: number;
+    recallContextTurns?: number;
+    recallMaxQueryChars?: number;
+    recallPromptPreamble?: string;
     debug?: boolean;
 }
 export interface ServiceConfig {
@@ -61,6 +81,8 @@ export interface RetainResponse {
 export interface RecallRequest {
     query: string;
     max_tokens?: number;
+    budget?: 'low' | 'mid' | 'high';
+    types?: Array<'world' | 'experience' | 'observation'>;
 }
 export interface RecallResponse {
     results: MemoryResult[];

package/openclaw.plugin.json

@@ -17,7 +17,7 @@
       },
       "bankMission": {
         "type": "string",
-        "description": "Custom mission/context for the memory bank",
+        "description": "Agent identity/purpose stored on the memory bank. Helps the memory engine understand context for better fact extraction during retain. Set once per bank on first use — this is not a recall prompt.",
         "default": "You are an AI assistant helping users across multiple communication channels (Telegram, Slack, Discord, etc.). Remember user preferences, instructions, and important context from conversations to provide personalized assistance."
       },
       "embedVersion": {
@@ -28,7 +28,15 @@
       "llmProvider": {
         "type": "string",
         "description": "LLM provider for Hindsight memory (e.g. 'openai', 'anthropic', 'gemini', 'groq', 'ollama', 'openai-codex', 'claude-code'). Takes priority over auto-detection but not over HINDSIGHT_API_LLM_PROVIDER env var.",
-        "enum": ["openai", "anthropic", "gemini", "groq", "ollama", "openai-codex", "claude-code"]
+        "enum": [
+          "openai",
+          "anthropic",
+          "gemini",
+          "groq",
+          "ollama",
+          "openai-codex",
+          "claude-code"
+        ]
       },
       "llmModel": {
         "type": "string",
@@ -71,8 +79,119 @@
       },
       "excludeProviders": {
         "type": "array",
-        "items": { "type": "string" },
+        "items": {
+          "type": "string"
+        },
         "description": "Message providers to exclude from recall and retain (e.g. ['telegram', 'discord'])"
+      },
+      "dynamicBankGranularity": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": [
+            "agent",
+            "channel",
+            "user",
+            "provider"
+          ]
+        },
+        "description": "Fields used to derive bank ID. Controls memory isolation granularity. Default: ['agent', 'channel', 'user'].",
+        "default": [
+          "agent",
+          "channel",
+          "user"
+        ]
+      },
+      "autoRetain": {
+        "type": "boolean",
+        "description": "Automatically retain conversation as memories after each interaction. Set to false to disable.",
+        "default": true
+      },
+      "retainRoles": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": [
+            "user",
+            "assistant",
+            "system",
+            "tool"
+          ]
+        },
+        "description": "Message roles to include in retained transcript. Default: ['user', 'assistant'].",
+        "default": [
+          "user",
+          "assistant"
+        ]
+      },
+      "retainEveryNTurns": {
+        "type": "integer",
+        "description": "Retain every Nth turn instead of every turn. 1 = every turn (default). Values > 1 enable chunked retention with a sliding window.",
+        "minimum": 1,
+        "default": 1
+      },
+      "retainOverlapTurns": {
+        "type": "integer",
+        "description": "Extra prior turns to include when chunked retention fires. Window = retainEveryNTurns + retainOverlapTurns. Only applies when retainEveryNTurns > 1.",
+        "minimum": 0,
+        "default": 0
+      },
+      "recallBudget": {
+        "type": "string",
+        "description": "Recall effort level. Higher budgets use more retrieval strategies for better results but take longer.",
+        "enum": ["low", "mid", "high"],
+        "default": "mid"
+      },
+      "recallMaxTokens": {
+        "type": "integer",
+        "description": "Maximum tokens for recall response. Controls how much memory context is injected per turn.",
+        "minimum": 1,
+        "default": 1024
+      },
+      "recallTypes": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": ["world", "experience", "observation"]
+        },
+        "description": "Memory types to recall. Defaults to ['world', 'experience'] — excludes verbose observation entries.",
+        "default": ["world", "experience"]
+      },
+      "recallRoles": {
+        "type": "array",
+        "items": {
+          "type": "string",
+          "enum": ["user", "assistant", "system", "tool"]
+        },
+        "description": "Roles to include when composing contextual recall query. Default: ['user', 'assistant'].",
+        "default": ["user", "assistant"]
+      },
+      "recallContextTurns": {
+        "type": "integer",
+        "minimum": 1,
+        "description": "Number of user turns to include in recall query context. 1 keeps latest-message-only behavior.",
+        "default": 1
+      },
+      "recallMaxQueryChars": {
+        "type": "integer",
+        "minimum": 1,
+        "description": "Maximum character length for composed recall query before calling recall.",
+        "default": 800
+      },
+      "recallTopK": {
+        "type": "integer",
+        "minimum": 1,
+        "description": "Maximum number of memories to inject per turn. Applied after API response as a hard cap."
+      },
+      "recallPromptPreamble": {
+        "type": "string",
+        "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:"
+      },
+      "debug": {
+        "type": "boolean",
+        "description": "Enable debug logging for Hindsight plugin operations.",
+        "default": false
       }
     },
     "additionalProperties": false
@@ -137,6 +256,61 @@
     "excludeProviders": {
       "label": "Excluded Providers",
       "placeholder": "e.g. telegram, discord"
+    },
+    "dynamicBankGranularity": {
+      "label": "Bank Granularity",
+      "placeholder": "e.g. ['agent', 'channel', 'user']"
+    },
+    "autoRetain": {
+      "label": "Auto-Retain",
+      "placeholder": "true (enable auto-retention)"
+    },
+    "retainRoles": {
+      "label": "Retain Roles",
+      "placeholder": "e.g. ['user', 'assistant']"
+    },
+    "retainEveryNTurns": {
+      "label": "Retain Every N Turns",
+      "placeholder": "1 (every turn, default)"
+    },
+    "retainOverlapTurns": {
+      "label": "Retain Overlap Turns",
+      "placeholder": "0 (no overlap, default)"
+    },
+    "recallBudget": {
+      "label": "Recall Budget",
+      "placeholder": "low, mid, or high"
+    },
+    "recallMaxTokens": {
+      "label": "Recall Max Tokens",
+      "placeholder": "1024 (default)"
+    },
+    "recallTypes": {
+      "label": "Recall Types",
+      "placeholder": "e.g. ['world', 'experience']"
+    },
+    "recallRoles": {
+      "label": "Recall Roles",
+      "placeholder": "e.g. ['user', 'assistant']"
+    },
+    "recallContextTurns": {
+      "label": "Recall Context Turns",
+      "placeholder": "1 (latest only, default)"
+    },
+    "recallMaxQueryChars": {
+      "label": "Recall Max Query Chars",
+      "placeholder": "800 (default)"
+    },
+    "recallTopK": {
+      "label": "Recall Top K",
+      "placeholder": "e.g. 5 (no limit by default)"
+    },
+    "recallPromptPreamble": {
+      "label": "Recall Prompt Preamble",
+      "placeholder": "Instruction shown above recalled memories in injected context"
+    },
+    "debug": {
+      "label": "Debug"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectorize-io/hindsight-openclaw",
-  "version": "0.4.15",
+  "version": "0.4.17",
   "description": "Hindsight memory plugin for OpenClaw - biomimetic long-term memory with fact extraction",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -50,5 +50,8 @@
   },
   "engines": {
     "node": ">=22"
+  },
+  "overrides": {
+    "rollup": "^4.59.0"
   }
 }