agentfootprint 1.23.0 → 2.1.0

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

@@ -0,0 +1,131 @@
+/**
+ * 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: each entry carries the rule that
+     * matched + the evidence values that satisfied it, enabling
+     * zero-hallucination "why" follow-ups.
+     */
+    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';
+};
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/memory/causal/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAE9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAElD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IAElD;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,CAAC;IAEF;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,uEAAuE;IACvE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAED;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,MAAM,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;CACvE;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC"}

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

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ *
+ * 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>;
+//# sourceMappingURL=writeSnapshot.d.ts.map

package/dist/types/memory/causal/writeSnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeSnapshot.d.ts","sourceRoot":"","sources":["../../../../src/memory/causal/writeSnapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAG9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;CACzC;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,WAIlC,WAAW,WAAW,CAAC,KAAG,QAAQ,IAAI,CAAC,CAmD7D"}

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

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ *
+ * 8-panel review (2026-04-28):
+ * - LLM Systems   ✅  asRole knob honored when present, defaults to 'system'
+ * - Architect     ✅  per-id scope keys (`memoryInjectionKey(id)`)
+ * - API Designer  ✅  one factory; CAUSAL stays here, no separate snapshotMemory
+ * - Performance   ✅  default `MEMORY_TIMING.TURN_START`; pipelines compiled once
+ * - Privacy       ✅  redact field passes through
+ * - ML / IR       ✅  threshold maps to semantic.minScore strictly; no fallback
+ * - SoftEng       ✅  unsupported combos throw with clear remediation hint
+ * - TS Engineer   ✅  discriminated union narrowing preserved across switches
+ *
+ * Book reference: AI Agents — The Definitive Guide, Ch 10 (Memory,
+ *   Autonomy, Long-Horizon Use — chapter still unavailable in pre-pub).
+ *
+ * @see ./define.types.ts        for the const-objects + types
+ * @see ./pipeline/*.ts          for the existing pipeline factories this dispatches to
+ * @see MEMORY.md                load-bearing design memory
+ */
+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;
+//# sourceMappingURL=define.d.ts.map

package/dist/types/memory/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../../src/memory/define.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAaH,OAAO,EAIL,KAAK,mBAAmB,EAYzB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AAInF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,gBAAgB,CAqB3E;AA6RD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,OAAO,CAErF"}

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

@@ -0,0 +1,284 @@
+/**
+ * Memory subsystem — public type surface.
+ *
+ * THE 2D mental model the library teaches:
+ *
+ *     MEMORY = TYPE × STRATEGY × STORE
+ *
+ *     TYPE       — what shape of memory you're keeping
+ *                  (Episodic messages / Semantic facts / Narrative beats /
+ *                   Causal footprintjs snapshots)
+ *     STRATEGY   — how to fit content into the next LLM call
+ *                  (Window / Budget / Summarize / TopK / Extract / Decay / Hybrid)
+ *     STORE      — where the bytes live
+ *                  (InMemoryStore / Redis / Postgres / DynamoDB / Vector ...)
+ *
+ * Strategy is universal — same Window works for Episodic and for Causal.
+ * That's why examples are organized by strategy (the discipline) not by
+ * type (the shape).
+ *
+ * Pattern: Single-Source-of-Truth const objects + discriminated union.
+ *          Mirrors `src/conventions.ts` (SUBFLOW_IDS, INJECTION_KEYS).
+ *          NEVER enums (TS enums emit runtime objects + opacity).
+ *          Const-as-const erases at compile time, accepts string literals,
+ *          and gives consumers IDE autocomplete + refactor safety.
+ *
+ * Role:    Layer-1 contract for the memory subsystem. Step 2's
+ *          `defineMemory()` factory consumes these to build pipelines;
+ *          Step 4's `Agent.memory()` builder mounts the resulting
+ *          definitions; Step 5's Causal machinery extends them.
+ *
+ * Emits:   Indirectly — every memory pipeline emits the unified
+ *          `agentfootprint.context.injected` event with `source: 'memory'`
+ *          when its read subflow places content into the messages slot.
+ *
+ * 8-panel review (2026-04-28):
+ * - LLM Systems   ✅  asRole knob added so memories can land as user/system/assistant
+ * - Architect     ✅  per-id scope keys (`memoryInjection_${id}`) — multi-memory layering safe
+ * - API Designer  ✅  ONE factory for all four types incl. Causal (no separate `snapshotMemory`)
+ * - Performance   ✅  default `MEMORY_TIMING.TURN_START` (was per-iteration — perf trap)
+ * - Privacy       ✅  `redact?` API hook reserved
+ * - ML / IR       ✅  causal snapshots tagged with original query for retrieval embedding
+ * - SoftEng       ✅  discriminated union with `kind` discriminator → full TS narrowing
+ * - TS Engineer   ✅  generic over `MemoryEntry<T>` payload preserves type-safety
+ *
+ * @see ./define.ts          for the `defineMemory()` factory itself
+ * @see ../../docs-site      for guides + the 7 strategy examples
+ * @see MEMORY.md            for the load-bearing design memory
+ */
+import type { LLMProvider } from '../adapters/types.js';
+import type { ContextRole } from '../events/types.js';
+import type { Embedder } from './embedding/index.js';
+import type { MemoryStore } from './store/index.js';
+/**
+ * What shape of memory you're keeping.
+ *
+ * - `EPISODIC`  — raw conversation messages, replayed on next turn
+ * - `SEMANTIC`  — extracted structured facts, deduped on key
+ * - `NARRATIVE` — beats / summaries of prior runs (append-only)
+ * - `CAUSAL`    — footprintjs execution snapshots, the differentiator
+ *                 (zero-hallucination follow-ups via decision-evidence replay)
+ */
+export declare const MEMORY_TYPES: {
+    readonly EPISODIC: "episodic";
+    readonly SEMANTIC: "semantic";
+    readonly NARRATIVE: "narrative";
+    readonly CAUSAL: "causal";
+};
+export type MemoryType = (typeof MEMORY_TYPES)[keyof typeof MEMORY_TYPES];
+/**
+ * How content is selected / compressed for the next LLM call.
+ *
+ * Universal across types. A `WINDOW` strategy on an Episodic store keeps
+ * the last N messages; on a Causal store it keeps the last N snapshots.
+ * Mix and match.
+ */
+export declare const MEMORY_STRATEGIES: {
+    readonly WINDOW: "window";
+    readonly BUDGET: "budget";
+    readonly SUMMARIZE: "summarize";
+    readonly TOP_K: "topK";
+    readonly EXTRACT: "extract";
+    readonly DECAY: "decay";
+    readonly HYBRID: "hybrid";
+};
+export type MemoryStrategyKind = (typeof MEMORY_STRATEGIES)[keyof typeof MEMORY_STRATEGIES];
+/**
+ * When the memory's READ subflow runs.
+ *
+ * Default `TURN_START` reads memory once per `agent.run()`. Use
+ * `EVERY_ITERATION` only when the strategy is sensitive to in-loop tool
+ * results — every-iteration multiplies store-latency by iteration-count.
+ */
+export declare const MEMORY_TIMING: {
+    readonly EVERY_ITERATION: "every-iteration";
+    readonly TURN_START: "turn-start";
+};
+export type MemoryTiming = (typeof MEMORY_TIMING)[keyof typeof MEMORY_TIMING];
+/**
+ * For Causal memory only — which slice of a footprintjs snapshot to
+ * inject. Snapshots can run 100KB+; projecting prevents context blowup.
+ *
+ * - `DECISIONS` — `decide()`/`select()` evidence only (the "why" chain)
+ * - `COMMITS`   — commitLog only (every state write, ordered)
+ * - `NARRATIVE` — narrative entries only (human-readable trace)
+ * - `FULL`      — entire snapshot (use sparingly)
+ */
+export declare const SNAPSHOT_PROJECTIONS: {
+    readonly DECISIONS: "decisions";
+    readonly COMMITS: "commits";
+    readonly NARRATIVE: "narrative";
+    readonly FULL: "full";
+};
+export type SnapshotProjection = (typeof SNAPSHOT_PROJECTIONS)[keyof typeof SNAPSHOT_PROJECTIONS];
+/** Window — keep the last `size` entries. Pure rule, no LLM, no embedder. */
+export interface WindowStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.WINDOW;
+    readonly size: number;
+}
+/**
+ * Budget — pick entries that fit within a token budget. Used as a
+ * decider stage: skip-if-empty | skip-if-no-budget | pick-by-tokens.
+ */
+export interface BudgetStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.BUDGET;
+    /** Reserve N tokens for prompt headers / new user message. Default 256. */
+    readonly reserveTokens?: number;
+    /** Skip injection below this token floor. Default 100. */
+    readonly minimumTokens?: number;
+    /** Hard cap on entries to inject — guards against "lost-in-the-middle". */
+    readonly maxEntries?: number;
+}
+/**
+ * Summarize — when the conversation grows long, an LLM compresses older
+ * turns into a paragraph; recent N turns stay raw. The standard answer
+ * to "long conversations blow context."
+ */
+export interface SummarizeStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.SUMMARIZE;
+    /** Keep this many most-recent turns uncompressed. */
+    readonly recent: number;
+    /** LLM that does the compression — recommend a cheap model (haiku). */
+    readonly llm: LLMProvider;
+}
+/**
+ * Top-K — embed the user's query, retrieve top-K by cosine similarity.
+ * STRICT threshold: when no entry meets the threshold, return EMPTY.
+ * No fallback — garbage in context is worse than no memory.
+ */
+export interface TopKStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.TOP_K;
+    readonly topK: number;
+    /** Min cosine similarity. Strict — no fallback below this. Default 0.7. */
+    readonly threshold?: number;
+    readonly embedder: Embedder;
+}
+/**
+ * Extract — on WRITE, an LLM (or pattern matcher) distills entries from
+ * raw messages into structured shapes (facts/beats). Usually paired with
+ * a load-side strategy like TopK or Window for the read direction.
+ */
+export interface ExtractStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.EXTRACT;
+    /** Pattern-based (regex heuristics, free) or LLM-based (paid). */
+    readonly extractor: 'pattern' | 'llm';
+    /** Required when `extractor: 'llm'`. */
+    readonly llm?: LLMProvider;
+    /** Discard extractions below this confidence. Default 0.7. */
+    readonly minConfidence?: number;
+    /** Cap entries extracted per turn. Default 5. */
+    readonly maxPerTurn?: number;
+}
+/**
+ * Decay — score entries by `recency × accessCount`, drop below floor.
+ * For long-running agents where unused memory should fade.
+ */
+export interface DecayStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.DECAY;
+    /** Half-life in milliseconds for the recency component. */
+    readonly halfLifeMs: number;
+    /** Drop entries scoring below this. Default 0.1. */
+    readonly minScore?: number;
+}
+/**
+ * Hybrid — compose multiple strategies. Each sub-strategy runs as its
+ * own selector branch; results are merged in the order listed.
+ */
+export interface HybridStrategy {
+    readonly kind: typeof MEMORY_STRATEGIES.HYBRID;
+    readonly strategies: ReadonlyArray<Exclude<Strategy, HybridStrategy>>;
+}
+/** The full strategy union — discriminated by `kind`. */
+export type Strategy = WindowStrategy | BudgetStrategy | SummarizeStrategy | TopKStrategy | ExtractStrategy | DecayStrategy | HybridStrategy;
+/**
+ * Reserved API surface for content redaction before memory writes.
+ * Impl is deferred; the field exists now so adding redaction later
+ * is non-breaking. Privacy panel review: snapshot/episodic writes may
+ * carry PII — this is the integration point.
+ */
+export interface MemoryRedactionPolicy {
+    /** Patterns to mask in stored content. */
+    readonly patterns?: readonly RegExp[];
+    /** Replacement string. Default `'[REDACTED]'`. */
+    readonly replacement?: string;
+}
+/**
+ * The opaque value `defineMemory()` returns. `Agent.memory()` consumes
+ * one of these per memory the consumer registers; multiple definitions
+ * layer cleanly via per-id scope keys (`memoryInjection_${id}`).
+ *
+ * Generic `T` is the payload shape stored — `Message` for episodic,
+ * `Fact` for semantic, `NarrativeBeat` for narrative, `RunSnapshot` for
+ * causal. The factory infers `T` from `type`.
+ */
+export interface MemoryDefinition<T = unknown> {
+    /** Stable identifier. Becomes the scope-key suffix and the Lens label. */
+    readonly id: string;
+    /** Surfaces in narrative / Lens hover. */
+    readonly description?: string;
+    /** Which TYPE shape — gates legal STRATEGY combinations. */
+    readonly type: MemoryType;
+    /** Compiled read subflow (built by the factory from type × strategy). */
+    readonly read: ReadonlyMemoryFlowChart<T>;
+    /** Compiled write subflow. Optional — `EPHEMERAL`-style configs omit. */
+    readonly write?: ReadonlyMemoryFlowChart<T>;
+    /** When `read` runs. Default `TURN_START`. */
+    readonly timing: MemoryTiming;
+    /** Role to use when injecting formatted content into the messages slot. */
+    readonly asRole: ContextRole;
+    /** Reserved for a future release — patterns to redact before write. */
+    readonly redact?: MemoryRedactionPolicy;
+    /** Snapshot projection — only meaningful when `type === CAUSAL`. */
+    readonly projection?: SnapshotProjection;
+}
+/**
+ * Opaque tag for the compiled flowchart the factory hands back.
+ * The actual type is `FlowChart<MemoryState>` from footprintjs but we
+ * keep it nominal here so consumers can't reach in.
+ */
+export type ReadonlyMemoryFlowChart<_T> = {
+    readonly __brand: 'ReadonlyMemoryFlowChart';
+};
+/**
+ * Common options for every memory type. Type-specific options layer on
+ * top via discriminated `type` field in the next overload set (Step 2).
+ */
+export interface DefineMemoryOptionsBase {
+    readonly id: string;
+    readonly description?: string;
+    readonly store: MemoryStore;
+    readonly strategy: Strategy;
+    readonly timing?: MemoryTiming;
+    readonly asRole?: ContextRole;
+    readonly redact?: MemoryRedactionPolicy;
+}
+export interface DefineEpisodicOptions extends DefineMemoryOptionsBase {
+    readonly type: typeof MEMORY_TYPES.EPISODIC;
+}
+export interface DefineSemanticOptions extends DefineMemoryOptionsBase {
+    readonly type: typeof MEMORY_TYPES.SEMANTIC;
+}
+export interface DefineNarrativeOptions extends DefineMemoryOptionsBase {
+    readonly type: typeof MEMORY_TYPES.NARRATIVE;
+}
+export interface DefineCausalOptions extends DefineMemoryOptionsBase {
+    readonly type: typeof MEMORY_TYPES.CAUSAL;
+    /** Slice of the snapshot to inject. Default `DECISIONS`. */
+    readonly projection?: SnapshotProjection;
+}
+/** Discriminated by `type`. The factory uses this to pick the pipeline. */
+export type DefineMemoryOptions = DefineEpisodicOptions | DefineSemanticOptions | DefineNarrativeOptions | DefineCausalOptions;
+export declare function isMemoryType(value: string): value is MemoryType;
+export declare function isMemoryStrategyKind(value: string): value is MemoryStrategyKind;
+export declare function isMemoryTiming(value: string): value is MemoryTiming;
+export declare function isSnapshotProjection(value: string): value is SnapshotProjection;
+/**
+ * Scope-key prefix used when mounting multiple `.memory()` definitions
+ * on the same Agent. Each memory writes to `memoryInjection_${id}` so
+ * registrations never collide. Formatter merges all keys with this
+ * prefix in registration order.
+ */
+export declare const MEMORY_INJECTION_KEY_PREFIX: "memoryInjection_";
+export declare function memoryInjectionKey(id: string): string;
+export declare function isMemoryInjectionKey(key: string): boolean;
+//# sourceMappingURL=define.types.d.ts.map

package/dist/types/memory/define.types.d.ts.map

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

package/dist/types/memory/embedding/embedMessages.d.ts

@@ -20,7 +20,7 @@
  */
 import type { TypedScope } from 'footprintjs';
 import type { Embedder } from './types';
-import type { Message } from '../../types/messages';
+import type { LLMMessage as Message } from '../../adapters/types';
 import type { MemoryState } from '../stages';
 /** Extend MemoryState to carry per-message embeddings for writeMessages. */
 export interface EmbedMessagesState extends MemoryState {

package/dist/types/memory/embedding/embedMessages.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embedMessages.d.ts","sourceRoot":"","sources":["../../../../src/memory/embedding/embedMessages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,4EAA4E;AAC5E,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IAEtD,mFAAmF;IACnF,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;CAClD;AAmBD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,WAIlC,WAAW,kBAAkB,CAAC,KAAG,QAAQ,IAAI,CAAC,CA6BpE"}
+{"version":3,"file":"embedMessages.d.ts","sourceRoot":"","sources":["../../../../src/memory/embedding/embedMessages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAE7C,4EAA4E;AAC5E,MAAM,WAAW,kBAAmB,SAAQ,WAAW;IACrD;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;IAEtD,mFAAmF;IACnF,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IAClC,yEAAyE;IACzE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;CAClD;AAOD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,WAIlC,WAAW,kBAAkB,CAAC,KAAG,QAAQ,IAAI,CAAC,CA6BpE"}

package/dist/types/memory/embedding/loadRelevant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loadRelevant.d.ts","sourceRoot":"","sources":["../../../../src/memory/embedding/loadRelevant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,4EAA4E;IAC5E,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAEpB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,MAAM,CAAC;CACjE;AAkCD,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,WAWhC,WAAW,WAAW,CAAC,KAAG,QAAQ,IAAI,CAAC,CAyB7D"}
+{"version":3,"file":"loadRelevant.d.ts","sourceRoot":"","sources":["../../../../src/memory/embedding/loadRelevant.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC5C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,4EAA4E;IAC5E,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IAEpB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,8BAA8B;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAC,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC;IAExD;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,MAAM,CAAC;CACjE;AAwBD,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,WAWhC,WAAW,WAAW,CAAC,KAAG,QAAQ,IAAI,CAAC,CAyB7D"}

package/dist/types/memory/facts/extractor.d.ts

@@ -12,7 +12,7 @@
  *   - `llmFactExtractor({ provider })` — one LLM call per turn for
  *     open-ended extraction. Opt-in.
  */
-import type { Message } from '../../types/messages';
+import type { LLMMessage as Message } from '../../adapters/types';
 import type { Fact } from './types';
 export interface FactExtractArgs {
     /** New-turn messages. */

package/dist/types/memory/facts/extractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/facts/extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IAEpC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;CAC1D"}
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/facts/extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,IAAI,EAAE,CAAC;IAEpC,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;CAC1D"}

package/dist/types/memory/facts/llmFactExtractor.d.ts

@@ -34,11 +34,11 @@
  *
  * const pipeline = factPipeline({
  *   store: new InMemoryStore(),
- *   extractor: llmFactExtractor({ provider: anthropic('claude-haiku-4-5') }),
+ *   extractor: llmFactExtractor({ provider: yourLLMProvider }),
  * });
  * ```
  */
-import type { LLMProvider } from '../../types';
+import type { LLMProvider } from '../../adapters/types';
 import type { FactExtractor } from './extractor';
 export interface LLMFactExtractorConfig {
     /** The provider used for extraction. Typically a cheap/fast model. */

package/dist/types/memory/facts/llmFactExtractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llmFactExtractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/facts/llmFactExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAIlE,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAErE;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAiHD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,aAAa,CA+B9E"}
+{"version":3,"file":"llmFactExtractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/facts/llmFactExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAyB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAIlE,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAE/B;;;;OAIG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IAErE;;;;OAIG;IACH,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;CACxC;AAkGD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,aAAa,CA8B9E"}

package/dist/types/memory/facts/patternFactExtractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"patternFactExtractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/facts/patternFactExtractor.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAuFlE,wBAAgB,oBAAoB,IAAI,aAAa,CAmCpD"}
+{"version":3,"file":"patternFactExtractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/facts/patternFactExtractor.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AA2ElE,wBAAgB,oBAAoB,IAAI,aAAa,CAmCpD"}