feat: add memory preflight reflexes

.gitignore

@@ -1,5 +1,8 @@
 node_modules/
 .npm-cache/
+.tmp-npm-cache/
+.audrey-demo-tmp/
+.claude/settings.local.json
 audrey-data/
 .tmp/
 .tmp-vitest/

README.md

@@ -4,76 +4,108 @@
 [![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)
 
-Audrey is a persistent memory and continuity engine for Claude Code and AI agents.
+Audrey is a local-first memory runtime and continuity engine for AI agents.
 
-It gives an agent a local memory store, durable recall, consolidation, contradiction handling, a REST sidecar, MCP tools, and benchmark gates without adding external infrastructure.
+It gives Codex, Claude Code, Claude Desktop, Cursor, local Ollama-backed agents, and custom agent services a shared local memory store, durable recall, consolidation, contradiction handling, a REST sidecar, MCP tools, and benchmark gates without adding external infrastructure.
+
+Audrey also checks memory before an agent acts. Known failures, project rules, and local quirks become preflight warnings and Memory Reflexes instead of repeated mistakes.
 
 Requires Node.js 20+.
 
 ## Quick Start
 
-### Claude Code
+### 60-Second Proof
 
 ```bash
-npx audrey init
-npx audrey doctor
+npx audrey demo
 ```
 
-This uses the default `local-offline` preset:
+This runs a self-contained local demo with no API keys, no host setup, and no external model. It writes temporary memories, records a redacted tool failure, asks Audrey for a Memory Capsule, proves recall, then deletes the demo store.
+
+### MCP Hosts
+
+```bash
+npx audrey mcp-config codex
+npx audrey mcp-config generic
+```
+
+`mcp-config codex` prints a ready-to-paste Codex TOML block. `mcp-config generic` prints JSON for local stdio MCP hosts such as Claude Desktop, Cursor, Windsurf, and JetBrains.
+
+Claude Code also has a direct installer:
+
+```bash
+npx audrey install
+claude mcp list
+```
+
+All MCP paths use local embeddings by default and store memory in one SQLite-backed data directory.
+
+### Ollama and Local Agents
 
-- registers Audrey with Claude Code
-- installs hooks for automatic recall and reflection
-- uses local embeddings by default
-- stores memory in one local SQLite-backed data directory
+Ollama is a local model runtime, not a memory store. Use Audrey as the sidecar memory tool layer for any Ollama-backed agent:
+
+```bash
+AUDREY_AGENT=ollama-local-agent npx audrey serve
+curl http://localhost:7437/health
+```
+
+Then expose Audrey's `/v1/preflight`, `/v1/reflexes`, `/v1/encode`, `/v1/recall`, `/v1/capsule`, and `/v1/status` routes as tools in the local agent loop.
+
+Runnable example:
+
+```bash
+AUDREY_AGENT=ollama-local-agent npx audrey serve
+OLLAMA_MODEL=qwen3 node examples/ollama-memory-agent.js "What should you remember about Audrey?"
+```
 
 ### REST or Docker Sidecar
 
 ```bash
-npx audrey init sidecar-prod
 docker compose up -d --build
 ```
 
 Then verify:
 
 ```bash
-npx audrey doctor
+npx audrey status
 curl http://localhost:3487/health
 ```
 
 ## Why Audrey
 
 - Local-first: memory lives in SQLite with `sqlite-vec`, not a hosted vector database.
+- Host-neutral: Audrey is a memory runtime for agent hosts, not a Claude-only extension.
 - Practical: MCP, CLI, REST, JavaScript, Python, and Docker are all first-class.
-- Durable: snapshot, restore, health checks, benchmark gates, and graceful shutdown are built in.
+- Durable: export/import, health checks, benchmark gates, and graceful shutdown are built in.
 - Structured: Audrey does more than save notes. It consolidates, decays, tracks contradictions, and supports procedural memory.
 
 ## What Ships
 
-- Claude Code MCP server with 13 memory tools
-- Automatic hook-based recall and reflection for Claude Code sessions
+- Local stdio MCP server with 19 memory tools
+- Ready-to-paste config generation for Codex and generic MCP hosts
+- Hook-compatible CLI helpers for recall, reflection, and tool trace capture
 - JavaScript SDK
 - Python SDK packaged as `audrey-memory`
-- REST API for sidecar deployment
+- REST API for sidecar deployment and Ollama/local-agent tool bridges
+- Memory Preflight for checking prior failures, risks, rules, and procedures before an agent acts
+- Memory Reflexes that convert preflight evidence into trigger-response guidance agents can automate
 - Docker and Compose deployment path
-- Snapshot and restore for portable memory state
+- Export/import for portable memory state
 - Machine-readable health and benchmark gates
 - Local benchmark harness with retrieval and lifecycle-operation tracks
 
-## Setup Presets
+## Integration Modes
 
-`npx audrey init` supports four named presets:
-
-| Preset | Best For | Behavior |
+| Mode | Best For | Entry Point |
 |---|---|---|
-| `local-offline` | Claude Code on one machine | Local embeddings, MCP install, hooks install |
-| `hosted-fast` | Claude Code with provider keys already present | Auto-picks hosted providers from env, MCP install, hooks install |
-| `ci-mock` | CI and smoke tests | Mock embedding + LLM providers, no Claude-specific setup |
-| `sidecar-prod` | REST API and Docker deployment | Sidecar-oriented defaults, no Claude-specific setup |
+| MCP stdio | Codex, Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, JetBrains | `npx audrey mcp-config <host>` or `npx audrey install` for Claude Code |
+| REST sidecar | Ollama-backed local agents, internal agent services, Docker | `npx audrey serve` or `docker compose up -d --build` |
+| SDK direct | Node.js and TypeScript agents inside one process | `import { Audrey } from 'audrey'` |
+| Python client | Python agents calling the REST sidecar | `pip install audrey-memory` |
 
 Useful checks:
 
 ```bash
-npx audrey doctor
 npx audrey status
 npx audrey status --json --fail-on-unhealthy
 ```
@@ -130,32 +162,28 @@ brain.close()
 
 ```bash
 # Setup
-npx audrey init
-npx audrey init hosted-fast
-npx audrey init ci-mock
-npx audrey init sidecar-prod
+npx audrey demo
+npx audrey mcp-config codex
+npx audrey mcp-config generic
 
-# Claude Code integration
+# MCP integration
 npx audrey install
-npx audrey hooks install
-npx audrey hooks uninstall
 npx audrey uninstall
 
 # Health and maintenance
-npx audrey doctor
 npx audrey status
 npx audrey dream
 npx audrey reembed
-
-# Versioning
-npx audrey snapshot
-npx audrey restore backup.json --force
+npx audrey observe-tool --event PostToolUse --tool Bash --outcome failed
 
 # Sidecar
 npx audrey serve
+node examples/ollama-memory-agent.js "Use Audrey memory before answering"
 docker compose up -d --build
 ```
 
+Before risky actions, hosts can call `memory_preflight` or `memory_reflexes` over MCP, or `POST /v1/preflight` / `POST /v1/reflexes` over REST. Preflight returns the risk briefing. Reflexes return trigger-response rules such as "Before using npm test, review the prior EPERM failure path."
+
 ## Benchmarks
 
 Audrey ships with a benchmark harness and release gate:
@@ -210,7 +238,11 @@ Key environment variables:
 ## Documentation
 
 - [docs/benchmarking.md](docs/benchmarking.md)
+- [docs/audrey-for-dummies.md](docs/audrey-for-dummies.md)
+- [docs/future-of-llm-memory.md](docs/future-of-llm-memory.md)
 - [docs/production-readiness.md](docs/production-readiness.md)
+- [docs/mcp-hosts.md](docs/mcp-hosts.md)
+- [docs/ollama-local-agents.md](docs/ollama-local-agents.md)
 - [CONTRIBUTING.md](CONTRIBUTING.md)
 - [SECURITY.md](SECURITY.md)
 

codex.md

@@ -4,7 +4,7 @@
 
 ## What Audrey Is
 
-Audrey is a **biological memory system for AI agents**. It gives agents persistent, local memory that encodes, consolidates, decays, and dreams — modeled after how human brains actually process memory. Published on npm as `audrey` (v0.20.0) and PyPI as `audrey-memory` (v0.20.0).
+Audrey is a **biological memory system and local-first continuity runtime for AI agents**. It gives Codex, Claude Code, Claude Desktop, Ollama-backed local agents, and custom agent services persistent local memory that encodes, consolidates, decays, and dreams - modeled after how human brains actually process memory. Published on npm as `audrey` (v0.20.0) and PyPI as `audrey-memory` (v0.20.0).
 
 **Not a database.** Not a RAG pipeline. Not a vector store. Audrey is a *memory layer* with biological fidelity: episodic memories consolidate into semantic principles, confidence decays over time, contradictions are tracked and resolved, emotional affect influences recall, and interference between competing memories is modeled explicitly.
 
@@ -41,7 +41,7 @@ audrey/
 │   ├── audrey.ts                 # Main Audrey class — EventEmitter, owns all methods
 │   ├── index.ts                  # Barrel re-exports (SDK entry point)
 │   ├── server.ts                 # HTTP server (Hono + @hono/node-server)
-│   ├── routes.ts                 # 13 REST endpoints + /health
+│   ├── routes.ts                 # 15 /v1 REST endpoints + /health
 │   ├── encode.ts                 # Episode encoding with auto-supersede
 │   ├── recall.ts                 # KNN vector recall with 6-signal confidence scoring
 │   ├── consolidate.ts            # Cluster episodes → extract principles (LLM or heuristic)
@@ -66,7 +66,7 @@ audrey/
 │   ├── ulid.ts                   # Monotonic ULID generation
 │   └── utils.ts                  # Cosine similarity, JSON parse, API key validation
 ├── mcp-server/                   # MCP server + CLI (2 modules)
-│   ├── index.ts                  # 13 MCP tools + CLI (install/uninstall/status/greeting/reflect/dream/reembed/serve)
+│   ├── index.ts                  # 19 MCP tools + CLI (install/uninstall/status/greeting/reflect/dream/reembed/serve)
 │   └── config.ts                 # Provider resolution, VERSION constant, install args
 ├── python-sdk/                   # Python SDK (pip install audrey-memory)
 │   ├── pyproject.toml            # Hatchling build, deps: httpx + pydantic
@@ -133,18 +133,21 @@ const dream = await brain.dream();
 brain.close();
 ```
 
-### 2. MCP Server (Claude Code / Cursor / Windsurf)
+### 2. MCP Server (Codex / Claude Code / Claude Desktop / Cursor / Windsurf)
 
 ```bash
-npx audrey install    # registers MCP server with Claude Code
+npx audrey demo                  # self-contained local proof, no keys or host setup
+npx audrey mcp-config codex     # prints ready-to-paste Codex TOML
+npx audrey mcp-config generic   # prints JSON for stdio MCP hosts
+npx audrey install              # registers MCP server with Claude Code
 npx audrey status     # check health
 npx audrey greeting   # session briefing (for hooks)
 npx audrey reflect    # form memories from conversation (for hooks)
 npx audrey dream      # consolidation + decay cycle
 npx audrey serve      # start HTTP API on port 7437
 ```
 
-13 MCP 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`.
+19 MCP 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`, `memory_observe_tool`, `memory_recent_failures`, `memory_capsule`, `memory_preflight`, `memory_reflexes`, `memory_promote`.
 
 ### 3. HTTP API
 
@@ -161,7 +164,7 @@ curl -X POST http://localhost:7437/v1/recall \
   -d '{"query":"test"}'
 ```
 
-14 endpoints: `GET /health`, `POST /v1/encode`, `POST /v1/recall`, `POST /v1/consolidate`, `POST /v1/dream`, `GET /v1/introspect`, `POST /v1/resolve-truth`, `GET /v1/export`, `POST /v1/import`, `POST /v1/forget`, `POST /v1/decay`, `GET /v1/status`, `POST /v1/reflect`, `POST /v1/greeting`.
+16 `/v1` endpoints plus `GET /health`: `POST /v1/encode`, `POST /v1/recall`, `POST /v1/capsule`, `POST /v1/preflight`, `POST /v1/reflexes`, `POST /v1/consolidate`, `POST /v1/dream`, `GET /v1/introspect`, `POST /v1/resolve-truth`, `GET /v1/export`, `POST /v1/import`, `POST /v1/forget`, `POST /v1/decay`, `GET /v1/status`, `POST /v1/reflect`, `POST /v1/greeting`.
 
 ### 4. Python SDK
 
@@ -306,7 +309,7 @@ Schema is in `src/db.ts`. Migrations are in the `MIGRATIONS` array (currently v1
 | `AUDREY_DEVICE` | No | `gpu` | Local embedding device (`gpu` or `cpu`) |
 | `AUDREY_PORT` | No | `7437` | HTTP API server port |
 | `AUDREY_API_KEY` | No | — | Bearer token for HTTP API auth |
-| `AUDREY_AGENT` | No | `claude-code` | Agent name for MCP server |
+| `AUDREY_AGENT` | No | `local-agent` | Agent name for MCP server |
 
 Auto-detection priority: `GOOGLE_API_KEY` → Gemini embeddings; `ANTHROPIC_API_KEY` → Anthropic LLM; no keys → local embeddings (384d, offline).