audrey 0.21.0 → 1.0.0

package/docs/mcp-hosts.md

@@ -1,206 +0,0 @@
-# Audrey MCP Host Guide
-
-Audrey ships as a local stdio MCP server. Claude Code is only one host; the same server is meant to be used from Codex, Claude Desktop, Cursor, Windsurf, VS Code, JetBrains, and any MCP-compatible local agent shell.
-
-For pinned configs that launch the built Audrey entrypoint directly:
-
-```bash
-npx audrey doctor
-npx audrey install --host codex --dry-run
-npx audrey install --host generic --dry-run
-npx audrey mcp-config codex
-npx audrey mcp-config generic
-npx audrey mcp-config vscode
-```
-
-`doctor` verifies the runtime, local memory store, provider configuration, and config-generation path. `install --host <host> --dry-run` prints setup instructions without writing to a host config file. That is the safest first pass when Codex, Cursor, Windsurf, VS Code, or JetBrains manage their own config formats.
-
-For portable configs that always resolve the latest published package, launch with `npx`:
-
-```json
-{
-  "mcpServers": {
-    "audrey-memory": {
-      "command": "npx",
-      "args": ["-y", "audrey"],
-      "env": {
-        "AUDREY_AGENT": "host-name"
-      }
-    }
-  }
-}
-```
-
-If a Windows host fails to locate `npx`, use:
-
-```json
-{
-  "mcpServers": {
-    "audrey-memory": {
-      "command": "cmd",
-      "args": ["/c", "npx", "-y", "audrey"]
-    }
-  }
-}
-```
-
-## Codex
-
-Codex uses TOML under `C:\Users\<you>\.codex\config.toml` on Windows.
-
-Generate a pinned block:
-
-```bash
-npx audrey install --host codex --dry-run
-npx audrey mcp-config codex
-```
-
-Example shape:
-
-```toml
-[mcp_servers.audrey-memory]
-command = "C:\\Program Files\\nodejs\\node.exe"
-args = ["C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\audrey\\dist\\mcp-server\\index.js"]
-
-[mcp_servers.audrey-memory.env]
-AUDREY_AGENT = "codex"
-AUDREY_DATA_DIR = "C:\\Users\\you\\.audrey\\data"
-AUDREY_EMBEDDING_PROVIDER = "local"
-AUDREY_DEVICE = "gpu"
-```
-
-Use one shared `AUDREY_DATA_DIR` if Codex and other hosts should remember the same work. Use separate data directories if you need hard separation between clients or projects.
-
-## Claude Code
-
-Claude Code can use Audrey through the built-in installer:
-
-```bash
-npx audrey install --host claude-code --dry-run
-npx audrey install
-claude mcp list
-```
-
-The dry-run prints the exact shape before any host changes. The real installer persists a Claude Code `AUDREY_AGENT=claude-code` identity while still using the same Audrey MCP runtime as every other host.
-
-## Claude Desktop
-
-Claude Desktop uses `claude_desktop_config.json`.
-
-```json
-{
-  "mcpServers": {
-    "audrey-memory": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "audrey"],
-      "env": {
-        "AUDREY_AGENT": "claude-desktop"
-      }
-    }
-  }
-}
-```
-
-## Cursor
-
-Official docs: <https://docs.cursor.com/en/context/mcp>
-
-- Project-local config: `.cursor/mcp.json`
-- Global config: `~/.cursor/mcp.json`
-- Cursor supports variable interpolation in `command`, `args`, `env`, `url`, and `headers`
-
-Recommended project-local example:
-
-```json
-{
-  "mcpServers": {
-    "audrey-memory": {
-      "command": "npx",
-      "args": ["-y", "audrey"],
-      "env": {
-        "AUDREY_AGENT": "cursor",
-        "AUDREY_DATA_DIR": "${workspaceFolder}/.audrey-data"
-      }
-    }
-  }
-}
-```
-
-## Windsurf
-
-Official docs: <https://docs.windsurf.com/windsurf/cascade/mcp>
-
-- Open the MCP Marketplace from the `MCPs` button in Cascade, or go to `Windsurf Settings` -> `Cascade` -> `MCP Servers`
-- Windsurf also supports file-based config via `~/.codeium/windsurf/mcp_config.json`
-
-Example:
-
-```json
-{
-  "mcpServers": {
-    "audrey-memory": {
-      "command": "npx",
-      "args": ["-y", "audrey"],
-      "env": {
-        "AUDREY_AGENT": "windsurf"
-      }
-    }
-  }
-}
-```
-
-## VS Code Copilot
-
-Official docs: <https://code.visualstudio.com/docs/copilot/chat/mcp-servers>
-
-- VS Code supports MCP servers in chat and local agents
-- Add Audrey through the MCP server UI or a workspace file such as `.vscode/mcp.json`
-
-Example:
-
-```json
-{
-  "servers": {
-    "audrey-memory": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "audrey"],
-      "env": {
-        "AUDREY_AGENT": "vscode-copilot"
-      }
-    }
-  }
-}
-```
-
-## JetBrains AI Assistant
-
-Official docs: <https://www.jetbrains.com/help/ai-assistant/settings-reference-mcp.html>
-
-- Go to `Settings` -> `Tools` -> `AI Assistant` -> `Model Context Protocol (MCP)`
-- Add a server directly, or use JetBrains' `Import from Claude` action if you already have Audrey configured there
-
-Example JSON:
-
-```json
-{
-  "mcpServers": {
-    "audrey-memory": {
-      "command": "npx",
-      "args": ["-y", "audrey"],
-      "env": {
-        "AUDREY_AGENT": "jetbrains"
-      }
-    }
-  }
-}
-```
-
-## Audrey Surfaces To Expect
-
-Once connected, hosts can use:
-
-- Tools: the 19 `memory_*` Audrey tools, including `memory_preflight` and `memory_reflexes`
-- Resources: `audrey://status`, `audrey://recent`, `audrey://principles`
-- Prompts: `audrey-session-briefing`, `audrey-memory-recall`, `audrey-memory-reflection`

package/docs/ollama-local-agents.md

@@ -1,128 +0,0 @@
-# Audrey With Ollama Local Agents
-
-Ollama provides local model inference. Audrey provides long-term memory. Treat Audrey as the memory sidecar that your Ollama-backed agent calls through tools.
-
-This is intentionally host-neutral: the same Audrey data directory can be shared by Codex, Claude Code, Claude Desktop, and a local Ollama agent, or isolated per project.
-
-## Start Audrey
-
-```bash
-AUDREY_AGENT=ollama-local-agent AUDREY_EMBEDDING_PROVIDER=local npx audrey serve
-```
-
-Health check:
-
-```bash
-curl http://localhost:7437/health
-curl http://localhost:7437/v1/status
-```
-
-Use `AUDREY_API_KEY` if the sidecar is reachable beyond your local process boundary:
-
-```bash
-AUDREY_API_KEY=secret AUDREY_AGENT=ollama-local-agent npx audrey serve
-```
-
-## Memory Tools To Expose
-
-Expose these Audrey routes as function tools in your local agent loop:
-
-| Tool | Audrey route | Purpose |
-|---|---|---|
-| `memory_preflight` | `POST /v1/preflight` | Check known risks, rules, procedures, and prior failures before tool use |
-| `memory_reflexes` | `POST /v1/reflexes` | Convert preflight evidence into trigger-response rules the agent can automate |
-| `memory_capsule` | `POST /v1/capsule` | Build a compact, ranked context packet for the current task |
-| `memory_recall` | `POST /v1/recall` | Search durable memories |
-| `memory_encode` | `POST /v1/encode` | Store useful observations, decisions, procedures, and preferences |
-| `memory_status` | `GET /v1/status` | Check memory/index health |
-
-Minimum useful loop:
-
-1. Before tool use, call `memory_reflexes` or `memory_preflight` for the proposed action.
-2. If a reflex says `block`, stop and ask for repair or approval.
-3. Before calling Ollama, ask Audrey for a capsule using the user task as the query.
-4. Add the capsule to the model instructions or context.
-5. Let the model call `memory_recall` for details when needed.
-6. After the task, call `memory_encode` for durable facts, decisions, mistakes, procedures, and preferences.
-7. Run `npx audrey dream` on a schedule to consolidate and decay memory.
-
-## Native Ollama Tool Shape
-
-Ollama supports function tools on `/api/chat`. Your agent owns the loop that executes a tool call and sends the result back to the model.
-
-Audrey ships a complete example loop:
-
-```bash
-OLLAMA_MODEL=qwen3 node examples/ollama-memory-agent.js "What should you remember about this project?"
-```
-
-```json
-{
-  "type": "function",
-  "function": {
-    "name": "memory_recall",
-    "description": "Recall Audrey memories relevant to a query.",
-    "parameters": {
-      "type": "object",
-      "required": ["query"],
-      "properties": {
-        "query": {
-          "type": "string",
-          "description": "Search query for durable memory."
-        },
-        "limit": {
-          "type": "number",
-          "description": "Maximum results to return."
-        }
-      }
-    }
-  }
-}
-```
-
-Tool executor:
-
-```js
-export async function memoryRecall({ query, limit = 5 }) {
-  const response = await fetch('http://localhost:7437/v1/recall', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ query, limit }),
-  });
-  if (!response.ok) {
-    throw new Error(`Audrey recall failed: ${response.status}`);
-  }
-  return response.json();
-}
-```
-
-## OpenAI-Compatible Ollama Mode
-
-Ollama also exposes an OpenAI-compatible API at `http://localhost:11434/v1/`. If your local agent framework already knows how to call OpenAI-style tools, point the model client at Ollama and keep Audrey as the tool executor.
-
-The important separation is:
-
-- Ollama answers with local models.
-- Audrey remembers, recalls, reconciles, and consolidates.
-- The agent loop decides when a model tool call should hit Audrey.
-
-Official Ollama references:
-
-- Native tool calling: <https://docs.ollama.com/capabilities/tool-calling>
-- OpenAI-compatible API: <https://docs.ollama.com/openai>
-
-## Data Layout
-
-For shared memory across hosts:
-
-```bash
-AUDREY_DATA_DIR=$HOME/.audrey/data
-```
-
-For project-local memory:
-
-```bash
-AUDREY_DATA_DIR=.audrey-data
-```
-
-Shared memory is better for personal continuity across Codex, Claude, and local agents. Project-local memory is better when clients, repositories, or experiments must not bleed into each other.

package/docs/production-readiness.md

@@ -1,128 +0,0 @@
-# Audrey Production Readiness
-
-Audrey is ready to be the memory layer inside a production agent system, but it is not a complete regulated-platform package by itself. Treat it as stateful infrastructure: pin providers, isolate tenants, monitor health, and wrap it with the controls your environment requires.
-
-First contact should now go through `npx audrey doctor`, then `npx audrey install --host <host> --dry-run` for local MCP hosts, `npx audrey install` for Claude Code specifically, or `npx audrey serve` for the sidecar path. Run `npx audrey status --json --fail-on-unhealthy` before exposing Audrey to real traffic.
-
-## Best Vertical Fit
-
-### 1. Financial Services Operations
-
-Best fit:
-
-- Payments operations copilots
-- Fraud and dispute investigation agents
-- KYC/KYB review assistants
-- Internal support agents that need durable incident and policy memory
-
-Why Audrey fits:
-
-- Contradiction tracking helps surface conflicting customer, tool, and policy evidence.
-- Confidence scoring and source lineage make escalations more reviewable.
-- Local SQLite storage keeps memory close to the application boundary.
-- Dream-cycle consolidation turns repeated incidents into reusable operational principles.
-
-Guardrails:
-
-- Do not store PAN, CVV, raw bank credentials, or secrets in memory.
-- Isolate memory stores by environment, customer, and business unit.
-- Keep export and purge paths in your incident-response runbook.
-- Add encryption at rest and backup retention outside Audrey.
-
-### 2. Healthcare Operations
-
-Best fit:
-
-- Care coordination assistants
-- Prior-authorization workflow agents
-- Intake, referral, and scheduling copilots
-- Internal knowledge assistants for clinical operations teams
-
-Why Audrey fits:
-
-- Longitudinal recall preserves operational context across multi-step handoffs.
-- Private memories support role-specific context without making it part of public recall.
-- Contradiction detection helps catch conflicting workflow instructions and stale operating assumptions.
-- Local embeddings allow offline-first or reduced-data-egress deployments.
-
-Guardrails:
-
-- Audrey is not a medical device and should not be treated as a clinical decision engine.
-- Use de-identified or minimum-necessary data unless the full deployment boundary is HIPAA-ready.
-- Enforce access controls and audit logging in the host application, not just in Audrey.
-- Separate patient-facing and staff-only memory scopes.
-
-## Production Checklist
-
-1. Pin `AUDREY_EMBEDDING_PROVIDER` and `AUDREY_LLM_PROVIDER` explicitly. Do not rely on key-based auto-detection in production.
-2. Set a dedicated `AUDREY_DATA_DIR` per environment and per tenant boundary.
-3. Add a startup check that runs `npx audrey doctor --json`.
-4. Alert on `health.healthy=false` or `health.reembed_recommended=true`.
-5. Schedule `npx audrey dream` during low-traffic windows so consolidation and decay stay current.
-6. Backup the SQLite data directory before changing embedding dimensions or providers.
-7. Treat re-embedding as a controlled maintenance action and validate with `npx audrey status`.
-8. Use `npx audrey install --host <host> --dry-run` in deployment docs so operators can preview host config without accidental writes.
-9. Keep API keys, bearer tokens, and raw credentials out of encoded memory content.
-10. Decide whether `private` memories are allowed for your use case and document who can create them.
-11. Add application-level encryption, access control, logging, and retention policies around Audrey.
-12. On graceful shutdown paths, call `await brain.waitForIdle()` before `brain.close()` so tracked background work drains cleanly.
-
-## Operations Commands
-
-```bash
-# First-contact diagnostics
-npx audrey doctor
-npx audrey doctor --json
-
-# Human-readable health
-npx audrey status
-
-# Monitoring-friendly health
-npx audrey status --json
-
-# Fail the process if the index is unhealthy or unreadable
-npx audrey status --json --fail-on-unhealthy
-
-# Nightly memory maintenance
-npx audrey dream
-
-# Repair vector/index drift after provider or dimension changes
-npx audrey reembed
-```
-
-## Example Deployment Pattern
-
-Use Audrey as a local sidecar to the agent service:
-
-- One Audrey data directory per tenant or deployment shard
-- Health checks wired to `status --json`
-- Scheduled dream/reembed jobs
-- Backups handled by the host platform
-- Regulated-data filtering handled before `memory_encode`
-
-That keeps Audrey focused on memory integrity while the host system owns compliance, tenancy, and transport security.
-
-## Docker Deployment
-
-Audrey now ships with a first-party container path for the REST API:
-
-```bash
-docker compose up -d --build
-```
-
-Operational notes:
-
-- The container persists SQLite data in the named volume `audrey-data`.
-- Set `AUDREY_API_KEY` before exposing the service beyond localhost.
-- For CI or very fast smoke checks, prefer `AUDREY_EMBEDDING_PROVIDER=mock` and `AUDREY_LLM_PROVIDER=mock`.
-- For stable local/offline container use, keep `AUDREY_EMBEDDING_PROVIDER=local` and `AUDREY_DEVICE=cpu`.
-- If you map the service to a different host port, keep the container port at `3487`.
-
-Suggested smoke check:
-
-```bash
-AUDREY_API_KEY=secret docker compose up -d --build
-curl -H "Authorization: Bearer secret" http://localhost:3487/health
-curl -H "Authorization: Bearer secret" http://localhost:3487/status
-docker compose logs --tail=100 audrey
-```