@etzelm/openclaw-memory-hindsight 0.1.1 → 0.2.0

package/dist/retain-queue.js

@@ -0,0 +1,493 @@
+import { appendFileSync, chmodSync, closeSync, existsSync, fstatSync, mkdirSync, openSync, readFileSync, readSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+import { HindsightHttpError } from "./client.js";
+export const RETAIN_QUEUE_DIR = "hindsight-native";
+export const RETAIN_QUEUE_FILE = "retain-queue.jsonl";
+/** Total size bound for the queue file, on top of the item and age limits. */
+export const RETAIN_QUEUE_MAX_BYTES = 32 * 1024 * 1024;
+/** `<state dir>/hindsight-native/retain-queue.jsonl`; the host passes the state dir to services. */
+export function retainQueuePath(stateDir) {
+    return join(stateDir, RETAIN_QUEUE_DIR, RETAIN_QUEUE_FILE);
+}
+/**
+ * True when Hindsight was not reached or failed on its side: network errors (fetch rejects with
+ * `TypeError: fetch failed`), timeouts and aborts, and HTTP 5xx. A 4xx is an answer about the
+ * request, so it is never queued. A refused redirect (`redirect: "error"`) is a configuration
+ * problem, not an outage, and any other TypeError is a bug, so neither is queued.
+ */
+export function isTransportFailure(error) {
+    if (error instanceof HindsightHttpError) {
+        return error.status >= 500;
+    }
+    if (error instanceof TypeError) {
+        const cause = error.cause;
+        const causeMessage = typeof cause?.message === "string" ? cause.message : "";
+        return error.message === "fetch failed" && !/redirect/i.test(causeMessage);
+    }
+    const name = error?.name;
+    return name === "AbortError" || name === "TimeoutError";
+}
+/**
+ * A 4xx from bank setup (applying `retainMission` before the write). It is about the bank's
+ * config, not the queued item, so replay keeps the item; a config fix lets it through.
+ */
+export class BankSetupError extends Error {
+    cause;
+    constructor(cause) {
+        super(`bank setup failed (${formatErrorMessage(cause)})`);
+        this.cause = cause;
+        this.name = "BankSetupError";
+    }
+}
+/**
+ * The only replay failure that drops an item: a Hindsight HTTP 4xx about the item itself (not
+ * auth, rate limit or an ambiguous 404). Everything else keeps the item.
+ */
+export function isDroppingRejection(error) {
+    return (error instanceof HindsightHttpError &&
+        error.status >= 400 &&
+        error.status < 500 &&
+        !isRetryableRejection(error));
+}
+/**
+ * Rejections on replay that say nothing about the item itself: keep it and retry later. That is
+ * auth (401, 403), rate limits (429) and a 404 for a route that does not exist (a wrong
+ * `hindsightApiUrl` path) or with an empty body. Hindsight creates a bank on its first retain, so
+ * only an explicit `Bank '<id>' not found` 404 is an answer about this item and drops it like
+ * other 4xx; an ambiguous 404 keeps it, and the age bound clears it in the end.
+ */
+export function isRetryableRejection(error) {
+    if (!(error instanceof HindsightHttpError)) {
+        return false;
+    }
+    if (error.status === 404) {
+        return !error.bankMissingExplicit;
+    }
+    return error.status === 401 || error.status === 403 || error.status === 429;
+}
+function isQueuedRetain(value) {
+    const v = value;
+    return (typeof v === "object" &&
+        v !== null &&
+        typeof v.bankId === "string" &&
+        v.bankId.length > 0 &&
+        typeof v.documentId === "string" &&
+        v.documentId.length > 0 &&
+        typeof v.queuedAt === "number" &&
+        Number.isFinite(v.queuedAt) &&
+        typeof v.item === "object" &&
+        v.item !== null &&
+        typeof v.item.content === "string");
+}
+/** The key of a tombstone line, written when a rewrite failed to drop an out-of-date copy. */
+function tombstoneKey(value) {
+    const t = value?.tombstone;
+    return typeof t?.bankId === "string" && typeof t.documentId === "string"
+        ? { bankId: t.bankId, documentId: t.documentId }
+        : undefined;
+}
+/** True when the file is empty or its last byte is a newline. */
+function endsWithNewline(filePath) {
+    const fd = openSync(filePath, "r");
+    try {
+        const { size } = fstatSync(fd);
+        if (size === 0) {
+            return true;
+        }
+        const last = Buffer.alloc(1);
+        readSync(fd, last, 0, 1, size - 1);
+        return last[0] === 0x0a;
+    }
+    finally {
+        closeSync(fd);
+    }
+}
+function stored(entry, line = JSON.stringify(entry)) {
+    return { entry, line, size: Buffer.byteLength(line, "utf8") + 1 };
+}
+/**
+ * Bounded, file-backed FIFO of failed auto-retains, one JSON line per item. One entry per bank and
+ * document id: a newer retain of the same document replaces the queued one in place. A new item is
+ * appended to the file; replacing, pruning and replay rewrite it (mode 600, atomic rename).
+ */
+export class RetainQueue {
+    options;
+    stored = [];
+    dropWarned = false;
+    /** Removals not yet written (replay batches its writes). */
+    dirty = false;
+    limits;
+    logger;
+    constructor(options) {
+        this.options = options;
+        this.limits = options.limits;
+        this.logger = options.logger;
+    }
+    get filePath() {
+        return this.options.filePath;
+    }
+    /** A restarted service reuses this queue with its own config and logger. */
+    configure(params) {
+        this.limits = params.limits;
+        this.logger = params.logger;
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+    maxBytes() {
+        return this.options.maxBytes ?? RETAIN_QUEUE_MAX_BYTES;
+    }
+    /**
+     * Reads the file. A missing file is an empty queue. Unreadable lines (a torn append) are
+     * skipped with one warning. Any other read error throws, so the file is never overwritten.
+     */
+    load() {
+        let text;
+        try {
+            text = readFileSync(this.filePath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                this.stored = [];
+                return;
+            }
+            throw error;
+        }
+        let loaded = [];
+        let skipped = 0;
+        let tombstones = 0;
+        for (const line of text.split("\n")) {
+            if (!line.trim()) {
+                continue;
+            }
+            try {
+                const entry = JSON.parse(line);
+                if (isQueuedRetain(entry)) {
+                    loaded.push(stored(entry, line));
+                    continue;
+                }
+                const dead = tombstoneKey(entry);
+                if (dead) {
+                    // Drops the earlier copies the tombstone was written for.
+                    loaded = loaded.filter((s) => s.entry.bankId !== dead.bankId || s.entry.documentId !== dead.documentId);
+                    tombstones += 1;
+                    continue;
+                }
+            }
+            catch {
+                // counted below
+            }
+            skipped += 1;
+        }
+        this.stored = loaded;
+        if (skipped > 0) {
+            this.logger.warn?.(`memory-hindsight: retain queue skipped ${skipped} unreadable line(s)`);
+        }
+        if (this.prune(false) > 0 || skipped > 0 || tombstones > 0) {
+            try {
+                this.persist();
+            }
+            catch (error) {
+                // Compaction is optional: the file loads the same way next time, so keep the queue on.
+                this.logger.warn?.(`memory-hindsight: retain queue file not compacted (${formatErrorMessage(error)})`);
+            }
+        }
+    }
+    size() {
+        return this.stored.length;
+    }
+    hasBank(bankId) {
+        return this.stored.some((s) => s.entry.bankId === bankId);
+    }
+    peek() {
+        return this.stored[0]?.entry;
+    }
+    /** Bank and document id of every queued item, oldest first. */
+    list() {
+        return this.stored.map(({ entry }) => ({ bankId: entry.bankId, documentId: entry.documentId }));
+    }
+    /**
+     * Adds or replaces (same bank and document id) and writes the file before returning. Returns
+     * false, and queues nothing, when the item alone is larger than the size bound.
+     */
+    enqueue(entry) {
+        const next = stored({
+            bankId: entry.bankId,
+            documentId: entry.documentId,
+            item: entry.item,
+            queuedAt: this.now(),
+        });
+        const index = this.stored.findIndex((s) => s.entry.bankId === entry.bankId && s.entry.documentId === entry.documentId);
+        if (next.size > this.maxBytes()) {
+            this.logger.warn?.(`memory-hindsight: retain too large to queue (${next.size} bytes, bound ${this.maxBytes()}); not queued`);
+            // An older copy of the same document is out of date now; do not replay it.
+            if (index >= 0) {
+                const [stale] = this.stored.splice(index, 1);
+                try {
+                    this.persist();
+                }
+                catch {
+                    this.markStale(stale.entry);
+                }
+            }
+            return false;
+        }
+        // A failed write never leaves memory holding an item the file lacks; see the catch below.
+        const before = [...this.stored];
+        if (index >= 0) {
+            this.stored[index] = next;
+        }
+        else {
+            this.stored.push(next);
+        }
+        try {
+            if (this.prune(false) === 0 && index < 0 && existsSync(this.filePath)) {
+                this.append(next.line);
+                return true;
+            }
+            this.persist();
+        }
+        catch (error) {
+            // A queued copy of the same document is out of date now (the caller sends the newer one
+            // live), so it must not be replayed over it: not from memory, and not after a restart.
+            this.stored = index >= 0 ? before.filter((_, i) => i !== index) : before;
+            if (index >= 0) {
+                this.markStale(before[index].entry);
+            }
+            throw error;
+        }
+        // False when the bound dropped the item just added or replaced.
+        return this.stored.includes(next);
+    }
+    /**
+     * Removes the entry when it is still the queued copy (a newer enqueue replaced it otherwise).
+     * Replay passes `persist: false` and calls `save()` in batches: a crash before the save only
+     * re-sends items that replace themselves on the server (same document id, update_mode replace).
+     */
+    remove(entry, options = {}) {
+        const index = this.stored.findIndex((s) => s.entry === entry);
+        if (index < 0) {
+            return;
+        }
+        this.stored.splice(index, 1);
+        if (options.persist === false) {
+            this.dirty = true;
+        }
+        else {
+            this.persist();
+        }
+    }
+    /** Writes batched removals, if any. */
+    save() {
+        if (this.dirty) {
+            this.persist();
+        }
+    }
+    /**
+     * Drops expired entries, then the oldest beyond maxItems or the byte bound. Warns once, then
+     * stays quiet until the queue is empty again.
+     */
+    prune(persist = true) {
+        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);
+        }
+        let bytes = kept.reduce((sum, s) => sum + s.size, 0);
+        while (kept.length > 0 && bytes > this.maxBytes()) {
+            bytes -= kept.shift().size;
+        }
+        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();
+            }
+        }
+        return dropped;
+    }
+    ensureDir() {
+        const dir = dirname(this.filePath);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        chmodSync(dir, 0o700);
+    }
+    append(line) {
+        // A torn last line (crash mid-append) must not swallow this item: start on a fresh line.
+        appendFileSync(this.filePath, `${endsWithNewline(this.filePath) ? "" : "\n"}${line}\n`, {
+            mode: 0o600,
+        });
+        try {
+            chmodSync(this.filePath, 0o600);
+        }
+        catch {
+            // The line is written; a chmod failure must not make the caller think it was not.
+        }
+    }
+    /**
+     * Best effort when the rewrite failed: append a tombstone for an out-of-date copy that is still
+     * in the file, so `load()` drops it after a restart instead of replaying it.
+     */
+    markStale(entry) {
+        try {
+            this.append(JSON.stringify({ tombstone: { bankId: entry.bankId, documentId: entry.documentId } }));
+        }
+        catch (error) {
+            this.logger.warn?.(`memory-hindsight: could not mark an out-of-date queued retain (${formatErrorMessage(error)}); a restart may replay it before the newer copy is written again`);
+        }
+    }
+    persist() {
+        this.dirty = false;
+        if (this.stored.length === 0) {
+            rmSync(this.filePath, { force: true });
+            this.dropWarned = false;
+            return;
+        }
+        this.ensureDir();
+        const tmp = `${this.filePath}.tmp`;
+        writeFileSync(tmp, `${this.stored.map((s) => s.line).join("\n")}\n`, { mode: 0o600 });
+        // writeFileSync keeps the mode of an existing file; force it.
+        chmodSync(tmp, 0o600);
+        renameSync(tmp, this.filePath);
+    }
+}
+/**
+ * One queue per file per process, shared across service restarts, so a stopped instance can
+ * never write a stale copy over the file the current instance owns.
+ */
+const sharedQueues = new Map();
+export function sharedRetainQueue(filePath, params) {
+    const existing = sharedQueues.get(filePath);
+    if (existing) {
+        existing.configure(params);
+        return existing;
+    }
+    const queue = new RetainQueue({ filePath, ...params });
+    queue.load();
+    sharedQueues.set(filePath, queue);
+    return queue;
+}
+/** Test seam: forget every shared queue, as a new process would (the files stay). */
+export function resetSharedRetainQueues() {
+    sharedQueues.clear();
+}
+export const RETAIN_QUEUE_RETRY_BASE_MS = 30_000;
+export const RETAIN_QUEUE_RETRY_MAX_MS = 15 * 60_000;
+// Replay writes the file after this many deliveries and at the end of each pass.
+const SAVE_EVERY = 25;
+/** Replays the queue in order on a backoff timer. Stops at the first transport failure. */
+export class RetainQueueRunner {
+    queue;
+    options;
+    timer;
+    delayMs;
+    running;
+    rejectionWarned = false;
+    controller = new AbortController();
+    constructor(queue, options) {
+        this.queue = queue;
+        this.options = options;
+        this.delayMs = this.baseDelay();
+    }
+    baseDelay() {
+        return this.options.baseDelayMs ?? RETAIN_QUEUE_RETRY_BASE_MS;
+    }
+    stopped() {
+        return this.controller.signal.aborted;
+    }
+    /** Runs one replay pass now (or joins the one in progress). */
+    flush() {
+        if (this.stopped()) {
+            return Promise.resolve();
+        }
+        this.running ??= this.replay()
+            .catch((error) => {
+            this.options.logger.warn?.(`memory-hindsight: retain queue replay stopped (${formatErrorMessage(error)})`);
+        })
+            .finally(() => {
+            this.running = undefined;
+        });
+        return this.running;
+    }
+    /** Schedules a pass after the current backoff unless one is already scheduled. */
+    schedule(delayMs = this.delayMs) {
+        if (this.stopped() || this.timer || this.queue.size() === 0) {
+            return;
+        }
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.flush();
+        }, delayMs);
+        this.timer.unref?.();
+    }
+    stop() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+        this.controller.abort();
+    }
+    async replay() {
+        let delivered = 0;
+        try {
+            delivered = await this.replayItems();
+        }
+        finally {
+            // Removals during the pass are batched; write the final state once.
+            this.queue.save();
+        }
+        if (delivered > 0) {
+            this.options.logger.info?.(`memory-hindsight: retain queue delivered ${delivered}, ${this.queue.size() > 0 ? `${this.queue.size()} pending` : "queue empty"}`);
+        }
+    }
+    async replayItems() {
+        const { logger, send } = this.options;
+        let delivered = 0;
+        this.queue.prune();
+        for (let entry = this.queue.peek(); entry; entry = this.queue.peek()) {
+            try {
+                await send(entry, this.controller.signal);
+            }
+            catch (error) {
+                if (this.stopped()) {
+                    return delivered;
+                }
+                if (!isDroppingRejection(error)) {
+                    // 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) {
+                        this.rejectionWarned = true;
+                        logger.warn?.(`memory-hindsight: queued retain not delivered (${formatErrorMessage(error)}); ${this.queue.size()} pending, retrying with backoff; new retains for a bank with pending items queue behind it`);
+                    }
+                    logger.debug?.(`memory-hindsight: retain queue replay deferred (${this.queue.size()} pending): ${formatErrorMessage(error)}`);
+                    // The pass that just failed waited the current delay; the next one waits twice as long.
+                    this.schedule();
+                    this.delayMs = Math.min(this.delayMs * 2, this.options.maxDelayMs ?? RETAIN_QUEUE_RETRY_MAX_MS);
+                    return delivered;
+                }
+                // Hindsight answered 4xx about this item: retrying cannot help, so it leaves the queue.
+                this.queue.remove(entry, { persist: false });
+                logger.warn?.(`memory-hindsight: queued retain rejected and dropped: ${formatErrorMessage(error)}`);
+                continue;
+            }
+            // A runner stopped mid-send leaves the item for the next one; a resend replaces itself.
+            if (this.stopped()) {
+                return delivered;
+            }
+            this.queue.remove(entry, { persist: false });
+            this.rejectionWarned = false;
+            delivered += 1;
+            if (delivered % SAVE_EVERY === 0) {
+                this.queue.save();
+            }
+        }
+        this.delayMs = this.baseDelay();
+        return delivered;
+    }
+}

package/dist/routing.js

@@ -60,3 +60,16 @@ export function sessionUsesMemory(config, params) {
     }
     return !(sessionKey && OPERATIONAL_SESSION_RE.test(sessionKey));
 }
+// Active Memory's blocking recall child: `<parent>:active-memory:<12 hex>` (as memory-core reads it).
+const ACTIVE_MEMORY_RECALL_SESSION_RE = /:active-memory:[a-f0-9]{12}$/i;
+/**
+ * Host maintenance turns that get no auto-recall and no auto-retain. The pre-compaction flush
+ * (trigger "memory") sends a fixed host prompt and saves through hindsight_retain; Active
+ * Memory's recall child sends a recall prompt and reads through hindsight_recall. Neither is a
+ * user turn, so recalling on its prompt or retaining its transcript only adds noise. The
+ * hindsight_* tools stay available to both.
+ */
+export function isMaintenanceTurn(params) {
+    return (params.trigger === "memory" ||
+        Boolean(params.sessionKey && ACTIVE_MEMORY_RECALL_SESSION_RE.test(params.sessionKey.trim())));
+}

package/dist/service.js

@@ -1,7 +1,13 @@
-import { HindsightClient } from "./client.js";
+import { formatErrorMessage } from "openclaw/plugin-sdk/error-runtime";
+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 preparedBanks = new Map();
     let stopped = false;
+    let runner;
+    // Kept after stop, so a live retain that fails after a stop or restart still lands in the file.
+    let queue;
     const client = new HindsightClient({
         resolveEndpoint: () => {
             const { apiUrl, apiToken } = params.config();
@@ -9,28 +15,132 @@ export function createHindsightService(params) {
         },
         ...(params.fetch ? { fetch: params.fetch } : {}),
     });
+    const ensureBank = async (bankId, signal) => {
+        let pending = preparedBanks.get(bankId);
+        if (!pending) {
+            const { retainMission } = params.config();
+            pending = client.applyBankDefaults(bankId, { retainMission }, signal);
+            preparedBanks.set(bankId, pending);
+            // A failed setup retries on the next write instead of caching the failure.
+            pending.catch(() => {
+                if (preparedBanks.get(bankId) === pending) {
+                    preparedBanks.delete(bankId);
+                }
+            });
+        }
+        await pending;
+    };
+    const write = async (bankId, item, signal) => {
+        await ensureBank(bankId, signal);
+        await client.retain(bankId, item, { signal });
+    };
+    const stopQueue = () => {
+        runner?.stop();
+        runner = undefined;
+    };
     return {
         config: params.config,
         client,
         logger: params.logger,
-        async ensureBank(bankId, signal) {
-            let pending = preparedBanks.get(bankId);
-            if (!pending) {
-                const { retainMission } = params.config();
-                pending = client.applyBankDefaults(bankId, { retainMission }, signal);
-                preparedBanks.set(bankId, pending);
-                // A failed setup retries on the next write instead of caching the failure.
-                pending.catch(() => {
-                    if (preparedBanks.get(bankId) === pending) {
-                        preparedBanks.delete(bankId);
+        ensureBank,
+        async retainOrQueue(bankId, item, signal) {
+            const entry = { bankId, documentId: item.document_id, item };
+            // Items already waiting for this bank go first, so the bank sees its writes in order.
+            let refused = false;
+            if (runner && queue?.hasBank(bankId)) {
+                let queued = false;
+                try {
+                    queued = queue.enqueue(entry);
+                }
+                catch (queueError) {
+                    // Disk full or not writable: warn and try a live write, as the failure path does.
+                    params.logger.warn?.(`memory-hindsight: could not queue retain (${formatErrorMessage(queueError)}); sending it now`);
+                }
+                if (queued) {
+                    void runner.flush();
+                    return "queued";
+                }
+                // Not queued (too large, already warned, or the write failed): send it live without
+                // waiting for the bank's queue, and do not try to queue it again.
+                refused = true;
+            }
+            try {
+                await write(bankId, item, signal);
+            }
+            catch (error) {
+                // Read again after the await: the service may have stopped or restarted meanwhile.
+                const target = queue;
+                if (!target || refused || !isTransportFailure(error)) {
+                    throw error;
+                }
+                let queued;
+                try {
+                    queued = target.enqueue(entry);
+                }
+                catch (queueError) {
+                    params.logger.warn?.(`memory-hindsight: could not queue retain (${formatErrorMessage(queueError)})`);
+                    throw error;
+                }
+                if (!queued) {
+                    throw error;
+                }
+                params.logger.warn?.(`memory-hindsight: Hindsight unreachable, retain queued (${target.size()} pending): ${formatErrorMessage(error)}`);
+                runner?.schedule();
+                return "queued";
+            }
+            if (runner && queue && queue.size() > 0) {
+                void runner.flush();
+            }
+            return "sent";
+        },
+        startRetainQueue(stateDir) {
+            stopQueue();
+            queue = undefined;
+            if (!params.config().retainQueueEnabled) {
+                return;
+            }
+            // The service contract always passes stateDir; only a bare test harness omits it.
+            if (!stateDir) {
+                params.logger.debug?.("memory-hindsight: host gave no state dir; failed retains are not queued");
+                return;
+            }
+            const limits = () => {
+                const config = params.config();
+                return { maxItems: config.retainQueueMaxItems, maxAgeMs: config.retainQueueMaxAgeMs };
+            };
+            try {
+                queue = sharedRetainQueue(retainQueuePath(stateDir), { limits, logger: params.logger });
+            }
+            catch (error) {
+                queue = undefined;
+                params.logger.warn?.(`memory-hindsight: retain queue unavailable, failed retains are not queued (${formatErrorMessage(error)})`);
+                return;
+            }
+            runner = new RetainQueueRunner(queue, {
+                send: async (entry, stopSignal) => {
+                    const signal = boundedSignal(RETAIN_TIMEOUT_MS, stopSignal);
+                    try {
+                        await ensureBank(entry.bankId, signal);
+                    }
+                    catch (error) {
+                        // A setup 4xx is about the bank config, not this item: keep it (see BankSetupError).
+                        throw isDroppingRejection(error) ? new BankSetupError(error) : error;
                     }
-                });
+                    await client.retain(entry.bankId, entry.item, { signal });
+                },
+                logger: params.logger,
+                ...params.retainQueueRetry,
+            });
+            if (queue.size() > 0) {
+                params.logger.info?.(`memory-hindsight: ${queue.size()} queued retain(s) from an earlier run, replaying`);
+                void runner.flush();
             }
-            await pending;
         },
+        retainQueue: () => runner,
         stopped: () => stopped,
         stop() {
             stopped = true;
+            stopQueue();
             preparedBanks.clear();
         },
         start() {

package/dist/tools.js

@@ -83,14 +83,12 @@ export function createRetainTool(service, deduper, ctx) {
         async execute(_toolCallId, rawParams, signal) {
             const params = asOptionalRecord(rawParams) ?? {};
             const content = requiredString(params, "content");
-            const tags = Array.isArray(params.tags)
-                ? [
-                    ...new Set(params.tags
-                        .filter((tag) => typeof tag === "string")
-                        .map((tag) => tag.trim())
-                        .filter(Boolean)),
-                ]
+            const callTags = Array.isArray(params.tags)
+                ? params.tags.filter((tag) => typeof tag === "string")
                 : [];
+            const tags = [
+                ...new Set([...service.config().retainTags, ...callTags].map((tag) => tag.trim()).filter(Boolean)),
+            ];
             const occurredAt = typeof params.occurred_at === "string" ? params.occurred_at.trim() : "";
             const flushId = ctx.memoryFlush?.flushId;
             if (flushId && !deduper.claim(flushId, bank.bankId, content)) {