agentfootprint 7.13.0 → 7.15.0

package/dist/esm/adapters/hosting/agentcore.js

@@ -0,0 +1,321 @@
+/**
+ * adapters/hosting/agentcore — AWS Bedrock **AgentCore Runtime** adapters for
+ * the two hosting ports.
+ *
+ *   import { agentCoreRuntimeHost, agentCoreSessions } from 'agentfootprint/hosting-providers';
+ *   import { standingAgent } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agent,
+ *     host: agentCoreRuntimeHost(),
+ *     sessions: agentCoreSessions({ store: 'session-storage' }),
+ *   });
+ *
+ * ── What this file actually is ───────────────────────────────────────────────
+ * Vendor paths, a header name, and two JSON body shapes. That is the whole
+ * adapter, and it is the claim the hosting ports were designed to make: a
+ * container runtime's contract is a CONFIGURATION of HTTP work that already
+ * exists, not a second implementation of it. Nothing here reaches into the
+ * ports, and nothing here needed the ports to change.
+ *
+ * AgentCore Runtime is a **container contract**: an ARM64 image serving HTTP on
+ * `0.0.0.0:8080` —
+ *
+ *   POST /invocations   JSON `{ "prompt": "..." }` → JSON `{ "response", "status" }`
+ *   GET  /ping          → `{ "status": "Healthy", "time_of_last_update": <unix seconds> }`
+ *
+ * and the caller's conversation arrives in the
+ * `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header rather than in the body,
+ * which is the one thing paths-and-bodies configuration alone could not
+ * express before this release.
+ *
+ * ── Verification status, stated plainly ──────────────────────────────────────
+ * `agentCoreRuntimeHost` is **plain HTTP and is really verified**: it runs the
+ * same host conformance suite as `nodeHost`, over a real socket, in
+ * `test/hosting/host-contract.test.ts`. There is no AWS SDK on its path.
+ *
+ * `agentCoreSessions({ store: 'memory' })` is **contract-mapped and
+ * injection-tested**: its AgentCore Memory calls are exercised through the
+ * `_client` seam, never against AWS. Confirm the command and field names
+ * against your installed `@aws-sdk/client-bedrock-agentcore` before you rely
+ * on it; real-cloud verification lands with a field deployment.
+ *
+ * Pattern: Adapter (GoF). Role: outer ring. The file-backed session store uses
+ * `node:fs` and nothing else; the event-backed one lazy-loads the AWS SDK, so
+ * importing this module costs zero peer-dep load.
+ */
+import { readEnvelope } from '../../hosting/envelope.js';
+import { headerValue, httpHost } from '../../hosting/httpHost.js';
+import { lazyRequire } from '../../lib/lazyRequire.js';
+// ─── The runtime host ────────────────────────────────────────────────
+const HOST_NAME = 'agentCoreRuntimeHost';
+/** The runtime's container contract, as constants rather than as scattered literals. */
+const INVOKE_PATH = '/invocations';
+const HEALTH_PATH = '/ping';
+const RUNTIME_PORT = 8080;
+/**
+ * The header the runtime puts the caller's conversation in. Matched
+ * case-insensitively — HTTP header names are case-insensitive and a proxy in
+ * front of the container is free to re-case them.
+ */
+const SESSION_HEADER = 'X-Amzn-Bedrock-AgentCore-Runtime-Session-Id';
+/**
+ * The AgentCore Runtime contract as an {@link HttpWire}.
+ *
+ * Exported so the body shapes are inspectable and testable without binding a
+ * socket, and so a deployment that must serve the same bodies from somewhere
+ * else can reuse them by name.
+ */
+export function agentCoreRuntimeWire(busy) {
+    return {
+        readRequest(facts) {
+            // `prompt` is the field the runtime's own quickstart and this repo's
+            // deploy template use. `input` is accepted too because the runtime passes
+            // the payload through verbatim — it is the CALLER who picks the field —
+            // and refusing a caller who used the port's own word would be a rule this
+            // adapter invented rather than one the contract imposes.
+            const prompt = facts.body.prompt ?? facts.body.input;
+            const input = typeof prompt === 'string' ? prompt : '';
+            // The conversation id arrives in a header, never in the body. It is
+            // caller-adjacent data, not identity — the port says so and it is just as
+            // true here.
+            const sessionId = headerValue(facts, SESSION_HEADER);
+            return sessionId !== undefined ? { input, sessionId } : { input };
+        },
+        // The runtime polls this to decide whether the container is ready and
+        // whether to send it more work. `time_of_last_update` is unix SECONDS.
+        health: () => ({
+            status: busy?.() === true ? 'HealthyBusy' : 'Healthy',
+            time_of_last_update: Math.floor(Date.now() / 1000),
+        }),
+        output: (response) => ({ response, status: 'success' }),
+        // The message only — never a stack. The runtime surfaces the status code;
+        // the body is read by whoever called the agent.
+        failure: (error, code) => ({ error, status: 'error', ...(code !== undefined && { code }) }),
+        // A distinct field from `response` on purpose: a caller concatenating
+        // stream frames must not be able to double-count the final answer by
+        // reading the same key twice.
+        chunk: (chunk) => ({ chunk }),
+    };
+}
+/**
+ * An `AgentHost` that speaks AgentCore Runtime's container contract.
+ *
+ * Passes the same conformance suite as `nodeHost` — it is the same HTTP host
+ * with this runtime's two paths, its header, and its two body shapes.
+ *
+ * @example  The container's entry point
+ *   const handle = await standingAgent({
+ *     agent,
+ *     host: agentCoreRuntimeHost(),
+ *     sessions: agentCoreSessions({ store: 'session-storage' }),
+ *   });
+ *   process.on('SIGTERM', () => void handle.close());
+ */
+export function agentCoreRuntimeHost(options = {}) {
+    return httpHost({
+        name: HOST_NAME,
+        wire: agentCoreRuntimeWire(options.busy),
+        invokePath: INVOKE_PATH,
+        healthPath: HEALTH_PATH,
+        port: options.port ?? RUNTIME_PORT,
+        hostname: options.hostname ?? '0.0.0.0',
+    });
+}
+/** The default file the `'session-storage'` mode writes to. */
+export const DEFAULT_SESSION_STORAGE_PATH = '/tmp/agentcore-session';
+/**
+ * A `SessionLifecycle` backed by AgentCore, with the checkpoint's home chosen
+ * at construction.
+ *
+ * Both modes store the SAME `CheckpointEnvelope` the port defines, and both
+ * refuse an unknown `format` by name through the shared `readEnvelope` — a
+ * conversation written by a newer runtime is refused, never half-restored.
+ * That law is inherited, not re-implemented.
+ *
+ * @example  Survive a stop/resume, no AWS SDK required
+ *   agentCoreSessions({ store: 'session-storage' });
+ *
+ * @example  Outlive the session entirely
+ *   agentCoreSessions({ store: 'memory', memoryId: process.env.MEMORY_ID!, region: 'us-west-2' });
+ */
+export function agentCoreSessions(options) {
+    return options.store === 'memory' ? memoryEventSessions(options) : fileSessions(options);
+}
+function fileSessions(options) {
+    const path = options.path ?? DEFAULT_SESSION_STORAGE_PATH;
+    async function readFile() {
+        const { readFile: read } = await import('node:fs/promises');
+        let raw;
+        try {
+            raw = await read(path, 'utf8');
+        }
+        catch {
+            // No file yet is the ordinary first-request state, not an error.
+            return { version: 1, sessions: {} };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new TypeError(`[hosting] the session file at '${path}' is not JSON (${err.message}). ` +
+                `Refusing rather than starting every conversation over silently — delete the file ` +
+                `to start fresh, or point 'path' somewhere else.`);
+        }
+        const sessions = parsed?.sessions;
+        return sessions && typeof sessions === 'object'
+            ? { version: 1, sessions: sessions }
+            : { version: 1, sessions: {} };
+    }
+    return {
+        async hydrate(sessionId) {
+            const file = await readFile();
+            const stored = file.sessions[sessionId];
+            if (stored === undefined)
+                return undefined;
+            // Validate HERE as well as in the composer, so a refusal points at the
+            // store that produced the bytes rather than at whoever read them next.
+            readEnvelope(stored);
+            return stored;
+        },
+        async persist(sessionId, envelope) {
+            const { writeFile, rename, mkdir } = await import('node:fs/promises');
+            const { dirname } = await import('node:path');
+            const file = await readFile();
+            const next = {
+                version: 1,
+                sessions: { ...file.sessions, [sessionId]: envelope },
+            };
+            await mkdir(dirname(path), { recursive: true }).catch(() => undefined);
+            // Write-then-rename: a container killed mid-write leaves the previous
+            // conversation intact rather than a truncated file that refuses to parse.
+            const temporary = `${path}.${process.pid}.tmp`;
+            await writeFile(temporary, JSON.stringify(next), 'utf8');
+            await rename(temporary, path);
+        },
+    };
+}
+// ─── 'memory': one AgentCore Memory event per persist ────────────────
+const DEFAULT_ACTOR_ID = 'afp-standing-agent';
+function memoryEventSessions(options) {
+    if (!options.memoryId) {
+        throw new Error(`agentCoreSessions({ store: 'memory' }) requires 'memoryId'.`);
+    }
+    const memoryId = options.memoryId;
+    const actorId = options.actorId ?? DEFAULT_ACTOR_ID;
+    const client = options._client ?? options.client ?? createSessionClient(options.region, options._sdk);
+    return {
+        async hydrate(sessionId) {
+            // AgentCore Memory is an append-only log and lists newest-first, so the
+            // newest readable event IS the conversation. Older ones are the earlier
+            // turns and deliberately left where they are — they are the audit trail.
+            const page = await client.listEvents({
+                memoryId,
+                actorId,
+                sessionId: safeSessionId(sessionId),
+                maxResults: 1,
+            });
+            const newest = page.events[0];
+            if (!newest || newest.envelope === null || newest.envelope === undefined)
+                return undefined;
+            readEnvelope(newest.envelope);
+            return newest.envelope;
+        },
+        async persist(sessionId, envelope) {
+            await client.createEvent({
+                memoryId,
+                actorId,
+                sessionId: safeSessionId(sessionId),
+                envelope,
+            });
+        },
+    };
+}
+const SESSION_ID_MAX = 99;
+/** AgentCore ids accept `[A-Za-z0-9_-]`; a session id is caller data and need not. */
+function safeSessionId(raw) {
+    const slug = raw.replace(/[^A-Za-z0-9_-]/g, '-');
+    if (slug.length <= SESSION_ID_MAX)
+        return slug;
+    // Keep a readable head plus a stable tail so two long ids stay distinct.
+    return `${slug.slice(0, SESSION_ID_MAX - 9)}-${fnv1a(raw)}`;
+}
+function fnv1a(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(36);
+}
+/** Pull the envelope out of an event's `payload` (a single `blob` document). */
+function envelopeFromPayload(payload) {
+    if (!Array.isArray(payload))
+        return null;
+    for (const part of payload) {
+        const blob = part?.blob;
+        if (blob && typeof blob === 'object')
+            return blob;
+    }
+    return null;
+}
+/**
+ * Map {@link AgentCoreSessionClientLike} onto the real SDK commands. If AWS
+ * renames a command, only this function changes — which is also why every test
+ * injects past it.
+ */
+function createSessionClient(region, injected) {
+    let mod;
+    if (injected) {
+        mod = injected;
+    }
+    else {
+        try {
+            mod = lazyRequire('@aws-sdk/client-bedrock-agentcore');
+        }
+        catch {
+            throw new Error(`agentCoreSessions({ store: 'memory' }) requires the ` +
+                '`@aws-sdk/client-bedrock-agentcore` peer dependency.\n' +
+                '  Install:  npm install @aws-sdk/client-bedrock-agentcore\n' +
+                "  Or use { store: 'session-storage' }, which needs no SDK at all.");
+        }
+    }
+    if (!mod.BedrockAgentCoreClient) {
+        throw new Error('agentCoreSessions: `@aws-sdk/client-bedrock-agentcore` is installed but ' +
+            '`BedrockAgentCoreClient` was not found. Update the SDK.');
+    }
+    const sdk = new mod.BedrockAgentCoreClient({ ...(region && { region }) });
+    const send = async (Ctor, name, input) => {
+        if (!Ctor) {
+            throw new Error(`agentCoreSessions: \`@aws-sdk/client-bedrock-agentcore\` is missing ${name}. Upgrade the SDK.`);
+        }
+        return sdk.send(new Ctor(input));
+    };
+    return {
+        async createEvent({ memoryId, actorId, sessionId, envelope }) {
+            await send(mod.CreateEventCommand, 'CreateEventCommand', {
+                memoryId,
+                actorId,
+                sessionId,
+                eventTimestamp: new Date(),
+                payload: [{ blob: envelope }],
+            });
+        },
+        async listEvents({ memoryId, actorId, sessionId, maxResults }) {
+            const result = (await send(mod.ListEventsCommand, 'ListEventsCommand', {
+                memoryId,
+                actorId,
+                sessionId,
+                includePayloads: true,
+                ...(maxResults !== undefined && { maxResults }),
+            }));
+            const events = (result?.events ?? []).map((event) => ({
+                eventId: event.eventId ?? '',
+                envelope: envelopeFromPayload(event.payload),
+            }));
+            return { events };
+        },
+    };
+}
+//# sourceMappingURL=agentcore.js.map

package/dist/esm/adapters/hosting/agentcore.js.map

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

package/dist/esm/adapters/memory/agentcore.d.ts

@@ -27,14 +27,20 @@
  *     AgentCore's ids are server-assigned.  **O(events in session)** — fine for typical
  *     window sizes; if you need O(1) keyed access at scale, use RedisStore.
  *   • `forget` → `ListEvents` + `DeleteEvent` per event (no `DeleteSession` on AgentCore).
- *   • `search` → still unwired (AgentCore's `RetrieveMemoryRecords` lands as a later helper).
+ *   • `search` → `RetrieveMemoryRecords`, **text-in**. AgentCore embeds and ranks on its
+ *     own side, so it takes a natural-language query; the port's `search()` takes a
+ *     vector. Pass `options.text` and this store serves the query; omit it and it refuses
+ *     by name rather than ranking an empty set. See `search()` below for the whole story.
  *   • `putIfVersion` / `seen` / `feedback` → in-process emulation (AgentCore has no native
  *     CAS / dedup / feedback primitive; these don't survive process restart).
+ *   • no `stream()` — AgentCore Memory has no streaming data-plane operation, and the
+ *     `MemoryStore` port has no streaming method to implement. Inventing one for a single
+ *     backend is how a port stops being a port.
  *
  * Role:    Outer ring. Lazy-requires the AWS SDK; zero runtime cost when another adapter is
  *          in use.  Emits: N/A (storage adapters don't emit).
  */
-import type { ListOptions, ListResult, MemoryStore, PutIfVersionResult } from '../../memory/store/types.js';
+import type { ListOptions, ListResult, MemoryStore, PutIfVersionResult, ScoredEntry, SearchOptions } from '../../memory/store/types.js';
 import type { MemoryEntry } from '../../memory/entry/index.js';
 import type { MemoryIdentity } from '../../memory/identity/index.js';
 /** One event as the adapter cares about it: AgentCore's id + the decoded entry. */
@@ -75,6 +81,35 @@ export interface AgentCoreLikeClient {
         sessionId: string;
         eventId: string;
     }): Promise<void>;
+    /**
+     * Server-side semantic retrieval (`RetrieveMemoryRecords`). Optional: a client
+     * built before this existed still satisfies the interface, and `search()`
+     * feature-detects it rather than assuming.
+     */
+    retrieveRecords?(input: {
+        memoryId: string;
+        namespace: string;
+        searchQuery: string;
+        maxResults?: number;
+        memoryStrategyId?: string;
+    }): Promise<{
+        records: readonly AgentCoreMemoryRecord[];
+    }>;
+}
+/** One record as `RetrieveMemoryRecords` returns it. */
+export interface AgentCoreMemoryRecord {
+    /** AgentCore's own record id. */
+    readonly memoryRecordId: string;
+    /** The record's text content. */
+    readonly content: string;
+    /** Relevance as AgentCore scored it, when it reports one. */
+    readonly score?: number;
+    /** Which strategy produced the record (semantic, summary, user-preference, …). */
+    readonly memoryStrategyId?: string;
+    /** The namespace it was found in. */
+    readonly namespace?: string;
+    /** When AgentCore created it (unix ms), when reported. */
+    readonly createdAt?: number;
 }
 export interface AgentCoreStoreOptions {
     /** AgentCore Memory ARN or id. Required. */
@@ -85,6 +120,27 @@ export interface AgentCoreStoreOptions {
     readonly client?: AgentCoreLikeClient;
     /** Page size for `listEvents`. Default 100. */
     readonly pageSize?: number;
+    /**
+     * Where `search()` looks. AgentCore organises extracted memory records into
+     * namespaces configured on the Memory resource's strategies (commonly
+     * something like `/strategies/{strategyId}/actors/{actorId}`).
+     *
+     * A function, because the namespace usually contains the actor: it is handed
+     * the resolved AgentCore ids for the identity being searched. Default:
+     * `/actors/{actorId}/sessions/{sessionId}` — the session's own records.
+     */
+    readonly searchNamespace?: (scope: {
+        readonly actorId: string;
+        readonly sessionId: string;
+    }) => string;
+    /**
+     * Restrict `search()` to one extraction strategy (semantic, summary,
+     * user-preference…). Omit to search across all of them.
+     *
+     * This is the metadata filter that reaches AgentCore's own side; `tiers` /
+     * `minScore` / `k` from {@link SearchOptions} are applied to what comes back.
+     */
+    readonly searchStrategyId?: string;
     /** @internal Test injection — skips the SDK require entirely. */
     readonly _client?: AgentCoreLikeClient;
     /** @internal Test injection — the AWS SDK module (to exercise the real shim with a mock SDK). */
@@ -100,6 +156,8 @@ export declare class AgentCoreStore implements MemoryStore {
     private readonly client;
     private readonly memoryId;
     private readonly pageSize;
+    private readonly searchNamespace;
+    private readonly searchStrategyId;
     private closed;
     private readonly signatures;
     private readonly feedbackBag;
@@ -130,6 +188,33 @@ export declare class AgentCoreStore implements MemoryStore {
     } | null>;
     /** GDPR "everything for this identity, gone." No DeleteSession on AgentCore → delete every event. */
     forget(identity: MemoryIdentity): Promise<void>;
+    /**
+     * Server-side semantic retrieval over AgentCore's extracted memory records
+     * (`RetrieveMemoryRecords`).
+     *
+     * ── Read this before you call it ─────────────────────────────────────────
+     * **It takes TEXT, not the vector.** AgentCore embeds and ranks on its own
+     * side, so `query` — the port's vector — is unusable here, and the query it
+     * actually needs travels in `options.text`. Omit that and this method throws
+     * a corrective error naming what is missing, because the alternative is
+     * ranking nothing and handing back `[]`, which reads as "no matches" when it
+     * really means "wrong query form". Pass both and every store can serve you:
+     * local-ranking backends use the vector and ignore the text.
+     *
+     * **It searches a DIFFERENT population than `list()`.** `list` returns the
+     * events this store wrote. This returns the records AgentCore's extraction
+     * strategies derived FROM those events — summaries, semantic facts, user
+     * preferences. The ids therefore belong to AgentCore, not to entries you
+     * `put()`, and `store.get(entry.id)` will not find them. They arrive as
+     * entries so ranking code needs no special case, with `metadata.source`
+     * saying plainly where they came from.
+     *
+     * Filters: `searchStrategyId` and the namespace reach AgentCore's own side;
+     * `k`, `minScore` and `tiers` are applied to what comes back.
+     *
+     * @throws when `options.text` is absent, or when the client cannot retrieve.
+     */
+    search<T = unknown>(identity: MemoryIdentity, query: readonly number[], options?: SearchOptions): Promise<readonly ScoredEntry<T>[]>;
     close(): Promise<void>;
     private ensureOpen;
 }
@@ -143,4 +228,5 @@ export interface BedrockAgentCoreSdkModule {
     readonly CreateEventCommand?: new (input: unknown) => unknown;
     readonly ListEventsCommand?: new (input: unknown) => unknown;
     readonly DeleteEventCommand?: new (input: unknown) => unknown;
+    readonly RetrieveMemoryRecordsCommand?: new (input: unknown) => unknown;
 }

package/dist/esm/adapters/memory/agentcore.js

@@ -27,9 +27,15 @@
  *     AgentCore's ids are server-assigned.  **O(events in session)** — fine for typical
  *     window sizes; if you need O(1) keyed access at scale, use RedisStore.
  *   • `forget` → `ListEvents` + `DeleteEvent` per event (no `DeleteSession` on AgentCore).
- *   • `search` → still unwired (AgentCore's `RetrieveMemoryRecords` lands as a later helper).
+ *   • `search` → `RetrieveMemoryRecords`, **text-in**. AgentCore embeds and ranks on its
+ *     own side, so it takes a natural-language query; the port's `search()` takes a
+ *     vector. Pass `options.text` and this store serves the query; omit it and it refuses
+ *     by name rather than ranking an empty set. See `search()` below for the whole story.
  *   • `putIfVersion` / `seen` / `feedback` → in-process emulation (AgentCore has no native
  *     CAS / dedup / feedback primitive; these don't survive process restart).
+ *   • no `stream()` — AgentCore Memory has no streaming data-plane operation, and the
+ *     `MemoryStore` port has no streaming method to implement. Inventing one for a single
+ *     backend is how a port stops being a port.
  *
  * Role:    Outer ring. Lazy-requires the AWS SDK; zero runtime cost when another adapter is
  *          in use.  Emits: N/A (storage adapters don't emit).
@@ -55,6 +61,8 @@ export class AgentCoreStore {
     client;
     memoryId;
     pageSize;
+    searchNamespace;
+    searchStrategyId;
     closed = false;
     // In-process shadow state for things AgentCore doesn't surface natively.
     signatures = new Map();
@@ -64,6 +72,10 @@ export class AgentCoreStore {
             throw new Error('AgentCoreStore requires `memoryId`.');
         this.memoryId = options.memoryId;
         this.pageSize = options.pageSize ?? 100;
+        this.searchNamespace =
+            options.searchNamespace ??
+                (({ actorId, sessionId }) => `/actors/${actorId}/sessions/${sessionId}`);
+        this.searchStrategyId = options.searchStrategyId;
         if (options._client)
             this.client = options._client;
         else if (options.client)
@@ -224,6 +236,90 @@ export class AgentCoreStore {
                 this.feedbackBag.delete(key);
         }
     }
+    /**
+     * Server-side semantic retrieval over AgentCore's extracted memory records
+     * (`RetrieveMemoryRecords`).
+     *
+     * ── Read this before you call it ─────────────────────────────────────────
+     * **It takes TEXT, not the vector.** AgentCore embeds and ranks on its own
+     * side, so `query` — the port's vector — is unusable here, and the query it
+     * actually needs travels in `options.text`. Omit that and this method throws
+     * a corrective error naming what is missing, because the alternative is
+     * ranking nothing and handing back `[]`, which reads as "no matches" when it
+     * really means "wrong query form". Pass both and every store can serve you:
+     * local-ranking backends use the vector and ignore the text.
+     *
+     * **It searches a DIFFERENT population than `list()`.** `list` returns the
+     * events this store wrote. This returns the records AgentCore's extraction
+     * strategies derived FROM those events — summaries, semantic facts, user
+     * preferences. The ids therefore belong to AgentCore, not to entries you
+     * `put()`, and `store.get(entry.id)` will not find them. They arrive as
+     * entries so ranking code needs no special case, with `metadata.source`
+     * saying plainly where they came from.
+     *
+     * Filters: `searchStrategyId` and the namespace reach AgentCore's own side;
+     * `k`, `minScore` and `tiers` are applied to what comes back.
+     *
+     * @throws when `options.text` is absent, or when the client cannot retrieve.
+     */
+    async search(identity, query, options = {}) {
+        this.ensureOpen('search');
+        const text = options.text?.trim();
+        if (!text) {
+            throw new Error('AgentCoreStore.search() needs the query as TEXT, in `options.text`.\n' +
+                `  AgentCore embeds and ranks server-side (RetrieveMemoryRecords), so the ${query.length}-dimension\n` +
+                '  vector this method was handed cannot be sent anywhere — and returning [] would look\n' +
+                '  like "no matches" rather than "wrong query form".\n' +
+                '  Fix:  store.search(identity, vector, { text: theUserQuestion })\n' +
+                '  Backends that rank locally ignore `text`, so passing both is always safe.');
+        }
+        if (!this.client.retrieveRecords) {
+            throw new Error('AgentCoreStore.search() requires a client that implements `retrieveRecords`.\n' +
+                '  The built-in client does; a custom or older injected `client` / `_client` may not.');
+        }
+        const scope = this.scope(identity);
+        const k = options.k ?? 10;
+        const page = await this.client.retrieveRecords({
+            memoryId: this.memoryId,
+            namespace: this.searchNamespace({ actorId: scope.actorId, sessionId: scope.sessionId }),
+            searchQuery: text,
+            maxResults: k,
+            ...(this.searchStrategyId !== undefined && { memoryStrategyId: this.searchStrategyId }),
+        });
+        const scored = [];
+        for (const record of page.records) {
+            const score = record.score ?? 0;
+            if (options.minScore !== undefined && score < options.minScore)
+                continue;
+            // AgentCore records carry no tier. A tier filter therefore excludes them
+            // all rather than silently ignoring the filter the caller asked for.
+            if (options.tiers && options.tiers.length > 0)
+                continue;
+            const createdAt = record.createdAt ?? Date.now();
+            const entry = {
+                id: record.memoryRecordId,
+                value: record.content,
+                version: 1,
+                createdAt,
+                updatedAt: createdAt,
+                lastAccessedAt: Date.now(),
+                accessCount: 0,
+                metadata: {
+                    // Says plainly that this did not come from an event this store wrote.
+                    source: 'agentcore-memory-record',
+                    ...(record.memoryStrategyId !== undefined && {
+                        memoryStrategyId: record.memoryStrategyId,
+                    }),
+                    ...(record.namespace !== undefined && { namespace: record.namespace }),
+                },
+            };
+            scored.push({ entry, score });
+        }
+        // AgentCore returns its own ranking; re-sort anyway so the port's
+        // "descending by score" holds even if a future API version reorders.
+        scored.sort((a, b) => b.score !== a.score ? b.score - a.score : a.entry.id < b.entry.id ? -1 : 1);
+        return scored.slice(0, k);
+    }
     async close() {
         if (this.closed)
             return;
@@ -318,6 +414,34 @@ function createAgentCoreClient(region, injected) {
                 eventId,
             });
         },
+        async retrieveRecords({ memoryId, namespace, searchQuery, maxResults, memoryStrategyId }) {
+            // AgentCore nests the query under `searchCriteria`; the strategy id is the
+            // metadata filter that reaches its side rather than being applied after.
+            const r = (await send(mod.RetrieveMemoryRecordsCommand, 'RetrieveMemoryRecordsCommand', {
+                memoryId,
+                namespace,
+                searchCriteria: {
+                    searchQuery,
+                    ...(maxResults !== undefined && { topK: maxResults }),
+                    ...(memoryStrategyId !== undefined && { memoryStrategyId }),
+                },
+                ...(maxResults !== undefined && { maxResults }),
+            }));
+            const records = (r?.memoryRecordSummaries ?? []).map((s) => {
+                const content = typeof s.content === 'string' ? s.content : s.content?.text ?? '';
+                const namespaceValue = Array.isArray(s.namespace) ? s.namespace[0] : s.namespace;
+                const createdAt = s.createdAt === undefined ? undefined : new Date(s.createdAt).getTime();
+                return {
+                    memoryRecordId: s.memoryRecordId ?? '',
+                    content,
+                    ...(typeof s.score === 'number' && { score: s.score }),
+                    ...(s.memoryStrategyId !== undefined && { memoryStrategyId: s.memoryStrategyId }),
+                    ...(typeof namespaceValue === 'string' && { namespace: namespaceValue }),
+                    ...(createdAt !== undefined && Number.isFinite(createdAt) && { createdAt }),
+                };
+            });
+            return { records };
+        },
     };
 }
 //# sourceMappingURL=agentcore.js.map