bedrock-agentcore 0.2.3 → 0.3.0

package/README.md

@@ -104,7 +104,7 @@ const agent = new Agent({
 - **Code Interpreter** — Execute Python/JS/TS in a sandbox → [Examples](https://github.com/awslabs/bedrock-agentcore-samples-typescript/tree/main/primitives/tools/code-interpreter)
 - **Browser** — Cloud-based web automation → [Examples](https://github.com/awslabs/bedrock-agentcore-samples-typescript/tree/main/primitives/tools/browser)
 - **Identity** — Manage API keys and OAuth tokens → [Examples](https://github.com/awslabs/bedrock-agentcore-samples-typescript/tree/main/primitives/identity)
-- **Memory** — Persistent knowledge across sessions (coming soon)
+- **Memory** — Persistent knowledge across sessions (experimental) → [Guide](docs/MEMORY.md)
 - **Gateway** — Transform APIs into MCP tools (coming soon)
 - **Observability** — OpenTelemetry tracing (coming soon)
 

package/dist/src/memory/integrations/strands/factory.d.ts

@@ -0,0 +1,78 @@
+import { BedrockAgentCoreClient } from '@aws-sdk/client-bedrock-agentcore';
+import type { AwsCredentialIdentityProvider } from '@aws-sdk/types';
+import type { ExtractionTrigger, MemoryMessageFilter } from '@strands-agents/sdk';
+import { AgentCoreMemoryStore } from './store.js';
+import { type MetadataProvider } from './types.js';
+/** Per-namespace read configuration. */
+export interface AgentCoreNamespaceConfig {
+    /** Namespace template, e.g. `/strategy/{id}/actor/{actorId}/preferences`. */
+    namespace: string;
+    /** Store name; defaults to a slug derived from the namespace. */
+    name?: string;
+    description?: string;
+    maxSearchResults?: number;
+    minScore?: number;
+    /** Over-fetch multiplier when `minScore` is set (see {@link AgentCoreMemoryStoreConfig.overFetchFactor}). */
+    overFetchFactor?: number;
+    /** Marks this the single write sink. Defaults to the first namespace when extraction is enabled; see {@link assertWritableTopology}. */
+    writable?: boolean;
+}
+/**
+ * Object form of the {@link CreateAgentCoreMemoryStoresInput.extraction} switch: writable, with optional
+ * control over write cadence and which message content is written.
+ */
+export interface AgentCoreExtractionConfig {
+    /**
+     * When buffered turns are flushed to `createEvent`. Omit for the MemoryManager's default
+     * (`IntervalTrigger`); pass any Strands {@link ExtractionTrigger} or an array. A trigger only sets
+     * cadence (fire-and-forget) — `MemoryManager.flush()` is what guarantees durability.
+     */
+    cadence?: ExtractionTrigger | ExtractionTrigger[];
+    /**
+     * Which message content blocks to exclude before writing (the extraction `filter`). Omit to use the
+     * framework default (drops tool use/result). Forwarded to the store's `ExtractionConfig.filter`.
+     */
+    filter?: MemoryMessageFilter;
+}
+export interface CreateAgentCoreMemoryStoresInput {
+    memoryId: string;
+    actorId: string;
+    sessionId: string;
+    /**
+     * Read namespaces — one store is built per entry, each reading its own exact namespace prefix. To read a
+     * whole subtree instead, that is a single store: construct it directly with
+     * `new AgentCoreMemoryStore({ ...identity, namespacePath })`.
+     */
+    namespaces: AgentCoreNamespaceConfig[];
+    /**
+     * The single write switch: omit/`false` = recall-only; `true` = writable with the default cadence;
+     * `{ cadence?, filter? }` = writable with a custom cadence/filter. The writer namespace is chosen by
+     * the per-namespace `writable` flag (else the first).
+     */
+    extraction?: boolean | AgentCoreExtractionConfig;
+    metadataProvider?: MetadataProvider;
+    /**
+     * Max conversational turns packed into one `createEvent` write (default
+     * {@link DEFAULT_MAX_TURNS_PER_EVENT}). Combined with the extraction trigger cadence, this controls
+     * write API-call volume: a flush of N turns is sent as `ceil(n / maxTurnsPerEvent)` events.
+     */
+    maxTurnsPerEvent?: number;
+    region?: string;
+    credentialsProvider?: AwsCredentialIdentityProvider;
+    /** Shared client; one is constructed (and reused across the returned stores) if omitted. */
+    client?: BedrockAgentCoreClient;
+}
+/**
+ * At most one store may be writable. `createEvent` is namespace-free (it writes the whole conversation to
+ * the `(memoryId, actorId, sessionId)` stream), so two writers would emit duplicate events that nothing
+ * upstream dedupes — and a store can't see its siblings, so the rule can only be enforced here, at
+ * construction. Exported so hand-built (`new`) multi-store setups can guard themselves. With
+ * `expectExtraction`, a writer is required (0 writers throws).
+ */
+export declare function assertWritableTopology(stores: readonly AgentCoreMemoryStore[], expectExtraction?: boolean): void;
+/**
+ * Build the stores for one `(actorId, sessionId)` — one shared client, one writer — ready to spread into
+ * `MemoryManagerConfig.stores`. Called once per `(actorId, sessionId)` by a multi-actor server.
+ */
+export declare function createAgentCoreMemoryStores(input: CreateAgentCoreMemoryStoresInput): AgentCoreMemoryStore[];
+//# sourceMappingURL=factory.d.ts.map

package/dist/src/memory/integrations/strands/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../../../src/memory/integrations/strands/factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mCAAmC,CAAA;AAC1E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,gBAAgB,CAAA;AACnE,OAAO,KAAK,EAAoB,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,YAAY,CAAA;AAEnB,wCAAwC;AACxC,MAAM,WAAW,wBAAwB;IACvC,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAA;IACjB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,6GAA6G;IAC7G,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,wIAAwI;IACxI,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,OAAO,CAAC,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,CAAA;IACjD;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;CAC7B;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IAEjB;;;;OAIG;IACH,UAAU,EAAE,wBAAwB,EAAE,CAAA;IAEtC;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,GAAG,yBAAyB,CAAA;IAEhD,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;IAEnC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,mBAAmB,CAAC,EAAE,6BAA6B,CAAA;IACnD,4FAA4F;IAC5F,MAAM,CAAC,EAAE,sBAAsB,CAAA;CAChC;AAwBD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,EAAE,gBAAgB,UAAQ,GAAG,IAAI,CAgB9G;AAED;;;GAGG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,gCAAgC,GAAG,oBAAoB,EAAE,CAiF3G"}

package/dist/src/memory/integrations/strands/factory.js

@@ -0,0 +1,108 @@
+import { BedrockAgentCoreClient } from '@aws-sdk/client-bedrock-agentcore';
+import { AgentCoreMemoryStore } from './store.js';
+import { DEFAULT_REGION, } from './types.js';
+/** Optional fields are spread conditionally so an explicit `undefined` never violates `exactOptionalPropertyTypes`. */
+function buildStoreConfig(args) {
+    const { config, ns, writable, extraction } = args;
+    return {
+        // Spread the shared identity flat — same client/identity object reused across the set.
+        ...config,
+        namespace: ns.namespace,
+        writable,
+        ...(ns.name !== undefined && { name: ns.name }),
+        ...(ns.description !== undefined && { description: ns.description }),
+        ...(ns.maxSearchResults !== undefined && { maxSearchResults: ns.maxSearchResults }),
+        ...(ns.minScore !== undefined && { minScore: ns.minScore }),
+        ...(ns.overFetchFactor !== undefined && { overFetchFactor: ns.overFetchFactor }),
+        ...(writable && extraction !== undefined && { extraction }),
+    };
+}
+/**
+ * At most one store may be writable. `createEvent` is namespace-free (it writes the whole conversation to
+ * the `(memoryId, actorId, sessionId)` stream), so two writers would emit duplicate events that nothing
+ * upstream dedupes — and a store can't see its siblings, so the rule can only be enforced here, at
+ * construction. Exported so hand-built (`new`) multi-store setups can guard themselves. With
+ * `expectExtraction`, a writer is required (0 writers throws).
+ */
+export function assertWritableTopology(stores, expectExtraction = false) {
+    const writers = stores.filter((s) => s.writable);
+    if (writers.length > 1) {
+        throw new Error(`AgentCore memory: at most one store may be writable, but ${writers.length} are ` +
+            `(${writers.map((s) => `"${s.name}"`).join(', ')}). createEvent is namespace-free, so multiple ` +
+            'writable stores would write duplicate events to the same (memoryId, actorId, sessionId) stream. ' +
+            'Mark exactly one namespace writable.');
+    }
+    if (expectExtraction && writers.length === 0) {
+        throw new Error('AgentCore memory: extraction is enabled but no store is writable. Mark one namespace ' +
+            '`writable: true` (or omit extraction for recall-only).');
+    }
+}
+/**
+ * Build the stores for one `(actorId, sessionId)` — one shared client, one writer — ready to spread into
+ * `MemoryManagerConfig.stores`. Called once per `(actorId, sessionId)` by a multi-actor server.
+ */
+export function createAgentCoreMemoryStores(input) {
+    if (!Array.isArray(input.namespaces) || input.namespaces.length === 0) {
+        throw new Error('createAgentCoreMemoryStores: at least one namespace is required');
+    }
+    input.namespaces.forEach((ns, i) => {
+        if (ns === null || typeof ns !== 'object' || typeof ns.namespace !== 'string' || ns.namespace.trim().length === 0) {
+            throw new Error(`createAgentCoreMemoryStores: namespaces[${i}].namespace must be a non-empty string`);
+        }
+    });
+    // Validated here too, not only in the sender: a recall-only set never builds a sender.
+    if (input.maxTurnsPerEvent !== undefined &&
+        (!Number.isInteger(input.maxTurnsPerEvent) || input.maxTurnsPerEvent < 1)) {
+        throw new Error(`createAgentCoreMemoryStores: maxTurnsPerEvent must be a positive integer, got ${input.maxTurnsPerEvent}`);
+    }
+    // `true` passes through (the MemoryManager applies its own default cadence); only a custom
+    // cadence/filter builds an ExtractionConfig. `!Array.isArray` stops a stray array (typeof === 'object')
+    // being duck-typed as a config.
+    const writeEnabled = input.extraction !== undefined && input.extraction !== false;
+    const extractionObj = typeof input.extraction === 'object' && !Array.isArray(input.extraction) ? input.extraction : {};
+    const hasCustomConfig = extractionObj.cadence !== undefined || extractionObj.filter !== undefined;
+    const extraction = !writeEnabled
+        ? undefined
+        : hasCustomConfig
+            ? {
+                ...(extractionObj.cadence !== undefined && { trigger: extractionObj.cadence }),
+                ...(extractionObj.filter !== undefined && { filter: extractionObj.filter }),
+            }
+            : true;
+    const client = input.client ??
+        new BedrockAgentCoreClient({
+            region: input.region ?? process.env.AWS_REGION ?? DEFAULT_REGION,
+            ...(input.credentialsProvider && { credentials: input.credentialsProvider }),
+        });
+    // Shared connection + write identity, built once and reused across every store in this set.
+    const config = {
+        memoryId: input.memoryId,
+        actorId: input.actorId,
+        sessionId: input.sessionId,
+        ...(input.metadataProvider !== undefined && { metadataProvider: input.metadataProvider }),
+        ...(input.maxTurnsPerEvent !== undefined && { maxTurnsPerEvent: input.maxTurnsPerEvent }),
+        client,
+    };
+    // The default writer skips namespaces that explicitly opted out (`writable: false`) rather than
+    // overriding them; multiple explicit `writable: true` flags are left intact so assertWritableTopology
+    // catches the conflict loudly instead of silently picking one.
+    const anyFlagged = input.namespaces.some((ns) => ns.writable === true);
+    const defaultWriterIndex = !anyFlagged && writeEnabled ? input.namespaces.findIndex((ns) => ns.writable !== false) : -1;
+    if (writeEnabled && !anyFlagged && defaultWriterIndex === -1) {
+        throw new Error('createAgentCoreMemoryStores: extraction is enabled but every namespace is marked writable: false; ' +
+            'leave one namespace un-opted-out (or set writable: true on the intended writer).');
+    }
+    const stores = input.namespaces.map((ns, i) => {
+        const isWriter = ns.writable === true || i === defaultWriterIndex;
+        return new AgentCoreMemoryStore(buildStoreConfig({
+            config,
+            ns,
+            writable: isWriter,
+            extraction: isWriter ? extraction : undefined,
+        }));
+    });
+    // Store-name uniqueness is validated by the MemoryManager constructor, so we don't re-check it here.
+    assertWritableTopology(stores, writeEnabled);
+    return stores;
+}
+//# sourceMappingURL=factory.js.map

package/dist/src/memory/integrations/strands/factory.js.map

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

package/dist/src/memory/integrations/strands/format.d.ts

@@ -0,0 +1,17 @@
+import type { MessageData } from '@strands-agents/sdk';
+/** AgentCore conversational role. Mirrors the SDK `Role` enum values we emit. */
+export type AgentCoreRole = 'USER' | 'ASSISTANT';
+/**
+ * Map a Strands message role to the AgentCore conversational role.
+ *
+ * Strands roles are `'user' | 'assistant'`; AgentCore's `Role` enum also has `OTHER`/`TOOL`, but the
+ * conversation-ingestion path only ever produces user/assistant turns, so we map to that subset.
+ */
+export declare function mapRole(message: Pick<MessageData, 'role'>): AgentCoreRole;
+export declare function extractText(message: Pick<MessageData, 'content'>): string;
+/**
+ * Whether a message is a user/assistant turn carrying extractable text. Tool-only or empty messages
+ * yield no useful AgentCore event, so the sender skips them.
+ */
+export declare function isUserOrAssistantWithText(message: MessageData): boolean;
+//# sourceMappingURL=format.d.ts.map

package/dist/src/memory/integrations/strands/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../../../../src/memory/integrations/strands/format.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAuB,MAAM,qBAAqB,CAAA;AAE3E,iFAAiF;AACjF,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,WAAW,CAAA;AAEhD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,GAAG,aAAa,CAEzE;AAMD,wBAAgB,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,GAAG,MAAM,CAQzE;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAEvE"}

package/dist/src/memory/integrations/strands/format.js

@@ -0,0 +1,29 @@
+/**
+ * Map a Strands message role to the AgentCore conversational role.
+ *
+ * Strands roles are `'user' | 'assistant'`; AgentCore's `Role` enum also has `OTHER`/`TOOL`, but the
+ * conversation-ingestion path only ever produces user/assistant turns, so we map to that subset.
+ */
+export function mapRole(message) {
+    return message.role === 'user' ? 'USER' : 'ASSISTANT';
+}
+function isTextBlock(block) {
+    return typeof block === 'object' && block !== null && typeof block.text === 'string';
+}
+export function extractText(message) {
+    // Drop empty/blank text blocks before joining so an empty middle block doesn't leave a stray blank
+    // line in the concatenation (mirrors the upstream renderer).
+    return message.content
+        .filter(isTextBlock)
+        .map((block) => block.text.trim())
+        .filter((text) => text.length > 0)
+        .join('\n');
+}
+/**
+ * Whether a message is a user/assistant turn carrying extractable text. Tool-only or empty messages
+ * yield no useful AgentCore event, so the sender skips them.
+ */
+export function isUserOrAssistantWithText(message) {
+    return (message.role === 'user' || message.role === 'assistant') && extractText(message).length > 0;
+}
+//# sourceMappingURL=format.js.map

package/dist/src/memory/integrations/strands/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../../../../src/memory/integrations/strands/format.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,OAAkC;IACxD,OAAO,OAAO,CAAC,IAAI,KAAM,MAAsB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,WAAW,CAAA;AACxE,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,OAAQ,KAA4B,CAAC,IAAI,KAAK,QAAQ,CAAA;AAC9G,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAqC;IAC/D,mGAAmG;IACnG,6DAA6D;IAC7D,OAAO,OAAO,CAAC,OAAO;SACnB,MAAM,CAAC,WAAW,CAAC;SACnB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SACjC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;SACjC,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,OAAoB;IAC5D,OAAO,CAAC,OAAO,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,CAAC,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,MAAM,GAAG,CAAC,CAAA;AACrG,CAAC"}

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

@@ -0,0 +1,11 @@
+export { AgentCoreMemoryStore } from './store.js';
+export { createAgentCoreMemoryStores, assertWritableTopology } from './factory.js';
+export { AgentCoreEventSender } from './sender.js';
+export { resolveNamespace, slugifyNamespace, RESERVED_METADATA_PREFIX } from './types.js';
+export { configureMemoryLogging } from './logger.js';
+export type { Logger } from './logger.js';
+export type { AgentCoreMemoryConfig, AgentCoreMemoryStoreConfig, AgentCoreReadTarget, MetadataProvider, } from './types.js';
+export type { CreateAgentCoreMemoryStoresInput, AgentCoreNamespaceConfig, AgentCoreExtractionConfig, } from './factory.js';
+export type { AgentCoreEventSenderConfig } from './sender.js';
+export type { AgentCoreRole } from './format.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/memory/integrations/strands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AACzF,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AACpD,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAEzC,YAAY,EACV,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,gCAAgC,EAChC,wBAAwB,EACxB,yBAAyB,GAC1B,MAAM,cAAc,CAAA;AACrB,YAAY,EAAE,0BAA0B,EAAE,MAAM,aAAa,CAAA;AAC7D,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/memory/integrations/strands/index.js

@@ -0,0 +1,6 @@
+export { AgentCoreMemoryStore } from './store.js';
+export { createAgentCoreMemoryStores, assertWritableTopology } from './factory.js';
+export { AgentCoreEventSender } from './sender.js';
+export { resolveNamespace, slugifyNamespace, RESERVED_METADATA_PREFIX } from './types.js';
+export { configureMemoryLogging } from './logger.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/memory/integrations/strands/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,2BAA2B,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAClF,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AACzF,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/memory/integrations/strands/logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Module-local logger mirroring the Strands SDK `Logger` convention (debug/info no-op by default,
+ * warn/error to console), with an injection hook so callers can route logs through Pino/Winston/etc.
+ *
+ * Strands exports `configureLogging` and the `Logger` type but not its global `logger` instance, so an
+ * external package cannot import that instance. We therefore own a console-backed default here that
+ * matches the SDK's shape; if Strands later exposes its instance, this can delegate to it without
+ * touching the call sites (`logger.warn(...)`).
+ */
+export interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export declare const logger: Logger;
+/** Inject a custom logger for AgentCore memory logging (e.g. to route through the host app's logger). */
+export declare function configureMemoryLogging(customLogger: Logger): void;
+//# sourceMappingURL=logger.d.ts.map

package/dist/src/memory/integrations/strands/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../../../../src/memory/integrations/strands/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,MAAM;IACrB,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC/B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;IAC9B,KAAK,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAAA;CAChC;AAWD,eAAO,MAAM,MAAM,EAAE,MAKpB,CAAA;AAED,yGAAyG;AACzG,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEjE"}

package/dist/src/memory/integrations/strands/logger.js

@@ -0,0 +1,27 @@
+/**
+ * Module-local logger mirroring the Strands SDK `Logger` convention (debug/info no-op by default,
+ * warn/error to console), with an injection hook so callers can route logs through Pino/Winston/etc.
+ *
+ * Strands exports `configureLogging` and the `Logger` type but not its global `logger` instance, so an
+ * external package cannot import that instance. We therefore own a console-backed default here that
+ * matches the SDK's shape; if Strands later exposes its instance, this can delegate to it without
+ * touching the call sites (`logger.warn(...)`).
+ */
+const defaultLogger = {
+    debug: () => { },
+    info: () => { },
+    warn: (...args) => console.warn(...args),
+    error: (...args) => console.error(...args),
+};
+let current = defaultLogger;
+export const logger = {
+    debug: (...args) => current.debug(...args),
+    info: (...args) => current.info(...args),
+    warn: (...args) => current.warn(...args),
+    error: (...args) => current.error(...args),
+};
+/** Inject a custom logger for AgentCore memory logging (e.g. to route through the host app's logger). */
+export function configureMemoryLogging(customLogger) {
+    current = customLogger;
+}
+//# sourceMappingURL=logger.js.map

package/dist/src/memory/integrations/strands/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../../../src/memory/integrations/strands/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,MAAM,aAAa,GAAW;IAC5B,KAAK,EAAE,GAAG,EAAE,GAAE,CAAC;IACf,IAAI,EAAE,GAAG,EAAE,GAAE,CAAC;IACd,IAAI,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnD,KAAK,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;CACtD,CAAA;AAED,IAAI,OAAO,GAAW,aAAa,CAAA;AAEnC,MAAM,CAAC,MAAM,MAAM,GAAW;IAC5B,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IAC1C,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;CAC3C,CAAA;AAED,yGAAyG;AACzG,MAAM,UAAU,sBAAsB,CAAC,YAAoB;IACzD,OAAO,GAAG,YAAY,CAAA;AACxB,CAAC"}

package/dist/src/memory/integrations/strands/sender.d.ts

@@ -0,0 +1,79 @@
+import { type BedrockAgentCoreClient } from '@aws-sdk/client-bedrock-agentcore';
+import type { MessageData } from '@strands-agents/sdk';
+import { type MetadataProvider } from './types.js';
+export interface AgentCoreEventSenderConfig {
+    client: BedrockAgentCoreClient;
+    memoryId: string;
+    actorId: string;
+    sessionId: string;
+    metadataProvider?: MetadataProvider | undefined;
+    /**
+     * Run-unique id anchoring the idempotency `clientToken`. Defaults to a fresh UUID per sender. A new
+     * sender is built per `(actorId, sessionId)` per process, so this distinguishes runs even when the
+     * framework's per-message sequence numbers reset to 0 (e.g. on session restore).
+     */
+    runId?: string;
+    /**
+     * Maximum conversational turns packed into a single `createEvent`. A batch larger than this splits
+     * into `ceil(n / maxTurnsPerEvent)` events. Defaults to {@link DEFAULT_MAX_TURNS_PER_EVENT}; bounds
+     * the payload well under the service limit.
+     */
+    maxTurnsPerEvent?: number;
+}
+/**
+ * Writes a batch of role-tagged messages to AgentCore, packing the turns into as few `createEvent`
+ * calls as possible. `createEvent` accepts an array of conversational turns, so one flush of N turns
+ * becomes a single call (chunked at `maxTurnsPerEvent`) rather than N calls — this is what lets the
+ * extraction trigger cadence actually control API-call volume. AgentCore extracts a multi-turn event
+ * into the same long-term records it would from N single-turn events.
+ *
+ * Error handling is delegated to the Strands `ExtractionCoordinator`: a failed `createEvent` throws
+ * out of {@link sendBatch}, which makes the coordinator roll back its high-water mark and re-fire the
+ * batch on the next trigger (with its own backoff and repeated-failure logging). The sender therefore
+ * keeps no retry/timeout/drop machinery of its own — that would duplicate or fight the coordinator. A
+ * caller that wants a per-request timeout configures it on the `client` it passes in (which also bounds
+ * the read path).
+ *
+ * Idempotency: when the framework provides per-message sequence numbers (via
+ * `AddMessagesContext.sequenceNumbers`), each event gets a deterministic `clientToken` derived from the
+ * sequence range it covers, so a coordinator re-fire of the same batch dedups exactly. Because sequence
+ * numbers reset to 0 across runs, the token also folds in a run-unique id (see
+ * {@link AgentCoreEventSenderConfig.runId}). Without sequence numbers no token is sent; a re-fire then
+ * writes one duplicate event, which AgentCore's server-side consolidation collapses at the record level
+ * (wasteful but not incorrect). The token derivation is isolated in {@link tokenForSeqs} so it can move
+ * to a stable per-message id when the framework exposes one.
+ */
+export declare class AgentCoreEventSender {
+    private readonly client;
+    private readonly memoryId;
+    private readonly actorId;
+    private readonly sessionId;
+    private readonly metadataProvider;
+    private readonly runId;
+    private readonly maxTurnsPerEvent;
+    constructor(config: AgentCoreEventSenderConfig);
+    /**
+     * Send a batch. The writable turns are packed into one `createEvent` per {@link EventGroup} (chunked
+     * by `maxTurnsPerEvent` and split where per-message metadata changes). `sequenceNumbers` (when the
+     * framework provides them) are index-aligned with `messages` and key each event's `clientToken`.
+     * Throws an `AggregateError` if any event fails, so the coordinator retries the batch.
+     */
+    sendBatch(messages: MessageData[], sequenceNumbers?: readonly number[]): Promise<void>;
+    /**
+     * Partition the sendable turns into events. A new event starts when the per-message metadata changes
+     * (the event's `metadata` is per-event in AgentCore, so turns in one event must share it) or when the
+     * current event reaches `maxTurnsPerEvent`. With no `metadataProvider`, all turns share the empty
+     * signature and collapse into size-capped events.
+     */
+    private groupIntoEvents;
+    private sendEvent;
+    /**
+     * Deterministic re-fire-stable token for an event covering the given sequence numbers, or `undefined`
+     * when any is missing (then we tolerate error-path duplicates; consolidation is the backstop). The
+     * token spans the event's `[firstSeq, lastSeq]`; a coordinator re-fire of the same batch reproduces
+     * the same range. Never time/random-based per call — the run-unique part is fixed for the sender's
+     * lifetime. Isolated here so it can switch to a stable per-message id when the framework exposes one.
+     */
+    private tokenForSeqs;
+}
+//# sourceMappingURL=sender.d.ts.map

package/dist/src/memory/integrations/strands/sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../../../../src/memory/integrations/strands/sender.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,sBAAsB,EAAsB,MAAM,mCAAmC,CAAA;AACnG,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAEtD,OAAO,EAA+B,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE/E,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,sBAAsB,CAAA;IAC9B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,gBAAgB,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAA;IAC/C;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAoBD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA8B;IAC/D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAQ;gBAE7B,MAAM,EAAE,0BAA0B;IAc9C;;;;;OAKG;IACG,SAAS,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IA8B5F;;;;;OAKG;IACH,OAAO,CAAC,eAAe;YAkBT,SAAS;IAmBvB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;CAKrB"}

package/dist/src/memory/integrations/strands/sender.js

@@ -0,0 +1,170 @@
+import { randomUUID } from 'crypto';
+import { CreateEventCommand } from '@aws-sdk/client-bedrock-agentcore';
+import { extractText, isUserOrAssistantWithText, mapRole } from './format.js';
+import { DEFAULT_MAX_TURNS_PER_EVENT } from './types.js';
+/**
+ * Writes a batch of role-tagged messages to AgentCore, packing the turns into as few `createEvent`
+ * calls as possible. `createEvent` accepts an array of conversational turns, so one flush of N turns
+ * becomes a single call (chunked at `maxTurnsPerEvent`) rather than N calls — this is what lets the
+ * extraction trigger cadence actually control API-call volume. AgentCore extracts a multi-turn event
+ * into the same long-term records it would from N single-turn events.
+ *
+ * Error handling is delegated to the Strands `ExtractionCoordinator`: a failed `createEvent` throws
+ * out of {@link sendBatch}, which makes the coordinator roll back its high-water mark and re-fire the
+ * batch on the next trigger (with its own backoff and repeated-failure logging). The sender therefore
+ * keeps no retry/timeout/drop machinery of its own — that would duplicate or fight the coordinator. A
+ * caller that wants a per-request timeout configures it on the `client` it passes in (which also bounds
+ * the read path).
+ *
+ * Idempotency: when the framework provides per-message sequence numbers (via
+ * `AddMessagesContext.sequenceNumbers`), each event gets a deterministic `clientToken` derived from the
+ * sequence range it covers, so a coordinator re-fire of the same batch dedups exactly. Because sequence
+ * numbers reset to 0 across runs, the token also folds in a run-unique id (see
+ * {@link AgentCoreEventSenderConfig.runId}). Without sequence numbers no token is sent; a re-fire then
+ * writes one duplicate event, which AgentCore's server-side consolidation collapses at the record level
+ * (wasteful but not incorrect). The token derivation is isolated in {@link tokenForSeqs} so it can move
+ * to a stable per-message id when the framework exposes one.
+ */
+export class AgentCoreEventSender {
+    client;
+    memoryId;
+    actorId;
+    sessionId;
+    metadataProvider;
+    runId;
+    maxTurnsPerEvent;
+    constructor(config) {
+        this.client = config.client;
+        this.memoryId = config.memoryId;
+        this.actorId = config.actorId;
+        this.sessionId = config.sessionId;
+        this.metadataProvider = config.metadataProvider;
+        this.runId = config.runId ?? randomUUID();
+        const cap = config.maxTurnsPerEvent ?? DEFAULT_MAX_TURNS_PER_EVENT;
+        if (!Number.isInteger(cap) || cap < 1) {
+            throw new Error(`AgentCoreEventSender: maxTurnsPerEvent must be a positive integer, got ${cap}`);
+        }
+        this.maxTurnsPerEvent = cap;
+    }
+    /**
+     * Send a batch. The writable turns are packed into one `createEvent` per {@link EventGroup} (chunked
+     * by `maxTurnsPerEvent` and split where per-message metadata changes). `sequenceNumbers` (when the
+     * framework provides them) are index-aligned with `messages` and key each event's `clientToken`.
+     * Throws an `AggregateError` if any event fails, so the coordinator retries the batch.
+     */
+    async sendBatch(messages, sequenceNumbers) {
+        const sendable = messages
+            .map((message, i) => ({ message, seq: sequenceNumbers?.[i] }))
+            .filter((m) => isUserOrAssistantWithText(m.message));
+        if (sendable.length === 0)
+            return;
+        // Validate + map metadata for every event BEFORE any network call. A charset violation is a
+        // deterministic input error, so it must fail loud-and-early (unwrapped) rather than being caught
+        // by the allSettled boundary below and re-wrapped as an opaque AggregateError. No createEvent is
+        // attempted if any group's metadata is invalid.
+        const events = this.groupIntoEvents(sendable).map((g) => {
+            // Omit an empty bag entirely so the event carries no `metadata` field (matches the no-provider case).
+            const metadata = g.metadata && Object.keys(g.metadata).length > 0 ? toAgentCoreMetadata(g.metadata) : undefined;
+            return { items: g.items, metadata };
+        });
+        const results = await Promise.allSettled(events.map((e) => this.sendEvent(e)));
+        const failures = results.filter((r) => r.status === 'rejected');
+        if (failures.length > 0) {
+            // Fold the first underlying reason into the message: the coordinator logs `.message` only, so a
+            // bare count would hide what actually failed.
+            const firstReason = failures[0].reason;
+            const firstMessage = firstReason instanceof Error ? firstReason.message : String(firstReason);
+            throw new AggregateError(failures.map((f) => f.reason), `AgentCore createEvent failed for ${failures.length} of ${events.length} event(s); first error: ${firstMessage}`);
+        }
+    }
+    /**
+     * Partition the sendable turns into events. A new event starts when the per-message metadata changes
+     * (the event's `metadata` is per-event in AgentCore, so turns in one event must share it) or when the
+     * current event reaches `maxTurnsPerEvent`. With no `metadataProvider`, all turns share the empty
+     * signature and collapse into size-capped events.
+     */
+    groupIntoEvents(sendable) {
+        const groups = [];
+        let current;
+        let currentSig;
+        for (const item of sendable) {
+            const metadata = this.metadataProvider?.(item.message);
+            const sig = metadata ? JSON.stringify(metadata) : '';
+            const atCap = current !== undefined && current.items.length >= this.maxTurnsPerEvent;
+            if (current === undefined || sig !== currentSig || atCap) {
+                current = { items: [], metadata };
+                groups.push(current);
+                currentSig = sig;
+            }
+            current.items.push(item);
+        }
+        return groups;
+    }
+    async sendEvent(event) {
+        const payload = event.items.map((item) => ({
+            conversational: { role: mapRole(item.message), content: { text: extractText(item.message) } },
+        }));
+        const clientToken = this.tokenForSeqs(event.items.map((item) => item.seq));
+        const command = new CreateEventCommand({
+            memoryId: this.memoryId,
+            actorId: this.actorId,
+            sessionId: this.sessionId,
+            eventTimestamp: new Date(),
+            payload,
+            ...(clientToken !== undefined && { clientToken }),
+            ...(event.metadata && { metadata: event.metadata }),
+        });
+        await this.client.send(command);
+    }
+    /**
+     * Deterministic re-fire-stable token for an event covering the given sequence numbers, or `undefined`
+     * when any is missing (then we tolerate error-path duplicates; consolidation is the backstop). The
+     * token spans the event's `[firstSeq, lastSeq]`; a coordinator re-fire of the same batch reproduces
+     * the same range. Never time/random-based per call — the run-unique part is fixed for the sender's
+     * lifetime. Isolated here so it can switch to a stable per-message id when the framework exposes one.
+     */
+    tokenForSeqs(seqs) {
+        if (seqs.length === 0 || seqs.some((s) => s === undefined))
+            return undefined;
+        const nums = seqs;
+        return `${this.memoryId}-${this.actorId}-${this.runId}-${nums[0]}-${nums[nums.length - 1]}`;
+    }
+}
+/**
+ * AgentCore restricts `createEvent` metadata values to this character set. The constraint is enforced
+ * server-side (not in the AWS SDK types), so a value outside it fails at `createEvent` with an opaque
+ * `ValidationException`. We validate client-side and throw a clear, actionable error instead — mirroring
+ * the namespace placeholder check.
+ */
+const METADATA_VALUE_PATTERN = /^[a-zA-Z0-9\s._:/=+@-]*$/;
+/**
+ * Map a metadata bag to AgentCore's `{ stringValue }` event-metadata shape. Non-string values are
+ * JSON-stringified. Each resulting value must match {@link METADATA_VALUE_PATTERN}; a value that doesn't
+ * (e.g. a string with commas/punctuation, or a stringified array/object whose `[]{}",` are rejected)
+ * throws here with the offending key, rather than failing opaquely server-side at `createEvent`.
+ *
+ * Values that don't produce a usable scalar string are rejected up front: `undefined`/functions/symbols
+ * (`JSON.stringify` returns the JS value `undefined`, not a string) and non-finite numbers / `null`
+ * (which stringify to the literal `"null"`). Without this guard those slip past the charset test —
+ * `undefined` as `{ stringValue: undefined }`, `NaN` as the string `"null"` — and corrupt the event.
+ */
+function toAgentCoreMetadata(metadata) {
+    const out = {};
+    for (const [key, value] of Object.entries(metadata)) {
+        if (value === undefined || value === null || (typeof value === 'number' && !Number.isFinite(value))) {
+            throw new Error(`AgentCoreEventSender: metadata value for key "${key}" is ${String(value)}, which has no valid ` +
+                `string representation. Provide a finite number, boolean, or a string (omit the key instead of ` +
+                `passing null/undefined).`);
+        }
+        const stringValue = typeof value === 'string' ? value : JSON.stringify(value);
+        if (typeof stringValue !== 'string' || !METADATA_VALUE_PATTERN.test(stringValue)) {
+            throw new Error(`AgentCoreEventSender: metadata value for key "${key}" contains characters AgentCore rejects ` +
+                `(allowed: letters, digits, whitespace, and ._:/=+@-). Got ${JSON.stringify(stringValue)}. ` +
+                `Note: arrays/objects stringify to JSON containing []{}", which are not allowed — pass a ` +
+                `pre-encoded scalar string instead.`);
+        }
+        out[key] = { stringValue };
+    }
+    return out;
+}
+//# sourceMappingURL=sender.js.map

package/dist/src/memory/integrations/strands/sender.js.map

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