agent-working-memory 0.4.1 → 0.4.3

package/README.md

@@ -1,177 +1,205 @@
 # AgentWorkingMemory (AWM)
 
-**Cognitive memory for AI agents — so they stop forgetting everything between conversations.**
+**Persistent working memory for AI agents.**
 
-If you've used Claude, ChatGPT, or any AI coding assistant for more than a day, you've hit the wall: it forgets. Every new conversation starts from zero. You re-explain your project, your stack, your preferences, your decisions — over and over. Long conversations go circular as the AI loses context from earlier in the same chat. It's like working with the smartest person in the world who gets amnesia at the end of every shift.
+AWM helps agents retain important project knowledge across conversations and sessions. Instead of storing everything and retrieving by similarity alone, it filters for salience, builds associative links between related memories, and periodically consolidates useful knowledge while letting noise fade.
 
-AWM fixes that. It gives AI agents a persistent, self-organizing memory that works like a sharp senior developer's brain — not a search engine. It decides what's worth remembering (77% of noise filtered at write time), connects related knowledge through associative links that strengthen with use, and periodically consolidates memories the way your brain does during sleep: reinforcing important patterns, building cross-topic shortcuts, and letting unused noise fade away. The result is an AI that remembers your architecture decisions from three weeks ago, surfaces relevant context without being asked, and doesn't waste your time re-learning things it already knew.
+Use it through Claude Code via MCP or as a local HTTP service for custom agents. Everything runs locally: SQLite + ONNX models + Node.js. No cloud, no API keys.
 
-## How It's Different
+### Without AWM
+- Agent forgets earlier architecture decision
+- Suggests Redux after project standardized on Zustand
+- Repeats discussion already settled three days ago
+- Every new conversation starts from scratch
 
-Most "memory for AI" projects are glorified vector databases — they embed everything, retrieve by cosine similarity, and dump results into the prompt. That's a search engine, not memory. AWM is fundamentally different:
+### With AWM
+- Recalls prior state-management decision and rationale
+- Surfaces related implementation patterns from past sessions
+- Continues work without re-asking for context
+- Gets more consistent the longer you use it
 
-| Feature | Typical RAG/Vector Store | AWM |
-|---------|------------------------|-----|
-| **What gets stored** | Everything | Only salient events (novelty + salience scoring filters 77% of noise at write time) |
-| **Retrieval** | Single-signal cosine similarity | 10-phase pipeline: BM25 + vectors + cross-encoder reranking + graph walk + temporal decay |
-| **Connections** | None | Hebbian associative edges that strengthen when memories are co-retrieved |
-| **Over time** | Grows forever, gets noisier | Sleep cycle consolidation: strengthens clusters, prunes noise, builds cross-topic bridges |
-| **Forgetting** | Manual cleanup or TTL | Cognitive forgetting: unretrieved memories fade, confirmed knowledge persists for months |
-| **Feedback** | None | Explicit useful/not-useful signals tune confidence, affecting retrieval rank and forgetting resistance |
-| **Self-correction** | Delete and re-insert | Retraction system: wrong memories get invalidated, corrections link back, confidence penalties propagate |
+---
 
-AWM is modeled on established cognitive science — ACT-R activation decay, Hebbian learning, complementary learning systems, and hippocampal memory staging. It's not a database with a prompt wrapper; it's a cognitive architecture that gets better the more you use it.
+## Quick Start
 
-## Benchmarks
+**Node.js 20+** required — check with `node --version`.
 
-| Eval | Score | What it tests |
-|------|-------|---------------|
-| Edge Cases | **100% (34/34)** | 9 failure modes: hub toxicity, flashbulb distortion, narcissistic interference, identity collision, contradiction preservation, bridge overshoot, noise forgetting benefit |
-| Stress Test | **92.3% (48/52)** | 500 memories, 100 sleep cycles, catastrophic forgetting, adversarial spam, recovery |
-| A/B Test | **AWM 100% vs Baseline 83%** | 100 project events, 24 recall questions |
-| Self-Test | **97.4% EXCELLENT** | 31 pipeline component checks |
-| Workday | **86.7% GOOD** | 43 memories across 4 simulated work sessions |
-| Real-World | **93.1% EXCELLENT** | 300 code chunks from a 71K-line production monorepo |
-| Token Savings | **64.5% savings** | Memory-guided context vs full conversation history |
+```bash
+npm install -g agent-working-memory
+awm setup --global
+```
 
-## Quick Start — Claude Code (Recommended)
+Restart Claude Code. That's it — 13 memory tools appear automatically.
 
-The fastest way to use AWM. Two commands, works in every project.
+First conversation will be ~30 seconds slower while ML models download (~124MB, cached locally). After that, everything runs on your machine.
 
-### Prerequisites
+> For isolated memory per folder, see [Separate Memory Pools](#separate-memory-pools). For team onboarding, see [docs/quickstart.md](docs/quickstart.md).
 
-**Node.js 20+** — download from [nodejs.org](https://nodejs.org) if needed. Check with `node --version`.
+---
 
-### Install
+## Who this is for
 
-```bash
-npm install -g agent-working-memory
-```
+- **Long-running coding agents** that need cross-session project knowledge
+- **Multi-agent workflows** where specialized agents share a common memory
+- **Local-first setups** where cloud memory is not acceptable
+- **Teams using Claude Code** who want persistent context without manual notes
 
-### Setup (Global — one brain for all projects)
+## What this is not
 
-```bash
-awm setup --global
-```
+- Not a chatbot UI
+- Not a hosted SaaS
+- Not a generic vector database
+- Not a replacement for your source of truth (code, docs, tickets)
 
-This writes `~/.mcp.json` so Claude Code picks up AWM everywhere. One unified memory across all your work.
+---
 
-**Restart Claude Code** to load the MCP server. The first conversation will download three small ML models (~124MB, cached locally). After that, everything runs on your machine — no API keys, no cloud calls.
+## Why it's different
 
-### Setup (Per-project)
+Most "memory for AI" projects are vector databases with a retrieval wrapper. AWM goes further:
 
-If you prefer isolated memory per project instead:
+| | Typical RAG / Vector Store | AWM |
+|---|---|---|
+| **Storage** | Everything | Only novel, salient events (77% filtered at write time) |
+| **Retrieval** | Cosine similarity | 10-phase pipeline: BM25 + vectors + reranking + graph walk + decay |
+| **Connections** | None | Hebbian edges that strengthen when memories co-activate |
+| **Over time** | Grows forever, gets noisier | Consolidation: strengthens clusters, prunes noise, builds bridges |
+| **Forgetting** | Manual cleanup | Cognitive forgetting: unused memories fade, confirmed knowledge persists |
+| **Feedback** | None | Useful/not-useful signals tune confidence and retrieval rank |
+| **Correction** | Delete and re-insert | Retraction: wrong memories invalidated, corrections linked, penalties propagate |
 
-```bash
-cd your-project
-awm setup
-```
+The design is based on cognitive science — ACT-R activation decay, Hebbian learning, complementary learning systems, and synaptic homeostasis — rather than ad-hoc heuristics. See [How It Works](#how-it-works) and [docs/cognitive-model.md](docs/cognitive-model.md) for details.
 
-This creates `.mcp.json` in the current directory and appends workflow instructions to `CLAUDE.md`. Use `--agent-id my-project` to customize the agent identifier.
+---
+
+## Benchmarks
+
+| Eval | Score | What it tests |
+|------|-------|---------------|
+| Edge Cases | **100% (34/34)** | 9 failure modes: hub toxicity, flashbulb distortion, narcissistic interference, identity collision, noise forgetting benefit |
+| Stress Test | **92.3% (48/52)** | 500 memories, 100 sleep cycles, catastrophic forgetting, adversarial spam |
+| A/B Test | **AWM 100% vs Baseline 83%** | 100 project events, 24 recall questions |
+| Self-Test | **97.4%** | 31 pipeline component checks |
+| Workday | **86.7%** | 43 memories across 4 simulated work sessions |
+| Real-World | **93.1%** | 300 code chunks from a 71K-line production monorepo |
+| Token Savings | **64.5% savings** | Memory-guided context vs full conversation history |
 
-### What Claude gets
+All evals are reproducible: `npm run test:self`, `npm run test:edge`, `npm run test:stress`, etc. See [Testing & Evaluation](#testing--evaluation) and [docs/benchmarks.md](docs/benchmarks.md) for full details.
+
+---
 
-After restarting Claude Code, 13 memory tools appear automatically:
+## Features
 
-| Tool | What it does |
-|------|-------------|
-| `memory_write` | Store a memory with salience metadata |
+### Memory Tools (13)
+
+| Tool | Purpose |
+|------|---------|
+| `memory_write` | Store a memory (salience filter decides disposition) |
 | `memory_recall` | Retrieve relevant memories by context |
-| `memory_feedback` | Tell AWM if a memory was useful or not |
-| `memory_retract` | Mark a wrong memory as invalid |
-| `memory_stats` | View memory health metrics |
+| `memory_feedback` | Report whether a recalled memory was useful |
+| `memory_retract` | Invalidate a wrong memory with optional correction |
+| `memory_stats` | View memory health metrics and activity |
 | `memory_checkpoint` | Save execution state (survives context compaction) |
-| `memory_restore` | Recover state + relevant context at conversation start |
+| `memory_restore` | Recover state + relevant context at session start |
 | `memory_task_add` | Create a prioritized task |
 | `memory_task_update` | Change task status/priority |
 | `memory_task_list` | List tasks by status |
 | `memory_task_next` | Get the highest-priority actionable task |
 | `memory_task_begin` | Start a task — auto-checkpoints and recalls context |
 | `memory_task_end` | End a task — writes summary and checkpoints |
-You don't need to tell Claude to "use memory." Once connected, Claude will automatically write important decisions, recall relevant context, and learn from feedback. Over time, it builds up knowledge that persists across every conversation.
 
 ### Separate Memory Pools
 
-By default, `awm setup --global` creates one shared memory pool. If you want isolated memory per folder (e.g., work vs personal projects), place a `.mcp.json` in each parent folder with a different `AWM_AGENT_ID`:
+By default, all projects share one memory pool. For isolated pools per folder, place a `.mcp.json` in each parent folder with a different `AWM_AGENT_ID`:
 
 ```
 C:\Users\you\work\.mcp.json          → AWM_AGENT_ID: "work"
 C:\Users\you\personal\.mcp.json      → AWM_AGENT_ID: "personal"
 ```
 
-Claude Code uses the closest `.mcp.json` ancestor. Same database file — isolation is by agent ID. Use different `AWM_HOOK_PORT` values if running multiple sessions simultaneously.
+Claude Code uses the closest `.mcp.json` ancestor. Same database, isolation by agent ID.
 
 ### Incognito Mode
 
-Run Claude Code without AWM recording anything:
-
 ```bash
 AWM_INCOGNITO=1 claude
 ```
 
-When `AWM_INCOGNITO=1` is set, AWM registers zero tools — Claude won't see any `memory_*` tools. All other tools, MCP servers, and skills work normally. No database is opened, nothing is recorded.
+Registers zero tools — Claude doesn't see memory at all. All other tools and MCP servers work normally.
 
 ### Auto-Checkpoint Hooks
 
-AWM includes Claude Code hooks that auto-save your working state:
-
-- **Stop** — reminds Claude to save learnings after each response (async, no delay)
-- **PreCompact** — auto-checkpoints before context window compression
-- **SessionEnd** — auto-checkpoints and runs full consolidation on graceful exit
+Installed by `awm setup --global`:
 
-These are installed automatically by `awm setup --global`. See [docs/team-setup-guide.md](docs/team-setup-guide.md) for manual hook configuration.
+- **Stop** — reminds Claude to write/recall after each response
+- **PreCompact** — auto-checkpoints before context compression
+- **SessionEnd** — auto-checkpoints and consolidates on close
+- **15-min timer** — silent auto-checkpoint while session is active
 
 ### Activity Log
 
-AWM writes a real-time activity log so you can see exactly what's happening:
-
 ```bash
 tail -f "$(npm root -g)/agent-working-memory/data/awm.log"
 ```
 
-Each event is one line: `timestamp | agentId | event | detail`. You'll see writes, recalls, checkpoints, consolidation cycles, and hook events.
-
-### Optional: Add workflow instructions to CLAUDE.md
+Real-time: writes, recalls, checkpoints, consolidation, hook events.
 
-For per-project setups, `awm setup` does this automatically. For global setups, add this to any project's `CLAUDE.md` where you want explicit memory guidance:
+### Activity Stats
 
-```markdown
-## Memory (AWM)
-You have persistent memory via the agent-working-memory MCP server.
-- At conversation start: call memory_restore to recover previous context
-- When you learn something important: call memory_write
-- When you need past context: call memory_recall
-- Before long operations: call memory_checkpoint to save your state
-- After using a recalled memory: call memory_feedback (useful/not-useful)
+```bash
+curl http://127.0.0.1:8401/stats
 ```
 
+Returns daily counts: `{"writes": 8, "recalls": 9, "hooks": 3, "total": 25}`
+
 ---
 
-## HTTP API (Alternative)
+## Memory Invocation Strategy
 
-If you want to use AWM outside of Claude Code (custom agents, scripts, etc.), you can run the HTTP server directly.
+AWM combines deterministic hooks for guaranteed memory operations at lifecycle transitions with agent-directed usage during active work.
 
-### From npm
+### Deterministic triggers (always happen)
 
-```bash
-npm install -g agent-working-memory
-awm serve
-```
+| Event | Action |
+|-------|--------|
+| Session start | `memory_restore` — recover state + recall context |
+| Pre-compaction | Auto-checkpoint via hook sidecar |
+| Session end | Auto-checkpoint + full consolidation |
+| Every 15 min | Silent auto-checkpoint (if active) |
+| Task start | `memory_task_begin` — checkpoint + recall |
+| Task end | `memory_task_end` — summary + checkpoint |
 
-### From source
+### Agent-directed triggers (when these situations occur)
 
-```bash
-git clone https://github.com/CompleteIdeas/agent-working-memory.git
-cd agent-working-memory
-npm install
-npx tsx src/index.ts
-```
+**Write memory when:**
+- A project decision is made or changed
+- A root cause is discovered
+- A reusable implementation pattern is established
+- A preference, constraint, or requirement is clarified
+- A prior assumption is found to be wrong
+
+**Recall memory when:**
+- Starting work on a new task or subsystem
+- Re-entering code you haven't touched recently
+- After context compaction
+- After a failed attempt (check if there's prior knowledge)
+- Before refactoring or making architectural changes
+
+**Retract when:**
+- A stored memory turns out to be wrong or outdated
 
-**The first time you run this, it downloads three small ML models (~124MB total).** These are cached locally in a `models/` folder. No API keys, no cloud calls. Everything runs on your machine.
+**Feedback when:**
+- A recalled memory was used (useful) or irrelevant (not useful)
 
-Once you see `AWM server listening on port 8400`, the server is ready.
+---
+
+## HTTP API
+
+For custom agents, scripts, or non-Claude-Code workflows:
 
-### Try it
+```bash
+awm serve                    # From npm install
+npx tsx src/index.ts         # From source
+```
 
 Write a memory:
 
@@ -188,7 +216,7 @@ curl -X POST http://localhost:8400/memory/write \
   }'
 ```
 
-Recall it:
+Recall:
 
 ```bash
 curl -X POST http://localhost:8400/memory/activate \
@@ -199,60 +227,31 @@ curl -X POST http://localhost:8400/memory/activate \
   }'
 ```
 
-### Configuration
-
-- **Change the port:** `awm serve --port 3000` or `AWM_PORT=3000`
-- **Custom database:** `AWM_DB_PATH=/path/to/memory.db`
-- **API key auth:** Set `AWM_API_KEY=your-secret` in `.env` — requests need `Authorization: Bearer your-secret` or `x-api-key: your-secret`
-- **Run tests:** `npx vitest run` (68 tests)
-- **Run eval suite:** `npm run test:self`
-- **Data is a single file:** `data/memory.db` (SQLite). Back it up, move it, delete it to start fresh.
-- **Models cached locally:** First run downloads to `models/`. No network after that.
-
 ---
 
-## Docker (Quick Alternative)
-
-If you'd rather not install Node.js locally:
-
-```bash
-docker build -t awm .
-docker run -p 8400:8400 -v awm-data:/data -v awm-models:/models awm
-```
-
-This gives you the HTTP server on port 8400. The `-v` flags persist your database and models across container restarts. For MCP integration with Docker, point your `.mcp.json` to the HTTP API instead of the MCP script.
-
 ## How It Works
 
 ### The Memory Lifecycle
 
-1. **Write** — Agent sends an observation, decision, or event. Salience scoring evaluates surprise, causal depth, and resolution effort. High-salience memories go active immediately; borderline ones enter a staging buffer; noise is discarded.
+1. **Write** — Salience scoring evaluates novelty, surprise, causal depth, and effort. High-salience memories go active; borderline ones enter staging; noise is discarded.
 
-2. **Connect** — Each memory gets a vector embedding (MiniLM-L6-v2, 384d). Temporal edges link it to recent memories in the same session. Hebbian edges form between memories that are retrieved together — the more often they co-activate, the stronger the link.
+2. **Connect** — Vector embedding (MiniLM-L6-v2, 384d). Temporal edges link to recent memories. Hebbian edges form between co-retrieved memories.
 
-3. **Retrieve** — The 10-phase activation pipeline combines keyword search (BM25), semantic search (cosine similarity), cross-encoder reranking, temporal decay (ACT-R), associative graph walks, and confidence gating. It returns the most relevant memories with explanations of why each scored the way it did.
+3. **Retrieve** — 10-phase pipeline: BM25 + semantic search + cross-encoder reranking + temporal decay (ACT-R) + graph walks + confidence gating.
 
-4. **Consolidate** — A periodic "sleep cycle" runs 7 phases modeled on how the brain processes memories during sleep:
-   - **Replay** — Find clusters of semantically similar memories
-   - **Strengthen** — Reinforce edges within clusters (access-weighted)
-   - **Bridge** — Create cross-cluster shortcuts between related topics
-   - **Decay** — Weaken unused edges (confidence-modulated half-life)
-   - **Homeostasis** — Normalize outgoing edge weights to prevent hub explosion
-   - **Forget** — Archive unretrieved, weakly-connected memories (age-gated, access-scaled)
-   - **Prune redundancy** — Archive semantically duplicate low-quality memories
-   - **Sweep staging** — Promote staging memories that resonate with active ones
+4. **Consolidate** — 7-phase sleep cycle: replay clusters, strengthen edges, bridge cross-topic, decay unused, normalize hubs, forget noise, sweep staging.
 
-5. **Feedback** — Agents report whether recalled memories were useful. Positive feedback raises confidence (improving retrieval rank and forgetting resistance); negative feedback lowers it.
+5. **Feedback** — Useful/not-useful signals adjust confidence, affecting retrieval rank and forgetting resistance.
 
-### Cognitive Model
+### Cognitive Foundations
 
-AWM is built on established cognitive science, not ad-hoc heuristics:
+- **ACT-R activation decay** (Anderson 1993) — memories decay with time, strengthen with use
+- **Hebbian learning** — co-retrieved memories form stronger associative edges
+- **Complementary Learning Systems** — fast capture (salience + staging) + slow consolidation (sleep cycle)
+- **Synaptic homeostasis** — edge weight normalization prevents hub domination
+- **Forgetting as feature** — noise removal improves signal-to-noise for connected memories
 
-- **ACT-R base-level activation** (Anderson 1993) — memories decay with time but strengthen with use. Confidence modulates the decay exponent: confirmed knowledge decays slower.
-- **Hebbian learning** — "neurons that fire together wire together." Co-retrieved memories form stronger associative edges, enabling graph-based spreading activation.
-- **Complementary Learning Systems** — fast capture (salience filter + staging) combined with slow consolidation (sleep cycle). Mirrors hippocampal-neocortical memory transfer.
-- **Synaptic homeostasis** — total connection weight per memory is normalized to prevent any single "hub" from dominating retrieval. Similar to how the brain downscales synaptic strength during sleep.
-- **Forgetting as feature** — noise removal improves signal-to-noise ratio for connected memories. Unretrieved noise gets pruned; confirmed knowledge gets stronger. In benchmarks, aggressive forgetting improves quality recall from 3/5 to 5/5.
+---
 
 ## Architecture
 
@@ -274,70 +273,41 @@ src/
     retraction.ts     - Negative memory / corrections
     eviction.ts       - Capacity enforcement
   hooks/
-    sidecar.ts        - Hook HTTP server (auto-checkpoint from Claude Code hooks)
+    sidecar.ts        - Hook HTTP server (auto-checkpoint, stats, timer)
   storage/
     sqlite.ts         - SQLite + FTS5 persistence layer
   api/
     routes.ts         - HTTP endpoints (memory + task + system)
-  mcp.ts            - MCP server (13 tools for Claude Code, incognito support)
+  mcp.ts            - MCP server (13 tools, incognito support)
   cli.ts            - CLI (setup, serve, hook config)
   index.ts          - HTTP server entry point
 ```
 
-## Task Management
+For detailed architecture including pipeline phases, database schema, and system diagrams, see [docs/architecture.md](docs/architecture.md).
 
-Tasks are first-class memory objects with status and priority tracking:
-
-```bash
-# Create a task
-curl -X POST http://localhost:8400/task/create \
-  -H "Content-Type: application/json" \
-  -d '{
-    "agentId": "my-agent",
-    "concept": "Fix login redirect bug",
-    "content": "Users get 404 after OAuth callback",
-    "priority": "urgent"
-  }'
-
-# Get next actionable task
-curl http://localhost:8400/task/next/my-agent
-```
-
-Priority levels: `urgent` > `high` > `medium` > `low`. Tasks can be blocked by other tasks and automatically unblock when dependencies complete.
+---
 
 ## Testing & Evaluation
 
-AWM has been through extensive testing — unit tests, integration tests, and multiple evaluation suites that simulate realistic use. Every component of the cognitive pipeline has been validated both in isolation and under real-world-like conditions.
-
-### Unit Tests (no server needed)
+### Unit Tests
 
 ```bash
-npx vitest run    # 68 tests — salience scoring, decay curves, Hebbian learning, novelty filtering, etc.
+npx vitest run    # 68 tests
 ```
 
-### Eval Suites (start the server first: `npx tsx src/index.ts`)
+### Eval Suites
 
 | Command | What it tests | Score |
 |---------|--------------|-------|
-| `npm run test:self` | 31 pipeline component checks — embedding quality, BM25 recall, reranker ordering, decay curves, confidence gating, Hebbian strengthening, graph walks, staging promotion | **97.4% EXCELLENT** |
-| `npm run test:edge` | 9 adversarial failure modes — context collapse (100 routine vs 5 rare), mega-hub toxicity (50-link hub node), flashbulb distortion (high-emotion memory overwriting facts), narcissistic interference (30 self-referential claims vs 4 facts), identity collision (same name, different people), contradiction trapping, bridge overshoot, noise forgetting benefit | **100% (34/34)** |
-| `npm run test:stress` | 500 memories, 100 sleep cycles, catastrophic forgetting resistance, adversarial spam injection (200 noise memories), long-term knowledge recovery after 50 days of neglect | **92.3% (48/52)** |
-| `npm run test:workday` | Simulates a coding assistant's workday — 43 memories across 4 projects (Express, React, CI/CD, PostgreSQL), then 14 recall challenges testing knowledge transfer, context switching, cross-cutting queries, and noise rejection | **86.7% GOOD** |
-| `npm run test:ab` | Head-to-head comparison: AWM's full pipeline vs a keyword-only baseline, 100 project events, 24 recall questions | **AWM 100% vs Baseline 83%** |
-| `npm run test:tokens` | Measures token savings — how much prompt context AWM saves vs dumping full conversation history | **64.5% savings** |
-| `npm run test:realworld` | Ingests 300 code chunks from a 71K-line production monorepo (EquiHub/SportsManagement), tests domain knowledge recall, architecture questions, and noise rejection | **93.1% EXCELLENT** |
-| `npm run test:sleep` | Targeted sleep cycle consolidation test | — |
-| `npm run test:locomo` | Academic benchmark (LoCoMo dataset) — multi-hop conversational memory | — |
-
-### What the Edge Cases Prove
-
-The edge case suite is particularly important because it tests the failure modes that kill other memory systems:
-
-- **Context Collapse** — Can AWM find 5 rare but important memories buried under 100 routine ones? (Yes — salience scoring and feedback bonuses keep confirmed knowledge afloat.)
-- **Mega-Hub Toxicity** — If one memory has 50 connections, does it hijack every query? (No — synaptic homeostasis normalizes edge weights.)
-- **Flashbulb Distortion** — Does a high-emotion memory overwrite the actual facts? (No — retraction system and confidence scoring keep specifics intact.)
-- **Narcissistic Interference** — Can 30 self-referential "I am amazing" claims drown out 4 real facts? (No — redundancy pruning archives the clones, feedback bonuses elevate confirmed knowledge.)
-- **Noise Forgetting Benefit** — Does forgetting 150 noise memories hurt the 5 quality ones? (Opposite — recall stays 5/5 because forgetting *improves* signal-to-noise ratio for connected memories.)
+| `npm run test:self` | 31 pipeline checks: embeddings, BM25, reranker, decay, confidence, Hebbian, graph walks, staging | **97.4%** |
+| `npm run test:edge` | 9 adversarial failure modes: context collapse, hub toxicity, flashbulb distortion, narcissistic interference, identity collision, contradiction, bridge overshoot, noise benefit | **100%** |
+| `npm run test:stress` | 500 memories, 100 sleep cycles, catastrophic forgetting, adversarial spam, recovery | **92.3%** |
+| `npm run test:workday` | 43 memories across 4 projects, 14 recall challenges | **86.7%** |
+| `npm run test:ab` | AWM vs keyword baseline, 100 events, 24 questions | **AWM 100% vs 83%** |
+| `npm run test:tokens` | Token savings vs full conversation history | **64.5%** |
+| `npm run test:realworld` | 300 chunks from 71K-line monorepo, 16 challenges | **93.1%** |
+
+---
 
 ## Environment Variables
 
@@ -345,13 +315,13 @@ The edge case suite is particularly important because it tests the failure modes
 |----------|---------|---------|
 | `AWM_PORT` | `8400` | HTTP server port |
 | `AWM_DB_PATH` | `memory.db` | SQLite database path |
-| `AWM_AGENT_ID` | `claude-code` | Default agent ID (MCP) |
+| `AWM_AGENT_ID` | `claude-code` | Agent ID (memory namespace) |
 | `AWM_EMBED_MODEL` | `Xenova/all-MiniLM-L6-v2` | Embedding model |
 | `AWM_EMBED_DIMS` | `384` | Embedding dimensions |
 | `AWM_RERANKER_MODEL` | `Xenova/ms-marco-MiniLM-L-6-v2` | Reranker model |
-| `AWM_HOOK_PORT` | `8401` | Hook sidecar HTTP port |
-| `AWM_HOOK_SECRET` | *(none)* | Bearer token for hook sidecar auth |
-| `AWM_INCOGNITO` | *(unset)* | Set to `1` to disable all memory tools |
+| `AWM_HOOK_PORT` | `8401` | Hook sidecar port |
+| `AWM_HOOK_SECRET` | *(none)* | Bearer token for hook auth |
+| `AWM_INCOGNITO` | *(unset)* | Set to `1` to disable all tools |
 
 ## Tech Stack
 
@@ -365,8 +335,22 @@ The edge case suite is particularly important because it tests the failure modes
 | Tests | Vitest 4 |
 | Validation | Zod 4 |
 
-All three ML models (embedding, reranker, query expander) run locally via ONNX — no OpenAI, no Anthropic API, no external calls for retrieval. The entire system is a single SQLite file + a Node.js process.
+All three ML models run locally via ONNX. No external API calls for retrieval. The entire system is a single SQLite file + a Node.js process.
+
+## Project Status
+
+AWM is in active development (v0.4.x). The core memory pipeline, consolidation system, and MCP integration are stable and used daily in production coding workflows.
+
+- Core retrieval and consolidation: **stable**
+- MCP tools and Claude Code integration: **stable**
+- Task management: **stable**
+- Hook sidecar and auto-checkpoint: **stable**
+- HTTP API: **stable** (for custom agents)
+
+See [CHANGELOG.md](CHANGELOG.md) for version history.
+
+---
 
 ## License
 
-MIT
+Apache 2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

package/dist/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAC"}

package/dist/api/index.js

@@ -1,2 +1,4 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 export * from './routes.js';
 //# sourceMappingURL=index.js.map

package/dist/api/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/api/index.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,sCAAsC;AACtC,cAAc,aAAa,CAAC"}

package/dist/api/routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/api/routes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAQnF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,cAAc,EAAE,cAAc,CAAC;IAC/B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,UAAU,EAAE,UAAU,CAAC;IACvB,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,sBAAsB,EAAE,sBAAsB,CAAC;CAChD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CAsd3E"}
+{"version":3,"file":"routes.d.ts","sourceRoot":"","sources":["../../src/api/routes.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACtE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAQnF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,WAAW,CAAC;IACnB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,cAAc,EAAE,cAAc,CAAC;IAC/B,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,UAAU,EAAE,UAAU,CAAC;IACvB,mBAAmB,EAAE,mBAAmB,CAAC;IACzC,sBAAsB,EAAE,sBAAsB,CAAC;CAChD;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI,CA4d3E"}

package/dist/api/routes.js

@@ -1,3 +1,5 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
 /**
  * API Routes — the black box interface agents interact with.
  *
@@ -40,6 +42,11 @@ export function registerRoutes(app, deps) {
     // ============================================================
     app.post('/memory/write', async (req, reply) => {
         const body = req.body;
+        if (!body.agentId || typeof body.agentId !== 'string' ||
+            !body.concept || typeof body.concept !== 'string' ||
+            !body.content || typeof body.content !== 'string') {
+            return reply.status(400).send({ error: 'agentId, concept, and content are required strings' });
+        }
         const novelty = computeNovelty(store, body.agentId, body.concept, body.content);
         const salience = evaluateSalience({
             content: body.content,