#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
feat: DX improvements — dark mode, status command, memory previews, token savings
Rohit Ghumare75a2d35ed612
diff --git a/README.md b/README.mdindex f9dafac3..f90e8bdc 100644--- a/README.md+++ b/README.md@@ -241,6 +241,12 @@ Add to `.opencode/config.json`:}```+**Any agent via SkillKit (32+ agents supported):**++```bash+npx skillkit install agentmemory+```+**REST API (any agent, any language):**```bash@@ -298,6 +304,54 @@ If you prefer not to use the plugin, add hooks directly to `~/.claude/settings.j}```+## First Steps After Install++Once hooks are installed, memory builds silently. No action needed — just use your agent normally.++### Session 1: Your agent works as usual++```+You: "Add JWT auth to the Express API"+Agent: reads files, writes code, runs tests, fixes errors+```++agentmemory captures every tool use via PostToolUse hooks. At session end, 47 raw observations compress into structured memory:++```json+{+ "type": "file_edit",+ "title": "Implement JWT middleware with jose",+ "facts": ["Using jose library for Edge compatibility", "JWT tokens expire after 30 days", "Middleware in src/middleware/auth.ts"],+ "concepts": ["jwt", "authentication", "jose", "middleware"],+ "files": ["src/middleware/auth.ts", "src/app/api/auth/route.ts"],+ "importance": 9+}+```++### Session 2: The payoff++You start a new session. Before the agent responds, the SessionStart hook fires and injects context (~1,900 tokens):++```+Agent already knows:+ - Auth uses jose JWT middleware in src/middleware/auth.ts+ - Tests in test/auth.test.ts cover token validation+ - You chose jose over jsonwebtoken for Edge compatibility+ - Rate limiting discussion from last week's debugging session+```++No re-explaining. The agent starts working immediately.++### How to verify it's working++```bash+npx @agentmemory/agentmemory status # quick terminal check+curl http://localhost:3111/agentmemory/health+open http://localhost:3113 # real-time viewer+```++After 1 session: check the Timeline tab in the viewer. After 2+ sessions: check Dashboard for memory count > 0 and the Token Savings card.+## How It Works### Observation Pipelinediff --git a/src/cli.ts b/src/cli.tsindex 20cb070c..2fc68ae7 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -13,7 +13,11 @@ if (args.includes("--help") || args.includes("-h")) {console.log(`agentmemory — persistent memory for AI coding agents-Usage: agentmemory [options]+Usage: agentmemory [command] [options]++Commands:+ (default) Start agentmemory worker+ status Show connection status, memory count, and healthOptions:--help, -h Show this help@@ -21,15 +25,10 @@ Options:--no-engine Skip auto-starting iii-engine--port <N> Override REST port (default: 3111)-Environment:- AGENTMEMORY_TOOLS=all Expose all 41 MCP tools- AGENTMEMORY_SECRET=xxx Auth secret for REST/MCP- CONSOLIDATION_ENABLED=true Enable auto-consolidation (off by default)- OBSIDIAN_AUTO_EXPORT=true Auto-export on consolidation-Quick start:- npx @agentmemory/agentmemory # installs iii if missing, starts everything- npx agentmemory-mcp # standalone MCP server (no engine needed)+ npx @agentmemory/agentmemory # start everything+ npx @agentmemory/agentmemory status # check health+ npx agentmemory-mcp # standalone MCP (no engine)`);process.exit(0);}@@ -245,7 +244,62 @@ async function main() {await import("./index.js");}-main().catch((err) => {- p.log.error(err instanceof Error ? err.message : String(err));- process.exit(1);-});+async function runStatus() {+ const port = getRestPort();+ const base = `http://localhost:${port}`;+ p.intro("agentmemory status");++ const up = await isEngineRunning();+ if (!up) {+ p.log.error(`Not running — no response on port ${port}`);+ p.log.info("Start with: npx @agentmemory/agentmemory");+ process.exit(1);+ }++ try {+ const [healthRes, sessionsRes, graphRes] = await Promise.all([+ fetch(`${base}/agentmemory/health`, { signal: AbortSignal.timeout(5000) }).then((r) => r.json()).catch(() => null),+ fetch(`${base}/agentmemory/sessions`, { signal: AbortSignal.timeout(5000) }).then((r) => r.json()).catch(() => null),+ fetch(`${base}/agentmemory/graph/stats`, { signal: AbortSignal.timeout(5000) }).then((r) => r.json()).catch(() => null),+ ]);++ const h = healthRes?.health;+ const status = healthRes?.status || "unknown";+ const version = healthRes?.version || "?";+ const sessions = Array.isArray(sessionsRes) ? sessionsRes.length : 0;+ const memories = h?.workers?.[0]?.function_count || 0;+ const nodes = graphRes?.nodes || 0;+ const edges = graphRes?.edges || 0;+ const cb = healthRes?.circuitBreaker?.state || "closed";+ const heapMB = h?.memory ? Math.round(h.memory.heapUsed / 1048576) : 0;+ const uptime = h?.uptimeSeconds ? Math.round(h.uptimeSeconds) : 0;++ p.log.success(`Connected — v${version} on port ${port}`);++ const lines = [+ `Health: ${status === "healthy" ? "healthy" : status}`,+ `Sessions: ${sessions}`,+ `Graph: ${nodes} nodes, ${edges} edges`,+ `Circuit: ${cb}`,+ `Heap: ${heapMB} MB`,+ `Uptime: ${uptime}s`,+ `Viewer: http://localhost:${port + 2}`,+ ];+ p.note(lines.join("\n"), "agentmemory");+ } catch (err) {+ p.log.error(err instanceof Error ? err.message : String(err));+ process.exit(1);+ }+}++if (args[0] === "status") {+ runStatus().catch((err) => {+ p.log.error(err instanceof Error ? err.message : String(err));+ process.exit(1);+ });+} else {+ main().catch((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 8dd51935..4e6d5bd5 100644--- a/src/viewer/index.html+++ b/src/viewer/index.html@@ -40,6 +40,35 @@--font-ui: 'Inter', -apple-system, sans-serif;--font-mono: 'JetBrains Mono', 'SF Mono', 'Fira Code', monospace;}+ html[data-theme="dark"] {+ --bg: #1a1a1e;+ --bg-alt: #232328;+ --bg-inset: #2a2a30;+ --border: #444;+ --border-light: #3a3a42;+ --border-heavy: #ccc;+ --ink: #eee;+ --ink-secondary: #ccc;+ --ink-muted: #999;+ --ink-faint: #777;+ --cream: #2a2520;+ }+ html[data-theme="dark"] body {+ background-image: radial-gradient(circle, #3a3a42 0.5px, transparent 0.5px);+ }+ html[data-theme="dark"] .graph-tooltip {+ background: rgba(30,30,35,0.92);+ border-color: rgba(255,255,255,0.1);+ box-shadow: 0 8px 32px rgba(0,0,0,0.4);+ }+ html[data-theme="dark"] .graph-controls button {+ background: rgba(30,30,35,0.92);+ border-color: rgba(255,255,255,0.1);+ }+ html[data-theme="dark"] .graph-controls button:hover {+ background: var(--ink);+ color: var(--bg);+ }* { margin: 0; padding: 0; box-sizing: border-box; }body {font-family: var(--font-body);@@ -422,6 +451,7 @@}.obs-card .obs-facts li { margin-bottom: 2px; }.tag-list { display: flex; gap: 4px; flex-wrap: wrap; margin-top: 6px; }+ mark { background: rgba(204, 0, 0, 0.12); color: var(--ink); padding: 0 2px; border-radius: 2px; }.tag {font-size: 10px;padding: 1px 6px;@@ -735,6 +765,7 @@</div><div class="header-right"><span class="dateline" id="dateline"></span>+ <button id="theme-toggle" class="btn" style="font-size:9px;padding:3px 10px;letter-spacing:0.1em;margin-right:8px;" onclick="toggleTheme()">DARK</button><span id="ws-status" class="ws-status disconnected">live updates off</span></div></div>@@ -782,6 +813,19 @@var dateEl = document.getElementById('dateline');if (dateEl) dateEl.textContent = new Date().toLocaleDateString('en-US', { weekday: 'short', year: 'numeric', month: 'short', day: 'numeric' });+ function isDarkMode() { return document.documentElement.dataset.theme === 'dark'; }+ function applyTheme(dark) {+ document.documentElement.dataset.theme = dark ? 'dark' : 'light';+ var btn = document.getElementById('theme-toggle');+ if (btn) btn.textContent = dark ? 'LIGHT' : 'DARK';+ localStorage.setItem('agentmemory-theme', dark ? 'dark' : 'light');+ }+ window.toggleTheme = function() { applyTheme(!isDarkMode()); };+ var savedTheme = localStorage.getItem('agentmemory-theme');+ if (savedTheme === 'dark' || (!savedTheme && window.matchMedia('(prefers-color-scheme: dark)').matches)) {+ applyTheme(true);+ }+var NODE_COLORS = {file: '#2D6A4F', function: '#1D4E89', concept: '#B8860B', error: '#CC0000',decision: '#6B3FA0', pattern: '#2563EB', library: '#C2410C', person: '#111111'@@ -974,6 +1018,12 @@html += '<div class="stat-card"><div class="label">Circuit Breaker</div><div class="value"><span class="cb-indicator ' + cbClass + '">' + esc(cb.state) + '</span></div>';html += '<div class="sub">' + (cb.failures || 0) + ' failures</div></div>';}+ var totalObs = d.sessions.reduce(function(a, s) { return a + (s.observationCount || 0); }, 0);+ var estFull = totalObs * 80;+ var estInjected = d.sessions.length * 2000;+ var savings = estFull > 0 ? Math.round((1 - estInjected / Math.max(estFull, 1)) * 100) : 0;+ if (savings < 0) savings = 0;+ html += '<div class="stat-card"><div class="label">Token Savings</div><div class="value">' + savings + '%</div><div class="sub">~' + estInjected.toLocaleString() + ' vs ~' + estFull.toLocaleString() + ' full</div></div>';html += '</div>';if (snap.memory || snap.cpu) {@@ -1604,7 +1654,7 @@// --- Canvas grid background ---var gridSize = 24;ctx.save();- ctx.strokeStyle = 'rgba(0,0,0,0.04)';+ ctx.strokeStyle = isDarkMode() ? 'rgba(255,255,255,0.04)' : 'rgba(0,0,0,0.04)';ctx.lineWidth = 0.5;for (var gx = 0; gx < w; gx += gridSize) {ctx.beginPath(); ctx.moveTo(gx, 0); ctx.lineTo(gx, h); ctx.stroke();@@ -1705,7 +1755,7 @@if (showEdgeLabel) {var zoomInv = 1 / graphSim.zoom;ctx.save();- ctx.fillStyle = isConnectedToFocus ? 'rgba(17,17,17,0.85)' : 'rgba(80,80,80,0.7)';+ ctx.fillStyle = isDarkMode() ? (isConnectedToFocus ? 'rgba(238,238,238,0.9)' : 'rgba(180,180,180,0.7)') : (isConnectedToFocus ? 'rgba(17,17,17,0.85)' : 'rgba(80,80,80,0.7)');ctx.font = (isConnectedToFocus ? '600 ' : '500 ') + (11 * zoomInv).toFixed(1) + 'px Inter, sans-serif';ctx.textAlign = 'center';ctx.fillText(e.type, cpx, cpy - (4 * zoomInv));@@ -1788,16 +1838,16 @@var labelH = 20 * zoomInv;var labelY = n.y + n.r + (8 * zoomInv); // Top of the background pill- ctx.fillStyle = 'rgba(255,255,255,0.92)';+ ctx.fillStyle = isDarkMode() ? 'rgba(30,30,35,0.92)' : 'rgba(255,255,255,0.92)';ctx.beginPath();ctx.roundRect ? ctx.roundRect(n.x - labelW / 2, labelY, labelW, labelH, 4 * zoomInv) : ctx.rect(n.x - labelW / 2, labelY, labelW, labelH);ctx.fill();- ctx.strokeStyle = 'rgba(0,0,0,0.08)';+ ctx.strokeStyle = isDarkMode() ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.08)';ctx.lineWidth = 1 * zoomInv;ctx.stroke();-- ctx.fillStyle = isSelected || isHovered ? '#111111' : '#444444';++ ctx.fillStyle = isDarkMode() ? (isSelected || isHovered ? '#eeeeee' : '#bbbbbb') : (isSelected || isHovered ? '#111111' : '#444444');// Vertically center text in the pill boxctx.fillText(label, n.x, labelY + (14 * zoomInv));ctx.restore();@@ -1858,8 +1908,20 @@var strength = Math.round((m.strength || 0) * 100);var barColor = strength > 70 ? 'var(--green)' : strength > 40 ? 'var(--yellow)' : 'var(--red)';html += '<tr>';+ var preview = (m.content || '').split('\n').slice(0, 2).join(' ').trim();+ var previewHtml = esc(truncate(preview, 150));+ if (search && search.length > 2) {+ var re = new RegExp('(' + search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ')', 'gi');+ previewHtml = previewHtml.replace(re, '<mark>$1</mark>');+ }html += '<td><span style="color:var(--ink);font-weight:600;">' + esc(truncate(m.title, 50)) + '</span>';- html += '<br><span style="font-size:11px;color:var(--ink-faint);font-style:italic;">' + esc(truncate(m.content, 80)) + '</span></td>';+ html += '<div style="font-size:12px;color:var(--ink-muted);margin-top:3px;line-height:1.4;max-height:34px;overflow:hidden;">' + previewHtml + '</div>';+ if (m.concepts && m.concepts.length > 0) {+ html += '<div style="margin-top:3px;display:flex;gap:4px;flex-wrap:wrap;">';+ m.concepts.slice(0, 4).forEach(function(c) { html += '<span class="tag">' + esc(c) + '</span>'; });+ html += '</div>';+ }+ html += '</td>';html += '<td><span class="badge ' + badgeClass + '">' + esc(m.type) + '</span></td>';html += '<td><div class="strength-bar"><div class="fill" style="width:' + strength + '%;background:' + barColor + '"></div></div> <span style="font-size:10px;color:var(--ink-faint);font-family:var(--font-mono);">' + strength + '%</span></td>';html += '<td style="color:var(--ink-muted);font-family:var(--font-mono);font-size:12px;">v' + (m.version || 1) + '</td>';