@etzelm/openclaw-memory-hindsight 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.5.0 (2026-11-10)
+
+### Upgrade notes
+
+- No config change is needed. All new keys default off.
+- The auto-recall query strip is always on. Recall queries change slightly, because host
+  boilerplate is no longer sent.
+- The config schema rejects unknown keys. A config that uses `listToolsWithoutAudience`,
+  `ignoreSessionPatterns`, `recallOnlySessionPatterns`, `recallCacheTtlMs` or
+  `recallFollowupMaxWords` fails validation on 0.3.0 and 0.4.0. Remove those keys before a
+  downgrade.
+
+### Added
+
+- `listToolsWithoutAudience` (default off): list the `hindsight_*` tools for agent sessions whose
+  tool list the host builds without a memory audience. OpenClaw 2026.11.x does this for claude-cli
+  turns (MCP tool projection), so those sessions had no Hindsight tools. A call still resolves its
+  bank only from the host-minted audience and fails without one.
+- `ignoreSessionPatterns` and `recallOnlySessionPatterns` (session-key globs, both default `[]`).
+  An ignored session gets no auto-recall, no auto-retain and no `hindsight_*` tools. A
+  recall-only session gets auto-recall and the read tools (`hindsight_recall`,
+  `hindsight_reflect`, and the knowledge-base read tools when `knowledgeReadTools` is on) even if
+  `skipOperationalSessions` would skip it, but never retains. Ignore wins over recall-only;
+  `excludeProviders`, `temp:` and incognito sessions still win over both. Patterns never select
+  a bank. See README, Configuration.
+- Auto-recall drops host boilerplate from the query (inter-session header, routed-by line,
+  messages-recorded banner, subagent context lines, cron tag, CLI-resumed and automation-repair
+  notices); a message that is only boilerplate no longer triggers a recall.
+- `recallCacheTtlMs` (default `0`, off): per-session cache of auto-recall results, keyed by
+  session, bank and query. Never shared across sessions or banks.
+- `recallFollowupMaxWords` (default `0`, off): short follow-ups skip auto-recall while the session
+  has a recent recall that returned memories, and otherwise recall with the previous user message
+  added to the query. An empty recall never enables the skip. Debug log tags each auto-recall
+  `fresh`, `cached`, `followup-skip` or `followup-expanded`.
+
 ## 0.4.0 (2026-11-09)
 
 ### Upgrade notes

package/README.md

@@ -119,12 +119,26 @@ tool conflict.
 | `retainTags`                | `[]`                 | Tags added to every retained memory (auto-retain, `hindsight_retain`, pre-compaction flush)           |
 | `excludeProviders`          | `[]`                 | Message providers that never recall or retain (for example `heartbeat`)                               |
 | `skipOperationalSessions`   | `true`               | Skip cron, heartbeat and subagent sessions                                                            |
+| `ignoreSessionPatterns`     | `[]`                 | Session-key globs with no recall, retain or `hindsight_*` tools (see below)                           |
+| `recallOnlySessionPatterns` | `[]`                 | Session-key globs that recall and read but never retain (see below)                                   |
 | `agentBankMap`              | `{}`                 | Agent id to bank id, so several agents share one owner bank                                           |
 | `allowInsecureHttp`         | `false`              | Allow plain http to a non-loopback `hindsightApiUrl` (token and conversation text unencrypted)        |
 | `retainQueueEnabled`        | `true`               | Queue auto-retains that fail because Hindsight is unreachable and send them later (see below)         |
 | `retainQueueMaxItems`       | `500`                | Most queued retains kept (1 to 10000); the oldest are dropped first                                   |
 | `retainQueueMaxAgeMs`       | `604800000` (7 days) | Queued retains older than this are dropped                                                            |
+| `recallCacheTtlMs`          | `0` (off)            | Auto-recall cache per session and bank, 0 to 3600000 ms; a repeated query skips the API call          |
+| `recallFollowupMaxWords`    | `0` (off)            | At most N words, no URL or path: skip after a recent recall with hits, else add the prior user turn   |
 | `knowledgeReadTools`        | `false`              | Offer the read-only knowledge-base tools (see below); turning it on needs a gateway restart           |
+| `listToolsWithoutAudience`  | `false`              | List the `hindsight_*` tools when the host builds the tool list without an audience (see below)       |
+
+Session patterns: `*` matches any run of characters except `:`, `**` matches anything including
+`:`, everything else is literal. Patterns match the trimmed session key. `ignoreSessionPatterns`
+sessions get no auto-recall, no auto-retain and no `hindsight_*` tools. `recallOnlySessionPatterns`
+sessions (for example `agent:dev:subagent:**`) get auto-recall, `hindsight_recall`,
+`hindsight_reflect` and, with `knowledgeReadTools`, the knowledge-base read tools, even when
+`skipOperationalSessions` would skip them, but never auto-retain and no `hindsight_retain`.
+`excludeProviders`, `temp:` and incognito sessions win over both lists, and ignore wins over
+recall-only. A pattern never selects a bank; the bank still comes from the memory audience.
 
 Fixed values (not configurable): recall max tokens 1024, query cap 800 characters, recall
 timeout 10 s, retain and reflect timeout 30 s, memory get and knowledge-base tool timeout 10 s
@@ -135,6 +149,15 @@ prompt, so the cached prefix stays stable). Knowledge-base tool caps: a response
 the tree shows 500 entries, then `(truncated, N more entries)`; search shows at most 50 hits
 with snippets cut at 500 characters and names and ids at 200.
 
+`listToolsWithoutAudience`: the claude-cli runtime on OpenClaw 2026.11.x builds a turn's MCP tool
+list before it attaches the turn's memory audience, so every tool factory sees no audience, returns
+null, and `hindsight_*` never reach claude-cli sessions (auto-recall still works; it reads the
+audience from the hook context). With this key on, an agent session with a session key gets the
+tools listed anyway. The host then builds the callable copy with the audience from the run's grant,
+and that copy alone reaches Hindsight; a call that still has no audience fails with an error before
+any request. The session filters (`memoryMode`, incognito, `excludeProviders`,
+`skipOperationalSessions`) apply as before, and an audience for another agent is still refused.
+
 Config changes apply without a restart: the plugin re-reads its entry from the host's current
 config snapshot (`api.runtime.config.current()`), falling back to the register-time
 `api.pluginConfig`. One exception: `knowledgeReadTools` registers its tools at startup, so turning

package/dist/config.js

@@ -1,6 +1,8 @@
 export const RECALL_BUDGETS = ["low", "mid", "high"];
 export const RECALL_TYPES = ["world", "experience", "observation"];
 export const MEMORY_MODES = ["hybrid", "context", "tools"];
+export const MAX_RECALL_CACHE_TTL_MS = 3_600_000;
+export const MAX_RECALL_FOLLOWUP_WORDS = 100;
 export const DEFAULT_RETAIN_QUEUE_MAX_ITEMS = 500;
 export const MAX_RETAIN_QUEUE_MAX_ITEMS = 10_000;
 export const DEFAULT_RETAIN_QUEUE_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
@@ -30,12 +32,17 @@ const CONFIG_KEYS = [
     "retainTags",
     "excludeProviders",
     "skipOperationalSessions",
+    "ignoreSessionPatterns",
+    "recallOnlySessionPatterns",
     "agentBankMap",
     "allowInsecureHttp",
     "retainQueueEnabled",
     "retainQueueMaxItems",
     "retainQueueMaxAgeMs",
     "knowledgeReadTools",
+    "listToolsWithoutAudience",
+    "recallCacheTtlMs",
+    "recallFollowupMaxWords",
 ];
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -93,6 +100,17 @@ function readPositiveInt(cfg, key, fallback, max = Number.MAX_SAFE_INTEGER) {
     }
     return value;
 }
+/** Integer from 0 to max; 0 means off. */
+function readNonNegativeInt(cfg, key, fallback, max) {
+    const value = cfg[key];
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > max) {
+        throw new Error(`${key} must be an integer from 0 to ${max}`);
+    }
+    return value;
+}
 function readBankMap(cfg) {
     const value = cfg.agentBankMap;
     if (value === undefined) {
@@ -201,12 +219,17 @@ export const hindsightConfigSchema = {
             retainTags: readStringList(value, "retainTags") ?? [],
             excludeProviders: readStringList(value, "excludeProviders") ?? [],
             skipOperationalSessions: readBool(value, "skipOperationalSessions", true),
+            ignoreSessionPatterns: readStringList(value, "ignoreSessionPatterns") ?? [],
+            recallOnlySessionPatterns: readStringList(value, "recallOnlySessionPatterns") ?? [],
             agentBankMap: readBankMap(value),
             allowInsecureHttp,
             retainQueueEnabled: readBool(value, "retainQueueEnabled", true),
             retainQueueMaxItems: readPositiveInt(value, "retainQueueMaxItems", DEFAULT_RETAIN_QUEUE_MAX_ITEMS, MAX_RETAIN_QUEUE_MAX_ITEMS),
             retainQueueMaxAgeMs: readPositiveInt(value, "retainQueueMaxAgeMs", DEFAULT_RETAIN_QUEUE_MAX_AGE_MS),
             knowledgeReadTools: readBool(value, "knowledgeReadTools", false),
+            listToolsWithoutAudience: readBool(value, "listToolsWithoutAudience", false),
+            recallCacheTtlMs: readNonNegativeInt(value, "recallCacheTtlMs", 0, MAX_RECALL_CACHE_TTL_MS),
+            recallFollowupMaxWords: readNonNegativeInt(value, "recallFollowupMaxWords", 0, MAX_RECALL_FOLLOWUP_WORDS),
         };
     },
 };

package/dist/index.js

@@ -12,10 +12,15 @@ import { isMaintenanceTurn, routeAudience, sessionUsesMemory } from "./routing.j
 import { resolveLearnRegistrar } from "./sdk-types.js";
 import { createHindsightService } from "./service.js";
 import { createFlushDeduper, createKnowledgePageTool, createKnowledgeSearchTool, createKnowledgeTreeTool, createRecallTool, createReflectTool, createRetainTool, KB_PAGE_TOOL, KB_SEARCH_TOOL, KB_TREE_TOOL, RECALL_TOOL, REFLECT_TOOL, RETAIN_TOOL, } from "./tools.js";
-import { buildRecallContext, extractRecallQuery, isEphemeralOperationalText, prepareRetentionTranscript, retainStartIndex, runStartMarker, } from "./transcript.js";
+import { buildRecallContext, expandFollowupQuery, extractRecallQuery, isEphemeralOperationalText, isShortFollowup, prepareRetentionTranscript, previousUserQuery, retainStartIndex, runStartMarker, } from "./transcript.js";
 export const PLUGIN_ID = "hindsight-native";
 // Bounds per-session run markers; one entry per active session is enough.
 const MAX_RUN_MARKERS = 1_000;
+// Bounds the auto-recall cache; one entry per active session, oldest dropped first.
+const MAX_RECALL_CACHE_SESSIONS = 512;
+function queryDigest(query) {
+    return createHash("sha256").update(query).digest("hex");
+}
 /**
  * Reads `plugins.entries[<id>].config` from a runtime config snapshot. Returns undefined when the
  * snapshot has no entry, so callers fall back to the register-time `api.pluginConfig`.
@@ -104,6 +109,8 @@ export default definePluginEntry({
         // Per session: where the current run started, kept for the whole run (by runId) so a second
         // agent_end for the run (host continuation after a retry, or a re-delivery) re-sends all of it.
         const runStartBySession = new Map();
+        // Last auto-recall per session (never shared across sessions; the bank is checked on read).
+        const recallCache = new Map();
         const capability = {
             providerRuntime: createHindsightProviderRuntime({
                 providerId: PLUGIN_ID,
@@ -168,6 +175,7 @@ export default definePluginEntry({
                 !sessionUsesMemory(config, {
                     sessionKey,
                     messageProvider: ctx.messageProvider,
+                    purpose: "recall",
                 })) {
                 return undefined;
             }
@@ -182,29 +190,71 @@ export default definePluginEntry({
             }
             try {
                 ctx.assertMemoryAudienceCurrent?.();
-                // Metrics count the Hindsight request only. A host assert that throws (audience changed,
-                // hook invocation stale) is host lifecycle, not a recall outcome, so it records nothing.
-                const recallStarted = performance.now();
+                const ttl = config.recallCacheTtlMs;
+                const now = Date.now();
+                const cached = ttl > 0 && sessionKey ? recallCache.get(sessionKey) : undefined;
+                const live = cached && cached.bankId === route.bankId && now - cached.at < ttl;
+                const followup = isShortFollowup(query, config.recallFollowupMaxWords);
+                if (followup && live && cached.results.length > 0) {
+                    api.logger.debug?.("memory-hindsight: auto-recall source=followup-skip");
+                    return undefined;
+                }
+                let recallQuery = query;
+                let source = "fresh";
+                if (followup) {
+                    const previous = previousUserQuery(event.messages, query);
+                    if (previous) {
+                        recallQuery = expandFollowupQuery(previous, query);
+                        source = "followup-expanded";
+                    }
+                }
+                const queryHash = queryDigest(recallQuery);
                 let results;
-                try {
-                    results = await service.client.recall(route.bankId, query, {
-                        budget: config.recallBudget,
-                        maxTokens: RECALL_MAX_TOKENS,
-                        ...(config.recallTypes ? { types: config.recallTypes } : {}),
-                        ...(config.preferObservations === undefined
-                            ? {}
-                            : { preferObservations: config.preferObservations }),
-                        signal: AbortSignal.timeout(RECALL_TIMEOUT_MS),
-                    });
+                if (live && cached.queryHash === queryHash) {
+                    results = cached.results;
+                    source = "cached";
                 }
-                catch (error) {
-                    metrics.recordRecall(ctx.agentId, route.bankId, isBankNotFound(error) ? "empty" : isTimeoutError(error) ? "timeout" : "error", performance.now() - recallStarted);
-                    throw error;
+                else {
+                    // Metrics count the Hindsight request only. A host assert that throws (audience changed,
+                    // hook invocation stale) is host lifecycle, not a recall outcome, so it records nothing.
+                    const recallStarted = performance.now();
+                    try {
+                        results = await service.client.recall(route.bankId, recallQuery, {
+                            budget: config.recallBudget,
+                            maxTokens: RECALL_MAX_TOKENS,
+                            ...(config.recallTypes ? { types: config.recallTypes } : {}),
+                            ...(config.preferObservations === undefined
+                                ? {}
+                                : { preferObservations: config.preferObservations }),
+                            signal: AbortSignal.timeout(RECALL_TIMEOUT_MS),
+                        });
+                    }
+                    catch (error) {
+                        metrics.recordRecall(ctx.agentId, route.bankId, isBankNotFound(error) ? "empty" : isTimeoutError(error) ? "timeout" : "error", performance.now() - recallStarted);
+                        throw error;
+                    }
+                    const recallMs = performance.now() - recallStarted;
+                    ctx.assertMemoryAudienceCurrent?.();
+                    ctx.hookInvocation?.assertActive();
+                    metrics.recordRecall(ctx.agentId, route.bankId, results.length === 0 ? "empty" : "injected", recallMs);
+                    if (ttl > 0 && sessionKey) {
+                        recallCache.delete(sessionKey);
+                        recallCache.set(sessionKey, {
+                            bankId: route.bankId,
+                            queryHash,
+                            results,
+                            at: Date.now(),
+                        });
+                        if (recallCache.size > MAX_RECALL_CACHE_SESSIONS) {
+                            recallCache.delete(recallCache.keys().next().value);
+                        }
+                    }
+                }
+                api.logger.debug?.(`memory-hindsight: auto-recall source=${source}`);
+                if (source === "cached") {
+                    ctx.assertMemoryAudienceCurrent?.();
+                    ctx.hookInvocation?.assertActive();
                 }
-                const recallMs = performance.now() - recallStarted;
-                ctx.assertMemoryAudienceCurrent?.();
-                ctx.hookInvocation?.assertActive();
-                metrics.recordRecall(ctx.agentId, route.bankId, results.length === 0 ? "empty" : "injected", recallMs);
                 if (results.length === 0) {
                     return undefined;
                 }
@@ -249,6 +299,7 @@ export default definePluginEntry({
                 !sessionUsesMemory(config, {
                     sessionKey,
                     messageProvider: ctx.messageProvider,
+                    purpose: "retain",
                 })) {
                 return;
             }
@@ -309,6 +360,7 @@ export default definePluginEntry({
             const key = ctx.sessionKey ?? event.sessionKey;
             if (key) {
                 runStartBySession.delete(key);
+                recallCache.delete(key);
             }
         });
         api.registerService({
@@ -330,6 +382,7 @@ export default definePluginEntry({
             stop: () => {
                 service.stop();
                 runStartBySession.clear();
+                recallCache.clear();
                 api.logger.info("memory-hindsight: stopped");
             },
         });

package/dist/routing.js

@@ -43,15 +43,60 @@ export function routeAudience(agentId, audience, bankMap) {
 }
 const OPERATIONAL_SESSION_RE = /^agent:[^:]+:(cron|heartbeat|subagent):/;
 const OPERATIONAL_PROVIDERS = new Set(["cron", "heartbeat", "subagent"]);
-/** Session filter shared by auto-recall, auto-retain and tool registration. */
-export function sessionUsesMemory(config, params) {
-    const { sessionKey, messageProvider } = params;
+const globCache = new Map();
+/**
+ * Session-key glob: `*` matches any run of characters except ":", `**` matches anything
+ * including ":", everything else is literal.
+ */
+function sessionGlobRegExp(glob) {
+    let re = globCache.get(glob);
+    if (!re) {
+        let source = "";
+        for (let i = 0; i < glob.length; i += 1) {
+            const ch = glob[i];
+            if (ch === "*") {
+                if (glob[i + 1] === "*") {
+                    source += ".*";
+                    i += 1;
+                }
+                else {
+                    source += "[^:]*";
+                }
+            }
+            else {
+                source += ch.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+            }
+        }
+        re = new RegExp(`^${source}$`, "s");
+        globCache.set(glob, re);
+    }
+    return re;
+}
+/** True when the trimmed session key matches any glob; a missing key matches nothing. */
+export function matchesSessionPattern(sessionKey, globs) {
+    const key = sessionKey?.trim();
+    return Boolean(key) && globs.some((glob) => sessionGlobRegExp(glob).test(key));
+}
+/**
+ * Session filter shared by auto-recall, auto-retain and tool registration. Patterns only
+ * decide whether a session uses memory; they never select a bank.
+ */
+export function sessionUsesMemory(config, 
+// A missing purpose is treated as "retain", the stricter side.
+params) {
+    const { sessionKey, messageProvider, purpose } = params;
     if (messageProvider && config.excludeProviders.includes(messageProvider)) {
         return false;
     }
     if (sessionKey?.startsWith("temp:")) {
         return false;
     }
+    if (matchesSessionPattern(sessionKey, config.ignoreSessionPatterns ?? [])) {
+        return false;
+    }
+    if (matchesSessionPattern(sessionKey, config.recallOnlySessionPatterns ?? [])) {
+        return purpose === "recall";
+    }
     if (!config.skipOperationalSessions) {
         return true;
     }

package/dist/tools.js

@@ -24,17 +24,43 @@ function requiredString(params, name) {
     }
     return value.trim();
 }
+export const NO_AUDIENCE_AT_CALL = "This session has no host memory audience for this call, so Hindsight memory is unavailable.";
+/**
+ * A tool listed for a session whose tool list the host built without a memory audience. Reading
+ * `bankId` throws, so `execute` fails before any request; the host builds the callable tool again
+ * with the session's audience, and that copy gets a real bank.
+ */
+function deferredBank() {
+    return {
+        get bankId() {
+            throw new Error(NO_AUDIENCE_AT_CALL);
+        },
+    };
+}
 /**
  * Resolves the bank for one tool context, or null when the session must not get the tool.
  * The bank comes only from the host-minted audience; the model never names a bank.
  */
-function resolveToolBank(service, ctx) {
+function resolveToolBank(service, ctx, purpose) {
     const config = service.config();
     if (config.memoryMode === "context" ||
         isIncognitoSessionKey(ctx.sessionKey) ||
-        !sessionUsesMemory(config, { sessionKey: ctx.sessionKey, messageProvider: ctx.messageChannel })) {
+        !sessionUsesMemory(config, {
+            sessionKey: ctx.sessionKey,
+            messageProvider: ctx.messageChannel,
+            purpose,
+        })) {
         return null;
     }
+    // Some hosts list a session's tools before they attach its audience (claude-cli MCP tool
+    // projection on OpenClaw 2026.11.x). Opt-in: list the tool for an agent session with a key, and
+    // let only the audience-bearing copy built for the call reach Hindsight.
+    if (config.listToolsWithoutAudience &&
+        !ctx.memoryAudience &&
+        ctx.agentId?.trim() &&
+        ctx.sessionKey?.trim()) {
+        return deferredBank();
+    }
     const route = routeAudience(ctx.agentId, ctx.memoryAudience, config.agentBankMap);
     return route.ok ? { bankId: route.bankId } : null;
 }
@@ -69,7 +95,7 @@ export function flushDocumentId(flushId, content) {
     return `openclaw-flush:${digest.slice(0, 32)}`;
 }
 export function createRetainTool(service, deduper, ctx) {
-    const bank = resolveToolBank(service, ctx);
+    const bank = resolveToolBank(service, ctx, "retain");
     if (!bank) {
         return null;
     }
@@ -134,7 +160,7 @@ export function createRetainTool(service, deduper, ctx) {
     };
 }
 export function createRecallTool(service, ctx) {
-    const bank = resolveToolBank(service, ctx);
+    const bank = resolveToolBank(service, ctx, "recall");
     if (!bank) {
         return null;
     }
@@ -176,7 +202,7 @@ export function createRecallTool(service, ctx) {
     };
 }
 export function createReflectTool(service, ctx) {
-    const bank = resolveToolBank(service, ctx);
+    const bank = resolveToolBank(service, ctx, "recall");
     if (!bank) {
         return null;
     }
@@ -220,7 +246,7 @@ export const KB_NAME_MAX_CHARS = 200;
 const KB_TREE_MAX_DEPTH = 32;
 /** The knowledge tools are opt-in and otherwise follow the recall tools' bank routing. */
 function resolveKnowledgeBank(service, ctx) {
-    return service.config().knowledgeReadTools ? resolveToolBank(service, ctx) : null;
+    return service.config().knowledgeReadTools ? resolveToolBank(service, ctx, "recall") : null;
 }
 /** Server text as one line, so a name or snippet cannot forge extra list entries. */
 function oneLine(value, maxChars = Number.MAX_SAFE_INTEGER) {

package/dist/transcript.js

@@ -116,22 +116,89 @@ export function isEphemeralOperationalText(text) {
     return OPERATIONAL_TEXT_PATTERNS.some((pattern) => pattern.test(normalized));
 }
 const MIN_QUERY_CHARS = 5;
+// Optional host timestamp prefix some of these lines carry, as in `[Wed 2026-10-28 19:24 PDT] `.
+const BOILERPLATE_TS = "(?:\\[(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun)[^\\]\\n]*\\]\\s*)?";
+const BOILERPLATE_PATTERNS = [
+    // Inter-session header, routed-by line, subagent tags, banners and scheduler notices.
+    /^\[Inter-session message\][^\n]*(?:\n|$)/gm,
+    /^This content was routed by OpenClaw[^\n]*(?:\n|$)/gm,
+    /^\[OpenClaw: \d+ (?:messages recorded|earlier messages|messages occurred)[^\n]*\](?:\n|$)/gm,
+    /^\[Subagent Context\][^\n]*(?:\n|$)/gm,
+    /^Every subagent in this batch[^\n]*(?:\n|$)/gm,
+    // Only the tag goes; the reminder text after it stays.
+    /^\[cron:[0-9a-f-]{8,} [^\]\n]*\][ \t]*/gm,
+    new RegExp(`^${BOILERPLATE_TS}OpenClaw resumed this CLI session[^\\n]*(?:\\n|$)`, "gm"),
+    new RegExp(`^${BOILERPLATE_TS}Automation repair request from the scheduler, not a user message\\.[^\\n]*(?:\\n|$)`, "gm"),
+];
+/** Removes host-generated boilerplate lines that carry no user intent. */
+export function stripRecallBoilerplate(text) {
+    let out = text;
+    for (const pattern of BOILERPLATE_PATTERNS) {
+        out = out.replace(pattern, "");
+    }
+    return out.trim();
+}
+/** Cleaned recall text for one message, or null when too short or not user text. */
+function cleanRecallCandidate(candidate) {
+    let cleaned = stripRecallBoilerplate(cleanMessageText(candidate));
+    cleaned = cleaned.replace(/^(?:System:.*\n)+\n?/, "");
+    cleaned = cleaned.replace(/\n\[from:[^\]]*\]\s*$/, "").trim();
+    if (cleaned.length >= MIN_QUERY_CHARS && !/^\s*system:/i.test(cleaned)) {
+        return cleaned.slice(0, RECALL_MAX_QUERY_CHARS);
+    }
+    return null;
+}
 /** The user's current request with host envelopes removed and capped, or null when too short. */
 export function extractRecallQuery(currentUserMessage, prompt) {
-    const candidates = [currentUserMessage, prompt];
-    for (const candidate of candidates) {
+    for (const candidate of [currentUserMessage, prompt]) {
         if (!candidate) {
             continue;
         }
-        let cleaned = cleanMessageText(candidate);
-        cleaned = cleaned.replace(/^(?:System:.*\n)+\n?/, "");
-        cleaned = cleaned.replace(/\n\[from:[^\]]*\]\s*$/, "").trim();
-        if (cleaned.length >= MIN_QUERY_CHARS && !/^\s*system:/i.test(cleaned)) {
-            return cleaned.slice(0, RECALL_MAX_QUERY_CHARS);
+        const cleaned = cleanRecallCandidate(candidate);
+        if (cleaned) {
+            return cleaned;
         }
     }
     return null;
 }
+/** True for a short message with no URL or path: it leans on the turn before it. */
+export function isShortFollowup(query, maxWords) {
+    if (maxWords < 1 || /\/|~\/|http/i.test(query)) {
+        return false;
+    }
+    return query.split(/\s+/).filter(Boolean).length <= maxWords;
+}
+/**
+ * The user message before the current one, cleaned like the query. The host may or may not list
+ * the current message last, so a trailing user message equal to the query is skipped.
+ */
+export function previousUserQuery(messages, query) {
+    if (!Array.isArray(messages)) {
+        return null;
+    }
+    let skippedCurrent = false;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (asMessage(message)?.role !== "user") {
+            continue;
+        }
+        const cleaned = cleanRecallCandidate(messageText(message));
+        if (!cleaned) {
+            continue;
+        }
+        if (!skippedCurrent && cleaned === query) {
+            skippedCurrent = true;
+            continue;
+        }
+        return isEphemeralOperationalText(cleaned) ? null : cleaned;
+    }
+    return null;
+}
+/** Previous user message plus the follow-up, capped with the follow-up kept whole. */
+export function expandFollowupQuery(previous, followup) {
+    const room = RECALL_MAX_QUERY_CHARS - followup.length - 1;
+    return room > 0 ? `${previous.slice(0, room)}\n${followup}` : followup;
+}
 function formatOccurred(start, end) {
     if (start && end) {
         return start === end ? ` [occurred: ${start}]` : ` [occurred: ${start} -> ${end}]`;

package/openclaw.plugin.json

@@ -72,6 +72,16 @@
       "help": "Queued retains older than this are dropped (default 7 days)",
       "advanced": true
     },
+    "recallCacheTtlMs": {
+      "label": "Recall Cache TTL (ms)",
+      "help": "Serve a repeated auto-recall query from a per-session cache for this long; 0 turns the cache off",
+      "advanced": true
+    },
+    "recallFollowupMaxWords": {
+      "label": "Recall Follow-up Max Words",
+      "help": "Messages this short (no URL or path) skip auto-recall while the session has a recent non-empty recall, else recall with the previous user message added; 0 turns it off",
+      "advanced": true
+    },
     "retainMission": {
       "label": "Retain Mission",
       "help": "Applied to each bank before its first write: what Hindsight should extract",
@@ -86,6 +96,11 @@
       "label": "Knowledge Base Read Tools",
       "help": "Offer hindsight_get_knowledge_base_tree, hindsight_search_knowledge_base and hindsight_get_knowledge_page on the same bank as hindsight_recall",
       "advanced": true
+    },
+    "listToolsWithoutAudience": {
+      "label": "List Tools Without Audience",
+      "help": "List the hindsight_* tools when the host builds a session's tool list before it attaches the memory audience (claude-cli sessions on OpenClaw 2026.11.x). Calls still need the audience",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -152,6 +167,22 @@
       "skipOperationalSessions": {
         "type": "boolean"
       },
+      "ignoreSessionPatterns": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "default": [],
+        "description": "Session-key globs that get no auto-recall, no auto-retain and no hindsight_* tools. `*` matches any run of characters except ':', `**` matches anything including ':'. Checked after excludeProviders, temp: and incognito, and before recallOnlySessionPatterns. Never selects a bank"
+      },
+      "recallOnlySessionPatterns": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "default": [],
+        "description": "Session-key globs that get auto-recall and the read tools (hindsight_recall, hindsight_reflect, knowledge-base read tools) even when skipOperationalSessions would skip them, but never auto-retain and no hindsight_retain tool. Same glob syntax as ignoreSessionPatterns. Never selects a bank"
+      },
       "retainQueueEnabled": {
         "type": "boolean",
         "default": true,
@@ -170,11 +201,30 @@
         "default": 604800000,
         "description": "Queued retains older than this many milliseconds are dropped (default 7 days)"
       },
+      "recallCacheTtlMs": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 3600000,
+        "default": 0,
+        "description": "Auto-recall cache lifetime in milliseconds, per session and bank (same query within this time is served without an API call); 0 = off. Also bounds how long a recall counts for recallFollowupMaxWords"
+      },
+      "recallFollowupMaxWords": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 100,
+        "default": 0,
+        "description": "A message with at most this many words and no URL or path is a short follow-up. Within recallCacheTtlMs of a recall that returned memories it skips auto-recall; otherwise the query is the previous user message plus the follow-up. Needs recallCacheTtlMs > 0 to skip; 0 = off"
+      },
       "knowledgeReadTools": {
         "type": "boolean",
         "default": false,
         "description": "Offer the read-only knowledge-base tools (tree, search, page) on the session's own memory bank"
       },
+      "listToolsWithoutAudience": {
+        "type": "boolean",
+        "default": false,
+        "description": "List the hindsight_* tools for an agent session whose tool list the host builds without its memory audience (claude-cli MCP tool projection on OpenClaw 2026.11.x). The bank still comes only from the audience: a call without one fails before any request"
+      },
       "agentBankMap": {
         "type": "object",
         "additionalProperties": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etzelm/openclaw-memory-hindsight",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Native Hindsight memory engine for OpenClaw: memory slot provider runtime, auto-recall, auto-retain, pre-compaction flush and hindsight_* agent tools.",
   "keywords": [
     "hindsight",