@agentmemory/agentmemory 0.8.0 → 0.8.1

package/README.md

@@ -7,6 +7,13 @@
   Persistent memory for Claude Code, Cursor, Gemini CLI, OpenCode, and any MCP client.
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/@agentmemory/agentmemory"><img src="https://img.shields.io/npm/v/@agentmemory/agentmemory?color=CB3837&label=npm" alt="npm version" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/actions"><img src="https://img.shields.io/github/actions/workflow/status/rohitg00/agentmemory/ci.yml?label=tests" alt="CI" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/blob/main/LICENSE"><img src="https://img.shields.io/github/license/rohitg00/agentmemory?color=blue" alt="License" /></a>
+  <a href="https://github.com/rohitg00/agentmemory/stargazers"><img src="https://img.shields.io/github/stars/rohitg00/agentmemory?style=flat&color=yellow" alt="Stars" /></a>
+</p>
+
 <p align="center">
   <img src="assets/demo.gif" alt="agentmemory demo" width="720" />
 </p>
@@ -14,23 +21,28 @@
 <p align="center">
   <a href="#quick-start">Quick Start</a> &bull;
   <a href="#why-agentmemory">Why</a> &bull;
-  <a href="#supported-agents">Agents</a> &bull;
+  <a href="#benchmarks-measured-not-projected">Benchmarks</a> &bull;
   <a href="#how-it-works">How It Works</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="#real-time-viewer">Viewer</a> &bull;
-  <a href="#configuration">Configuration</a> &bull;
+  <a href="#configuration">Config</a> &bull;
   <a href="#api">API</a>
 </p>
 
 ---
 
-You explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences. Built-in memory (CLAUDE.md, .cursorrules) caps out at 200 lines and goes stale. agentmemory fixes this — it silently captures what your agent does, compresses it into searchable memory, and injects the right context when the next session starts. One command. Works across agents.
+You explain the same architecture every session. You re-discover the same bugs. You re-teach the same preferences. Built-in memory (CLAUDE.md, .cursorrules) caps out at 200 lines and goes stale. agentmemory fixes this. It silently captures what your agent does, compresses it into searchable memory, and injects the right context when the next session starts. One command. Works across agents.
 
-**What changes:** Session 1 you set up JWT auth. Session 2 you ask for rate limiting — the agent already knows your auth uses jose middleware in `src/middleware/auth.ts`, your tests cover token validation, and you chose jose over jsonwebtoken for Edge compatibility. No re-explaining. No copy-pasting. The agent just *knows*.
+**What changes:** Session 1 you set up JWT auth. Session 2 you ask for rate limiting. The agent already knows your auth uses jose middleware in `src/middleware/auth.ts`, your tests cover token validation, and you chose jose over jsonwebtoken for Edge compatibility. No re-explaining. No copy-pasting. The agent just *knows*.
 
-**95.2% retrieval accuracy** on [LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025). 43 MCP tools. 12 hooks. Real-time viewer. Works with Claude Code, Cursor, Gemini CLI, OpenCode, and any MCP client. 646 tests. Zero external DB dependencies.
+| | |
+|---|---|
+| **95.2% R@5** | [LongMemEval](https://arxiv.org/abs/2410.10813) (ICLR 2025) retrieval accuracy |
+| **92% fewer tokens** | ~1,900 injected vs ~19,000 full context ($10/yr vs $500+/yr) |
+| **43 MCP tools** | Search, remember, forget, actions, leases, signals, mesh sync |
+| **12 hooks** | Captures every tool use automatically, zero manual effort |
+| **0 external deps** | No Postgres, no Redis, no vector DB. Just iii-engine (auto-installed) |
 
 ```bash
 npx @agentmemory/agentmemory   # installs iii-engine if missing, starts everything
@@ -38,6 +50,39 @@ npx @agentmemory/agentmemory   # installs iii-engine if missing, starts everythi
 
 ---
 
+## Quick Start
+
+### Claude Code (paste this, the agent does the rest)
+
+```
+Install agentmemory: run `npx @agentmemory/agentmemory` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` to register all 12 hooks, 4 skills, and 43 MCP tools. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113.
+```
+
+That's it. Paste the block above into Claude Code. The agent handles installation, engine startup, plugin registration, and verification.
+
+### Other agents
+
+Start the memory server first: `npx @agentmemory/agentmemory`
+
+Then add the MCP config for your agent. All agents use the same server, so memories are shared across them.
+
+| Agent | Setup |
+|---|---|
+| **OpenClaw** | Add to MCP config: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["agentmemory-mcp"]}}}` |
+| **Cursor** | Add to `~/.cursor/mcp.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["agentmemory-mcp"]}}}` |
+| **OpenCode** | Add to `.opencode/config.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["agentmemory-mcp"]}}}` |
+| **Codex CLI** | Add to `.codex/config.yaml`: `mcp_servers: {agentmemory: {command: npx, args: ["agentmemory-mcp"]}}` |
+| **Gemini CLI** | `gemini mcp add agentmemory -- npx agentmemory-mcp` |
+| **Hermes Agent** | Add to `~/.hermes/config.yaml`: `mcp_servers: {agentmemory: {command: npx, args: ["agentmemory-mcp"]}}` or use the [memory provider plugin](integrations/hermes/) |
+| **Cline** | Add MCP server in Cline settings |
+| **Goose** | Add to `~/.config/goose/config.yaml`: `mcp_servers: {agentmemory: {command: npx, args: ["agentmemory-mcp"]}}` |
+| **Kilo Code** | Add MCP server in Kilo Code settings |
+| **Aider** | Use REST API: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'` |
+| **Claude Desktop** | Add to `claude_desktop_config.json`: `{"mcpServers": {"agentmemory": {"command": "npx", "args": ["agentmemory-mcp"]}}}` |
+| **Any agent (32+)** | `npx skillkit install agentmemory` |
+
+---
+
 ## Why agentmemory
 
 Every coding agent forgets everything when the session ends. You waste the first 5 minutes of every session re-explaining your stack, your conventions, your recent decisions. agentmemory runs in the background and eliminates that entirely.
@@ -82,7 +127,7 @@ Session 2: "Now add rate limiting"
 
 ### How it compares to built-in agent memory
 
-Every AI coding agent now ships with built-in memory — Claude Code has `MEMORY.md`, Cursor has notepads, Windsurf has Cascade memories, Cline has memory bank. These work like sticky notes: fast, always-on, but fundamentally limited.
+Every AI coding agent now ships with built-in memory. Claude Code has `MEMORY.md`, Cursor has notepads, Cline has memory bank. These work like sticky notes: fast, always-on, but fundamentally limited.
 
 agentmemory is the searchable database behind the sticky notes.
 
@@ -103,6 +148,33 @@ agentmemory is the searchable database behind the sticky notes.
 | Knowledge graph | No | Entity extraction + temporal versioning |
 | Observability | Read files manually | Real-time viewer on :3113 |
 
+### What it costs (spoiler: almost nothing)
+
+| Approach | Tokens/year | Annual cost | Notes |
+|---|---|---|---|
+| Paste full history into context | 19.5M+ | Impossible | Exceeds context window after ~200 observations |
+| LLM-summarized memory (extraction-based) | ~650K | ~$500/yr | Loses context, summarization is lossy |
+| **agentmemory context injection** | **~170K** | **~$10/yr** | Token-budgeted, only relevant memories injected |
+| agentmemory with local embeddings | ~170K | **$0** | all-MiniLM-L6-v2 runs locally, no API calls |
+
+### How memory flows
+
+```text
+PostToolUse hook fires
+  -> SHA-256 dedup (5min window)
+  -> Privacy filter (strip secrets, API keys)
+  -> Store raw observation
+  -> LLM compress -> structured facts + concepts + narrative
+  -> Generate vector embedding
+  -> Index in BM25 + vector + knowledge graph
+
+SessionStart hook fires
+  -> Load project profile (top concepts, files, patterns)
+  -> Hybrid search (BM25 + vector + graph) for recent context
+  -> Apply token budget (default: 2000 tokens)
+  -> Inject into conversation via stdout
+```
+
 ### Benchmarks (measured, not projected)
 
 #### LongMemEval-S (ICLR 2025, 500 questions)
@@ -124,7 +196,9 @@ These are retrieval recall scores (not end-to-end QA accuracy). Embedding model:
 | agentmemory BM25 (stemmed + synonyms) | 55.9% | 82.7% | 95.5% | 1,571 |
 | agentmemory + Xenova embeddings | **64.1%** | **94.9%** | **100.0%** | **1,571** |
 
-agentmemory finds "N+1 query fix" when you search "database performance optimization" — something keyword matching literally cannot do.
+agentmemory finds "N+1 query fix" when you search "database performance optimization". Keyword matching can't do this.
+
+> **Methodology note:** All LongMemEval numbers are retrieval recall (`recall_any@K`), not end-to-end QA accuracy. We clearly distinguish these because the LongMemEval leaderboard measures QA accuracy (retrieve + generate + judge). No hyperparameters were tuned on the test set. Full scripts and results are committed and reproducible.
 
 Full benchmark reports: [`benchmark/LONGMEMEVAL.md`](benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](benchmark/QUALITY.md), [`benchmark/SCALE.md`](benchmark/SCALE.md), [`benchmark/REAL-EMBEDDINGS.md`](benchmark/REAL-EMBEDDINGS.md)
 
@@ -147,11 +221,17 @@ Any agent that connects to MCP servers can use agentmemory's 43 tools, 6 resourc
 
 | Agent | How to connect |
 |---|---|
-| **Cursor** | Add MCP server in settings or `~/.cursor/mcp.json` |
+| **OpenClaw** (345K stars) | Add MCP server in settings |
+| **OpenCode** (100K stars) | Add to `.opencode/config.json` MCP servers |
+| **Gemini CLI** (98K stars) | `gemini mcp add agentmemory -- npx agentmemory-mcp` |
+| **Codex CLI** (62K stars) | Add to `.codex/config.yaml` MCP servers |
+| **Cline** (59K stars) | Add MCP server in Cline settings |
+| **Cursor** (1M+ users) | Add MCP server in settings or `~/.cursor/mcp.json` |
+| **Hermes Agent** (33K stars) | MCP config or [memory provider plugin](integrations/hermes/) |
+| **Goose** (33K stars) | Add to `~/.config/goose/config.yaml` MCP servers |
+| **Kilo Code** (1.5M users) | Add MCP server in Kilo Code settings |
+| **Aider** (42K stars) | Use REST API (no MCP) |
 | **Claude Desktop** | Add to `claude_desktop_config.json` MCP servers |
-| **Gemini CLI** | `gemini mcp add agentmemory -- npx agentmemory-mcp` |
-| **OpenCode** | Add to `.opencode/config.json` MCP servers |
-| **Cline / Continue** | MCP server configuration |
 | **Any MCP client** | Point to `http://localhost:3111/agentmemory/mcp/*` |
 
 ### REST API (any agent, any language)
@@ -173,140 +253,21 @@ GET  /agentmemory/profile       # Get project intelligence
 |---|---|
 | Claude Code user | Plugin install (hooks + MCP + skills) |
 | Building a custom agent with Claude SDK | AgentSDKProvider (zero config) |
-| Using Cursor, Gemini CLI, OpenCode, or any MCP client | MCP server (43 tools + 6 resources + 3 prompts) |
+| OpenClaw, Cursor, Codex, OpenCode, Gemini CLI, Cline, Goose, Kilo Code | MCP server (43 tools + 6 resources + 3 prompts) |
+| Hermes Agent user | [Memory provider plugin](integrations/hermes/) (deeper) or MCP |
 | Building your own agent framework | REST API (103 endpoints) |
-| Sharing memory across multiple agents | All agents point to the same iii-engine instance |
+| Sharing memory across multiple agents | All agents point to the same agentmemory instance |
 
-## Quick Start
-
-### 1. Start agentmemory
-
-```bash
-npx @agentmemory/agentmemory
-```
-
-This auto-installs iii-engine if missing, starts it, and runs the worker. One command.
-
-Or from source:
+### From source
 
 ```bash
 git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
 npm install && npm run build && npm start
 ```
 
-### 2. Connect your agent
-
-**Claude Code (plugin — hooks + MCP + skills):**
-
-```bash
-/plugin marketplace add rohitg00/agentmemory
-/plugin install agentmemory
-```
-
-All 12 hooks, 4 skills, and MCP server are registered automatically.
-
-**Cursor / Claude Desktop / Cline / any MCP client:**
-
-Add to your MCP config (e.g. `~/.cursor/mcp.json`, `claude_desktop_config.json`):
-
-```json
-{
-  "mcpServers": {
-    "agentmemory": {
-      "command": "npx",
-      "args": ["agentmemory-mcp"]
-    }
-  }
-}
-```
-
-**Gemini CLI:**
-
-```bash
-gemini mcp add agentmemory -- npx agentmemory-mcp
-```
-
-**OpenCode:**
-
-Add to `.opencode/config.json`:
-
-```json
-{
-  "mcpServers": {
-    "agentmemory": {
-      "command": "npx",
-      "args": ["agentmemory-mcp"]
-    }
-  }
-}
-```
-
-**Any agent via SkillKit (32+ agents supported):**
-
-```bash
-npx skillkit install agentmemory
-```
-
-**REST API (any agent, any language):**
-
-```bash
-curl -X POST http://localhost:3111/agentmemory/remember \
-  -H "Content-Type: application/json" \
-  -d '{"content": "Always use jose for JWT on Edge", "type": "preference"}'
-
-curl -X POST http://localhost:3111/agentmemory/smart-search \
-  -H "Content-Type: application/json" \
-  -d '{"query": "JWT authentication"}'
-```
-
-### 3. Verify
-
-```bash
-curl http://localhost:3111/agentmemory/health
-open http://localhost:3113   # Real-time viewer
-```
-
-```json
-{
-  "status": "healthy",
-  "service": "agentmemory",
-  "version": "0.7.7",
-  "health": {
-    "memory": { "heapUsed": 42000000, "heapTotal": 67000000 },
-    "cpu": { "percent": 2.1 },
-    "eventLoopLagMs": 1.2,
-    "status": "healthy"
-  },
-  "circuitBreaker": { "state": "closed", "failures": 0 }
-}
-```
-
-### Manual Hook Setup (alternative)
-
-If you prefer not to use the plugin, add hooks directly to `~/.claude/settings.json`:
-
-```json
-{
-  "hooks": {
-    "SessionStart": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/session-start.mjs" }],
-    "UserPromptSubmit": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/prompt-submit.mjs" }],
-    "PreToolUse": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/pre-tool-use.mjs" }],
-    "PostToolUse": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/post-tool-use.mjs" }],
-    "PostToolUseFailure": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/post-tool-failure.mjs" }],
-    "PreCompact": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/pre-compact.mjs" }],
-    "SubagentStart": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/subagent-start.mjs" }],
-    "SubagentStop": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/subagent-stop.mjs" }],
-    "Notification": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/notification.mjs" }],
-    "TaskCompleted": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/task-completed.mjs" }],
-    "Stop": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/stop.mjs" }],
-    "SessionEnd": [{ "type": "command", "command": "node ~/agentmemory/dist/hooks/session-end.mjs" }]
-  }
-}
-```
-
 ## First Steps After Install
 
-Once hooks are installed, memory builds silently. No action needed — just use your agent normally.
+Once hooks are installed, memory builds silently. No action needed. Just use your agent normally.
 
 ### Session 1: Your agent works as usual
 
@@ -470,7 +431,7 @@ agentmemory automatically cleans itself:
 | 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 |
+| **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) |
 

package/dist/cli.mjs

@@ -159,12 +159,12 @@ async function main() {
 	p.intro("agentmemory");
 	if (skipEngine) {
 		p.log.info("Skipping engine check (--no-engine)");
-		await import("./src-qOdKVNQz.mjs");
+		await import("./src-Df36IFVL.mjs");
 		return;
 	}
 	if (await isEngineRunning()) {
 		p.log.success("iii-engine is running");
-		await import("./src-qOdKVNQz.mjs");
+		await import("./src-Df36IFVL.mjs");
 		return;
 	}
 	if (!await startEngine()) {
@@ -192,7 +192,7 @@ async function main() {
 		process.exit(1);
 	}
 	s.stop("iii-engine is ready");
-	await import("./src-qOdKVNQz.mjs");
+	await import("./src-Df36IFVL.mjs");
 }
 async function runStatus() {
 	const port = getRestPort();

package/dist/index.mjs

@@ -3910,7 +3910,7 @@ function registerAutoForgetFunction(sdk, kv) {
 
 //#endregion
 //#region src/version.ts
-const VERSION = "0.8.0";
+const VERSION = "0.8.1";
 
 //#endregion
 //#region src/functions/export-import.ts
@@ -4016,7 +4016,8 @@ function registerExportImportFunction(sdk, kv) {
 			"0.7.6",
 			"0.7.7",
 			"0.7.9",
-			"0.8.0"
+			"0.8.0",
+			"0.8.1"
 		]).has(importData.version)) return {
 			success: false,
 			error: `Unsupported export version: ${importData.version}`
@@ -14465,9 +14466,11 @@ function startViewerServer(port, _kv, _sdk, secret, restPort) {
 		if (method === "GET" && (pathname === "/" || pathname === "/viewer" || pathname === "/agentmemory/viewer")) {
 			const base = dirname(fileURLToPath(import.meta.url));
 			const candidates = [
-				join(base, "..", "src", "viewer", "index.html"),
+				join(base, "index.html"),
+				join(base, "viewer", "index.html"),
 				join(base, "..", "viewer", "index.html"),
-				join(base, "viewer", "index.html")
+				join(base, "..", "src", "viewer", "index.html"),
+				join(base, "..", "dist", "viewer", "index.html")
 			];
 			for (const p of candidates) try {
 				const html = readFileSync(p, "utf-8");