agentmemory

Persistent memory across coding sessions and agents.
Persistent memory for Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, Oh My Pi, OpenCode, DeepSeek Harness, and any MCP client.

🇬🇧 English • 🇨🇳 简体中文 • 🇹🇼 繁體中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇵🇹 Português • 🇧🇷 Português (Brasil) • 🇪🇸 Español • 🇩🇪 Deutsch • 🇫🇷 Français • 🇮🇹 Italiano • 🇳🇱 Nederlands • 🇵🇱 Polski • 🇨🇿 Čeština • 🇷🇴 Română • 🇭🇺 Magyar • 🇬🇷 Ελληνικά • 🇸🇪 Svenska • 🇩🇰 Dansk • 🇳🇴 Norsk • 🇫🇮 Suomi • 🇷🇺 Русский • 🇺🇦 Українська • 🇹🇷 Türkçe • 🇮🇱 עברית • 🇸🇦 العربية • 🇮🇳 हिन्दी • 🇧🇩 বাংলা • 🇵🇰 اردو • 🇹🇭 ไทย • 🇻🇳 Tiếng Việt • 🇮🇩 Bahasa Indonesia • 🇵🇭 Tagalog

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

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

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.

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

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

Claude Code native plugin + 12 hooks + MCP	Codex CLI native plugin + 6 hooks + MCP	GitHub Copilot CLI MCP + plugin hooks/skills	Cursor native plugin + lifecycle hooks + MCP	OpenCode capture plugin + MCP
Devin 6 hooks + skills + MCP	OpenClaw native plugin + MCP	Hermes native plugin + MCP	pi native recall + capture + skills	OpenHuman native Memory trait backend
Gemini CLI MCP server	Antigravity MCP + hooks	Claude Desktop MCP server	Warp connect + MCP + skills	Zed MCP server
Cline MCP server	Continue MCP server	Droid MCP server	Kiro MCP server	Qwen Code MCP server
DeepSeek Harness native capture + MCP	Roo Code MCP server	Kilo Code MCP server	Goose MCP server	Aider REST API
Oh My Pi native recall + capture + skills + optional MCP

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

Memories stay outside your repository by default:

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.

• More focused recall: project and agent scopes, saved-memory retrieval, explicit context budgets and full-source expansion.
• Less repeated work: incremental session summaries skip unchanged observations; exports page through stored data.
• More native integrations: installable Pi package, OMP and DeepSeek Harness plugins, and improved Cursor workspace attribution.
• Safer recovery: compression, import validation and runtime recovery fixes, with status and activity visible in the viewer.

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%.

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.

AgentMemory is built for the coding workflow you already have. Capture supported agent activity automatically, share project history across tools, retrieve scoped memories, and inspect the original sources in a local viewer. Lessons, actions, versioned memories and import/export ship in the Apache-2.0 project; keyword recall needs no account or model API key.

Choose by workload and deployment. Other products also offer local deployment or agent plugins, so those alone are not useful differentiators.

Detailed comparison and sources, checked 2026-10-28. Deployment options, provider costs and integrations vary; scores from different datasets and metrics are not a head-to-head ranking.

# Terminal 1: start the server
npx -y @agentmemory/agentmemory@latest

# Terminal 2: seed sample data and see recall in action
npx -y @agentmemory/agentmemory@latest demo

demo seeds 3 realistic sessions (JWT auth, N+1 query fix, rate limiting) and runs searches against them. Keyless installs disable vectors, so the mem::search keyword queries should hit through BM25 while database performance optimization can return zero. smart-search may additionally return structural graph matches when graph data exists. To make the semantic query find the N+1 fix through vectors, set EMBEDDING_PROVIDER=local, restart, and allow the first model download to finish.

Open http://localhost:3113 to watch the memory build live.

With the server running, check health, the viewer and status:

curl -fsS http://localhost:3111/agentmemory/livez
curl -fsS http://localhost:3111/agentmemory/health
curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status

status reports server health, provider and embedding mode, capture delivery, and recovery state. Save a probe and confirm it is searchable. Protected REST requests require the daemon secret. If you configured AGENTMEMORY_SECRET, use that value in this terminal; otherwise load the generated local secret:

read -r AGENTMEMORY_SECRET < "$HOME/.agentmemory/secret"

curl -fsS -X POST http://localhost:3111/agentmemory/remember \
  -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'

curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
  -H "Authorization: Bearer $AGENTMEMORY_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"query":"restart persistence probe","limit":5}'

Then run npx -y @agentmemory/agentmemory@latest stop, start the canonical command again in Terminal 1, wait for /agentmemory/livez, and repeat the search. The probe must still be returned. If you selected a custom --data-dir, pass the same directory on the restart.

Install and setup live in Install above (the first run walks you through it). Day to day:

agentmemory                    # start the server
agentmemory stop               # stop it cleanly
agentmemory status             # health, providers and recovery state
agentmemory capture            # inspect capture inbox and offline spool
agentmemory capture --drain    # replay queued observations
agentmemory connect <agent>    # connect another agent
agentmemory doctor             # interactive diagnostics + fix prompts
agentmemory remove             # uninstall everything we created

Every session agentmemory records is replayable. Open the viewer, pick the Replay tab, and scrub through the timeline: prompts, tool calls, tool results, and responses render as discrete events with play/pause, speed control (0.5x to 4x), and keyboard shortcuts (space to toggle, arrows to step).

To bring in older Claude Code JSONL transcripts:

# Import everything under the default ~/.claude/projects
npx -y @agentmemory/agentmemory@latest import-jsonl

# Or import a single file
npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl

Imported sessions appear alongside native sessions in Replay. Transcripts are indexed for search and marked with origin channel import; session processing can also produce crystals and lessons.

Heads-up if you rely on import-jsonl as your primary capture path: Claude Code's cleanupPeriodDays (in ~/.claude/settings.json, default 30) auto-deletes JSONL transcripts older than that window from ~/.claude/projects/. If you install agentmemory fresh on a months-old Claude Code history, anything older than 30 days is already gone before the first import. Either run import-jsonl on a cron, raise cleanupPeriodDays to something higher, or wire the auto-capture hooks (the default plugin install path) so each turn lands in agentmemory while the session is live and the JSONL cleanup stops mattering.

Use the maintenance command when you intentionally want to update your local runtime:

npx -y @agentmemory/agentmemory@latest upgrade

This updates the local runtime and may update JavaScript dependencies in the current workspace. Back up your data and read the upgrade guide before updating an existing installation.

Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.

If you wire agentmemory's MCP server through ~/.claude.json directly instead of using /plugin install, Claude Code never resolves ${CLAUDE_PLUGIN_ROOT} and you have to point hook scripts at absolute paths in ~/.claude/settings.json. Those paths typically embed the agentmemory version (e.g. ~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…), so the next upgrade silently breaks every hook.

Workaround:

agentmemory connect claude-code --with-hooks

This merges the same hook commands into ~/.claude/settings.json with absolute paths resolved to the bundled plugin/ directory of the currently installed @agentmemory/agentmemory package. Re-run the command after upgrading agentmemory to refresh the paths. User entries in the same file are preserved; only previous agentmemory entries are replaced. Using the /plugin install path remains the recommended approach. For remote or protected deployments, launch Claude Code with AGENTMEMORY_URL and AGENTMEMORY_SECRET set. The plugin passes both values through to its bundled MCP server; when AGENTMEMORY_URL is empty, the MCP shim uses http://localhost:3111.

# 1. start the memory server in a separate terminal
npx -y @agentmemory/agentmemory@latest

# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory

The Codex plugin ships from the same plugin/ directory as the Claude Code plugin. It registers:

• A bundled stdio MCP bridge to the running daemon, with no npm download or fallback store. See the local Codex guide to test an unreleased build.
• 6 lifecycle hooks: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop
• 9 invocable skills: /recall, /remember, /session-history, /forget, /recap, /handoff, /lesson, /commit-context, /commit-history, plus 8 reference skills the agent loads on demand (memory discipline, MCP tools, REST API, config, agents, hooks, architecture, and the skill-authoring guide)

Codex's hook engine injects CLAUDE_PLUGIN_ROOT into hook subprocesses (per codex-rs/hooks/src/engine/discovery.rs), so the same hook scripts work across both hosts without duplication. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure events are Claude-Code-only and are not registered for Codex.

Native plugin hook dispatch is verified with Codex CLI 0.150.1. Trust the plugin hooks before expecting capture. Desktop behavior depends on its bundled runtime; check /hooks and confirm a captured event before enabling a workaround.

If your host requires global hooks, mirror the commands into ~/.codex/hooks.json. When MCP is already wired, the current connector needs --force to reach hook installation:

agentmemory connect codex --with-hooks --force

This merges global hooks and rewrites the agentmemory MCP entry, preserving unrelated entries. Review any custom agentmemory endpoint settings before using --force. Re-run after upgrading to refresh script paths. Enable either native plugin hooks or global copies to avoid duplicate capture.

For VS Code agent mode, use the Copilot MCP and automatic-capture guide. The CLI connector does not configure VS Code.

# MCP-only wiring
agentmemory connect copilot-cli

# Alternatively, full hooks/skills plugin from the GitHub subdir
copilot plugin install rohitg00/agentmemory:plugin

agentmemory connect copilot-cli merges mcpServers.agentmemory into ~/.copilot/mcp-config.json (or $COPILOT_HOME/mcp-config.json when COPILOT_HOME is set) and preserves existing servers. On native Windows this is the only automated connect adapter; configure every other native Windows agent manually. WSL connect is supported only when the target agent is installed in that same WSL environment. Copilot picks up the MCP server on next launch or after /mcp. Install the plugin as well when you want the full hook/skill experience.

# MCP wiring
agentmemory connect cursor

Then add the native hooks: Settings → Plugins → Add marketplace → select an agentmemory checkout (the directory containing .cursor-plugin/plugin.json), enable the agentmemory plugin, and reload the window.

The plugin provides lifecycle capture, workspace-aware project attribution, skills and MCP. Enable either the plugin hooks or manual hooks in ~/.cursor/hooks.json to avoid duplicate capture.

Full guide: integrations/cursor/

agentmemory connect pi --with-mcp
agentmemory connect omp --with-mcp
agentmemory connect dsh --with-hooks

Choose the command for your host. Pi and OMP install native recall/capture, offline replay and 17 skills; --with-mcp adds the full toolset. Run /reload in Pi or restart OMP, then check /agentmemory-status. DSH installs MCP and the bundled capture plugin; restart DSH after connecting.

Pi also supports an installable @agentmemory/pi package. See the Pi package guide for local installation and npm availability. Use one installation method per host.

Guides: Pi, Oh My Pi, DSH.

Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.

Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:

mcp_servers:
  agentmemory:
    command: npx
    args: ["-y", "@agentmemory/mcp"]

memory:
  provider: agentmemory

Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.

Start the memory server: npx -y @agentmemory/agentmemory@latest

agentmemory ships 17 skills in the Claude-Code-style <dir>/SKILL.md format: 9 invocable action skills (remember, recall, recap, handoff, forget, lesson, commit-context, commit-history, session-history) and 8 reference skills the agent loads on demand (memory-discipline, agentmemory-mcp-tools, agentmemory-rest-api, agentmemory-config, agentmemory-agents, agentmemory-hooks, agentmemory-architecture, write-agentmemory-skill). The reference skills carry data tables generated from source, so they never drift. The skills CLI by vercel-labs auto-installs them into the calling agent's native skill directory across supported agents (Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf, and more):

npx skills add rohitg00/agentmemory -y          # auto-detects the calling agent
npx skills add rohitg00/agentmemory -y -a warp  # explicit agent
npx skills add rohitg00/agentmemory -y -a '*'   # install to every installed agent

This is complementary to agentmemory connect <agent>:

• agentmemory connect <agent> normally writes the MCP server config. Hermes, OpenClaw, Pi and Oh My Pi install their native integration and bundled skills by default; MCP is opt-in with --with-mcp.
• npx skills add rohitg00/agentmemory installs skills for agents without native bundled skills. Skip this step for Hermes, OpenClaw, Pi and Oh My Pi; their native connectors already install the skills.

For the few agents the skills CLI doesn't cover yet (Zed v1.3.x and below), drop the 17 SKILL.md files under the agent's native skill directory yourself; the same format works everywhere.

The agentmemory entry is the same MCP server block across every host that uses the mcpServers shape (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw):

"agentmemory": {
  "command": "npx",
  "args": ["-y", "@agentmemory/mcp"],
  "env": {
    "AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
    "AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
  }
}

Merge this entry into the existing mcpServers object in the host's config file; don't replace the file. If the file already has other servers, add agentmemory next to them as another key inside mcpServers. If mcpServers is missing entirely, paste the block inside { "mcpServers": { ... } }. The ${VAR} placeholders inherit AGENTMEMORY_URL / AGENTMEMORY_SECRET from the shell at MCP-server launch; unset vars pass empty strings and the shim falls back to http://localhost:3111. One wired entry covers both local and remote (k8s / reverse-proxied) deployments.

Sandboxed MCP clients (Flatpak / Snap / restrictive containers) that can't reach the host's localhost: also set "AGENTMEMORY_FORCE_PROXY": "1" in the env block, and point AGENTMEMORY_URL at a route the sandbox can actually reach (e.g. your LAN IP).

Use the REST API from any language or the MCP tools from an agent. REST requests use JSON and bearer authentication; see the save and search example.

For direct runtime integration, see the Python examples.

git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start

npm start launches the same local server as the installed CLI. Dependencies for automatic setup are listed under Install; the API and viewer bind to 127.0.0.1.

agentmemory runs on Windows 10/11. WSL2 follows the Linux path and can install the pinned engine automatically. Native Windows requires the pinned iii-engine v0.25.0 binary installed manually; download the matching archive from the iii v0.25.0 release page, verify its checksum, and place iii.exe on PATH (for example %USERPROFILE%\.local\bin\iii.exe). The CLI does not extract the Windows ZIP automatically.

Native Windows automated MCP wiring supports only agentmemory connect copilot-cli. For other native Windows agents, use the manual MCP block from Other agents. Run connect inside WSL only when the target agent is installed in that same WSL environment.

Standalone MCP only (no engine). If you only need MCP tools and do not need the REST API, viewer, or runtime services:

npx -y @agentmemory/agentmemory@latest mcp
# or
npx -y @agentmemory/mcp

Diagnostics: Run agentmemory doctor or restart with --verbose. Use --port <N> or --instance <N> if the default ports are occupied. See the upgrade guide for runtime compatibility and recovery.

Self-host with Docker Compose or the platform templates below. Persistent memory and credentials live on the /data volume. Back up and reuse that volume when upgrading. See the deployment guide for authentication, network access, backups and migration.

Render's one-click deploy button requires render.yaml at the repository root, which we deliberately keep clean. Use the Render Blueprint flow documented in deploy/render/ to point at the in-repo blueprint manually.

Full setup details (HMAC capture, viewer SSH tunnel, rotation, backup, cost floors) live in deploy/:

• deploy/fly: single machine with auto_stop_machines = "stop"; cheapest idle.
• deploy/railway: Hobby plan flat fee, volume in the dashboard.
• deploy/render: Blueprint flow, automatic disk snapshots on paid plans.
• deploy/coolify: self-hosted on your own VPS via Coolify; same Docker Compose stack, you own the host and the data.

REST uses port 3111; the viewer uses 3113. Keep both private or protect them with authentication and TLS. Platform-specific exposure settings and legacy Docker migration are covered in the deployment guide.

Project knowledge gets scattered across chats and instruction files. AgentMemory makes past decisions, fixes and lessons searchable from the agent you are using now.

Session 1: "Add auth to the API"
  Agent writes code, runs tests, fixes bugs
  Connected hooks capture supported tool events
  Observations become searchable project history

Session 2: "Now add rate limiting"
  Agent recalls:
    - Auth uses JWT middleware in src/middleware/auth.ts
    - Tests in test/auth.test.ts cover token validation
    - You chose jose over jsonwebtoken for Edge compatibility
  Continues with the earlier decisions in context.

Agent instructions and memory files remain useful for stable project guidance. AgentMemory adds searchable session history, source-linked memories and coordination across connected agents.

PostToolUse hook fires
  -> Stable event ID, durable capture inbox, offline spool when unavailable
  -> Privacy filter (strip secrets, API keys)
  -> Store raw observation
  -> Synthetic compression by default
     (LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
  -> Vector embedding when an embedding provider is active
  -> Index in BM25, plus vectors when enabled

Stop / SessionEnd hook fires
  -> Incremental summary when new observations are available
  -> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
  -> Slot reflection (if AGENTMEMORY_SLOTS=true and AGENTMEMORY_REFLECT=true)

SessionStart hook fires
  -> Load project profile (top concepts, files, patterns)
  -> Hybrid search (BM25 + vector + graph)
  -> Token budget (default: 2000 tokens)
  -> Inject context when enabled by the integration

Modeled on how human brains process memory, including sleep consolidation.

Memories decay over time (Ebbinghaus curve). Frequently accessed memories strengthen. Stale memories auto-evict. Contradictions are detected and resolved.

The table below describes the Claude Code hook surface. Other integrations capture the events their host provides; see the individual setup guides. Automatic context injection through the shared hooks is opt-in with AGENTMEMORY_INJECT_CONTEXT=true.

The Claude bridge is opt-in: set CLAUDE_MEMORY_BRIDGE=true and CLAUDE_PROJECT_PATH to your project directory, then restart agentmemory. memory_claude_bridge_sync exports only the latest memories scoped to that project, excluding unscoped memories. The read direction continues to read existing MEMORY.md content.

Export creates MEMORY.md only when it is absent. Existing files are preserved, including previous generated exports and edits made by you or Claude Code. Identical content returns changed: false; different content returns an error. To regenerate deliberately, move the existing file to a backup location (or remove it if no longer needed), then run the tool again. See the bridge settings in .env.example.

Triple-stream retrieval combining three signals:

Fused with Reciprocal Rank Fusion (RRF, k=60) and session-diversified (max 3 results per session).

When a vector index is populated, mem::search (behind memory_recall) uses the hybrid BM25 + vector ranker. Without embeddings it uses BM25. smart-search can additionally fuse structural graph matches when graph data exists, including in keyless mode. Lesson recall runs on a dedicated in-memory BM25 index instead of scanning the whole corpus per query. Superseded memory versions are excluded from every recall path; the version chain keeps their history.

Vectors survive a crash or force-kill. The vector index is saved in buckets at most every AGENTMEMORY_INDEX_SAVE_INTERVAL_MS (10 minutes). Every vector added or removed in between is also written right away to a small pending log in the state store, and the next start replays it without calling the embedding provider. Each successful save empties the log. For older documents without vectors, AGENTMEMORY_VECTOR_BACKFILL=all opts into a bounded backfill at startup, capped by AGENTMEMORY_VECTOR_BACKFILL_MAX (500). Keep the opt-in set across restarts to process more documents. See source and vector recovery. /agentmemory/status and the viewer show the pending log size and the backfill state. Keyless installs write nothing.

BM25 tokenizes Greek, Cyrillic, Hebrew, Arabic, and accented Latin out of the box. For Chinese / Japanese / Korean memories, install the optional segmenters (npm install @node-rs/jieba tiny-segmenter) to split CJK runs into word-level tokens; without them, agentmemory soft-falls to whole-run tokenization and prints a one-time hint on stderr.

Keyless installs disable vector embeddings: mem::search uses BM25, while smart-search can also use existing structural graph data. To opt into free on-device semantic embeddings, add this to ~/.agentmemory/.env and restart agentmemory:

EMBEDDING_PROVIDER=local

The normal npm install includes the optional @huggingface/transformers runtime. The first embedding request downloads Xenova/all-MiniLM-L6-v2, so it needs network access and can take longer; subsequent inference runs on-device. Remote providers are auto-detected from their keys unless EMBEDDING_PROVIDER overrides them.

54 tools, 6 resources, 3 prompts, and 17 skills.

MCP shim vs full server: the published @agentmemory/mcp package is a thin shim. It exposes the full 54-tool surface only when it can reach a running agentmemory server via AGENTMEMORY_URL (proxy mode). With no server reachable, the shim falls back to a 7-tool local set (memory_save, memory_recall, memory_smart_search, memory_sessions, memory_export, memory_audit, memory_governance_delete). The AGENTMEMORY_TOOLS=core|all env var is a server-side flag; setting it in the shim's env block has no effect. If you see only 7 tools in Cursor / OpenCode / Gemini CLI, start npx -y @agentmemory/agentmemory@latest (or connect to a self-hosted server) and set AGENTMEMORY_URL=http://localhost:3111.

Three tool surfaces, smallest to largest: AGENTMEMORY_TOOLS=core trims visibility to 8 essentials (memory_save, memory_recall, memory_consolidate, memory_smart_search, memory_sessions, memory_diagnose, memory_lesson_save, memory_reflect); the base set below is the registry's 14 foundational tools; the default (AGENTMEMORY_TOOLS=all) exposes all 54, minus the 6 memory_slot_* tools until AGENTMEMORY_SLOTS=true.

The table shows the four core skills. The full set is 9 invocable skills plus 8 reference skills; see the Native skills section above.

Run without the full server, for any MCP client. Either of these works:

npx -y @agentmemory/agentmemory@latest mcp   # canonical (always available)
npx -y @agentmemory/mcp                # shim package alias

Or add to your agent's MCP config:

Most agents (Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):

{
  "mcpServers": {
    "agentmemory": {
      "command": "npx",
      "args": ["-y", "@agentmemory/mcp"],
      "env": {
        "AGENTMEMORY_URL": "http://localhost:3111"
      }
    }
  }
}

Merge the agentmemory entry into your host's existing mcpServers object rather than replacing the file. For sandboxed clients that can't reach the host's localhost, add "AGENTMEMORY_FORCE_PROXY": "1" to the env block and set AGENTMEMORY_URL to a route the sandbox can reach.

OpenCode (opencode.json):

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  },
  "plugin": ["./plugins/agentmemory-capture.ts"]
}

Copy the plugin file from the repo:

mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/

Auto-starts on port 3113. The viewer loads one snapshot when it connects (GET /agentmemory/viewer/snapshot) and then applies live events over SSE at /agentmemory/viewer/events on the REST worker: new memories, lessons, observations, audit entries, graph changes and health updates appear without polling or page reloads. The only other requests are the actions you click, "load more" pages and searches. When the stream drops, the viewer shows how old its numbers are, reconnects with backoff and resyncs from one snapshot.

• 12 tabs in four groups with live counts, deep links (#memories/<id>, #sessions/<id>?obs=<id>, #graph/<id>, #health/consolidation), keyboard shortcuts and a mobile menu.
• Memories: server-side search, filters by project, agent and type, a detail panel with the version chain and a word diff, provenance links, copy buttons for the id, the MCP call and a curl command, edit (a new version), forget with confirmation, bulk forget and JSON export.
• Sessions: an inline observation timeline with readable tool input and output, filters and paging, and the memories and lessons each session produced.
• Graph: search, node detail with relations and sources, a legend that does not rely on colour alone, and zoom controls.
• Health: the live version of GET /agentmemory/status. Every problem comes with its fix, plus the state backend, index save state, graph provenance compaction progress and a consolidation explainer with the real thresholds.
• Audit, Activity, Profile, Replay, Lessons, Actions and Crystals pages, each with an empty state that says what the section is, why it is empty and the command that fills it, and a ? glossary tooltip on every term and number.

open http://localhost:3113

The viewer server binds to 127.0.0.1 by default and attaches the server secret when it forwards requests to the REST API. On a non-loopback bind, the HTML shell remains public but every proxy request requires the bearer; the viewer prompts for it and stores it in session storage. Configure explicit host/origin allowlists and TLS before exposing a viewer. The REST-served /agentmemory/viewer endpoint follows the normal bearer-token rules and redirects browsers without a token to the viewer port. CSP headers use a per-response script nonce and disable inline handler attributes (script-src-attr 'none').

agentmemory auto-detects providers from your environment. A provider makes LLM-backed operations available, but provider configuration alone does not enable LLM-written observation compression. That path requires both a provider and AGENTMEMORY_AUTO_COMPRESS=true.

agentmemory talks to any OpenAI-API-compatible server, so anything that exposes /v1/chat/completions works without code changes. No paid keys, no cloud, no rate limits; runs entirely on your hardware.

Ollama (default port 11434):

ollama pull qwen3:8b   # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve

# ~/.agentmemory/.env
OPENAI_API_KEY=ollama                          # any non-empty string; Ollama ignores it
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:8b

LM Studio (default port 1234):

Open LM Studio → Local Server tab → Start Server. Pick any chat model from the picker (Qwen 3, gpt-oss, DeepSeek R1, etc.).

# ~/.agentmemory/.env
OPENAI_API_KEY=lmstudio                        # any non-empty string; LM Studio ignores it
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b                          # match the model name from LM Studio

vLLM / llama.cpp / Text Generation Inference: same shape. Point OPENAI_BASE_URL at whatever URL your server exposes and set OPENAI_MODEL to a name your server will accept.

Model picks for memory work: compression and summarization are short tasks (<2K tokens in, <500 tokens out) where a 7B instruct model is plenty. Recommendations:

Qwen 3 models think by default and can burn the whole token budget on reasoning before any output. Set AGENTMEMORY_LLM_NOTHINK=1 to append /no_think to graph-extraction prompts, and raise MAX_TOKENS (16384 works) if extractions come back empty.

Reasoning-class models (o1-style with <think> blocks) can return empty content with a reasoning field your local server may not surface. If extractions come back blank, switch to a non-reasoning model first. The OPENAI_REASONING_EFFORT=none env can also disable thinking on Ollama Cloud thinking models that mirror the OpenAI reasoning schema.

Local embeddings ship as an optional dependency but are not enabled by default. Set EMBEDDING_PROVIDER=local to opt into Xenova/all-MiniLM-L6-v2 (384-dim). The first embedding request downloads the model; inference is on-device afterward. Without that setting or a remote embedding key, vectors stay disabled, mem::search uses BM25, and smart-search can still add existing graph matches.

Start keyless for capture and keyword recall. Enable EMBEDDING_PROVIDER=local for on-device semantic search after the initial model download. LLM-written compression requires a provider and AGENTMEMORY_AUTO_COMPRESS=true; it can make a request for each captured observation, so check your provider's current pricing before enabling it.

The viewer and agentmemory status show the active providers. Local OpenAI-compatible servers work with the same configuration shape as hosted providers.

In multi-agent setups where several roles share one agentmemory server (architect / developer / reviewer / researcher / support-agent), AGENT_ID tags every write with the role that made it. AGENTMEMORY_AGENT_SCOPE controls whether recall filters by that tag.

TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated  # optional; default "shared"

Two modes:

What gets tagged when AGENT_ID is set: Session.agentId, RawObservation.agentId, CompressedObservation.agentId, Memory.agentId. The role flows from api::session::start → mem::observe → mem::compress → KV.

What gets filtered in isolated mode: mem::smart-search, /agentmemory/memories, /agentmemory/observations, /agentmemory/sessions. Each endpoint accepts ?agentId=<role> to override per-request, and ?agentId=* to opt out of the env scope entirely. /memories also accepts ?includeOrphans=true to surface pre-AGENT_ID memories whose agentId is undefined.

Per-call override at the SDK / REST layer: every mutating endpoint (/session/start, /remember) accepts an agentId field in the request body that wins over the env. Useful for runtimes routing many roles through one server process. The MCP memory_save tool exposes the same agentId field, the standalone stdio server forwards both agentId and project, and saved memories carry agentId into the search index, so agent-scoped search covers memories as well as observations.

When AGENT_ID is unset, memory remains unscoped (legacy behavior, no tags, no filters).

The API and viewer bind to loopback by default.

--port <N> sets the REST port and defaults the viewer to N+2. Use --instance N for a separate runtime. Internal runtime listeners must remain private; see the deployment guide before exposing the service remotely.

The default file store needs no separate database service. Redis is optional with AGENTMEMORY_STATE_BACKEND=redis and AGENTMEMORY_REDIS_URL. Changing backends does not copy existing memories. Follow the storage and backup guide for persistence settings, Redis limitations and authenticated export/import.

Put agentmemory runtime configuration in ~/.agentmemory/.env instead of exporting variables in every shell. If the viewer shows a setup hint like export ANTHROPIC_API_KEY=..., copy it into this file as ANTHROPIC_API_KEY=... without the export prefix, then restart agentmemory. Set AGENTMEMORY_ENV_FILE to use another env-file path.

Process environment variables take precedence over values in the file. Restart the server after changing its configuration.

On Windows, the same file lives at %USERPROFILE%\.agentmemory\.env:

New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env

To test with a Claude Code Pro/Max subscription instead of an API key, opt in explicitly:

AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true

LLM-written observation compression requires both lines: access to an LLM provider (including this explicit subscription fallback) and AGENTMEMORY_AUTO_COMPRESS=true. A provider by itself leaves the default synthetic compression path in place.

Consolidation (graph nodes, lessons, crystals) is on by default whenever an LLM provider is configured. Explicitly opt out with CONSOLIDATION_ENABLED=false if you want LLM-free operation. Graph extraction is a separate flag:

GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false   # opt out of auto-consolidation

Common options for ~/.agentmemory/.env:

# Semantic recall on your machine, after the first model download
EMBEDDING_PROVIDER=local

# Optional automatic context injection through the shared hooks
# AGENTMEMORY_INJECT_CONTEXT=true

# Optional LLM-written compression; also requires a configured provider
# AGENTMEMORY_AUTO_COMPRESS=true

# Show 8 essential MCP tools instead of the default 54
# AGENTMEMORY_TOOLS=core

# Disable scheduled auto-forget and lesson/insight decay
# AUTO_FORGET_ENABLED=false
# LESSON_DECAY_ENABLED=false
# INSIGHT_DECAY_ENABLED=false

The complete reference is .env.example, including provider credentials, capture filters, retention, storage, team scope and optional features. AGENTMEMORY_ENV_FILE selects another file. Never commit a populated .env or bearer secret.

146 endpoints on port 3111. The REST API binds to 127.0.0.1 by default. Protected endpoints require Authorization: Bearer <secret>, and mesh sync endpoints require an explicitly set AGENTMEMORY_SECRET on both peers.

Authentication is on by default. When AGENTMEMORY_SECRET is not set (in the shell or in ~/.agentmemory/.env), the CLI generates a random secret on first start and stores it at ~/.agentmemory/secret, mirrored to the selected data directory as secret, with mode 0600 (the platform-specific default data directory is described above). Bundled clients read the canonical secret first when they talk to a local server: the CLI, the viewer, the hooks under plugin/scripts, the MCP server and the @agentmemory/mcp shim, the configs written by agentmemory connect, and the bundled OpenCode, Pi, OpenClaw, Hermes and filesystem-watcher integrations. The stored secret is only sent to loopback URLs (localhost, 127.0.0.0/8, ::1). An explicit AGENTMEMORY_SECRET always wins, and remote clients need the secret set in their environment. Repository-based Docker self-host deployments and the deploy/ entrypoints generate and export their own secret. To call the API by hand:

curl -H "Authorization: Bearer <secret-from-data-dir>" http://localhost:3111/agentmemory/health

Request rules for writes. POST, PUT, PATCH and DELETE requests to the REST API and the viewer must send Content-Type: application/json (a charset parameter is fine) whenever they carry a body, and an Origin header, when present, must be a loopback origin for the configured REST or viewer port or be listed in VIEWER_ALLOWED_ORIGINS (comma-separated, e.g. https://memory.example.com). Clients that send no Origin header (CLI, hooks, MCP, curl, server-to-server) are unaffected. The viewer also accepts its own origin.

File paths. Endpoints that read or write files (/compress-file, /replay/import-jsonl, /graph/import-graphify) only accept paths under ~/.agentmemory, the instance data directory, or a directory listed in AGENTMEMORY_IMPORT_ROOT (separate several with :, or ; on Windows). /replay/import-jsonl also accepts its default ~/.claude/projects. /obsidian/export stays inside AGENTMEMORY_EXPORT_ROOT and /migrate inside ~/.agentmemory. Symlinks are resolved before every check.

Secret scrubbing. API keys, bearer tokens, PEM private key blocks and credentials embedded in URLs (scheme://user:password@host) are redacted before text is stored, on every write path: observations, remember, evolve, slots, lessons, actions, sketches, signals, checkpoints, imports, jsonl replay, mesh sync, team shares, compression and summary output, crystals and graph nodes.

Capture delivery. Hooks send each observation once to POST /agentmemory/observe with an eventId. It is the host's own id for the call when the payload has one (for example Claude Code's tool_use_id), otherwise a hash of the session, hook type, tool name, input, output and host timestamp. The server writes the event to a capture inbox in the state store, stores the observation, then removes the inbox entry. The status code says what happened:

Failed events are retried every AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS (10 s) with doubling backoff, up to AGENTMEMORY_CAPTURE_MAX_ATTEMPTS (5). Events that still fail stay in the inbox as dead letters, are listed on /agentmemory/status and the viewer Health page, and can be retried with POST /agentmemory/capture/retry ({"eventId": "..."} or {"all": true}). Accepted event ids are remembered for AGENTMEMORY_CAPTURE_DEDUP_HOURS (168 hours, at most AGENTMEMORY_CAPTURE_EVENTS_MAX ids), so a hook replayed after a timeout or a restart is stored once, while two separate tool calls with their own host ids are stored twice even when their content is identical. When an observation is deleted (forget, session delete, eviction, auto-forget or an import that replaces the store), its event is marked as deleted before the observation is removed, so a replay of that event inside the same window is answered as a duplicate and stores nothing. The state store writes to disk every 2 seconds, so an answered event can still be only in memory for a moment. To cover that, every 2xx answer also carries the server's bootId (new at every start), acceptedAt and durableAfterMs (the save interval plus 1.5 s on the file store, 1.5 s on redis, where persistence is the operator's setting). Hooks keep the event in the local spool until that window has passed and delete it on a later call without another request. If the bootId has changed by then, the server restarted, so the hook sends the event again with the same eventId; an event that did reach the disk is not stored twice. The server also sends such events itself at start and every retry interval, so a restart loses nothing even when no hook runs afterwards. Older hooks ignore the extra fields, and new hooks against an older server discard the event on 2xx as before.

When the server is down, does not answer in time or returns a 5xx, the hook appends the observation to a local spool file, <data dir>/capture-spool/<host>-<port>.jsonl (override the folder with AGENTMEMORY_CAPTURE_SPOOL_DIR). The file is private to your user (mode 600), secrets are redacted the same way the server redacts them, it holds at most AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES (5 MiB) and drops entries older than AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS (168). When it is full, new entries are dropped and counted, and /agentmemory/status reports it. The hook still exits 0 within its time limit and adds no request when the server is healthy. The spool is sent at the next start and by the first hook that reaches the server again, in a background process so the agent does not wait. Event ids make this safe: an observation that did arrive before a timeout is not stored twice. npx @agentmemory/agentmemory capture shows the spool and the server inbox, --drain sends the spool now, and GET /agentmemory/capture returns the same as JSON. Set AGENTMEMORY_CAPTURE_SPOOL=false to turn the spool off.

Resetting the graph. Call POST /agentmemory/graph/reset to start a new graph generation. The previous graph becomes inaccessible to graph queries, node lookups, statistics, and MCP reads; new imports and extraction populate the new generation. Existing observations and memories remain available. Old graph storage is retained.

Upgrading from v0.9.30: if you already reset the graph before upgrading, run POST /agentmemory/graph/reset again after the upgrade. Earlier reset timestamps are not used to infer a completed generation reset.

Compacting graph provenance. Legacy provenance compaction is deferred at startup because it reads complete legacy scopes. /agentmemory/status reports deferred, or off with AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false. Run the manual compaction below during maintenance. Retrieval index migration is separate: use agentmemory graph-index migrate --allow-legacy-scan as described in the maintenance guide.

To run it by hand, call POST /agentmemory/graph/compact. It walks the name and edge-key indexes instead of listing every node and edge, and is safe to re-run. When it trims ids it writes a graph_compact audit entry.

curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{}'

On a large store, or when the call returns 504, run it in slices. Send scope (nodes, edges or history), offset and limit, then call again with the returned nextOffset until it is null. Do this for nodes, edges and history, and finish with one {"scope":"snapshot"} call, because a sliced run does not touch the cached snapshot.

curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Authorization: Bearer <secret>" -H "Content-Type: application/json" -d '{"scope":"snapshot"}'

npm run dev               # Hot reload
npm run build             # Production build
npm test                  # 4,100+ tests
npm run test:integration  # API tests (requires running services)

Prerequisites: see Install. Contribution rules and release checks are in CONTRIBUTING.md.

Apache-2.0