agentmemory README

The project's README from github.com/rohitg00/agentmemory. As one markdown file: README.md.

agentmemory: persistent memory for AI coding agents

Your coding agent remembers everything. No more re-explaining. Built on iii engine
Persistent memory for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, and any MCP client.

English | 简体中文 | 繁體中文 | 日本語 | 한국어 | Español | Türkçe | Русский | हिन्दी | Português | Français | Deutsch

rohitg00/agentmemory | Trendshift

Design doc: 1.6k stars / 230 forks on the gist

The gist extends Karpathy's LLM Wiki pattern with confidence scoring, lifecycle, knowledge graphs, and hybrid search: agentmemory is the implementation.

npm version CI License Stars

95.2% retrieval R@5 92% fewer tokens 54 MCP tools 12 auto hooks 0 external DBs 1,674+ tests passing

agentmemory demo

Install • Quick Start • Benchmarks • vs Competitors • Agents • How It Works • MCP • Viewer • Powered by iii • Config • API

Install

Requirements:

Canonical fresh-install command:

npx -y @agentmemory/agentmemory@latest

The first run is an interactive setup: pick the agents to wire (Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...), pick an LLM provider or stay keyless, and it seeds the config, starts the memory server and its pinned iii engine, and offers to install globally so the bare agentmemory command works everywhere afterward. -y accepts npx's package prompt and @latest avoids a stale cached release. A provider makes LLM features available, but LLM-written observation compression starts only when AGENTMEMORY_AUTO_COMPRESS=true is also set.

Keyless mode disables vector embeddings. memory_recall (the mem::search path) uses BM25, while memory_smart_search can also fuse structural graph matches when graph data already exists. For free on-device semantic recall, set EMBEDDING_PROVIDER=local in ~/.agentmemory/.env and restart. The first embedding request downloads Xenova/all-MiniLM-L6-v2; inference runs locally after that initial model download.

The local runtime uses four ports: 3111 for REST/MCP HTTP, 3112 for iii streams, 3113 for the viewer, and 49134 for the iii worker WebSocket. Persistent iii state lives in ~/Library/Application Support/agentmemory on macOS, $XDG_DATA_HOME/agentmemory or ~/.local/share/agentmemory on Linux, and %APPDATA%\agentmemory on Windows. Use --data-dir <path> or AGENTMEMORY_DATA_DIR to override it, and reuse the same value on every restart. For backward compatibility, an existing ./data/state_store.db or ./data/iii-config.yaml takes precedence over the platform default for instance 0; an explicit flag or environment override still wins.

Then prove recall works and give your agent its skills:

npx -y @agentmemory/agentmemory@latest demo  # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y   # 17 native skills so your agent knows when to reach for memory

The keyword searches should hit in default keyless mode through BM25. The demo's database performance optimization query is intentionally semantic and can return zero until an embedding provider is configured.

Prefer to let a coding agent do the whole thing? Hand it one instruction:

Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md

Wire more agents any time with agentmemory connect <agent> — 20 adapters listed at Works with every agent. Full command reference at Quick Start.

Windows

The fast path is WSL2. Native Windows engine setup requires the pinned v0.11.2 ZIP to be downloaded and iii.exe extracted manually; the CLI does not auto-extract it. Docker Desktop is also supported. See the Windows notes for the step-by-step.

Global install / EACCES 
npm install -g @agentmemory/agentmemory@latest

The npx command above remains the canonical fresh-install path and avoids global-prefix permission issues.

npx serves an old version

npx caches per version. Force the latest with npx -y @agentmemory/agentmemory@latest, or clear the cache once with rm -rf ~/.npm/_npx (macOS/Linux; on Windows delete %LOCALAPPDATA%\npm-cache\_npx).

Already running your own iii engine

agentmemory pins iii-engine v0.11.2 and won't attach to a different version (the worker can't speak another engine's protocol). Stop the other engine, then run npx -y @agentmemory/agentmemory@latest. It installs and runs the pinned v0.11.2 in ~/.agentmemory/bin, leaving your own iii untouched.

Works with every agent

agentmemory works with any agent that supports hooks, MCP, or REST API. All agents share the same memory server.

Claude Code
Claude Code
native plugin + 12 hooks + MCP 		Codex CLI
Codex CLI
native plugin + 6 hooks + MCP 		GitHub Copilot CLI
GitHub Copilot CLI
MCP + plugin hooks/skills 		OpenClaw
OpenClaw
native plugin + MCP 		Hermes
Hermes
native plugin + MCP 		pi
pi
native plugin + MCP 		OpenHuman
OpenHuman
native Memory trait backend 		Cursor
Cursor
native plugin + MCP 		Gemini CLI
Gemini CLI
MCP server
OpenCode
OpenCode
22 hooks + MCP + plugin 		Cline
Cline
MCP server 		Goose
Goose
MCP server 		Kilo Code
Kilo Code
MCP server 		Aider
Aider
REST API 		Claude Desktop
Claude Desktop
MCP server 		Devin
Devin
6 hooks + MCP 		Roo Code
Roo Code
MCP server
Warp
Warp
connect + MCP + skills

Works with any agent that speaks MCP or HTTP. One server, memories shared across all of them.

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, with no re-explaining and no copy-pasting.

npx -y @agentmemory/agentmemory@latest

By default, agentmemory stores iii-engine state outside the repository you start it from: ~/Library/Application Support/agentmemory on macOS, $XDG_DATA_HOME/agentmemory or ~/.local/share/agentmemory on Linux, and %APPDATA%\agentmemory on Windows. An existing legacy ./data/state_store.db or ./data/iii-config.yaml is reused for instance 0 before that platform default. To choose a location explicitly, pass --data-dir <path> or set AGENTMEMORY_DATA_DIR; either explicit setting takes precedence over legacy discovery:

npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest

Native and Docker launches use this same resolved host directory; Docker bind-mounts it at /data. --instance 1 appends instance-1 to the resolved directory and selects the separate default port quartet 3211/3212/3213/49234.

Latest release notes: CHANGELOG.md.

Benchmarks

Retrieval Accuracy

coding-agent-life-v1 (in-house corpus, sandbox-reproducible)

Adapter P@5 R@5 Top-5 hit rate p50 latency
agentmemory hybrid 0.240 1.000 15 / 15 14 ms
grep baseline 0.227 0.967 15 / 15 0 ms

100% top-5 hit rate at the P@5 math ceiling for this corpus (0.240, see scorecard). Hybrid retrieves every gold session; grep misses 1 of 2 gold on the multi-session temporal query. Lift is recall + temporal, not aggregate precision. This benchmark is small and gold-sparse; the larger LongMemEval-S below differentiates better. Full per-type breakdown + correction note: docs/benchmarks/2026-05-20-coding-agent-life-v1.md.

LongMemEval-S (ICLR 2025, 500 questions)

System R@5 R@10 MRR
agentmemory 95.2% 98.6% 88.2%
BM25-only fallback 86.2% 94.6% 71.5%

Token Savings

Approach Tokens/yr Cost/yr
Paste full context 19.5M+ Impossible (exceeds window)
LLM-summarized ~650K ~$500
agentmemory ~170K ~$10
agentmemory + local embeddings ~170K $0

Embedding model: all-MiniLM-L6-v2 (local, free, no API key). Full reports: benchmark/LONGMEMEVAL.md, benchmark/QUALITY.md, benchmark/SCALE.md. Competitor comparison: benchmark/COMPARISON.md covering agentmemory vs mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.

Reproduce locally: eval/README.md, an adapter-pluggable harness for LongMemEval _s (public 500-Q) + coding-agent-life-v1 (in-house 15-session corpus). Grep / vector / agentmemory adapters score side-by-side, NDJSON output, published scorecards land in docs/benchmarks/.

Pairs with codegraph, Understand Anything, and Graphify. Code-graph indexing, multi-agent build pipelines, and broader knowledge graphs across docs / PDFs / images / videos. agentmemory remembers the work; those three projects light up the rest of the context layer. Recipes + question-routing table: docs/recipes/pairings.md.

vs Competitors

t
agentmemory mem0 (63K ⭐) Letta / MemGPT (24K ⭐) Khoj (36K ⭐) supermemory (29K ⭐) TencentDB Agent Memory (22K ⭐) MemPalace (54K ⭐) oracleagentmemory Hippo Built-in (CLAUDE.md)
Type Memory engine + MCP server Memory layer API Full agent runtime Personal AI Memory API + app Team memory hub (LLM proxy) Vector memory (OSS) Memory engine (Oracle DB) Memory system Static file
Retrieval R@5 95.2% 68.5% (LoCoMo) 83.2% (LoCoMo) N/A Self-reported PersonaMem 76% (self-reported) ~96.6% (self-reported) 94.4% (self-reported) N/A N/A (grep)
Auto-capture 12 hooks (zero manual effort) Manual add() calls Agent self-edits Manual API-side extraction Proxy interception (base-URL swap) Manual API extraction Manual Manual editing

agentmemory (rohitg00/agentmemory)

Searching Database…

29.6K ·GitHub
Agentmemory
Что это такое?Постоянная память для ИИ-агентов, которые пишут код: она фиксирует, что делает ваш агент, сжимает это в память, по которой можно искать, и подкладывает нужный контекст при старте следующей сессии — так что вам больше не придётся заново объяснять свой проект Claude Code, Cursor или Codex.
Это библиотека, которую я импортирую в свой код, или отдельный сервис, к которому обращаются мои агенты?Отдельный локальный сервер памяти плюс CLI agentmemory. Ваши кодинг-агенты подключаются к нему через хуки, MCP или REST API, и в код вашего проекта ничего не импортируется.
Как его запустить?Установите Node.js 20+ и выполните npx -y @agentmemory/agentmemory@latest. Первый запуск интерактивный: выберите агентов, которых нужно подключить, и LLM-провайдера (или режим без ключа), после чего он создаст конфиг, запустит сервер памяти и предложит глобальную установку.
Каким кодинг-агентам он может дать память?Любому агенту с хуками, MCP или REST API — 20 адаптеров: Claude Code (12 хуков + MCP), Codex CLI, Cursor, Gemini CLI, OpenCode (22 хука), Copilot CLI, Cline, Aider, Devin, Warp, Hermes, OpenClaw. Все они работают с одним сервером; подключить ещё можно в любой момент командой agentmemory connect.
Он работает на «нативном» Windows или это морока?Работает, но WSL2 — самый быстрый путь. На нативном Windows нужно вручную скачать ZIP закреплённого iii-engine v0.11.2 и самому извлечь iii.exe — CLI не распаковывает его автоматически; Docker Desktop — второй поддерживаемый вариант.
Память остаётся на моём компьютере или уходит в какое-то облако?Всё остаётся локально: сервер работает на вашей машине (порты 3111 REST/MCP, 3112 — стримы, 3113 — просмотрщик, 49134 — worker), а состояние хранится в вашей пользовательской папке данных, вне репозитория. Локальный режим эмбеддингов (EMBEDDINGPROVIDER=local) выполняет вывод на устройстве после однократной загрузки модели.
Нужен ли мне API-ключ LLM, чтобы этим пользоваться?Нет. Режим без ключа работает сразу из коробки — поиск по ключевым словам выполняется через BM25 без всякого ключа. Провайдер открывает LLM-функции; EMBEDDINGPROVIDER=local даёт бесплатный семантический поиск на устройстве (all-MiniLM-L6-v2, скачивается один раз), а сжатие текста силами LLM дополнительно требует AGENTMEMORYAUTOCOMPRESS=true.
Что это меняет на практике, изо дня в день?В первой сессии вы настраиваете JWT-аутентификацию; во второй сессии, когда попросите rate limiting, агент уже знает, что ваша аутентификация использует middleware jose в src/middleware/auth.ts и что вы выбрали jose вместо jsonwebtoken ради совместимости с Edge — ничего заново объяснять и копировать не нужно.
Почему бы просто не продолжать пользоваться CLAUDE.md?Встроенные варианты вроде CLAUDE.md или .cursorrules упираются в потолок примерно в 200 строк и устаревают. agentmemory записывает информацию постоянно, сжимает увиденное в память, по которой можно искать, подкладывает нужный контекст в каждой сессии и делится ею между всеми вашими агентами вместо одного файла на каждый инструмент.
Что за движок iii в комплекте?Это локальный движок хранения и поиска, закреплённый на версии v0.11.2 и устанавливаемый в ~/.agentmemory/bin. Worker не умеет говорить на протоколе другого движка, поэтому не подключится к вашему собственному iii — он запускает закреплённую версию параллельно, не трогая вашу установку.
What are similar projects?context-mode, ruflo, mem0, brigade, billion-context, memex, Raven, MemOS
Which topics is it in?claudecode, hybrid-search, genai, hermes, copilot, hooks, gemini-cli, knowledge-graph, embeddings, openclaw, harness, opencode
Creator
rohitg00
Size
31.5 MB
Stars
29.6K
Updated
CommitOct 16Releasev0.9.30Oct 06
Age
7mo
Commits · 90 Days