@etzelm/openclaw-memory-hindsight 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,57 @@
 # 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
+
+- No config change is needed. The plugin now serves Prometheus metrics at
+  `GET /plugins/hindsight-native/metrics` on the Gateway port. To collect them, add a scrape job
+  for that path that sends a Gateway token with `operator.read`. Without a scrape job nothing
+  changes.
+
+### Added
+
+- Gateway metrics: Prometheus text at `GET /plugins/hindsight-native/metrics` on the Gateway
+  port (Gateway auth, `operator.read`). Auto-recall and auto-retain counts by outcome with
+  latency histograms, and retain queue depth, replays and drops. Labels are `agent` and `bank`
+  plus fixed outcome and reason values; conversation banks share one label per owner bank.
+  See README, Gateway metrics.
+
 ## 0.3.0 (2026-11-08)
 
 ### 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
@@ -236,6 +259,40 @@ Host tool listings can therefore show them while the key is off: the manifest's
 only test that a key is present, not that it is `true`, so they cannot express this key. The
 write tools (create folder, create page, update, delete) are not ported.
 
+### Gateway metrics
+
+The plugin serves Prometheus text at `GET /plugins/hindsight-native/metrics` on the Gateway
+port. The route uses Gateway auth and needs `operator.read` (or `operator.write` /
+`operator.admin`), the same as `diagnostics-prometheus`, so scrape it with the token you use
+for `/api/diagnostics/prometheus`. `diagnostics-prometheus` renders only core diagnostic
+events and has no plugin metric surface, which is why this is a separate path. There is no
+config key; counters live in memory and reset when the Gateway restarts.
+
+| Series (`openclaw_hindsight_` prefix) | Type      | Labels                     |
+| ------------------------------------- | --------- | -------------------------- |
+| `recall_total`                        | counter   | `agent`, `bank`, `outcome` |
+| `recall_duration_seconds`             | histogram | `agent`, `bank`            |
+| `retain_total`                        | counter   | `agent`, `bank`, `outcome` |
+| `retain_duration_seconds`             | histogram | `agent`, `bank`            |
+| `retain_queue_depth`                  | gauge     | `bank`                     |
+| `retain_queue_replays_total`          | counter   | `bank`, `outcome`          |
+| `retain_queue_drops_total`            | counter   | `bank`, `reason`           |
+
+- Recall counts the auto-recall request only: `injected`, `empty` (no results or no bank yet),
+  `timeout`, `error`. A recall the host cancels (audience changed, hook invocation stale) is
+  not counted. Retain counts auto-retain only: `sent`, `queued`, `timeout`, `error`. Tool
+  calls are not counted.
+- The latency histograms cover every outcome, so timeouts and fast `queued` retains are in the
+  same quantiles as successful calls.
+- Replays: `delivered`, or `deferred` (Hindsight unreachable, item kept). Drops count retains
+  that are lost: `limit` (`retainQueueMaxItems`, `retainQueueMaxAgeMs` or the size bound),
+  `too_large` (the live write failed and the item is over the queue's size bound), `rejected`
+  (a 4xx on replay).
+- `agent` is the normalized agent id. `bank` is the owner bank; every conversation bank of
+  that owner shares one `<bank>::conv` label. Values that are not label-safe read `unknown`.
+  Past 200 label sets per metric family, new `agent` and `bank` values fold into `other`;
+  `outcome` and `reason` keep their value. No session ids, document ids or text.
+
 ### Mapping from `@vectorize-io/hindsight-openclaw`
 
 | Vendor key                                                                                                                                                                                                                                                                                                        | Here                                                                                                      |

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

@@ -6,15 +6,21 @@ import { asOptionalRecord } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { isBankNotFound } from "./client.js";
 import { hasUnresolvedToken, hindsightConfigSchema, isPlainHttpRemote, RECALL_MAX_TOKENS, RECALL_TIMEOUT_MS, RETAIN_SOURCE, RETAIN_TIMEOUT_MS, } from "./config.js";
 import { createLearnContribution, createLegacyLearnFields, createProviderFlushPlanResolver, RECALL_TOOL_NAMES, } from "./memory-capability.js";
+import { createMetricsRouteHandler, HindsightMetrics, isTimeoutError, METRICS_ROUTE_PATH, } from "./metrics.js";
 import { createHindsightProviderRuntime } from "./provider-runtime.js";
 import { isMaintenanceTurn, routeAudience, sessionUsesMemory } from "./routing.js";
 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`.
@@ -80,14 +86,31 @@ export default definePluginEntry({
                 return startupConfig;
             }
         };
+        const metrics = new HindsightMetrics();
         const service = createHindsightService({
             config: currentConfig,
             logger: api.logger,
+            metrics,
+        });
+        // Gateway-side metrics on the gateway port, behind gateway auth (see metrics.ts for why this
+        // is a plugin route and not diagnostics-prometheus). The floor host has the method; the check
+        // only keeps a host or test double without it from failing registration.
+        if (typeof api.registerHttpRoute !== "function") {
+            api.logger.debug?.("memory-hindsight: host has no registerHttpRoute; metrics route not served");
+        }
+        api.registerHttpRoute?.({
+            path: METRICS_ROUTE_PATH,
+            auth: "gateway",
+            match: "exact",
+            gatewayRuntimeScopeSurface: "trusted-operator",
+            handler: createMetricsRouteHandler(metrics, () => service.retainQueueDepth()),
         });
         const flushDeduper = createFlushDeduper();
         // 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,
@@ -152,6 +175,7 @@ export default definePluginEntry({
                 !sessionUsesMemory(config, {
                     sessionKey,
                     messageProvider: ctx.messageProvider,
+                    purpose: "recall",
                 })) {
                 return undefined;
             }
@@ -166,17 +190,71 @@ export default definePluginEntry({
             }
             try {
                 ctx.assertMemoryAudienceCurrent?.();
-                const 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),
-                });
-                ctx.assertMemoryAudienceCurrent?.();
-                ctx.hookInvocation?.assertActive();
+                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;
+                if (live && cached.queryHash === queryHash) {
+                    results = cached.results;
+                    source = "cached";
+                }
+                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();
+                }
                 if (results.length === 0) {
                     return undefined;
                 }
@@ -221,6 +299,7 @@ export default definePluginEntry({
                 !sessionUsesMemory(config, {
                     sessionKey,
                     messageProvider: ctx.messageProvider,
+                    purpose: "retain",
                 })) {
                 return;
             }
@@ -238,6 +317,7 @@ export default definePluginEntry({
             // so a continuation or a re-delivery replaces the document with the whole run.
             const runPart = sanitizeDocumentIdPart(runId, `${Date.now()}`);
             const documentId = `openclaw:${sanitizeDocumentIdPart(sessionKey, "session")}-${sessionKeyDigest(sessionKey)}:run:${runPart}`;
+            const retainStarted = performance.now();
             try {
                 // No ctx.assertMemoryAudienceCurrent() here. The host starts agent_end handlers without
                 // awaiting them (runAgentEndSideEffectsAsync -> void runAgentEnd, after awaiting the
@@ -264,9 +344,11 @@ export default definePluginEntry({
                         ...(ctx.channelId ? { channel_id: ctx.channelId } : {}),
                     },
                 }, signal);
+                metrics.recordRetain(ctx.agentId, route.bankId, outcome, performance.now() - retainStarted);
                 api.logger.debug?.(`memory-hindsight: ${outcome === "sent" ? "retained" : "queued"} ${retention.messageCount} messages (${route.audience.kind})`);
             }
             catch (error) {
+                metrics.recordRetain(ctx.agentId, route.bankId, isTimeoutError(error) ? "timeout" : "error", performance.now() - retainStarted);
                 api.logger.warn?.(`memory-hindsight: auto-retain failed: ${formatErrorMessage(error)}`);
             }
         });
@@ -278,6 +360,7 @@ export default definePluginEntry({
             const key = ctx.sessionKey ?? event.sessionKey;
             if (key) {
                 runStartBySession.delete(key);
+                recallCache.delete(key);
             }
         });
         api.registerService({
@@ -299,6 +382,7 @@ export default definePluginEntry({
             stop: () => {
                 service.stop();
                 runStartBySession.clear();
+                recallCache.clear();
                 api.logger.info("memory-hindsight: stopped");
             },
         });

package/dist/metrics.js

@@ -0,0 +1,197 @@
+import { normalizeDiagnosticValue } from "openclaw/plugin-sdk/diagnostic-runtime";
+import { getPluginRuntimeGatewayRequestScope } from "openclaw/plugin-sdk/plugin-runtime";
+import { normalizeAgentIdStrict } from "openclaw/plugin-sdk/routing";
+/**
+ * Gateway-side metrics for auto-recall, auto-retain and the retain queue, rendered as Prometheus
+ * text on a gateway-auth plugin route. diagnostics-prometheus renders only core diagnostic events
+ * and has no plugin metric surface, so the plugin serves its own series on the gateway port.
+ * Labels are agent and bank plus fixed enums; never session ids, document ids or text.
+ */
+export const METRICS_ROUTE_PATH = "/plugins/hindsight-native/metrics";
+const PREFIX = "openclaw_hindsight_";
+// Seconds. Recall times out at 10 s, retain at 30 s.
+export const LATENCY_BUCKETS = [0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30];
+// Label sets per family before new agent and bank values fold into "other"; agents and banks come
+// from config. Outcome and reason keep their value, so the bound grows by the enum size at most.
+export const MAX_SERIES_PER_FAMILY = 200;
+const OTHER = "other";
+const FOLDED_LABELS = new Set(["agent", "bank"]);
+/** Agent label: the normalized agent id, or "unknown" when it is missing or not label-safe. */
+export function agentLabel(agentId) {
+    // The guard runs first: normalizing would turn a session-shaped value into a safe-looking id.
+    // The strict form never falls back to the default agent, so an odd id reads unknown, not main.
+    const safe = normalizeDiagnosticValue(agentId);
+    if (safe === "unknown") {
+        return safe;
+    }
+    const normalized = normalizeAgentIdStrict(safe);
+    return normalized.ok ? normalized.value : "unknown";
+}
+/**
+ * Bank label. A conversation bank (`<owner>::conv::<digest>`, one per root session) folds into
+ * `<owner>::conv`, so the label set stays as small as the configured agents and bank map.
+ */
+export function bankLabel(bankId) {
+    if (!bankId) {
+        return "unknown";
+    }
+    const conv = bankId.indexOf("::conv::");
+    return normalizeDiagnosticValue(conv >= 0 ? `${bankId.slice(0, conv)}::conv` : bankId);
+}
+/** True for the error an `AbortSignal.timeout` fetch rejects with. */
+export function isTimeoutError(error) {
+    return error?.name === "TimeoutError";
+}
+function labelKey(labels) {
+    return JSON.stringify(Object.entries(labels));
+}
+function escapeLabelValue(value) {
+    return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n");
+}
+function formatLabels(labels, extra) {
+    const pairs = Object.entries(labels);
+    if (extra) {
+        pairs.push(extra);
+    }
+    if (pairs.length === 0) {
+        return "";
+    }
+    return `{${pairs.map(([k, v]) => `${k}="${escapeLabelValue(v)}"`).join(",")}}`;
+}
+/** Bounded map of label set to state; past the bound every new set lands on the "other" set. */
+class Series {
+    create;
+    entries = new Map();
+    constructor(create) {
+        this.create = create;
+    }
+    get(labels) {
+        let key = labelKey(labels);
+        let entry = this.entries.get(key);
+        if (!entry) {
+            if (this.entries.size >= MAX_SERIES_PER_FAMILY) {
+                labels = Object.fromEntries(Object.entries(labels).map(([k, v]) => [k, FOLDED_LABELS.has(k) ? OTHER : v]));
+                key = labelKey(labels);
+                entry = this.entries.get(key);
+            }
+            if (!entry) {
+                entry = { labels, value: this.create() };
+                this.entries.set(key, entry);
+            }
+        }
+        return entry.value;
+    }
+    values() {
+        return [...this.entries.values()];
+    }
+}
+function newHistogram() {
+    return { buckets: LATENCY_BUCKETS.map(() => 0), sum: 0, count: 0 };
+}
+function formatNumber(value) {
+    return Number.isFinite(value) ? String(value) : value > 0 ? "+Inf" : "-Inf";
+}
+export class HindsightMetrics {
+    recalls = new Series(() => ({ n: 0 }));
+    recallLatency = new Series(newHistogram);
+    retains = new Series(() => ({ n: 0 }));
+    retainLatency = new Series(newHistogram);
+    replays = new Series(() => ({ n: 0 }));
+    drops = new Series(() => ({ n: 0 }));
+    // Kept across scrapes, so a bank whose queue drained reads 0 instead of disappearing.
+    depth = new Series(() => ({ n: 0 }));
+    recordRecall(agentId, bankId, outcome, ms) {
+        const base = { agent: agentLabel(agentId), bank: bankLabel(bankId) };
+        this.recalls.get({ ...base, outcome }).n += 1;
+        observe(this.recallLatency.get(base), ms);
+    }
+    recordRetain(agentId, bankId, outcome, ms) {
+        const base = { agent: agentLabel(agentId), bank: bankLabel(bankId) };
+        this.retains.get({ ...base, outcome }).n += 1;
+        observe(this.retainLatency.get(base), ms);
+    }
+    recordReplay(bankId, outcome) {
+        this.replays.get({ bank: bankLabel(bankId), outcome }).n += 1;
+    }
+    recordDrop(bankId, reason, count = 1) {
+        if (count > 0) {
+            this.drops.get({ bank: bankLabel(bankId), reason }).n += count;
+        }
+    }
+    /** Prometheus text exposition (version 0.0.4). Families with no samples print only HELP/TYPE. */
+    render(queueDepth) {
+        const lines = [];
+        const counter = (name, help, series) => {
+            lines.push(`# HELP ${PREFIX}${name} ${help}`, `# TYPE ${PREFIX}${name} counter`);
+            for (const { labels, value } of series.values()) {
+                lines.push(`${PREFIX}${name}${formatLabels(labels)} ${value.n}`);
+            }
+        };
+        const histogram = (name, help, series) => {
+            lines.push(`# HELP ${PREFIX}${name} ${help}`, `# TYPE ${PREFIX}${name} histogram`);
+            for (const { labels, value } of series.values()) {
+                LATENCY_BUCKETS.forEach((le, i) => {
+                    lines.push(`${PREFIX}${name}_bucket${formatLabels(labels, ["le", String(le)])} ${value.buckets[i]}`);
+                });
+                lines.push(`${PREFIX}${name}_bucket${formatLabels(labels, ["le", "+Inf"])} ${value.count}`, `${PREFIX}${name}_sum${formatLabels(labels)} ${formatNumber(value.sum)}`, `${PREFIX}${name}_count${formatLabels(labels)} ${value.count}`);
+            }
+        };
+        counter("recall_total", "Auto-recall attempts by outcome.", this.recalls);
+        histogram("recall_duration_seconds", "Auto-recall latency.", this.recallLatency);
+        counter("retain_total", "Auto-retain attempts by outcome.", this.retains);
+        histogram("retain_duration_seconds", "Auto-retain latency.", this.retainLatency);
+        lines.push(`# HELP ${PREFIX}retain_queue_depth Retains waiting in the offline queue.`, `# TYPE ${PREFIX}retain_queue_depth gauge`);
+        for (const { value } of this.depth.values()) {
+            value.n = 0;
+        }
+        for (const [bankId, n] of queueDepth?.() ?? []) {
+            this.depth.get({ bank: bankLabel(bankId) }).n += n;
+        }
+        for (const { labels, value } of this.depth.values()) {
+            lines.push(`${PREFIX}retain_queue_depth${formatLabels(labels)} ${value.n}`);
+        }
+        counter("retain_queue_replays_total", "Queued retain replay attempts by outcome.", this.replays);
+        counter("retain_queue_drops_total", "Retains dropped from the queue by reason.", this.drops);
+        return `${lines.join("\n")}\n`;
+    }
+}
+function observe(h, ms) {
+    const seconds = Math.max(0, ms) / 1000;
+    LATENCY_BUCKETS.forEach((le, i) => {
+        if (seconds <= le) {
+            h.buckets[i] += 1;
+        }
+    });
+    h.sum += seconds;
+    h.count += 1;
+}
+// Mirrors diagnostics-prometheus: the route is gateway-auth, and read access is checked here so a
+// scope-narrowed operator identity cannot read it.
+const READ_SCOPES = ["operator.read", "operator.write", "operator.admin"];
+function hasReadScope() {
+    const scopes = getPluginRuntimeGatewayRequestScope()?.client?.connect?.scopes;
+    return Array.isArray(scopes) && READ_SCOPES.some((scope) => scopes.includes(scope));
+}
+export function createMetricsRouteHandler(metrics, queueDepth, readScope = hasReadScope) {
+    return (req, res) => {
+        res.setHeader("Cache-Control", "no-store");
+        if (!readScope()) {
+            res.statusCode = 403;
+            res.setHeader("Content-Type", "text/plain; charset=utf-8");
+            res.end("missing scope: operator.read");
+            return true;
+        }
+        if (req.method !== "GET" && req.method !== "HEAD") {
+            res.statusCode = 405;
+            res.setHeader("Allow", "GET, HEAD");
+            res.end("Method Not Allowed");
+            return true;
+        }
+        const body = metrics.render(queueDepth);
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "text/plain; version=0.0.4; charset=utf-8");
+        res.setHeader("Content-Length", String(Buffer.byteLength(body, "utf8")));
+        res.end(req.method === "HEAD" ? undefined : body);
+        return true;
+    };
+}

package/dist/retain-queue.js

@@ -131,10 +131,12 @@ export class RetainQueue {
     fileBytes = 0;
     limits;
     logger;
+    onDrop;
     constructor(options) {
         this.options = options;
         this.limits = options.limits;
         this.logger = options.logger;
+        this.onDrop = options.onDrop;
     }
     get filePath() {
         return this.options.filePath;
@@ -143,6 +145,7 @@ export class RetainQueue {
     configure(params) {
         this.limits = params.limits;
         this.logger = params.logger;
+        this.onDrop = params.onDrop;
     }
     now() {
         return this.options.now?.() ?? Date.now();
@@ -224,6 +227,21 @@ export class RetainQueue {
     peek() {
         return this.stored[0]?.entry;
     }
+    /**
+     * True when the item alone is over the size bound, so `enqueue` refuses it. Not reported as a
+     * drop here: the caller may still send it live, and reports it only when it is lost.
+     */
+    isTooLarge(entry) {
+        return stored({ ...entry, queuedAt: this.now() }).size > this.maxBytes();
+    }
+    /** Queued items per bank id. */
+    depthByBank() {
+        const depth = new Map();
+        for (const { entry } of this.stored) {
+            depth.set(entry.bankId, (depth.get(entry.bankId) ?? 0) + 1);
+        }
+        return depth;
+    }
     /** Bank and document id of every queued item, oldest first. */
     list() {
         return this.stored.map(({ entry }) => ({ bankId: entry.bankId, documentId: entry.documentId }));
@@ -264,7 +282,10 @@ export class RetainQueue {
         }
         let rewriteError;
         try {
-            if (this.prune(false) === 0 &&
+            // Drops are reported only once the write that makes them stick succeeds; the fallback below
+            // restores memory and prunes again, and reports then.
+            const pruned = this.pruneStored();
+            if (pruned.length === 0 &&
                 index < 0 &&
                 existsSync(this.filePath) &&
                 this.canAppend(next.size)) {
@@ -272,6 +293,7 @@ export class RetainQueue {
                 return true;
             }
             this.persist();
+            this.reportDrops(pruned);
             // False when the bound dropped the item just added or replaced.
             return this.stored.includes(next);
         }
@@ -285,7 +307,8 @@ export class RetainQueue {
         // older one, and a tombstone for every item the bounds drop, so no dropped line can come back
         // on a restart (say, after a later tombstone brings the count under maxItems).
         this.stored = [...kept, next];
-        this.prune(false);
+        // Reported only if the append below sticks; otherwise memory goes back to `kept`.
+        const prunedAgain = this.pruneStored();
         const keepsNext = this.stored.includes(next);
         const dead = kept.filter((s) => !this.stored.includes(s)).map((s) => s.entry);
         if (!keepsNext && index >= 0) {
@@ -302,6 +325,7 @@ export class RetainQueue {
                 if (text) {
                     this.append(text);
                 }
+                this.reportDrops(prunedAgain);
                 return keepsNext;
             }
             catch {
@@ -345,9 +369,17 @@ export class RetainQueue {
      * stays quiet until the queue is empty again.
      */
     prune(persist = true) {
+        const dropped = this.pruneStored();
+        this.reportDrops(dropped);
+        if (dropped.length > 0 && persist) {
+            this.persist();
+        }
+        return dropped.length;
+    }
+    /** The bounds step of `prune()`: updates memory and warns, but neither reports nor writes. */
+    pruneStored() {
         const { maxItems, maxAgeMs } = this.limits();
         const cutoff = this.now() - maxAgeMs;
-        const before = this.stored.length;
         let kept = this.stored.filter((s) => s.entry.queuedAt >= cutoff);
         if (kept.length > maxItems) {
             kept = kept.slice(kept.length - maxItems);
@@ -356,19 +388,20 @@ export class RetainQueue {
         while (kept.length > 0 && bytes > this.maxBytes()) {
             bytes -= kept.shift().size;
         }
+        const keptSet = new Set(kept);
+        const dropped = this.stored.filter((s) => !keptSet.has(s));
         this.stored = kept;
-        const dropped = before - kept.length;
-        if (dropped > 0) {
-            if (!this.dropWarned) {
-                this.dropWarned = true;
-                this.logger.warn?.(`memory-hindsight: retain queue dropped ${dropped} item(s) over retainQueueMaxItems (${maxItems}), retainQueueMaxAgeMs (${maxAgeMs}) or the ${this.maxBytes()}-byte size bound; further drops are not logged until the queue is empty`);
-            }
-            if (persist) {
-                this.persist();
-            }
+        if (dropped.length > 0 && !this.dropWarned) {
+            this.dropWarned = true;
+            this.logger.warn?.(`memory-hindsight: retain queue dropped ${dropped.length} item(s) over retainQueueMaxItems (${maxItems}), retainQueueMaxAgeMs (${maxAgeMs}) or the ${this.maxBytes()}-byte size bound; further drops are not logged until the queue is empty`);
         }
         return dropped;
     }
+    reportDrops(dropped) {
+        for (const s of dropped) {
+            this.onDrop?.(s.entry.bankId, "limit");
+        }
+    }
     ensureDir() {
         const dir = dirname(this.filePath);
         mkdirSync(dir, { recursive: true, mode: 0o700 });
@@ -526,6 +559,7 @@ export class RetainQueueRunner {
                     return delivered;
                 }
                 if (!isDroppingRejection(error)) {
+                    this.options.onReplay?.(entry.bankId, "deferred");
                     // Not an answer about this item (outage, auth, rate limit, ambiguous 404, refused
                     // redirect, or an unexpected error): keep it and back off.
                     if (!isTransportFailure(error) && !this.rejectionWarned) {
@@ -540,6 +574,7 @@ export class RetainQueueRunner {
                 }
                 // Hindsight answered 4xx about this item: retrying cannot help, so it leaves the queue.
                 this.queue.remove(entry, { persist: false });
+                this.options.onDrop?.(entry.bankId, "rejected");
                 logger.warn?.(`memory-hindsight: queued retain rejected and dropped: ${formatErrorMessage(error)}`);
                 continue;
             }
@@ -548,6 +583,7 @@ export class RetainQueueRunner {
                 return delivered;
             }
             this.queue.remove(entry, { persist: false });
+            this.options.onReplay?.(entry.bankId, "delivered");
             this.rejectionWarned = false;
             delivered += 1;
             if (delivered % SAVE_EVERY === 0) {

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/service.js

@@ -3,6 +3,12 @@ import { boundedSignal, HindsightClient } from "./client.js";
 import { RETAIN_TIMEOUT_MS } from "./config.js";
 import { BankSetupError, isDroppingRejection, isTransportFailure, RetainQueueRunner, retainQueuePath, sharedRetainQueue, } from "./retain-queue.js";
 export function createHindsightService(params) {
+    const { metrics } = params;
+    // Queue and replay observers feed the gateway metrics; none when the caller passes no metrics.
+    const queueObserver = metrics ? { onDrop: metrics.recordDrop.bind(metrics) } : {};
+    const runnerObserver = metrics
+        ? { onDrop: metrics.recordDrop.bind(metrics), onReplay: metrics.recordReplay.bind(metrics) }
+        : {};
     const preparedBanks = new Map();
     let stopped = false;
     let runner;
@@ -71,6 +77,10 @@ export function createHindsightService(params) {
                 // Read again after the await: the service may have stopped or restarted meanwhile.
                 const target = queue;
                 if (!target || refused || !isTransportFailure(error)) {
+                    // Queue-first path: the queue refused the item and the live write failed, so it is lost.
+                    if (target && refused && isTransportFailure(error) && target.isTooLarge(entry)) {
+                        metrics?.recordDrop(bankId, "too_large");
+                    }
                     throw error;
                 }
                 let queued;
@@ -82,6 +92,11 @@ export function createHindsightService(params) {
                     throw error;
                 }
                 if (!queued) {
+                    // Lost: the live write failed and the queue refused it. A bound that dropped the new item
+                    // is already counted as `limit` by the queue.
+                    if (target.isTooLarge(entry)) {
+                        metrics?.recordDrop(bankId, "too_large");
+                    }
                     throw error;
                 }
                 params.logger.warn?.(`memory-hindsight: Hindsight unreachable, retain queued (${target.size()} pending): ${formatErrorMessage(error)}`);
@@ -109,7 +124,11 @@ export function createHindsightService(params) {
                 return { maxItems: config.retainQueueMaxItems, maxAgeMs: config.retainQueueMaxAgeMs };
             };
             try {
-                queue = sharedRetainQueue(retainQueuePath(stateDir), { limits, logger: params.logger });
+                queue = sharedRetainQueue(retainQueuePath(stateDir), {
+                    limits,
+                    logger: params.logger,
+                    ...queueObserver,
+                });
             }
             catch (error) {
                 queue = undefined;
@@ -131,6 +150,7 @@ export function createHindsightService(params) {
                     await client.retain(entry.bankId, { ...entry.item, document_id: entry.documentId, update_mode: "replace" }, { signal });
                 },
                 logger: params.logger,
+                ...runnerObserver,
                 ...params.retainQueueRetry,
             });
             if (queue.size() > 0) {
@@ -139,6 +159,7 @@ export function createHindsightService(params) {
             }
         },
         retainQueue: () => runner,
+        retainQueueDepth: () => queue?.depthByBank(),
         stopped: () => stopped,
         stop() {
             stopped = 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.3.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",