@etzelm/openclaw-memory-hindsight 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 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

@@ -236,6 +236,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/index.js

@@ -6,6 +6,7 @@ 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";
@@ -80,9 +81,24 @@ 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
@@ -166,17 +182,29 @@ 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),
-                });
+                // 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();
+                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),
+                    });
+                }
+                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 (results.length === 0) {
                     return undefined;
                 }
@@ -238,6 +266,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 +293,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)}`);
             }
         });

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@etzelm/openclaw-memory-hindsight",
-  "version": "0.3.0",
+  "version": "0.4.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",