agentfootprint 6.44.0 → 6.45.0

package/dist/esm/memory/beats/llmExtractor.d.ts

@@ -0,0 +1,56 @@
+/**
+ * llmExtractor — LLM-backed beat extractor.
+ *
+ * Uses an LLMProvider (typically a cheap model like Claude Haiku or
+ * GPT-4o-mini) to produce semantically rich beats. One extraction LLM
+ * call per turn. Opt-in — default is `heuristicExtractor()` which is
+ * free.
+ *
+ * The extractor asks the LLM for a JSON response in this shape:
+ *
+ * ```json
+ * {
+ *   "beats": [
+ *     {
+ *       "summary": "User revealed their name is Alice",
+ *       "importance": 0.9,
+ *       "refs": ["msg-1-0"],
+ *       "category": "identity"
+ *     }
+ *   ]
+ * }
+ * ```
+ *
+ * The extractor parses, clamps importance via `asImportance()`, and
+ * returns the beats. Malformed responses fall back to an empty array
+ * — a bad extraction should not break the agent turn.
+ *
+ * Usage:
+ * ```ts
+ * import { anthropic } from 'agentfootprint';
+ * import { llmExtractor, narrativePipeline, InMemoryStore } from 'agentfootprint/memory';
+ *
+ * const pipeline = narrativePipeline({
+ *   store: new InMemoryStore(),
+ *   extractor: llmExtractor({ provider: yourLLMProvider }),
+ * });
+ * ```
+ */
+import type { LLMProvider } from '../../adapters/types.js';
+import type { BeatExtractor } from './extractor.js';
+export interface LLMExtractorConfig {
+    /** The provider used for extraction. Typically a cheap/fast model. */
+    readonly provider: LLMProvider;
+    /**
+     * Override the system prompt. Defaults to a one-paragraph instruction
+     * that elicits the JSON shape described in the module docs.
+     */
+    readonly systemPrompt?: string;
+    /**
+     * Dev-mode logger invoked when the LLM response fails to parse.
+     * Defaults to `console.warn` — production consumers can route the
+     * signal to their telemetry pipeline.
+     */
+    readonly onParseError?: (error: unknown, rawContent: string) => void;
+}
+export declare function llmExtractor(config: LLMExtractorConfig): BeatExtractor;

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

@@ -0,0 +1,60 @@
+/**
+ * Narrative beats — the unit of narrative memory.
+ *
+ * A `NarrativeBeat` is a self-contained summary extracted from one or
+ * more messages during a turn. Instead of persisting raw conversation
+ * forever, a narrative pipeline compresses each turn into beats and
+ * recalls them by composing beats back into a coherent story.
+ *
+ * Core properties:
+ *   - **Summary**: a single sentence describing what happened.
+ *   - **Importance**: 0..1 score the picker uses to prefer salient
+ *     beats when the context-token budget is tight.
+ *   - **Refs**: ids of the source messages the beat was extracted
+ *     from. Lets consumers walk backwards from a recalled beat to
+ *     the raw source — the explainability story.
+ *   - **Category**: optional free-form tag (e.g. `"identity"`,
+ *     `"preference"`, `"fact"`). Extractors / consumers pick their
+ *     own taxonomy.
+ *
+ * Beats are persisted via the ordinary `MemoryStore` interface —
+ * `MemoryEntry<NarrativeBeat>` slots in unchanged. No storage changes
+ * needed to support narrative memory.
+ */
+/** Importance score in the half-open range [0, 1]. */
+export type BeatImportance = number;
+export interface NarrativeBeat {
+    /** One-sentence summary of what happened in this beat. */
+    readonly summary: string;
+    /**
+     * Importance score in [0, 1]. Picker stages use this to prefer
+     * salient beats when the budget is tight. Default 0.5 (neutral).
+     * Values outside [0, 1] are clamped by `asImportance()`.
+     */
+    readonly importance: BeatImportance;
+    /**
+     * Ids of the source messages this beat was extracted from. Consumers
+     * answer "why does the agent remember X?" by walking refs backwards
+     * to the raw message text. May be empty for synthesized beats
+     * (e.g., beats produced from prior beats during compaction).
+     */
+    readonly refs: readonly string[];
+    /**
+     * Optional free-form category — `"identity"`, `"preference"`,
+     * `"task-status"`, etc. Extractors / consumers pick their own
+     * taxonomy. Useful for filtering recalls by type.
+     */
+    readonly category?: string;
+}
+/**
+ * Clamp a value to the valid [0, 1] importance range. Non-finite
+ * inputs collapse to 0.5 (neutral) so extractors that produce NaN
+ * / ±Infinity don't poison the picker's comparisons.
+ */
+export declare function asImportance(value: unknown): BeatImportance;
+/**
+ * Duck-typed guard — true iff `value` has the shape of a
+ * `NarrativeBeat`. Used by pipelines that handle mixed-payload stores
+ * (raw messages + beats) to route entries correctly.
+ */
+export declare function isNarrativeBeat(value: unknown): value is NarrativeBeat;

package/dist/esm/memory/beats/writeBeats.d.ts

@@ -0,0 +1,22 @@
+/**
+ * writeBeats — persist extracted beats to the memory store.
+ *
+ * Reads from scope:  `newBeats`, `identity`
+ * Writes to store:   one MemoryEntry<NarrativeBeat> per beat via `putMany`
+ *
+ * Parallels `writeMessages` — same shape, but the payload is beats
+ * rather than raw messages. Uses `store.putMany` so N beats from a
+ * single turn become 1 round-trip on network-backed adapters
+ * (Redis / DynamoDB / Postgres).
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { ExtractBeatsState } from './extractBeats.js';
+export interface WriteBeatsConfig {
+    /** The store to persist to. Typically the same store as the pipeline's read side. */
+    readonly store: MemoryStore;
+}
+/**
+ * Build the `writeBeats` stage function.
+ */
+export declare function writeBeats(config: WriteBeatsConfig): (scope: TypedScope<ExtractBeatsState>) => Promise<void>;

package/dist/esm/memory/causal/evidenceRecorder.d.ts

@@ -0,0 +1,66 @@
+/**
+ * causalEvidenceRecorder — the evidence bridge (backlog Phase-1 #5).
+ *
+ * Harvests, DURING the run, everything a causal snapshot needs beyond
+ * (query, finalContent) — from events the engine already fires:
+ *
+ *   stream.tool_start/tool_end  → ToolCallRecord (name, args, resultPreview, errored)
+ *   stream.llm_end              → tokenUsage accumulation + iteration high-water
+ *   agent.turn_start/turn_end   → durationMs (+ authoritative totals when seen)
+ *   FlowRecorder.onDecision     → DecisionRecord with footprintjs decide()/select()
+ *                                 operator-level evidence (rule, conditions, chosen)
+ *   context.evaluated routing   → DecisionRecord per skill the graph routed to
+ *
+ * Pattern: CombinedRecorder (Convention 1 — single purpose: evidence
+ *          accumulation); per-turn reset anchored on `agent.turn_start`
+ *          (Convention 4 — executor `clear()` resets between runs; same-
+ *          executor pause/resume PRESERVES pre-pause evidence by design).
+ * PII note: tool args/results and decide() evidence persist into snapshots.
+ *          footprintjs `RedactionPolicy.emitPatterns` redacts the emit channel
+ *          BEFORE this recorder IF the consumer configures one on the executor
+ *          — the Agent does NOT configure one by default. Values are bounded
+ *          (`maxPreviewChars` for results, `maxFieldChars` for args/evidence);
+ *          treat the snapshot store as PII-bearing and protect it accordingly.
+ *
+ * The Agent attaches this automatically when a CAUSAL memory is mounted and
+ * threads `collect` into the memory write mount (`evidenceSource`) — so
+ * `writeSnapshot` persists real evidence instead of zeros.
+ */
+import type { FlowDecisionEvent, FlowSelectedEvent } from 'footprintjs';
+import type { DecisionRecord, ToolCallRecord } from './types.js';
+/** What the bridge delivers to `writeSnapshot` for one run. */
+export interface RunEvidence {
+    readonly iterations: number;
+    readonly decisions: ReadonlyArray<DecisionRecord>;
+    readonly toolCalls: ReadonlyArray<ToolCallRecord>;
+    readonly durationMs: number;
+    readonly tokenUsage: {
+        readonly input: number;
+        readonly output: number;
+    };
+}
+export interface CausalEvidenceRecorderOptions {
+    /** Recorder id (default 'causal-evidence'). */
+    readonly id?: string;
+    /** Max chars kept of each tool result preview. Default 200. */
+    readonly maxPreviewChars?: number;
+    /** Max serialized chars kept of tool ARGS and decision EVIDENCE (the
+     *  PII-dense fields). Oversized values are replaced by a truncated
+     *  preview marker. Default 2000. */
+    readonly maxFieldChars?: number;
+}
+export interface CausalEvidenceRecorderHandle {
+    readonly id: string;
+    /** Snapshot the evidence accumulated for the CURRENT run. */
+    collect(): RunEvidence;
+    clear(): void;
+    onEmit(event: {
+        name: string;
+        payload: unknown;
+    }): void;
+    onDecision(event: FlowDecisionEvent): void;
+    onSelected(event: FlowSelectedEvent): void;
+}
+/** Build the evidence-harvesting recorder. Attach via `.recorder(rec)` (the
+ *  Agent does this automatically for CAUSAL memories). */
+export declare function causalEvidenceRecorder(options?: CausalEvidenceRecorderOptions): CausalEvidenceRecorderHandle;

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

@@ -0,0 +1,6 @@
+export type { SnapshotEntry, DecisionRecord, ToolCallRecord, ProjectedSnapshot, SnapshotMessage, } from './types.js';
+export { DEFAULT_TOOL_RESULT_PREVIEW_LEN } from './types.js';
+export { causalEvidenceRecorder, type CausalEvidenceRecorderHandle, type CausalEvidenceRecorderOptions, type RunEvidence, } from './evidenceRecorder.js';
+export { writeSnapshot, type WriteSnapshotConfig } from './writeSnapshot.js';
+export { loadSnapshot, type LoadSnapshotConfig } from './loadSnapshot.js';
+export { snapshotPipeline, type SnapshotPipelineConfig } from './snapshotPipeline.js';

package/dist/esm/memory/causal/loadSnapshot.d.ts

@@ -0,0 +1,51 @@
+/**
+ * loadSnapshot — read-side stage for Causal memory.
+ *
+ * Embeds the user's current question, searches the store for the most
+ * similar past run, projects the snapshot per `SnapshotProjection`,
+ * and writes the formatted result to `scope.formatted` so the
+ * downstream slot subflow injects it as a system message.
+ *
+ * Reads from scope:   `identity`, `messages` (or `newMessages` fallback)
+ * Writes to scope:    `formatted` — array of `LLMMessage` to inject
+ *
+ * Strict-threshold semantics:
+ *   When `minScore` is set and no past snapshot meets it, returns an
+ *   empty `formatted`. NO fallback — garbage past context is worse than
+ *   no context.
+ *
+ * Empty-query handling:
+ *   No user message → no embedding → no search → empty result.
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { Embedder } from '../embedding/index.js';
+import type { MemoryState } from '../stages/index.js';
+import { type SnapshotProjection } from '../define.types.js';
+export interface LoadSnapshotConfig {
+    /** Vector-capable store. Must implement `search()`. */
+    readonly store: MemoryStore;
+    /** Embedder used to vectorize the current query. */
+    readonly embedder: Embedder;
+    /** Stable id of the embedder — filters cross-model results out. */
+    readonly embedderId?: string;
+    /** Top-k snapshots to retrieve. Default 1 (most-relevant past run). */
+    readonly topK?: number;
+    /**
+     * Minimum cosine score [-1, 1]. Strict — entries below this are
+     * dropped. When no entry meets the threshold, the stage emits no
+     * messages (no fallback). Default 0.7.
+     */
+    readonly minScore?: number;
+    /**
+     * Slice of the snapshot to project. Default `'decisions'` —
+     * decision evidence is the highest-signal field for "why" follow-ups.
+     */
+    readonly projection?: SnapshotProjection;
+    /**
+     * Optional override for query extraction. Default: last user
+     * message in `scope.messages` (current turn's question).
+     */
+    readonly queryFrom?: (scope: TypedScope<MemoryState>) => string;
+}
+export declare function loadSnapshot(config: LoadSnapshotConfig): (scope: TypedScope<MemoryState>) => Promise<void>;

package/dist/esm/memory/causal/snapshotPipeline.d.ts

@@ -0,0 +1,35 @@
+/**
+ * snapshotPipeline — composes `loadSnapshot` + `writeSnapshot` into a
+ * `MemoryPipeline` ready to be mounted by `defineMemory({ type: CAUSAL })`.
+ *
+ *   READ  :  LoadSnapshot — embed query → search → project → format
+ *   WRITE :  WriteSnapshot — embed query → store as MemoryEntry<SnapshotEntry>
+ *
+ * The pipeline emits the same `agentfootprint.context.injected` event
+ * (with `source: 'memory'`) as every other memory flavor, so Lens
+ * shows Causal injections as memory chips alongside Episodic /
+ * Semantic / Narrative without special UI.
+ */
+import type { MemoryStore } from '../store/index.js';
+import type { Embedder } from '../embedding/index.js';
+import type { MemoryPipeline } from '../pipeline/types.js';
+import type { SnapshotProjection } from '../define.types.js';
+export interface SnapshotPipelineConfig {
+    /** Vector-capable store for the snapshots. Must implement `search()`. */
+    readonly store: MemoryStore;
+    /** Embedder used for both write-side indexing and read-side query. */
+    readonly embedder: Embedder;
+    /** Stable id of the embedder — prevents cross-model similarity pollution. */
+    readonly embedderId?: string;
+    /** Top-k past snapshots to consider on read. Default 1. */
+    readonly topK?: number;
+    /** Cosine threshold below which matches are dropped. Default 0.7. */
+    readonly minScore?: number;
+    /** Slice of the snapshot to inject. Default `'decisions'`. */
+    readonly projection?: SnapshotProjection;
+    /** Optional TTL for snapshots in ms. Useful for compliance windows. */
+    readonly ttlMs?: number;
+    /** Optional tier tag for written snapshots. */
+    readonly tier?: 'hot' | 'warm' | 'cold';
+}
+export declare function snapshotPipeline(config: SnapshotPipelineConfig): MemoryPipeline;

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

@@ -0,0 +1,130 @@
+/**
+ * Causal memory — types.
+ *
+ * A `SnapshotEntry` is the value stored in a Causal `MemoryStore`. It
+ * captures one agent run's "what happened and why" so future turns can
+ * answer follow-up questions ("why did you reject this?") with EXACT
+ * past facts instead of LLM reconstruction.
+ *
+ * Differentiator: footprintjs's `decide()`/`select()` already capture
+ * decision evidence as first-class events during traversal — we just
+ * persist them. Other libraries can't do this without rebuilding their
+ * core to surface decision evidence.
+ *
+ * Stored as `MemoryEntry<SnapshotEntry>` so the existing store layer
+ * (`MemoryStore`, `InMemoryStore`, future Redis/Dynamo/Postgres
+ * adapters) handles persistence + identity isolation + TTL + vector
+ * search out of the box.
+ */
+import type { LLMMessage } from '../../adapters/types.js';
+/**
+ * One stored agent run — the unit of causal memory.
+ *
+ * Field set is INTENTIONALLY MINIMAL for now: enough to demonstrate
+ * cross-run replay + cover RL/SFT export paths later. Richer fields
+ * (full commitLog, narrative entries with depth/path) get added when
+ * an out-of-band recorder integrates `executor.getSnapshot()` directly.
+ */
+export interface SnapshotEntry {
+    /**
+     * The user's message at the time of the run. THIS IS WHAT GETS
+     * EMBEDDED for retrieval — new queries are matched by cosine
+     * similarity against past queries.
+     */
+    readonly query: string;
+    /**
+     * The agent's final answer for the run. Pairs with `query` to form
+     * the (prompt, completion) pair RL/SFT exports project on.
+     */
+    readonly finalContent: string;
+    /**
+     * Iteration count — how many ReAct loop turns the agent used to
+     * produce `finalContent`. Useful for ranking "decisive" runs vs
+     * "thrashy" ones.
+     */
+    readonly iterations: number;
+    /**
+     * Decision records collected via `decide()`/`select()` during the
+     * run. Empty when the agent's flowchart didn't use any decision
+     * primitives. THE killer field (by design): each entry carries the rule
+     * that matched + the evidence values that satisfied it. STATUS: persisted
+     * EMPTY today — the evidence bridge (backlog #5) wires it.
+     */
+    readonly decisions: ReadonlyArray<DecisionRecord>;
+    /**
+     * Tool calls made during the run. Each entry: tool name, args,
+     * result (truncated). Surfaces the agent's tool-use trajectory for
+     * RL training of tool-use policies.
+     */
+    readonly toolCalls: ReadonlyArray<ToolCallRecord>;
+    /**
+     * Optional rendered narrative — when an out-of-band recorder
+     * captures `executor.getNarrative()` at write time, the full
+     * human-readable trace lands here.
+     */
+    readonly narrative?: string;
+    /**
+     * Wall-clock duration of the run in milliseconds.
+     */
+    readonly durationMs: number;
+    /**
+     * Cumulative token usage at end of run. Used to skip expensive
+     * snapshots from training-data exports under cost caps.
+     */
+    readonly tokenUsage: {
+        readonly input: number;
+        readonly output: number;
+    };
+    /**
+     * Optional eval score attached by an `evalRecorder`. When present,
+     * exports can filter to high-quality runs for SFT or rank for DPO.
+     */
+    readonly evalScore?: number;
+}
+export interface DecisionRecord {
+    /** Stage id where the decision happened (`'classify-risk'`). */
+    readonly stageId: string;
+    /** Branch chosen (`'rejected'`, `'manual-review'`). */
+    readonly chosen: string;
+    /** Optional human label of the rule that matched. */
+    readonly rule?: string;
+    /** Evidence values that led to the choice (key→value). */
+    readonly evidence?: Readonly<Record<string, unknown>>;
+}
+export interface ToolCallRecord {
+    /** Tool name as registered on the agent. */
+    readonly name: string;
+    /** Arguments passed to the tool. */
+    readonly args: Readonly<Record<string, unknown>>;
+    /** Result returned by the tool — TRUNCATED to keep snapshots small. */
+    readonly resultPreview: string;
+    /** True when the tool threw and the result is the error message. */
+    readonly errored: boolean;
+}
+/**
+ * Default truncation when serializing tool results into the snapshot.
+ * Keeps snapshot entries small enough to fit many in context during
+ * retrieval. Override per-call via `writeSnapshot` config.
+ */
+export declare const DEFAULT_TOOL_RESULT_PREVIEW_LEN = 500;
+/**
+ * What `loadSnapshot` returns to the formatter — the projection slice
+ * the consumer asked for via `defineMemory({ projection })`. Each
+ * projection produces a different `LLMMessage` content layout.
+ */
+export interface ProjectedSnapshot {
+    readonly query: string;
+    readonly content: string;
+    readonly source: {
+        readonly entryId: string;
+        readonly score: number;
+    };
+}
+/**
+ * The shape of a single message produced from a projected snapshot.
+ * Always `system` role so the LLM treats it as authoritative context
+ * about a past run.
+ */
+export type SnapshotMessage = LLMMessage & {
+    readonly role: 'system';
+};

package/dist/esm/memory/causal/writeSnapshot.d.ts

@@ -0,0 +1,73 @@
+/**
+ * writeSnapshot — write-side stage for Causal memory.
+ *
+ * Captures the current run's `(query, finalContent)` pair from
+ * `scope.newMessages` (populated by the Agent's PrepareFinal stage),
+ * embeds the query for retrieval, and persists a `SnapshotEntry` to
+ * the store. Future turns can match new questions against past
+ * queries via cosine similarity to replay decision evidence.
+ *
+ * Reads from scope:  `identity`, `turnNumber`, `newMessages`
+ * Writes to store:   one `SnapshotEntry` per call, id = `snap-{turn}`
+ *
+ * Why per-turn (not per-iteration)?
+ *   Causal memory captures TURN outcomes — "user asked X, agent said Y."
+ *   Mid-iteration state isn't useful for cross-run replay.
+ *
+ * Turn derivation — collisions are impossible by construction:
+ *   The effective turn is `max(scope.turnNumber, maxStoredTurn + 1)` where
+ *   `maxStoredTurn` is the highest `snap-{n}` already live in THIS
+ *   conversation's namespace (`identityNamespace(identity)` — the durable
+ *   conversation anchor across `run()` calls, Agent instances, and
+ *   processes). Rationale:
+ *     - Hosts that track `turnNumber` correctly keep their numbering
+ *       (`turnNumber: 5` → `snap-5`, gaps preserved).
+ *     - Hosts with a stale counter (the Agent seeds `turnNumber = 1` on
+ *       every run) still get a fresh, ordered id — turn 2 of the same
+ *       conversation lands `snap-2` instead of silently replacing
+ *       `snap-1`.
+ *   Causal snapshots are decision evidence (audit/replay data): when
+ *   "stale counter" and "deliberate same-turn rewrite" are
+ *   indistinguishable, never destroying a prior turn's evidence wins.
+ *   TTL-expired snapshots are ignored by the scan (same as every read).
+ *
+ * Empty-newMessages handling:
+ *   When `newMessages` is empty (no final answer produced — e.g.
+ *   pause-resume mid-flight), the stage no-ops. Re-runs after resume
+ *   capture the snapshot then.
+ *
+ * @see ./types.ts          for the SnapshotEntry shape this writes
+ * @see ./loadSnapshot.ts   for the read-side counterpart
+ */
+import type { TypedScope } from 'footprintjs';
+import type { MemoryStore } from '../store/index.js';
+import type { Embedder } from '../embedding/index.js';
+import type { MemoryState } from '../stages/index.js';
+export interface WriteSnapshotConfig {
+    /** The store to persist the snapshot to. */
+    readonly store: MemoryStore;
+    /**
+     * Embedder used to vectorize the query for later cosine-search.
+     * Required — Causal memory's value comes from semantic retrieval
+     * across past runs.
+     */
+    readonly embedder: Embedder;
+    /**
+     * Stable id for the embedder. Stored on the entry so a later
+     * embedder swap doesn't cross-pollute similarity scores.
+     * Default: `'unknown-embedder'` — pass an explicit id when you
+     * may swap embedder instances over time.
+     */
+    readonly embedderId?: string;
+    /**
+     * TTL in milliseconds — drop snapshots after this duration. Useful
+     * for compliance ("delete causal trace after 30 days").
+     */
+    readonly ttlMs?: number;
+    /**
+     * Tier to tag the snapshot with — typical: `'hot'` for current,
+     * `'warm'`/`'cold'` for archived. Read stages can filter by tier.
+     */
+    readonly tier?: 'hot' | 'warm' | 'cold';
+}
+export declare function writeSnapshot(config: WriteSnapshotConfig): (scope: TypedScope<MemoryState>) => Promise<void>;

package/dist/esm/memory/define.d.ts

@@ -0,0 +1,63 @@
+/**
+ * defineMemory — the single factory the consumer uses to register a
+ * memory subsystem on an Agent.
+ *
+ *     defineMemory({ id, type, strategy, store }) → MemoryDefinition
+ *
+ * The factory's job:
+ *   1. Switch on `type` (Episodic / Semantic / Narrative / Causal)
+ *      to pick the right family of pipelines.
+ *   2. Switch on `strategy.kind` within that family to wire stage
+ *      configs (loadCount / topK / threshold / extractor / ...).
+ *   3. Return an opaque `MemoryDefinition` that step-4's
+ *      `Agent.memory()` builder method consumes.
+ *
+ * Pattern: Factory + Strategy (GoF). One factory, N strategies, four
+ *          types — all reduce to two compiled FlowCharts (`read`,
+ *          `write?`) that mount as subflows.
+ *
+ * Role:    Layer-2 of the memory stack. Sits between the const-objects
+ *          contract (Layer 1) and the Agent builder method (Layer 4).
+ *
+ * Emits:   Indirectly — the compiled subflows emit
+ *          `agentfootprint.context.injected` with `source: 'memory'`
+ *          when their formatter writes to the messages slot.
+ *
+ * @see ./define.types.ts        for the const-objects + types
+ * @see ./pipeline/*.ts          for the existing pipeline factories this dispatches to
+ */
+import { type DefineMemoryOptions } from './define.types.js';
+import type { MemoryDefinition, ReadonlyMemoryFlowChart } from './define.types.js';
+/**
+ * Build a `MemoryDefinition` from a high-level `{ type, strategy, store }`
+ * config. Internally dispatches to one of the existing pipeline factories
+ * (defaultPipeline / semanticPipeline / factPipeline / narrativePipeline /
+ * autoPipeline / ephemeralPipeline) and wires the compiled flowcharts
+ * into the opaque definition that `Agent.memory()` consumes.
+ *
+ * Supported combinations:
+ *
+ * | type      | strategy.kind | underlying pipeline      |
+ * | --------- | ------------- | ------------------------ |
+ * | EPISODIC  | WINDOW        | defaultPipeline          |
+ * | EPISODIC  | BUDGET        | defaultPipeline          |
+ * | EPISODIC  | SUMMARIZE     | defaultPipeline + summarize stage |
+ * | SEMANTIC  | TOP_K         | semanticPipeline         |
+ * | SEMANTIC  | EXTRACT       | factPipeline             |
+ * | SEMANTIC  | WINDOW        | factPipeline (recency-load) |
+ * | NARRATIVE | EXTRACT       | narrativePipeline        |
+ * | NARRATIVE | WINDOW        | narrativePipeline (recency-load) |
+ * | (any)     | HYBRID        | autoPipeline (when sub-strategies map cleanly) |
+ *
+ * Unsupported combinations throw with a remediation hint pointing to a
+ * working alternative or to the raw `mountMemoryRead`/`mountMemoryWrite`
+ * helpers for power users.
+ */
+export declare function defineMemory(options: DefineMemoryOptions): MemoryDefinition;
+/**
+ * Internal — unwrap the brand. Used by `Agent.memory()` (step 4)
+ * to mount the pipeline. NOT exported.
+ *
+ * @internal
+ */
+export declare function unwrapMemoryFlowChart<T>(branded: ReadonlyMemoryFlowChart<T>): unknown;