AgentMemory captures coding sessions, makes decisions and fixes searchable, and lets your agents recall them later. Keep one memory store across tools, inspect what was saved, and choose how much context reaches the model.
- Capture: native hooks and plugins record supported session events, with secret scrubbing and offline replay.
- Recall: keyword search works without an API key; local or remote embeddings add semantic search.
- Continue: retrieve project history, lessons and session handoffs from another agent.
- Inspect: browse, edit, export and forget memories in the live viewer.
Install
Requirements:
- Node.js 20 or newer with npm and npx (
node -v, npm -v, and npx -v).
- macOS/Linux also need
curl, a POSIX sh, and tar for automatic runtime setup.
- Windows users can use WSL2 or follow the native Windows setup.
Start setup:
npx -y @agentmemory/agentmemory@latest
Choose your agents and either a provider or keyless mode. Setup writes the configuration, starts the memory server, and offers a global install for the agentmemory command. -y accepts the npm package prompt; @latest selects the current release. LLM-written observation compression is opt-in with a provider and AGENTMEMORY_AUTO_COMPRESS=true.
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 API is at http://localhost:3111 and the live viewer at http://localhost:3113. Both bind to loopback by default. Configuration lives in ~/.agentmemory/.env; see data storage for memory locations and separate instances.
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
Connect another agent with agentmemory connect <agent>. See supported integrations and everyday commands.
npm install -g @agentmemory/agentmemory@latest
The npx command above remains the canonical fresh-install path and avoids global-prefix permission issues.
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).
agentmemory works with any agent that supports hooks, MCP, or REST API. All agents share the same memory server.
Data storage
Memories stay outside your repository by default:
| Platform | Data directory |
|---|
| macOS | ~/Library/Application Support/agentmemory |
| Linux | $XDG_DATA_HOME/agentmemory or ~/.local/share/agentmemory |
| Windows | %APPDATA%\agentmemory |
An existing ./data/state_store.db is reused for instance 0. Choose another directory with --data-dir <path> or AGENTMEMORY_DATA_DIR. Keep the same directory when restarting or upgrading.
agentmemory --data-dir ~/.agentmemory-projects/main
agentmemory --instance 1
--instance 1 uses an instance-1 subdirectory, API port 3211 and viewer port 3213. See storage and backups for Redis and backend migration.
Latest release notes: CHANGELOG.md.
What's new in 0.9.33
- Large stores keep working: state reads page, so scopes above 64 MiB no longer fail, on iii 0.25.1.
- Better recall: saved memories are no longer capped at three per search, and evicted memories leave the indexes.
- Hooks reach the model: PreToolUse context arrives in the hook envelope, scoped to the current project.
- Steadier providers: placeholder keys count as unset, and the circuit breaker resets on success.
Release notes and contributor credits.
Useful recall without a model API. On LongMemEval-S, AgentMemory's keyless BM25 component found at least one relevant source for 96.2% of answerable questions and every required source for 84.7%.
| LongMemEval-S, top 5 distinct sessions | AgentMemory BM25 | Lexical baseline |
|---|
| Every required source found (strict recall-all@5) | 84.7% | 72.1% |
| At least one relevant source found (any-hit@5) | 96.2% | 88.7% |
That is 12.6 percentage points higher complete-source retrieval than the lexical baseline on the same inputs, with no embedding model or paid API. Measured on 2026-10-28: 500 questions per adapter, 470 answerable, 30 excluded from retrieval scoring, zero execution failures.
This component test measures retrieval from supplied sessions. Full-system answer quality, hybrid retrieval and competitor rankings require separate evaluations. Read the complete results, including the smaller coding fixture, limitations and reproduction steps.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
