Interactive companion
How agentmemory works
A local memory service for coding agents: 12 Claude Code hooks, 51 MCP tool definitions in the inspected clone, REST endpoints, and BM25 plus vector plus graph retrieval.
jose middleware. Session 2 you ask for rate limiting, and the agent already knows your auth stack, your test file, and why you chose jose over jsonwebtoken. No re-explaining.
Decision strip
The article is long because the repo surface is broad. These are the decisions a practitioner needs first.
npx @agentmemory/agentmemory
Article setup section and npm registry.
Solo developers and small teams using Claude Code, Cursor, Codex CLI, Gemini CLI, or other MCP clients.
Article AlphaSignal Take.
BM25, vector, and graph streams fuse through Reciprocal Rank Fusion.
Local src/state/hybrid-search.ts.
Auto-compress, context injection, slots, reflect, and graph extraction are all off by default.
Local src/config.ts and article limitations.
Repo snapshot
Snapshot anchored to v0.9.9 to match the article. Live counters are shown as safe-floor ranges so they stay accurate as the repo continues to climb.
| GitHub repo | rohitg00/agentmemory |
|---|---|
| GitHub activity | 5,000+ stars, 500+ forks, 15+ open issues (excluding pull requests). Verified 2026-05-12, climbing. |
| Latest release | v0.9.9, published 2026-05-11 at 18:39:20 UTC. Pinned slot injection and MiniMax env loader fixes. |
| npm latest | @agentmemory/agentmemory 0.9.9 and @agentmemory/mcp 0.9.9. 29 published versions on the main package. |
| Local clone inspected | v0.9.9, commit 03fb42d, dated 2026-05-11. |
| License and language | Apache-2.0, TypeScript ESM. |
| Node requirement | >=20.0.0 in the local package metadata. |
| Inspected source surface | 51 MCP tool definitions, 6 MCP resources, 3 MCP prompts, 12 Claude Code hooks, 121 REST api_path declarations plus 6 MCP API declarations. |
| Inspected test surface | 80 test files, 888 static it( or test( calls. Tests were not run; this is not a passing-test claim. |
| Default local ports | REST 3111, streams 3112, viewer 3113. |
Architecture map
Click a node to see what it does, where the article sourced it, and what caveat matters. Dashed lines mark optional or observability paths.
12 hooks
Claude Code lifecycle hooks capture session start, prompts, tool calls, failures, sub-agent events, stop events, and session end.
Setup walkthrough
A guided version of the article setup path. The checklist saves in this browser only.
Claude Code plugin path
/plugin marketplace add rohitg00/agentmemory /plugin install agentmemory
Universal MCP block
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}Gemini CLI
gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user
Codex CLI
codex mcp add agentmemory -- npx -y @agentmemory/mcp
REST health check
curl -s http://localhost:3111/agentmemory/health
MCP and REST surface
Seven tools ship visible by default. The full 51-tool surface is exposed when you set AGENTMEMORY_TOOLS=all. This mirrors the actual plugin behavior.
Filter tools
Tool names come from local src/mcp/tools-registry.ts.
Benchmark evidence
The headline number is retrieval recall on LongMemEval-S, not end-to-end answer accuracy.
LongMemEval-S, repo-reported
BM25-only fallback
BM25-only reports R@5 86.2%, R@10 94.6%, R@20 98.6%, NDCG@10 73.0%, and MRR 71.5% in the repo benchmark doc.
Source: local `benchmark/LONGMEMEVAL.md` and research handoff.
R@5
Whether at least one relevant item appears in the top 5 retrieval results.
R@10
The same recall check with a top-10 window.
NDCG@10
A ranking-quality metric that rewards relevant items appearing higher in the top 10.
MRR
Mean reciprocal rank, sensitive to how early the first relevant result appears.
Token and scale framing
The article cites repo-reported token efficiency around 1,900 selected tokens per session and a 92% reduction at the 240-observation working point. The handoff also notes scale data up to 50,000 observations from `benchmark/SCALE.md`.
No independent benchmark rerun was performed for this HTML build.
Do not over-read the chart
These are retrieval-only scores on LongMemEval-S. The repo does not claim them as end-to-end LongMemEval QA accuracy. Mem0 and Letta/MemGPT publish numbers on other evaluation sets, so the article treats cross-tool comparison as context rather than a leaderboard.
Comparison
Tool column is sortable; click the header to alphabetize. Cell values match the article's Comparison section verbatim; cross-benchmark claims are avoided per the article's framing.
| Type | Auto-capture | Search | External deps | Lock-in | |
|---|---|---|---|---|---|
| agentmemory | Memory engine + MCP server | 12 hooks | BM25 + vector + graph (RRF) | None | None (any MCP client) |
| mem0 (53K stars) | Memory layer API | Manual add() | Vector + graph | Qdrant / pgvector | None |
| Letta / MemGPT (22K stars) | Full agent runtime | Agent self-edits | Vector (archival) | Postgres + vector DB | High (Letta runtime) |
| Built-in (CLAUDE.md) | Static file | Manual editing | Loads everything | None | Per-agent format |
Current limitations
These are the caveats a developer should check before moving beyond localhost or treating the repo as stable infrastructure.
Command reference
The appendix turned into a compact command center.
Search
Use when a session needs context from prior work.
curl -s -X POST http://localhost:3111/agentmemory/smart-search \
-H "Content-Type: application/json" \
-d '{"query": "jwt auth middleware", "limit": 5}'Save memory
Use for a decision or pattern worth keeping.
curl -s -X POST http://localhost:3111/agentmemory/remember \
-H "Content-Type: application/json" \
-d '{"content": "Auth uses jose, chosen over jsonwebtoken for Edge compat", "concepts": ["jwt", "auth", "edge"], "files": ["src/middleware/auth.ts"]}'Project profile
Use to inspect concepts, files, and patterns.
curl -s "http://localhost:3111/agentmemory/profile?project=$(pwd)"
Health
Use after plugin or MCP setup.
curl -s http://localhost:3111/agentmemory/health