Potencia tu agente
El comando propio del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
npx -y [email protected]Claude Code no tiene enlace de instalación para un comando local. Copia el comando de abajo y ejecútalo en una terminal.
claude mcp add audrey -- npx -y audrey@2.1.1Ejecútalo en una terminal.
{ "mcpServers": { "audrey": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
You fix the deploy command on Monday. On Thursday, a fresh session tries the broken version again.
You explain that this repository never commits generated files. The next agent helpfully commits them.
You discover a subtle migration rule, write it down somewhere, and still have to remember to paste it into every new conversation.
Automatic, evidence-backed memory and pre-action Guard for Codex, Claude Code, and custom AI agents
That is the gap Audrey closes.
Audrey sits beside the agent and participates in the work automatically. At the start of a session it brings back a small, relevant memory packet. When you submit a prompt, it recalls project facts, preferences, procedures, and recent risks. Before a side-effectful tool runs, Audrey checks the proposed action against prior evidence. Afterward, it links the outcome back to the exact check that preceded it.
The model does not have to remember that a memory tool exists. That is the point.
Install Audrey once, review the hooks once, and then use Codex or Claude Code normally.
npm install -g audrey
audrey install --host auto
Requires Node.js 22.16+ (22.x) or 24+. SQLite is built into Node, so fresh installs and npx launches work without approving dependency scripts. npm 11.17+ may warn about dependency scripts, and npm 12 may report that it blocked them; those scripts are not required for Audrey's CPU embedding runtime.
auto configures whichever supported CLIs are installed. You can choose one explicitly:
audrey install --host codex
audrey install --host claude-code
Restart the host after installation. Codex asks you to trust non-managed hooks once through /hooks; Claude Code may also ask you to approve project or plugin components. Audrey is automatic after that explicit install-and-trust step—never secretly installed.
Autopilot then closes the loop:
Each hook event carries a host-declared timeout (30 seconds for the PreToolUse Guard check); Audrey races its own internal embedding/LLM timeout a few seconds ahead of that deadline so it can exit cleanly instead of losing the race to the host's kill. Infrastructure failures are fail-open by default: if Audrey itself errors or runs out of time, the tool call proceeds unguarded rather than freezing the session. Set AUDREY_HOOK_FAIL_CLOSED=1 to deny the action instead when the PreToolUse check fails this way; other lifecycle hooks (session start, prompt recall, post-tool bookkeeping) have no "deny" to fall back to and always degrade open regardless of this setting.
The first attempt fails:
$ npm run deploy
Error: deployment target is missing
Audrey keeps a redacted trace and the exact action fingerprint. If another session proposes the same action before the problem is fixed, Guard returns a denial with evidence. Change the command or fix the target and Audrey lets the work continue. Once that exact action succeeds, the old failure no longer blocks it.
This is more useful than “the vector search found a vaguely similar error.” Audrey creates a receipt before the action, records what happened after it, and preserves the lineage between the two.
Try the complete loop without an API key or network call:
audrey demo --scenario repeated-failure
Between the failed deploy and the retry, an agent runs a lot of commands that cannot change anything: grep for the error, git status, cat on a config file, ls on a directory that turns out not to exist. A memory system that treats every one of those as a risk, or remembers grep finding nothing as a "failure", becomes a smoke alarm that goes off when you make toast. People stop listening, and then it is worth nothing on the day the toaster is on fire.
Audrey reads the command the way an engineer would. A command whose every part is positively recognised as read-only (grep, git log, npm view, docker ps, sed -n '1,40p', and their kind, with no command substitution, no redirect except to /dev/null, no sudo or xargs, no environment assignment that could change what the verb resolves to) never reaches the Guard at all. Its exit code is recorded but never counted as a lesson. Everything else is guarded exactly as before, and anything Audrey cannot positively recognise is treated as doing.
$ grep -rn "prisma" src/ Guard: silent
$ git status --short Guard: silent
$ cat prisma/schema.prisma Guard: silent
$ npm run deploy
Audrey Guard: BLOCKED
- recent_failure (high): This exact Bash action failed before: Prisma client was not generated. Run npm run db:generate before deploy.
- must_follow (high): Before running npm run deploy, run npm run db:generate because Prisma client must be generated first.
That is the output of audrey demo --scenario repeated-failure, which runs the whole sequence with no API key and no network.
When Guard does speak, it names the memory it is speaking from, and a remembered failure is matched to the proposed command by what it runs (npm run deploy against npm run deploy), not by how similar two strings look to an embedding.
Commands with execution-capable options or lifecycle scripts are guarded, including git ls-remote --upload-pack=..., npm pack --dry-run, and ss -K. The classifier is a convenience for ordinary inspection commands, not an operating-system sandbox. Repository configuration, shell expansion, and programs invoked by a reader can change what a command does. Use host permissions or a sandbox when enforcement is required.
Audrey treats memory as more than a pile of text chunks.
Every context packet includes memory IDs, confidence, provenance where available, and a reason for inclusion. Uncertain or disputed memories are labeled as such. Retrieved content is wrapped with a simple rule: memory is evidence, not authority; current system and user instructions always win.
Age is not the only way a memory goes wrong. A note saying "ship with npm run deploy:prod" is perfectly recent, well sourced, and completely wrong the day that script is deleted. Worse, every recall reinforces it, because retrieval counts as evidence that a memory is useful. A confidently stated, well-supported, false instruction is more damaging than no memory at all.
So Audrey checks. When a memory is written, it records the claims inside it that can be verified against the project — repository-relative paths and package script names — and keeps only the ones that resolve at that moment. That last part is what makes the signal worth anything: a claim that never resolved is a guess about a typo, while a claim that resolved once and no longer does is the world moving out from under a memory that still asserts it.
audrey ground
[audrey] Grounding memories against /home/you/project
[audrey] Checked 14: 12 still true, 2 broken, 0 repaired.
[audrey] 01K8ZQ... references a missing npm_script: deploy:prod
[audrey] 01K8ZR... references a missing path: scripts/release.mjs
Broken memories are not deleted. They keep their content, say plainly what they still refer to, and take a confidence penalty so they stop leading by default while remaining readable and repairable. They also stop being eligible for the packet's must-follow section — that is the section that can force a Guard block, and a rule naming a file that no longer exists is a rule nobody can follow.
Repair is symmetric. Restore the file or the script and the next check clears the flag. A checkout that has moved reports unknown rather than broken, because a memory should not be discredited for describing a project this machine cannot currently see.
Memories with no checkable claims are left unlabeled. Silence is not a clean bill of health, and presenting it as one would be the same mistake pointed the other way.
Most of this runs on its own once Autopilot is installed. You do not invoke recall, and you do not invoke Guard. The table is here for the parts you would reach for deliberately, and so the automatic parts are legible rather than magic.
Audrey does not upload your memory to a hosted service by default. It does not treat every sentence as permanent truth. It does not promote instructions from arbitrary tool output into trusted policy. It does not claim that a small local benchmark proves state-of-the-art memory quality.
Raw prompt events and tool bodies are not retained by default. Audrey stores hashes, bounded summaries, fingerprints, and redaction metadata. Explicit user-memory language is persisted intentionally; tool failure memories are sanitized first. Admin export/import/forget/promote surfaces are disabled unless AUDREY_ENABLE_ADMIN_TOOLS=1.
At-rest encryption, identity-bound tenant authorization, rate limiting, and regulated retention remain deployment responsibilities today. They are not hidden behind a “production ready” badge.
Guard checks memory at the point where it can change an action, not after the damage is done. Exact failure fingerprints avoid the noisy “one Bash command failed, so all Bash commands are suspicious” behavior.
Audrey is not tied to one model vendor. Codex and Claude Code use the same memory runtime and the same evidence contract. MCP, REST, JavaScript, and Python clients make the core usable in custom agents too.
Allow, warn, and block decisions carry receipts and evidence IDs. Outcome records connect back to those receipts. Teams can ask not only “what did the agent remember?” but “which memory changed this action, and was that useful?”
The default store is SQLite, FTS5, and sqlite-vec. Local embeddings are the default. Cloud embedding or LLM providers require explicit configuration.
Agent-scoped recall continues through validation, contradiction detection, interference, affect, failure lookup, capsules, greetings, Guard, and REST request routing. Recall updates retrieval bookkeeping for its returned results (usage count and last-reinforced timestamp for semantic and procedural memories). Capsule and Guard filtering may further narrow those results. Explicit validation feedback (memory_validate / /v1/validate) separately adjusts salience based on how a memory actually performed, not merely on being recalled.
Vector candidates are partitioned by agent before nearest-neighbor ranking, so one busy agent cannot crowd another out of a bounded search. For hard tenant boundaries, still use a distinct AUDREY_DATA_DIR per tenant or security domain.
npm exec --yes --package=audrey -- audrey demo --scenario repeated-failure
That command runs from the npm cache, exercises the full SQLite-backed Guard loop, and leaves host configuration unchanged.
The ambition is a temporal evidence graph for agents: immutable observations, explicit validity windows, source trust, evolving claims, scoped procedures, and outcome-calibrated policy. The defensible part is not storing more text. It is knowing what was believed, why, in which context, for how long, and whether acting on it helped.
Near-term work includes durable background cognition jobs, tenant namespaces bound to credentials, memory quarantine and taint propagation, public long-horizon evaluations, encrypted backup options, and a persistent local daemon that removes per-hook model startup entirely.
If that is the kind of agent infrastructure you want to build, open an issue or start with the demo. Audrey is MIT licensed, and the product boundary is intentionally inspectable.
Everything below is the machinery. The short version above is the product.
audreyaudrey-memorysqlite-vecnpm install audrey
pip install audrey-memory
Audrey uses node:sqlite; sqlite-vec ships its extension in platform packages. The local embedding runtime also includes its CPU binaries, so npm install --ignore-scripts audrey works. Keep optional dependencies enabled: they contain the platform files for sqlite-vec and sharp. GPU acceleration may require additional ONNX Runtime libraries for your platform. Some supported Node releases print an experimental SQLite warning at startup; it does not prevent operation.
For Autopilot, prefer a global or otherwise stable installation. Hook and MCP configuration pins the actual Node executable and Audrey entrypoint; an ephemeral npx cache is not a durable production runtime.
Preview or apply lifecycle hooks independently:
audrey hook-config claude-code
audrey hook-config claude-code --apply --scope local
audrey hook-config claude-code --apply --scope project
audrey hook-config claude-code --apply --scope user
audrey hook-config codex
audrey hook-config codex --apply --scope project
audrey hook-config codex --apply --scope user
Claude Code scope mapping follows the host’s terminology:
local → .claude/settings.local.jsonproject → .claude/settings.jsonuser → ~/.claude/settings.jsonCodex supports project .codex/hooks.json and user ~/.codex/hooks.json; it has no local hook scope. Audrey preserves unrelated hooks, replaces older Audrey-owned handlers, writes a private timestamped backup, and is idempotent on repeat installation. Project-adjacent backup names match *.audrey-*.bak; keep that pattern ignored because a host config can contain unrelated credentials.
Audrey respects CLAUDE_CONFIG_DIR and CODEX_HOME. Generated hooks pin the stable Node executable, Audrey entrypoint, data directory, agent identity, and non-secret provider choices used at install time. With local embeddings, an Autopilot install performs one warmup so the first real hook is not also the first model load; set AUDREY_DISABLE_WARMUP=1 to skip it.
Generate MCP configuration without applying it:
audrey mcp-config codex
audrey mcp-config generic
audrey mcp-config vscode
Remove Audrey-owned MCP registrations and hooks with the same host and scope you installed:
audrey uninstall --host auto --scope user
audrey uninstall --host claude-code --scope local
audrey uninstall --host codex --scope project
Add --dry-run to preview uninstall without changing either host. Add --mcp-only only when you intentionally want to preserve Audrey hooks.
The shared hook adapter normalizes current Codex and Claude Code payloads.
AUDREY_CONTEXT_BUDGET_CHARS (default 4000; Autopilot uses a conservative 3200-character packet unless overridden).Bash, Edit, MultiEdit, Write, NotebookEdit, apply_patch, and every mcp__* tool from connected MCP servers, excluding Audrey's own memory tools so the Guard never guards itself.grep, ls, sed -n, git status, npm ls, and similar; no command substitution, no redirect except to /dev/null, no sudo, xargs, or eval) skips the preflight, and a non-zero exit from it is recorded but never treated as a failure to avoid. Anything the classifier does not recognise is guarded.npm run deploy, git push), not by how similar the two command strings read.session_id + tool_use_id, so parallel tool calls do not attach to the wrong receipt.PostToolUseFailure and Codex responses that explicitly expose a non-zero exit normalize to the same failure path. Current Codex hooks can omit Bash exit status; Audrey records an opaque result as unknown, never as invented success.{} (no opinion, so the tool proceeds). Only PreToolUse changes behavior under AUDREY_HOOK_FAIL_CLOSED=1, emitting a deny decision instead; context-injection and post-tool hooks have no deny path and always emit {}.Codex hook interception is a guardrail, not a complete shell-policy boundary. The current host contract does not intercept every richer unified_exec path and may omit the exit status of silent Bash failures. See the Codex hooks documentation. Use the Guard receipt as evidence, and keep sandboxing, approvals, CI, and deployment controls in place.
import { Audrey, MemoryController } from 'audrey';
const memory = new Audrey({
dataDir: './audrey-data',
agent: 'payments-agent',
embedding: { provider: 'local', dimensions: 384 },
});
await memory.encode({
content: 'Stripe returns HTTP 429 above 100 requests per second.',
source: 'direct-observation',
tags: ['stripe', 'rate-limit'],
context: { service: 'billing' },
});
const capsule = await memory.capsule('increase Stripe throughput', {
scope: 'agent',
budgetChars: 3000,
});
const guard = new MemoryController(memory);
const before = await guard.beforeAction({
action: 'deploy the billing worker',
tool: 'Bash',
command: 'npm run deploy:billing',
cwd: process.cwd(),
});
console.log(before.decision, before.evidenceIds);
await memory.closeAsync();
AUDREY_AGENT=payments-agent audrey serve
curl http://127.0.0.1:7437/health
Core routes:
Use AUDREY_API_KEY for any non-loopback deployment. X-Audrey-Agent scopes encode, recall, capsules, preflight, Guard, consolidation, and greetings inside a trusted deployment; it is a routing header, not an authentication boundary. Bind agent/tenant identity at your gateway rather than trusting an arbitrary public header. Every route also accepts a per-call agent field in the JSON body as a fallback for callers (such as the Python client) that cannot set a header per request; the header wins whenever both are present.
from audrey_memory import Audrey
memory = Audrey(base_url="http://127.0.0.1:7437", agent="payments-agent")
memory_id = memory.encode(
"Stripe returns HTTP 429 above 100 requests per second.",
source="direct-observation",
)
results = memory.recall("Stripe rate limit", limit=5)
memory.close()
The Python package is a client for the REST sidecar; the memory runtime remains in the Node process.
episode
├─ transactional SQLite + vector + FTS write
├─ agent-scoped interference / resonance / validation
├─ reinforcement or contradiction evidence
├─ sleep-time consolidation into semantic or procedural memory
└─ grounding checks that stored claims still hold in the project
query
├─ bounded vector candidates
├─ FTS5 lexical candidates
├─ reciprocal-rank fusion and confidence scoring
├─ context / affect / recency / interference modifiers
└─ final-only retrieval bookkeeping
Agent-scoped vector search uses a native sqlite-vec partition key before nearest-neighbor ranking, not post-filtered whole-store candidates. If fusion underfills, Audrey makes one bounded partition-local retry. Semantic and procedural retrieval counts update only as final results are yielded; deduplicated, over-limit, and unconsumed stream candidates receive no authority boost.
Audrey exposes 23 MCP tools plus status, recent-memory, and principle resources and briefing/recall/reflection prompts. The main groups are:
memory_encode, memory_reflect, memory_observe_toolmemory_recall, memory_capsule, memory_greetingmemory_preflight, memory_guard_before, memory_guard_after, memory_reflexesmemory_consolidate, memory_dream, memory_decay, memory_resolve_truth, memory_groundmemory_validate, memory_promote, memory_forget, memory_export, memory_import, memory_status, memory_introspectThe server also sends host instructions explaining the Guard receipt loop when lifecycle hooks are unavailable.
Provider secrets are never embedded in generated hook commands. --include-secrets applies only to MCP registration; prefer host environment injection or a secret manager.
New local stores use private directory and database permissions on filesystems that support POSIX modes. Existing database and WAL files are restricted on open. Windows and mounted volumes need appropriate operating-system ACLs. Set AUDREY_SHARED_STORE=1 (SDK: sharedStore: true) only when you manage shared access yourself.
Local models download into the per-user cache on first use. Allow that first run to finish before relying on hooks offline. A failed initialization can be retried in the same process. For a system package installed by root, run the initial model load as the desktop user so the cache remains writable.
Snapshot format 2 preserves grounding anchors, their last known state, and consolidation undo journals; older snapshots remain importable. Worktrees share a repository identity for recall, while grounding checks the checkout where an anchor was recorded. Rollback preserves earlier knowledge when undoing a merge. Legacy merges without an undo journal are refused when they cannot be reversed safely.
The REST API requires JSON request bodies and rejects cross-origin browser requests. Unauthenticated requests require a loopback host unless AUDREY_ALLOW_NO_AUTH=1 is explicitly set. Configure AUDREY_API_KEY for network deployments.
AUDREY_DATA_DIR.audrey status --json --fail-on-unhealthy.Local embeddings use Transformers.js 4.3+ with sharp 0.35.4+, resolving the earlier libvips/libheif advisories in the published dependency tree. A hosted embedding provider changes runtime execution but does not remove installed packages. Run npm audit --omit=dev against your installation to check current advisories.
Run the release gates locally:
npm test
npm run bench:memory:check
npm run bench:guard:check
npm run bench:guard:publication:verify
npm run smoke:cli
npm run pack:check
GuardBench currently contains ten local, deterministic pre-action scenarios covering repeated failures, procedures, scope changes, recovery, redaction, conflicting instructions, and noisy stores. The checked-in v1 methodology uses a mock 64-dimensional embedding provider and exists to catch regressions. A perfect local pass is not a claim about real-provider latency or production false-positive rates.
Latest local result in this checkout: 10/10 scenarios passed, 100% prevention rate, 0% false-block rate, 0 raw secret leaks, 0 published artifact leaks, and 3.805ms / 13.445ms p50/p95 Guard latency under the mock-provider methodology.
benchmarks/perf-snapshot.js measures encode and hybrid-recall p50/p95/p99 at configurable corpus sizes with machine and provider provenance. Run it on the hardware and embedding provider you plan to operate; hosted-provider latency is dominated by its network round trip.
The longer-term public evaluation target includes LongMemEval, MemoryAgentBench, and adversarial memory-poisoning cases. Relevant design directions include bitemporal knowledge graphs in Zep/Graphiti, evolving memory organization in A-MEM, and sleep-time agent compute in Sleep-time Compute.
git clone https://github.com/Evilander/Audrey.git
cd Audrey
npm ci
npm run build
npm run lint
npm run format:check
npm test
These commands are intentionally documented because the paper and release evidence ledger verifies them against the public source tree:
npm run bench:guard:zep
npm run bench:guard:external:dry-run
npm run bench:guard:external:evidence
npm run bench:guard:external:evidence:strict
npm run paper:arxiv:compile
npm run paper:arxiv:compile:strict
npm run paper:launch-results
npm run paper:launch-results:strict
npm run release:cut:plan
npm run release:cut:apply
npm run release:readiness
npm run release:readiness:strict
npm run python:release:check
Live Zep runs require ZEP_API_KEY; ZEP_GUARDBENCH_INGEST_DELAY_MS tunes ingestion settling time. The external dry-run matrix proves adapter shape without credentials, while external evidence verification distinguishes pending runs from verified live evidence.
Publication packaging performs an absolute-path sweep, reserves an X URL reserve in social copy, and checks submitted artifact-url targets. Release readiness separately reports source-control state, live remote-head verification, npm registry/auth readiness, and PyPI publish readiness.
MIT licensed. Built for agents that should get better at the work without becoming less accountable.
Automatic, evidence-backed memory and pre-action Guard for Codex, Claude Code, and custom AI agents
{ "mcpServers": { "audrey": { "command": "npx", "args": [ "-y", "[email protected]" ] } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
Audrey se ejecuta localmente por stdio.
Última comprobación: 2026-11-12. Automatic, evidence-backed memory and pre-action Guard for Codex, Claude Code, and custom AI agents