audrey 0.23.1 → 1.0.1

package/dist/src/validate.js

@@ -6,13 +6,13 @@ const CONTRADICTION_THRESHOLD = 0.60;
 export async function validateMemory(db, embeddingProvider, episode, options = {}) {
     const { threshold = REINFORCEMENT_THRESHOLD, contradictionThreshold = CONTRADICTION_THRESHOLD, llmProvider, embeddingVector, embeddingBuffer, } = options;
     const episodeBuffer = embeddingBuffer ?? embeddingProvider.vectorToBuffer(embeddingVector ?? await embeddingProvider.embed(episode.content));
-    const nearestSemantic = db.prepare(`
-    SELECT s.*, (1.0 - v.distance) AS similarity
-    FROM vec_semantics v
-    JOIN semantics s ON s.id = v.id
-    WHERE v.embedding MATCH ?
-      AND k = 1
-      AND (v.state = 'active' OR v.state = 'context_dependent')
+    const nearestSemantic = db.prepare(`
+    SELECT s.*, (1.0 - v.distance) AS similarity
+    FROM vec_semantics v
+    JOIN semantics s ON s.id = v.id
+    WHERE v.embedding MATCH ?
+      AND k = 1
+      AND (v.state = 'active' OR v.state = 'context_dependent')
   `).get(episodeBuffer);
     let bestMatch = null;
     let bestSimilarity = 0;
@@ -34,14 +34,14 @@ export async function validateMemory(db, embeddingProvider, episode, options = {
             const now = new Date().toISOString();
             // supporting_count only increments when this is a new piece of evidence;
             // re-validating the same episode shouldn't keep inflating the count.
-            db.prepare(`
-        UPDATE semantics SET
-          supporting_count = supporting_count + ?,
-          evidence_episode_ids = ?,
-          evidence_count = ?,
-          source_type_diversity = ?,
-          last_reinforced_at = ?
-        WHERE id = ?
+            db.prepare(`
+        UPDATE semantics SET
+          supporting_count = supporting_count + ?,
+          evidence_episode_ids = ?,
+          evidence_count = ?,
+          source_type_diversity = ?,
+          last_reinforced_at = ?
+        WHERE id = ?
       `).run(wasAdded ? 1 : 0, JSON.stringify(existing), existing.length, diversity, now, matchId);
         });
         reinforce();
@@ -120,21 +120,21 @@ export function createContradiction(db, claimAId, claimAType, claimBId, claimBTy
     const state = resolution ? 'resolved' : 'open';
     const resolvedAt = resolution ? now : null;
     const resolutionJson = resolution ? JSON.stringify(resolution) : null;
-    db.prepare(`
-    INSERT INTO contradictions (id, claim_a_id, claim_a_type, claim_b_id, claim_b_type,
-      state, resolution, resolved_at, created_at)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    db.prepare(`
+    INSERT INTO contradictions (id, claim_a_id, claim_a_type, claim_b_id, claim_b_type,
+      state, resolution, resolved_at, created_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(id, claimAId, claimAType, claimBId, claimBType, state, resolutionJson, resolvedAt, now);
     return id;
 }
 export function reopenContradiction(db, contradictionId, newEvidenceId) {
     const now = new Date().toISOString();
-    db.prepare(`
-    UPDATE contradictions SET
-      state = 'reopened',
-      reopen_evidence_id = ?,
-      reopened_at = ?
-    WHERE id = ?
+    db.prepare(`
+    UPDATE contradictions SET
+      state = 'reopened',
+      reopen_evidence_id = ?,
+      reopened_at = ?
+    WHERE id = ?
   `).run(newEvidenceId, now, contradictionId);
 }
 //# sourceMappingURL=validate.js.map

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 |