agentfootprint 6.44.0 → 6.45.0

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';

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

@@ -0,0 +1,108 @@
+/**
+ * mountMemoryPipeline — mount a MemoryPipeline's read + write subflows
+ * into an arbitrary agent flowchart.
+ *
+ * Given:
+ *   - a `FlowChartBuilder<AgentState>` the caller has been assembling,
+ *   - a `MemoryPipeline { read, write }` (typically from a preset),
+ *   - identity + turn + budget inputs sourced from agent scope,
+ *   - mount points (which stage id to insert the read subflow before),
+ *
+ * returns the builder with:
+ *   1. the `read` subflow mounted BEFORE the given anchor stage, with an
+ *      inputMapper that reads identity/turn/budget from agent scope and
+ *      an outputMapper that writes `formatted` messages back,
+ *   2. the `write` subflow (if present) appended AT THE END, with an
+ *      inputMapper that reads `newMessages` from agent scope.
+ *
+ * The agent's existing stages are responsible for:
+ *   - populating `identity`, `turnNumber`, `contextTokensRemaining`,
+ *     `newMessages` in scope BEFORE the relevant memory subflow runs,
+ *   - consuming the injected `formatted` messages (merge into the
+ *     agent's outgoing LLM prompt).
+ *
+ * This helper does NOT own any of those concerns — it owns only the
+ * mechanical subflow mounting. Consumer-facing API
+ * (`AgentBuilder.memoryPipeline()`) is layered on top.
+ *
+ * Why a standalone helper, not a direct `AgentBuilder` patch?
+ *   - Lets us test the wire mechanism end-to-end in isolation (Layer 6)
+ *     without changing the existing AgentRunner path (100+ tests).
+ *   - The wire is a small, reviewable unit; the AgentBuilder refactor is
+ *     a larger concern that can ship separately.
+ *   - Future non-Agent concepts (Swarm, Parallel) can use the same helper
+ *     — memory isn't tied to Agent conceptually.
+ */
+import type { FlowChartBuilder } from 'footprintjs';
+import type { MemoryPipeline } from '../pipeline/types.js';
+/**
+ * Keys this helper reads from / writes to on the parent agent scope.
+ * Kept as fields on the config so consumers with non-standard field names
+ * can override without renaming scope properties.
+ */
+export interface MountMemoryPipelineConfig<ParentState> {
+    /** The compiled read + write subflows from a pipeline preset. */
+    readonly pipeline: MemoryPipeline;
+    /**
+     * Scope field name the read subflow reads identity from. Default
+     * `'identity'` — matches `MemoryState.identity`. Override when the
+     * host flowchart uses a different name.
+     */
+    readonly identityKey?: keyof ParentState & string;
+    /** Scope field name for the turn counter. Default `'turnNumber'`. */
+    readonly turnNumberKey?: keyof ParentState & string;
+    /**
+     * Scope field name for the context-tokens-remaining signal.
+     * Default `'contextTokensRemaining'`.
+     */
+    readonly contextTokensKey?: keyof ParentState & string;
+    /**
+     * Scope field the read subflow writes its `formatted` output to.
+     * Default `'memoryInjection'` — agent stages consume this to prepend
+     * to the LLM prompt. Distinct from the pipeline's own `formatted`
+     * field so there's no ambiguity between subflow-local and parent scope.
+     */
+    readonly injectionKey?: keyof ParentState & string;
+    /**
+     * Scope field the write subflow reads messages to persist from.
+     * Default `'newMessages'` — populated by the agent at turn end.
+     */
+    readonly newMessagesKey?: keyof ParentState & string;
+    /** Subflow id for the read mount. Default `'sf-memory-read'`. */
+    readonly readSubflowId?: string;
+    /** Subflow id for the write mount. Default `'sf-memory-write'`. */
+    readonly writeSubflowId?: string;
+    /**
+     * Evidence source for CAUSAL pipelines (the evidence bridge, backlog #5).
+     * Called by the write mount's inputMapper at write time; its result lands on
+     * `MemoryState.runEvidence` so `writeSnapshot` persists real decisions /
+     * tool calls / iterations / duration / token usage instead of zeros. The
+     * Agent threads `causalEvidenceRecorder().collect` here automatically when a
+     * CAUSAL memory is mounted. Omit for non-causal pipelines.
+     */
+    readonly evidenceSource?: () => import('../causal/evidenceRecorder.js').RunEvidence;
+}
+/**
+ * Mount only the READ subflow. Appends at the current builder tail, so
+ * callers typically invoke this BEFORE their LLM-call stage:
+ *
+ *   let b = flowChart('Seed', seedFn, 'seed');
+ *   b = mountMemoryRead(b, { pipeline });
+ *   b = b.addFunction('CallLLM', llmStage, 'call-llm');   // reads memoryInjection
+ *   b = mountMemoryWrite(b, { pipeline });                // persists newMessages
+ *
+ * Returns the same builder reference (fluent).
+ */
+export declare function mountMemoryRead<ParentState>(builder: FlowChartBuilder<ParentState>, config: MountMemoryPipelineConfig<ParentState>): FlowChartBuilder<ParentState>;
+/**
+ * Mount only the WRITE subflow. No-op when the pipeline has no `write`
+ * (e.g., ephemeral pipelines) — returns the builder unchanged.
+ */
+export declare function mountMemoryWrite<ParentState>(builder: FlowChartBuilder<ParentState>, config: MountMemoryPipelineConfig<ParentState>): FlowChartBuilder<ParentState>;
+/**
+ * Convenience: mount both read and write subflows back-to-back.
+ * Appropriate ONLY when the host flowchart has no stages between memory
+ * read and memory write (rare — most agents have the LLM call between).
+ * Prefer `mountMemoryRead` + stages + `mountMemoryWrite` for typical agents.
+ */
+export declare function mountMemoryPipeline<ParentState>(builder: FlowChartBuilder<ParentState>, config: MountMemoryPipelineConfig<ParentState>): FlowChartBuilder<ParentState>;

package/dist/esm/memory-providers.d.ts

@@ -0,0 +1,37 @@
+/**
+ * agentfootprint/memory-providers — memory store adapters (canonical subpath).
+ *
+ * The Block B canonical name. Mirrors the parallel structure shipped in
+ * v2.5:
+ *
+ *   agentfootprint/llm-providers     ← LLM provider adapters
+ *   agentfootprint/tool-providers    ← tool dispatch + tool sources
+ *   agentfootprint/memory-providers  ← memory store adapters (this file)
+ *   agentfootprint/security          ← cross-cutting authorization
+ *
+ * One subpath that grows — RedisStore, AgentCoreStore, and future
+ * stores (DynamoDB, Postgres, Pinecone, …) all live here. No more
+ * adding `agentfootprint/memory-<vendor>` per-adapter subpath each
+ * time a new store ships.
+ *
+ * Per-adapter aliases (`agentfootprint/memory-redis`,
+ * `agentfootprint/memory-agentcore`) stay available through the v2.x
+ * line — they point at the same files. New code SHOULD import from
+ * `agentfootprint/memory-providers`:
+ *
+ *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
+ *
+ * Pattern: Adapter (GoF) — each store translates the `MemoryStore`
+ *          interface onto a specific backend (Redis, DynamoDB-style
+ *          AWS Bedrock AgentCore Memory, etc.).
+ * Role:    Outer ring (Hexagonal). All store adapters lazy-require
+ *          their vendor SDKs at construction time, so importing this
+ *          barrel costs ZERO peer-dep load — only the stores you
+ *          actually instantiate pull their SDK in.
+ *
+ * @example
+ *   import { RedisStore, AgentCoreStore } from 'agentfootprint/memory-providers';
+ */
+export { RedisStore, type RedisStoreOptions, type RedisLikeClient, type RedisLikePipeline, } from './adapters/memory/redis.js';
+export { AgentCoreStore, type AgentCoreStoreOptions, type AgentCoreLikeClient, } from './adapters/memory/agentcore.js';
+export { BedrockAgentMemory, type BedrockAgentMemoryOptions, type BedrockAgentMemoryLikeClient, type BedrockAgentSummary, } from './adapters/memory/bedrockAgentMemory.js';

package/dist/esm/observability/contextError/finders/compareFinders.d.ts

@@ -0,0 +1,19 @@
+/**
+ * compareFinders — run several finders on the same case and collect their answers
+ * side by side (a leaderboard row per finder). PARAMETRIC: you pass the finders to
+ * compare, so nothing is auto-discovered or retained — unused finders stay
+ * tree-shakeable.
+ */
+import type { Finder, FindInput, FindResult } from './types.js';
+/** One finder's result in a comparison (or the error it threw). */
+export interface CompareRow {
+    readonly finder: string;
+    readonly result: FindResult | null;
+    readonly error?: string;
+}
+/**
+ * Run each finder on `input`; a finder that throws (e.g. missing a dep it needs)
+ * becomes a row with `result: null` and `error` set, so one finder cannot abort
+ * the comparison.
+ */
+export declare function compareFinders(finders: readonly Finder[], input: FindInput): Promise<CompareRow[]>;

package/dist/esm/observability/contextError/finders/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * observability / contextError / finders — pluggable context-bug localization.
+ *
+ * "Which piece of context made the agent's answer wrong?" Pick a finder and call
+ * `find(input)`. Each finder is a thin, self-explaining adapter over the engines in
+ * `src/lib/context-bisect` + `src/lib/influence-core`; the academic method + citation
+ * live in `meta`, never in the import name.
+ *
+ *   import { rankSuspects } from 'agentfootprint/observability/contextError/finders';
+ *   const r = await rankSuspects.find(input);   // r.lead, r.evidence ('guessed'|'proven')
+ *
+ * Tree-shakeable: one finder = one file = one named export. Importing one finder does
+ * not pull the others (or the heavy ablation path behind removeAndRetry). This barrel
+ * is re-export-only — no runtime code, no registry.
+ */
+export type { ContextPiece, Evidence, Finder, FinderMeta, FindInput, FindResult, Granularity, ScoredSuspect, StepInput, } from './types.js';
+export { rankSuspects } from './rankSuspects.js';
+export { removeAndRetry } from './removeAndRetry.js';
+export { traceSteps } from './traceSteps.js';
+export { testManyCombos } from './testManyCombos.js';
+export { shrinkToCause } from './shrinkToCause.js';
+export { compareFinders, type CompareRow } from './compareFinders.js';

package/dist/esm/observability/contextError/finders/rankSuspects.d.ts

@@ -0,0 +1,2 @@
+import type { Finder } from './types.js';
+export declare const rankSuspects: Finder;

package/dist/esm/observability/contextError/finders/removeAndRetry.d.ts

@@ -0,0 +1,11 @@
+/**
+ * removeAndRetry — the thorough finder. Removes each context piece, re-runs the
+ * agent, and a piece is the cause iff its removal flips the outcome back. No
+ * embedder, no heuristic: pure counterfactual. Exact, but pays one re-run per
+ * piece (`checks`), and on multi-loop runs it can over-attribute (several pieces
+ * each flip) — narrow with a slice first when that happens.
+ *
+ * Method: leave-one-out ablation (counterfactual necessity).
+ */
+import type { Finder } from './types.js';
+export declare const removeAndRetry: Finder;

package/dist/esm/observability/contextError/finders/shrinkToCause.d.ts

@@ -0,0 +1,11 @@
+/**
+ * shrinkToCause — keeps cutting the suspect set down until the smallest subset whose
+ * removal still fixes the answer. For a single dominant cause it converges in fewer
+ * re-runs than leave-one-out (delta-debugging minimization); for co-necessary causes it
+ * still returns the minimal recovering set, but may cost more probes than leave-one-out.
+ * The returned set is verified to recover by construction.
+ *
+ * Method: delta-debugging minimization (ddmin) over the removal set that recovers.
+ */
+import type { Finder } from './types.js';
+export declare const shrinkToCause: Finder;

package/dist/esm/observability/contextError/finders/testManyCombos.d.ts

@@ -0,0 +1,11 @@
+/**
+ * testManyCombos — turns context pieces on and off in many combinations, re-runs each,
+ * and learns which pieces drive the wrong answer (a linear-surrogate attribution), then
+ * confirms the top candidate with one clean ablation. The sampling one: it estimates an
+ * influence weight per piece from counterfactual data rather than ranking by similarity.
+ *
+ * Method: random-subset ablation + linear-surrogate attribution. Deterministic
+ * pseudo-random masking (a reproducible reimplementation of ContextCite's random subsets).
+ */
+import type { Finder } from './types.js';
+export declare const testManyCombos: Finder;

package/dist/esm/observability/contextError/finders/traceSteps.d.ts

@@ -0,0 +1,2 @@
+import type { Finder } from './types.js';
+export declare const traceSteps: Finder;