audrey 0.21.0 → 1.0.0

package/dist/src/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/validate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/validate.ts"],"names":[],"mappings":"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"}

package/docs/AUDREY_PAPER_OUTLINE.md

@@ -0,0 +1,175 @@
+# Audrey Paper Outline
+
+## Working Title
+
+Audrey Guard: Local-First Pre-Action Memory Control for Tool-Using Agents
+
+## One-Sentence Thesis
+
+Long-term memory for agents should not stop at recall; it should run before tool use, connect prior outcomes to the next action, and return an auditable `allow`, `warn`, or `block` decision with evidence.
+
+## Abstract Draft
+
+Tool-using agents repeatedly fail in ways that are avoidable: they rerun broken commands, ignore project-specific procedures, lose the context behind prior failures, and trust degraded retrieval paths as if they were complete. Existing agent-memory systems focus mainly on storing and retrieving conversational facts. Audrey reframes memory as a local-first control loop for action: observe tool outcomes, encode durable lessons, build a memory capsule before the next action, generate reflexes, decide whether to allow, warn, or block, and validate whether the memory changed the result.
+
+This paper introduces Audrey Guard, a SQLite-backed memory controller for Model Context Protocol and CLI agents. Audrey Guard combines hybrid vector/FTS recall, memory capsules, preflight warnings, tool-trace learning, redaction-first audit logging, and evidence-linked impact measurement. The evaluation plan measures repeated-failure prevention, false-block rate, degraded-recall fail-closed behavior, redaction safety, and overhead. The result is a practical memory firewall for local agent work: not a replacement for general memory platforms, but an auditable layer that helps agents avoid repeating known mistakes before they touch tools.
+
+## Core Contributions
+
+1. Define pre-action memory control as a distinct problem from generic long-term memory retrieval.
+2. Present the Audrey Guard loop: `PostToolUse` observation -> memory encoding -> preflight/capsule/reflex generation -> `allow` / `warn` / `block` -> validation/impact.
+3. Show a local-first implementation over SQLite, vector search, FTS, MCP, CLI, REST, and Python clients.
+4. Introduce GuardBench, an evaluation suite focused on tool-use risk reduction rather than chat-memory accuracy alone.
+5. Measure safety properties that memory systems usually underreport: repeated-failure prevention, recall degradation handling, secret redaction, and audit lineage.
+
+## Paper Structure
+
+### 1. Introduction
+
+- Agents now operate tools, not just text conversations.
+- The failure mode is operational: the agent knows less than yesterday's run.
+- Generic memory recall is necessary but insufficient; the memory must participate before action.
+- Audrey's claim: a local memory controller can prevent repeated tool failures with low overhead and inspectable evidence.
+
+### 2. Background and Related Work
+
+- Agent-memory systems: Mem0, Letta/MemGPT, LangMem, Zep/Graphiti, Supermemory, OpenMemory, Cognee, LlamaIndex memory.
+- Memory-as-system-resource work: MemOS, procedural memory, evidence-driven retention, temporal graphs.
+- MCP tool safety: tool annotations, tool poisoning, descriptor drift, open-world tool risk.
+- Hook runtimes: Claude Code `PreToolUse`, `PostToolUse`, and `PostToolUseFailure` make pre-action memory control deployable.
+
+### 3. Problem Definition
+
+- Input: proposed agent action, tool name, command/action text, cwd, file scope, session id, and current memory store.
+- Output: decision, risk score, summary, evidence ids, recommended actions, reflexes, optional capsule, and preflight event id.
+- Desired behavior:
+  - Block exact repeated failures unless the action changed.
+  - Warn on relevant prior failures, must-follow procedures, contradictions, and degraded recall.
+  - Preserve evidence lineage and redact secrets before durable storage.
+  - Add low enough latency to run inside tool hooks.
+
+### 4. Audrey Guard Design
+
+- Memory substrate: episodic, semantic, procedural, event log, validation, decay, consolidation.
+- Recall: hybrid vector + FTS with tag/source/date filters and partial-failure diagnostics.
+- Capsules: budgeted evidence assembly for action context.
+- Preflight: warnings and risk scoring from capsule sections, status, and recent tool failures.
+- Reflexes: action-oriented responses generated from preflight evidence.
+- Controller: `beforeAction()` and `afterAction()` over existing Audrey primitives.
+- Audit safety: redaction-before-truncation, action hashing, file-scope hashing, event ids.
+
+### 5. Implementation
+
+- Runtime: Node.js 20+, TypeScript, SQLite, sqlite-vec, Hono REST, MCP stdio, Python client.
+- CLI:
+  - `audrey guard --tool Bash "npm run deploy"`
+  - `audrey demo --scenario repeated-failure`
+- MCP surfaces:
+  - Tools for recall, preflight, reflexes, observe-tool, impact, status.
+  - Resources for status, recent memories, and principles.
+  - Prompts for session briefing, recall, and reflection.
+- Docker behavior: fail-closed non-loopback REST sidecar with required API key.
+
+### 6. Evaluation: GuardBench
+
+Baselines:
+
+- No memory.
+- Recent-window memory.
+- Vector-only recall.
+- Keyword/FTS-only recall.
+- Audrey Guard with hybrid recall and exact-failure matching.
+
+Scenarios:
+
+- Repeated failed shell command.
+- Required preflight procedure missing.
+- Same command in a different file scope.
+- Same tool/action with changed command.
+- Prior failure plus successful fix.
+- Recall vector table missing.
+- FTS failure under hybrid recall.
+- Long secret near truncation boundary.
+- Conflicting project instructions.
+- High-volume irrelevant memory noise.
+
+Metrics:
+
+- Repeated-failure prevention rate.
+- False-block rate.
+- Useful-warning precision.
+- Evidence recall: whether the blocking evidence is surfaced.
+- Redaction safety: raw secret leakage count.
+- Recall-degradation detection rate.
+- Runtime overhead p50/p95.
+- Validation-linked impact count.
+
+### 7. Results Plan
+
+- Use the existing repeated-failure demo as the first qualitative figure.
+- Run `npm run bench:memory:check` as the memory-regression baseline.
+- Keep the `bench:guard` command wired into release evidence before paper submission.
+- Report machine provenance for all timings, matching the existing 0.22.2 benchmark snapshot style.
+- Include ablations:
+  - Without exact action hash.
+  - Without file scope.
+  - Without recall degradation warnings.
+  - Without redaction-aware truncation.
+
+### 8. Discussion
+
+- Why Audrey should not compete as "the best general memory store."
+- Why local-first matters for tool traces: secrets, filesystem paths, project rules, and private failures.
+- Why tool annotations are hints, not policy guarantees.
+- What Audrey borrows from graph memory without adding a graph database to the core.
+- Limitations:
+  - Claude Code hook config can be applied with a guarded settings merge, but
+    equivalent Codex hook wiring still depends on a stable host hook surface.
+  - Validation lineage is bound to exact preflight event evidence, but feedback
+    does not yet tune risk scoring.
+  - Local comparative GuardBench numbers exist; no external-system numbers yet.
+  - Temporal belief fields are still future work.
+
+### 9. Conclusion
+
+- Agent memory should be judged by whether it changes future actions, not just whether it retrieves relevant text.
+- Audrey Guard demonstrates a practical local loop for using memory as a pre-action control layer.
+- The next publishable milestone is live external-adapter GuardBench output plus broader host-hook integration.
+
+## Figures and Tables
+
+1. Guard loop diagram: observe -> encode -> capsule/preflight/reflex -> decision -> validate.
+2. Architecture diagram: SQLite store, event log, recall, controller, MCP/CLI/REST clients.
+3. Repeated-failure demo transcript with evidence ids.
+4. GuardBench table by baseline and scenario.
+5. Redaction/truncation safety table.
+6. Latency table: preflight p50/p95 by memory count.
+
+## Artifact Checklist Before Submission
+
+- `bench:guard` script and JSON output.
+- Public GuardBench scenario manifest, comparative adapter package, and external-run metadata bundle.
+- Reproducible benchmark snapshot with Node version, CPU, RAM, git SHA.
+- CLI smoke transcript for `audrey demo --scenario repeated-failure`.
+- MCP smoke transcript for `tools/list`, `resources/list`, `prompts/list`, and `memory_status`.
+- Python integration proof.
+- Docker fail-closed auth proof.
+- Paper appendix with exact commands.
+
+## Submission Strategy
+
+1. Publish an arXiv preprint after GuardBench exists.
+2. Submit to an agent-systems, AI engineering, or LLM applications workshop.
+3. Keep the first version implementation-centered, not theory-heavy.
+4. Release the evaluation artifact with the paper so the claim is falsifiable.
+
+## Source Map
+
+- MCP tool annotations and trust model: https://modelcontextprotocol.io/specification/2025-11-25/server/tools and https://modelcontextprotocol.io/specification/2025-11-25/schema
+- MCP annotation risk vocabulary: https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/
+- Claude Code hooks: https://code.claude.com/docs/en/hooks
+- Mem0 token-efficient memory algorithm: https://mem0.ai/blog/mem0-the-token-efficient-memory-algorithm
+- MemOS: https://huggingface.co/papers/2507.03724
+- MCP Security Bench: https://huggingface.co/papers/2510.15994
+- Securing MCP against tool poisoning: https://papers.cool/arxiv/2512.06556
+- Zep/Graphiti temporal knowledge graph: https://help.getzep.com/graphiti/graphiti/overview

package/docs/MEMORY_BENCHMARKING.md

@@ -0,0 +1,59 @@
+# Audrey Memory Benchmarking Strategy
+
+Updated: 2026-05-05 for the 0.23.0 Audrey Guard release.
+
+Audrey should win trust before it tries to win leaderboards. The benchmark story is:
+separate what Audrey can prove locally, publish the exact harness and artifacts, and
+only compare against external systems on tasks that measure the same thing.
+
+## 0.23.0 Release Stance
+
+- Performance snapshots measure Audrey's local pipeline: SQLite, sqlite-vec,
+  hybrid ranking, and post-encode work. They intentionally exclude hosted
+  embedding latency and do not compare against unrelated systems.
+- The behavioral suite is split into retrieval, lifecycle operations, and guard
+  loop behavior. Guard cases stay out of the comparable aggregate because
+  "no controller" baselines are useful regressions, not fair leaderboard peers.
+- `npm run bench:memory:guard` is Audrey's new product benchmark: can memory
+  stop an agent before it repeats a known tool failure or violates a must-follow
+  release rule, and can the receipt boundary reject replayed or non-guard
+  outcomes?
+- The next public claim should be a reproducible report, not a slogan: commit
+  the command, raw JSON, machine provenance, model/provider configuration, and
+  any judge prompt or scoring rule used.
+
+## External Benchmark Map
+
+| Benchmark | What It Tests | Audrey Fit |
+|---|---|---|
+| LongMemEval | Information extraction, multi-session reasoning, temporal reasoning, knowledge updates, and abstention across scalable chat histories. | Good retrieval/lifecycle fit once Audrey has an adapter and evaluator. Source: https://arxiv.org/abs/2410.10813 |
+| LoCoMo | Very long-term conversations around 300 turns, 9K tokens on average, and up to 35 sessions, with QA, summarization, and multimodal dialogue tasks. | Useful external context, but Audrey should keep published scores separate from local synthetic cases. Source: https://arxiv.org/abs/2402.17753 |
+| MemoryAgentBench | Incremental multi-turn memory with accurate retrieval, test-time learning, long-range understanding, and selective forgetting. | Strong fit for Audrey's live agent posture because it evaluates online accumulation rather than static long-context reading. Source: https://arxiv.org/abs/2507.05257 |
+| StructMemEval | Whether agents organize long-term memory into useful structures such as ledgers, to-do lists, and trees rather than just recalling facts. | High-value 0.24 target for Audrey's memory-controller routing and future typed memory stores. Source: https://arxiv.org/abs/2602.11243 |
+| MemGUI-Bench | Cross-temporal and cross-spatial memory for mobile GUI agents, with memory-centric tasks and staged evaluation. | Not a direct coding-agent benchmark, but its failure taxonomy is relevant to tool-bound agents with UI state. Source: https://arxiv.org/abs/2602.06075 |
+
+## Release-Quality Rules
+
+1. Do not mix controller benchmarks with retrieval leaderboards unless all
+   compared systems receive equivalent controller affordances.
+2. Do not quote latency without the embedding provider, dimensions, corpus size,
+   recall mode, hardware, Node version, and whether warm caches were involved.
+3. Treat abstention, deletion, overwrite, conflict resolution, and selective
+   forgetting as first-class memory outcomes, not edge cases.
+4. Prefer task evidence over vibe: raw JSON, artifacts, evaluator code, and
+   reproduction commands should ship with every public benchmark claim.
+5. For coding-agent memory, measure prevented mistakes and time-to-recovery, not
+   only whether a stored fact was recalled.
+
+## 0.24 Benchmark Targets
+
+- Add a LongMemEval adapter that can run a small public shard with mock and real
+  embedding providers.
+- Add a MemoryAgentBench-style incremental harness with explicit selective
+  forgetting and test-time learning cases.
+- Add structured-memory cases that force Audrey to maintain a ledger, checklist,
+  or dependency tree across sessions.
+- Add an agent-tool benchmark where `beforeAction()` and `afterAction()` wrap a
+  scripted coding workflow and score prevented repeats, blocked violations, and
+  useful cautions.
+- Publish one reproducible external report before making any SOTA-style claim.

package/docs/PRODUCTION_BACKLOG.md

@@ -0,0 +1,304 @@
+# Audrey Production Backlog
+
+Updated: 2026-05-13 after the Audrey 1.0 release-cut and paper-gate pass.
+
+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 has been cut locally and is ready for package-level validation
+through 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 npm:smoke
+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.0 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.0 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.0.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.
+
+## Unreleased v0.23 Guard Chassis
+
+The first Audrey Guard slice is now in the working tree:
+
+- `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.0 readiness
+  checklist, then runs a clean-consumer npm package smoke test and the 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: Claude Code hook apply is explicit rather
+than part of `install`, Codex hook wiring is not available yet, and validation
+feedback is recorded but not yet used to 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.0 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.0.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 npm:smoke` to prove the packed npm tarball installs in a clean consumer project, imports the public ESM API, runs encode/recall, and executes both CLI shims.
+- `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. Add the equivalent Codex hook wiring when the host exposes a stable hook
+   surface, and add a one-command Claude Code install mode that runs MCP
+   registration plus hook apply after a dry-run preview.
+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.
+
+## 1.0 / Paper Publish Blockers
+
+The local code and paper gates are strong, but the 1.0/publication objective is
+not complete until `release:readiness:strict` passes. Current blockers:
+
+- 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.
+
+## v0.23 Product Direction (Tracked, Not Decided)
+
+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, scoped to fit one or two
+releases:
+
+1. Host hook wiring for Claude Code and Codex so Guard runs automatically
+   before tool use and tool outcomes feed back into trace/validation surfaces.
+2. 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/paper/00-master.md

@@ -0,0 +1,48 @@
+# 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

@@ -0,0 +1,27 @@
+# 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.