#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
feat: auto-install iii-engine, clack CLI, viewer lessons tab, README update
Rohit Ghumaree26320e3aaa9
diff --git a/AGENTS.md b/AGENTS.mdindex 7b24ab91..223eea5e 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -110,4 +110,4 @@ Hook scripts in `src/hooks/` are standalone Node.js scripts (no iii-sdk import).- 6 MCP resources, 3 MCP prompts- 12 hooks, 4 skills- 50+ iii functions-- 573 tests+- 581 testsdiff --git a/README.md b/README.mdindex 2155aecd..4d77d75c 100644--- a/README.md+++ b/README.md@@ -31,8 +31,7 @@ Every AI coding agent has the same blind spot. Session ends, memory vanishes. YoThe result is measurable. On 240 real observations across 30 sessions, agentmemory hits 64% Recall@10 and perfect MRR while using 92% fewer tokens than dumping everything into context. When an agent searches "database performance optimization," it finds the N+1 fix you made three weeks ago — something keyword grep literally cannot do. Memories version automatically, supersede each other, propagate staleness to related graph nodes, and sync across agent instances via P2P mesh. Your agents stop repeating mistakes. Your context stays clean. Your sessions start fast.```bash-npm install -g @agentmemory/agentmemory-agentmemory # auto-starts iii-engine, runs worker+npx @agentmemory/agentmemory # installs iii-engine if missing, starts everything```---@@ -176,21 +175,22 @@ GET /agentmemory/profile # Get project intelligenceAll 12 hooks, 4 skills, and MCP server are registered automatically.-### 2. Start the Worker+### 2. Start agentmemory```bash-npm install -g @agentmemory/agentmemory-agentmemory # auto-detects and starts iii-engine+npx @agentmemory/agentmemory```+This auto-installs iii-engine if missing, starts it, and runs the worker. One command.+Or from source:```bashgit clone https://github.com/rohitg00/agentmemory.git && cd agentmemory-docker compose up -d && npm install && npm run build && npm start+npm install && npm run build && npm start```-### 3. Verify+### 4. Verify```bashcurl http://localhost:3111/agentmemory/health@@ -842,7 +842,7 @@ npm run test:integration # API tests (requires running services)### Prerequisites- Node.js >= 20-- Docker+- [iii-engine](https://iii.dev/docs) (`curl -fsSL https://install.iii.dev/iii/main/install.sh | sh`)## Licensediff --git a/package-lock.json b/package-lock.jsonindex a03c4e64..fdd03b6b 100644--- a/package-lock.json+++ b/package-lock.json@@ -1,23 +1,23 @@{- "name": "agentmemory",- "version": "0.5.0",+ "name": "@agentmemory/agentmemory",+ "version": "0.7.0","lockfileVersion": 3,"requires": true,"packages": {"": {- "name": "agentmemory",- "version": "0.5.0",+ "name": "@agentmemory/agentmemory",+ "version": "0.7.0","license": "Apache-2.0","dependencies": {"@anthropic-ai/claude-agent-sdk": "^0.2.56","@anthropic-ai/sdk": "^0.39.0",- "@xenova/transformers": "^2.17.2",+ "@clack/prompts": "^1.2.0","dotenv": "^16.4.7","iii-sdk": "^0.3.0","zod": "^3.23.0"},"bin": {- "agentmemory": "dist/index.mjs",+ "agentmemory": "dist/cli.mjs","agentmemory-mcp": "dist/standalone.mjs"},"devDependencies": {@@ -28,7 +28,7 @@"vitest": "^3.0.0"},"engines": {- "node": ">=18.0.0"+ "node": ">=20.0.0"},"optionalDependencies": {"@xenova/transformers": "^2.17.2"@@ -155,6 +155,28 @@"node": "^20.19.0 || >=22.12.0"}},+ "node_modules/@clack/core": {+ "version": "1.2.0",+ "resolved": "https://registry.npmjs.org/@clack/core/-/core-1.2.0.tgz",+ "integrity": "sha512-qfxof/3T3t9DPU/Rj3OmcFyZInceqj/NVtO9rwIuJqCUgh32gwPjpFQQp/ben07qKlhpwq7GzfWpST4qdJ5Drg==",+ "license": "MIT",+ "dependencies": {+ "fast-wrap-ansi": "^0.1.3",+ "sisteransi": "^1.0.5"+ }+ },+ "node_modules/@clack/prompts": {+ "version": "1.2.0",+ "resolved": "https://registry.npmjs.org/@clack/prompts/-/prompts-1.2.0.tgz",+ "integrity": "sha512-4jmztR9fMqPMjz6H/UZXj0zEmE43ha1euENwkckKKel4XpSfokExPo5AiVStdHSAlHekz4d0CA/r45Ok1E4D3w==",+ "license": "MIT",+ "dependencies": {+ "@clack/core": "1.2.0",+ "fast-string-width": "^1.1.0",+ "fast-wrap-ansi": "^0.1.3",+ "sisteransi": "^1.0.5"+ }+ },"node_modules/@emnapi/core": {"version": "1.8.1","resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.8.1.tgz",@@ -2793,6 +2815,30 @@"license": "MIT","optional": true},+ "node_modules/fast-string-truncated-width": {+ "version": "1.2.1",+ "resolved": "https://registry.npmjs.org/fast-string-truncated-width/-/fast-string-truncated-width-1.2.1.tgz",+ "integrity": "sha512-Q9acT/+Uu3GwGj+5w/zsGuQjh9O1TyywhIwAxHudtWrgF09nHOPrvTLhQevPbttcxjr/SNN7mJmfOw/B1bXgow==",+ "license": "MIT"+ },+ "node_modules/fast-string-width": {+ "version": "1.1.0",+ "resolved": "https://registry.npmjs.org/fast-string-width/-/fast-string-width-1.1.0.tgz",+ "integrity": "sha512-O3fwIVIH5gKB38QNbdg+3760ZmGz0SZMgvwJbA1b2TGXceKE6A2cOlfogh1iw8lr049zPyd7YADHy+B7U4W9bQ==",+ "license": "MIT",+ "dependencies": {+ "fast-string-truncated-width": "^1.2.0"+ }+ },+ "node_modules/fast-wrap-ansi": {+ "version": "0.1.6",+ "resolved": "https://registry.npmjs.org/fast-wrap-ansi/-/fast-wrap-ansi-0.1.6.tgz",+ "integrity": "sha512-HlUwET7a5gqjURj70D5jl7aC3Zmy4weA1SHUfM0JFI0Ptq987NH2TwbBFLoERhfwk+E+eaq4EK3jXoT+R3yp3w==",+ "license": "MIT",+ "dependencies": {+ "fast-string-width": "^1.1.0"+ }+ },"node_modules/fdir": {"version": "6.5.0","resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",@@ -3117,18 +3163,6 @@"url": "https://github.com/sponsors/ljharb"}},- "node_modules/jiti": {- "version": "2.6.1",- "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.6.1.tgz",- "integrity": "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==",- "dev": true,- "license": "MIT",- "optional": true,- "peer": true,- "bin": {- "jiti": "lib/jiti-cli.mjs"- }- },"node_modules/jsesc": {"version": "3.1.0","resolved": "https://registry.npmjs.org/jsesc/-/jsesc-3.1.0.tgz",@@ -3945,6 +3979,12 @@"is-arrayish": "^0.3.1"}},+ "node_modules/sisteransi": {+ "version": "1.0.5",+ "resolved": "https://registry.npmjs.org/sisteransi/-/sisteransi-1.0.5.tgz",+ "integrity": "sha512-bLGGlR1QxBcynn2d5YmDX4MGjlZvy2MRBDRNHLJ8VI6l6+9FUiyTFNJ0IveOSP0bcXgVDPRcfGqA0pjaqUpfVg==",+ "license": "MIT"+ },"node_modules/source-map-js": {"version": "1.2.1","resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",diff --git a/package.json b/package.jsonindex 8fac6d6b..6b9825c3 100644--- a/package.json+++ b/package.json@@ -39,6 +39,7 @@"dependencies": {"@anthropic-ai/claude-agent-sdk": "^0.2.56","@anthropic-ai/sdk": "^0.39.0",+ "@clack/prompts": "^1.2.0","dotenv": "^16.4.7","iii-sdk": "^0.3.0","zod": "^3.23.0"diff --git a/src/cli.ts b/src/cli.tsindex d68d84fa..bb72c959 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -1,12 +1,12 @@#!/usr/bin/env node-import { spawn, execFileSync } from "node:child_process";+import { spawn, execFileSync, execSync } from "node:child_process";import { existsSync } from "node:fs";import { join, dirname } from "node:path";import { fileURLToPath } from "node:url";+import * as p from "@clack/prompts";const __dirname = dirname(fileURLToPath(import.meta.url));-const args = process.argv.slice(2);if (args.includes("--help") || args.includes("-h")) {@@ -22,14 +22,14 @@ Options:--port <N> Override REST port (default: 3111)Environment:- AGENTMEMORY_TOOLS=all Expose all 41 MCP tools- AGENTMEMORY_SECRET=xxx Auth secret for REST/MCP+ AGENTMEMORY_TOOLS=all Expose all 41 MCP tools+ AGENTMEMORY_SECRET=xxx Auth secret for REST/MCPCONSOLIDATION_ENABLED=true Enable auto-consolidation (off by default)OBSIDIAN_AUTO_EXPORT=true Auto-export on consolidationQuick start:- npx agentmemory # auto-starts iii-engine, runs worker- npx agentmemory-mcp # standalone MCP server (no engine needed)+ npx @agentmemory/agentmemory # installs iii if missing, starts everything+ npx agentmemory-mcp # standalone MCP server (no engine needed)`);process.exit(0);}@@ -82,32 +82,103 @@ function whichBinary(name: string): string | null {}}+async function installIii(): Promise<boolean> {+ if (process.platform === "win32") {+ p.log.warn("Automatic iii-engine install is not supported on Windows.");+ p.log.info("Install manually: https://iii.dev/docs");+ return false;+ }++ const curlBin = whichBinary("curl");+ if (!curlBin) {+ p.log.warn("curl not found — cannot auto-install iii-engine.");+ return false;+ }++ const shouldInstall = await p.confirm({+ message: "iii-engine is not installed. Install it now?",+ initialValue: true,+ });++ if (p.isCancel(shouldInstall) || !shouldInstall) {+ return false;+ }++ const s = p.spinner();+ s.start("Installing iii-engine...");++ try {+ execSync("curl -fsSL https://install.iii.dev/iii/main/install.sh | sh", {+ stdio: ["pipe", "pipe", "pipe"],+ timeout: 120000,+ });++ const installed = whichBinary("iii");+ if (installed) {+ s.stop("iii-engine installed successfully");+ return true;+ }++ s.stop("Installation completed but iii not found in PATH");+ p.log.warn("You may need to restart your shell or add iii to your PATH.");++ const iiiPaths = [+ join(process.env["HOME"] || "", ".local", "bin", "iii"),+ "/usr/local/bin/iii",+ ];+ for (const iiiPath of iiiPaths) {+ if (existsSync(iiiPath)) {+ p.log.info(`Found iii at: ${iiiPath}`);+ process.env["PATH"] = `${dirname(iiiPath)}:${process.env["PATH"]}`;+ return true;+ }+ }++ return false;+ } catch (err) {+ s.stop("Failed to install iii-engine");+ p.log.error(err instanceof Error ? err.message : String(err));+ return false;+ }+}+async function startEngine(): Promise<boolean> {const configPath = findIiiConfig();+ let iiiBin = whichBinary("iii");++ if (!iiiBin) {+ const installed = await installIii();+ if (installed) {+ iiiBin = whichBinary("iii");+ }+ }- const iiiBin = whichBinary("iii");if (iiiBin && configPath) {- console.log(`[agentmemory] Starting iii-engine: ${iiiBin} --config ${configPath}`);+ const s = p.spinner();+ s.start(`Starting iii-engine: ${iiiBin}`);const child = spawn(iiiBin, ["--config", configPath], {detached: true,stdio: "ignore",});child.unref();+ s.stop("iii-engine process started");return true;}+ const dockerBin = whichBinary("docker");const dockerCompose = join(__dirname, "..", "docker-compose.yml");const dcExists = existsSync(dockerCompose) || existsSync(join(process.cwd(), "docker-compose.yml"));- const dockerBin = whichBinary("docker");if (dockerBin && dcExists) {const composeFile = existsSync(dockerCompose) ? dockerCompose : join(process.cwd(), "docker-compose.yml");- console.log(`[agentmemory] Starting iii-engine via Docker...`);+ const s = p.spinner();+ s.start("Starting iii-engine via Docker...");const child = spawn(dockerBin, ["compose", "-f", composeFile, "up", "-d"], {detached: true,stdio: "ignore",});child.unref();+ s.stop("Docker compose started");return true;}@@ -124,36 +195,57 @@ async function waitForEngine(timeoutMs: number): Promise<boolean> {}async function main() {- if (!skipEngine && !(await isEngineRunning())) {- const started = await startEngine();- if (!started) {- console.error(`-[agentmemory] iii-engine is not running and could not be auto-started.+ p.intro("agentmemory");-Install one of:- 1. iii CLI: npm install -g iii-engine- 2. Docker: docker compose up -d (with docker-compose.yml)+ if (skipEngine) {+ p.log.info("Skipping engine check (--no-engine)");+ await import("./index.js");+ return;+ }-Or run with --no-engine to connect to a remote engine.-`);- process.exit(1);- }+ if (await isEngineRunning()) {+ p.log.success("iii-engine is running");+ await import("./index.js");+ return;+ }- console.log(`[agentmemory] Waiting for iii-engine to start...`);- const ready = await waitForEngine(15000);- if (!ready) {- const port = getRestPort();- console.error(`[agentmemory] iii-engine did not become ready within 15s.`);- console.error(`[agentmemory] Check that ports ${port}, ${port + 1}, 49134 are available.`);- process.exit(1);- }- console.log(`[agentmemory] iii-engine is ready.`);+ const started = await startEngine();+ if (!started) {+ p.log.error("Could not start iii-engine.");+ p.note(+ [+ "Install iii-engine (pick one):",+ " curl -fsSL https://install.iii.dev/iii/main/install.sh | sh",+ " cargo install iii-engine",+ "",+ "Or use Docker:",+ " docker pull iiidev/iii:latest",+ "",+ "Docs: https://iii.dev/docs",+ "",+ "Or skip with: agentmemory --no-engine",+ ].join("\n"),+ "Setup required",+ );+ process.exit(1);+ }++ const s = p.spinner();+ s.start("Waiting for iii-engine to be ready...");++ const ready = await waitForEngine(15000);+ if (!ready) {+ const port = getRestPort();+ s.stop("iii-engine did not become ready within 15s");+ p.log.error(`Check that ports ${port}, ${port + 1}, 49134 are available.`);+ process.exit(1);}+ s.stop("iii-engine is ready");await import("./index.js");}main().catch((err) => {- console.error(`[agentmemory] Fatal:`, err);+ p.log.error(err instanceof Error ? err.message : String(err));process.exit(1);});diff --git a/src/viewer/index.html b/src/viewer/index.htmlindex 4366bf01..baccd783 100644--- a/src/viewer/index.html+++ b/src/viewer/index.html@@ -727,7 +727,7 @@<div class="app-header"><div class="brand"><h1>agentmemory</h1>- <span class="version">v0.5.0</span>+ <span class="version">v0.7.0</span></div><div class="header-right"><span class="dateline" id="dateline"></span>@@ -741,6 +741,7 @@<button data-tab="memories">Memories</button><button data-tab="timeline">Timeline</button><button data-tab="sessions">Sessions</button>+ <button data-tab="lessons">Lessons</button><button data-tab="audit">Audit</button><button data-tab="activity">Activity</button><button data-tab="profile">Profile</button>@@ -749,6 +750,7 @@<div id="view-dashboard" class="view active"></div><div id="view-graph" class="view"></div><div id="view-memories" class="view"></div>+ <div id="view-lessons" class="view"></div><div id="view-timeline" class="view"></div><div id="view-sessions" class="view"></div><div id="view-audit" class="view"></div>@@ -803,13 +805,14 @@var state = {activeTab: 'dashboard',- dashboard: { loaded: false, health: null, sessions: [], memories: [], graphStats: null, recentAudit: [] },+ dashboard: { loaded: false, health: null, sessions: [], memories: [], graphStats: null, recentAudit: [], lessons: [], crystals: [] },graph: { loaded: false, nodes: [], edges: [], stats: null, filters: {}, selectedNode: null },memories: { loaded: false, items: [], search: '', typeFilter: '' },timeline: { loaded: false, observations: [], sessionId: '', minImportance: 0, page: 0, pageSize: 50 },sessions: { loaded: false, items: [], selectedId: null },audit: { loaded: false, entries: [], opFilter: '' },activity: { loaded: false, observations: [], sessions: [], typeFilter: '' },+ lessons: { loaded: false, items: [], search: '' },profile: { loaded: false, projects: [], selectedProject: '', data: null },ws: null};@@ -891,6 +894,7 @@case 'memories': if (!state.memories.loaded) await loadMemories(); break;case 'timeline': if (!state.timeline.loaded) await loadTimeline(); break;case 'sessions': if (!state.sessions.loaded) await loadSessions(); break;+ case 'lessons': if (!state.lessons.loaded) await loadLessons(); break;case 'audit': if (!state.audit.loaded) await loadAudit(); break;case 'activity': if (!state.activity.loaded) await loadActivity(); break;case 'profile': if (!state.profile.loaded) await loadProfile(); break;@@ -908,7 +912,9 @@apiGet('audit?limit=5'),apiGet('semantic'),apiGet('procedural'),- apiGet('relations')+ apiGet('relations'),+ apiGet('lessons'),+ apiGet('crystals')]);state.dashboard.health = results[0];state.dashboard.sessions = (results[1] && results[1].sessions) || [];@@ -917,6 +923,8 @@state.dashboard.recentAudit = (results[4] && results[4].entries) || [];state.dashboard.semantic = (results[5] && results[5].facts) || (results[5] && results[5].semantic) || [];state.dashboard.procedural = (results[6] && results[6].procedures) || (results[6] && results[6].procedural) || [];+ state.dashboard.lessons = (results[8] && results[8].lessons) || [];+ state.dashboard.crystals = (results[9] && results[9].crystals) || [];state.dashboard.relations = (results[7] && results[7].relations) || [];state.dashboard.loaded = true;renderDashboard();@@ -940,6 +948,10 @@var html = '<div class="stats-grid">';html += '<div class="stat-card"><div class="label">Sessions</div><div class="value">' + d.sessions.length + '</div><div class="sub">' + activeSessions + ' active</div></div>';html += '<div class="stat-card"><div class="label">Memories</div><div class="value">' + d.memories.length + '</div><div class="sub">latest versions</div></div>';+ var lessonCount = (d.lessons || []).length;+ var crystalCount = (d.crystals || []).length;+ html += '<div class="stat-card"><div class="label">Lessons</div><div class="value">' + lessonCount + '</div><div class="sub">confidence-scored</div></div>';+ html += '<div class="stat-card"><div class="label">Crystals</div><div class="value">' + crystalCount + '</div><div class="sub">action digests</div></div>';html += '<div class="stat-card"><div class="label">Graph Nodes</div><div class="value">' + nodeCount + '</div><div class="sub">' + edgeCount + ' edges</div></div>';html += '<div class="stat-card"><div class="label">Health</div><div class="value"><div class="health-bar"><span class="health-dot ' + dotClass + '"></span> ' + esc(healthStatus) + '</div></div>';html += '<div class="sub">' + esc(snap.connectionState || 'unknown') + '</div></div>';@@ -2210,6 +2222,53 @@setTimeout(function() { btn.textContent = 'Summarize'; btn.disabled = false; }, 2000);}+ async function loadLessons() {+ var el = document.getElementById('view-lessons');+ el.innerHTML = '<div class="loading">Loading lessons...</div>';+ var result = await apiGet('lessons');+ state.lessons.items = (result && result.lessons) || [];+ state.lessons.loaded = true;+ renderLessons();+ }++ function renderLessons() {+ var el = document.getElementById('view-lessons');+ var items = state.lessons.items;+ var search = state.lessons.search.toLowerCase();++ if (search) {+ items = items.filter(function(l) {+ return (l.content + ' ' + l.context + ' ' + (l.tags || []).join(' ')).toLowerCase().indexOf(search) >= 0;+ });+ }++ var html = '<div style="display:flex;gap:8px;margin-bottom:12px;">';+ html += '<input class="search-input" type="text" placeholder="Search lessons..." value="' + esc(state.lessons.search) + '" oninput="state.lessons.search=this.value;renderLessons()" style="flex:1" />';+ html += '<span style="font-size:12px;color:var(--ink-faint);align-self:center;">' + items.length + ' lessons</span>';+ html += '</div>';++ if (items.length === 0) {+ html += '<div class="empty-state"><div class="empty-icon">💡</div><p>No lessons yet</p><p style="font-size:12px;color:var(--ink-faint);font-style:italic;">Lessons are extracted from crystals or saved manually via memory_lesson_save.</p></div>';+ } else {+ html += '<table><thead><tr><th>Lesson</th><th>Confidence</th><th>Reinforcements</th><th>Source</th><th>Project</th><th>Updated</th></tr></thead><tbody>';+ items.forEach(function(l) {+ var confPct = Math.round(l.confidence * 100);+ var confColor = confPct >= 70 ? 'var(--green)' : confPct >= 40 ? 'var(--yellow)' : 'var(--red)';+ html += '<tr>';+ html += '<td style="max-width:400px;">' + esc(truncate(l.content, 120)) + (l.context ? '<div style="font-size:11px;color:var(--ink-faint);margin-top:2px;">' + esc(truncate(l.context, 80)) + '</div>' : '') + '</td>';+ html += '<td><div class="gauge" style="min-width:80px;"><div class="gauge-bar"><div class="gauge-fill" style="width:' + confPct + '%;background:' + confColor + '"></div></div><span class="gauge-value" style="font-size:11px;">' + confPct + '%</span></div></td>';+ html += '<td style="text-align:center;">' + (l.reinforcements || 0) + '</td>';+ html += '<td><span class="badge badge-' + (l.source === 'crystal' ? 'purple' : l.source === 'consolidation' ? 'yellow' : 'blue') + '">' + esc(l.source) + '</span></td>';+ html += '<td style="font-size:12px;color:var(--ink-muted);">' + esc(l.project || '-') + '</td>';+ html += '<td style="font-size:12px;color:var(--ink-muted);">' + shortTime(l.updatedAt) + '</td>';+ html += '</tr>';+ });+ html += '</tbody></table>';+ }++ el.innerHTML = html;+ }+async function loadAudit() {var el = document.getElementById('view-audit');el.innerHTML = '<div class="loading">Loading audit log...</div>';