#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
docs: rewrite README for v0.3.0 — what, why, and agent support (#5)
Rohit Ghumared400b051da3e
diff --git a/README.md b/README.mdindex c2aed5c1..306580df 100644--- a/README.md+++ b/README.md@@ -1,28 +1,33 @@<p align="center">- <h1 align="center">agentmemory</h1>- <p align="center">Persistent memory for AI coding agents.<br/>Powered by <a href="https://iii.dev">iii-engine</a>.</p>+ <img src="assets/banner.png" alt="agentmemory — Persistent memory for AI coding agents" width="720" /></p><p align="center">+ <strong>Persistent memory for AI coding agents.</strong><br/>+ Powered by <a href="https://iii.dev">iii-engine</a>.+</p>++<p align="center">+ <a href="#why-agentmemory">Why</a> •+ <a href="#supported-agents">Agents</a> •<a href="#quick-start">Quick Start</a> •<a href="#how-it-works">How It Works</a> •- <a href="#self-evaluation">Self-Evaluation</a> •- <a href="#mcp-server">MCP Server</a> •- <a href="#skills">Skills</a> •+ <a href="#search">Search</a> •+ <a href="#memory-evolution">Memory Evolution</a> •+ <a href="#mcp-server">MCP</a> •<a href="#configuration">Configuration</a> •- <a href="#api">API</a> •- <a href="#plugin-install">Plugin Install</a>+ <a href="#api">API</a></p>----Your AI coding agent forgets everything between sessions. agentmemory fixes that.+## Why agentmemory-It silently captures tool usage during coding sessions, compresses observations via LLM, and injects relevant context into future sessions. No manual notes. No copy-pasting. The agent just *knows*.+AI coding agents forget everything between sessions. You explain the same architecture, re-discover the same patterns, and re-learn the same preferences every time. agentmemory fixes that.```Session 1: "Add auth to the API"- Claude Code writes code, runs tests, fixes bugs+ Agent writes code, runs tests, fixes bugsagentmemory silently captures every tool useSession ends -> observations compressed into structured memory@@ -31,25 +36,89 @@ Session 2: "Now add rate limiting"- Auth uses JWT middleware in src/middleware/auth.ts- Tests in test/auth.test.ts cover token validation- Decision: chose jose over jsonwebtoken for Edge compatibility- Claude Code starts with full project awareness+ Agent starts with full project awareness+```++No manual notes. No copy-pasting. The agent just *knows*.++### What it gives you++| Capability | What it does |+|---|---|+| **Automatic capture** | Every tool use, file edit, test run, and error is silently recorded via hooks |+| **LLM compression** | Raw observations are compressed into structured facts, concepts, and narratives |+| **Context injection** | Past knowledge is injected at session start within a configurable token budget |+| **Semantic search** | Hybrid BM25 + vector search finds relevant memories even with different wording |+| **Memory evolution** | Memories version over time, supersede each other, and form relationship graphs |+| **Project profiles** | Aggregated per-project intelligence: top concepts, files, conventions, common errors |+| **Auto-forgetting** | TTL expiry, contradiction detection, and importance-based eviction keep memory clean |+| **Privacy first** | API keys, secrets, and `<private>` tags are stripped before anything is stored |+| **Self-healing** | Circuit breaker, provider fallback chain, self-correcting LLM output, health monitoring |++### How it compares++| | CLAUDE.md | agentmemory |+|---|---|---|+| Storage | Flat file | iii-engine KV (persistent, distributed) |+| Capture | Manual | All 12 hook types |+| Search | Text find | Hybrid BM25 + vector (6 embedding providers) |+| Intelligence | None | LLM compression, quality scoring, self-correction |+| Memory model | Append-only | Versioned with relationships and evolution |+| Forgetting | Manual delete | Auto-forget (TTL, contradictions, importance) |+| Multi-agent | One file | Shared KV with project-scoped profiles |+| Observability | None | Health monitor, circuit breaker, OTEL telemetry |+| Integration | Built-in | Plugin + MCP server + REST API + slash commands |++## Supported Agents++agentmemory works with any agent that supports hooks, MCP, or via its REST API.++### Native hook support (zero config)++These agents support hooks natively. agentmemory captures tool usage automatically via its 12 hooks.++| Agent | Integration | Setup |+|---|---|---|+| **Claude Code** | 12 hooks (all types) | `/plugin install agentmemory` or manual hook config |+| **Claude Code SDK** | Agent SDK provider | Built-in `AgentSDKProvider` uses your Claude subscription |++### MCP support (any MCP-compatible agent)++Any agent that connects to MCP servers can use agentmemory's 10 tools. The agent actively queries and saves memory through MCP calls.++| Agent | How to connect |+|---|---|+| **Claude Desktop** | Add to `claude_desktop_config.json` MCP servers |+| **Cursor** | Add MCP server in settings |+| **Windsurf** | MCP server configuration |+| **Cline / Continue** | MCP server configuration |+| **Any MCP client** | Point to `http://localhost:3111/agentmemory/mcp/*` |++### REST API (any agent, any language)++Agents without hooks or MCP can integrate via the 28 REST endpoints directly. This works with any agent, language, or framework.++```bash+POST /agentmemory/observe # Capture what the agent did+POST /agentmemory/smart-search # Find relevant memories+POST /agentmemory/context # Get context for injection+POST /agentmemory/remember # Save long-term memory+GET /agentmemory/profile # Get project intelligence```-## What's New in v0.2.0+### Choosing an integration method-- **Self-evaluation framework** — Zod I/O validation, quality scoring (0-100), self-correcting LLM retries, per-function metrics-- **Health monitoring** — Real-time CPU, memory, event loop lag tracking with degraded/critical alerts-- **Circuit breaker** — Automatic failover when LLM providers go down (closed → open → half-open recovery)-- **BM25 search** — Replaced basic TF scoring with BM25 (k1=1.2, b=0.75) for better search relevance-- **Deduplication** — SHA-256 content hashing with 5-minute TTL window prevents duplicate observations-- **Memory eviction** — Age-based + importance-based + per-project cap eviction with dry-run support-- **MCP server** — 5 tools for any MCP-compatible client (memory_recall, memory_save, memory_file_history, memory_patterns, memory_sessions)-- **4 skills** — /recall, /remember, /session-history, /forget-- **12 hooks** — All Claude Code hook types covered (up from 5)-- **OTEL telemetry** — Counters and histograms for observability+| Your situation | Use |+|---|---|+| Claude Code user | Plugin install (hooks + MCP + skills) |+| Building a custom agent with Claude SDK | AgentSDKProvider (zero config) |+| Using Cursor, Windsurf, or any MCP client | MCP server (10 tools) |+| Building your own agent framework | REST API (28 endpoints) |+| Sharing memory across multiple agents | All agents point to the same iii-engine instance |## Quick Start-### 1. Install the Plugin+### 1. Install the Plugin (Claude Code)```bash/plugin marketplace add rohitg00/agentmemory@@ -64,10 +133,7 @@ All 12 hooks, 4 skills, and MCP server are registered automatically.git clone https://github.com/rohitg00/agentmemory.gitcd agentmemory-# Start iii-engine-docker compose up -d--# Install, build, run+docker compose up -d # Start iii-enginenpm install && npm run build && npm start```@@ -77,27 +143,21 @@ npm install && npm run build && npm startcurl http://localhost:3111/agentmemory/health```-Returns real health data:-```json{"status": "healthy","service": "agentmemory",- "version": "0.2.0",+ "version": "0.3.0","health": {"memory": { "heapUsed": 42000000, "heapTotal": 67000000 },"cpu": { "percent": 2.1 },"eventLoopLagMs": 1.2,- "status": "healthy",- "alerts": []+ "status": "healthy"},- "functionMetrics": [...],"circuitBreaker": { "state": "closed", "failures": 0 }}```-HTTP 503 when status is `critical`.-### Manual Hook Setup (alternative)If you prefer not to use the plugin, add hooks directly to `~/.claude/settings.json`:@@ -125,31 +185,26 @@ If you prefer not to use the plugin, add hooks directly to `~/.claude/settings.j### Observation Pipeline-Every tool use flows through this pipeline:-```PostToolUse hook fires- -> Dedup check SHA-256 hash of tool_name + tool_input (5min window)+ -> Dedup check SHA-256 hash (5min window, no duplicates)-> mem::privacy Strip secrets, API keys, <private> tags-> mem::observe Store raw observation, push to real-time stream-> mem::compress LLM extracts: type, facts, narrative, concepts, files- Validates output with Zod, scores quality (0-100)+ Validates with Zod, scores quality (0-100)Self-corrects on validation failure (1 retry)- Records latency + quality in per-function metrics+ Generates vector embedding for semantic search```### Context Injection-On `SessionStart`, agentmemory builds context from your history:-```SessionStart hook fires-> mem::context Load recent sessions for this project- BM25-ranked search across observations- Prefer summaries, fall back to high-importance observations+ Hybrid search (BM25 + vector) across observations+ Inject project profile (top concepts, files, patterns)Apply token budget (default: 2000 tokens)- Return formatted context block- -> stdout Claude Code injects it into the conversation+ -> stdout Agent receives context in the conversation```### What Gets Captured@@ -162,82 +217,164 @@ SessionStart hook fires| `PostToolUse` | Tool name, input, output || `PostToolUseFailure` | Failed tool invocations with error context || `PreCompact` | Re-injects memory context before context compaction |-| `SubagentStart` | Sub-agent spawning events |-| `SubagentStop` | Sub-agent completion events |+| `SubagentStart/Stop` | Sub-agent lifecycle events || `Notification` | System notifications || `TaskCompleted` | Task completion events || `Stop` | Triggers end-of-session summary || `SessionEnd` | Marks session complete |-### Privacy+## Search-All data passes through `mem::privacy` before storage:-- `<private>...</private>` tags are stripped-- API keys (`sk-*`, `ghp_*`, `xoxb-*`, `AKIA*`), JWTs, and secrets are redacted+agentmemory v0.3.0 supports hybrid search combining keyword matching with semantic understanding.-## Self-Evaluation+### How search works-agentmemory v0.2.0 monitors its own health and validates its own I/O.+| Mode | When | How |+|---|---|---|+| **BM25 only** | No embedding API key configured | Keyword matching with BM25 (k1=1.2, b=0.75) |+| **Hybrid** | Any embedding key configured | BM25 + vector cosine similarity fused with Reciprocal Rank Fusion (k=60) |-### Quality Scoring+Hybrid search means "authentication middleware" finds results even if the stored text says "auth layer" or "JWT validation". BM25-only mode still works well for exact keyword matches.-Every LLM-generated compression and summary is scored 0-100:+### Embedding providers-| Check | Points |-|-------|--------|-| Has structured facts | +20 |-| Narrative length > 10 chars | +20 |-| Concepts extracted | +20 |-| Title quality (not truncated) | +20 |-| Importance in valid range (1-10) | +20 |+agentmemory auto-detects which provider to use from your environment variables. No embedding key? It falls back to BM25-only mode with zero degradation.++| Provider | Model | Dimensions | Env Var | Notes |+|---|---|---|---|---|+| Gemini | `text-embedding-004` | 768 | `GEMINI_API_KEY` | Free tier (1500 RPM) |+| OpenAI | `text-embedding-3-small` | 1536 | `OPENAI_API_KEY` | $0.02/1M tokens |+| Voyage AI | `voyage-code-3` | 1024 | `VOYAGE_API_KEY` | Optimized for code |+| Cohere | `embed-english-v3.0` | 1024 | `COHERE_API_KEY` | Free trial available |+| OpenRouter | Any embedding model | varies | `OPENROUTER_API_KEY` | Multi-model proxy |+| Local | `all-MiniLM-L6-v2` | 384 | (none) | Offline, optional `@xenova/transformers` |++Override auto-detection with `EMBEDDING_PROVIDER=voyage` in your `.env`.++### Progressive disclosure++Smart search returns compact results first (title, type, score, timestamp) to save tokens. Expand specific IDs to get full observation details.++```bash+# Compact results (50-100 tokens each)+curl -X POST http://localhost:3111/agentmemory/smart-search \+ -d '{"query": "database migration"}'-Scores are tracked per-function and exposed via the `/health` endpoint.+# Expand specific results (500-1000 tokens each)+curl -X POST http://localhost:3111/agentmemory/smart-search \+ -d '{"expandIds": ["obs_abc123", "obs_def456"]}'+```-### Self-Correction+## Memory Evolution-When LLM output fails Zod validation, agentmemory retries once with a stricter prompt suffix explaining the exact validation errors. This recovers from malformed JSON, missing fields, and out-of-range values.+Memories in agentmemory are not static. They version, evolve, and form relationships.-### Circuit Breaker+### Versioning-LLM providers fail. The circuit breaker prevents cascading failures:+When you save a memory that's similar to an existing one (Jaccard > 0.7), the old memory is superseded:```-Closed (normal)- -> 3 failures in 60s -> Open (all calls rejected)- -> 30s cooldown -> Half-Open (one test call allowed)- -> Success -> Closed (normal)- -> Failure -> Open (restart cooldown)+v1: "Use Express for API routes"+v2: "Use Fastify instead of Express for API routes" (supersedes v1)+v3: "Use Hono instead of Fastify for Edge API routes" (supersedes v2)```-When the circuit is open, observations are stored raw without compression. No data is lost.+Only the latest version is returned in search results. The full chain is preserved for audit.++### Relationships++Memories can be linked: `supersedes`, `extends`, `derives`, `contradicts`, `related`. Traversal follows these links up to N hops.++### Auto-forget++agentmemory automatically cleans itself:-### Health Monitor+| Mechanism | What it does |+|---|---|+| **TTL expiry** | Memories with `forgetAfter` date are deleted when expired |+| **Contradiction detection** | Near-duplicate memories (Jaccard > 0.9) — older one is demoted |+| **Low-value eviction** | Observations older than 90 days with importance < 3 are removed |+| **Per-project cap** | Projects are capped at 10,000 observations (lowest importance evicted first) |++Run `POST /agentmemory/auto-forget?dryRun=true` to preview what would be cleaned.++### Project profiles-Collects every 30 seconds:-- **Memory**: heap used/total, RSS, external-- **CPU**: user/system time, real percentage via delta sampling-- **Event loop lag**: detect blocking operations-- **Connection state**: engine connectivity+agentmemory aggregates observations into per-project intelligence:++```bash+curl "http://localhost:3111/agentmemory/profile?project=/my/project"+```-Thresholds:-| Metric | Warning | Critical |-|--------|---------|----------|-| Event loop lag | > 100ms | > 500ms |-| CPU | > 80% | > 90% |-| Heap usage | > 80% | > 95% |-| Connection | reconnecting | disconnected |+Returns top concepts, most-touched files, coding conventions, common errors, and a session count. This profile is automatically injected into session context.++### Timeline++Navigate observations chronologically around any anchor point:++```bash+curl -X POST http://localhost:3111/agentmemory/timeline \+ -d '{"anchor": "2026-02-15", "before": 5, "after": 5}'+```++### Export / Import++Full data portability:++```bash+# Export everything+curl http://localhost:3111/agentmemory/export > backup.json++# Import with merge strategy+curl -X POST http://localhost:3111/agentmemory/import \+ -d '{"exportData": ..., "strategy": "merge"}'+```++Strategies: `merge` (combine), `replace` (overwrite), `skip` (ignore duplicates).++## Self-Evaluation++agentmemory monitors its own health and validates its own output.++### Quality scoring++Every LLM compression is scored 0-100 based on structured facts, narrative quality, concept extraction, title quality, and importance range. Scores are tracked per-function and exposed via `/health`.++### Self-correction++When LLM output fails Zod validation, agentmemory retries with a stricter prompt explaining the exact errors. This recovers from malformed JSON, missing fields, and out-of-range values.++### Circuit breaker + fallback chain++```+Primary provider fails+ -> Circuit breaker opens (3 failures in 60s)+ -> Falls back to next provider in FALLBACK_PROVIDERS chain+ -> 30s cooldown -> half-open -> test call -> recovery+```++Configure with `FALLBACK_PROVIDERS=anthropic,gemini,openrouter`. When all providers are down, observations are stored raw without compression. No data is lost.++### Health monitor++Collects every 30 seconds: heap usage, CPU percentage (delta sampling), event loop lag, connection state. Alerts at warning (80% CPU, 100ms lag) and critical (90% CPU, 500ms lag) thresholds. `GET /agentmemory/health` returns HTTP 503 when critical.## MCP Server-agentmemory exposes 5 tools via MCP for any compatible client:+10 tools for any MCP-compatible client:| Tool | Description ||------|-------------|| `memory_recall` | Search past observations by keyword |-| `memory_save` | Save an insight, decision, or pattern to long-term memory |+| `memory_save` | Save an insight, decision, or pattern || `memory_file_history` | Get past observations about specific files || `memory_patterns` | Detect recurring patterns across sessions || `memory_sessions` | List recent sessions with status |+| `memory_smart_search` | Hybrid semantic + keyword search with progressive disclosure |+| `memory_timeline` | Chronological observations around an anchor point |+| `memory_profile` | Project profile with top concepts, files, patterns |+| `memory_export` | Export all memory data as JSON |+| `memory_relations` | Query memory relationship graph |### MCP Endpoints@@ -246,14 +383,6 @@ GET /agentmemory/mcp/tools — List available toolsPOST /agentmemory/mcp/call — Execute a tool```-### Example--```bash-curl -X POST http://localhost:3111/agentmemory/mcp/call \- -H "Content-Type: application/json" \- -d '{"name": "memory_recall", "arguments": {"query": "authentication", "limit": 5}}'-```-## SkillsFour slash commands for interacting with memory:@@ -269,48 +398,56 @@ Four slash commands for interacting with memory:### LLM Providers-agentmemory needs an LLM for compressing observations and generating session summaries.+agentmemory needs an LLM for compressing observations and generating summaries. It auto-detects from your environment.-| Provider | Config | Cost |-|----------|--------|------|-| **Claude subscription** (default) | No config needed | Included in Max/Pro |-| **Anthropic API** | `ANTHROPIC_API_KEY` | Per-token |-| **Gemini** | `GEMINI_API_KEY` | Per-token |-| **OpenRouter** | `OPENROUTER_API_KEY` | Per-token |+| Provider | Config | Notes |+|----------|--------|-------|+| **Claude subscription** (default) | No config needed | Uses `@anthropic-ai/claude-agent-sdk`. Zero cost beyond your Max/Pro plan |+| **Anthropic API** | `ANTHROPIC_API_KEY` | Direct API access, per-token billing |+| **Gemini** | `GEMINI_API_KEY` | Also enables Gemini embeddings (free tier) |+| **OpenRouter** | `OPENROUTER_API_KEY` | Access any model through one API |-No API key? agentmemory uses your Claude subscription automatically via `@anthropic-ai/claude-agent-sdk`. Zero config.+No API key? agentmemory uses your Claude subscription automatically. Zero config.### Environment VariablesCreate `~/.agentmemory/.env`:```env-# LLM provider -- pick one (or leave empty for subscription mode)+# LLM provider (pick one, or leave empty for Claude subscription)ANTHROPIC_API_KEY=sk-ant-...# GEMINI_API_KEY=...# OPENROUTER_API_KEY=...-# Optional: override model-# ANTHROPIC_MODEL=claude-sonnet-4-20250514-# GEMINI_MODEL=gemini-2.0-flash-# OPENROUTER_MODEL=anthropic/claude-sonnet-4-20250514+# Embedding provider (auto-detected from LLM keys, or override)+# EMBEDDING_PROVIDER=voyage+# VOYAGE_API_KEY=...+# OPENAI_API_KEY=...+# COHERE_API_KEY=...-# Optional: bearer token for API auth+# Hybrid search weights (default: 0.4 BM25 + 0.6 vector)+# BM25_WEIGHT=0.4+# VECTOR_WEIGHT=0.6++# Provider fallback chain (comma-separated, tried in order)+# FALLBACK_PROVIDERS=anthropic,gemini,openrouter++# Bearer token for API auth# AGENTMEMORY_SECRET=your-secret-here-# Optional: engine connection+# Engine connection# III_ENGINE_URL=ws://localhost:49134# III_REST_PORT=3111# III_STREAMS_PORT=3112-# Optional: memory tuning+# Memory tuning# TOKEN_BUDGET=2000# MAX_OBS_PER_SESSION=500```## API-All endpoints on port `3111`. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set.+28 endpoints on port `3111`. Protected endpoints require `Authorization: Bearer <secret>` when `AGENTMEMORY_SECRET` is set.| Method | Path | Description ||--------|------|-------------|@@ -320,6 +457,7 @@ All endpoints on port `3111`. Protected endpoints require `Authorization: Bearer| `POST` | `/agentmemory/observe` | Capture observation || `POST` | `/agentmemory/context` | Generate context || `POST` | `/agentmemory/search` | Search observations (BM25) |+| `POST` | `/agentmemory/smart-search` | Hybrid search with progressive disclosure || `POST` | `/agentmemory/summarize` | Generate session summary || `POST` | `/agentmemory/remember` | Save to long-term memory || `POST` | `/agentmemory/forget` | Delete observations/sessions |@@ -327,57 +465,21 @@ All endpoints on port `3111`. Protected endpoints require `Authorization: Bearer| `POST` | `/agentmemory/patterns` | Detect recurring patterns || `POST` | `/agentmemory/generate-rules` | Generate CLAUDE.md rules from patterns || `POST` | `/agentmemory/file-context` | Get file-specific history |-| `POST` | `/agentmemory/evict` | Evict stale memories (supports `?dryRun=true`) |+| `POST` | `/agentmemory/evict` | Evict stale memories (`?dryRun=true`) || `POST` | `/agentmemory/migrate` | Import from SQLite |+| `POST` | `/agentmemory/timeline` | Chronological observations around anchor |+| `POST` | `/agentmemory/relations` | Create memory relationship |+| `POST` | `/agentmemory/evolve` | Evolve memory (new version) |+| `POST` | `/agentmemory/auto-forget` | Run auto-forget (`?dryRun=true`) |+| `POST` | `/agentmemory/import` | Import data from JSON |+| `GET` | `/agentmemory/profile` | Project profile (`?project=/path`) |+| `GET` | `/agentmemory/export` | Export all data as JSON || `GET` | `/agentmemory/sessions` | List all sessions |-| `GET` | `/agentmemory/observations?sessionId=X` | Session observations |+| `GET` | `/agentmemory/observations` | Session observations (`?sessionId=X`) || `GET` | `/agentmemory/viewer` | Real-time web viewer || `GET` | `/agentmemory/mcp/tools` | List MCP tools || `POST` | `/agentmemory/mcp/call` | Execute MCP tool |-### Examples--```bash-# Start a session-curl -X POST http://localhost:3111/agentmemory/session/start \- -H "Content-Type: application/json" \- -d '{"sessionId": "ses-1", "project": "/my/project", "cwd": "/my/project"}'--# Capture an observation-curl -X POST http://localhost:3111/agentmemory/observe \- -H "Content-Type: application/json" \- -d '{- "hookType": "post_tool_use",- "sessionId": "ses-1",- "project": "/my/project",- "cwd": "/my/project",- "timestamp": "2026-02-25T12:00:00Z",- "data": {"tool": "Edit", "file": "src/auth.ts", "content": "Added JWT validation"}- }'--# Search across all observations (BM25-ranked)-curl -X POST http://localhost:3111/agentmemory/search \- -H "Content-Type: application/json" \- -d '{"query": "authentication middleware", "limit": 10}'--# Save something to long-term memory-curl -X POST http://localhost:3111/agentmemory/remember \- -H "Content-Type: application/json" \- -d '{"content": "Always use jose for JWT in Edge environments", "type": "preference"}'--# Preview memory eviction (dry run)-curl -X POST "http://localhost:3111/agentmemory/evict?dryRun=true"--# List sessions-curl http://localhost:3111/agentmemory/sessions-```--## Real-Time Viewer--Open [http://localhost:3111/agentmemory/viewer](http://localhost:3111/agentmemory/viewer) to watch observations flow in real-time.--Connects to iii-engine's WebSocket stream. Dark theme, timeline layout, session filtering, auto-scroll.-## Plugin Install### From Marketplace (recommended)@@ -398,20 +500,6 @@ Restart Claude Code. All 12 hooks, 4 skills, and MCP tools are registered automa/plugin uninstall agentmemory # Remove```-## Migration--Import from existing SQLite-based memory systems :--```bash-npm install better-sqlite3--curl -X POST http://localhost:3111/agentmemory/migrate \- -H "Content-Type: application/json" \- -d '{"dbPath": "~/.agentmemory/memory.db"}'-```--Imports sessions, observations, and summaries.-## Architectureagentmemory is built on iii-engine's three primitives:@@ -419,24 +507,25 @@ agentmemory is built on iii-engine's three primitives:| What you'd normally need | What agentmemory uses ||---|---|| Express.js / Fastify | iii HTTP Triggers |-| SQLite / Postgres | iii KV State |+| SQLite / Postgres + pgvector | iii KV State + in-memory vector index || SSE / Socket.io | iii Streams (WebSocket) || pm2 / systemd | iii-engine worker management || Prometheus / Grafana | iii OTEL + built-in health monitor |-| Redis (circuit breaker) | In-process circuit breaker |+| Redis (circuit breaker) | In-process circuit breaker + fallback chain |-**52 source files. ~4,800 LOC. 82 tests. 195KB bundled.**+**69 source files. ~5,600 LOC. 144 tests. 126KB bundled.**-### Functions+### Functions (21)| Function | Purpose ||----------|---------|| `mem::observe` | Store raw observation with dedup check |-| `mem::compress` | LLM compression with validation + quality scoring |+| `mem::compress` | LLM compression with validation + quality scoring + embedding || `mem::search` | BM25-ranked full-text search |+| `mem::smart-search` | Hybrid search with progressive disclosure || `mem::context` | Build session context within token budget || `mem::summarize` | Generate validated session summaries |-| `mem::remember` | Save to long-term memory |+| `mem::remember` | Save to long-term memory (auto-supersedes similar) || `mem::forget` | Delete observations, sessions, or memories || `mem::file-index` | File-specific observation lookup || `mem::consolidate` | Merge duplicate observations |@@ -444,25 +533,36 @@ agentmemory is built on iii-engine's three primitives:| `mem::generate-rules` | Generate CLAUDE.md rules from patterns || `mem::migrate` | Import from SQLite || `mem::evict` | Age + importance + cap-based memory eviction |+| `mem::relate` | Create relationship between memories |+| `mem::evolve` | Create new version of a memory |+| `mem::get-related` | Traverse memory relationship graph |+| `mem::timeline` | Chronological observations around anchor |+| `mem::profile` | Aggregate project profile |+| `mem::auto-forget` | TTL expiry + contradiction detection |+| `mem::export` / `mem::import` | Full JSON round-trip |### Data Model-| Scope | Key | Stores |-|-------|-----|--------|-| `mem:sessions` | `{session_id}` | Session metadata, project, timestamps |-| `mem:obs:{session_id}` | `{obs_id}` | Compressed observations |-| `mem:summaries` | `{session_id}` | End-of-session summaries |-| `mem:memories` | `{memory_id}` | Long-term memories (remember/forget) |-| `mem:metrics` | `{function_id}` | Per-function metrics (latency, quality, success rate) |-| `mem:health` | `latest` | Latest health snapshot |-| `mem:config` | `{key}` | Runtime configuration overrides |+| Scope | Stores |+|-------|--------|+| `mem:sessions` | Session metadata, project, timestamps |+| `mem:obs:{session_id}` | Compressed observations with embeddings |+| `mem:summaries` | End-of-session summaries |+| `mem:memories` | Long-term memories (versioned, with relationships) |+| `mem:relations` | Memory relationship graph |+| `mem:profiles` | Aggregated project profiles |+| `mem:emb:{obs_id}` | Vector embeddings |+| `mem:index:bm25` | Persisted BM25 index |+| `mem:metrics` | Per-function metrics |+| `mem:health` | Health snapshots |+| `mem:config` | Runtime configuration overrides |## Development```bashnpm run dev # Hot reload-npm run build # Production build-npm test # Unit tests (82 tests, ~300ms)+npm run build # Production build (126KB)+npm test # Unit tests (144 tests, ~700ms)npm run test:integration # API tests (requires running services)```diff --git a/assets/banner.png b/assets/banner.pngnew file mode 100644index 00000000..6fff482dBinary files /dev/null and b/assets/banner.png differ