Skip to content

#1 Persistent memory for AI coding agents based on real-world benchmarks

docs: rewrite README for v0.3.0 — what, why, and agent support (#5)

Rohit Ghumared400b051da3e
diff --git a/README.md b/README.md
index 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> &bull;
+ <a href="#supported-agents">Agents</a> &bull;
<a href="#quick-start">Quick Start</a> &bull;
<a href="#how-it-works">How It Works</a> &bull;
- <a href="#self-evaluation">Self-Evaluation</a> &bull;
- <a href="#mcp-server">MCP Server</a> &bull;
- <a href="#skills">Skills</a> &bull;
+ <a href="#search">Search</a> &bull;
+ <a href="#memory-evolution">Memory Evolution</a> &bull;
+ <a href="#mcp-server">MCP</a> &bull;
<a href="#configuration">Configuration</a> &bull;
- <a href="#api">API</a> &bull;
- <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 bugs
agentmemory silently captures every tool use
Session 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.git
cd agentmemory
-# Start iii-engine
-docker compose up -d
-
-# Install, build, run
+docker compose up -d # Start iii-engine
npm install && npm run build && npm start
```
@@ -77,27 +143,21 @@ npm install && npm run build && npm start
curl 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 tools
POST /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}}'
-```
-
## Skills
Four 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 Variables
Create `~/.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.
-
## Architecture
agentmemory 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
```bash
npm 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.png
new file mode 100644
index 00000000..6fff482d
Binary files /dev/null and b/assets/banner.png differ