agent-working-memory 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CompleteIdeas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,311 @@
+# AgentWorkingMemory (AWM)
+
+**Cognitive memory for AI agents — so they stop forgetting everything between conversations.**
+
+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 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.
+
+## How It's Different
+
+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:
+
+| Feature | Typical RAG/Vector Store | AWM |
+|---------|------------------------|-----|
+| **What gets stored** | Everything | Only salient events (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.
+
+## Benchmarks
+
+| 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 |
+
+## Getting Started
+
+### Prerequisites
+
+You need **Node.js 20 or newer** installed on your machine. That's it — no Python, no Docker, no API keys, no cloud accounts.
+
+**Don't have Node.js?** Download the LTS version from [nodejs.org](https://nodejs.org). Run `node --version` in your terminal to check — if you see `v20.x.x` or higher, you're good.
+
+### Step 1: Get the Code
+
+```bash
+git clone https://github.com/CompleteIdeas/AgentWorkingMemory.git
+cd AgentWorkingMemory
+```
+
+### Step 2: Install Dependencies
+
+```bash
+npm install
+```
+
+This installs everything AWM needs. Takes about a minute depending on your internet connection.
+
+### Step 3: Start the Server
+
+```bash
+npx tsx src/index.ts
+```
+
+**The first time you run this, it downloads three small ML models (~124MB total).** These are cached locally in a `models/` folder — you'll never need to download them again. No API keys, no cloud calls. Everything runs on your machine.
+
+Once you see `AWM server listening on port 8400`, the server is ready.
+
+### Step 4: Try It Out
+
+Open a second terminal. Write a memory:
+
+```bash
+curl -X POST http://localhost:8400/memory/write \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agentId": "my-agent",
+    "concept": "Express error handling",
+    "content": "Use centralized error middleware as the last app.use()",
+    "eventType": "causal",
+    "surprise": 0.5,
+    "causalDepth": 0.7
+  }'
+```
+
+Now recall it by asking a question:
+
+```bash
+curl -X POST http://localhost:8400/memory/activate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agentId": "my-agent",
+    "context": "How should I handle errors in my Express API?"
+  }'
+```
+
+You should see the memory come back with a relevance score and an explanation of why it matched. That's the 10-phase retrieval pipeline doing its thing.
+
+### Tips for Technical People
+
+- **Change the port:** `AWM_PORT=3000 npx tsx src/index.ts`
+- **Custom database location:** `AWM_DB_PATH=/path/to/memory.db npx tsx src/index.ts`
+- **Run unit tests:** `npx vitest run` (47 tests, no server needed)
+- **Run eval suite:** Start the server first, then `npm run test:self` in another terminal
+- **Data lives in a single file:** `memory.db` in the project root (SQLite). Back it up, move it, delete it to start fresh.
+- **Models are cached locally:** First run downloads to `models/`. No network calls after that.
+
+---
+
+## Using with Claude Code (MCP Integration)
+
+This is the main use case — giving Claude Code persistent memory across conversations. AWM connects to Claude Code through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), which lets Claude use AWM's memory tools directly.
+
+### Step 1: Find your project's MCP config
+
+In the project where you want Claude to have memory, create or edit `.mcp.json` in the project root:
+
+```json
+{
+  "mcpServers": {
+    "agent-working-memory": {
+      "command": "npx",
+      "args": ["tsx", "C:/path/to/AgentWorkingMemory/src/mcp.ts"],
+      "env": {
+        "AWM_DB_PATH": "C:/path/to/memory.db",
+        "AWM_AGENT_ID": "claude-code"
+      }
+    }
+  }
+}
+```
+
+**Replace the paths** with the actual location where you cloned AgentWorkingMemory. Use forward slashes even on Windows.
+
+### Step 2: Restart Claude Code
+
+Close and reopen Claude Code (or run `/mcp` to reload). Claude will now have 9 new tools:
+
+| Tool | What it does |
+|------|-------------|
+| `memory_write` | Store a memory with salience metadata |
+| `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_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 |
+
+### Step 3: Use it naturally
+
+You don't need to tell Claude to "use memory." Once MCP is connected, Claude will automatically write important decisions, recall relevant context, and learn from feedback. Over time, it builds up project knowledge that persists across every conversation.
+
+**Pro tip:** You can use the same `memory.db` file across multiple projects if you want shared knowledge. Or use different databases per project for isolation — your call.
+
+---
+
+## 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.
+
+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.
+
+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.
+
+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
+
+5. **Feedback** — Agents report whether recalled memories were useful. Positive feedback raises confidence (improving retrieval rank and forgetting resistance); negative feedback lowers it.
+
+### Cognitive Model
+
+AWM is built on established cognitive science, not ad-hoc heuristics:
+
+- **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
+
+```
+src/
+  core/             # Cognitive primitives
+    embeddings.ts     - Local vector embeddings (MiniLM-L6-v2, 384d)
+    reranker.ts       - Cross-encoder passage scoring (ms-marco-MiniLM)
+    query-expander.ts - Synonym expansion (flan-t5-small)
+    salience.ts       - Write-time importance scoring
+    decay.ts          - ACT-R temporal activation decay
+    hebbian.ts        - Association strengthening/weakening
+  engine/           # Processing pipelines
+    activation.ts     - 10-phase retrieval pipeline
+    consolidation.ts  - 7-phase sleep cycle consolidation
+    connections.ts    - Discover links between memories
+    staging.ts        - Weak signal buffer (promote or discard)
+    retraction.ts     - Negative memory / corrections
+    eviction.ts       - Capacity enforcement
+  storage/
+    sqlite.ts         - SQLite + FTS5 persistence layer
+  api/
+    routes.ts         - HTTP endpoints (memory + task + system)
+  mcp.ts            - MCP server (9 tools for Claude Code)
+  index.ts          - HTTP server entry point
+```
+
+## Task Management
+
+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)
+
+```bash
+npx vitest run    # 47 tests — salience scoring, decay curves, Hebbian learning, etc.
+```
+
+### Eval Suites (start the server first: `npx tsx src/index.ts`)
+
+| 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.)
+
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `AWM_PORT` | `8400` | HTTP server port |
+| `AWM_DB_PATH` | `memory.db` | SQLite database path |
+| `AWM_AGENT_ID` | `claude-code` | Default agent ID (MCP) |
+| `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 |
+
+## Tech Stack
+
+| Component | Technology |
+|-----------|-----------|
+| Language | TypeScript (ES2022, strict) |
+| Database | SQLite via better-sqlite3 + FTS5 |
+| HTTP | Fastify 5 |
+| MCP | @modelcontextprotocol/sdk |
+| ML Runtime | @huggingface/transformers (local ONNX) |
+| 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.
+
+## License
+
+MIT

package/dist/api/index.d.ts

@@ -0,0 +1,2 @@
+export * from './routes.js';
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/api/index.js

@@ -0,0 +1,2 @@
+export * from './routes.js';
+//# sourceMappingURL=index.js.map

package/dist/api/index.js.map

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

package/dist/api/routes.d.ts

@@ -0,0 +1,53 @@
+/**
+ * API Routes — the black box interface agents interact with.
+ *
+ * Core (agent-facing):
+ *   POST /memory/write       — write a memory (salience filter decides disposition)
+ *   POST /memory/activate    — retrieve by context activation
+ *   POST /memory/feedback    — report whether a memory was useful
+ *   POST /memory/retract     — invalidate a wrong memory
+ *
+ * Checkpointing:
+ *   POST /memory/checkpoint        — save explicit execution state
+ *   GET  /memory/restore/:agentId  — restore state + targeted recall + async mini-consolidation
+ *
+ * Task management:
+ *   POST /task/create         — create a prioritized task
+ *   POST /task/update         — update status, priority, or blocking
+ *   GET  /task/list/:agentId  — list tasks (filtered by status)
+ *   GET  /task/next/:agentId  — get highest-priority actionable task
+ *
+ * Diagnostic (debugging/eval):
+ *   POST /memory/search      — deterministic search (not cognitive)
+ *   GET  /memory/:id         — get a specific engram
+ *   GET  /agent/:id/stats    — memory stats for an agent
+ *   GET  /agent/:id/metrics  — eval metrics
+ *   POST /agent/register     — register a new agent
+ *
+ * System:
+ *   POST /system/evict       — trigger eviction check
+ *   POST /system/decay       — trigger edge decay
+ *   POST /system/consolidate — run sleep cycle (strengthen, decay, sweep)
+ *   GET  /health             — health check
+ */
+import type { FastifyInstance } from 'fastify';
+import type { EngramStore } from '../storage/sqlite.js';
+import type { ActivationEngine } from '../engine/activation.js';
+import type { ConnectionEngine } from '../engine/connections.js';
+import type { EvictionEngine } from '../engine/eviction.js';
+import type { RetractionEngine } from '../engine/retraction.js';
+import type { EvalEngine } from '../engine/eval.js';
+import type { ConsolidationEngine } from '../engine/consolidation.js';
+import type { ConsolidationScheduler } from '../engine/consolidation-scheduler.js';
+export interface MemoryDeps {
+    store: EngramStore;
+    activationEngine: ActivationEngine;
+    connectionEngine: ConnectionEngine;
+    evictionEngine: EvictionEngine;
+    retractionEngine: RetractionEngine;
+    evalEngine: EvalEngine;
+    consolidationEngine: ConsolidationEngine;
+    consolidationScheduler: ConsolidationScheduler;
+}
+export declare function registerRoutes(app: FastifyInstance, deps: MemoryDeps): void;
+//# sourceMappingURL=routes.d.ts.map

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

@@ -0,0 +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,CAmd3E"}