@strands-agents/sdk 1.4.0 → 1.5.0

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

@@ -0,0 +1,133 @@
+import type { JSONValue } from '../../types/json.js';
+import type { MessageData, ContentBlockData } from '../../types/messages.js';
+import type { Model } from '../../models/model.js';
+import type { LocalAgent } from '../../types/agent.js';
+type DistributedKeyof<Union> = Union extends unknown ? keyof Union : never;
+/**
+ * Content block kinds that {@link MemoryMessageFilter} can exclude before messages reach an
+ * {@link Extractor} or the no-extractor passthrough.
+ *
+ * Derived from the SDK's {@link ContentBlockData} union: every member's discriminator key is its
+ * kind (`{ toolUse: ... }` → `'toolUse'`, `{ text: string }` → `'text'`), so this tracks new block
+ * types automatically instead of drifting. Matches the runtime `_blockKind` used to filter.
+ */
+export type MemoryContentBlockType = DistributedKeyof<ContentBlockData>;
+/**
+ * Filters content blocks out of messages before extraction.
+ *
+ * Blocks whose kind is in {@link exclude} are stripped; a message left with no content is dropped
+ * entirely. Defaults to excluding tool traffic (`toolUse` / `toolResult`), which is rarely useful as
+ * long-term memory and adds noise.
+ */
+export interface MemoryMessageFilter {
+    /** Content block kinds to strip before extraction. */
+    exclude: MemoryContentBlockType[];
+}
+/** Default filter: drop tool-call traffic, keep everything else (text, reasoning, media). */
+export declare const DEFAULT_MEMORY_MESSAGE_FILTER: MemoryMessageFilter;
+/**
+ * A discrete entry produced by an {@link Extractor}, ready to be written to a store via its `add`.
+ */
+export interface ExtractionResult {
+    /** The textual content of the entry. */
+    content: string;
+    /** Optional metadata to associate with the entry. */
+    metadata?: Record<string, JSONValue>;
+}
+/**
+ * Context passed to {@link Extractor.extract}.
+ *
+ * Lets the manager hand an extractor a fallback model without the extractor having to be wired to
+ * the agent directly. {@link ModelExtractor} uses its own configured model when set, else
+ * {@link defaultModel}.
+ */
+export interface ExtractorContext {
+    /** The agent's model, supplied so an extractor can default to it. */
+    defaultModel?: Model;
+}
+/**
+ * Transforms conversation messages into discrete, searchable entries.
+ *
+ * Implementations distill raw turns into facts worth remembering. Optional on a store's
+ * {@link ExtractionConfig}: when absent, the manager passes messages straight to the store (see the
+ * no-extractor passthrough on {@link MemoryStore}), which is the right path for backends that
+ * extract server-side.
+ */
+export interface Extractor {
+    /**
+     * Extract entries from a batch of messages.
+     *
+     * @param messages - The filtered messages to extract from
+     * @param context - Optional context (e.g. a fallback model)
+     * @returns The entries to write to the store
+     */
+    extract(messages: MessageData[], context?: ExtractorContext): Promise<ExtractionResult[]>;
+}
+/**
+ * Context handed to {@link ExtractionTrigger.attach} so a trigger can wire itself into the agent
+ * lifecycle and signal when extraction should run for its store.
+ */
+export interface ExtractionTriggerContext {
+    /** The agent the trigger attaches its hooks to. */
+    agent: LocalAgent;
+    /** Save this store's unsaved messages now. Runs in the background and returns immediately, so calling it from a hook never blocks the agent. To await completion, see {@link MemoryManager.flush}. */
+    fire: () => void;
+}
+/**
+ * Controls when a store's {@link ExtractionConfig} runs.
+ *
+ * A trigger is a self-attaching value object: {@link attach} wires whatever agent hooks the trigger
+ * needs and calls {@link ExtractionTriggerContext.fire} when extraction should happen. Extend this
+ * class for custom triggering logic.
+ *
+ * A trigger must eventually fire for its store's buffered messages to be written: the high-water-mark
+ * dedup means skipped turns are still picked up on the *next* fire, but a trigger that never fires
+ * never extracts (and its messages stay buffered for the session). For a guaranteed final write at a
+ * boundary, the caller uses {@link MemoryManager.flush}, which force-completes regardless of triggers.
+ */
+export declare abstract class ExtractionTrigger {
+    /** Stable identifier for this trigger kind, used in logging. */
+    abstract readonly name: string;
+    /**
+     * Wire this trigger into the agent lifecycle.
+     *
+     * Called once per store during {@link MemoryManager} initialization. Register hooks on
+     * `context.agent` and call `context.fire()` when extraction should run.
+     *
+     * @param context - The agent to attach to and the fire callback bound to this trigger's store
+     */
+    abstract attach(context: ExtractionTriggerContext): void;
+}
+/**
+ * Per-store automatic-extraction configuration.
+ *
+ * Lives on a store (via {@link MemoryStoreConfig}) so different stores can extract on different
+ * schedules and in different styles. {@link trigger} decides *when*; {@link extractor} decides *how*
+ * (omit it to pass raw messages straight to the store); {@link filter} prunes content blocks first.
+ */
+export interface ExtractionConfig {
+    /**
+     * When to run extraction. A single trigger or an array; multiple triggers compose (extraction runs
+     * whenever any of them fires). Omit to default to every 5 turns; an explicit empty array is
+     * rejected at construction.
+     */
+    trigger?: ExtractionTrigger | ExtractionTrigger[];
+    /**
+     * How to turn messages into entries (client-side extraction). When set, the store must implement
+     * `add` and each produced entry is stored through it. When omitted, the default depends on the
+     * store's write methods: a store implementing `addMessages` uses server-side extraction (the manager
+     * hands it the raw messages, no model call), while a store implementing only `add` defaults to a
+     * {@link ModelExtractor} that distills facts client-side.
+     */
+    extractor?: Extractor;
+    /**
+     * Content blocks to strip before extraction. Defaults to {@link DEFAULT_MEMORY_MESSAGE_FILTER}
+     * (excludes `toolUse` / `toolResult`).
+     *
+     * For use cases or extractors with value in distilling over the *full* turn you instead want
+     * everything: pass `{ exclude: [] }` so tool blocks reach `addMessages`.
+     */
+    filter?: MemoryMessageFilter;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/memory/extraction/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC5E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,uBAAuB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAItD,KAAK,gBAAgB,CAAC,KAAK,IAAI,KAAK,SAAS,OAAO,GAAG,MAAM,KAAK,GAAG,KAAK,CAAA;AAE1E;;;;;;;GAOG;AACH,MAAM,MAAM,sBAAsB,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAAA;AAEvE;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,OAAO,EAAE,sBAAsB,EAAE,CAAA;CAClC;AAED,6FAA6F;AAC7F,eAAO,MAAM,6BAA6B,EAAE,mBAE3C,CAAA;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAA;IACf,qDAAqD;IACrD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;CACrC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,YAAY,CAAC,EAAE,KAAK,CAAA;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAA;CAC1F;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,mDAAmD;IACnD,KAAK,EAAE,UAAU,CAAA;IACjB,sMAAsM;IACtM,IAAI,EAAE,MAAM,IAAI,CAAA;CACjB;AAED;;;;;;;;;;;GAWG;AACH,8BAAsB,iBAAiB;IACrC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAE9B;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI;CACzD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,CAAA;IACjD;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;CAC7B"}

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

@@ -0,0 +1,19 @@
+/** Default filter: drop tool-call traffic, keep everything else (text, reasoning, media). */
+export const DEFAULT_MEMORY_MESSAGE_FILTER = {
+    exclude: ['toolUse', 'toolResult'],
+};
+/**
+ * Controls when a store's {@link ExtractionConfig} runs.
+ *
+ * A trigger is a self-attaching value object: {@link attach} wires whatever agent hooks the trigger
+ * needs and calls {@link ExtractionTriggerContext.fire} when extraction should happen. Extend this
+ * class for custom triggering logic.
+ *
+ * A trigger must eventually fire for its store's buffered messages to be written: the high-water-mark
+ * dedup means skipped turns are still picked up on the *next* fire, but a trigger that never fires
+ * never extracts (and its messages stay buffered for the session). For a guaranteed final write at a
+ * boundary, the caller uses {@link MemoryManager.flush}, which force-completes regardless of triggers.
+ */
+export class ExtractionTrigger {
+}
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/memory/extraction/types.ts"],"names":[],"mappings":"AA+BA,6FAA6F;AAC7F,MAAM,CAAC,MAAM,6BAA6B,GAAwB;IAChE,OAAO,EAAE,CAAC,SAAS,EAAE,YAAY,CAAC;CACnC,CAAA;AAsDD;;;;;;;;;;;GAWG;AACH,MAAM,OAAgB,iBAAiB;CAatC"}

package/dist/src/memory/index.d.ts

@@ -0,0 +1,9 @@
+export { MemoryManager } from './memory-manager.js';
+export type { MemoryEntry, MemoryStore, MemoryStoreConfig, SearchOptions, AddMessagesContext, MemorySearchOptions, MemoryAddOptions, MemoryToolConfig, MemoryAddToolConfig, MemoryManagerConfig, } from './types.js';
+export { ExtractionTrigger } from './extraction/types.js';
+export { InvocationTrigger, IntervalTrigger } from './extraction/triggers.js';
+export type { IntervalTriggerOptions } from './extraction/triggers.js';
+export { ModelExtractor } from './extraction/model-extractor.js';
+export type { ModelExtractorOptions } from './extraction/model-extractor.js';
+export type { ExtractionConfig, Extractor, ExtractorContext, ExtractionResult, ExtractionTriggerContext, MemoryMessageFilter, MemoryContentBlockType, } from './extraction/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/memory/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,YAAY,EACV,WAAW,EACX,WAAW,EACX,iBAAiB,EACjB,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACnB,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,YAAY,CAAA;AAEnB,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAC7E,YAAY,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAA;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA;AAChE,YAAY,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAA;AAC5E,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,uBAAuB,CAAA"}

package/dist/src/memory/index.js

@@ -0,0 +1,5 @@
+export { MemoryManager } from './memory-manager.js';
+export { ExtractionTrigger } from './extraction/types.js';
+export { InvocationTrigger, IntervalTrigger } from './extraction/triggers.js';
+export { ModelExtractor } from './extraction/model-extractor.js';
+//# sourceMappingURL=index.js.map

package/dist/src/memory/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAcnD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAA;AACzD,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAA;AAE7E,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAA"}

package/dist/src/memory/memory-manager.d.ts

@@ -0,0 +1,131 @@
+import type { Plugin } from '../plugins/plugin.js';
+import type { LocalAgent } from '../types/agent.js';
+import type { Tool } from '../tools/tool.js';
+import type { MemoryEntry, MemoryManagerConfig, MemorySearchOptions, MemoryAddOptions } from './types.js';
+/**
+ * Default maximum results per store when neither the caller nor the store specifies one.
+ * Resolved by the {@link MemoryManager}.
+ */
+export declare const DEFAULT_MAX_SEARCH_RESULTS = 3;
+/**
+ * Provides cross-session memory retrieval and storage for agents.
+ *
+ * Manages one or more {@link MemoryStore} backends, exposing `search_memory` and
+ * `add_memory` tools for agent-driven recall and persistence. Any tools the stores
+ * themselves provide (via {@link MemoryStore.getTools}) are registered alongside these.
+ *
+ * @example
+ * ```typescript
+ * import { Agent, MemoryManager } from '@strands-agents/sdk'
+ *
+ * // Config shorthand
+ * const agent = new Agent({
+ *   model,
+ *   memoryManager: { stores: [myStore], addToolConfig: true },
+ * })
+ *
+ * // Class instance (for programmatic access)
+ * const memoryManager = new MemoryManager({ stores: [myStore], addToolConfig: true })
+ * const agent = new Agent({ model, memoryManager })
+ * await memoryManager.search('user preferences')
+ * ```
+ */
+export declare class MemoryManager implements Plugin {
+    readonly name = "strands:memory-manager";
+    private readonly _config;
+    private readonly _searchStores;
+    /** All writable stores — the unscoped target set for the programmatic {@link add} method. */
+    private readonly _addStores;
+    private readonly _searchToolConfig;
+    private readonly _addToolConfig;
+    private readonly _addToolStores;
+    /** Stores with extraction enabled, each paired with its resolved config; wired up in {@link initAgent}. */
+    private readonly _extractionStores;
+    /** Background extraction coordinator, created in {@link initAgent} when extraction is configured. */
+    private _coordinator;
+    constructor(config: MemoryManagerConfig);
+    /**
+     * Resolves the writable stores the `add_memory` tool may write to. When `stores` is given, each
+     * entry (a store name or a {@link MemoryStore} instance) must resolve by name to a configured,
+     * `add`-capable writable store (else throws). Omitted means all such stores.
+     */
+    private _resolveAddToolStores;
+    /**
+     * Initializes the plugin with the agent.
+     *
+     * Wires up automatic extraction for any store configured with {@link ExtractionConfig}: buffers
+     * conversation messages and attaches each store's triggers. A no-op when no store uses extraction.
+     *
+     * @param agent - The agent this plugin is being attached to
+     */
+    initAgent(agent: LocalAgent): void;
+    /**
+     * Saves every store's remaining messages and waits for all saves to finish. No-op when no store has
+     * extraction configured.
+     *
+     * Extraction normally runs in the background, so the most recent turn may not be saved yet when the
+     * agent responds. Call this once at a boundary you control - typically your app's shutdown handler -
+     * so nothing is lost. A process killed before then (crash, hard timeout) may still lose the last
+     * unsaved turn; a more frequent trigger narrows that window.
+     *
+     * Do not call this after every turn alongside a periodic trigger: it forces a save each time and so
+     * defeats the trigger's schedule.
+     */
+    flush(): Promise<void>;
+    /**
+     * Returns tools registered by this plugin.
+     *
+     * Includes the manager's own `search_memory` / `add_memory` tools (per their config) plus any
+     * tools the configured stores expose via {@link MemoryStore.getTools}.
+     *
+     * @returns Array of tools to register with the agent
+     */
+    getTools(): Tool[];
+    /**
+     * Search stores for entries matching the query. If `stores` is provided, only searches to those named stores.
+     *
+     * This method is unscoped with full access to all configured stores.
+     * Tool-level store scoping is applied by the search tool callback.
+     * When `options.stores` is omitted, all stores are searched.
+     *
+     * Only `maxSearchResults` and routing (`stores`) cross this layer. Store-specific search
+     * parameters (e.g. a Bedrock metadata `filter` or search-type override) are not expressible here
+     * across heterogeneous stores — set them as per-instance defaults on the store, or call the
+     * store's own `search()` directly for full control. Per-instance store policy (such as a tenant
+     * filter) always applies, including when reached through the `search_memory` tool.
+     *
+     * @param query - The search query string
+     * @param options - Optional max results (forwarded to all stores) and store name filter
+     * @returns Array of memory entries from matching stores
+     */
+    search(query: string, options?: MemorySearchOptions): Promise<MemoryEntry[]>;
+    /**
+     * Add content to writable stores. If `stores` is provided, only writes to those named stores;
+     * otherwise all writable stores are targeted.
+     *
+     * This method is unscoped, with full access to all configured writable stores; tool-level store
+     * scoping is applied by the add tool callback. Target stores are validated first (an unknown or
+     * read-only named store throws), then the writes are awaited: per-store failures are logged, and
+     * an `AggregateError` is thrown if any store fails.
+     *
+     * @param content - The text content to add
+     * @param options - Optional metadata and store name filter
+     */
+    add(content: string, options?: MemoryAddOptions): Promise<void>;
+    /**
+     * Resolves the store names that a tool callback should target against the tool's scoped set.
+     *
+     * - Omitting `requested` targets all scoped stores.
+     * - Names that are in scope are kept; out-of-scope names are dropped with a warning.
+     * - When every requested name is out of scope, throws so the model receives an actionable error
+     *   (the tool layer turns the thrown error into a model-visible result it can correct from).
+     *
+     * @param scopedNames - Store names available to this tool
+     * @param requested - Store names the model asked for, if any
+     * @returns A non-empty list of in-scope store names to target
+     */
+    private _resolveToolTargets;
+    private _createSearchTool;
+    private _createAddTool;
+}
+//# sourceMappingURL=memory-manager.d.ts.map

package/dist/src/memory/memory-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-manager.d.ts","sourceRoot":"","sources":["../../../src/memory/memory-manager.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAC5C,OAAO,KAAK,EACV,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EAEnB,gBAAgB,EAGjB,MAAM,YAAY,CAAA;AAgBnB;;;GAGG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAe3C;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAc,YAAW,MAAM;IAC1C,QAAQ,CAAC,IAAI,4BAA2B;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,6FAA6F;IAC7F,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAe;IAC1C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0B;IAC5D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAe;IAC9C,2GAA2G;IAC3G,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;IACvD,qGAAqG;IACrG,OAAO,CAAC,YAAY,CAAmC;gBAE3C,MAAM,EAAE,mBAAmB;IAoEvC;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAsB7B;;;;;;;OAOG;IACH,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAoBlC;;;;;;;;;;;OAWG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;;;;;OAOG;IACH,QAAQ,IAAI,IAAI,EAAE;IAmBlB;;;;;;;;;;;;;;;;OAgBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA2ClF;;;;;;;;;;;OAWG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IA2CrE;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,mBAAmB;IAqB3B,OAAO,CAAC,iBAAiB;IAyCzB,OAAO,CAAC,cAAc;CAsDvB"}