audrey 0.16.1 → 0.17.0

package/README.md

@@ -1,68 +1,81 @@
 # Audrey
 
-Biological memory architecture for AI agents. Memory that decays, consolidates, feels, and learns — not just a database.
+[![CI](https://github.com/Evilander/Audrey/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/Evilander/Audrey/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/audrey.svg)](https://www.npmjs.com/package/audrey)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## Why Audrey Exists
+Persistent memory for Claude Code and AI agents. Two commands, every session remembers.
 
-Every AI memory tool today (Mem0, Zep, LangChain Memory) is a filing cabinet. Store stuff, retrieve stuff. None of them do what biological memory actually does:
+```bash
+npx audrey install          # 13 MCP memory tools
+npx audrey hooks install    # automatic memory in every session
+```
+
+That's it. Claude Code now wakes up knowing what happened yesterday, recalls relevant context per-prompt, and consolidates learnings when the session ends. No cloud, no config files, no infrastructure — one SQLite file.
+
+Audrey also works as a standalone SDK, MCP server, and REST API for any AI agent framework.
+
+> **On `/dream`** — Anthropic recently shipped `/dream` for Claude Code memory maintenance. Audrey predates it and goes further: episodic-to-semantic consolidation, contradiction detection, confidence decay, emotional affect, causal reasoning, and source reliability weighting. `/dream` is a maintenance pass. Audrey is a cognitive memory architecture.
+
+## Why Audrey
+
+Most AI memory tools are storage wrappers. They save facts, retrieve facts, and keep everything forever. That leaves real production problems unsolved:
 
-- Memories don't decay. A fact from 6 months ago has the same weight as one from today.
-- No consolidation. Raw events never become general principles.
-- No contradiction detection. Conflicting facts coexist silently.
-- No self-defense. If an agent hallucinates and encodes the hallucination, it becomes "truth."
+- Old information stays weighted like new information.
+- Raw events never become reusable operating knowledge.
+- Conflicting facts quietly coexist.
+- Model-generated mistakes can get reinforced into false "truth."
 
-Audrey fixes all of this by modeling memory the way the brain does:
+Audrey models memory as a working system instead of a filing cabinet.
 
 | Brain Structure | Audrey Component | What It Does |
 |---|---|---|
 | Hippocampus | Episodic Memory | Fast capture of raw events and observations |
 | Neocortex | Semantic Memory | Consolidated principles and patterns |
 | Cerebellum | Procedural Memory | Learned workflows and conditional behaviors |
-| Sleep Replay | Dream Cycle | Consolidates episodes into principles, applies decay |
-| Prefrontal Cortex | Validation Engine | Truth-checking, contradiction detection |
-| Amygdala | Affect System | Emotional encoding, arousal-salience coupling, mood-congruent recall |
+| Sleep Replay | Dream Cycle | Consolidates episodes into principles and applies decay |
+| Prefrontal Cortex | Validation Engine | Truth-checking and contradiction detection |
+| Amygdala | Affect System | Emotional encoding, arousal-salience coupling, and mood-congruent recall |
+
+## What You Get
+
+- Local SQLite-backed memory with `sqlite-vec`
+- MCP server for Claude Code with 13 memory tools
+- **Claude Code hooks integration** — automatic memory in every session (`npx audrey hooks install`)
+- JavaScript SDK for direct application use
+- **Git-friendly versioning** via JSON snapshots (`npx audrey snapshot` / `restore`)
+- **REST API server** - any language, any framework (`npx audrey serve`)
+- Health checks via `npx audrey status --json`
+- Benchmark harness with retrieval and lifecycle-operation tracks via `npm run bench:memory`
+- Regression gate for benchmark quality via `npm run bench:memory:check`
+- Optional local embeddings and optional hosted LLM providers
+- Strongest production fit today in financial services ops and healthcare ops
 
 ## Install
 
-### MCP Server for Claude Code (one command)
+### MCP Server for Claude Code
 
 ```bash
-npx audrey install
+npx audrey install          # Register 13 MCP memory tools
+npx audrey hooks install    # Wire automatic memory into session lifecycle
 ```
 
-That's it. Audrey auto-detects API keys from your environment:
-
-- `GOOGLE_API_KEY` or `GEMINI_API_KEY` set? Uses Gemini embeddings (3072d).
-- Neither? Runs with local embeddings (384d, MiniLM via @huggingface/transformers — zero API key, works offline).
-- `AUDREY_EMBEDDING_PROVIDER=openai` for explicit OpenAI embeddings (1536d).
-- `ANTHROPIC_API_KEY` set? Enables LLM-powered consolidation, contradiction detection, and reflection.
-
-```bash
-# Check status
-npx audrey status
-
-# Uninstall
-npx audrey uninstall
-```
+Audrey auto-detects providers from your environment:
 
-Every Claude Code session now has 13 memory tools: `memory_encode`, `memory_recall`, `memory_consolidate`, `memory_dream`, `memory_introspect`, `memory_resolve_truth`, `memory_export`, `memory_import`, `memory_forget`, `memory_decay`, `memory_status`, `memory_reflect`, `memory_greeting`.
+- `GOOGLE_API_KEY` or `GEMINI_API_KEY` -> Gemini embeddings (3072d)
+- no embedding key -> local embeddings (384d, MiniLM, offline-capable)
+- `AUDREY_EMBEDDING_PROVIDER=openai` -> explicit OpenAI embeddings (1536d)
+- `ANTHROPIC_API_KEY` -> LLM-powered consolidation, contradiction detection, and reflection
 
-### CLI Subcommands
+Quick checks:
 
 ```bash
-npx audrey install          # Register MCP server with Claude Code
-npx audrey uninstall        # Remove MCP server registration
-npx audrey status           # Show memory store health and stats
-npx audrey greeting         # Output session briefing (mood, principles, recent memories)
-npx audrey greeting "auth"  # Briefing + context-relevant memories for "auth"
-npx audrey reflect          # Reflect on conversation + dream cycle (reads turns from stdin)
-npx audrey dream            # Run consolidation + decay cycle
-npx audrey reembed          # Re-embed all memories with current provider
+npx audrey status
+npx audrey status --json
+npx audrey status --json --fail-on-unhealthy
 ```
 
-`greeting` and `reflect` are designed for Claude Code hooks — wire them into SessionStart and Stop events for automatic memory lifecycle.
-
-### SDK in Your Code
+### SDK
 
 ```bash
 npm install audrey
@@ -70,739 +83,393 @@ npm install audrey
 
 Zero external infrastructure. One SQLite file.
 
-## Usage
+## Quick Start
 
 ```js
 import { Audrey } from 'audrey';
 
-// 1. Create a brain
 const brain = new Audrey({
   dataDir: './agent-memory',
-  agent: 'my-agent',
-  embedding: { provider: 'local', dimensions: 384 },  // or 'gemini', 'openai'
+  agent: 'support-agent',
+  embedding: { provider: 'local', dimensions: 384 },
 });
 
-// 2. Encode observations — with optional emotional context
 await brain.encode({
-  content: 'Stripe API returns 429 above 100 req/s',
+  content: 'Stripe API returned 429 above 100 req/s',
   source: 'direct-observation',
   tags: ['stripe', 'rate-limit'],
+  context: { task: 'debugging', domain: 'payments' },
   affect: { valence: -0.4, arousal: 0.7, label: 'frustration' },
 });
 
-// 3. Recall what you know — mood-congruent retrieval
 const memories = await brain.recall('stripe rate limits', {
   limit: 5,
-  mood: { valence: -0.3 },  // frustrated right now? memories encoded in frustration surface first
+  context: { task: 'debugging', domain: 'payments' },
 });
 
-// 4. Filtered recall — by tag, source, or date range
-const recent = await brain.recall('stripe', {
-  tags: ['rate-limit'],
-  sources: ['direct-observation'],
-  after: '2026-02-01T00:00:00Z',
-  context: { task: 'debugging', domain: 'payments' },  // context-dependent retrieval
-});
-
-// 5. Dream — the biological sleep cycle
 const dream = await brain.dream();
-// Consolidates episodes into principles, applies forgetting curves, reports health
-
-// 6. Reflect on a conversation — form lasting memories
-const result = await brain.reflect([
-  { role: 'user', content: 'How do I handle rate limits?' },
-  { role: 'assistant', content: 'Use exponential backoff with jitter...' },
-]);
-// LLM extracts what matters, encodes it as lasting memories
-
-// 7. Session greeting — wake up with context
 const briefing = await brain.greeting({ context: 'debugging stripe' });
-// Returns mood, principles, recent memories, identity, unresolved threads
-
-// 8. Forget something
-brain.forget(memoryId);                                 // soft-delete
-brain.forget(memoryId, { purge: true });                // hard-delete
-await brain.forgetByQuery('old API endpoint', { minSimilarity: 0.9 });
-
-// 9. Check brain health
-const stats = brain.introspect();
-// { episodic: 47, semantic: 12, procedural: 3, dormant: 8, ... }
 
-// 10. Clean up
+await brain.waitForIdle();
 brain.close();
 ```
 
-### Configuration
-
-```js
-const brain = new Audrey({
-  dataDir: './audrey-data',     // SQLite database directory
-  agent: 'my-agent',           // Agent identifier
-
-  // Embedding provider (required)
-  embedding: {
-    provider: 'local',         // 'mock' (test), 'local' (384d MiniLM), 'gemini' (3072d), 'openai' (1536d)
-    dimensions: 384,           // Must match provider
-    apiKey: '...',             // Required for gemini/openai
-    device: 'gpu',             // 'gpu' or 'cpu' — for local provider only
-  },
-
-  // LLM provider (optional — enables smart consolidation + contradiction detection + reflection)
-  llm: {
-    provider: 'anthropic',     // 'mock', 'anthropic', or 'openai'
-    apiKey: '...',             // Required for anthropic/openai
-    model: 'claude-sonnet-4-6', // Optional model override
-  },
-
-  // Consolidation settings
-  consolidation: {
-    minEpisodes: 3,            // Minimum cluster size for principle extraction
-  },
-
-  // Context-dependent retrieval
-  context: {
-    enabled: true,             // Enable encoding-specificity principle
-    weight: 0.3,               // Max 30% confidence boost on full context match
-  },
-
-  // Emotional memory
-  affect: {
-    enabled: true,             // Enable affect system
-    weight: 0.2,               // Max 20% mood-congruence boost
-    arousalWeight: 0.3,        // Yerkes-Dodson arousal-salience coupling
-    resonance: {               // Detect emotional echoes across experiences
-      enabled: true,
-      k: 5,                    // How many past episodes to check
-      threshold: 0.5,          // Semantic similarity threshold
-      affectThreshold: 0.6,    // Emotional similarity threshold
-    },
-  },
-
-  // Interference-based forgetting
-  interference: {
-    enabled: true,             // New episodes suppress similar existing memories
-    weight: 0.15,              // Suppression strength
-  },
-
-  // Decay settings
-  decay: {
-    dormantThreshold: 0.1,     // Below this confidence = dormant
-  },
-});
-```
-
-**Without an LLM provider**, consolidation uses a default text-based extractor and contradiction detection is similarity-only. **With an LLM provider**, Audrey extracts real generalized principles (semantic and procedural), detects semantic contradictions, resolves context-dependent truths, and reflects on conversations to form lasting memories.
+## MCP Tools
 
-### Environment Variables (MCP Server)
+Every Claude Code session gets these tools after `npx audrey install`:
 
-| Variable | Default | Purpose |
-|---|---|---|
-| `AUDREY_DATA_DIR` | `~/.audrey/data` | SQLite database directory |
-| `AUDREY_AGENT` | `claude-code` | Agent identifier |
-| `AUDREY_EMBEDDING_PROVIDER` | auto-detect | `local`, `gemini`, `openai`, or `mock` |
-| `AUDREY_LLM_PROVIDER` | auto-detect | `anthropic`, `openai`, or `mock` |
-| `AUDREY_DEVICE` | `gpu` | Device for local embedding provider |
-| `GOOGLE_API_KEY` | — | Gemini embeddings (auto-selected when present) |
-| `ANTHROPIC_API_KEY` | — | Anthropic LLM (consolidation, reflection, contradiction detection) |
-| `OPENAI_API_KEY` | — | OpenAI embeddings/LLM (must be explicitly selected for embeddings) |
+- `memory_encode`
+- `memory_recall`
+- `memory_consolidate`
+- `memory_dream`
+- `memory_introspect`
+- `memory_resolve_truth`
+- `memory_export`
+- `memory_import`
+- `memory_forget`
+- `memory_decay`
+- `memory_status`
+- `memory_reflect`
+- `memory_greeting`
 
-## Core Concepts
+## CLI
 
-### Four Memory Types
-
-**Episodic** (hot, fast decay) — Raw events. "Stripe returned 429 at 3pm." Immutable. Append-only. Never modified.
-
-**Semantic** (warm, slow decay) — Consolidated principles. "Stripe enforces 100 req/s rate limit." Extracted automatically from clusters of episodic memories.
-
-**Procedural** (cold, slowest decay) — Learned workflows. "When Stripe rate-limits, implement exponential backoff." Skills the agent has acquired. Routed automatically when the LLM identifies a principle as procedural.
-
-**Causal** — Why things happened. Not just "A then B" but "A caused B because of mechanism C." Prevents correlation-as-causation.
-
-### Confidence Formula
-
-Every memory has a compositional confidence score:
-
-```
-C(m, t) = w_s * S + w_e * E + w_r * R(t) + w_ret * Ret(t)
-```
-
-| Component | What It Measures | Default Weight |
-|---|---|---|
-| **S** — Source reliability | How trustworthy is the origin? | 0.30 |
-| **E** — Evidence agreement | Do observations agree or contradict? | 0.35 |
-| **R(t)** — Recency decay | How old is the memory? (Ebbinghaus curve) | 0.20 |
-| **Ret(t)** — Retrieval reinforcement | How often is this memory accessed? | 0.15 |
-
-Source reliability hierarchy:
-
-| Source Type | Reliability |
-|---|---|
-| `direct-observation` | 0.95 |
-| `told-by-user` | 0.90 |
-| `tool-result` | 0.85 |
-| `inference` | 0.60 |
-| `model-generated` | 0.40 (capped at 0.6 confidence) |
-
-The `model-generated` cap prevents circular self-confirmation — an agent can't boost its own hallucinations into high-confidence "facts."
-
-### Decay (Forgetting Curves)
-
-Unreinforced memories lose confidence over time following Ebbinghaus exponential decay:
-
-| Memory Type | Half-Life | Rationale |
-|---|---|---|
-| Episodic | 7 days | Raw events go stale fast |
-| Semantic | 30 days | Principles are hard-won |
-| Procedural | 90 days | Skills are slowest to forget |
-
-Retrieval resets the decay clock. Frequently accessed memories persist. Memories below the dormant threshold (0.1) become dormant — still searchable with `includeDormant: true`, but excluded from default recall.
-
-### Dream Cycle (The "Sleep" Cycle)
-
-`brain.dream()` runs the full biological sleep analog:
-
-1. **Consolidate** — Cluster similar episodic memories via KNN, extract principles via LLM, route to semantic or procedural tables
-2. **Decay** — Apply forgetting curves, transition low-confidence memories to dormant
-3. **Introspect** — Report memory system health
-
-The pipeline is fully transactional — if any cluster fails mid-run, all writes roll back. Consolidation is idempotent. Re-running on the same data produces no duplicates.
-
-### Consolidation Routing
-
-When the LLM extracts a principle, it classifies it:
-
-- `type: 'semantic'` → goes to the `semantics` table (general knowledge)
-- `type: 'procedural'` → goes to the `procedures` table with `trigger_conditions` (actionable skills)
+```bash
+# Setup
+npx audrey install              # Register MCP server with Claude Code
+npx audrey uninstall            # Remove MCP server registration
+npx audrey hooks install        # Wire Audrey into Claude Code hooks (automatic memory)
+npx audrey hooks uninstall      # Remove Audrey hooks
 
-### Contradiction Handling
+# Health and monitoring
+npx audrey status               # Human-readable health report
+npx audrey status --json        # Machine-readable health output
+npx audrey status --json --fail-on-unhealthy  # CI gate
 
-When memories conflict, Audrey doesn't force a winner. Contradictions have a lifecycle:
+# Session lifecycle (used by hooks automatically)
+npx audrey greeting             # Load identity, principles, mood
+npx audrey greeting "auth"      # With context-aware recall
+npx audrey recall "query"       # Semantic memory search (returns hook-compatible JSON)
+npx audrey reflect              # Consolidate learnings from stdin conversation + dream
 
-```
-open -> resolved | context_dependent | reopened
-```
+# Maintenance
+npx audrey dream                # Full consolidation + decay cycle
+npx audrey reembed              # Re-embed all memories after provider/dimension change
 
-Context-dependent truths are modeled explicitly:
+# Versioning
+npx audrey snapshot             # Export memories to timestamped JSON file
+npx audrey snapshot backup.json # Export to specific file
+npx audrey restore backup.json  # Restore from snapshot (re-embeds with current provider)
+npx audrey restore backup.json --force  # Overwrite existing memories
 
-```js
-// "Stripe rate limit is 100 req/s" (live keys)
-// "Stripe rate limit is 25 req/s" (test keys)
-// Both true — under different conditions
+# REST API server
+npx audrey serve                # Start HTTP server on port 3487
+npx audrey serve 8080           # Custom port
 ```
 
-New high-confidence evidence can reopen resolved disputes.
-
-### Forget and Purge
-
-Memories can be explicitly forgotten — by ID or by semantic query:
-
-**Soft-delete** (default) — Marks the memory as forgotten/superseded and removes its vector index. The record stays in the database but is excluded from recall. Reversible via direct database access.
-
-**Hard-delete** (`purge: true`) — Permanently removes the memory from both the main table and the vector index. Irreversible.
-
-**Bulk purge** — Removes all forgotten, dormant, superseded, and rolled-back memories in one operation. Useful for GDPR compliance or storage cleanup.
-
-### Rollback
+## Hooks Integration
 
-Bad consolidation? Undo it:
+Audrey integrates directly into Claude Code's hook lifecycle for automatic, zero-config memory in every session:
 
-```js
-const history = brain.consolidationHistory();
-brain.rollback(history[0].id);
-// Semantic memories -> rolled_back state
-// Source episodes -> un-consolidated
-// Full audit trail preserved
+```bash
+npx audrey hooks install
 ```
 
-### Circular Self-Confirmation Defense
-
-The most dangerous exploit in AI memory: agent hallucinates X, encodes it, later retrieves it, "reinforcement" boosts confidence, X eventually consolidates as "established truth."
-
-Audrey's defenses:
-
-1. **Source diversity requirement** — Consolidation requires evidence from 2+ distinct source types
-2. **Model-generated cap** — Memories from `model-generated` sources are capped at 0.6 confidence
-3. **Source lineage tracking** — Provenance chains detect when all evidence traces back to a single inference
-4. **Source diversity score** — Every semantic memory tracks how many different source types contributed
-
-## API Reference
+This configures four hooks in `~/.claude/settings.json`:
 
-### `new Audrey(config)`
+| Hook Event | Command | What Happens |
+|---|---|---|
+| **SessionStart** | `npx audrey greeting` | Loads identity, learned principles, current mood, and recent memories |
+| **UserPromptSubmit** | `npx audrey recall` | Semantic search on every prompt — injects relevant memories as context |
+| **Stop** | `npx audrey reflect` | Extracts lasting learnings from the conversation, then runs a dream cycle |
+| **PostCompact** | `npx audrey greeting` | Re-injects critical memories after context window compaction |
 
-See [Configuration](#configuration) above for all options.
+With hooks installed, Claude Code sessions automatically wake up with context, recall relevant memories per-prompt, and consolidate learnings when the session ends. No manual tool calls needed.
 
-### `brain.encode(params)` -> `Promise<string>`
+## REST API Server
 
-Encode an episodic memory. Returns the memory ID.
+Turn Audrey into an HTTP service that any language or framework can use:
 
-```js
-const id = await brain.encode({
-  content: 'What happened',          // Required. Non-empty string, max 50000 chars.
-  source: 'direct-observation',      // Required. See source types above.
-  salience: 0.8,                     // Optional. 0-1. Default: 0.5
-  causal: {                          // Optional. What caused this / what it caused.
-    trigger: 'batch-processing',
-    consequence: 'queue-backed-up',
-  },
-  tags: ['stripe', 'production'],    // Optional. Array of strings.
-  supersedes: 'previous-id',         // Optional. ID of episode this corrects.
-  context: { task: 'debugging' },    // Optional. Situational context for retrieval.
-  affect: {                          // Optional. Emotional context.
-    valence: -0.5,                   //   -1 (negative) to 1 (positive)
-    arousal: 0.7,                    //   0 (calm) to 1 (activated)
-    label: 'frustration',            //   Human-readable emotion label
-  },
-  private: true,                     // Optional. If true, excluded from public recall.
-});
+```bash
+npx audrey serve           # Start on port 3487
+npx audrey serve 8080      # Custom port
+AUDREY_API_KEY=secret npx audrey serve  # With Bearer token auth
 ```
 
-Episodes are **immutable**. Corrections create new records with `supersedes` links. The original is preserved.
+Endpoints:
 
-### `brain.encodeBatch(paramsList)` -> `Promise<string[]>`
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health` | Liveness probe |
+| `GET` | `/status` | Memory stats (introspect) |
+| `POST` | `/encode` | Store a memory (`{ content, source, tags?, context?, affect? }`) |
+| `POST` | `/recall` | Semantic search (`{ query, limit?, context? }`) |
+| `POST` | `/dream` | Full consolidation + decay cycle |
+| `POST` | `/consolidate` | Run consolidation only |
+| `POST` | `/forget` | Forget by `{ id }` or `{ query }` |
+| `POST` | `/snapshot` | Export all memories as JSON |
+| `POST` | `/restore` | Wipe and reimport from snapshot |
 
-Encode multiple episodes in one call. Same params as `encode()`, but as an array.
+Example from any language:
 
-```js
-const ids = await brain.encodeBatch([
-  { content: 'Stripe returned 429', source: 'direct-observation' },
-  { content: 'Redis timed out', source: 'tool-result' },
-  { content: 'User reports slow checkout', source: 'told-by-user' },
-]);
-```
-
-### `brain.recall(query, options)` -> `Promise<Memory[]>`
-
-Retrieve memories ranked by `similarity * confidence`.
+```bash
+# Store a memory
+curl -X POST http://localhost:3487/encode \
+  -H "Content-Type: application/json" \
+  -d '{"content": "The deploy failed due to OOM", "source": "direct-observation"}'
 
-```js
-const memories = await brain.recall('stripe rate limits', {
-  limit: 5,                       // Max results (default 10, max 50)
-  minConfidence: 0.5,             // Filter below this confidence
-  types: ['semantic'],            // Filter by memory type
-  includeProvenance: true,        // Include evidence chains
-  includeDormant: false,          // Include dormant memories
-  tags: ['rate-limit'],           // Only episodic memories with these tags
-  sources: ['direct-observation'], // Only episodic memories from these sources
-  after: '2026-02-01T00:00:00Z', // Only memories created after this date
-  before: '2026-03-01T00:00:00Z', // Only memories created before this date
-  context: { task: 'debugging' }, // Boost memories encoded in matching context
-  mood: { valence: -0.3, arousal: 0.5 }, // Mood-congruent retrieval
-});
+# Search memories
+curl -X POST http://localhost:3487/recall \
+  -H "Content-Type: application/json" \
+  -d '{"query": "deploy failures", "limit": 5}'
 ```
 
-Tag and source filters only apply to episodic memories (semantic and procedural memories don't have tags or sources). Date filters apply to all memory types. Recall gracefully degrades — if one memory type's vector search fails, the others still return results.
-
-Each result:
-
-```js
-{
-  id: '01ABC...',
-  content: 'Stripe enforces ~100 req/s rate limit',
-  type: 'semantic',
-  confidence: 0.87,
-  score: 0.74,          // similarity * confidence
-  source: 'consolidation',
-  state: 'active',
-  contextMatch: 0.8,   // When retrieval context provided
-  moodCongruence: 0.7, // When mood provided
-  provenance: {         // When includeProvenance: true
-    evidenceEpisodeIds: ['01XYZ...', '01DEF...'],
-    evidenceCount: 3,
-    supportingCount: 3,
-    contradictingCount: 0,
-  },
-}
-```
+## Versioning
 
-Retrieval automatically reinforces matched memories (boosts confidence, resets decay clock).
+Audrey stores memories in SQLite with WAL mode, which isn't git-friendly. Instead, use JSON snapshots:
 
-### `brain.recallStream(query, options)` -> `AsyncGenerator<Memory>`
+```bash
+# Save a checkpoint
+npx audrey snapshot
 
-Streaming version of `recall()`. Yields results one at a time. Supports early `break`. Same options as `recall()`.
+# Commit it
+git add audrey-snapshot-*.json && git commit -m "memory checkpoint"
 
-```js
-for await (const memory of brain.recallStream('stripe issues', { limit: 10 })) {
-  console.log(memory.content, memory.score);
-  if (memory.score > 0.9) break;
-}
+# Restore on another machine or after a reset
+npx audrey restore audrey-snapshot-2026-03-24_15-30-00.json
 ```
 
-### `brain.dream(options)` -> `Promise<DreamResult>`
+Snapshots are human-readable, diffable, and provider-agnostic. Embeddings are re-generated on import, so you can switch providers (e.g., local to Gemini) and restore seamlessly.
 
-Run the full biological sleep cycle: consolidate + decay + introspect.
+## Production Fit
 
-```js
-const result = await brain.dream({
-  minClusterSize: 3,           // Min episodes per cluster
-  similarityThreshold: 0.85,   // KNN clustering threshold
-  dormantThreshold: 0.1,       // Below this = dormant
-});
-// {
-//   consolidation: { episodesEvaluated, clustersFound, principlesExtracted, semanticsCreated, proceduresCreated },
-//   decay: { totalEvaluated, transitionedToDormant },
-//   stats: { episodic, semantic, procedural, ... },
-// }
-```
+Audrey is strongest today in workflows where memory must stay local, reviewable, and durable:
 
-### `brain.reflect(turns)` -> `Promise<ReflectResult>`
+- **Financial services operations**: payments ops, fraud and dispute workflows, KYC/KYB review, internal policy assistants
+- **Healthcare operations**: care coordination, prior-auth workflows, intake and referral routing, internal staff knowledge assistants
 
-Feed a conversation to the LLM and extract lasting memories. Requires an LLM provider.
+Audrey is a memory layer, not a compliance boundary. For regulated environments, pair it with application-level access control, encryption, retention, audit logging, and data-minimization rules.
 
-```js
-const result = await brain.reflect([
-  { role: 'user', content: 'How do I handle rate limits?' },
-  { role: 'assistant', content: 'Use exponential backoff...' },
-]);
-// { encoded: 2, memories: [...] }
-```
+Production guide: [docs/production-readiness.md](docs/production-readiness.md)
 
-### `brain.greeting(options)` -> `Promise<GreetingResult>`
+Industry demos:
 
-Session-start briefing. Returns mood, principles, identity, recent memories, and unresolved threads.
+- [examples/fintech-ops-demo.js](examples/fintech-ops-demo.js)
+- [examples/healthcare-ops-demo.js](examples/healthcare-ops-demo.js)
 
-```js
-const briefing = await brain.greeting({
-  context: 'debugging stripe',  // Optional — also returns relevant memories
-  recentLimit: 10,
-  principleLimit: 5,
-  identityLimit: 5,
-});
-// { recent, principles, mood, unresolved, identity, contextual }
-```
+## Core Concepts
 
-### `brain.forget(id, options)` -> `ForgetResult`
+### Memory Types
 
-Forget a memory by ID. Works on any memory type (episodic, semantic, procedural).
+- **Episodic**: raw events and observations
+- **Semantic**: consolidated principles
+- **Procedural**: reusable workflows and actions
+- **Causal**: relationships that explain why something happened
 
-```js
-brain.forget(memoryId);                       // soft-delete
-brain.forget(memoryId, { purge: true });      // hard-delete (permanent)
-// { id, type: 'episodic', purged: false }
-```
-
-### `brain.forgetByQuery(query, options)` -> `Promise<ForgetResult | null>`
+### Confidence
 
-Find the closest matching memory by semantic search and forget it. Searches all three memory types, picks the best match.
+Audrey scores memories using source reliability, evidence agreement, recency decay, and retrieval reinforcement. That helps keep direct observations above guesses and keeps stale or weakly supported knowledge from dominating recall.
 
-```js
-const result = await brain.forgetByQuery('old API endpoint', {
-  minSimilarity: 0.9,    // Threshold for match (default 0.9)
-  purge: false,          // Hard-delete? (default false)
-});
-// null if no match above threshold
-```
+### Dream Cycle
 
-### `brain.purge()` -> `PurgeCounts`
+`brain.dream()` runs the full maintenance path:
 
-Bulk hard-delete all dead memories: forgotten episodes, dormant/superseded/rolled-back semantics and procedures.
+1. Consolidate related episodes into principles.
+2. Apply decay so low-value memories lose weight over time.
+3. Report memory health and current stats.
 
-```js
-const counts = brain.purge();
-// { episodes: 12, semantics: 3, procedures: 0 }
-```
+### Contradiction Handling
 
-### `brain.consolidate(options)` -> `Promise<ConsolidationResult>`
+When evidence conflicts, Audrey tracks the contradiction instead of silently picking a winner. Resolutions can stay open, be marked resolved, or become context-dependent.
 
-Run the consolidation engine manually. Fully transactional — if any cluster fails, all writes roll back.
+## Configuration
 
 ```js
-const result = await brain.consolidate({
-  minClusterSize: 3,
-  similarityThreshold: 0.80,
-  extractPrinciple: (episodes) => ({    // Optional LLM callback
-    content: 'Extracted principle text',
-    type: 'semantic',                   // or 'procedural'
-    conditions: ['trigger conditions'], // for procedural only
-  }),
+const brain = new Audrey({
+  dataDir: './audrey-data',
+  agent: 'my-agent',
+  embedding: {
+    provider: 'local', // mock | local | gemini | openai
+    dimensions: 384,
+    device: 'gpu',
+  },
+  llm: {
+    provider: 'anthropic', // mock | anthropic | openai
+    apiKey: process.env.ANTHROPIC_API_KEY,
+  },
+  consolidation: {
+    minEpisodes: 3,
+  },
+  context: {
+    enabled: true,
+    weight: 0.3,
+  },
+  affect: {
+    enabled: true,
+    weight: 0.2,
+  },
+  decay: {
+    dormantThreshold: 0.1,
+  },
 });
-// { runId, status, episodesEvaluated, clustersFound, principlesExtracted, semanticsCreated, proceduresCreated }
-```
-
-### `brain.decay(options)` -> `DecayResult`
-
-Apply forgetting curves. Transitions low-confidence memories to dormant.
-
-```js
-const result = brain.decay({ dormantThreshold: 0.1 });
-// { totalEvaluated, transitionedToDormant, timestamp }
 ```
 
-### `brain.memoryStatus()` -> `HealthStatus`
+## Operations
 
-Check brain health: vector index sync, dimension consistency, re-embed recommendations.
+Recommended production workflow:
 
-```js
-brain.memoryStatus();
-// { healthy, vec_episodes, searchable_episodes, vec_semantics, ..., reembed_recommended }
-```
-
-### `brain.rollback(runId)` -> `RollbackResult`
+```bash
+# Health checks
+npx audrey status
+npx audrey status --json --fail-on-unhealthy
 
-Undo a consolidation run.
+# Scheduled maintenance
+npx audrey dream
 
-```js
-brain.rollback('01ABC...');
-// { rolledBackMemories: 3, restoredEpisodes: 9 }
-```
+# Repair vector/index drift after provider or dimension changes
+npx audrey reembed
 
-### `brain.resolveTruth(contradictionId)` -> `Promise<Resolution>`
+# Version control your memories
+npx audrey snapshot
+npx audrey restore <file> --force
 
-Resolve an open contradiction using LLM reasoning. Requires an LLM provider configured.
+# Run the benchmark harness
+npm run bench:memory
 
-```js
-const resolution = await brain.resolveTruth('contradiction-id');
-// { resolution: 'context_dependent', conditions: { a: 'live keys', b: 'test keys' }, explanation: '...' }
+# Fail CI if Audrey drops below benchmark guardrails
+npm run bench:memory:check
 ```
 
-### `brain.introspect()` -> `Stats`
+## Benchmarking
 
-Get memory system health stats.
+Audrey now ships with a memory benchmark harness built for three purposes:
 
-```js
-brain.introspect();
-// {
-//   episodic: 247, semantic: 31, procedural: 8,
-//   causalLinks: 42, dormant: 15,
-//   contradictions: { open: 2, resolved: 7, context_dependent: 3, reopened: 0 },
-//   lastConsolidation: '2026-02-18T22:00:00Z',
-//   totalConsolidationRuns: 14,
-// }
-```
+- measure Audrey against naive local baselines on LongMemEval-style memory abilities plus privacy and abstention checks
+- measure Audrey on lifecycle operations that other memory systems usually hand-wave: update, overwrite, delete, merge, and abstain
+- keep Audrey grounded against published LoCoMo results from leading memory systems
 
-### `brain.consolidationHistory()` -> `ConsolidationRun[]`
+Run it with:
 
-Full audit trail of all consolidation runs.
-
-### `brain.export()` / `brain.import(snapshot)`
-
-Export all memories as a JSON snapshot, or import from one. Full-fidelity: preserves consolidation metrics, run metadata, and config. Import re-embeds everything with the current provider in a single atomic transaction.
-
-```js
-const snapshot = brain.export();   // { version, episodes, semantics, procedures, consolidationMetrics, ... }
-await brain.import(snapshot);      // Re-embeds everything with current provider
-```
-
-### Events
-
-```js
-brain.on('encode', ({ id, content, source }) => { ... });
-brain.on('reinforcement', ({ episodeId, targetId, similarity }) => { ... });
-brain.on('contradiction', ({ episodeId, contradictionId, semanticId, resolution }) => { ... });
-brain.on('consolidation', ({ runId, principlesExtracted }) => { ... });
-brain.on('decay', ({ totalEvaluated, transitionedToDormant }) => { ... });
-brain.on('dream', ({ consolidation, decay, stats }) => { ... });
-brain.on('rollback', ({ runId, rolledBackMemories }) => { ... });
-brain.on('forget', ({ id, type, purged }) => { ... });
-brain.on('purge', ({ episodes, semantics, procedures }) => { ... });
-brain.on('interference', ({ newEpisodeId, suppressedId, similarity }) => { ... });
-brain.on('resonance', ({ episodeId, resonances }) => { ... });
-brain.on('migration', ({ episodes, semantics, procedures }) => { ... });
-brain.on('error', (err) => { ... });
+```bash
+npm run bench:memory
 ```
 
-### `brain.close()`
+Artifacts land in `benchmarks/output/` as JSON, SVG charts, and an HTML report.
 
-Close the database connection.
+For CI and release gates:
 
-## Architecture
-
-```
-audrey-data/
-  audrey.db          <- Single SQLite file. WAL mode. That's your brain.
-```
-
-```
-src/
-  audrey.js          Main class. EventEmitter. Public API surface.
-  causal.js          Causal graph management. LLM-powered mechanism articulation.
-  confidence.js      Compositional confidence formula. Pure math.
-  consolidate.js     "Sleep" cycle. KNN clustering -> LLM extraction -> promote.
-  db.js              SQLite + sqlite-vec. Schema, vec0 tables, migrations.
-  decay.js           Ebbinghaus forgetting curves.
-  embedding.js       Pluggable providers (Mock, Local/MiniLM, Gemini, OpenAI). Batch embedding.
-  encode.js          Immutable episodic memory creation + vec0 writes.
-  affect.js          Emotional memory: arousal-salience coupling, mood-congruent recall, resonance.
-  context.js         Context-dependent retrieval modifier (encoding specificity).
-  interference.js    Competitive memory suppression (engram competition).
-  forget.js          Soft-delete, hard-delete, query-based forget, bulk purge.
-  introspect.js      Health dashboard queries.
-  llm.js             Pluggable LLM providers (Mock, Anthropic, OpenAI).
-  prompts.js         Structured prompt templates for LLM operations.
-  recall.js          KNN retrieval + confidence scoring + filtered recall + streaming.
-  rollback.js        Undo consolidation runs.
-  utils.js           Date math, safe JSON parse.
-  validate.js        KNN validation + LLM contradiction detection.
-  migrate.js         Dimension migration re-embedding.
-  adaptive.js        Adaptive consolidation parameter suggestions.
-  export.js          Memory export (JSON snapshots with consolidation metrics).
-  import.js          Memory import with batch re-embedding in atomic transactions.
-  index.js           SDK barrel export (all providers, database utilities).
-
-mcp-server/
-  index.js           MCP tool server (13 tools, stdio transport) + CLI subcommands.
-  config.js          Shared config (env var parsing, provider resolution, install arg builder).
+```bash
+npm run bench:memory:check
 ```
 
-### Database Schema
+That command fails if Audrey drops below its minimum local score, local pass rate, or required margin over the strongest naive baseline.
 
-| Table | Purpose |
-|---|---|
-| `episodes` | Immutable raw events (content, source, salience, causal context, affect, private flag) |
-| `semantics` | Consolidated principles (content, state, evidence chain) |
-| `procedures` | Learned workflows (trigger conditions, success/failure counts) |
-| `causal_links` | Causal relationships (cause, effect, mechanism, link type) |
-| `contradictions` | Dispute tracking (claims, state, resolution) |
-| `consolidation_runs` | Audit trail (inputs, outputs, status, checkpoint cursor) |
-| `consolidation_metrics` | Per-run metrics and confidence deltas |
-| `vec_episodes` | sqlite-vec KNN index for episode embeddings |
-| `vec_semantics` | sqlite-vec KNN index for semantic embeddings |
-| `vec_procedures` | sqlite-vec KNN index for procedural embeddings |
-| `audrey_config` | Dimension configuration, embedding model info, metadata |
-
-All mutations use SQLite transactions. CHECK constraints enforce valid states and source types. Vector search uses sqlite-vec with cosine distance.
-
-## Running Tests
+For track-specific runs:
 
 ```bash
-npm test          # 463 tests across 29 files
-npm run test:watch
+npm run bench:memory:retrieval
+npm run bench:memory:operations
 ```
 
-## Running the Demo
+For committed GitHub-friendly charts:
 
 ```bash
-node examples/stripe-demo.js
+npm run bench:memory:readme-assets
 ```
 
-Demonstrates the full pipeline: encode 3 rate-limit observations, consolidate into principle, recall proactively.
-
----
-
-## Changelog
-
-### v0.16.0 (current)
-
-- Version bump for npm publish with all v0.15.0 features included
-- 463 tests across 29 test files
-
-### v0.15.0 — Production Hardening + Dream Cycle
-
-- `dream()` method: consolidation + decay + introspect (biological sleep analog)
-- `memory_dream` MCP tool with configurable thresholds
-- `greeting` and `reflect` CLI subcommands for hook integration
-- Consolidation routes procedural principles to `procedures` table (previously all went to semantics)
-- Fully transactional consolidation — mid-run failures roll back all writes
-- Recall gracefully degrades per memory type (independent try/catch per KNN search)
-- sqlite-vec crash guard for empty vector tables
-- LLM JSON parsing strips markdown code fences from any provider
-- Input validation: empty content rejected, 50K char limit, forget requires exactly one target
-- Full-fidelity export/import: preserves consolidation metrics, run metadata, config
-- Import uses batch embedding in a single atomic transaction
-- Expanded SDK exports: all embedding/LLM providers, database utilities
-- Shared `resolveLLMConfig()` for CLI commands
-- 463 tests across 29 test files
-
-### v0.14.0 — Memory Intelligence
+### README Snapshot
 
-- `memory_reflect` MCP tool — form lasting memories from conversation turns
-- `memory_greeting` MCP tool — session-start context briefing
-- `greeting()` method: mood, principles, identity, recent memories, unresolved threads
-- `reflect()` method: LLM-powered conversation analysis and memory formation
-- Rewritten consolidation prompt for deeper principle extraction
-- Rewritten reflection prompt for relational and emotional depth
-- `npx audrey status` shows last consolidation time
+Local Audrey-vs-baseline results:
 
-### v0.13.0 — GPU-Accelerated Embeddings
+![Audrey local memory benchmark](docs/assets/benchmarks/local-benchmark.svg)
 
-- GPU device configuration for LocalEmbeddingProvider
-- True single-forward-pass batch embedding for LocalEmbeddingProvider
-- Gemini `batchEmbedContents` API for batch embedding
-- `reembedAll` uses `embedBatch` for performance
-- `AUDREY_DEVICE` env var, `memoryStatus` reports device
+Lifecycle operations benchmark:
 
-### v0.11.0 — Multi-Provider Embeddings + Privacy
+![Audrey memory operations benchmark](docs/assets/benchmarks/operations-benchmark.svg)
 
-- `LocalEmbeddingProvider` — 384d MiniLM via @huggingface/transformers (zero API key, works offline)
-- `GeminiEmbeddingProvider` — 3072d via Google text-embedding-004
-- `private: true` memory flag — memories visible to AI only, excluded from public recall
-- Auto-select embedding provider: local -> gemini (if API key present) -> explicit openai
-- `npx audrey reembed` CLI subcommand for provider migration
-- `reflect()` method for post-conversation memory formation
-- 409 tests across 29 test files
+Published comparison anchors from current LLM memory systems:
 
-### v0.9.0 — Emotional Memory
+![Published LLM memory benchmark comparison](docs/assets/benchmarks/published-memory-standards.svg)
 
-- Valence-arousal affect model (Russell's circumplex) on every episode
-- Arousal-salience coupling via Yerkes-Dodson inverted-U curve
-- Mood-congruent recall — matching emotional state boosts retrieval confidence
-- Emotional resonance detection — new experiences that echo past emotional patterns emit events
-- MCP server: `memory_encode` accepts `affect`, `memory_recall` accepts `mood`
+**Current deterministic CI snapshot** (`node benchmarks/run.js --provider mock --dimensions 64`):
 
-### v0.8.0 — Context-Dependent Retrieval
-
-- Encoding specificity principle: context stored with memory, matching context boosts recall
-- MCP server: `memory_encode` and `memory_recall` accept `context`
-
-### v0.7.0 — Interference + Salience
-
-- Interference-based forgetting: new memories competitively suppress similar existing ones
-- Salience-weighted confidence: high-salience memories resist decay
-- Spaced-repetition reconsolidation: retrieval intervals affect reinforcement strength
-
-### v0.6.0 — Filtered Recall + Forget
-
-- Filtered recall: tag, source, and date-range filters on `recall()` and `recallStream()`
-- `forget()`, `forgetByQuery()`, `purge()`
-- `memory_forget` and `memory_decay` MCP tools
-
-### v0.5.0 — Feature Depth
-
-- Configurable confidence weights and decay rates per instance
-- Memory export/import (JSON snapshots with re-embedding)
-- `memory_export` and `memory_import` MCP tools
-- Auto-consolidation scheduling
-- Adaptive consolidation parameter suggestions
-
-### v0.3.1 — MCP Server
-
-- MCP tool server via `@modelcontextprotocol/sdk` with stdio transport
-- One-command install: `npx audrey install` (auto-detects API keys)
-- CLI subcommands: `install`, `uninstall`, `status`
-
-### v0.3.0 — Vector Performance
+| Local track | Audrey | Best Baseline |
+|---|---|---|
+| Combined local benchmark | **100.0%** | 41.7% |
+| Retrieval capabilities | **100.0%** | 56.3% |
+| Memory operations | **100.0%** | 25.0% |
 
-- sqlite-vec native vector indexing (vec0 virtual tables with cosine distance)
-- KNN queries for recall, validation, and consolidation clustering
-- Batch encoding API and streaming recall with async generators
+Retrieval-family breakdown:
 
-### v0.2.0 — LLM Integration
+| Category | Audrey | Vector Only | Best Baseline |
+|---|---|---|---|
+| Information Extraction | 100% | 100% | 100% |
+| Knowledge Updates | 100% | 50% | 50% |
+| Multi-Session Reasoning | 100% | 100% | 100% |
+| Temporal Reasoning | 100% | 100% | 100% |
+| Abstention | 100% | 50% | 50% |
+| Conflict Resolution | 100% | 50% | 50% |
+| Procedural Learning | 100% | 0% | 0% |
+| Privacy | 100% | 0% | 0% |
 
-- LLM-powered principle extraction, contradiction detection, causal articulation
-- Context-dependent truth resolution
-- Configurable LLM providers (Mock, Anthropic, OpenAI)
+Operation-family breakdown:
 
-### v0.1.0 — Foundation
+| Operation | Audrey | Vector Only | Best Baseline |
+|---|---|---|---|
+| Update / Overwrite | 100% | 50% | 50% |
+| Delete + Abstain | 100% | 0% | 50% |
+| Semantic Merge | 100% | 0% | 0% |
+| Procedural Merge | 100% | 0% | 0% |
 
-- Immutable episodic memory, compositional confidence, Ebbinghaus forgetting curves
-- Consolidation engine, contradiction lifecycle, rollback
-- Circular self-confirmation defense, causal context, introspection
+Published comparison anchors from the field (different benchmarks and conditions - included for field context, not direct comparison):
 
-## Design Decisions
+| System | Benchmark | Score | What it represents |
+|---|---|---|---|
+| **Audrey** | Internal retrieval + operations benchmark | **100.0%** | Update, overwrite, delete, merge, abstention, consolidation, privacy |
+| MIRIX | Published LoCoMo | 85.4% | Typed multimodal memory |
+| Letta Filesystem | Published LoCoMo | 74.0% | Context-engineering |
+| Mem0 Graph Memory | Published LoCoMo | 68.5% | Graph memory |
+| Mem0 | Published LoCoMo | 66.9% | Production baseline |
 
-**Why SQLite, not Postgres?** Zero infrastructure. `npm install` and you have a brain. The adapter pattern means you can migrate to pgvector when you need to scale.
+Primary comparison sources:
 
-**Why append-only episodes?** Immutability creates a reliable audit trail. Corrections use `supersedes` links rather than mutations. You can always trace back to what actually happened.
+- [MIRIX paper](https://arxiv.org/abs/2507.07957)
+- [Mem0 paper](https://arxiv.org/abs/2504.19413)
+- [Letta benchmark write-up](https://www.letta.com/blog/benchmarking-ai-agent-memory)
+- [LongMemEval paper](https://arxiv.org/abs/2410.10813)
 
-**Why Ebbinghaus curves?** Biological forgetting is an adaptive feature, not a bug. It prevents cognitive overload, maintains relevance, and enables generalization. Audrey's forgetting works the same way.
+Benchmark guide: [docs/benchmarking.md](docs/benchmarking.md)
 
-**Why model-generated cap at 0.6?** Prevents the most dangerous exploit in AI memory: circular self-confirmation where an agent's own inferences bootstrap themselves into high-confidence "facts" through repeated retrieval.
+## Repository
 
-**Why soft-delete by default?** Hard-deletes are irreversible. Soft-delete preserves data integrity and audit trails while excluding the memory from recall. Use `purge: true` or `brain.purge()` when you need permanent removal (GDPR, storage cleanup).
+- Contributing guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Security policy: [SECURITY.md](SECURITY.md)
+- CI workflow: [.github/workflows/ci.yml](.github/workflows/ci.yml)
+- Benchmarking guide: [docs/benchmarking.md](docs/benchmarking.md)
 
-**Why emotional memory?** Every memory system stores facts. Biological memory stores facts with emotional context — and that context changes how memories are retrieved. Emotional arousal modulates encoding strength (amygdala-hippocampal interaction). Current mood biases which memories surface (Bower, 1981). This isn't a novelty feature — it's the foundation for AI that remembers like it cares.
+## Development
 
-**Why a dream cycle?** Biological sleep isn't downtime — it's when the brain consolidates episodic memories into long-term semantic knowledge, prunes weak connections, and strengthens important ones. Audrey's `dream()` does the same: cluster episodes, extract principles, apply decay, report health. Wire it into session hooks and your agent gets smarter every time it sleeps.
+```bash
+npm ci
+npm test
+npm run pack:check
+npm run bench:memory
+npm run bench:memory:retrieval
+npm run bench:memory:operations
+npm run bench:memory:check
+npm run bench:memory:readme-assets
+```
+
+Current validated baseline:
+
+- `npm test`
+- `npm run pack:check`
+- `npm run bench:memory`
+- `npm run bench:memory:retrieval`
+- `npm run bench:memory:operations`
+- `npm run bench:memory:check`
+- `npm run bench:memory:readme-assets`
 
 ## License
 
-MIT
+MIT. See [LICENSE](LICENSE).