audrey 0.17.0 → 0.21.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.21.0 - Release Diagnostics and Host Setup
+
+- Added `npx audrey doctor` for first-contact diagnostics, JSON automation, provider checks, MCP entrypoint validation, memory-store health, and host config generation.
+- Added `npx audrey install --host <host> --dry-run` so Codex, Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, JetBrains, and generic MCP hosts can preview setup without accidental config writes.
+- Updated docs around the recommended first run: `doctor`, `demo`, safe host install preview, then host-specific verification.
+- Kept Claude Code's direct installer intact while making the default release story host-neutral.
+- Refreshed lockfile transitive packages through the npm resolver; vulnerability audit remains clean.
+
+## 0.20.0 - Memory Reflexes
+
+- Added Memory Preflight and Memory Reflexes so agents can check memory before acting and turn repeated failures into trigger-response guidance.
+- Added Ollama/local-agent guidance and runnable local-agent example.
+- Expanded host-neutral MCP docs and Audrey for Dummies onboarding.

package/README.md

@@ -1,474 +1,284 @@
-# Audrey
+<div align="center">
+  <img src="docs/assets/audrey-wordmark.png" alt="Audrey wordmark" width="760">
 
-[![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)
+  <p><strong>The local-first memory control plane for AI agents.</strong></p>
 
-Persistent memory for Claude Code and AI agents. Two commands, every session remembers.
+  <p>
+    Give Codex, Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, JetBrains, Ollama-backed agents,
+    and custom agent services one durable memory layer they can check before they act.
+  </p>
 
-```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:
+  <p>
+    <a href="https://github.com/Evilander/Audrey/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Evilander/Audrey/actions/workflows/ci.yml/badge.svg?branch=master"></a>
+    <a href="https://www.npmjs.com/package/audrey"><img alt="npm version" src="https://img.shields.io/npm/v/audrey.svg"></a>
+    <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
+  </p>
+</div>
 
-- 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."
+## Why Audrey Exists
 
-Audrey models memory as a working system instead of a filing cabinet.
+Agents forget the exact mistakes they made yesterday. They repeat broken commands, lose project-specific rules, miss contradictions, and treat every new session like a cold start.
 
-| 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 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
-
-```bash
-npx audrey install          # Register 13 MCP memory tools
-npx audrey hooks install    # Wire automatic memory into session lifecycle
-```
+Audrey turns those hard-won lessons into a local memory runtime:
 
-Audrey auto-detects providers from your environment:
+- `memory_recall` finds durable context by semantic similarity.
+- `memory_preflight` checks prior failures, risks, rules, and relevant procedures before an action.
+- `memory_reflexes` converts remembered evidence into trigger-response guidance agents can follow.
+- `memory_dream` consolidates episodes into principles and applies decay.
+- `audrey doctor` tells a human or CI system whether the runtime is actually ready.
 
-- `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
+It is not a hosted vector database, a notes app, or a Claude-only plugin. Audrey is a SQLite-backed continuity layer that can sit under any local or sidecar agent loop.
 
-Quick checks:
+<div align="center">
+  <img src="docs/assets/audrey-feature-grid.jpg" alt="Audrey feature marks: memory continuity, archive signal, recall loop, layered evidence, local node, and remembering before acting" width="760">
+</div>
 
-```bash
-npx audrey status
-npx audrey status --json
-npx audrey status --json --fail-on-unhealthy
-```
+## Quick Start
 
-### SDK
+Requires Node.js 20+.
 
 ```bash
-npm install audrey
+npx audrey doctor
+npx audrey demo
 ```
 
-Zero external infrastructure. One SQLite file.
-
-## Quick Start
-
-```js
-import { Audrey } from 'audrey';
-
-const brain = new Audrey({
-  dataDir: './agent-memory',
-  agent: 'support-agent',
-  embedding: { provider: 'local', dimensions: 384 },
-});
-
-await brain.encode({
-  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' },
-});
-
-const memories = await brain.recall('stripe rate limits', {
-  limit: 5,
-  context: { task: 'debugging', domain: 'payments' },
-});
+`doctor` verifies Node, the MCP entrypoint, provider selection, memory-store health, and host config generation. `demo` runs a no-key, no-host, no-network proof: it creates temporary memories, records a redacted failed tool trace, generates a Memory Capsule, proves recall, prints Memory Reflexes, and deletes the demo store.
 
-const dream = await brain.dream();
-const briefing = await brain.greeting({ context: 'debugging stripe' });
+Expected first-run shape:
 
-await brain.waitForIdle();
-brain.close();
+```text
+Audrey Doctor v0.21.0
+Store health: not initialized
+Verdict: ready
 ```
 
-## MCP Tools
+After the first real memory write, `doctor` should report the store as healthy.
 
-Every Claude Code session gets these tools after `npx audrey install`:
+## Install Into Agent Hosts
 
-- `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`
-
-## CLI
+Preview host setup without editing config files:
 
 ```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
-
-# 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
-
-# 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
-
-# Maintenance
-npx audrey dream                # Full consolidation + decay cycle
-npx audrey reembed              # Re-embed all memories after provider/dimension change
-
-# 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
-
-# REST API server
-npx audrey serve                # Start HTTP server on port 3487
-npx audrey serve 8080           # Custom port
+npx audrey install --host codex --dry-run
+npx audrey install --host claude-code --dry-run
+npx audrey install --host generic --dry-run
 ```
 
-## Hooks Integration
-
-Audrey integrates directly into Claude Code's hook lifecycle for automatic, zero-config memory in every session:
+Generate raw config blocks:
 
 ```bash
-npx audrey hooks install
+npx audrey mcp-config codex
+npx audrey mcp-config generic
+npx audrey mcp-config vscode
 ```
 
-This configures four hooks in `~/.claude/settings.json`:
-
-| 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 |
-
-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.
-
-## REST API Server
-
-Turn Audrey into an HTTP service that any language or framework can use:
+Claude Code can be registered directly:
 
 ```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
+npx audrey install
+claude mcp list
 ```
 
-Endpoints:
+All local MCP paths default to local embeddings and one shared SQLite-backed memory directory. Use `AUDREY_DATA_DIR` to isolate projects, tenants, or host identities.
 
-| 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 |
+## Use With Ollama And Local Agents
 
-Example from any language:
+Ollama runs models; Audrey supplies memory. Start Audrey as a local REST sidecar and expose its routes as tools in your agent loop:
 
 ```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"}'
-
-# Search memories
-curl -X POST http://localhost:3487/recall \
-  -H "Content-Type: application/json" \
-  -d '{"query": "deploy failures", "limit": 5}'
+AUDREY_AGENT=ollama-local-agent npx audrey serve
+curl http://localhost:7437/health
+curl http://localhost:7437/v1/status
 ```
 
-## Versioning
-
-Audrey stores memories in SQLite with WAL mode, which isn't git-friendly. Instead, use JSON snapshots:
+Runnable example:
 
 ```bash
-# Save a checkpoint
-npx audrey snapshot
-
-# Commit it
-git add audrey-snapshot-*.json && git commit -m "memory checkpoint"
-
-# Restore on another machine or after a reset
-npx audrey restore audrey-snapshot-2026-03-24_15-30-00.json
+AUDREY_AGENT=ollama-local-agent npx audrey serve
+OLLAMA_MODEL=qwen3 node examples/ollama-memory-agent.js "What should you remember about Audrey?"
 ```
 
-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.
-
-## Production Fit
-
-Audrey is strongest today in workflows where memory must stay local, reviewable, and durable:
-
-- **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
-
-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.
-
-Production guide: [docs/production-readiness.md](docs/production-readiness.md)
-
-Industry demos:
-
-- [examples/fintech-ops-demo.js](examples/fintech-ops-demo.js)
-- [examples/healthcare-ops-demo.js](examples/healthcare-ops-demo.js)
+Core sidecar tools:
 
-## Core Concepts
+| Agent Need | REST Route |
+|---|---|
+| Check memory before acting | `POST /v1/preflight` |
+| Get reflex rules for an action | `POST /v1/reflexes` |
+| Store a useful observation | `POST /v1/encode` |
+| Recall relevant context | `POST /v1/recall` |
+| Get a turn-sized memory packet | `POST /v1/capsule` |
+| Check health | `GET /v1/status` |
 
-### Memory Types
+## What Ships
 
-- **Episodic**: raw events and observations
-- **Semantic**: consolidated principles
-- **Procedural**: reusable workflows and actions
-- **Causal**: relationships that explain why something happened
+| Surface | Status |
+|---|---|
+| MCP stdio server | 19 tools, resources, and prompt templates |
+| CLI | `doctor`, `demo`, `install`, `mcp-config`, `status`, `dream`, `reembed`, `observe-tool`, `promote` |
+| REST API | Hono server with `/health`, `/openapi.json`, `/docs`, and `/v1/*` routes |
+| JavaScript SDK | Direct TypeScript/Node import from `audrey` |
+| Python client | `pip install audrey-memory`, calls the REST sidecar |
+| Storage | Local SQLite plus `sqlite-vec`, no hosted database required |
+| Deployment | npm package, Docker, Compose, host-specific MCP config generation |
+| Safety loop | preflight warnings, reflexes, redacted tool traces, contradiction handling |
 
-### Confidence
+## Memory Model
 
-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.
+Audrey is built around the parts of memory that matter for agents:
 
-### Dream Cycle
+- Episodic memory: specific observations, tool results, preferences, and session facts.
+- Semantic memory: consolidated principles extracted from repeated evidence.
+- Procedural memory: remembered ways to act, avoid, retry, or verify.
+- Affect and salience: emotional weight and importance influence recall.
+- Interference and decay: stale, conflicting, or low-confidence memories lose authority over time.
+- Contradiction handling: competing claims are tracked instead of silently overwritten.
+- Tool-trace learning: failed commands and risky actions become future preflight warnings.
 
-`brain.dream()` runs the full maintenance path:
+The product bet is simple: the next generation of useful agents will not just retrieve facts. They will remember what happened, decide whether a memory is still trustworthy, and use that memory before touching tools.
 
-1. Consolidate related episodes into principles.
-2. Apply decay so low-value memories lose weight over time.
-3. Report memory health and current stats.
+## Use Audrey From Code
 
-### Contradiction Handling
-
-When evidence conflicts, Audrey tracks the contradiction instead of silently picking a winner. Resolutions can stay open, be marked resolved, or become context-dependent.
-
-## Configuration
+### JavaScript
 
 ```js
+import { Audrey } from 'audrey';
+
 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,
-  },
+  agent: 'support-agent',
+  embedding: { provider: 'local', dimensions: 384 },
 });
-```
 
-## Operations
-
-Recommended production workflow:
-
-```bash
-# Health checks
-npx audrey status
-npx audrey status --json --fail-on-unhealthy
-
-# Scheduled maintenance
-npx audrey dream
-
-# Repair vector/index drift after provider or dimension changes
-npx audrey reembed
+await brain.encode({
+  content: 'Stripe returns HTTP 429 above 100 req/s',
+  source: 'direct-observation',
+  tags: ['stripe', 'rate-limit'],
+});
 
-# Version control your memories
-npx audrey snapshot
-npx audrey restore <file> --force
+const memories = await brain.recall('stripe rate limit');
 
-# Run the benchmark harness
-npm run bench:memory
-
-# Fail CI if Audrey drops below benchmark guardrails
-npm run bench:memory:check
+await brain.waitForIdle();
+brain.close();
 ```
 
-## Benchmarking
-
-Audrey now ships with a memory benchmark harness built for three purposes:
-
-- 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
-
-Run it with:
+### Python
 
 ```bash
-npm run bench:memory
+pip install audrey-memory
 ```
 
-Artifacts land in `benchmarks/output/` as JSON, SVG charts, and an HTML report.
+```python
+from audrey_memory import Audrey
 
-For CI and release gates:
-
-```bash
-npm run bench:memory:check
+brain = Audrey(base_url="http://127.0.0.1:7437", agent="support-agent")
+memory_id = brain.encode("Stripe returns HTTP 429 above 100 req/s", source="direct-observation")
+results = brain.recall("stripe rate limit", limit=5)
+brain.close()
 ```
 
-That command fails if Audrey drops below its minimum local score, local pass rate, or required margin over the strongest naive baseline.
+## Production Readiness
+
+Audrey is close to a 1.0-ready local memory runtime, but production depends on how it is embedded. Treat it like stateful infrastructure.
 
-For track-specific runs:
+Release gates used for this package:
 
 ```bash
-npm run bench:memory:retrieval
-npm run bench:memory:operations
+npm run build
+npm run typecheck
+npm run bench:memory:check
+npm pack --dry-run
+npx audrey doctor
+npx audrey demo
 ```
 
-For committed GitHub-friendly charts:
+Recommended runtime checks:
 
 ```bash
-npm run bench:memory:readme-assets
+npx audrey doctor --json
+npx audrey status --json --fail-on-unhealthy
+npx audrey install --host codex --dry-run
 ```
 
-### README Snapshot
-
-Local Audrey-vs-baseline results:
-
-![Audrey local memory benchmark](docs/assets/benchmarks/local-benchmark.svg)
-
-Lifecycle operations benchmark:
+Production controls you still own:
 
-![Audrey memory operations benchmark](docs/assets/benchmarks/operations-benchmark.svg)
+- Set one `AUDREY_DATA_DIR` per tenant, environment, or isolation boundary.
+- Pin `AUDREY_EMBEDDING_PROVIDER` and `AUDREY_LLM_PROVIDER` explicitly.
+- Back up the SQLite data directory before provider or dimension changes.
+- Keep API keys and raw credentials out of encoded memory content.
+- Use `AUDREY_API_KEY` if the REST sidecar is reachable beyond the local process boundary.
+- Run `npx audrey dream` on a schedule so consolidation and decay stay current.
+- Add application-level encryption, retention, access control, and audit logging for regulated environments.
 
-Published comparison anchors from current LLM memory systems:
+Read the full guide: [docs/production-readiness.md](docs/production-readiness.md).
 
-![Published LLM memory benchmark comparison](docs/assets/benchmarks/published-memory-standards.svg)
+## Benchmarks
 
-**Current deterministic CI snapshot** (`node benchmarks/run.js --provider mock --dimensions 64`):
+Audrey ships with a benchmark harness and release gate:
 
-| Local track | Audrey | Best Baseline |
-|---|---|---|
-| Combined local benchmark | **100.0%** | 41.7% |
-| Retrieval capabilities | **100.0%** | 56.3% |
-| Memory operations | **100.0%** | 25.0% |
-
-Retrieval-family breakdown:
-
-| 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% |
+```bash
+npm run bench:memory
+npm run bench:memory:check
+```
 
-Operation-family breakdown:
+Current repo snapshot:
 
-| 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% |
+![Audrey local benchmark](docs/assets/benchmarks/local-benchmark.svg)
 
-Published comparison anchors from the field (different benchmarks and conditions - included for field context, not direct comparison):
+The benchmark suite covers retrieval behavior, overwrite behavior, delete/abstain behavior, and semantic/procedural merge behavior. For methodology and comparison anchors, see [docs/benchmarking.md](docs/benchmarking.md).
 
-| 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 |
+## Command Reference
 
-Primary comparison sources:
+```bash
+# First contact
+npx audrey doctor
+npx audrey demo
+
+# MCP setup
+npx audrey install --host codex --dry-run
+npx audrey mcp-config codex
+npx audrey mcp-config generic
+npx audrey install
+npx audrey uninstall
+
+# Health and maintenance
+npx audrey status
+npx audrey status --json --fail-on-unhealthy
+npx audrey dream
+npx audrey reembed
 
-- [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)
+# Tool-trace learning
+npx audrey observe-tool --event PostToolUse --tool Bash --outcome failed
+npx audrey promote --dry-run
 
-Benchmark guide: [docs/benchmarking.md](docs/benchmarking.md)
+# REST sidecar
+npx audrey serve
+docker compose up -d --build
+```
 
-## Repository
+## Documentation
 
-- 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)
+- [Audrey for Dummies](docs/audrey-for-dummies.md)
+- [MCP host guide](docs/mcp-hosts.md)
+- [Ollama and local agents](docs/ollama-local-agents.md)
+- [Production readiness](docs/production-readiness.md)
+- [Future of LLM memory](docs/future-of-llm-memory.md)
+- [Benchmarking](docs/benchmarking.md)
+- [Security policy](SECURITY.md)
 
 ## Development
 
 ```bash
 npm ci
+npm run build
+npm run typecheck
 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
+npm run pack:check
+python -m unittest discover -s python/tests -v
+python -m build --no-isolation python
 ```
 
-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`
+On some locked-down Windows hosts, Vitest/Vite can fail before tests start with `spawn EPERM`. That is an environment process-spawn blocker, not an Audrey runtime failure. Use build, typecheck, benchmark, pack dry-run, direct `dist/` smokes, and GitHub Actions as the release evidence path.
 
 ## License