@strands-agents/sdk 1.4.0 → 1.5.0

package/dist/src/memory/extraction/coordinator.js

@@ -0,0 +1,245 @@
+import { logger } from '../../logging/logger.js';
+import { normalizeError } from '../../errors.js';
+/**
+ * Number of consecutive save failures after which a store backs off (stops trying every turn).
+ * @internal
+ */
+export const SAVE_FAILURES_BEFORE_BACKOFF = 10;
+/**
+ * While backed off, a store retries only once every this many save attempts (a probe).
+ * @internal
+ */
+export const BACKOFF_PROBE_INTERVAL = 3;
+/** The kind of a content block (e.g. 'text', 'toolUse'), used to match it against a filter. */
+function _blockKind(block) {
+    // A text block is `{ text: string }`; every other block is a single-key wrapper (`{ toolUse }`, …).
+    if ('text' in block)
+        return 'text';
+    return Object.keys(block)[0] ?? '';
+}
+/**
+ * Removes excluded content blocks, and drops any message left empty. Does not mutate the input.
+ * Carries each message's sequence number through so it stays aligned with the filtered batch.
+ */
+function _filterMessages(buffered, filter) {
+    const exclude = new Set(filter.exclude);
+    const result = [];
+    for (const { seq, message } of buffered) {
+        const content = message.content.filter((block) => !exclude.has(_blockKind(block)));
+        if (content.length > 0) {
+            result.push({
+                seq,
+                message: {
+                    role: message.role,
+                    content,
+                    ...(message.metadata !== undefined && { metadata: message.metadata }),
+                },
+            });
+        }
+    }
+    return result;
+}
+/**
+ * Saves conversation messages to memory stores, in the background, without slowing the agent down.
+ *
+ * How it works, in three pieces:
+ *
+ * 1. **The buffer.** Every message the agent produces is copied into one shared list (`_pending`).
+ *    Each gets a number (`seq`) that only ever counts up, so we can tell which messages are newer.
+ *    We keep our own copy here (rather than reading the agent's live message list) because the agent
+ *    can delete old messages to stay within its context window; our copy means we never lose one
+ *    before it's saved.
+ *
+ * 2. **Per-store progress.** Each store can save at its own pace, so we remember, per store, the
+ *    `seq` of the last message it has already saved (`_marks`). When a store saves, it only looks at
+ *    messages newer than that number, so the same message is never saved twice to the same store.
+ *
+ * 3. **One save at a time per store.** A store might be asked to save again while a previous save is
+ *    still running. We chain each store's saves one after another (`_chains`) so they can't overlap
+ *    or run out of order.
+ *
+ * If a store fails to save {@link SAVE_FAILURES_BEFORE_BACKOFF} times in a row, it backs off: instead
+ * of trying every turn, it retries only once every {@link BACKOFF_PROBE_INTERVAL} attempts (a probe).
+ * A successful probe clears the failure streak and resumes normal saving - so a transient outage
+ * recovers on its own and the messages buffered during it are saved once the store comes back. A
+ * permanently broken store keeps probing and logs an error each time, surfacing the misconfiguration.
+ *
+ * Saving itself either runs the store's extractor to pull out facts, or hands the raw messages to the
+ * store - see {@link _write}.
+ * @internal
+ */
+export class ExtractionCoordinator {
+    _stores;
+    /** Per store: its resolved extraction config (triggers, extractor, filter). */
+    _storeToExtractionConfig = new Map();
+    _defaultModel;
+    /** The shared list of messages waiting to be saved, oldest first. Each is tagged with its `seq`. */
+    _pending = [];
+    /** The number to give the next message added to the buffer. Only ever increases. */
+    _nextSeq = 0;
+    /** Per store: the `seq` of the last message that store has already saved. Starts at -1 (saved none). */
+    _marks = new Map();
+    /** Per store: a promise for that store's currently-running save, so the next save waits its turn. */
+    _chains = new Map();
+    /** Per store: how many saves have failed in a row. Reset to 0 on a successful save. */
+    _consecutiveFailures = new Map();
+    /** Per store: while backed off, counts save requests so we can let every Nth through as a probe. */
+    _backoffCounters = new Map();
+    /**
+     * @param stores - The extraction-configured stores this coordinator manages, each with its resolved config
+     * @param defaultModel - The agent's model, passed to extractors that don't configure their own
+     */
+    constructor(stores, defaultModel) {
+        this._stores = stores.map((s) => s.store);
+        this._defaultModel = defaultModel;
+        for (const { store, config } of stores) {
+            this._storeToExtractionConfig.set(store, config);
+            this._marks.set(store, -1);
+        }
+    }
+    /** Adds a message to the buffer. */
+    record(message) {
+        this._pending.push({ seq: this._nextSeq++, message });
+    }
+    /**
+     * Saves this store's unsaved messages, in the background. Queued behind the store's previous save so
+     * two never run at once. Failures are logged and swallowed - saving must never break the agent loop.
+     * The returned promise is for {@link flush}; callers (triggers) ignore it so they don't block.
+     */
+    process(store) {
+        if (!this._shouldAttempt(store)) {
+            return Promise.resolve();
+        }
+        return this._enqueue(store);
+    }
+    /** Queues a save for the store behind its previous one, so saves never overlap or reorder. */
+    _enqueue(store) {
+        const previous = this._chains.get(store) ?? Promise.resolve();
+        const next = previous.then(() => this._extract(store));
+        this._chains.set(store, next);
+        return next;
+    }
+    /**
+     * Whether to attempt a save now. A healthy store always attempts. A backed-off store (too many
+     * failures in a row) attempts only once every {@link BACKOFF_PROBE_INTERVAL} requests - a probe to
+     * see if it has recovered - and skips the rest.
+     */
+    _shouldAttempt(store) {
+        if ((this._consecutiveFailures.get(store) ?? 0) < SAVE_FAILURES_BEFORE_BACKOFF) {
+            return true;
+        }
+        const count = (this._backoffCounters.get(store) ?? 0) + 1;
+        this._backoffCounters.set(store, count);
+        return count % BACKOFF_PROBE_INTERVAL === 0;
+    }
+    /**
+     * Saves every store's remaining messages and waits for all saves to finish. Call this once at a
+     * boundary you control - typically app shutdown - to make sure nothing in the buffer is lost.
+     *
+     * It first tells every store to save (even one whose trigger hasn't fired this turn, or one that is
+     * backed off - flush bypasses backoff so a recovered store still writes its backlog); stores with
+     * nothing to save do nothing. Then it waits, re-checking until no new save has started, so saves
+     * that begin while we're waiting are also covered.
+     */
+    async flush() {
+        for (const store of this._stores) {
+            void this._enqueue(store);
+        }
+        for (;;) {
+            const inFlight = [...this._chains.values()];
+            await Promise.all(inFlight);
+            // If nothing new started while we waited, everything is done.
+            if (this._chains.size === inFlight.length && [...this._chains.values()].every((p, i) => p === inFlight[i])) {
+                return;
+            }
+        }
+    }
+    async _extract(store) {
+        const mark = this._marks.get(store) ?? -1;
+        const fresh = this._pending.filter((buffered) => buffered.seq > mark);
+        if (fresh.length === 0) {
+            return;
+        }
+        // Mark these messages as saved before we start saving, so a queued save behind this one won't
+        // pick them up again. If the save fails we put the mark back (below) and they retry.
+        const highestSeq = fresh[fresh.length - 1].seq;
+        this._marks.set(store, highestSeq);
+        const filter = this._storeToExtractionConfig.get(store).filter;
+        const filtered = _filterMessages(fresh, filter);
+        try {
+            if (filtered.length > 0) {
+                await this._write(store, filtered);
+                // A successful write clears the failure streak and ends any backoff. Only a real write counts
+                // as recovery - a fully-filtered (empty) turn never touched the backend, so it leaves backoff
+                // state untouched (it still advances the mark above; those messages had nothing to save).
+                this._consecutiveFailures.set(store, 0);
+                this._backoffCounters.delete(store);
+            }
+        }
+        catch (err) {
+            this._onSaveFailed(store, mark, err);
+        }
+        finally {
+            this._trim();
+        }
+    }
+    /**
+     * Handles a failed save. Puts the mark back so the messages retry next time. Once a store has failed
+     * {@link SAVE_FAILURES_BEFORE_BACKOFF} times in a row it logs an error and enters backoff (it then
+     * retries only on probes - see {@link _shouldAttempt}); before that it logs a warning. The messages
+     * stay buffered either way, so a store that recovers saves them.
+     */
+    _onSaveFailed(store, markBeforeSave, err) {
+        const failures = (this._consecutiveFailures.get(store) ?? 0) + 1;
+        this._consecutiveFailures.set(store, failures);
+        this._marks.set(store, markBeforeSave);
+        const reason = normalizeError(err).message;
+        if (failures >= SAVE_FAILURES_BEFORE_BACKOFF) {
+            logger.error(`store=<${store.name}>, failures=<${failures}>, reason=<${reason}> | memory store save failing repeatedly`);
+        }
+        else {
+            logger.warn(`store=<${store.name}>, reason=<${reason}> | memory extraction failed`);
+        }
+    }
+    /**
+     * Saves the messages to the store, one of two ways:
+     * - store has an extractor: run it to pull out facts, then write each fact via `add`.
+     * - no extractor: hand the raw messages to `addMessages` so the store keeps their roles.
+     *
+     * Fact writes run in parallel. If any fails we throw, which makes the caller retry the whole batch
+     * next time - so a fact that already saved may be written again (stores should expect duplicates).
+     */
+    async _write(store, buffered) {
+        const extractor = this._storeToExtractionConfig.get(store).extractor;
+        const messages = buffered.map((buffer) => buffer.message);
+        if (extractor) {
+            const entries = await extractor.extract(messages, { defaultModel: this._defaultModel });
+            const settled = await Promise.allSettled(entries.map((entry) => store.add(entry.content, entry.metadata)));
+            const failures = settled.filter((r) => r.status === 'rejected');
+            if (failures.length > 0) {
+                throw new AggregateError(failures.map((failure) => failure.reason), `failed to write ${failures.length} of ${entries.length} extracted entries`);
+            }
+            return;
+        }
+        // Pass each message's sequence number so a store can build an idempotency key surviving retries.
+        await store.addMessages(messages, { sequenceNumbers: buffered.map((buffer) => buffer.seq) });
+    }
+    /**
+     * Removes messages from the buffer once every store has saved them (so none still needs them).
+     *
+     * A store that hasn't saved a message yet - because its trigger hasn't fired, or it's failing and
+     * waiting to recover - keeps that message buffered. So a store stuck failing for good slowly grows
+     * the buffer; that surfaces as repeated error logs and is bounded by the (non-persisted) session.
+     */
+    _trim() {
+        let minMark = Infinity;
+        for (const store of this._stores) {
+            minMark = Math.min(minMark, this._marks.get(store) ?? -1);
+        }
+        if (minMark === Infinity) {
+            return;
+        }
+        this._pending = this._pending.filter((buffered) => buffered.seq > minMark);
+    }
+}
+//# sourceMappingURL=coordinator.js.map

package/dist/src/memory/extraction/coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordinator.js","sourceRoot":"","sources":["../../../../src/memory/extraction/coordinator.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAehD;;;GAGG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,EAAE,CAAA;AAE9C;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAA;AAQvC,+FAA+F;AAC/F,SAAS,UAAU,CAAC,KAAuB;IACzC,oGAAoG;IACpG,IAAI,MAAM,IAAI,KAAK;QAAE,OAAO,MAAM,CAAA;IAClC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;AACpC,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,QAA2B,EAAE,MAA2B;IAC/E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,OAAO,CAAC,CAAA;IAC/C,MAAM,MAAM,GAAsB,EAAE,CAAA;IACpC,KAAK,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,IAAI,QAAQ,EAAE,CAAC;QACxC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QAClF,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACvB,MAAM,CAAC,IAAI,CAAC;gBACV,GAAG;gBACH,OAAO,EAAE;oBACP,IAAI,EAAE,OAAO,CAAC,IAAI;oBAClB,OAAO;oBACP,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;iBACtE;aACF,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,qBAAqB;IACf,OAAO,CAAe;IACvC,+EAA+E;IAC9D,wBAAwB,GAAG,IAAI,GAAG,EAAyC,CAAA;IAC3E,aAAa,CAAO;IACrC,oGAAoG;IAC5F,QAAQ,GAAsB,EAAE,CAAA;IACxC,oFAAoF;IAC5E,QAAQ,GAAG,CAAC,CAAA;IACpB,wGAAwG;IACvF,MAAM,GAAG,IAAI,GAAG,EAAuB,CAAA;IACxD,qGAAqG;IACpF,OAAO,GAAG,IAAI,GAAG,EAA8B,CAAA;IAChE,uFAAuF;IACtE,oBAAoB,GAAG,IAAI,GAAG,EAAuB,CAAA;IACtE,oGAAoG;IACnF,gBAAgB,GAAG,IAAI,GAAG,EAAuB,CAAA;IAElE;;;OAGG;IACH,YAAY,MAA2B,EAAE,YAAmB;QAC1D,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAA;QACzC,IAAI,CAAC,aAAa,GAAG,YAAY,CAAA;QACjC,KAAK,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,MAAM,EAAE,CAAC;YACvC,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;YAChD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAA;QAC5B,CAAC;IACH,CAAC;IAED,oCAAoC;IACpC,MAAM,CAAC,OAAoB;QACzB,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;IACvD,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,KAAkB;QACxB,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,EAAE,CAAC;YAChC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1B,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC7B,CAAC;IAED,8FAA8F;IACtF,QAAQ,CAAC,KAAkB;QACjC,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAA;QAC7D,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAA;QACtD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;QAC7B,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;OAIG;IACK,cAAc,CAAC,KAAkB;QACvC,IAAI,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,4BAA4B,EAAE,CAAC;YAC/E,OAAO,IAAI,CAAA;QACb,CAAC;QACD,MAAM,KAAK,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;QACzD,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAA;QACvC,OAAO,KAAK,GAAG,sBAAsB,KAAK,CAAC,CAAA;IAC7C,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK;QACT,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,KAAK,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QAC3B,CAAC;QACD,SAAS,CAAC;YACR,MAAM,QAAQ,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;YAC3C,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YAC3B,8DAA8D;YAC9D,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,QAAQ,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3G,OAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,QAAQ,CAAC,KAAkB;QACvC,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;QACzC,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,GAAG,IAAI,CAAC,CAAA;QACrE,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,OAAM;QACR,CAAC;QAED,8FAA8F;QAC9F,qFAAqF;QACrF,MAAM,UAAU,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,GAAG,CAAA;QAC/C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,UAAU,CAAC,CAAA;QAElC,MAAM,MAAM,GAAG,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,MAAM,CAAA;QAC/D,MAAM,QAAQ,GAAG,eAAe,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;QAE/C,IAAI,CAAC;YACH,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;gBAClC,8FAA8F;gBAC9F,8FAA8F;gBAC9F,0FAA0F;gBAC1F,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;gBACvC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YACrC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,CAAA;QACtC,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,aAAa,CAAC,KAAkB,EAAE,cAAsB,EAAE,GAAY;QAC5E,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;QAChE,IAAI,CAAC,oBAAoB,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAA;QAC9C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,cAAc,CAAC,CAAA;QACtC,MAAM,MAAM,GAAG,cAAc,CAAC,GAAG,CAAC,CAAC,OAAO,CAAA;QAE1C,IAAI,QAAQ,IAAI,4BAA4B,EAAE,CAAC;YAC7C,MAAM,CAAC,KAAK,CACV,UAAU,KAAK,CAAC,IAAI,gBAAgB,QAAQ,cAAc,MAAM,0CAA0C,CAC3G,CAAA;QACH,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,IAAI,cAAc,MAAM,8BAA8B,CAAC,CAAA;QACrF,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,MAAM,CAAC,KAAkB,EAAE,QAA2B;QAClE,MAAM,SAAS,GAAG,IAAI,CAAC,wBAAwB,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,SAAS,CAAA;QACrE,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QAEzD,IAAI,SAAS,EAAE,CAAC;YACd,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,aAAa,EAAE,CAAC,CAAA;YACvF,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;YAC3G,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAA8B,EAAE,CAAC,CAAC,CAAC,MAAM,KAAK,UAAU,CAAC,CAAA;YAC3F,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,cAAc,CACtB,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,EACzC,mBAAmB,QAAQ,CAAC,MAAM,OAAO,OAAO,CAAC,MAAM,oBAAoB,CAC5E,CAAA;YACH,CAAC;YACD,OAAM;QACR,CAAC;QAED,iGAAiG;QACjG,MAAM,KAAK,CAAC,WAAY,CAAC,QAAQ,EAAE,EAAE,eAAe,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC/F,CAAC;IAED;;;;;;OAMG;IACK,KAAK;QACX,IAAI,OAAO,GAAG,QAAQ,CAAA;QACtB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;QAC3D,CAAC;QACD,IAAI,OAAO,KAAK,QAAQ,EAAE,CAAC;YACzB,OAAM;QACR,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,GAAG,OAAO,CAAC,CAAA;IAC5E,CAAC;CACF"}

package/dist/src/memory/extraction/model-extractor.d.ts

@@ -0,0 +1,32 @@
+import { type MessageData } from '../../types/messages.js';
+import type { Model } from '../../models/model.js';
+import type { ExtractionResult, Extractor, ExtractorContext } from './types.js';
+/** Options for {@link ModelExtractor}. */
+export interface ModelExtractorOptions {
+    /** Model used to extract facts. Defaults to the agent's own model; set a cheaper one to cut cost. */
+    model?: Model;
+    /** System prompt steering what counts as a fact. Defaults to a general fact-extraction prompt. */
+    systemPrompt?: string;
+}
+/**
+ * An {@link Extractor} that calls a language model to distill messages into discrete facts.
+ *
+ * Use for self-managed stores that hold plain text and want automatic distillation. Backends that
+ * extract server-side should omit the extractor entirely (the no-extractor passthrough hands them
+ * raw messages instead).
+ *
+ * @example
+ * ```typescript
+ * extraction: {
+ *   trigger: [new InvocationTrigger()],
+ *   extractor: new ModelExtractor({ model: cheapModel, systemPrompt: 'Extract user preferences.' }),
+ * }
+ * ```
+ */
+export declare class ModelExtractor implements Extractor {
+    private readonly _model?;
+    private readonly _systemPrompt;
+    constructor(options?: ModelExtractorOptions);
+    extract(messages: MessageData[], context?: ExtractorContext): Promise<ExtractionResult[]>;
+}
+//# sourceMappingURL=model-extractor.d.ts.map

package/dist/src/memory/extraction/model-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-extractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/extraction/model-extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC9E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAGlD,OAAO,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAO/E,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,qGAAqG;IACrG,KAAK,CAAC,EAAE,KAAK,CAAA;IACb,kGAAkG;IAClG,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAe,YAAW,SAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAO;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;gBAE1B,OAAO,GAAE,qBAA0B;IAOzC,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAsChG"}

package/dist/src/memory/extraction/model-extractor.js

@@ -0,0 +1,118 @@
+import { Message, TextBlock } from '../../types/messages.js';
+import { logger } from '../../logging/logger.js';
+/** Default instruction guiding the model to emit discrete, durable facts as a JSON array. */
+const DEFAULT_SYSTEM_PROMPT = `You extract durable facts worth remembering across future conversations from a transcript.
+
+Return ONLY a JSON array of objects, each: {"content": string}. Each object is one discrete, self-contained fact (a preference, decision, or stable detail about the user or task). Do not include transient chit-chat, questions, or anything already obvious. If there is nothing worth remembering, return [].`;
+/**
+ * An {@link Extractor} that calls a language model to distill messages into discrete facts.
+ *
+ * Use for self-managed stores that hold plain text and want automatic distillation. Backends that
+ * extract server-side should omit the extractor entirely (the no-extractor passthrough hands them
+ * raw messages instead).
+ *
+ * @example
+ * ```typescript
+ * extraction: {
+ *   trigger: [new InvocationTrigger()],
+ *   extractor: new ModelExtractor({ model: cheapModel, systemPrompt: 'Extract user preferences.' }),
+ * }
+ * ```
+ */
+export class ModelExtractor {
+    _model;
+    _systemPrompt;
+    constructor(options = {}) {
+        if (options.model !== undefined) {
+            this._model = options.model;
+        }
+        this._systemPrompt = options.systemPrompt ?? DEFAULT_SYSTEM_PROMPT;
+    }
+    async extract(messages, context) {
+        const model = this._model ?? context?.defaultModel;
+        if (!model) {
+            throw new Error('ModelExtractor: no model configured and no default model available');
+        }
+        if (messages.length === 0) {
+            return [];
+        }
+        // Present the transcript as a single user turn so the system prompt governs extraction, rather
+        // than feeding raw roles the model might try to continue.
+        const transcript = messages.map((message) => _renderMessage(message)).join('\n');
+        const promptMessages = [
+            new Message({
+                role: 'user',
+                content: [new TextBlock(`Extract facts from the following transcript:\n\n${transcript}`)],
+            }),
+        ];
+        const stream = model.streamAggregated(promptMessages, { systemPrompt: this._systemPrompt });
+        // Manual .next() loop: streamAggregated returns its result as the generator return value
+        // (done:true), which for-await-of discards.
+        let result;
+        for (;;) {
+            result = await stream.next();
+            if (result.done)
+                break;
+        }
+        if (!result?.done || !result.value) {
+            throw new Error('ModelExtractor: model returned no response');
+        }
+        const text = result.value.message.content
+            .map((block) => ('text' in block ? block.text : ''))
+            .join('')
+            .trim();
+        return _parseEntries(text, model.constructor.name);
+    }
+}
+/** Renders one message as `role: text`, joining its text blocks. */
+function _renderMessage(message) {
+    const text = message.content
+        .map((block) => ('text' in block ? block.text : ''))
+        .filter((part) => part.length > 0)
+        .join('\n');
+    return `${message.role}: ${text}`;
+}
+/**
+ * Parses the model's response into entries. Tolerates the array being wrapped in prose or a fenced
+ * code block by extracting the first top-level bracketed array. Malformed output yields no entries
+ * (logged) rather than throwing, so a single bad extraction never breaks the agent loop.
+ */
+function _parseEntries(text, modelName) {
+    const json = _extractJsonArray(text);
+    if (json === undefined) {
+        logger.warn(`model=<${modelName}> | ModelExtractor: no JSON array in model output, skipping`);
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (err) {
+        logger.warn(`model=<${modelName}>, error=<${String(err)}> | ModelExtractor: failed to parse output`);
+        return [];
+    }
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    const entries = [];
+    for (const item of parsed) {
+        if (item && typeof item === 'object' && typeof item.content === 'string') {
+            const record = item;
+            const content = record.content.trim();
+            if (content.length > 0) {
+                entries.push({ content, ...(record.metadata !== undefined && { metadata: record.metadata }) });
+            }
+        }
+    }
+    return entries;
+}
+/** Extracts the substring from the first `[` to the last `]`, or undefined if absent. */
+function _extractJsonArray(text) {
+    const start = text.indexOf('[');
+    const end = text.lastIndexOf(']');
+    if (start === -1 || end === -1 || end < start) {
+        return undefined;
+    }
+    return text.slice(start, end + 1);
+}
+//# sourceMappingURL=model-extractor.js.map

package/dist/src/memory/extraction/model-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-extractor.js","sourceRoot":"","sources":["../../../../src/memory/extraction/model-extractor.ts"],"names":[],"mappings":"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"}

package/dist/src/memory/extraction/resolve-extraction-config.d.ts

@@ -0,0 +1,46 @@
+import type { MemoryStore } from '../types.js';
+import { type ExtractionConfig, type ExtractionTrigger, type Extractor, type MemoryMessageFilter } from './types.js';
+/**
+ * Default cadence when an {@link ExtractionConfig} omits its `trigger`: extract every N turns.
+ * @internal
+ */
+export declare const DEFAULT_EXTRACTION_TRIGGER_TURNS = 5;
+/**
+ * An {@link ExtractionConfig} with every field resolved to a concrete value, ready to drive
+ * extraction. Produced by {@link resolveExtractionConfig} so the {@link MemoryManager} and
+ * {@link ExtractionCoordinator} never have to re-apply defaults or normalize shapes.
+ * @internal
+ */
+export interface ResolvedExtractionConfig {
+    /** Normalized to an array (a single trigger is wrapped). Never empty for a resolved config. */
+    triggers: ExtractionTrigger[];
+    /**
+     * The extractor that distills facts client-side and stores them via the store's `add` method, or
+     * `undefined` to use the store's `addMessages` method (server-side extraction).
+     */
+    extractor?: Extractor;
+    /** The content-block filter applied before extraction. */
+    filter: MemoryMessageFilter;
+}
+/**
+ * Resolves a store's `extraction` setting into a {@link ResolvedExtractionConfig}, applying defaults.
+ *
+ * The single place the `boolean | ExtractionConfig` shorthand is interpreted: `false`/omitted is off
+ * (returns `undefined`), `true` enables all defaults, an {@link ExtractionConfig} defaults its unset
+ * fields. The defaults are:
+ * - **trigger**: every {@link DEFAULT_EXTRACTION_TRIGGER_TURNS} turns. An explicit empty array is left
+ *   empty for the {@link MemoryManager} to reject.
+ * - **extractor**: chosen from the methods the store implements. A store that implements `addMessages`
+ *   supports server-side extraction, so it defaults to no extractor: the manager hands raw messages to
+ *   `addMessages` and the backend extracts them itself, with no model call. A store that implements only
+ *   `add` cannot extract server-side, so it defaults to a {@link ModelExtractor} that distills facts
+ *   client-side (via model calls) and stores each one through `add`.
+ * - **filter**: {@link DEFAULT_MEMORY_MESSAGE_FILTER}.
+ *
+ * @param extraction - The store's `extraction` setting
+ * @param store - The store, inspected for the write methods it implements to pick the default extractor
+ * @returns The resolved config, or `undefined` when extraction is disabled
+ * @internal
+ */
+export declare function resolveExtractionConfig(extraction: boolean | ExtractionConfig | undefined, store: Pick<MemoryStore, 'add' | 'addMessages'>): ResolvedExtractionConfig | undefined;
+//# sourceMappingURL=resolve-extraction-config.d.ts.map

package/dist/src/memory/extraction/resolve-extraction-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-extraction-config.d.ts","sourceRoot":"","sources":["../../../../src/memory/extraction/resolve-extraction-config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAG9C,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,SAAS,EACd,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,eAAO,MAAM,gCAAgC,IAAI,CAAA;AAEjD;;;;;GAKG;AACH,MAAM,WAAW,wBAAwB;IACvC,+FAA+F;IAC/F,QAAQ,EAAE,iBAAiB,EAAE,CAAA;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,0DAA0D;IAC1D,MAAM,EAAE,mBAAmB,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS,EAClD,KAAK,EAAE,IAAI,CAAC,WAAW,EAAE,KAAK,GAAG,aAAa,CAAC,GAC9C,wBAAwB,GAAG,SAAS,CAkCtC"}

package/dist/src/memory/extraction/resolve-extraction-config.js

@@ -0,0 +1,59 @@
+import { IntervalTrigger } from './triggers.js';
+import { ModelExtractor } from './model-extractor.js';
+import { DEFAULT_MEMORY_MESSAGE_FILTER, } from './types.js';
+/**
+ * Default cadence when an {@link ExtractionConfig} omits its `trigger`: extract every N turns.
+ * @internal
+ */
+export const DEFAULT_EXTRACTION_TRIGGER_TURNS = 5;
+/**
+ * Resolves a store's `extraction` setting into a {@link ResolvedExtractionConfig}, applying defaults.
+ *
+ * The single place the `boolean | ExtractionConfig` shorthand is interpreted: `false`/omitted is off
+ * (returns `undefined`), `true` enables all defaults, an {@link ExtractionConfig} defaults its unset
+ * fields. The defaults are:
+ * - **trigger**: every {@link DEFAULT_EXTRACTION_TRIGGER_TURNS} turns. An explicit empty array is left
+ *   empty for the {@link MemoryManager} to reject.
+ * - **extractor**: chosen from the methods the store implements. A store that implements `addMessages`
+ *   supports server-side extraction, so it defaults to no extractor: the manager hands raw messages to
+ *   `addMessages` and the backend extracts them itself, with no model call. A store that implements only
+ *   `add` cannot extract server-side, so it defaults to a {@link ModelExtractor} that distills facts
+ *   client-side (via model calls) and stores each one through `add`.
+ * - **filter**: {@link DEFAULT_MEMORY_MESSAGE_FILTER}.
+ *
+ * @param extraction - The store's `extraction` setting
+ * @param store - The store, inspected for the write methods it implements to pick the default extractor
+ * @returns The resolved config, or `undefined` when extraction is disabled
+ * @internal
+ */
+export function resolveExtractionConfig(extraction, store) {
+    if (!extraction) {
+        return undefined;
+    }
+    const config = extraction === true ? {} : extraction;
+    const triggers = config.trigger === undefined
+        ? [new IntervalTrigger({ turns: DEFAULT_EXTRACTION_TRIGGER_TURNS })]
+        : Array.isArray(config.trigger)
+            ? config.trigger
+            : [config.trigger];
+    let extractor = config.extractor;
+    if (extractor === undefined) {
+        // Pick the default extractor from the store's write methods:
+        // - implements `addMessages` (whether or not it also implements `add`): extract server-side. Leave
+        //   the extractor undefined so raw messages go straight to `addMessages` with no model call.
+        // - implements only `add`: it cannot extract server-side, so default to a ModelExtractor that
+        //   distills facts client-side and stores each via `add`.
+        const implementsAdd = typeof store.add === 'function';
+        const implementsAddMessages = typeof store.addMessages === 'function';
+        if (implementsAdd && !implementsAddMessages) {
+            extractor = new ModelExtractor();
+        }
+    }
+    const filter = config.filter ?? DEFAULT_MEMORY_MESSAGE_FILTER;
+    return {
+        triggers,
+        ...(extractor !== undefined && { extractor }),
+        filter,
+    };
+}
+//# sourceMappingURL=resolve-extraction-config.js.map

package/dist/src/memory/extraction/resolve-extraction-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-extraction-config.js","sourceRoot":"","sources":["../../../../src/memory/extraction/resolve-extraction-config.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EACL,6BAA6B,GAK9B,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,MAAM,CAAC,MAAM,gCAAgC,GAAG,CAAC,CAAA;AAoBjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,uBAAuB,CACrC,UAAkD,EAClD,KAA+C;IAE/C,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,OAAO,SAAS,CAAA;IAClB,CAAC;IACD,MAAM,MAAM,GAAqB,UAAU,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAA;IAEtE,MAAM,QAAQ,GACZ,MAAM,CAAC,OAAO,KAAK,SAAS;QAC1B,CAAC,CAAC,CAAC,IAAI,eAAe,CAAC,EAAE,KAAK,EAAE,gCAAgC,EAAE,CAAC,CAAC;QACpE,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;YAC7B,CAAC,CAAC,MAAM,CAAC,OAAO;YAChB,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IAExB,IAAI,SAAS,GAAG,MAAM,CAAC,SAAS,CAAA;IAChC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,6DAA6D;QAC7D,mGAAmG;QACnG,6FAA6F;QAC7F,8FAA8F;QAC9F,0DAA0D;QAC1D,MAAM,aAAa,GAAG,OAAO,KAAK,CAAC,GAAG,KAAK,UAAU,CAAA;QACrD,MAAM,qBAAqB,GAAG,OAAO,KAAK,CAAC,WAAW,KAAK,UAAU,CAAA;QACrE,IAAI,aAAa,IAAI,CAAC,qBAAqB,EAAE,CAAC;YAC5C,SAAS,GAAG,IAAI,cAAc,EAAE,CAAA;QAClC,CAAC;IACH,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,6BAA6B,CAAA;IAE7D,OAAO;QACL,QAAQ;QACR,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,MAAM;KACP,CAAA;AACH,CAAC"}

package/dist/src/memory/extraction/triggers.d.ts

@@ -0,0 +1,41 @@
+import { ExtractionTrigger, type ExtractionTriggerContext } from './types.js';
+/**
+ * Runs extraction after every agent invocation.
+ *
+ * The highest-fidelity option: nothing said in a turn is missed. Also the most expensive when an
+ * {@link Extractor} is configured (a model call per turn) — for a server-side-extraction backend
+ * with no extractor it is just a per-turn write.
+ *
+ * @example
+ * ```typescript
+ * extraction: { trigger: [new InvocationTrigger()] }
+ * ```
+ */
+export declare class InvocationTrigger extends ExtractionTrigger {
+    readonly name = "invocation";
+    attach(context: ExtractionTriggerContext): void;
+}
+/** Options for {@link IntervalTrigger}. */
+export interface IntervalTriggerOptions {
+    /** Run extraction once every this many invocations. Must be a positive integer. */
+    turns: number;
+}
+/**
+ * Runs extraction every N agent invocations.
+ *
+ * A controllable middle ground: extraction (and any model call it entails) happens on a cadence
+ * rather than every turn, while the high-water mark guarantees the messages from the skipped turns
+ * are still processed when the trigger does fire.
+ *
+ * @example
+ * ```typescript
+ * extraction: { trigger: [new IntervalTrigger({ turns: 5 })] }
+ * ```
+ */
+export declare class IntervalTrigger extends ExtractionTrigger {
+    readonly name = "interval";
+    private readonly _turns;
+    constructor(options: IntervalTriggerOptions);
+    attach(context: ExtractionTriggerContext): void;
+}
+//# sourceMappingURL=triggers.d.ts.map

package/dist/src/memory/extraction/triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../../../../src/memory/extraction/triggers.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,KAAK,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAE7E;;;;;;;;;;;GAWG;AACH,qBAAa,iBAAkB,SAAQ,iBAAiB;IACtD,QAAQ,CAAC,IAAI,gBAAe;IAE5B,MAAM,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI;CAKhD;AAED,2CAA2C;AAC3C,MAAM,WAAW,sBAAsB;IACrC,mFAAmF;IACnF,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,SAAQ,iBAAiB;IACpD,QAAQ,CAAC,IAAI,cAAa;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;gBAEnB,OAAO,EAAE,sBAAsB;IAQ3C,MAAM,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI;CAgBhD"}

package/dist/src/memory/extraction/triggers.js

@@ -0,0 +1,59 @@
+import { AfterInvocationEvent } from '../../hooks/events.js';
+import { HookOrder } from '../../hooks/types.js';
+import { ExtractionTrigger } from './types.js';
+/**
+ * Runs extraction after every agent invocation.
+ *
+ * The highest-fidelity option: nothing said in a turn is missed. Also the most expensive when an
+ * {@link Extractor} is configured (a model call per turn) — for a server-side-extraction backend
+ * with no extractor it is just a per-turn write.
+ *
+ * @example
+ * ```typescript
+ * extraction: { trigger: [new InvocationTrigger()] }
+ * ```
+ */
+export class InvocationTrigger extends ExtractionTrigger {
+    name = 'invocation';
+    attach(context) {
+        // Run after the SDK's own after-invocation hooks (e.g. session persistence) so extraction sees
+        // the fully settled turn.
+        context.agent.addHook(AfterInvocationEvent, () => context.fire(), { order: HookOrder.SDK_LAST });
+    }
+}
+/**
+ * Runs extraction every N agent invocations.
+ *
+ * A controllable middle ground: extraction (and any model call it entails) happens on a cadence
+ * rather than every turn, while the high-water mark guarantees the messages from the skipped turns
+ * are still processed when the trigger does fire.
+ *
+ * @example
+ * ```typescript
+ * extraction: { trigger: [new IntervalTrigger({ turns: 5 })] }
+ * ```
+ */
+export class IntervalTrigger extends ExtractionTrigger {
+    name = 'interval';
+    _turns;
+    constructor(options) {
+        super();
+        if (!Number.isInteger(options.turns) || options.turns < 1) {
+            throw new Error(`IntervalTrigger: turns must be a positive integer, got ${options.turns}`);
+        }
+        this._turns = options.turns;
+    }
+    attach(context) {
+        // Per-attach counter: each store this trigger is configured on gets its own count via a fresh
+        // closure, so two stores sharing one IntervalTrigger instance still fire independently.
+        let count = 0;
+        context.agent.addHook(AfterInvocationEvent, () => {
+            count++;
+            // `fire` is fire-and-forget (returns void); it dispatches extraction in the background.
+            if (count % this._turns === 0) {
+                context.fire();
+            }
+        }, { order: HookOrder.SDK_LAST });
+    }
+}
+//# sourceMappingURL=triggers.js.map

package/dist/src/memory/extraction/triggers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.js","sourceRoot":"","sources":["../../../../src/memory/extraction/triggers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAA;AAC5D,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAA;AAChD,OAAO,EAAE,iBAAiB,EAAiC,MAAM,YAAY,CAAA;AAE7E;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,iBAAkB,SAAQ,iBAAiB;IAC7C,IAAI,GAAG,YAAY,CAAA;IAE5B,MAAM,CAAC,OAAiC;QACtC,+FAA+F;QAC/F,0BAA0B;QAC1B,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,oBAAoB,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,QAAQ,EAAE,CAAC,CAAA;IAClG,CAAC;CACF;AAQD;;;;;;;;;;;GAWG;AACH,MAAM,OAAO,eAAgB,SAAQ,iBAAiB;IAC3C,IAAI,GAAG,UAAU,CAAA;IACT,MAAM,CAAQ;IAE/B,YAAY,OAA+B;QACzC,KAAK,EAAE,CAAA;QACP,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;YAC1D,MAAM,IAAI,KAAK,CAAC,0DAA0D,OAAO,CAAC,KAAK,EAAE,CAAC,CAAA;QAC5F,CAAC;QACD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,KAAK,CAAA;IAC7B,CAAC;IAED,MAAM,CAAC,OAAiC;QACtC,8FAA8F;QAC9F,wFAAwF;QACxF,IAAI,KAAK,GAAG,CAAC,CAAA;QACb,OAAO,CAAC,KAAK,CAAC,OAAO,CACnB,oBAAoB,EACpB,GAAG,EAAE;YACH,KAAK,EAAE,CAAA;YACP,wFAAwF;YACxF,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9B,OAAO,CAAC,IAAI,EAAE,CAAA;YAChB,CAAC;QACH,CAAC,EACD,EAAE,KAAK,EAAE,SAAS,CAAC,QAAQ,EAAE,CAC9B,CAAA;IACH,CAAC;CACF"}