agentmemory

// Overview

agentmemory is a self-hosted memory server for AI coding agents. Coding assistants normally start each session with no idea what happened in the last one, so you re-explain the same architecture, conventions, and past decisions. agentmemory records what the agent actually does — prompts, tool calls, tool outputs, failures — through the agent's own lifecycle hooks, then injects the relevant parts back at the start of the next session within a token budget (2000 tokens by default).

Capture runs as a pipeline: a PostToolUse hook fires, the observation is SHA-256 deduplicated within a five-minute window, passed through a privacy filter that strips secrets and API keys, stored, compressed, and indexed in BM25 (plus vectors when an embedding provider is configured). At session end it summarizes, and can extract a knowledge graph. Memories are organised into four tiers modeled on human memory — working (raw observations), episodic (session summaries), semantic (extracted facts and patterns), and procedural (workflows and decision patterns) — and decay on an Ebbinghaus curve so frequently used memories strengthen while stale ones are evicted.

It runs locally with no external database: the server exposes a REST API and an MCP server on port 3111, an iii event stream on 3112, and a live viewer on 3113 where you can watch memory build and replay any recorded session event by event. It works with Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, OpenCode and other MCP clients, wired up with agentmemory connect. It is written in TypeScript, licensed Apache 2.0, and built on the iii engine (pinned to v0.11.2).

// What it does

• Automatic capture through agent lifecycle hooks — SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, PreCompact, subagent lifecycle, Stop and SessionEnd
• Four-tier consolidation (working, episodic, semantic, procedural) with Ebbinghaus-curve decay, contradiction detection, and auto-eviction of stale memories
• Hybrid retrieval fusing BM25 keyword search, vector similarity, and knowledge-graph matches
• MCP server plus a REST API, so any MCP client can read and write memory
• Privacy filter that strips secrets and API keys before storage, and SHA-256 deduplication over a five-minute window
• Live viewer with session replay: scrub prompts, tool calls, results and responses with play/pause and speed control
• Runs keyless with no external database; optional on-device embeddings via Xenova/all-MiniLM-L6-v2 for semantic recall

// Getting started

agentmemory needs Node.js 20 or newer. The first run is an interactive setup that picks which agents to wire up, seeds the config, and starts the memory server and its pinned iii engine.

npx -y @agentmemory/agentmemory@latest

npx -y @agentmemory/agentmemory@latest demo
# then open http://localhost:3113

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

curl -fsS -X POST http://localhost:3111/agentmemory/remember \
  -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 'Content-Type: application/json' \
  -d '{"query":"restart persistence probe","limit":5}'

agentmemory connect <agent>    # wire another agent
agentmemory                    # start the server
agentmemory stop               # stop it cleanly
agentmemory doctor             # interactive diagnostics
agentmemory remove             # uninstall everything it created

echo 'EMBEDDING_PROVIDER=local' >> ~/.agentmemory/.env
agentmemory stop && agentmemory

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Stop re-explaining a codebase's architecture and conventions to a coding agent at the start of every session
• Keep memory on your own machine when session transcripts contain code or context you can't send to a hosted memory service
• Share one memory layer across several agents — Claude Code, Cursor, Codex CLI, Copilot CLI — instead of each keeping its own
• Replay a past agent session event by event to work out what it did and why
• Import existing Claude Code JSONL transcripts so older sessions become searchable memory

// How agentmemory compares

agentmemory alongside other open-source agent memory tools AI/TLDR tracks, ranked by GitHub stars.