audrey — Claude Code MCP server: what it does, how to install
Local memory engine for coding agents. It recalls past session failures and intercepts risky commands with a Guard check before execution.
claude mcp add --env AUDREY_DATA_DIR=<AUDREY_DATA_DIR> --env AUDREY_AGENT=<AUDREY_AGENT> --transport stdio audrey -- npx -y audreyWhat audrey does
Audrey maintains project context across independent agent sessions. When a new run opens, it injects a concise briefing with known project rules and recent hazards. During user prompts, durable instructions like "remember that" turn into persistent records.
The core mechanism is the Guard pre-action check. Before an agent executes a shell command or edits files, Audrey evaluates the fingerprint against recorded historical failures. If an identical command failed previously, Guard blocks execution with evidence. Meanwhile, benign inspection commands such as grep, git status, or cat pass through silently without triggering false alerts.
Runtime requirements are strict: Node.js 22.16+ or 24+ is mandatory because storage relies on Node's built-in SQLite engine. By default, hook timeouts or internal errors fail open so sessions do not freeze, but setting AUDREY_HOOK_FAIL_CLOSED=1 enforces strict blocking instead.
What it helps with
- prevent agents from running previously failed build or deploy scripts
- retain repository conventions across brand-new agent sessions
- block accidental commits of generated files before actions execute
- filter out harmless read-only terminal commands from error tracking
Example prompts for the agent
- Remember that we must generate the database client before running migrations.
- Check the repository status and run the test deployment.
- Do not commit auto-generated configuration files in this project.
How to install audrey
Platform CLI
claude mcp add --env AUDREY_DATA_DIR=<AUDREY_DATA_DIR> --env AUDREY_AGENT=<AUDREY_AGENT> --transport stdio audrey -- npx -y audreyReplace <…> with your own values
Platform CLI
codex mcp add audrey --env AUDREY_DATA_DIR=<AUDREY_DATA_DIR> --env AUDREY_AGENT=<AUDREY_AGENT> -- npx -y audreyReplace <…> with your own values
Config file
{
"mcpServers": {
"audrey": {
"command": "npx",
"args": [
"-y",
"audrey"
],
"env": {
"AUDREY_DATA_DIR": "<AUDREY_DATA_DIR>",
"AUDREY_AGENT": "<AUDREY_AGENT>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"audrey": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"audrey"
],
"env": {
"AUDREY_DATA_DIR": "<AUDREY_DATA_DIR>",
"AUDREY_AGENT": "<AUDREY_AGENT>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e AUDREY_DATA_DIR=<AUDREY_DATA_DIR> -e AUDREY_AGENT=<AUDREY_AGENT> audrey npx -y audreyReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about audrey
How do I install audrey in Claude Code?
Run claude mcp add audrey -- npx -y audrey in your terminal. If you need custom storage paths, run claude mcp add --env AUDREY_DATA_DIR=<AUDREY_DATA_DIR> --env AUDREY_AGENT=<AUDREY_AGENT> --transport stdio audrey -- npx -y audrey.
What is the role of Guard in audrey?
Guard inspects proposed tool actions against recorded failures and project constraints before execution. When it detects an identical failed command, it denies the operation and returns the stored evidence.
What happens if audrey encounters a timeout during a check?
Checks carry a 30-second window and fail open by default, letting the tool proceed if Audrey times out. You can force strict denials on failures by configuring the AUDREY_HOOK_FAIL_CLOSED=1 environment variable.
