@strands-agents/sdk 1.4.0 → 1.5.0

package/dist/src/memory/memory-manager.js

@@ -0,0 +1,404 @@
+import { MessageAddedEvent } from '../hooks/events.js';
+import { ExtractionCoordinator } from './extraction/coordinator.js';
+import { resolveExtractionConfig } from './extraction/resolve-extraction-config.js';
+import { tool } from '../tools/tool-factory.js';
+import { z } from 'zod';
+import { logger } from '../logging/logger.js';
+import { normalizeError } from '../errors.js';
+const SEARCH_TOOL_DESCRIPTION = 'Search long-term memory for facts, preferences, or context from previous conversations. Use when you need background about the user or topic that may have been discussed before.';
+const ADD_TOOL_DESCRIPTION = 'Add facts, preferences, or decisions to long-term memory so they are remembered across conversations. Use when the user shares something worth recalling later.';
+/**
+ * Default maximum results per store when neither the caller nor the store specifies one.
+ * Resolved by the {@link MemoryManager}.
+ */
+export const DEFAULT_MAX_SEARCH_RESULTS = 3;
+/** Flattens nested AggregateErrors so the leaves are concrete reasons, not errors-of-errors. */
+function _flattenReasons(reasons) {
+    return reasons.flatMap((reason) => (reason instanceof AggregateError ? _flattenReasons(reason.errors) : [reason]));
+}
+/**
+ * Whether a store has any write sink. The `add_memory` tool and programmatic `add` use `add`;
+ * extraction additionally accepts `addMessages`. A writable store must have at least one.
+ */
+function _hasWriteSink(store) {
+    return typeof store.add === 'function' || typeof store.addMessages === 'function';
+}
+/**
+ * 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 class MemoryManager {
+    name = 'strands:memory-manager';
+    _config;
+    _searchStores;
+    /** All writable stores — the unscoped target set for the programmatic {@link add} method. */
+    _addStores;
+    _searchToolConfig;
+    _addToolConfig;
+    _addToolStores;
+    /** Stores with extraction enabled, each paired with its resolved config; wired up in {@link initAgent}. */
+    _extractionStores;
+    /** Background extraction coordinator, created in {@link initAgent} when extraction is configured. */
+    _coordinator;
+    constructor(config) {
+        if (config.stores.length === 0) {
+            throw new Error('MemoryManager: at least one store is required');
+        }
+        const seenNames = new Set();
+        const extractionStores = [];
+        for (const store of config.stores) {
+            if (seenNames.has(store.name)) {
+                throw new Error(`MemoryManager: duplicate store name '${store.name}'`);
+            }
+            seenNames.add(store.name);
+            if (store.writable && !_hasWriteSink(store)) {
+                throw new Error(`MemoryManager: store '${store.name}' is writable but has no add or addMessages method`);
+            }
+            if (store.extraction) {
+                if (!store.writable) {
+                    throw new Error(`MemoryManager: store '${store.name}' has extraction config but is not writable`);
+                }
+                const resolved = resolveExtractionConfig(store.extraction, store);
+                if (resolved.triggers.length === 0) {
+                    throw new Error(`MemoryManager: store '${store.name}' has extraction config but no triggers`);
+                }
+                // Each extraction shape needs its matching write sink. An extractor produces discrete entries
+                // written via `add`; without an extractor the raw message batch goes to `addMessages`.
+                if (resolved.extractor) {
+                    if (typeof store.add !== 'function') {
+                        throw new Error(`MemoryManager: store '${store.name}' has an extractor but no add method (extracted entries are written via add)`);
+                    }
+                }
+                else if (typeof store.addMessages !== 'function') {
+                    throw new Error(`MemoryManager: store '${store.name}' has extraction config without an extractor but no addMessages method`);
+                }
+                extractionStores.push({ store, config: resolved });
+            }
+        }
+        this._config = config;
+        this._searchStores = config.stores;
+        // `add`-targeting paths (tool / programmatic) need an `add` method specifically.
+        this._addStores = config.stores.filter((s) => s.writable && typeof s.add === 'function');
+        this._extractionStores = extractionStores;
+        this._searchToolConfig =
+            config.searchToolConfig === false
+                ? false
+                : typeof config.searchToolConfig === 'object'
+                    ? config.searchToolConfig
+                    : {};
+        if (config.addToolConfig === undefined || config.addToolConfig === false) {
+            this._addToolConfig = false;
+            this._addToolStores = [];
+        }
+        else {
+            // The `add_memory` tool writes via `add` (not `addMessages`), so it needs an `add`-capable store.
+            if (this._addStores.length === 0) {
+                throw new Error('MemoryManager: addToolConfig is enabled but no writable stores implement add');
+            }
+            this._addToolConfig = typeof config.addToolConfig === 'object' ? config.addToolConfig : {};
+            this._addToolStores = this._resolveAddToolStores(this._addToolConfig);
+        }
+    }
+    /**
+     * 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.
+     */
+    _resolveAddToolStores(toolConfig) {
+        if (toolConfig.stores === undefined) {
+            return this._addStores;
+        }
+        const names = toolConfig.stores.map((store) => (typeof store === 'string' ? store : store.name));
+        return [...new Set(names)].map((name) => {
+            const found = this._config.stores.find((s) => s.name === name);
+            if (!found) {
+                throw new Error(`MemoryManager: addToolConfig store '${name}' not found`);
+            }
+            if (!found.writable) {
+                throw new Error(`MemoryManager: addToolConfig store '${name}' is not writable`);
+            }
+            if (typeof found.add !== 'function') {
+                throw new Error(`MemoryManager: addToolConfig store '${name}' has no add method (only addMessages)`);
+            }
+            return found;
+        });
+    }
+    /**
+     * 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) {
+        if (this._extractionStores.length === 0) {
+            return;
+        }
+        const coordinator = new ExtractionCoordinator(this._extractionStores, agent.model);
+        this._coordinator = coordinator;
+        // Buffer every message the agent adds, so extraction has its own copy to save from.
+        agent.addHook(MessageAddedEvent, (event) => {
+            coordinator.record(event.message.toJSON());
+        });
+        for (const { store, config } of this._extractionStores) {
+            for (const trigger of config.triggers) {
+                trigger.attach({ agent, fire: () => void coordinator.process(store) });
+            }
+        }
+    }
+    /**
+     * 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.
+     */
+    async flush() {
+        await this._coordinator?.flush();
+    }
+    /**
+     * 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() {
+        const tools = [];
+        if (this._searchToolConfig !== false) {
+            tools.push(this._createSearchTool(this._searchToolConfig));
+        }
+        if (this._addToolConfig !== false) {
+            tools.push(this._createAddTool(this._addToolConfig, this._addToolStores));
+        }
+        for (const store of this._config.stores) {
+            const storeTools = store.getTools?.() ?? [];
+            tools.push(...storeTools);
+        }
+        return tools;
+    }
+    /**
+     * 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
+     */
+    async search(query, options) {
+        logger.debug(`query=<${query}>, max_search_results=<${options?.maxSearchResults}>, stores=<${options?.stores}> | searching stores`);
+        const targetStores = options?.stores !== undefined
+            ? [...new Set(options.stores)].map((name) => {
+                const found = this._config.stores.find((s) => s.name === name);
+                if (!found) {
+                    throw new Error(`MemoryManager: store '${name}' not found`);
+                }
+                return found;
+            })
+            : this._config.stores;
+        const settled = await Promise.allSettled(targetStores.map((store) => store.search(query, {
+            maxSearchResults: options?.maxSearchResults ?? store.maxSearchResults ?? DEFAULT_MAX_SEARCH_RESULTS,
+        })));
+        const results = [];
+        for (let i = 0; i < settled.length; i++) {
+            const settledResult = settled[i];
+            const storeName = targetStores[i].name;
+            if (settledResult.status === 'rejected') {
+                logger.warn(`store=<${storeName}>, reason=<${normalizeError(settledResult.reason).message}> | store search failed`);
+                continue;
+            }
+            for (const entry of settledResult.value) {
+                results.push({ ...entry, storeName });
+            }
+        }
+        logger.debug(`results=<${results.length}> | search complete`);
+        return results;
+    }
+    /**
+     * 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
+     */
+    async add(content, options) {
+        let writableStores;
+        if (options?.stores !== undefined) {
+            writableStores = [...new Set(options.stores)].map((name) => {
+                const found = this._config.stores.find((s) => s.name === name);
+                if (!found) {
+                    throw new Error(`MemoryManager: store '${name}' not found`);
+                }
+                if (!found.writable) {
+                    throw new Error(`MemoryManager: store '${name}' is read-only`);
+                }
+                return found;
+            });
+        }
+        else {
+            writableStores = this._addStores;
+        }
+        if (writableStores.length === 0) {
+            throw new Error('MemoryManager: no writable store matched');
+        }
+        const settled = await Promise.allSettled(writableStores.map((store) => store.add(content, options?.metadata)));
+        const failures = [];
+        for (let i = 0; i < settled.length; i++) {
+            const settledResult = settled[i];
+            if (settledResult.status === 'rejected') {
+                const storeName = writableStores[i].name;
+                logger.warn(`store=<${storeName}>, reason=<${normalizeError(settledResult.reason).message}> | store write failed`);
+                failures.push({ store: storeName, reason: settledResult.reason });
+            }
+        }
+        if (failures.length > 0) {
+            throw new AggregateError(failures.map((failure) => failure.reason), `MemoryManager: store writes failed: ${failures.map((failure) => failure.store).join(', ')}`);
+        }
+    }
+    /**
+     * 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
+     */
+    _resolveToolTargets(scopedNames, requested) {
+        if (requested === undefined || requested.length === 0) {
+            return scopedNames;
+        }
+        const inScope = requested.filter((name) => scopedNames.includes(name));
+        const outOfScope = requested.filter((name) => !scopedNames.includes(name));
+        if (inScope.length === 0) {
+            throw new Error(`MemoryManager: requested=<${requested.join(', ')}> | none of the requested memory stores are available; available stores: ${scopedNames.join(', ')}`);
+        }
+        if (outOfScope.length > 0) {
+            logger.warn(`requested=<${outOfScope.join(', ')}> | ignoring memory stores outside this tool's scope`);
+        }
+        return inScope;
+    }
+    _createSearchTool(config) {
+        let description = config.description ?? SEARCH_TOOL_DESCRIPTION;
+        const storeDescriptions = this._searchStores
+            .filter((s) => s.description)
+            .map((s) => `- ${s.name}: ${s.description}`);
+        if (storeDescriptions.length > 0) {
+            description += `\n\nAvailable memory stores:\n${storeDescriptions.join('\n')}`;
+            description +=
+                '\n\nYou can target one or more memory stores by name if you know which domains are relevant, or omit the stores parameter to search all.';
+        }
+        const scopedNames = this._searchStores.map((s) => s.name);
+        const inputSchema = z.object({
+            query: z.string().describe('What to search for'),
+            maxSearchResults: z.number().optional().describe('Maximum number of results per store'),
+            stores: z
+                .array(z.string())
+                .optional()
+                .describe('Filter to specific stores by name. Omit to search all available stores.'),
+        });
+        return tool({
+            name: config.name ?? 'search_memory',
+            description,
+            inputSchema,
+            callback: async (input) => {
+                const stores = this._resolveToolTargets(scopedNames, input.stores);
+                const results = await this.search(input.query, {
+                    ...(input.maxSearchResults != null && { maxSearchResults: input.maxSearchResults }),
+                    stores,
+                });
+                return results.map((entry) => ({
+                    content: entry.content,
+                    ...(entry.storeName && { storeName: entry.storeName }),
+                    ...(entry.metadata && { metadata: entry.metadata }),
+                }));
+            },
+        });
+    }
+    _createAddTool(config, stores) {
+        let description = config.description ?? ADD_TOOL_DESCRIPTION;
+        const storeDescriptions = stores.filter((s) => s.description).map((s) => `- ${s.name}: ${s.description}`);
+        if (storeDescriptions.length > 0) {
+            description += `\n\nAvailable writable stores:\n${storeDescriptions.join('\n')}`;
+            description +=
+                '\n\nYou can target a specific store by name to route facts to the right place, or omit to add to all available writable stores.';
+        }
+        const scopedNames = stores.map((s) => s.name);
+        const waitForWrites = config.waitForWrites ?? true;
+        const inputSchema = z.object({
+            entries: z.array(z.string()).min(1).describe('Data to add to long-term memory'),
+            stores: z
+                .array(z.string())
+                .optional()
+                .describe('Target specific stores by name. Omit to add to all writable stores.'),
+        });
+        return tool({
+            name: config.name ?? 'add_memory',
+            description,
+            inputSchema,
+            callback: async (input) => {
+                const stores = this._resolveToolTargets(scopedNames, input.stores);
+                if (!waitForWrites) {
+                    // Fire-and-forget: dispatch the writes without awaiting so the agent loop isn't blocked.
+                    // add() logs per-store failures; swallow the rejection so it isn't an unhandled rejection.
+                    for (const content of input.entries) {
+                        void this.add(content, { stores }).catch(() => { });
+                    }
+                    return { accepted: input.entries.length };
+                }
+                // Await mode: surface failures to the model with concrete reasons (not nested AggregateErrors).
+                const settled = await Promise.allSettled(input.entries.map((content) => this.add(content, { stores })));
+                const failures = settled.filter((settledResult) => settledResult.status === 'rejected');
+                if (failures.length > 0) {
+                    const reasons = _flattenReasons(failures.map((failure) => failure.reason));
+                    throw new AggregateError(reasons, `MemoryManager: failed to add ${failures.length} of ${input.entries.length} entries: ${reasons.map((reason) => normalizeError(reason).message).join('; ')}`);
+                }
+                return { stored: input.entries.length };
+            },
+        });
+    }
+}
+//# sourceMappingURL=memory-manager.js.map

package/dist/src/memory/memory-manager.js.map

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

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

@@ -0,0 +1,213 @@
+import type { JSONValue } from '../types/json.js';
+import type { MessageData } from '../types/messages.js';
+import type { Tool } from '../tools/tool.js';
+import type { ExtractionConfig } from './extraction/types.js';
+/**
+ * A single memory entry retrieved from or stored to a memory store.
+ */
+export interface MemoryEntry {
+    /** The textual content of this memory entry. */
+    content: string;
+    /**
+     * Name of the store this entry came from. Populated by {@link MemoryManager.search} so callers
+     * (and the model, via `search_memory`) can tell which store produced each result and refine
+     * targeting. Stores need not set this themselves.
+     */
+    storeName?: string;
+    /** Optional metadata (e.g., score, source, id, timestamp). */
+    metadata?: Record<string, JSONValue>;
+}
+/**
+ * Options passed to {@link MemoryStore.search}.
+ *
+ * Store implementations may extend this with backend-specific fields (e.g. a metadata filter or
+ * search-type override) in their own `search` signature. Note that {@link MemoryManager.search}
+ * only forwards the base fields here across its (potentially heterogeneous) stores — to use a
+ * store's extended options, call that store's `search` directly, or set them as per-instance
+ * defaults on the store.
+ */
+export interface SearchOptions {
+    /** Maximum number of results to return from this store. */
+    maxSearchResults?: number;
+}
+/**
+ * Context the {@link MemoryManager} supplies to {@link MemoryStore.addMessages} alongside a batch.
+ *
+ * An extension point: fields are added here without changing the {@link MemoryStore.addMessages}
+ * signature.
+ */
+export interface AddMessagesContext {
+    /**
+     * Per-message identities aligned one-to-one with `messages` (`sequenceNumbers[i]` identifies
+     * `messages[i]`). A retried batch reuses the same numbers, so a store can build an idempotency key
+     * that survives retries - unlike a content hash, which collides when two messages share text (e.g.
+     * "ok"). Numbers increase with order but may have gaps, and reset to 0 each agent run, so a durable
+     * dedup token must combine one with a run-unique id.
+     */
+    readonly sequenceNumbers?: readonly number[];
+}
+/**
+ * Declarative properties shared by every memory store and its config.
+ *
+ * This is the single source of truth for a store's identity and behavior knobs. Both the runtime
+ * {@link MemoryStore} interface and concrete store configs extend it, so these fields are declared
+ * once. Concrete stores add their own backend-specific config fields on top.
+ */
+export interface MemoryStoreConfig {
+    /** Identifier for this store, used to target specific stores in search/add tools. Must be unique. */
+    readonly name: string;
+    /** Human-readable description of what this store contains. Included in tool descriptions. */
+    readonly description?: string;
+    /**
+     * Default maximum number of results this store returns per search, used when a caller does not
+     * pass a per-call `maxSearchResults`.
+     */
+    readonly maxSearchResults?: number;
+    /**
+     * Whether this store accepts writes. Optional at config time (caller intent, defaults to `false`);
+     * concrete stores resolve it to a definite boolean on the {@link MemoryStore} interface.
+     *
+     * @defaultValue false
+     */
+    readonly writable?: boolean;
+    /**
+     * Automatic-extraction config for this writable store, as a `boolean | config` shorthand. `true`
+     * enables it with defaults; an {@link ExtractionConfig} defaults any unset field; `false`/omitted is off.
+     *
+     * The defaults run every 5 turns, and the extraction method depends on the store's write methods. A
+     * store implementing `addMessages` uses server-side extraction: the manager hands it the raw messages
+     * and the backend extracts them, with no model call. A store implementing only `add` uses a
+     * {@link ModelExtractor} for client-side extraction: it calls the agent's model to distill facts and
+     * stores each one via `add`.
+     *
+     * @defaultValue false
+     */
+    readonly extraction?: boolean | ExtractionConfig;
+}
+/**
+ * Interface for a memory store backend.
+ *
+ * Extends {@link MemoryStoreConfig} with the runtime methods a store provides. Every store is
+ * searchable; the resolved `writable` flag declares whether it also accepts writes, which is how
+ * the {@link MemoryManager} decides where to route them. `search_memory` can query all stores, while
+ * `add_memory` can only write to `writable` stores.
+ */
+export interface MemoryStore extends MemoryStoreConfig {
+    /**
+     * Whether this store accepts writes.
+     * - `false`: searchable only; never written to.
+     * - `true`: searchable and writable. Requires at least one write sink — `add`, `addMessages`,
+     *   or both — to be implemented.
+     */
+    readonly writable: boolean;
+    /** Search the store for entries matching the query, ordered by relevance. */
+    search(query: string, options?: SearchOptions): Promise<MemoryEntry[]>;
+    /**
+     * Add a single piece of content to the store. Used by the `add_memory` tool, the programmatic
+     * {@link MemoryManager.add}, and by extraction when an {@link ExtractionConfig.extractor} produces
+     * discrete entries (an extraction config with an extractor requires this method).
+     *
+     * A store satisfies `writable: true` with `add`, {@link addMessages}, or both. A store may also
+     * implement `add` while declaring `writable: false`, in which case it is never invoked.
+     *
+     * Extraction writes are at-least-once: if one entry in a batch fails, the whole batch is retried, so
+     * `add` may be called again with content it already stored. Implementations used with extraction
+     * should tolerate duplicate writes (e.g. dedupe, or accept that retries may re-store an entry).
+     *
+     * The resolved value is store-specific (e.g. a created record id or a write receipt) — each backend
+     * may return whatever shape fits it. The {@link MemoryManager} does not consume this value (it only
+     * awaits completion); callers using a store directly can read it.
+     */
+    add?(content: string, metadata?: Record<string, JSONValue>): Promise<unknown>;
+    /**
+     * Ingest a batch of conversation messages, preserving their role structure. This is the sink for
+     * automatic extraction that does not distill facts client-side: the manager hands the filtered
+     * {@link MessageData} batch straight here in one call — no serialization, no model call. Backends
+     * that turn raw turns into memory themselves (e.g. role-aware conversational APIs that summarize
+     * server-side) implement this so the user/assistant structure survives. A store using extraction
+     * implements this method, unless it configures an {@link ExtractionConfig.extractor} (which produces
+     * discrete entries written via {@link add} instead).
+     *
+     * Satisfies `writable: true` the same way {@link add} does. The resolved value is store-specific
+     * and not consumed by the manager.
+     *
+     * A store scopes its writes (e.g. by tenant or namespace) through its own configuration. The
+     * {@link AddMessagesContext} parameter lets the manager pass additional per-batch context to the
+     * store.
+     *
+     * @param messages - The filtered messages to ingest, in order
+     * @param context - Manager-supplied per-batch context (see {@link AddMessagesContext})
+     */
+    addMessages?(messages: MessageData[], context?: AddMessagesContext): Promise<unknown>;
+    /**
+     * Returns store-specific tools to register with the agent, through a {@link MemoryManager}. Registers
+     * tools alongside `search_memory` / `add_memory` tools if enabled on the {@link MemoryManager}.
+     * Implement to expose backend-specific capabilities (e.g. a store-native query tool).
+     *  Optional, mirrors {@link Plugin.getTools}.
+     *
+     * @returns Array of tools provided by this store
+     */
+    getTools?(): Tool[];
+}
+/**
+ * Options for {@link MemoryManager.search}.
+ *
+ * Extends the store primitive {@link SearchOptions} with manager-level store routing.
+ */
+export interface MemorySearchOptions extends SearchOptions {
+    /** Filter to specific stores by name. Omit to search all. */
+    stores?: string[];
+}
+/**
+ * Options for {@link MemoryManager.add}.
+ */
+export interface MemoryAddOptions {
+    /** Metadata to associate with the added entry. */
+    metadata?: Record<string, JSONValue>;
+    /** Filter to specific writable stores by name. Omit to write to all writable stores. */
+    stores?: string[];
+}
+/**
+ * Configuration for customizing a memory tool's name or description.
+ */
+export interface MemoryToolConfig {
+    /** Custom tool name. */
+    name?: string;
+    /** Custom tool description. */
+    description?: string;
+}
+/**
+ * Configuration for the `add_memory` tool. Extends {@link MemoryToolConfig} with an explicit
+ * allowlist of stores the tool may write to.
+ */
+export interface MemoryAddToolConfig extends MemoryToolConfig {
+    /**
+     * The writable stores the `add_memory` tool may write to, given as store names or the
+     * {@link MemoryStore} instances themselves. Each must be a configured, `writable` store.
+     *  Omit (or set `addToolConfig: true`) to allow all writable stores.
+     */
+    stores?: (string | MemoryStore)[];
+    /**
+     * Whether the tool waits for store writes before returning to the model. Defaults to `true`.
+     * - `true` (default): waits for writes — the tool returns `{ stored }` on success, or surfaces a
+     *   failure to the model if any store write fails.
+     * - `false`: fire-and-forget — the tool returns `{ accepted }` once writes are dispatched (so a
+     *   slow backend never blocks the agent loop); per-store failures are logged.
+     */
+    waitForWrites?: boolean;
+}
+/**
+ * Configuration for the {@link MemoryManager}.
+ */
+export interface MemoryManagerConfig {
+    /** One or more memory stores to manage. */
+    stores: MemoryStore[];
+    /** Search tool configuration. Defaults to `true`. */
+    searchToolConfig?: MemoryToolConfig | boolean;
+    /**
+     * Add tool configuration. Defaults to `false` (opt-in). `true` lets the tool write to all
+     * writable stores; pass a {@link MemoryAddToolConfig} with `stores` to restrict it to specific ones.
+     */
+    addToolConfig?: MemoryAddToolConfig | boolean;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/src/memory/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/memory/types.ts"],"names":[],"mappings":""}

package/dist/src/middleware/__tests__/agent-middleware.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-middleware.test.d.ts.map