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;
    /** Resolved injection config, or `false` when injection is disabled. */
    private readonly _injectionConfig;
    /**
     * Tracer for memory operation spans, shared with the extraction coordinator. A per-instance
     * Tracer is intentional: it wraps the same global OTel provider, and parent-child nesting is
     * established via OTel context (context.active() / context.with()), not instance hierarchy — so a
     * fresh instance routes spans to the same exporter and parents correctly without fragmenting traces.
     */
    private readonly _tracer;
    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 two independent behaviors:
     * - **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.
     * - **Injection**: when enabled, registers an `InvokeModelStage` middleware that folds retrieved
     *   memory into the model input for each call without touching durable history. See
     *   {@link _provideMemoryContext}, the `renderContent` callback the middleware invokes.
     *
     * @param agent - The agent this plugin is being attached to
     */
    initAgent(agent: LocalAgent): Promise<void>;
    /** Call `initialize()` on each store that implements it. */
    private _initStores;
    /** Wires background extraction for stores configured with {@link ExtractionConfig}. */
    private _initExtraction;
    /**
     * Registers the injection middleware when injection is enabled. Folds retrieved memory into the
     * model input for each call via {@link _provideMemoryContext}, without touching durable history. A
     * no-op when injection is disabled.
     */
    private _initInjection;
    /**
     * Produces the memory context text to inject for a model call, or `undefined` to skip. This is the
     * `renderContent` callback the injection middleware invokes (see {@link initAgent}).
     *
     * Derives a query (the configured callback or an adaptive default), searches memory, and renders the
     * top entries. Skips silently (returns `undefined`) when no query can be derived or the search
     * returns nothing. The rendering callback throwing fails open (returns `undefined`).
     *
     * @param messages - The current conversation, as data
     * @param config - The resolved injection configuration
     * @returns The injected text, or `undefined` when there is nothing to inject
     */
    private _provideMemoryContext;
    /**
     * 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>;
    /**
     * Derives the injection search query. Uses the configured `query` callback when provided (a throw
     * fails open, skipping injection); otherwise an adaptive default: the latest user message's text on
     * a user turn, or the most recent assistant message's text otherwise (the previous autonomous step).
     *
     * @param messages - The current conversation, as data
     * @param config - The resolved injection configuration
     * @returns The query string, or `undefined` when none is available
     */
    private _resolveInjectionQuery;
    /**
     * Default injection format: a `<memory>` block with one `<entry>` per result. Each entry carries a
     * `source` attribute naming the originating store (when known) so the model can attribute memories.
     *
     * @param entries - The retrieved memory entries to render
     * @returns The rendered `<memory>` block
     */
    private _defaultInjectionFormat;
    /** Returns the index of the last element matching `predicate`, or -1. */
    private _findLastIndex;
    /**
     * 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
     * @param detached - Internal. When the write runs detached from the call that scheduled it (the
     *   fire-and-forget add tool path), start the span as a trace root rather than parenting to a
     *   possibly-ended span.
     * @internal
     */
    add(content: string, options?: MemoryAddOptions, detached?: boolean): 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