agentfootprint 1.22.0 → 2.0.1

package/dist/types/lib/injection-engine/types.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Injection Engine — types.
+ *
+ * THE primitive that unifies every form of context engineering in the
+ * library. Skills, Steering docs, Instructions, RAG, Memory, custom
+ * Context — all reduce to one shape: an `Injection` with a `trigger`
+ * (when), `inject` (what — one or more slot targets), and a `flavor`
+ * (observability tag).
+ *
+ * Pattern: Strategy (GoF) — each Injection's trigger is a strategy for
+ *          "should I activate this iteration?". Each Injection's
+ *          `inject` is the Memento (GoF) carrying content to slots.
+ * Role:    Layer-3 context engineering primitive in the stack.
+ *          Sits below the slot subflows.
+ * Emits:   Engine emits `agentfootprint.context.evaluated` once per
+ *          iteration. Slot subflows emit `agentfootprint.context.injected`
+ *          for each InjectionRecord they place.
+ */
+import type { Tool } from '../../core/tools.js';
+import type { ContextRole, ContextSource } from '../../events/types.js';
+/**
+ * Discriminated union — exactly one of four kinds. Adding a new
+ * trigger kind is one new variant; engine evaluator + Lens chip
+ * naturally extend.
+ */
+export type InjectionTrigger = 
+/** Always-on. Used for steering-doc-style injections. */
+{
+    readonly kind: 'always';
+}
+/** Predicate runs once per iteration. Most flexible. */
+ | {
+    readonly kind: 'rule';
+    readonly activeWhen: (ctx: InjectionContext) => boolean;
+}
+/** Activates after a specific tool returns. The "Dynamic ReAct" flavor —
+ *  tool results steer the next iteration's prompt. `toolName` matches
+ *  literally (string) or by regex. */
+ | {
+    readonly kind: 'on-tool-return';
+    readonly toolName: string | RegExp;
+}
+/** Activates when the LLM calls a designated tool. The "Skill" flavor:
+ *  `read_skill('billing')` activates the billing Skill for the next
+ *  iteration. */
+ | {
+    readonly kind: 'llm-activated';
+    readonly viaToolName: string;
+};
+/**
+ * Multi-slot per Injection. A Skill for example targets BOTH
+ * system-prompt (the body) AND tools (the unlocked capabilities)
+ * in one Injection. Lens displays the same Injection chip across
+ * each slot it lands in.
+ */
+export interface InjectionContent {
+    /** Text appended to the system-prompt slot when active. */
+    readonly systemPrompt?: string;
+    /** Messages prepended to the messages slot when active. */
+    readonly messages?: ReadonlyArray<{
+        readonly role: ContextRole;
+        readonly content: string;
+    }>;
+    /** Tools added to the tools slot when active. */
+    readonly tools?: readonly Tool[];
+}
+/**
+ * Context passed to `rule` predicates. Read-only snapshot of the
+ * agent's iteration state. Internal mutable state is hidden.
+ */
+export interface InjectionContext {
+    /** Current ReAct iteration (1-based). */
+    readonly iteration: number;
+    /** The current user message that started this turn. */
+    readonly userMessage: string;
+    /**
+     * Conversation history up to (but not including) the current
+     * iteration's LLM call. Includes prior iterations within the same turn.
+     */
+    readonly history: ReadonlyArray<{
+        readonly role: ContextRole;
+        readonly content: string;
+        readonly toolName?: string;
+    }>;
+    /**
+     * The most recent tool result, if the previous iteration ended in a
+     * tool call. Used both by `rule` predicates and by `on-tool-return`
+     * trigger evaluation.
+     */
+    readonly lastToolResult?: {
+        readonly toolName: string;
+        readonly result: string;
+    };
+    /**
+     * IDs of LLM-activated injections that the LLM has activated this
+     * turn (via their `viaToolName` tool call). Engine includes them
+     * in the active set on subsequent iterations until turn end.
+     */
+    readonly activatedInjectionIds: readonly string[];
+}
+/**
+ * THE primitive. Five fields. Four trigger kinds. Three slot targets.
+ *
+ * Every named flavor (Skill, Steering, Instruction, Context, RAG,
+ * Memory, Guardrail, …) is a sugar factory that produces one of these.
+ *
+ * @example
+ *   // Direct construction (power user)
+ *   const myInjection: Injection = {
+ *     id: 'demo',
+ *     flavor: 'instructions',
+ *     trigger: { kind: 'rule', activeWhen: (ctx) => ctx.iteration > 1 },
+ *     inject: { systemPrompt: 'Refine the previous answer.' },
+ *   };
+ *
+ *   // Sugar (recommended)
+ *   const myInjection2 = defineInstruction({
+ *     id: 'demo',
+ *     activeWhen: (ctx) => ctx.iteration > 1,
+ *     prompt: 'Refine the previous answer.',
+ *   });
+ */
+export interface Injection {
+    /** Unique id. Used for observability + de-duplication + LLM-activation lookup. */
+    readonly id: string;
+    /** Human-readable description (Lens / docs / debug). */
+    readonly description?: string;
+    /** Observability tag. Drives Lens chip color + ContextRecorder source field. */
+    readonly flavor: ContextSource;
+    /** WHEN to activate. */
+    readonly trigger: InjectionTrigger;
+    /** WHAT to contribute (one or more slots). */
+    readonly inject: InjectionContent;
+}
+/**
+ * Returned by `evaluateInjections()`. Slot subflows consume `active`;
+ * `skipped` is observability metadata (predicate errors).
+ */
+export interface InjectionEvaluation {
+    readonly active: readonly Injection[];
+    readonly skipped: ReadonlyArray<{
+        readonly id: string;
+        readonly reason: 'predicate-threw' | 'unknown-trigger-kind';
+        readonly error?: string;
+    }>;
+}
+/**
+ * POJO projection of an active Injection — flows through footprintjs
+ * scope (which cannot serialize functions) so that slot subflows can
+ * read it across the subflow boundary.
+ *
+ * Drops the `trigger` (already evaluated) and projects `inject.tools`
+ * to schemas only (the Tool's `execute` function lives on the Agent's
+ * closure-held registry, looked up by injection id at exec time).
+ */
+export interface ActiveInjection {
+    readonly id: string;
+    readonly flavor: import('../../events/types.js').ContextSource;
+    readonly description?: string;
+    readonly inject: {
+        readonly systemPrompt?: string;
+        readonly messages?: ReadonlyArray<{
+            readonly role: import('../../events/types.js').ContextRole;
+            readonly content: string;
+        }>;
+        /** Tool schemas only — `execute` lives on Agent's closure registry. */
+        readonly tools?: ReadonlyArray<{
+            readonly schema: import('../../adapters/types.js').LLMToolSchema;
+            readonly injectionId: string;
+        }>;
+    };
+}
+/** Project a full Injection (with functions) into a scope-safe POJO. */
+export declare function projectActiveInjection(inj: Injection): ActiveInjection;
+//# sourceMappingURL=types.d.ts.map

package/dist/types/lib/injection-engine/types.d.ts.map

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

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

@@ -18,7 +18,7 @@
  * rules-based extractor for a specific domain, or a hybrid that
  * combines heuristics with LLM rescoring.
  */
-import type { Message } from '../../types/messages';
+import type { LLMMessage as Message } from '../../adapters/types';
 import type { NarrativeBeat } from './types';
 export interface ExtractArgs {
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/beats/extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;CAC/D"}
+{"version":3,"file":"extractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/beats/extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EAAE,UAAU,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;IAEtC;;;OAGG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;CAC/D"}

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

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

package/dist/types/memory/beats/llmExtractor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llmExtractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/beats/llmExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAW,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,aAAa,CAAC;AAI9D,MAAM,WAAW,kBAAkB;IACjC,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;CACtE;AA4FD,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,aAAa,CA4BtE"}
+{"version":3,"file":"llmExtractor.d.ts","sourceRoot":"","sources":["../../../../src/memory/beats/llmExtractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,KAAK,EAAE,WAAW,EAAyB,MAAM,sBAAsB,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,aAAa,CAAC;AAI9D,MAAM,WAAW,kBAAkB;IACjC,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;CACtE;AA6ED,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,GAAG,aAAa,CA2BtE"}

package/dist/types/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 { writeSnapshot, type WriteSnapshotConfig } from './writeSnapshot.js';
+export { loadSnapshot, type LoadSnapshotConfig } from './loadSnapshot.js';
+export { snapshotPipeline, type SnapshotPipelineConfig } from './snapshotPipeline.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/memory/causal/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,aAAa,EACb,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,+BAA+B,EAAE,MAAM,YAAY,CAAC;AAE7D,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC"}

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

@@ -0,0 +1,52 @@
+/**
+ * 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. Aligns with the LLM-systems panel verdict in the design.
+ *
+ * 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>;
+//# sourceMappingURL=loadSnapshot.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"loadSnapshot.d.ts","sourceRoot":"","sources":["../../../../src/memory/causal/loadSnapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;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;AAEtD,OAAO,EAAwB,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,WAAW,kBAAkB;IACjC,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B,mEAAmE;IACnE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAEzC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK,MAAM,CAAC;CACjE;AAaD,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB,WAahC,WAAW,WAAW,CAAC,KAAG,QAAQ,IAAI,CAAC,CA+B7D"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"snapshotPipeline.d.ts","sourceRoot":"","sources":["../../../../src/memory/causal/snapshotPipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAK7D,MAAM,WAAW,sBAAsB;IACrC,yEAAyE;IACzE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAE5B,sEAAsE;IACtE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAE7B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B,8DAA8D;IAC9D,QAAQ,CAAC,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAEzC,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;CACzC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,GAAG,cAAc,CAkC/E"}

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"}