agentfootprint 6.44.0 → 7.0.0

package/dist/esm/memory/stages/summarize.d.ts

@@ -0,0 +1,87 @@
+/**
+ * summarize — stage that compresses old loaded entries into a single
+ * summary entry, preserving the most-recent N verbatim.
+ *
+ * Reads from scope:  `loaded`
+ * Writes to scope:   `loaded` (mutated: oldest entries replaced by one
+ *                     synthetic summary entry)
+ *
+ * Where this fits in the pipeline:
+ *
+ *   loadRecent → summarize → pickByBudget → formatDefault
+ *
+ * After `summarize` runs, `loaded` is smaller (fewer entries, one of
+ * which is a synthetic summary). The picker then selects from this
+ * reduced set using the standard budget logic.
+ *
+ * ## Determinism contract (Anthropic-reviewer ask)
+ *
+ * For prompt caching to stay stable across runs, the summary content
+ * MUST be the same each time for the same input. This requires:
+ *
+ *   1. Temperature = 0 on the provided LLM.
+ *   2. A stable seed if the provider supports it (Anthropic: omit;
+ *      OpenAI: pass a fixed `seed` in the request).
+ *   3. Same system prompt + message set produces same output.
+ *
+ * The stage CANNOT enforce this — it just calls the caller-supplied
+ * `llm` function. Callers are responsible for configuring determinism.
+ * Non-deterministic summarizers still work but invalidate prompt caches
+ * on every turn (~5× token-cost increase on cache-enabled providers).
+ *
+ * ## When summarize does NOT fire
+ *
+ * - `loaded.length < triggerMinEntries` → no-op (not enough history).
+ * - `loaded.length <= preserveRecent` → no-op (nothing to summarize; all
+ *    entries would be preserved verbatim anyway).
+ * - LLM call throws → error propagates to the pipeline's executor
+ *    (fail-loud, per loadRecent / writeMessages convention).
+ *
+ * ## Config guidance
+ *
+ * Choose `triggerMinEntries - preserveRecent >= 2`. Below that, a firing
+ * summarizer would compress just one entry — wasted LLM call with no
+ * real compression. Defaults (trigger 20, preserve 5) summarize 15
+ * entries when firing, which is a meaningful compression ratio.
+ *
+ * ## Summary entry shape
+ *
+ * The synthetic entry replaces the summarized range. It has:
+ *   - `id`: `summary-{earliest_turn}-to-{latest_turn}`
+ *   - `value`: a `{role: 'system', content: summaryText}` message
+ *   - `source.turn`: the LATEST turn that was summarized (for sorting)
+ *   - `tier`: 'cold' (marks it as "condensed, may not be recent")
+ *   - `source.identity`: carried over from the summarized range's first entry
+ */
+import type { TypedScope } from 'footprintjs';
+import type { LLMMessage as Message } from '../../adapters/types.js';
+import type { MemoryState } from './types.js';
+export interface SummarizeConfig {
+    /**
+     * LLM callback. Receives the chronological messages to summarize;
+     * must return the summary text. Caller is responsible for configuring
+     * the underlying model (temperature=0, seed, system prompt, etc.) to
+     * keep the output deterministic — see "Determinism contract" above.
+     */
+    readonly llm: (messages: readonly Message[]) => Promise<string>;
+    /**
+     * Minimum `loaded.length` before summarization triggers. Below this,
+     * no-op — the conversation is short enough to keep verbatim. Default 20.
+     */
+    readonly triggerMinEntries?: number;
+    /**
+     * Number of most-recent entries to preserve verbatim (NOT summarized).
+     * The oldest `loaded.length - preserveRecent` entries become a single
+     * summary entry. Default 5 — keeps recent turns intact so the agent
+     * can reference specific phrasing.
+     */
+    readonly preserveRecent?: number;
+    /**
+     * Optional custom system prompt for the summarizer. Default is a
+     * neutral "summarize the following conversation..." instruction.
+     * Override for domain-specific summaries (e.g., "preserve all
+     * refund-related details").
+     */
+    readonly systemPrompt?: string;
+}
+export declare function summarize(config: SummarizeConfig): (scope: TypedScope<MemoryState>) => Promise<void>;

package/dist/esm/memory/stages/tokenize.d.ts

@@ -0,0 +1,43 @@
+/**
+ * tokenize — approximate token counter for budget-aware memory stages.
+ *
+ * Memory stages need to answer "how many tokens does this content cost?"
+ * to decide what fits in a budget. A real tokenizer (tiktoken, Anthropic's
+ * tokenizer, etc.) is accurate but:
+ *
+ *   - Adds a dependency (tiktoken is ~2MB, has WASM loading quirks).
+ *   - Differs per model family (Claude counts differently from GPT).
+ *   - Pulls frontend bundles from small to huge.
+ *
+ * Phase 1 uses a deterministic approximation: 1 token ≈ 4 characters of
+ * English text. The constant comes from OpenAI's own documentation and
+ * is within ~15% for typical chat content. For "how much memory can I
+ * inject into an 8K context", 15% is fine.
+ *
+ * Consumers who need exact counts pass their own `TokenCounter` through
+ * the pipeline config. When that lands (Phase 2), this default stays as
+ * the dependency-free baseline.
+ */
+import type { LLMMessage as Message } from '../../adapters/types.js';
+/** A function that returns the token count of a string. */
+export type TokenCounter = (text: string) => number;
+/**
+ * Default approximation — 1 token per ~4 characters. Low-accuracy,
+ * zero-dependency, deterministic (same input → same count). Good enough
+ * for budget-based decisions; replace via pipeline config for accuracy.
+ *
+ * Accuracy notes:
+ *   - ASCII English: within ~15% of tiktoken.
+ *   - CJK / emoji / heavy unicode: can undercount by ~2× because
+ *     `String.length` counts UTF-16 code units, and CJK chars often
+ *     take multiple tokens each. Use a real tokenizer for these workloads.
+ *   - Code / JSON: reasonably accurate (punctuation-heavy is ~4 chars/tok).
+ */
+export declare const approximateTokenCounter: TokenCounter;
+/**
+ * Count tokens in a single message. Handles string content and the
+ * content-block array variant (where each block has its own text field).
+ * Non-text blocks (tool calls, images) contribute a small constant to
+ * reflect their structural cost.
+ */
+export declare function countMessageTokens(message: Message, counter?: TokenCounter): number;

package/dist/esm/memory/stages/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * MemoryState — shared scope for every stage in a memory pipeline.
+ *
+ * Each stage reads some fields and writes others; the pipeline's narrative
+ * shows who wrote what. Fields are added as layers need them — this is the
+ * minimal shape for Layer 2 (load + write stages). Layer 3 will add
+ * `candidates`, `selected`, `formatted`; Layer 8 will add summarization
+ * fields. Every field is optional so pipelines can mix stages freely.
+ *
+ * Shape design: fields cluster by pipeline direction.
+ *   - `identity` / `turnNumber` / `contextTokensRemaining` are INPUTS
+ *     set by the wire layer before the pipeline runs.
+ *   - `loaded` is the READ-SIDE output.
+ *   - `newMessages` is the WRITE-SIDE input.
+ *   - (later layers: `candidates`, `selected`, `formatted`, `saveBatch`)
+ */
+import type { MemoryIdentity } from '../identity/index.js';
+import type { MemoryEntry } from '../entry/index.js';
+import type { LLMMessage as Message } from '../../adapters/types.js';
+export interface MemoryState {
+    /**
+     * Scoping for every storage call this pipeline makes. Wire layer
+     * populates this before the pipeline runs; stages MUST NOT mutate it.
+     */
+    readonly identity: MemoryIdentity;
+    /**
+     * Run-local turn counter — 1 for the first `agent.run`, 2 for the second,
+     * and so on within the same conversationId. Written into `MemoryEntry.source`
+     * by write-side stages for provenance.
+     */
+    readonly turnNumber: number;
+    /**
+     * Context-window pressure signal (MemGPT-reviewer ask). Populated by the
+     * wire layer with `model.contextWindow - tokensUsedSoFar`. Picker stages
+     * (Layer 3) use this to decide how much memory to inject.
+     *
+     * 0 or negative values should be treated by consumers as "no headroom" —
+     * stages typically skip or truncate memory injection in that case.
+     */
+    readonly contextTokensRemaining: number;
+    /**
+     * Read-side output: entries loaded from the store this turn. Stages
+     * typically APPEND rather than replace so multiple load stages can
+     * contribute (e.g. recent-messages + semantic-retrieval + facts).
+     */
+    loaded: MemoryEntry<Message>[];
+    /**
+     * Picker output — the subset of `loaded` that fits the context budget,
+     * in chronological order (oldest first). Format stages consume this.
+     * Empty array when the picker decided NOT to inject memory (budget
+     * below minimum, or no entries loaded).
+     */
+    selected: MemoryEntry<Message>[];
+    /**
+     * Formatter output — the `Message[]` that will be injected into the
+     * LLM's prompt this turn. The wire layer merges this into the agent's
+     * messages array (typically as `system` messages before the user turn).
+     */
+    formatted: Message[];
+    /**
+     * Write-side input: messages to persist at the end of this turn. The
+     * wire layer populates from the agent's final message state;
+     * `writeMessages` wraps each as a `MemoryEntry` and calls `store.put`.
+     */
+    newMessages: Message[];
+    /**
+     * Write-side input (CAUSAL pipelines): evidence harvested during the run by
+     * `causalEvidenceRecorder` — decisions, tool calls, iterations, duration,
+     * token usage. Populated by the wire layer via the mount's `evidenceSource`;
+     * undefined for non-causal pipelines (writeSnapshot falls back to zeros).
+     */
+    runEvidence?: import('../causal/evidenceRecorder.js').RunEvidence;
+    /** Escape hatch for pipeline-specific fields. Typed per-pipeline as needed. */
+    [key: string]: unknown;
+}

package/dist/esm/memory/stages/writeMessages.d.ts

@@ -0,0 +1,71 @@
+/**
+ * writeMessages — write-side stage that persists new turn messages as
+ * `MemoryEntry`s.
+ *
+ * Reads from scope:  `identity`, `turnNumber`, `newMessages`
+ * Writes to store:   one entry per message, id = `msg-{turnNumber}-{index}`
+ *
+ * Every written entry carries `source.turn` + `source.identity` so
+ * retrieval stages can later show "recalled from turn 5" with correct
+ * cross-session provenance. A content-hash signature is also registered
+ * via `store.recordSignature` so subsequent `seen()` calls recognize
+ * near-duplicate content without loading the full entries.
+ *
+ * Why a deterministic `id` format?
+ *   `msg-{turn}-{index}` lets write-then-re-write be idempotent: a stage
+ *   that re-runs in the same turn (retries, resumable turns) overwrites
+ *   the same id instead of growing history. For non-turn-scoped writes,
+ *   pass a custom `idFrom` that produces whatever shape your app needs.
+ *
+ * PII / redaction:
+ *   Message content is stored VERBATIM. If your messages contain PII
+ *   (names, addresses, secrets), redact BEFORE writing — either by
+ *   mutating `scope.newMessages` upstream or by wrapping the call site
+ *   with a redaction helper. The storage layer does NOT scrub for you.
+ *   Pair with footprintjs's `RedactionPolicy` for end-to-end coverage.
+ *
+ * Extended thinking blocks (Anthropic) / reasoning tokens (OpenAI):
+ *   Persisting reasoning blocks is expensive — they can be 10-100× the
+ *   size of the final message. Strip them from `scope.newMessages` before
+ *   calling this stage UNLESS you plan to recall them (e.g. for debugging
+ *   replay). A common pattern: write reasoning to `tier: 'cold'` with a
+ *   short `ttlMs` so they age out quickly.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { LLMMessage as Message } from '../../adapters/types.js';
+import type { MemoryState } from './types.js';
+export interface WriteMessagesConfig {
+    /** The store to persist to. */
+    readonly store: MemoryStore;
+    /**
+     * Optional id producer — receives (turn, index, message) and returns
+     * the `MemoryEntry.id`. Defaults to `msg-{turn}-{index}` which makes
+     * re-runs of the same turn idempotent. Override for app-level ids
+     * (e.g. use a message's server-side id).
+     */
+    readonly idFrom?: (turn: number, index: number, message: Message) => string;
+    /**
+     * Optional signature producer for the recognition set. When present,
+     * each message produces a signature that is registered via
+     * `store.recordSignature`; `seen()` later returns `true` for the same
+     * content. Default: skip (many apps don't need recognition).
+     */
+    readonly signatureFrom?: (message: Message) => string;
+    /**
+     * Optional TTL in milliseconds from `Date.now()`. When set, written
+     * entries expire this long after they were stored. Useful for
+     * compliance retention windows ("delete chat history after 30 days").
+     */
+    readonly ttlMs?: number;
+    /**
+     * Optional tier for the entries. Typical pattern:
+     *   - `'hot'`  for the last few turns
+     *   - `'warm'` for older turns
+     *   - `'cold'` for archived
+     * Stages in Layer 3+ can filter on tier. Omitting leaves entries
+     * untiered (read stages still see them; tier-filtered reads skip them).
+     */
+    readonly tier?: 'hot' | 'warm' | 'cold';
+}
+export declare function writeMessages(config: WriteMessagesConfig): (scope: TypedScope<MemoryState>) => Promise<void>;

package/dist/esm/memory/store/InMemoryStore.d.ts

@@ -0,0 +1,62 @@
+/**
+ * InMemoryStore — reference `MemoryStore` implementation, zero dependencies.
+ *
+ * Kept deliberately small — ~200 lines. Its job is to validate the
+ * interface contract: every stage and pipeline is tested against this
+ * adapter, so any bug in the store shape surfaces here first.
+ *
+ * Internal structure:
+ *   namespace (string) → Map<entryId, MemoryEntry>
+ *                      + Set<signature>    (for seen)
+ *                      + Map<id, usefulnessSum, usefulnessCount>  (for feedback)
+ *
+ * TTL is enforced lazily on read (cheapest; no background sweeper needed).
+ * Pagination cursor is a monotonic integer — entries sorted by updatedAt desc.
+ */
+import type { MemoryIdentity } from '../identity/index.js';
+import type { MemoryEntry } from '../entry/index.js';
+import type { ListOptions, ListResult, MemoryStore, PutIfVersionResult, ScoredEntry, SearchOptions } from './types.js';
+export declare class InMemoryStore implements MemoryStore {
+    /**
+     * Top-level namespace → slot. Using `Map` rather than a plain object
+     * avoids prototype-pollution surface AND preserves insertion order
+     * (needed for deterministic list pagination).
+     */
+    private readonly namespaces;
+    private slot;
+    /** True if the entry's TTL has elapsed. Centralized so both `get` and `list` agree. */
+    private isExpired;
+    get<T = unknown>(identity: MemoryIdentity, id: string): Promise<MemoryEntry<T> | null>;
+    put<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>): Promise<void>;
+    /**
+     * Batched write — resolves the slot once and writes each entry into the
+     * same Map. Saves N-1 slot lookups vs. calling `put()` in a loop, and
+     * gives network-backed adapters a place to pipeline round-trips.
+     */
+    putMany<T = unknown>(identity: MemoryIdentity, entries: readonly MemoryEntry<T>[]): Promise<void>;
+    putIfVersion<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, expectedVersion: number): Promise<PutIfVersionResult>;
+    list<T = unknown>(identity: MemoryIdentity, options?: ListOptions): Promise<ListResult<T>>;
+    delete(identity: MemoryIdentity, id: string): Promise<void>;
+    seen(identity: MemoryIdentity, signature: string): Promise<boolean>;
+    recordSignature(identity: MemoryIdentity, signature: string): Promise<void>;
+    feedback(identity: MemoryIdentity, id: string, usefulness: number): Promise<void>;
+    getFeedback(identity: MemoryIdentity, id: string): Promise<{
+        average: number;
+        count: number;
+    } | null>;
+    forget(identity: MemoryIdentity): Promise<void>;
+    /**
+     * O(n) linear scan over identity-scoped entries. Fine for dev / tests
+     * — for production, plug in a real vector backend (pgvector, Pinecone,
+     * Qdrant) that implements the same interface.
+     *
+     * Semantics per the `MemoryStore.search?` contract:
+     *   - Entries without `embedding` are skipped (ignored, not errored).
+     *   - Entries with `embedding.length` mismatching the query are
+     *     skipped (cosine would throw — silent-skip avoids poisoning top-k).
+     *   - TTL-expired entries are omitted.
+     *   - Optional `tiers` / `minScore` / `embedderId` filters applied.
+     *   - Returns descending by score; ties broken by id for determinism.
+     */
+    search<T = unknown>(identity: MemoryIdentity, query: readonly number[], options?: SearchOptions): Promise<readonly ScoredEntry<T>[]>;
+}

package/dist/esm/memory/store/index.d.ts

@@ -0,0 +1,2 @@
+export type { MemoryStore, ListOptions, ListResult, MemoryCursor, PutIfVersionResult, SearchOptions, ScoredEntry, } from './types.js';
+export { InMemoryStore } from './InMemoryStore.js';

package/dist/esm/memory/store/types.d.ts

@@ -0,0 +1,223 @@
+/**
+ * MemoryStore — the I/O boundary.
+ *
+ * Every storage backend (InMemory, Redis, DynamoDB, Postgres, Bedrock
+ * AgentCore) implements this interface. Stages above the store layer never
+ * talk to a concrete backend — they invoke these methods and trust the
+ * adapter to handle durability, consistency, encryption, pagination, etc.
+ *
+ * Design principles:
+ *
+ * 1. **Identity is always the first argument.** Every call takes
+ *    `MemoryIdentity` so stores enforce tenant / principal isolation at
+ *    the boundary. A bug passing the wrong identity surfaces as "no data"
+ *    rather than a cross-tenant leak.
+ *
+ * 2. **Methods return Promises uniformly.** Even InMemoryStore's sync ops
+ *    are wrapped — stages can await every call and adapters are free to
+ *    swap sync ↔ async without breaking callers.
+ *
+ * 3. **Writes are optimistic-concurrency-aware.** `putIfVersion` is the
+ *    default for multi-writer correctness; `put` is convenience for "I
+ *    know I'm the only writer" callers (single-server, tests).
+ *
+ * 4. **Reads return cursors, not unbounded arrays.** `list` takes
+ *    `{ cursor?, limit? }` so large namespaces never OOM. Stages iterate
+ *    as long as they need.
+ *
+ * 5. **Recognition is separate from recall.** `seen(signature)` is a
+ *    boolean check — cheaper than `get` when the caller only needs
+ *    "have we processed this before?" (cognitive-arch reviewer ask).
+ *
+ * 6. **Feedback flows back.** `feedback(id, usefulness)` lets retrieval
+ *    stages signal "this entry was actually used / wasn't used" so
+ *    adapters can drive their own learning / eviction (RAG-theory ask).
+ */
+import type { MemoryIdentity } from '../identity/index.js';
+import type { MemoryEntry } from '../entry/index.js';
+/** Pagination cursor — opaque string, adapter-specific encoding. */
+export type MemoryCursor = string;
+/** Options for listing entries in a namespace. */
+export interface ListOptions {
+    /** Continuation token from a previous `list` call. Omit for the first page. */
+    readonly cursor?: MemoryCursor;
+    /** Maximum entries to return in this page. Adapters may cap this lower. */
+    readonly limit?: number;
+    /** Optional filter — only return entries matching these tiers. */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+}
+/** Result of a paginated `list` call. */
+export interface ListResult<T = unknown> {
+    readonly entries: readonly MemoryEntry<T>[];
+    /** Present iff more pages exist. Pass back into `list.cursor` to continue. */
+    readonly cursor?: MemoryCursor;
+}
+/** Outcome of a `putIfVersion` attempt. */
+export interface PutIfVersionResult {
+    /** True iff the write succeeded. */
+    readonly applied: boolean;
+    /**
+     * When `applied === false`, the current version stored — caller can
+     * decide whether to retry, merge, or abort. Absent if the entry did
+     * not exist at all.
+     */
+    readonly currentVersion?: number;
+}
+/** Options for a vector similarity search. */
+export interface SearchOptions {
+    /**
+     * How many top-scoring entries to return. Default 10. Adapters may
+     * cap this lower (Pinecone: 10000, pgvector: user-defined, etc.).
+     */
+    readonly k?: number;
+    /** Filter results by tier (e.g. `['hot']`) before ranking. */
+    readonly tiers?: ReadonlyArray<'hot' | 'warm' | 'cold'>;
+    /**
+     * Drop entries whose similarity score is below this threshold. Useful
+     * when "no match" is a valid outcome (vs. always returning the k
+     * nearest no matter how far away). Range [-1, 1] for cosine.
+     */
+    readonly minScore?: number;
+    /**
+     * Embedder id the query was produced with. When present, adapters MAY
+     * skip entries whose `embeddingModel` doesn't match — prevents silent
+     * cross-model similarity pollution. Absent = trust caller knows what
+     * they're doing.
+     */
+    readonly embedderId?: string;
+}
+/**
+ * A `MemoryEntry` annotated with its similarity score. Returned by
+ * `store.search()`. Score semantics are adapter-defined but SHOULD
+ * use cosine similarity by default ([-1, 1], higher = closer).
+ */
+export interface ScoredEntry<T = unknown> {
+    readonly entry: MemoryEntry<T>;
+    readonly score: number;
+}
+/**
+ * Common surface for all backends. Every method takes `MemoryIdentity`
+ * as the scoping argument; stores MUST prefix their internal keys with
+ * `identityNamespace(identity)` to prevent cross-tenant access.
+ */
+export interface MemoryStore {
+    /**
+     * Fetch one entry by id within the given identity's namespace.
+     * Returns `null` when the entry doesn't exist OR has expired (TTL).
+     * Callers should not distinguish — both mean "no data."
+     *
+     * Side effect: adapters MAY increment `accessCount` and update
+     * `lastAccessedAt` when returning the entry (decay signals).
+     */
+    get<T = unknown>(identity: MemoryIdentity, id: string): Promise<MemoryEntry<T> | null>;
+    /**
+     * Unconditional write — overwrites any existing entry with the same id.
+     * Prefer `putIfVersion` in multi-writer scenarios.
+     */
+    put<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>): Promise<void>;
+    /**
+     * Batched unconditional write. Semantically equivalent to N sequential
+     * `put()` calls but gives adapters a chance to batch the round-trip.
+     *
+     * - **InMemoryStore**: no-op optimization — loops internally.
+     * - **Redis**: pipelined MSET / MULTI-EXEC.
+     * - **DynamoDB**: `BatchWriteItem` (25-entry limit enforced by caller
+     *   or adapter — adapters MAY chunk).
+     * - **Postgres**: multi-row INSERT … ON CONFLICT DO UPDATE.
+     *
+     * Atomicity is NOT guaranteed across the batch — a partial failure
+     * may leave some entries written, some not. Stages that need
+     * transactional semantics should use `putIfVersion` per entry with
+     * application-level rollback. Most memory flows are append-idempotent
+     * (ids are deterministic like `msg-{turn}-{idx}`), so the batch model
+     * matches the common case.
+     *
+     * **Empty batch (`entries.length === 0`): MUST be a no-op.** Callers
+     * rely on this to skip a round-trip when there's nothing to persist
+     * (e.g., a turn that produced no new messages). Adapters must not
+     * reject empty batches — return a resolved Promise immediately.
+     *
+     * Default implementation for adapters that don't override: sequentially
+     * calls `put()` for each entry. Adapters SHOULD override for
+     * performance-critical paths.
+     */
+    putMany<T = unknown>(identity: MemoryIdentity, entries: readonly MemoryEntry<T>[]): Promise<void>;
+    /**
+     * Optimistic-concurrency write. Writes only if the stored version equals
+     * `expectedVersion`, OR if no entry exists at all AND `expectedVersion`
+     * is `0` (first-write sentinel).
+     *
+     * Returns `{ applied: true }` on success, `{ applied: false, currentVersion }`
+     * when the caller's assumed version is stale.
+     */
+    putIfVersion<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, expectedVersion: number): Promise<PutIfVersionResult>;
+    /**
+     * Page through entries in the identity's namespace. Ordered by adapter's
+     * choice (usually most-recently-updated first) — consumers that care
+     * about order should filter client-side.
+     */
+    list<T = unknown>(identity: MemoryIdentity, options?: ListOptions): Promise<ListResult<T>>;
+    /** Remove one entry. No-op if the entry doesn't exist. */
+    delete(identity: MemoryIdentity, id: string): Promise<void>;
+    /**
+     * Cheap "have we processed this signature before?" check. Useful for
+     * deduplication, idempotent writes, and cognitive-arch-style recognition
+     * vs. recall. Signature is an opaque string the caller controls
+     * (content hash, canonicalized fact, etc.).
+     */
+    seen(identity: MemoryIdentity, signature: string): Promise<boolean>;
+    /**
+     * Write-side of the recognition set — adds a signature so subsequent
+     * `seen()` calls return `true`. Stages register signatures as entries
+     * are written (content hashes, canonicalized facts). Separate from the
+     * entry store: a signature outlives the entry that produced it, so
+     * dedup survives garbage collection.
+     */
+    recordSignature(identity: MemoryIdentity, signature: string): Promise<void>;
+    /**
+     * Record usefulness feedback for an entry. `usefulness` in `[-1, 1]`:
+     *   -1 = retrieved but harmful / misleading
+     *    0 = retrieved but not used (neutral)
+     *    1 = retrieved AND used in the final answer
+     *
+     * Non-finite values (NaN / ±Infinity) MUST be rejected by adapters —
+     * they poison the aggregate. Caller should pass a finite number in
+     * `[-1, 1]`; adapters clamp to the valid range for hardening.
+     */
+    feedback(identity: MemoryIdentity, id: string, usefulness: number): Promise<void>;
+    /**
+     * Read-side of feedback — aggregated usefulness for an entry. Returns
+     * `null` when no feedback has been recorded (distinct from "neutral
+     * average of 0" — callers often want to treat the two differently).
+     * Retrieval stages consume this to feedback-weight rankings.
+     */
+    getFeedback(identity: MemoryIdentity, id: string): Promise<{
+        average: number;
+        count: number;
+    } | null>;
+    /**
+     * GDPR — remove ALL entries for the given identity.
+     * Must be implementable in one operation per backend (DELETE WHERE prefix).
+     */
+    forget(identity: MemoryIdentity): Promise<void>;
+    /**
+     * Optional — similarity search over entries that carry an
+     * `embedding` field. Returns the top-k entries by cosine similarity
+     * (descending). Adapters that don't support vector search should
+     * OMIT this method; callers feature-detect via `if (store.search)`.
+     *
+     * Semantics:
+     *   - Entries with no `embedding` field are ignored (not errored).
+     *   - Entries with `embedding` of mismatched length are skipped
+     *     (cosine would throw — silent-skip avoids poisoning the top-k).
+     *   - TTL-expired entries are omitted (same as `get`/`list`).
+     *   - Ordering: descending by score. Ties broken by adapter choice.
+     *
+     * Reference backends:
+     *   - **InMemoryStore**: O(n) linear scan over identity-scoped entries.
+     *     Fine for dev / tests. Production needs a real vector DB.
+     *   - **pgvector**: `ORDER BY embedding <=> query LIMIT k`.
+     *   - **Pinecone / Qdrant / Weaviate**: native vector query API.
+     */
+    search?<T = unknown>(identity: MemoryIdentity, query: readonly number[], options?: SearchOptions): Promise<readonly ScoredEntry<T>[]>;
+}

package/dist/esm/memory/wire/index.d.ts

@@ -0,0 +1,2 @@
+export { mountMemoryRead, mountMemoryWrite, mountMemoryPipeline } from './mountMemoryPipeline.js';
+export type { MountMemoryPipelineConfig } from './mountMemoryPipeline.js';