agentfootprint 1.23.0 → 2.1.0

package/README.md

@@ -1,333 +1,300 @@
 <p align="center">
-  <h1 align="center">AGENT FOOTPRINT</h1>
+  <h1 align="center">AgentFootPrint</h1>
   <p align="center">
-    <strong>The explainable agent framework</strong>
+    <strong>Context engineering, made buildable.</strong>
   </p>
 </p>
 
 <p align="center">
   <a href="https://github.com/footprintjs/agentfootprint/actions"><img src="https://github.com/footprintjs/agentfootprint/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/v/agentfootprint.svg?style=flat" alt="npm version"></a>
-  <a href="https://img.shields.io/npm/dm/agentfootprint.svg"><img src="https://img.shields.io/npm/dm/agentfootprint.svg" alt="Downloads"></a>
   <a href="https://github.com/footprintjs/agentfootprint/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License"></a>
-  <br>
+  <a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/dm/agentfootprint.svg" alt="Downloads"></a>
   <a href="https://footprintjs.github.io/agentfootprint/"><img src="https://img.shields.io/badge/Docs-agentfootprint-facc15?style=flat&logo=typescript&logoColor=white" alt="Docs"></a>
-  <a href="https://footprintjs.github.io/agent-playground/"><img src="https://img.shields.io/badge/Playground-Live_Demo-facc15?style=flat" alt="Playground"></a>
-  <a href="https://footprintjs.github.io/footPrint/"><img src="https://img.shields.io/badge/Built_on-footprintjs-ca8a04?style=flat" alt="Built on footprintjs"></a>
+  <a href="https://github.com/footprintjs/footPrint"><img src="https://img.shields.io/badge/Built_on-footprintjs-ca8a04?style=flat" alt="Built on footprintjs"></a>
 </p>
 
-> **Most agent frameworks invent new class names for every paper. agentfootprint gives you 2 primitives, 3 compositions, and makes every other "feature" explicit about what it injects into the Agent's prompt.** Context engineering, visible. Students and engineers can read any agent paper and see it in agentfootprint terms.
+<br>
+
+**Building Generative AI applications is mostly *context engineering*** &mdash; deciding *what content lands in which slot of the LLM call, when, and why*. agentfootprint gives you a framework to build generative AI apps — single LLM calls, agents, multi-agent systems — where this discipline is **buildable at the control-flow level** (Sequence, Parallel, Conditional, Loop), not hidden inside new classes per paper.
 
 ```bash
-npm install agentfootprint
+npm install agentfootprint footprintjs
 ```
 
 ```typescript
-import { Agent, defineTool } from 'agentfootprint';              // Build agents
-import { mock, anthropic } from 'agentfootprint/providers';      // Connect providers
-import { defineInstruction } from 'agentfootprint/instructions'; // Conditional behavior
-import { agentObservability } from 'agentfootprint/observe';     // Observability
-import { withRetry } from 'agentfootprint/resilience';           // Reliability
-import { gatedTools } from 'agentfootprint/security';            // Tool safety
-import { ExplainRecorder } from 'agentfootprint/explain';        // Grounding analysis
-import { SSEFormatter } from 'agentfootprint/stream';            // Real-time events
+const agent = Agent.create({ provider: anthropic(...) })
+  .steering(tone)              // always-on persona
+  .instruction(urgentRule)     // rule-gated, fires when matched
+  .skill(billingSkill)         // LLM-activated body + tools
+  .memory(causalMemory)        // cross-run "why" replay
+  .build();
 ```
 
 ---
 
-## The Mental Model — 2 Primitives + 3 Compositions + N Patterns
+## What is context engineering?
 
-Everything in agentfootprint is expressible in five building blocks. Named patterns (ReAct, Swarm, Reflexion, Tree-of-Thoughts, Plan-Execute...) are recipes that combine them — not new classes.
+Every LLM call has **three slots**:
 
-```typescript
-import { Agent, defineTool } from 'agentfootprint';
-import { mock } from 'agentfootprint/providers';
-import { agentObservability } from 'agentfootprint/observe';
-
-const obs = agentObservability();
-const agent = Agent.create({ provider: mock([...]) })
-  .system('You are a research assistant.')
-  .tool(searchTool)
-  .recorder(obs)
-  .build();
-
-const result = await agent.run('Find AI trends');
-console.log(result.content);              // LLM response
-console.log(obs.explain().iterations);    // per-iteration evaluation data ← the differentiator
+```
+┌──────────────────────────────────────────────────────────────┐
+│  ┌─────────────────────┐  ┌──────────────┐  ┌────────────┐   │
+│  │  system-prompt slot │  │ messages slot│  │ tools slot │   │
+│  │  (instructions,     │  │ (history,    │  │ (functions │   │
+│  │   persona, rules)   │  │  user input, │  │  the LLM   │   │
+│  │                     │  │  tool results)│ │  may call) │   │
+│  └─────────────────────┘  └──────────────┘  └────────────┘   │
+└──────────────────────────────────────────────────────────────┘
 ```
 
-**Primitives — atomic invocation units:**
-
-| # | Primitive | What it is | Use case |
-|---|-----------|------------|----------|
-| 1 | **LLM** | One call in, one response out | Summarization, classification, extraction |
-| 2 | **Agent** | A loop of (think → tool → think) — **Agent = ReAct** | Research, code generation, anything iterative |
-
-**Compositions — how primitives arrange:**
+Context engineering is **deciding what flows into each slot, when**. The same content can be a *Skill* (LLM activates it), a *Steering* doc (always-on), an *Instruction* (rule-gated), a *Fact* (developer-supplied data), or a *Memory* (learned across runs). They're flavors of the same idea: **injection into a slot at the right moment**.
 
-| # | Composition | What it is | Use case |
-|---|-------------|------------|----------|
-| 1 | **Sequence** | One after another | Approval flows, ETL — output of one feeds the next |
-| 2 | **Parallel** | At the same time | Analysis from multiple perspectives — merged by LLM |
-| 3 | **Conditional** | Branch on a decider | Triage flows, deterministic routing |
+| Flavor | Slot | When it injects |
+|---|---|---|
+| **Skill** | system-prompt + tools | When the LLM calls `read_skill('billing')` |
+| **Steering** | system-prompt | Always-on (persona, output format, safety) |
+| **Instruction** | system-prompt or messages | Rule-gated (predicate matches the turn / a tool just returned) |
+| **Fact** | system-prompt or messages | Always-on, but data &mdash; user profile, env, current time |
+| **Memory** | messages | Learned across runs &mdash; window / facts / narrative / **causal snapshots** |
+| **RAG** | messages | Retrieved chunks (rule + score threshold) |
 
-**Patterns — named configurations of the above:**
+You're not learning N new framework classes &mdash; you're learning **one model**: slot &times; flavor &times; timing.
 
-| Pattern | Built from | Source |
-|---------|-----------|--------|
-| **ReAct** | Agent (default) | Yao 2022 |
-| **Dynamic ReAct** | Agent with per-iteration context re-evaluation | agentfootprint extension |
-| **Hierarchy (Swarm)** | Agent routing to specialist-Agents via tools | OpenAI 2024 |
-| **Reflexion** | Sequence(Agent, LLM-critique, Agent) | Shinn 2023 |
-| **Tree-of-Thoughts** | Parallel(Agent × N) + LLM-rank | Yao 2023 |
-| **Plan-Execute** | LLM-plan + Sequence(Agent per step) | Wang 2023 |
-| **Map-Reduce** | Parallel(Agent × N) + LLM-merge | Dean 2004 applied to LLMs |
+---
 
-**Context Engineering — cross-cutting, applies to any Agent:**
+## Where do you inject?
 
-What you inject into the Agent's slots. This is the library's teaching thesis — every "new agent feature" that competing frameworks wrap in new classes is just **content flowing into one of three slots**.
+Into the three slots of the LLM API call:
 
-| Mechanism | Target slot | What it does |
-|-----------|-------------|--------------|
-| **RAG** | messages | Retrieved chunks injected into the prompt |
-| **Memory** | messages | Prior-turn context re-injected |
-| **Skills** | system-prompt (+ tools) | Activate a skill → its prompt + tools become visible |
-| **Instructions** | system-prompt | Per-tool guidance injected after specific tool results |
-| **Tools** | tools slot | Available functions the LLM can call |
-| **Grounding** | system-prompt | Style guides, rules, non-negotiables |
+| LLM API field | Holds | Examples of what you'd inject here |
+|---|---|---|
+| **`system` prompt** | Persona, rules, available capabilities | Steering doc · Instruction text · Skill body · Fact data · formatted memory |
+| **`messages` array** | Conversation turns + tool results | Memory replay · RAG chunks · synthetic tool results · injected instructions on a recent turn |
+| **`tools` array** | Function schemas the LLM may call | Skill-attached tools · permission-gated subset · per-iteration dynamic registry |
 
-**Every runner** (LLMCall, Agent, Sequence/FlowChart, Parallel, Conditional, Swarm) shares one interface: `.build()` → `.run()`, `.observe(h)`, `.getNarrativeEntries()`, `.getSnapshot()`, `.getSpec()`.
+Every injection — Skill, Steering, Instruction, Fact, Memory, RAG, Guardrail — lands in **one of these three places**. There is no fourth slot.
 
----
+## When (and how) do we inject?
 
-## Architecture — 5 Layers
+Context engineering happens at runtime. Three timing levels of expressiveness:
 
 ```
-Layer 1: BUILD          → concepts/     Single LLM (LLMCall, Agent, RAG)
-                                         Multi-Agent (FlowChart, Parallel, Swarm)
-                          tools/         defineTool, ToolRegistry, askHuman
-
-Layer 2: COMPOSE        → lib/loop/     buildAgentLoop — the ReAct engine
-                          lib/slots/    SystemPrompt, Messages, Tools subflows
-
-Layer 3: EVALUATE       → recorders/    ExplainRecorder — per-iteration evaluation
-                          explain       obs.explain() → { iterations, sources, claims, context }
-
-Layer 4: MONITOR        → recorders/    TokenRecorder, CostRecorder, ToolUsageRecorder
-                          streaming/    AgentStreamEvent, SSEFormatter
-                          narrative     Human-readable execution story (footprintjs)
-
-Layer 5: INFRASTRUCTURE → adapters/     Anthropic, OpenAI, Bedrock, Mock, MCP, A2A
-                          providers/    Prompt, Message, Tool strategies
-                          memory/       Conversation stores (Redis, Postgres, DynamoDB)
+1.  LLMCall                  ← one-shot. Inject once before the call.
+       ↓
+2.  Agent (ReAct loop)       ← inject before EVERY iteration.
+       ↓
+3.  Dynamic Agent            ← inject DIFFERENTLY per iteration based on
+                                tool results, reasoning state, or user input.
 ```
 
-Each folder has a README. Start at Layer 1, add layers as you need them.
+The third level is where context engineering pays off. The agent calls a `redact_pii` tool → on the *next* iteration, an Instruction with `trigger: 'on-tool-return'` fires that says *"use the redacted text only, don't paraphrase the original"*. That kind of just-in-time injection is what separates an LLM that follows the rules from one that drifts.
 
-Built on [footprintjs](https://github.com/footprintjs/footPrint) — the flowchart pattern for backend code. One DFS traversal, three observer systems (scope/flow/agent), connected data out.
+agentfootprint handles all three timing levels through the **same** primitive (`Injection`), evaluated by the **same** engine, observed by the **same** event (`agentfootprint.context.injected`).
 
 ---
 
-## What's Different
+## Building a generative app = deciding when/how to inject
 
-Features no other agent framework provides — and why they matter.
+That's the discipline. agentfootprint abstracts it for you in two layers, both built on the [footprintjs](https://github.com/footprintjs/footPrint) flowchart substrate:
 
-**Quality:**
+### Layer 1 — Single agent: one `Injection` primitive
 
-| Feature | What |
-|---------|------|
-| **Dynamic ReAct** | All 3 slots (prompt, tools, messages) re-evaluate EACH loop iteration. Agent adapts mid-conversation. |
-| **Conditional Behavior** | `defineInstruction({ activeWhen })` — rules activate based on accumulated decision state. |
-| **Tool Result Recency** | Instructions inject into the recency window AFTER tool calls — guidance at the right moment. |
-| **Per-Iteration Evaluation** | `obs.explain().iterations` — context + decisions + sources + claims connected per loop. |
+For ONE agent, every Skill / Steering / Instruction / Fact / Memory / RAG is the same `Injection` primitive: *"this content lands in this slot when this trigger matches."* You define them; the engine evaluates them per iteration; observability flows through one event.
 
-**Safety & Cost:**
+```
+Agent  ─►  InjectionEngine  ─►  ┌─ system-prompt slot ─► CallLLM ─► Tools ─► loop
+                                  ├─ messages slot
+                                  └─ tools slot
+```
 
-| Feature | What |
-|---------|------|
-| **Permission-Gated Tools** | LLM never SEES blocked tools — filtered at resolve time. Can't hallucinate a tool it never saw. |
-| **$0 Testing** | `mock()` adapter — same interface as Anthropic/OpenAI. Full test suite, zero API spend. |
+### Layer 2 — Multi-agent: connect agents through control flow
 
-**UX & Debugging:**
+For MULTIPLE agents, you don't need a new primitive. Connect them with the same control-flow building blocks that connect any flowchart stages:
 
-| Feature | What |
-|---------|------|
-| **Human-in-the-Loop** | Agent pauses, serializes to JSON, resumes hours later on a different server. `askHuman()`. |
-| **Streaming Events** | 9-event discriminated union. Build React/Next.js real-time UI. SSEFormatter for SSE. |
-| **Narrative Traces** | Human-readable execution story a follow-up LLM can reason about. |
-| **Single Traversal** | 3 observer systems fire during ONE DFS pass → all data connected. No post-processing. |
+| Composition | What it does | Multi-agent example |
+|---|---|---|
+| **Sequence** | A → B → C | `Sequence(Researcher, Writer, Editor)` — output flows downstream |
+| **Parallel** | fan-out, merge | `Parallel(Critic1, Critic2, Critic3) + merge` — multi-perspective review |
+| **Conditional** | predicate-based routing | route to specialist Agent based on intent classification |
+| **Loop** | repeat with budget | `Loop(Agent + judge)` — iterate until quality bar hit |
 
----
+That's it. **No `MultiAgentSystem` class. No `Orchestrator` class. No new vocabulary.** Multi-agent is just compositions of single Agents through control flow.
 
-## Adapter-Swap Testing
+### Same abstraction → native patterns
 
-Write tests with `mock()`. Deploy with `anthropic()`. Same code. $0 test runs.
+Because the substrate is so small (Agent + Sequence/Parallel/Conditional/Loop), every named multi-agent pattern is just a recipe — and we ship runnable examples for the canonical ones:
 
-```typescript
-import { mock, createProvider, anthropic } from 'agentfootprint/providers';
-
-// test — deterministic, free, instant
-const provider = mock([{ content: 'Paris.' }]);
+| Pattern | Recipe | Source |
+|---|---|---|
+| **ReAct** | `Agent` with the default loop | Yao 2022 |
+| **Reflexion** | `Sequence(Agent, critique-LLM, Agent)` | Shinn 2023 |
+| **Tree-of-Thoughts** | `Parallel(Agent × N) + rank` | Yao 2023 |
+| **Self-Consistency** | `Parallel(Agent × N) + majority-vote` | Wang 2022 |
+| **Debate** | `Loop(Agent × 2 + judge)` | Du 2023 |
+| **Map-Reduce** | `Parallel(Agent × N) + merge` | Dean 2004 |
+| **Swarm** | `Agent` whose tools are other `Agent`s | OpenAI 2024 |
 
-// production — swap one line
-const provider = createProvider(anthropic('claude-sonnet-4-20250514'));
+Browse them in [`examples/patterns/`](examples/patterns/). Every file runs end-to-end with `npm run example examples/patterns/<file>.ts`. **You compose. We don't ship a `ReflexionAgent` class.**
 
-// Same agent. Same tools. Same flowchart.
-const agent = Agent.create({ provider }).system('Geography expert.').tool(searchTool).build();
-```
-
-Works with Anthropic, OpenAI, Bedrock, Ollama. No lock-in.
+> **Show me the smallest one** — [`examples/patterns/02-reflection.ts`](examples/patterns/02-reflection.ts) implements Reflexion in ~30 lines. Run it: `npm run example examples/patterns/02-reflection.ts`.
 
 ---
 
-## Features
-
-### Conditional Behavior
-
-Define rules that inject into system prompt, tools, AND tool-result recency window. Driven by accumulated state. All 3 slots re-evaluate each iteration in Dynamic mode — progressive tool authorization, context-aware prompts, state-driven behavior.
+## Why a context-engineering framework
 
-```typescript
-import { defineInstruction } from 'agentfootprint/instructions';
-import { Agent, AgentPattern } from 'agentfootprint';
-
-const refund = defineInstruction({
-  id: 'refund-handling',
-  activeWhen: (d) => d.orderStatus === 'denied',
-  prompt: 'Handle denied orders with empathy. Follow refund policy.',
-  tools: [processRefund],
-  onToolResult: [{ id: 'empathy', text: 'Do NOT promise reversal.' }],
-  safety: true,   // fail-closed: fires even when predicate throws
-});
+If you're going to build generative AI apps on a framework, pick the one whose **core stays small as the field grows**. agentfootprint's core has *one* Injection primitive. Every current flavor reduces to it &mdash; and so will every flavor that hasn't been invented yet.
 
-const agent = Agent.create({ provider })
-  .tool(lookupOrder)
-  .instruction(refund)
-  .decision({ orderStatus: null })
-  .pattern(AgentPattern.Dynamic)
-  .build();
 ```
-
-### Narrative Traces
-
-Connected entries with key, value, stageId — collected during traversal. Feed to a follow-up LLM for debugging.
-
-```typescript
-agent.getNarrative();
-// [
-//   "[Seed] Initialized agent state",
-//   "[CallLLM] claude-sonnet-4 (127in / 45out)",
-//   "[ExecuteToolCalls] lookup_order({orderId: 'ORD-1003'})",
-//   "[Finalize] Your order was denied..."
-// ]
+Skill        =  Injection { trigger: 'llm-activated', slots: [system-prompt, tools] }
+Steering     =  Injection { trigger: 'always-on',     slots: [system-prompt] }
+Instruction  =  Injection { trigger: 'rule',          slots: [system-prompt | messages] }
+Fact         =  Injection { trigger: 'always-on',     slots: [system-prompt | messages] }
+RAG          =  Injection { trigger: 'rule + score',  slots: [messages] }            (v2.1) ✓
+Guardrail    =  Injection { trigger: 'on-tool-return',slots: [system-prompt]  }      (v2.x)
+???          =  Injection { trigger: ?,               slots: ? }                    (your idea)
 ```
 
-### Human-in-the-Loop
+Adding the next flavor is **one new factory file** &mdash; no engine change, no slot subflow change, no consumer-API change. Lens chips, observability events, audit trails all flow through the same plumbing.
 
-Agent pauses, serializes state to JSON, resumes hours later on a different server.
+| | Frameworks growing class-per-paper | agentfootprint |
+|---|---|---|
+| Adding a new flavor (e.g. *guardrail*) | New `GuardrailAgent` class, new event type, new UI surface | One factory file, same `Injection` shape, same `context.injected` event |
+| Cross-run "why was X rejected?" | LLM reconstructs from messages | Replay EXACT past decisions from causal snapshots |
+| Training-data export | Manual, lossy, optional | Same snapshot shape → SFT / DPO / process-RL ready (v2.1+) |
+| Decision evidence | Lost &mdash; only the final answer survives | First-class events from `decide()` / `select()` captured during traversal |
 
-```typescript
-import { Agent, askHuman } from 'agentfootprint';
-
-const agent = Agent.create({ provider })
-  .tool(askHuman())
-  .build();
-
-const result = await agent.run('Process my refund');
-if (result.paused) {
-  const checkpoint = result.pauseData;   // store in Redis/Postgres/anywhere
-  const final = await agent.resume(humanResponse);  // hours later, different server
-}
-```
-
-### Streaming Events
+---
 
-9-event discriminated union. Build any UX — CLI, web, mobile.
+## Quick Start
 
 ```typescript
-await agent.run('Check order', {
-  onEvent: (event) => {
-    switch (event.type) {
-      case 'token':      process.stdout.write(event.content); break;
-      case 'tool_start': console.log(`Running ${event.toolName}...`); break;
-      case 'tool_end':   console.log(`Done (${event.latencyMs}ms)`); break;
-    }
+import {
+  Agent, defineTool, defineSteering, defineInstruction,
+  defineMemory, MEMORY_TYPES, MEMORY_STRATEGIES,
+  InMemoryStore, anthropic,
+} from 'agentfootprint';
+
+// Want $0 testing? Swap `anthropic({...})` for `mock({ reply: '...' })`
+// — same agent, same flowchart, no API key needed.
+
+// 1. A tool the agent can call
+const weather = defineTool({
+  schema: {
+    name: 'weather',
+    description: 'Current weather for a city.',
+    inputSchema: {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city'],
+    },
   },
+  execute: async (args) => `${(args as { city: string }).city}: 72°F, sunny`,
 });
-```
-
-Events: `turn_start` · `llm_start` · `thinking` · `token` · `llm_end` · `tool_start` · `tool_end` · `turn_end` · `error`
 
-### Observability
+// 2. Context engineering: one steering doc + one rule-gated instruction
+const tone = defineSteering({
+  id: 'tone',
+  prompt: 'Be friendly and concise. Acknowledge feelings before facts.',
+});
 
-One call for everything. Collect during traversal, never post-process.
+const urgent = defineInstruction({
+  id: 'urgent',
+  activeWhen: (ctx) => /urgent|asap|emergency/i.test(ctx.userMessage),
+  prompt: 'The user marked this urgent. Prioritize the fastest resolution.',
+});
 
-```typescript
-import { agentObservability } from 'agentfootprint/observe';
+// 3. Memory across runs
+const memory = defineMemory({
+  id: 'short-term',
+  type: MEMORY_TYPES.EPISODIC,
+  strategy: { kind: MEMORY_STRATEGIES.WINDOW, size: 10 },
+  store: new InMemoryStore(),
+});
 
-const obs = agentObservability();
-agent.recorder(obs).build();
-await agent.run('Hello');
+// 4. Build — every layer composes
+const agent = Agent.create({
+  provider: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY! }),
+  model: 'claude-sonnet-4-5-20250929',
+})
+  .system('You are a helpful weather assistant.')
+  .tool(weather)
+  .steering(tone)
+  .instruction(urgent)
+  .memory(memory)
+  .build();
 
-obs.tokens();   // metrics: { totalCalls, totalInputTokens, totalOutputTokens, calls[] }
-obs.tools();    // metrics: { totalCalls, byTool: { search: { calls, errors, latency } } }
-obs.cost();     // metrics: USD amount
-obs.explain();  // evaluation: { iterations, sources, claims, decisions, context }
+// 5. Run with multi-tenant identity
+const id = { conversationId: 'alice-session' };
+await agent.run({ message: 'Weather in SF urgently?', identity: id });
 ```
 
-| Category | Recorders | Audience |
-|----------|-----------|----------|
-| **Evaluation** | `ExplainRecorder` | LLM evaluator — faithfulness, hallucination, grounding |
-| **Metrics** | `TokenRecorder`, `CostRecorder`, `ToolUsageRecorder`, `TurnRecorder` | Ops dashboard, billing |
-| **Safety** | `GuardrailRecorder`, `PermissionRecorder`, `QualityRecorder` | Security, compliance |
-| **Export** | `OTelRecorder` | Datadog, Grafana, any OTel backend |
+Every `.steering` / `.instruction` / `.memory` / `.tool` call adds an injection or a binding. The Agent's flowchart shows them as visible subflows in the narrative &mdash; you can read exactly *what landed in which slot, when, and why* for any run.
 
-### Tool Gating — Defense-in-Depth
+---
 
-The LLM never sees tools it can't use. Two layers: resolve-time filtering + execute-time rejection.
+## Memory &mdash; one factory, four types, seven strategies
 
-```typescript
-import { gatedTools, PermissionPolicy } from 'agentfootprint/security';
+`defineMemory({ type, strategy, store })` &mdash; one factory dispatches `type &times; strategy.kind` onto the right pipeline.
 
-const policy = PermissionPolicy.fromRoles({
-  user: ['search', 'calc'],
-  admin: ['search', 'calc', 'delete-user'],
-}, 'user');
+| Type | What's stored |
+|---|---|
+| `EPISODIC` | Raw conversation messages |
+| `SEMANTIC` | Extracted structured facts |
+| `NARRATIVE` | Beats / summaries of prior runs |
+| **`CAUSAL`** ⭐ | **footprintjs decision-evidence snapshots** &mdash; replay "why" cross-run, zero hallucination |
 
-const agent = Agent.create({ provider })
-  .toolProvider(gatedTools(allTools, policy.checker()))
-  .build();
+| Strategy | How content is selected |
+|---|---|
+| `WINDOW` | Last N entries (rule, no LLM, no embeddings) |
+| `BUDGET` | Fit-to-tokens (decider) |
+| `SUMMARIZE` | LLM compresses older turns |
+| `TOP_K` | Score-threshold semantic retrieval |
+| `EXTRACT` | LLM distills facts/beats on write |
+| `DECAY` | Recency-weighted (planned) |
+| `HYBRID` | Compose multiple |
 
-policy.setRole('admin');  // upgrade mid-conversation
-```
+**Causal memory** is the differentiator: footprintjs's `decide()` and `select()` capture decision evidence as first-class events. Causal memory persists those snapshots tagged with the user's original query. New questions cosine-match past queries → inject the prior decision evidence → the LLM answers from EXACT past facts. Cross-run "why was X rejected last week?" follow-ups answer correctly without reconstruction.
 
-### Resilience
+The same snapshot data shape becomes RL/SFT/DPO training data in v2.1+.
 
-```typescript
-import { withRetry, withFallback, resilientProvider } from 'agentfootprint/resilience';
+---
 
-const reliable = withRetry(agent, { maxRetries: 3 });
-const resilient = withFallback(primaryAgent, cheapAgent);
-const provider = resilientProvider([anthropicAdapter, openaiAdapter, ollamaAdapter]);
-```
+## Documentation
+
+| Resource | Link |
+|---|---|
+| **Getting Started** | [Quick Start](https://footprintjs.github.io/agentfootprint/getting-started/quick-start/) &middot; [Key Concepts](https://footprintjs.github.io/agentfootprint/getting-started/key-concepts/) &middot; [Why agentfootprint?](https://footprintjs.github.io/agentfootprint/getting-started/why/) |
+| **Guides** | [Agent](https://footprintjs.github.io/agentfootprint/guides/agent/) &middot; [Memory](https://footprintjs.github.io/agentfootprint/guides/memory/) &middot; [Skills](https://footprintjs.github.io/agentfootprint/guides/skills-explained/) &middot; [Instructions](https://footprintjs.github.io/agentfootprint/guides/instructions/) &middot; [Streaming](https://footprintjs.github.io/agentfootprint/guides/streaming/) |
+| **Examples** | [33 runnable examples](https://github.com/footprintjs/agentfootprint/tree/main/examples) &mdash; primitives, compositions, patterns, context engineering, memory, runtime features |
+| **Integrations** | [Anthropic](https://footprintjs.github.io/agentfootprint/integrations/anthropic/) &middot; [OpenAI](https://footprintjs.github.io/agentfootprint/integrations/openai/) &middot; [AWS Bedrock](https://footprintjs.github.io/agentfootprint/integrations/aws-bedrock/) &middot; [Ollama](https://footprintjs.github.io/agentfootprint/integrations/ollama/) |
+| **Built on** | [footprintjs](https://github.com/footprintjs/footPrint) &mdash; the flowchart pattern for backend code |
 
 ---
 
-## Samples
-
-`test/samples/` — runnable with `vitest`:
-
-| # | Sample | What it demonstrates |
-|---|--------|---------------------|
-| 01-16 | Core patterns | LLMCall, Agent, RAG, FlowChart, Swarm, recorders, tools, security, errors, multi-modal |
-| 17 | **Conditional Behavior** | defineInstruction, decide(), conditional activation, Decision Scope |
-| 18 | **Streaming Events** | AgentStreamEvent lifecycle, tool events, SSE |
-| 19 | **Tool Gating** | gatedTools, PermissionPolicy, role-based tool access |
-| 21 | **SSE Server** | Express SSE endpoint with SSEFormatter |
-| 22 | **Resilience** | withRetry, withFallback, provider failover |
-| 23 | **Memory Stores** | redisStore, postgresStore, dynamoStore adapters |
-| 24 | **Structured Output** | outputSchema, Zod auto-convert, zodToJsonSchema |
-| 25 | **OTel** | OpenTelemetry spans with mock tracer |
-| 26 | **Explain Recorder** | ExplainRecorder: sources, claims, decisions, per-iteration eval |
+## What v2.0 ships (today)
+
+- **2 primitives** — `LLMCall`, `Agent` (ReAct loop)
+- **3 compositions + Loop** — Sequence · Parallel · Conditional · Loop
+- **6 LLM providers** — Anthropic · OpenAI · Bedrock · Ollama · Browser-Anthropic · Browser-OpenAI · Mock (for $0 testing)
+- **InjectionEngine** — one `Injection` primitive + 4 typed factories (`defineSkill` / `defineSteering` / `defineInstruction` / `defineFact`); covers Dynamic ReAct via `on-tool-return` triggers
+- **Memory subsystem** — `defineMemory` factory, 4 types (Episodic / Semantic / Narrative / **Causal** ⭐) × 7 strategies (Window / Budget / Summarize / TopK / Extract / Decay / Hybrid)
+- **Multi-agent through control flow** — no separate `MultiAgentSystem` class; agents compose via Sequence / Parallel / Conditional / Loop
+- **6 canonical patterns** runnable as examples — ReAct · Reflexion · ToT · Self-Consistency · Debate · Map-Reduce · Swarm
+- **Observability** — 47 typed events × 13 domains; recorders for context · stream · agent · cost · skill · permission · eval · memory
+- **Resilience helpers** — `withRetry`, `withFallback`, `resilientProvider`
+- **Pause / resume** — JSON-serializable checkpoints; agent can pause via `askHuman`/`pauseHere` and resume hours later on a different server
+- **AI-coding-tool support** — bundled instructions for Claude Code / Cursor / Windsurf / Cline / Kiro / Copilot
+- **33 runnable end-to-end examples** — every example is a real test exercising the documented surface
+
+## What's next
+
+| Release | Focus |
+|---|---|
+| v2.1 | RAG flavor (`defineRAG`) · Redis memory store adapter · MCP integration · CircuitBreaker as a first-class primitive · 3-tier structured-output fallback |
+| v2.2 | Governance subsystem (`Policy`, `BudgetTracker`, role-based access) · DynamoDB / Postgres / Pinecone store adapters |
+| v2.3 | Causal training-data exports — `causalMemory.exportForTraining({ format: 'sft' \| 'dpo' \| 'process' })` for HuggingFace / OpenAI / Anthropic batch fine-tune |
+| v2.4+ | Deep Agents (planning-before-execution) · A2A protocol · Lens UI deep-link |
 
 ---