Audrey

<div align="center">
  <img src="docs/assets/audrey-wordmark.png" alt="Audrey" width="720">

  <p><strong>Memory that shows up before your coding agent makes the same mistake twice.</strong></p>

  <p>
    Audrey gives Codex and Claude Code one local, evidence-backed memory loop:
    remember what mattered, recall it automatically, check before acting, and learn from what happened next.
  </p>

  <p>
    <a href="https://github.com/Evilander/Audrey/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Evilander/Audrey/actions/workflows/ci.yml/badge.svg?branch=master"></a>
    <a href="https://www.npmjs.com/package/audrey"><img alt="npm version" src="https://img.shields.io/npm/v/audrey.svg"></a>
    <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
  </p>
</div>

## Your agent should remember the work, not just the chat

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.

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.

## Meet Audrey Autopilot

Install Audrey once, review the hooks once, and then use Codex or Claude Code normally.

```bash
npm install -g audrey --allow-scripts=better-sqlite3,onnxruntime-node,sharp,protobufjs
audrey install --host auto
```

The explicit install-script list is for npm 12's safer dependency policy. It permits only the four packages Audrey needs for SQLite, local inference, and their generated runtime files. With npm 11 or earlier, the shorter `npm install -g audrey` is equivalent.

`auto` configures whichever supported CLIs are installed. You can choose one explicitly:

```bash
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:

| Moment | What Audrey does |
|---|---|
| Session starts | Injects a compact, agent-scoped memory briefing |
| You send a prompt | Recalls relevant evidence; explicitly durable phrases such as “remember that…” or “I prefer…” can become memories |
| Bash/edit/write is proposed | Checks exact prior failures, trusted rules, procedures, contradictions, and memory health |
| The tool finishes | Correlates `tool_use_id` to the Guard receipt and records the redacted outcome |
| A tool failure is reported | Forms a durable, sanitized failure memory for the next attempt |
| The turn stops or context compacts | Runs lightweight, due-only consolidation without holding the conversation open |

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.

## A small story about a failed deploy

The first attempt fails:

```text
$ 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:

```bash
audrey demo --scenario repeated-failure
```

## What Audrey remembers

Audrey treats memory as more than a pile of text chunks.

- Episodes are things that happened: a user decision, a tool result, a project fact, a preference.
- Semantic memories are principles supported by accumulated evidence.
- Procedural memories are ways of acting: how to retry, verify, avoid, or recover.
- Contradictions stay visible instead of being silently overwritten.
- Confidence changes with source quality, evidence, age, retrieval, interference, context, and feedback.
- Low-value memories decay; repeated evidence can consolidate into longer-lived knowledge.

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.

## When a memory stops being true

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.

```bash
audrey ground
```

```text
[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.

## Everything it does, and when you'd actually use it

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.

| What | When you want it | Why it helps | How |
|---|---|---|---|
| **Autopilot** | Always, after one install | The whole point. Memory arrives before the agent acts instead of after you notice it went wrong. | `audrey install --host auto`, restart the host, approve hooks once |
| **Guard** | Automatic, before any bash/edit/write | Checks the exact action fingerprint against prior failures. Not "something like this broke once" — this exact command, still broken. | Runs at `PreToolUse`. Manually: `audrey guard --tool Bash --strict` |
| **Grounding** | After deleting or renaming things a memory might mention | Confidence tells you a memory is well-sourced. Grounding tells you it is still true. A note about a script you deleted is confident and wrong. | `audrey ground`, or let the maintenance sweep do it |
| **Session briefing** | Automatic at session start | Small, scoped packet instead of pasting context every time. Each memory injects once per session, not every prompt. | `SessionStart` hook. Preview with `audrey greeting` |
| **Explicit capture** | When you say "remember that…" or "I prefer…" | Deliberate memories are worth more than inferred ones, and phrasing it that way is enough. | Just type it. Autopilot picks up those sentence shapes |
| **Consolidation** | Automatic when idle; manually before a long break | Repeated episodes become one principle. Otherwise the store is a pile of near-duplicates and recall gets noisy. | `audrey dream` |
| **Contradictions** | When two memories disagree | Neither one silently wins. Both stay visible and labeled until something resolves them. | Surfaced in packets; `memory_resolve_truth` to settle one |
| **Decay** | Automatic | Low-value memories fade. Reinforced ones stick around. Runs in the same sweep as consolidation. | Part of `audrey dream` |
| **Promote** | When a pattern deserves to be a repo rule | Moves a learned habit out of memory and into a file your team can read and review. | `audrey promote --dry-run` firs