Audrey
About
Persistent memory and continuity engine for Claude Code and AI agents.
Details
- License
- MIT
Explore
- Local‑first, no cloud or account required.
- SQLite‑backed memory with semantic recall via sqlite‑vec.
- Preflight checks (allow/warn/block) before tool execution.
- Supports Codex, Claude Code, Cursor, Ollama, and custom agents.
- MCP stdio server, REST API, CLI, and JavaScript/Python SDKs.
- Memory model with episodic, semantic, procedural, decay, and contradiction handling.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
AudreyCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Requires Node.js 20+.
npx audrey doctor
npx audrey demo --scenario repeated-failure
npx audrey guard --tool Bash "npm run deploy"
doctor verifies Node, the MCP entrypoint, provider selection, memory-store health, and host config generation. The repeated-failure demo is no-key, no-host, and no-network: it creates a temporary store, records a failed deploy, teaches Audrey the fix, then shows Audrey Guard blocking the repeat attempt with evidence.
Expected first-run shape:
Audrey Doctor v1.0.2
Store health: not initialized
Verdict: ready
After the first real memory write, doctor should report the store as healthy.
Preview host setup without editing config files:
npx audrey install --host codex --dry-run
npx audrey install --host claude-code --dry-run
npx audrey install --host generic --dry-run
Generate raw config blocks:
npx audrey mcp-config codex
npx audrey mcp-config generic
npx audrey mcp-config vscode
npx audrey hook-config claude-code
Claude Code can be registered directly:
npx audrey install
claude mcp list
For memory-before-action hooks, preview with npx audrey hook-config, then apply with
claude-codenpx audrey hook-config claude-code --apply for
--scope project.claude/settings.local.json or --scope user for
~/.claude/settings.json. Audrey merges the hook block into existing settings
and writes a timestamped backup before changing a non-empty file. The generated
PreToolUse hook runs audrey guard --hook --fail-on-warn; the PostToolUse
and PostToolUseFailure hooks record redacted tool traces. Verify the active
hook set inside Claude Code with /hooks.
All local MCP paths default to local embeddings and one shared SQLite-backed memory directory. Set a distinct AUDREY_DATA_DIR per tenant, agent identity, or concurrent host. SQLite uses WAL mode without an advisory lock, so two processes sharing a directory will contend on writes. Isolation is a hard requirement for multi-agent setups, not a recommendation.
Installer-generated host config does not include provider API keys by default. Prefer setting ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_API_KEY, or GEMINI_API_KEY in the host runtime environment; use npx audrey install --include-secrets only if you explicitly accept argv/config exposure.
| Variable | Default | Purpose |
|---|---|---|
| AUDREY_DATA_DIR | ~/.audrey/data | SQLite memory store path. Use one per tenant or agent identity for isolation. |
| AUDREY_AGENT | local-agent | Logical agent identity stamped on writes. |
| AUDREY_EMBEDDING_PROVIDER | local | local, gemini, openai, or mock. Cloud providers require explicit opt-in. |
| AUDREY_LLM_PROVIDER | auto | anthropic, openai, or mock. |
| AUDREY_DEVICE | gpu | Local embedding device (gpu or cpu). Falls back to CPU if GPU init fails. |
| AUDREY_PORT | 7437 | REST sidecar port. |
| AUDREY_HOST | 127.0.0.1 | REST sidecar bind address. Set to 0.0.0.0 only with AUDREY_API_KEY. |
| AUDREY_API_KEY | unset | Bearer token required for non-loopback REST traffic. |
| AUDREY_ALLOW_NO_AUTH | 0 | Set to 1 to allow non-loopback bind without an API key. Don't. |
| AUDREY_ENABLE_ADMIN_TOOLS | 0 | Set to 1 to enable export, import, and forget routes/tools. Disabled by default. |
| AUDREY_PROMOTE_ROOTS | unset | Colon/semicolon-separated extra roots for audrey promote --yes writes. By default writes are restricted to process.cwd(). |
| AUDREY_DEBUG | 0 | Set to 1 to print MCP info logs (server started, warmup completed). Errors always log. |
| AUDREY_PROFILE | 0 | Set to 1 to emit per-stage timings via MCP _meta.diagnostics. |
| AUDREY_DISABLE_WARMUP | 0 | Set to 1 to skip background embedding warmup at MCP boot. |
| AUDREY_ONNX_VERBOSE | 0 | Set to 1 to restore ONNX runtime EP-assignment warnings (suppressed by default). |
| AUDREY_PRAGMA_DEFAULTS | 1 | Set to 0 to revert SQLite PRAGMA tuning to better-sqlite3 defaults. |
| AUDREY_CONTEXT_BUDGET_CHARS | 4000 | Default Memory Capsule character budget. |
npx audrey install --host codex --dry-run
npx audrey mcp-config codex
npx audrey mcp-config generic
npx audrey hook-config claude-code
npx audrey install
npx audrey uninstall
npx audrey observe-tool --event PostToolUse --tool Bash --outcome failed
npx audrey promote --dry-run
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"audrey": {
"audrey-memory": {
"command": "npx",
"args": [
"-y",
"audrey",
"mcp"
],
"env": {
"AUDREY_EMBEDDING_PROVIDER": "mock"
}
}
}
}
}McpServers
{
"audrey-memory": {
"command": "npx",
"args": [
"-y",
"audrey",
"mcp"
],
"env": {
"AUDREY_EMBEDDING_PROVIDER": "mock"
}
}
}edit AUDREY_API_KEY in .env
docker compose up -d --build
The Node sidecar defaults to 127.0.0.1:7437. The Docker image intentionally binds inside the container on 3487, so Compose requires AUDREY_API_KEY in .env before startup. Override the published host port with AUDREY_PUBLISHED_PORT when using Compose.
Documentation
- Security policy
- Audrey paper outline
- Public setup, runtime, benchmark, and command guidance is maintained in this README.
Development
Developer setup runs from source, not from the published tarball, so npm run build is required before any CLI subcommand resolves:
npm ci
npm run build
npm run lint # ESLint (type-checked typescript-eslint); CI requires it clean
npm run format # Prettier; use
npm run format:check to verify without writingnpm test
Once built, the Quick Start commands work against the local dist/ output. Code style and types are enforced: npm run lint and npm run format:check run in CI (Ubuntu + Windows) and in every release gate, so the baseline cannot regress. The full release gate runs everything CI runs:
npm run release:gate
python -m unittest discover -s python/tests -v
npm run python:release:check
``
npm test uses a repo-local Vitest launcher so locked-down Windows temp
directories do not block test startup. npm run release:gate:sandbox` remainsavailable for hosts that block child-process spawning entirely.
License
MIT. See LICENSE.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
