audrey 1.1.2 → 1.2.0

package/docs/PRODUCTION_BACKLOG.md

@@ -1,321 +0,0 @@
-# Audrey Production Backlog
-
-Updated: 2026-07-10 for the Audrey 1.1 Autopilot release candidate.
-
-This file tracks release posture and remaining product work. It is intentionally
-public-safe: it avoids exploit recipes, stale line references, and private
-planning notes.
-
-## Current Release Posture
-
-Audrey 1.0.0 and 1.0.1 remain the published historical baseline. The 1.1.0
-working tree adds automatic Claude Code and Codex lifecycle integration and is
-released only after it passes the full gate:
-
-```bash
-npm run release:gate
-npm run release:gate:paper
-npm run release:cut:plan
-npm run release:readiness
-npm run python:release:check
-npm run smoke:cli
-npm run pack:check
-npm run security:audit
-npx audrey doctor
-npx audrey status --fail-on-unhealthy
-python -m unittest discover -s python/tests -v
-python -m build --no-isolation python
-```
-
-`npm run release:readiness` is intentionally pending-aware. It exits cleanly
-when local code and paper artifacts verify but the final 1.1 release is still
-blocked on source-control release state, GitHub Release object readiness, npm
-registry/auth readiness, PyPI publish readiness, authenticated browser
-publication URLs, live Mem0/Zep evidence, or npm/PyPI account steps. Use
-`npm run release:readiness:strict` only when cutting the actual 1.1 release;
-strict mode must fail until those publish blockers are resolved.
-`npm run release:cut:plan` is the dry-run version/changelog cut. It previews
-the edits that `npm run release:cut:apply -- --target-version 1.1.0` would
-write to `package.json`, `package-lock.json`, `mcp-server/config.ts`,
-`python/audrey_memory/_version.py`, and `CHANGELOG.md`. The changelog plan is
-publishable release-note copy rather than TODO scaffolding, and strict
-readiness rejects placeholder markers if a manual edit reintroduces them.
-
-`npm test` now routes through `scripts/run-vitest.mjs`, which sets `TEMP`,
-`TMP`, and `TMPDIR` to `.tmp-vitest` before Vitest starts. That removes the
-previous locked-down Windows temp-directory startup failure while keeping
-`npm run release:gate:sandbox` available for hosts that block child-process
-spawning entirely.
-
-## Guard Chassis And 1.1 Autopilot
-
-The Guard chassis shipped across the 0.23 and 1.0 lines. Audrey 1.1 adds the
-automatic host loop:
-
-- `audrey install --host auto` discovers installed Claude Code and Codex CLIs,
-  registers the MCP server, and applies host-specific hooks from stable Node
-  and Audrey entrypoints. It preserves unrelated configuration, backs up
-  non-empty files, replaces older Audrey-owned handlers, and is idempotent.
-- One host adapter normalizes session start, prompt submission, pre-tool,
-  post-tool, post-compaction, and stop events. It injects bounded memory,
-  creates Guard receipts, correlates outcomes by `session_id + tool_use_id`,
-  forms sanitized failure memories, and runs maintenance only when due.
-- Codex project and user hooks require one-time review through `/hooks`;
-  Claude Code supports local, project, and user scopes. Hook failures remain
-  fail-open unless `AUDREY_HOOK_FAIL_CLOSED=1` is set.
-
-The underlying Guard chassis includes:
-
-- `src/controller.ts` adds `MemoryController.beforeAction()` and
-  `afterAction()` over the existing tool-trace, reflex, preflight, capsule,
-  validation, and impact primitives.
-- `npx audrey guard --tool <Tool> "<action>"` runs the controller from the
-  terminal, prints a screenshot-friendly guard decision, emits nonzero on
-  `block`, and supports `--json`, `--explain`, `--override`, and
-  `--fail-on-warn`.
-- `npx audrey demo --scenario repeated-failure` is the deterministic
-  no-network demo: a deploy fails once, Audrey records it, the next preflight
-  blocks the repeat with evidence, and `impact` records the helpful validation.
-- `Audrey.encodeBatch()` now uses provider-level `embedBatch()` instead of
-  issuing one embedding call per episode.
-- Guard exact-failure matching redacts before trimming, treats tool names
-  case-insensitively, and includes file scope in the action hash so unrelated
-  edits do not collide.
-- Validation feedback can now bind to the exact `preflight_event_id`, evidence
-  id set, and Guard action fingerprint that surfaced a memory; Audrey rejects
-  lineage claims when the validated memory was not preflight evidence.
-- `npx audrey guard --hook --fail-on-warn` consumes Claude Code `PreToolUse`
-  JSON from stdin and emits the current `hookSpecificOutput.permissionDecision`
-  shape; `npx audrey hook-config claude-code` generates PreToolUse and
-  PostToolUse command hooks, with failed outcomes inferred from the
-  PostToolUse hook payload.
-- `npx audrey hook-config claude-code --apply --scope project|user` now merges
-  those hooks into Claude Code settings, preserves unrelated settings/hooks,
-  dedupes Audrey handlers, and writes a timestamped backup before changing an
-  existing settings file.
-- `npm run bench:guard:check` now publishes local GuardBench comparative
-  numbers for ten pre-action scenarios across Audrey Guard, no-memory,
-  recent-window, vector-only, and FTS-only adapters, including repeated failure
-  prevention, recovered-path suppression, recall degradation, redaction safety,
-  and noisy memory-store control recall.
-- GuardBench now accepts external ESM adapters with `--adapter`, withholds
-  expected decisions/evidence during adapter execution, and emits manifest,
-  raw-output, and machine-provenance artifacts.
-- `npm run bench:guard:adapter-smoke` exercises the external adapter loader
-  through the real CLI path with a credential-free example adapter.
-- `benchmarks/adapters/mem0-platform.mjs` is the first concrete external-system
-  adapter. It uses Mem0 Platform REST APIs with runtime-only `MEM0_API_KEY`,
-  async add/event polling, V2 search, and user-entity cleanup.
-- `npm run bench:guard:mem0` wraps the live Mem0 run in a reproducible external
-  GuardBench evidence bundle with runtime-env checks and
-  `external-run-metadata.json`; `--dry-run` captures the exact command without
-  needing credentials.
-- `npm run release:gate:paper` is the publication gate: it rebuilds, typechecks,
-  refreshes performance and behavioral benchmark outputs, runs GuardBench,
-  syncs README/paper/ledger metrics from JSON artifacts, verifies paper
-  consistency and redaction hygiene, runs the pending-aware 1.1 readiness
-  checklist, then runs the CLI smoke test and npm pack dry-run.
-- Preflight now performs a supplemental tagged control-memory sweep for
-  trusted `must-follow` memories so high-salience rules survive irrelevant
-  memory noise.
-- Recall partial-failure diagnostics now propagate into capsules and strict
-  Guard preflights, so degraded vector/FTS paths become blocking memory-health
-  warnings instead of silent empty context.
-- `/v1/status` and `memory_status` expose the latest recall degradation check
-  with the failing path and error message.
-- `npm test` and `npm run test:watch` use the repo-local Vitest temp launcher,
-  so full Vitest is no longer dependent on a writable user temp directory.
-- `docs/AUDREY_PAPER_OUTLINE.md` defines the publishable Audrey Guard thesis
-  and the GuardBench evaluation plan.
-
-Still not production-complete Guard: hooks can inspect only the lifecycle
-events and tool paths emitted by each trusted host, each event starts a
-short-lived Audrey process rather than using a persistent local daemon, and
-validation feedback is recorded but does not yet tune risk scoring.
-
-## Shipped In The 0.22.2 Correctness Pass
-
-- Two CodeRabbit review passes plus a CodeQL audit landed: see `CHANGELOG.md#0222---2026-05-01`.
-  Net result: every critical and major finding from the first pass was
-  eliminated; the second pass surfaced a duplicate of the `vec_*.state`
-  stale-denormalization bug in `src/interference.ts` and an API-key auth
-  length-leak in `src/routes.ts`, both fixed.
-- `GET /v1/impact` REST route + Python `impact()` on sync and async clients.
-  `analytics()` is now an alias of `impact()`.
-- Python integration tests unskipped; they spin up the real TS REST sidecar
-  and exercise encode → recall → mark_used → impact → snapshot → restore.
-- Legitimate performance benchmarks (`npm run bench:perf-snapshot`) replace
-  the synthetic-baseline SVGs that previously shipped in README.
-
-## Shipped In The 0.22.1 Hardening Pass
-
-- Agent-scoped encode, recall, greeting, capsule, preflight, reflex, and
-  consolidation paths.
-- Admin export, import, and forget tools/routes fail closed unless
-  `AUDREY_ENABLE_ADMIN_TOOLS=1` is set.
-- Snapshot import uses bounded schemas for memory rows, config, events,
-  consolidation history, and content size.
-- Export/import now preserves `memory_events` and consolidated-memory agent
-  ownership.
-- Stored memory content is wrapped as untrusted data before LLM extraction,
-  contradiction, reflection, and rule-promotion prompts.
-- Local embeddings are the default. Cloud embedding providers require explicit
-  `AUDREY_EMBEDDING_PROVIDER`.
-- MCP stdio now exposes memory tools, `audrey://status`, `audrey://recent`,
-  `audrey://principles`, and briefing/recall/reflection prompt templates.
-- Python package metadata builds cleanly as `audrey-memory 0.22.1`.
-- Release scripts separate full CI (`release:gate`) from a reduced gate
-  (`release:gate:sandbox`) for hosts that cannot start Vitest.
-
-## Release Evidence To Keep Current
-
-Before publishing a new npm or Python package, capture:
-
-- `npm run release:gate` on a normal CI host.
-- `npm run release:gate:sandbox` on locked-down local hosts.
-- `npm run release:gate:paper` before publishing the paper, npm package, or
-  public launch posts that quote benchmark numbers.
-- `npm run release:readiness -- --json` to capture the current 1.1 prompt-to-artifact checklist.
-- `npm run release:readiness:strict -- --json` immediately before npm publish, PyPI publish, and browser launch are claimed complete.
-- `npm run release:cut:plan -- --target-version 1.1.0 --json` before applying the final version/changelog bump.
-- `npm run python:release:check` to build wheel/sdist artifacts, inspect package metadata, check for local path leakage, and run `twine check`.
-- `npm run smoke:cli` and `npm run pack:check` to exercise the public CLI and inspect the npm tarball contents.
-- `npm run security:audit`.
-- `npm ci --dry-run`.
-- Direct stdio MCP smoke: initialize, `tools/list`, `resources/list`,
-  `prompts/list`, `resources/read audrey://status`.
-- `npx audrey --version`, `npx audrey doctor --json`, and
-  `npx audrey status --json --fail-on-unhealthy`.
-- Python unit tests and `npm run python:release:check`.
-
-## P0: Next Release Blockers
-
-1. Replace per-event process startup with a persistent local runtime, and add a
-   real-host compatibility matrix that measures cold/warm latency and records
-   which tool paths each supported Claude Code and Codex version emits.
-2. Run the Mem0 Platform and Zep Cloud adapters with real runtime keys,
-   publish their raw per-scenario outputs, then add Letta/Graphiti-style
-   adapters.
-3. Use validation feedback to tune warning priority, recommendation wording,
-   and repeated-risk suppression without giving the model direct policy
-   control.
-4. Add MCP tool-risk policy inputs: descriptor fingerprints, annotation hints,
-   trusted-server status, and descriptor drift warnings.
-
-## Historical 1.0 / Paper Publish Snapshot
-
-The following rows preserve the publication state recorded during the 2026-05-13
-paper pass. They are evidence history, not the current 1.1 release checklist:
-
-- Source control is partially released remotely but not coherent yet: live
-  GitHub refs now show `release/audrey-1.0.0` at `83eb0ad` while `v1.0.0` is
-  still tag object `9a22dca` peeled to older commit `b3430fa`. Reconcile or
-  recreate the tag on the final release commit before treating 1.0 as cut. This
-  sandbox still cannot write `.git` metadata, the local `origin/master`
-  tracking ref is stale versus live `53761da`, and the working tree still has
-  uncommitted release/launch evidence changes. Fetch/reconcile from a
-  credentialed host or a clean temporary clone before treating this checkout as
-  source-control ready.
-- The GitHub tag exists, but the public GitHub Releases API currently returns
-  `404` for `v1.0.0`, and this browser session is not signed into GitHub. Publish
-  a stable GitHub Release from the verified tag and attach or link the paper and
-  submission artifacts before strict readiness can pass.
-- npm publish readiness still needs CLI authentication: `audrey@1.0.0` is not
-  published on the registry and `npm whoami` currently returns E401. The local
-  tarball smoke now passes through `npm run npm:smoke`, including clean-consumer
-  install, ESM import, encode/recall, and both CLI shims.
-- PyPI publish readiness still needs runtime credentials or trusted-publisher
-  evidence for the final `audrey-memory` upload.
-- Browser launch results are still not complete: LinkedIn, Reddit, and Hacker
-  News are submitted and verified, arXiv is account-authorization blocked under
-  support ticket `AH-190018`, and X still needs a logged-in posting session. The
-  first r/LocalLLaMA attempt was removed for insufficient subreddit karma, so
-  the recorded Reddit launch URL is now the rule-checked r/ClaudeCode Showcase
-  post. Audrey-specific Reddit replies in that thread now include the GitHub
-  repo URL, including the PreToolUse/permissions.deny exchange and Moriarty's
-  GuardBench feedback thread. The first Hacker News Show HN path was
-  account-restricted, so the recorded Hacker News launch URL is the verified
-  neutral link submission.
-- Mem0 and Zep GuardBench evidence is still dry-run/pending until
-  `MEM0_API_KEY` and `ZEP_API_KEY` are provided at runtime and strict external
-  evidence passes.
-- npm/PyPI publishing still needs account authentication and OTP handling.
-- Production `npm audit --omit=dev --audit-level=moderate` is clean after the
-  latest transitive `protobufjs` lockfile refresh.
-
-## P1: Product Quality
-
-1. Add `memory_ask` / `recallAuto()` for callers that should not choose a
-   retrieval strategy manually.
-2. Add adaptive hybrid recall weighting behind an environment flag, then compare
-   against the current benchmark output before making it default.
-3. Benchmark `encodeBatch` across mock, OpenAI, and Gemini providers before
-   claiming cloud-provider speedups.
-4. Add a visible `audrey impact` or dashboard story that shows memories used,
-   helpful, wrong, decayed, and promoted over time.
-5. Add install smoke tests for generated Codex, Claude Code, VS Code, Cursor,
-   and Windsurf MCP configs.
-
-## P2: Hardening And Scale
-
-1. Move large local embedding dependencies to optional install paths if package
-   size becomes a distribution blocker.
-2. Add event-log retention controls for long-running tool-trace stores.
-3. Add signed import/export bundles for cross-machine memory transfer.
-4. Cache prepared statements on hot recall paths if production profiling shows
-   SQLite prepare overhead above budget.
-5. Add bitemporal belief fields for facts that change over time.
-
-## Commercial Wedge
-
-The product wedge remains "memory before action": Audrey should prevent agents
-from repeating known bad actions, ignoring known workflows, or acting without
-the context they already earned. The strongest paid surface is likely team
-memory operations: policy editor, memory diff/rollback, audit log, shared
-encrypted stores, hosted relay, CI gates, and support.
-
-## Historical v0.23 Product Direction
-
-A 2026-05-01 audit recommends repositioning Audrey from a generic local
-memory framework to **Audrey Guard** — a local-first memory firewall whose
-single job is to stop AI coding agents from repeating expensive mistakes
-before they touch tools. The core loop already exists in pieces in this
-repo (`observeTool`, `preflight`, `reflexes`, `validate`, `impact`,
-`promote`); the v0.23 work would be making them feel like one product
-loop instead of separate primitives.
-
-Open questions before committing to the rename:
-
-- Is the marketing surface ("memory firewall for coding agents") narrower
-  than the actual product can support across non-coding agents?
-- Does keeping the current "local memory runtime" framing for the OSS core
-  while branding the guard CLI separately give us the same wedge without
-  abandoning existing positioning?
-
-Concrete v0.23 work the audit identified, with shipped items marked:
-
-1. Shipped in 1.1: host hook wiring for Claude Code and Codex so Guard runs
-   automatically before supported tool use and outcomes feed trace/validation
-   surfaces.
-2. Shipped: Memory Controller Layer (`src/controller.ts`) that owns
-   `beforeAction(action) → GuardResult` and
-   `afterAction(outcome) → void` over the existing primitives. This
-   chassis also enables splitting `src/audrey.ts` (now ~1.2K lines) into
-   focused services.
-3. Benchmark the new batched `Audrey.encodeBatch()` path across mock, OpenAI,
-   and Gemini providers before claiming cloud-provider speedups.
-4. Hybrid-recall N+1: batch the FTS-only row loaders in
-   `src/hybrid-recall.ts` by type instead of per-id SELECTs.
-5. Persist recall-degradation history in the event log so status can show more
-   than the latest in-process check.
-6. Move the heavy local embedding dependency
-   (`@huggingface/transformers` + ONNX) to `optionalDependencies` so
-   non-local-provider users don't pay the install size.
-7. Expand FTS-only confidence in hybrid recall through the same
-   confidence/scoring pipeline used by vector candidates.
-8. Add `AUDREY_STRICT_ISOLATION=1` and make strict agent scope the
-   default before team scopes ship.
-
-The "first paid feature" line of work — encrypted blob sync of local
-Audrey stores ("Audrey Cloud Sync") — remains the smallest commercial
-primitive that doesn't require rebuilding the product around hosted Postgres.

package/docs/assets/audrey-logo.svg

@@ -1,45 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="960" height="300" viewBox="0 0 960 300" role="img" aria-labelledby="title desc">
-  <title id="title">Audrey logo</title>
-  <desc id="desc">A luminous memory orb and Audrey wordmark for a local-first AI memory runtime.</desc>
-  <defs>
-    <radialGradient id="orb" cx="42%" cy="35%" r="70%">
-      <stop offset="0%" stop-color="#f7dfad"/>
-      <stop offset="42%" stop-color="#d08f61"/>
-      <stop offset="78%" stop-color="#3b5f72"/>
-      <stop offset="100%" stop-color="#172a31"/>
-    </radialGradient>
-    <linearGradient id="ring" x1="68" x2="242" y1="56" y2="238" gradientUnits="userSpaceOnUse">
-      <stop offset="0%" stop-color="#f2c777"/>
-      <stop offset="50%" stop-color="#78a6ad"/>
-      <stop offset="100%" stop-color="#273d45"/>
-    </linearGradient>
-    <linearGradient id="word" x1="302" x2="814" y1="94" y2="218" gradientUnits="userSpaceOnUse">
-      <stop offset="0%" stop-color="#f4d7a1"/>
-      <stop offset="46%" stop-color="#d08f61"/>
-      <stop offset="100%" stop-color="#85aeb2"/>
-    </linearGradient>
-    <filter id="softGlow" x="-30%" y="-30%" width="160%" height="160%">
-      <feGaussianBlur stdDeviation="8" result="blur"/>
-      <feMerge>
-        <feMergeNode in="blur"/>
-        <feMergeNode in="SourceGraphic"/>
-      </feMerge>
-    </filter>
-  </defs>
-
-  <rect width="960" height="300" rx="36" fill="#0f171a"/>
-  <path d="M54 228C131 266 220 247 274 181C324 120 320 61 270 42C224 25 154 50 103 99C56 144 30 193 54 228Z" fill="#122126"/>
-  <circle cx="158" cy="150" r="74" fill="url(#orb)" filter="url(#softGlow)"/>
-  <path d="M105 163C126 138 151 128 180 134C204 139 219 154 222 177" fill="none" stroke="#f8e7c7" stroke-width="8" stroke-linecap="round"/>
-  <path d="M98 132C123 106 153 98 188 108C214 115 233 132 244 159" fill="none" stroke="#1d3037" stroke-width="10" stroke-linecap="round"/>
-  <path d="M84 190C113 207 145 212 180 205C217 197 247 176 269 142" fill="none" stroke="url(#ring)" stroke-width="5" stroke-linecap="round"/>
-  <path d="M86 109C113 78 149 60 194 57C231 55 261 66 284 90" fill="none" stroke="url(#ring)" stroke-width="4" stroke-linecap="round" opacity="0.85"/>
-  <circle cx="83" cy="190" r="7" fill="#f2c777"/>
-  <circle cx="284" cy="90" r="6" fill="#85aeb2"/>
-  <circle cx="269" cy="142" r="5" fill="#f8e7c7"/>
-
-  <text x="320" y="150" fill="url(#word)" font-family="Georgia, 'Times New Roman', serif" font-size="88" font-weight="700" letter-spacing="-3">Audrey</text>
-  <text x="326" y="198" fill="#c7d0cc" font-family="'Segoe UI', Candara, sans-serif" font-size="24" letter-spacing="4">LOCAL-FIRST MEMORY FOR AGENTS</text>
-  <path d="M327 219H811" stroke="#30484d" stroke-width="2"/>
-  <text x="326" y="250" fill="#8ea19b" font-family="'Segoe UI', Candara, sans-serif" font-size="20">recall / preflight / reflexes / consolidation / one SQLite brain</text>
-</svg>

package/docs/paper/00-master.md

@@ -1,48 +0,0 @@
-# Agent Memory Should Control Tool Use: Audrey Guard and Pre-Action Memory Control
-
-## Abstract
-
-Agent memory should be judged by whether it changes future tool actions, not only by whether it retrieves relevant text. Audrey implements a local-first pre-action memory controller that converts prior tool outcomes, procedures, contradictions, recall health, and redacted traces into auditable `allow`, `warn`, or `block` decisions before an agent acts. The system builds bounded memory capsules, scores preflight risk, generates evidence-linked reflexes, blocks exact repeated failures through deterministic action identity hashing, and closes the loop through post-action validation and impact reporting. This paper frames the scientific category as pre-action memory control and the artifact as Audrey Guard. The Stage-A version reports implemented Audrey evidence: the controller and CLI, redaction-first tool tracing, recall-degradation handling, the canonical 0.22.2 performance snapshot, the current behavioral regression gate output, the local comparative GuardBench run, and the deterministic repeated-failure demo. It also specifies GuardBench as the evaluation methodology for future cross-system comparison.
-
-## Table of Contents and Authoring Status
-
-| Section | File | Status | Owner |
-|---|---|---|---|
-| 0. Master, abstract, status | `00-master.md` | Draft initialized | Codex |
-| 1. Introduction | `01-introduction.md` | Draft complete | Claude strategy, Codex draft |
-| 2. Related Work | `02-related-work.md` | Draft complete | Claude citation strategy, Codex draft |
-| 3. Problem Definition | `03-problem-definition.md` | Draft complete | Codex |
-| 4. Design | `04-design.md` | Draft complete | Codex |
-| 5. GuardBench Specification | `05-guardbench-spec.md` | Draft complete | Claude spec review, Codex draft |
-| 6. Implementation | `06-implementation.md` | Draft complete | Codex |
-| 7. Evaluation | `07-evaluation.md` | Draft complete | Codex with Claude anti-claim review |
-| 8. Discussion and Limitations | `08-discussion-limitations.md` | Draft complete | Claude review, Codex draft |
-| 9. Conclusion | `09-conclusion.md` | Draft complete | Codex |
-| Consolidated v1 master | `audrey-paper-v1.md` | Assembled | Codex |
-| Appendix A. Demo Transcript | `appendix-a-demo-transcript.md` | Draft complete | Codex |
-| Appendix B. Evidence Ledger | `evidence-ledger.md` | Initialized and populated | Codex |
-| References | `references.bib` | Initialized with primary URLs; benchmark citations added | Codex |
-
-## Current Draft Constraints
-
-- Quote benchmark numbers from `benchmarks/snapshots/perf-0.22.2.json`, not the README sample table (Ledger: E28).
-- Treat GuardBench Stage A as a specification contribution plus local comparative result, not completed external-system results.
-- Cite external claims only from primary papers, official documentation, official repositories, or first-party project posts.
-- Keep claims about Audrey tied to evidence-ledger IDs.
-- Keep section-body ledger references while drafting; remove them during final submission polish after claims are stable.
-
-## Assembled Draft Preview
-
-| Order | File | Lines |
-|---|---|---:|
-| Master | `audrey-paper-v1.md` | 921 |
-| 1 | `01-introduction.md` | 27 |
-| 2 | `02-related-work.md` | 47 |
-| 3 | `03-problem-definition.md` | 108 |
-| 4 | `04-design.md` | 162 |
-| 5 | `05-guardbench-spec.md` | 242 |
-| 6 | `06-implementation.md` | 113 |
-| 7 | `07-evaluation.md` | 124 |
-| 8 | `08-discussion-limitations.md` | 61 |
-| 9 | `09-conclusion.md` | 11 |
-| Appendix A | `appendix-a-demo-transcript.md` | 114 |

package/docs/paper/01-introduction.md

@@ -1,27 +0,0 @@
-# 1. Introduction
-
-Tool-using agents fail in ways that ordinary chat-memory evaluation does not measure. They repeat broken shell commands after a previous run already exposed the error. They ignore project-specific setup rules that were learned in an earlier session. They lose the causal link between a failed action and the fix that made a later action safe. They treat degraded retrieval as complete memory and act anyway. In Audrey's repeated-failure demo, an agent first runs `npm run deploy` and fails because the Prisma client was not generated. Audrey records the failed tool event, stores the operational rule, and blocks the same action when it is proposed again. The transcript ends with the intended behavior of pre-action memory control: "Audrey saw the agent fail once. Audrey stopped it from failing twice." (Ledger: E25, E42)
-
-Most memory evaluation frames do not test this behavior. MTEB evaluates text embeddings across retrieval and representation tasks [@muennighoff2023mteb]. LongMemEval evaluates chat assistants on information extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention over long interaction histories [@wu2025longmemeval]. LoCoMo evaluates very long-term conversational memory through question answering, summarization, and multimodal dialogue generation [@maharana2024locomo]. These benchmarks are valuable, but their output target is retrieved context or an answer. They do not ask whether memory changed a future tool action before the action reached the shell, file system, browser, API, or MCP server.
-
-This paper defines pre-action memory control as a distinct systems problem. A controller receives a proposed tool action and remembered state before execution, then returns an auditable `allow`, `warn`, or `block` decision with evidence. Section 3 gives the formal input and output contract, desired behavior properties, threat model, and scope boundaries. The key shift is the evaluation target: memory is judged by its effect on action selection, not only by the relevance of retrieved text.
-
-Audrey Guard is the artifact studied in this paper. It is a local-first memory controller for agents that observes tool outcomes, redacts traces, retrieves relevant memory, constructs a bounded capsule, scores preflight risk, generates reflexes, returns `allow`/`warn`/`block`, and validates whether memory helped after the action path completes (Ledger: E1-E17). The implementation is exposed through MCP, CLI, REST, and Python client surfaces, while the core guard path runs host-side before tool execution (Ledger: E18-E19, E26, E32-E36).
-
-This paper makes six contributions:
-
-1. It formalizes pre-action memory control as a problem separate from chat recall, retrieval accuracy, and long-context question answering (Section 3).
-
-2. It presents Audrey Guard, a local-first controller that converts remembered failures, procedures, contradictions, recall health, and redacted tool traces into `allow`, `warn`, or `block` decisions before tool use (Sections 4 and 6; Ledger: E1-E15, E29-E40).
-
-3. It introduces deterministic action identity for repeated-failure prevention: tool, redacted command, normalized working directory, and sorted file scope are hashed and matched against prior failed tool events (Sections 4, 6, and 7; Ledger: E3, E25, E42).
-
-4. It implements a redaction-first tool-trace path so guard evidence can reference prior tool input, output, and error summaries without storing raw secrets in durable memory (Sections 4 and 6; Ledger: E12-E13).
-
-5. It treats recall degradation as a control signal: missing vector tables, KNN failures, and FTS failures propagate as `RecallError[]`, appear in capsules, and become high-severity preflight warnings under strict guard mode (Sections 4 and 6; Ledger: E7, E9-E10, E15, E40).
-
-6. It specifies GuardBench, a reproducibility contract for measuring whether memory changes future tool actions, including scenarios, baselines, metrics, redaction sweeps, machine provenance, and raw per-scenario outputs (Section 5).
-
-The empirical scope is Stage A. This paper reports implemented Audrey evidence: the controller and CLI guard path, redaction-first tool tracing, recall-degradation handling, the canonical 0.22.2 performance snapshot, the current `bench:memory:check` regression output, the local comparative GuardBench run, and the deterministic repeated-failure demo transcript (Ledger: E20-E26, E41-E42, E46). It does not report external-system GuardBench comparisons, production-load measurements, or real-provider embedding latency. The external adapter contract, Mem0 adapter, and evidence-bundle runner now exist, but live external-system scores belong in a v2 paper after credentialed runs publish raw outputs under the contract in Section 5 (Ledger: E47-E50).
-
-Section 2 positions Audrey against memory systems, memory benchmarks, graph-memory systems, and MCP safety work. Section 3 defines the pre-action memory-control problem. Section 4 describes Audrey Guard's design. Section 5 specifies GuardBench. Section 6 documents the implementation. Section 7 reports Stage-A evaluation artifacts. Section 8 discusses limitations and open problems. Section 9 concludes.

package/docs/paper/02-related-work.md

@@ -1,47 +0,0 @@
-# 2. Related Work
-
-This section organizes prior work by the behavior each system optimizes. The point of comparison is not whether a system has memory. It is whether memory runs before tool use and produces an evidence-linked action decision.
-
-## Conversational and Scalable Memory Systems
-
-Mem0 optimizes scalable long-term memory for multi-session agents. Its paper frames the problem as extracting, consolidating, and retrieving salient information from ongoing conversations, including a graph-memory variant for relational structure, and evaluates on LoCoMo-style conversational memory tasks [@chhikara2025mem0]. Its 2026 algorithm post emphasizes token-efficient retrieval through hierarchical memory, ADD-only extraction, entity linking, and multi-signal retrieval [@mem02026tokenefficient]. Audrey differs at the control boundary: Mem0 optimizes what context to retrieve for response generation, while Audrey evaluates whether remembered context changes a proposed tool action before execution.
-
-MemGPT, now associated with Letta, optimizes virtual context management. The MemGPT paper treats limited context windows as an operating-system-style memory hierarchy problem, moving information between memory tiers so an LLM can operate beyond its immediate context window [@packer2024memgpt]. This is an architectural framing for extended context and multi-session chat. Audrey borrows the systems instinct but changes the target: its controller is not a virtual-context manager for the model; it is a host-side guard that returns `allow`, `warn`, or `block` for a proposed action.
-
-LangMem optimizes memory as a reusable agent-runtime primitive. Its documentation describes tooling for extracting important information from conversations, optimizing agent behavior through prompt refinement, maintaining long-term memory, and providing hot-path memory tools agents can call during active conversations [@langchain2026langmem]. This is close to an agent developer's integration layer. Audrey differs because the guard path does not depend on the language model deciding to call a memory tool; the host asks memory before the tool call proceeds.
-
-Supermemory optimizes a developer memory API and context stack. Its documentation positions the service as long-term and short-term memory and context infrastructure, with ingestion, extraction, graph memory, user profiles, connectors, and managed RAG [@supermemory2026docs]. Its repository describes persistent memory for AI tools and an API that returns user profiles and relevant memories [@supermemory2026repo]. Audrey differs by keeping the pre-action controller local and by treating prior tool outcomes, redaction state, and recall degradation as enforceable control inputs rather than retrieved context alone.
-
-## Memory as System Resource and Graph Systems
-
-MemOS optimizes memory as a system resource. The paper introduces a memory operating system that manages heterogeneous memory forms across temporal scales, with memory units carrying content and metadata such as provenance and versioning [@li2025memos]. This is the broadest systems framing among the related memory papers. Audrey's scope is narrower and more operational: it does not manage parameter-level memories or schedule heterogeneous memory resources; it inserts a local memory-derived decision layer before agent tool use.
-
-Zep optimizes temporal knowledge graphs for agent memory. Its paper presents Graphiti as a temporally aware knowledge-graph engine that synthesizes unstructured conversations and structured business data while maintaining historical relationships, then evaluates retrieval over Deep Memory Retrieval and LongMemEval-style tasks [@rasmussen2025zep]. Audrey uses contradictions, recent tool events, and typed memory, but it does not claim to be a temporal knowledge graph service. Its central output is a guard decision, not a retrieved graph context.
-
-Graphiti optimizes real-time temporal context graphs. Its repository describes context graphs that track how facts change over time, maintain provenance to source data, and support semantic, keyword, and graph traversal retrieval [@zep2026graphiti]. This is valuable for evolving facts and historical queries. Audrey's use of evidence is different: evidence is attached to an action decision and to recommendations that a host can enforce.
-
-Cognee optimizes knowledge infrastructure for agent memory. The Cognee repository describes an open-source memory control plane that ingests data, combines embeddings and graphs, supports local execution, and provides traceability and cross-agent knowledge sharing [@cognee2026repo]. The Cognee paper studies hyperparameter optimization for graph construction, retrieval, and prompting in multi-hop question answering [@markovic2025cognee]. Audrey does not optimize knowledge-graph retrieval quality. It uses local memory to decide whether an agent action should proceed.
-
-## Memory Benchmarks and Evaluation
-
-MTEB optimizes broad evaluation of embedding models. It spans embedding tasks such as retrieval, clustering, reranking, and semantic textual similarity across many datasets and languages [@muennighoff2023mteb]. It is relevant because many memory systems rely on embeddings, but it evaluates representation quality rather than the behavioral effect of memory on a tool-using agent.
-
-LongMemEval optimizes long-term chat-assistant memory evaluation. It tests information extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention across sustained user-assistant histories [@wu2025longmemeval]. GuardBench is orthogonal. It starts after a system has some memory state and asks whether that state changes a future tool action.
-
-LoCoMo optimizes very long-term conversational memory. It provides long dialogues across many sessions and evaluates question answering, event summarization, and multimodal dialogue generation [@maharana2024locomo]. GuardBench does not replace LoCoMo. It tests a separate failure surface: repeated actions, missing procedures, degraded recall, secret redaction, and contradictions at the tool boundary.
-
-MemoryBench optimizes continual-learning evaluation from accumulated user feedback. Its paper argues that many memory benchmarks focus on homogeneous reading-comprehension tasks and introduces a user-feedback simulation framework across domains, languages, and task types [@ai2026memorybench]. Audrey's validation loop is smaller: it records whether a memory was used, helpful, or wrong, then updates salience and bookkeeping (Ledger: E16). GuardBench evaluates the control effect of those memories, not general continual-learning quality.
-
-## MCP Tool Safety and Pre-Action Runtimes
-
-The Model Context Protocol standardizes how clients discover and call tools. The 2025-06-18 schema defines `tools/list`, tool metadata, `tools/call`, input and output schemas, and tool annotations [@mcp2025schema]. MCP creates an interoperable tool surface; it does not define a memory-derived policy for whether a call should happen. Audrey fits beside MCP as a local controller that runs before a host invokes a tool.
-
-MCP Security Bench optimizes evaluation of MCP-specific attacks. It introduces attack categories across task planning, tool invocation, and response handling, and evaluates LLM agents with real benign and malicious MCP tools [@zhang2026mcpsecuritybench]. Audrey is not an MCP attack benchmark and not a complete MCP defense system. It addresses one component inside a defensive host: memory-derived pre-action control with evidence and redaction.
-
-The tool-poisoning paper studies semantic attacks against MCP-integrated systems, including malicious tool descriptors, shadowing through contaminated context, and descriptor changes after approval [@jamshidi2025toolpoisoning]. Audrey's trusted-control-source gate responds to a related risk inside memory: untrusted memories tagged as must-follow are not promoted into control rules (Ledger: E6). This does not solve tool poisoning. It reduces one path by which remembered content becomes operational instruction.
-
-The MCP tool-annotations blog frames annotations as a risk vocabulary. It states that annotations such as read-only, destructive, idempotent, and open-world are hints, not guaranteed descriptions, and that clients should not base tool-use decisions on annotations from untrusted servers [@mcp2026toolannotations]. Audrey's decision layer is complementary: it uses remembered outcomes, procedures, contradictions, and recall health, not only static tool metadata.
-
-## What Is Missing
-
-Across the primary sources reviewed here, memory systems optimize extraction, retrieval, persistence, graph structure, context assembly, personalization, or continual learning. Safety work around MCP optimizes attack detection, tool metadata, and protocol-level risk. The missing evaluation target is action effect: whether memory changes what an agent does next. Audrey implements a redaction-first, evidence-linked, host-side controller that runs before tool use and returns `allow`, `warn`, or `block`; GuardBench specifies how to evaluate that category.

package/docs/paper/03-problem-definition.md

@@ -1,108 +0,0 @@
-# 3. Problem Definition: Pre-Action Memory Control
-
-Long-term memory systems for agents are usually evaluated as retrieval systems: given prior interaction history and a current query, the system returns facts, summaries, graph neighborhoods, or memory-tool results that improve the next model response. Mem0 evaluates scalable conversational memory and token efficiency [@chhikara2025mem0; @mem02026tokenefficient]. MemGPT/Letta frames memory as virtual context management across tiers [@packer2024memgpt]. Zep and Graphiti model changing facts as temporal knowledge graphs [@rasmussen2025zep; @zep2026graphiti]. MemOS treats memory as a manageable system resource [@li2025memos]. LangMem, Supermemory, and Cognee expose memory management, search, and graph/context layers for agents [@langchain2026langmem; @supermemory2026docs; @markovic2025cognee; @cognee2026repo].
-
-Those systems make recall, memory formation, or memory organization the central artifact. This paper studies a different artifact: a controller that runs before an agent uses a tool. The relevant question is not only whether memory returns useful text. The relevant question is whether memory changes the next external action.
-
-## Problem Statement
-
-A tool-using agent repeatedly converts model state into external actions: shell commands, file edits, API calls, browser operations, MCP tool calls, or domain-specific side effects. These actions are not only language outputs. They change local files, spend API budget, mutate remote systems, publish content, delete data, and expose credentials. MCP standardizes tool discovery and invocation through a JSON-RPC protocol surface [@mcp2025schema]. Claude Code hooks expose pre-tool and post-tool extension points around tool calls [@anthropic2026claudecodehooks]. These interfaces make tool use observable and interceptable; they do not by themselves decide whether prior failures, remembered constraints, stale recall, or contradictions should stop the next action.
-
-The pre-action memory control problem is:
-
-Given an intended agent action and a local memory state, return an auditable decision before tool execution: `allow`, `warn`, or `block`, with evidence and repair guidance.
-
-Audrey implements this decision as the `GuardResult` contract with `decision`, `riskScore`, `summary`, `evidenceIds`, `recommendedActions`, `capsule`, `reflexes`, and `preflightEventId` fields (Ledger: E1). Its current controller calls preflight/reflex generation before action, records a preflight event, and scopes recall to the current agent (Ledger: E2). It also records tool outcomes after execution and turns failures into future tool-result memories (Ledger: E4).
-
-## Formal Interface
-
-Let an intended action at time `t` be:
-
-```text
-a_t = (tool, action, command, cwd, files, session_id)
-```
-
-where `tool` names the external capability, `action` is the human-readable intended operation, `command` is the concrete command when present, `cwd` is the execution directory, `files` is the known file scope, and `session_id` identifies the agent session. Audrey represents this shape in `AgentAction` (Ledger: E1).
-
-Let `M_t` be the memory store visible to the agent, `T_t` be the tool-trace event history, and `H_t` be the current recall-health state. A pre-action memory controller is a function:
-
-```text
-G(M_t, T_t, H_t, a_t) -> (d_t, r_t, E_t, R_t, C_t)
-```
-
-where:
-
-- `d_t in {allow, warn, block}` is the action decision.
-- `r_t in [0,1]` is the risk score.
-- `E_t` is a set of evidence identifiers.
-- `R_t` is a set of recommended repair or mitigation actions.
-- `C_t` is an optional memory capsule containing the evidence packet.
-
-The controller is useful only if `d_t` is consumed before the side effect occurs. If the decision is displayed after execution, the system is post-hoc logging, not pre-action control.
-
-After the tool executes, let the observed outcome be:
-
-```text
-o_t = (outcome, output, error_summary, metadata)
-```
-
-where `outcome` includes success, failure, or unknown status. A closed-loop memory controller also defines an update function:
-
-```text
-U(M_t, T_t, a_t, o_t) -> (M_{t+1}, T_{t+1})
-```
-
-Audrey implements this post-action update by recording redacted tool events and encoding failures as tool-result memories for later preflight use (Ledger: E4, E12).
-
-## Desired Behavior Properties
-
-**Pre-action placement.** The controller runs after the agent proposes tool parameters and before the tool runs. Audrey's `beforeAction()` path calls reflex/preflight generation before execution (Ledger: E2). This placement separates memory control from answer generation.
-
-**Evidence-linked decisions.** Every warning or block is backed by memory IDs, failure IDs, recall diagnostics, or preflight event IDs. Audrey preflight returns warnings, evidence IDs, recommended actions, recent failures, and an optional capsule (Ledger: E8-E10). Reflex generation preserves evidence IDs and reasons (Ledger: E11).
-
-**Action identity.** A repeated-failure detector needs an action identity stricter than a natural-language similarity match and more robust than raw string equality. Audrey hashes tool name, redacted command/action text, normalized working directory, and sorted normalized files; it then compares the hash with prior failed tool events for the same agent and tool (Ledger: E3).
-
-**Conservative control-source handling.** A memory tagged as a rule is not automatically trusted. Audrey treats `must-follow` style tags as control signals only when the source is `direct-observation` or `told-by-user`; untrusted control-looking memories are routed to uncertain/disputed context (Ledger: E6).
-
-**Recall-degradation awareness.** If retrieval partially fails, a memory controller should not silently proceed as though recall were complete. Audrey represents recall errors, propagates partial failures, exposes recent recall degradation in status, carries recall errors into capsules, and turns capsule recall errors into high-severity preflight warnings (Ledger: E7, E9, E15).
-
-**Redaction before persistence.** Tool traces are high-risk memory inputs because they contain commands, environment output, stack traces, credentials, and file paths. Audrey's tool-trace contract states that raw tool input, output, and error text do not leave the module without redaction; it stores hashes, redacted summaries, redacted metadata, file fingerprints, and redaction state (Ledger: E12). The redaction layer covers common credentials, bearer/basic auth, private keys, JWTs, URL credentials, password assignments, payment/PII patterns, signed URL signatures, session cookies, high-entropy secrets, and sensitive JSON keys (Ledger: E13).
-
-**Bounded context assembly.** A pre-action controller must fit within model and tool budgets. Audrey capsules include `budget_chars`, `used_chars`, and `truncated` fields and organize evidence into typed sections rather than returning an unstructured recall list (Ledger: E5).
-
-**Agent scoping.** A local memory runtime used by multiple agents should not leak another agent's private operational history into a current preflight. Audrey capsule recall forces `scope: 'agent'` (Ledger: E7).
-
-**Closed-loop validation.** A memory controller needs feedback after action because the controller's evidence can be helpful, merely used, or wrong. Audrey validation accepts `used`, `helpful`, and `wrong` outcomes and updates salience and bookkeeping fields; impact reporting summarizes validation and recent activity (Ledger: E16-E17).
-
-## Threat Model
-
-The controller assumes an agent with legitimate access to local tools and MCP tools. The main hazards are action-selection hazards, not cryptographic compromise.
-
-The in-scope hazards are:
-
-- Repeating an exact action that already failed.
-- Ignoring a remembered must-follow procedure or project rule.
-- Acting on a memory set with open contradictions.
-- Treating degraded recall as complete recall.
-- Persisting credentials or sensitive tool output into long-lived memory.
-- Allowing untrusted tool outputs or descriptors to influence future actions as if they were trusted rules.
-- Losing auditability between a warning/block and the evidence that caused it.
-
-The MCP ecosystem makes these hazards concrete. The MCP specification standardizes the schema for tools and messages [@mcp2025schema]. MCP security benchmarks and tool-poisoning work evaluate attacks against MCP-integrated agents, including adversarial tool descriptions, shadowing through shared context, and changed tool descriptors after approval [@zhang2026mcpsecuritybench; @jamshidi2025toolpoisoning]. The MCP tool-annotations discussion frames annotations as risk hints that matter only when a client performs a concrete action based on them [@mcp2026toolannotations]. Audrey's controller fits this pattern: memory risk is useful when it changes the host-side decision.
-
-The out-of-scope hazards are:
-
-- First-time mistakes with no relevant prior evidence.
-- Malicious host compromise, database tampering, or filesystem attacks outside Audrey's process boundary.
-- Formal verification that a tool action is semantically safe.
-- Permission enforcement, sandboxing, rate limiting, or policy execution outside the memory controller.
-- Model alignment, deception detection, and general prompt-injection defense independent of remembered evidence.
-- Complete prevention of secret exposure after a caller explicitly stores unredacted data outside Audrey's tool-trace path.
-
-These boundaries matter for evaluation. Audrey Guard is not a replacement for sandboxing, MCP permission systems, static analysis, or human approval. It is a memory-derived pre-action control layer: it catches hazards that are visible in prior outcomes, stored rules, contradictions, tool traces, and recall health.
-
-## Stage-A Evaluation Target
-
-The first paper version evaluates implemented mechanisms and specifies GuardBench rather than claiming full benchmark results across external systems. The implemented evidence available today is: the controller and CLI guard path (Ledger: E1-E4, E26), the redacted tool-trace path (Ledger: E12-E13), preflight/reflex behavior (Ledger: E8-E11), recall degradation handling (Ledger: E15), closed-loop validation and impact reporting (Ledger: E16-E17), the canonical performance snapshot (Ledger: E20-E22), the current behavioral regression gate output (Ledger: E23-E24), and the deterministic repeated-failure demo (Ledger: E25).
-
-GuardBench therefore belongs in this version as a specification for future comparative evaluation, not as a completed empirical result table. The empirical claims in the first version use existing Audrey artifacts only.