Agent Mem

Local, self-learning memory shared by Claude Code, Codex, GitHub Copilot CLI and OpenCode.

Agent Mem records what your agents do through their hooks, learns from it, and gives every agent the relevant part of that history at the right moment. It makes no LLM calls of its own and has no daemon, no server and no open ports: one SQLite file on your machine.

What it does

All harnesses write into the same memory, so what Claude Code learned is available to Codex and vice versa. Notes that Claude Code and Codex write themselves (auto memory / memories) are read in as well.

How it learns (without an LLM)

• Activation (ACT-R): memories that are used often and recently rank higher; unused ones fade but are never deleted.

• Implicit feedback: a recalled memory counts as useful when the agent opens it, edits its files, or cites its id.

• Error → fix recipes: a failing command, followed by edits and the same command passing, becomes a recipe.

• Corrections → rules: "pnpm statt npm" / "use pnpm instead of npm" becomes a proposed rule; after enabling, npm is blocked with the reason shown to the agent.

• Dead ends: reverted changes (git checkout --, git restore, git reset --hard) become warnings for the same files.

• Association graph: files, commands, errors and packages that occur together are linked (Hebbian learning) and searched with Personalized PageRank.

• Consolidation: once a day in the background, edges decay, repeated preferences become global, outdated facts are superseded and memories anchored to deleted files are invalidated.

Search combines SQLite FTS5, optional multilingual E5 embeddings, and the graph, fused with reciprocal rank fusion. Time words such as "gestern" or "last week" filter by date.

Related MCP server: CodeLedger

Install

Requirements: macOS, Linux or Windows and Python 3.11–3.14. uv installs a suitable Python automatically. On Intel Macs semantic search is not available (ONNX Runtime ships no wheels there); full-text and graph search work.

curl -LsSf https://raw.githubusercontent.com/Abuarchiv/agent-mem/main/install.sh | sh
# Windows: irm https://raw.githubusercontent.com/Abuarchiv/agent-mem/main/install.ps1 | iex

or directly:

uv tool install "agent-mem[semantic] @ git+https://github.com/Abuarchiv/agent-mem"

Then connect your harnesses:

agent-mem setup claude     # Claude Code plugin (hooks + MCP)
agent-mem setup codex      # Codex plugin or hooks.json + config.toml
agent-mem setup copilot    # Copilot CLI plugin
agent-mem setup opencode   # OpenCode plugin + MCP entry
agent-mem models install   # optional: E5 model (~120 MB) for semantic search
agent-mem doctor

agent-mem must be on your PATH because the hooks call it.

Harness notes:

• Codex asks you to trust plugin hooks once (/hooks).

• Copilot CLI currently ignores extra context returned after a successful tool call (github/copilot-cli#2980); session start, subagent start, pre-tool and failure hints work.

• OpenCode: run sessions serially per repository (upstream snapshot lock).

• Subagents (Claude Code, Codex, Copilot CLI) receive the same short briefing as a new session.

Bring in history from before the install:

agent-mem import claude            # ~/.claude/projects/**/*.jsonl (subagent transcripts are skipped)
agent-mem import codex             # ~/.codex/sessions/**/*.jsonl
agent-mem import claude-mem ~/.claude-mem/claude-mem.db
agent-mem import agentmemory export.json

If you used claude-mem or agentmemory, disable them afterwards; otherwise hooks run twice and context is injected twice.

Commands

agent-mem status [--json] | doctor [--fix] [--json] | paths
agent-mem view [--project DIR] [--output FILE] [--no-open]   # read-only HTML page of your memory
agent-mem search "query" [--project DIR] [--all-projects] [--limit N] [--json]
agent-mem show T12 M3
agent-mem rules [list|enable|disable|delete] [ID]
agent-mem lessons                               # suggested lines for AGENTS.md / CLAUDE.md
agent-mem pause [--for 2h] | resume
agent-mem export [--project DIR] [--output FILE]
agent-mem purge --id ID | --project DIR | --before DATE | --all  [--yes]
agent-mem backup | restore [FILE | --latest]
agent-mem consolidate | index [--no-download] | eval <longmemeval.json>
agent-mem setup <harness> [--write] | models [status|install] | import <source> [PATH] [--dry-run]

MCP tools for agents: mem_search, mem_timeline, mem_get, mem_remember, mem_forget.

To browse the data, run agent-mem view. It writes one self-contained HTML page to the private data directory and opens it in your browser: timeline of turns with every action, memories with their activation, learned rules, error fixes and preferences, the association graph, and capture health. There is no server and no open port; the page blocks all network requests and shows a snapshot, so run the command again to refresh it. For raw SQL, open the database (agent-mem paths) with datasette or DB Browser for SQLite.

Configuration

config.json in the data directory (see agent-mem paths). Invalid values fall back to defaults and show up in agent-mem doctor. Main keys:

{
  "capture": true,
  "excluded_projects": ["/path/to/private/repo"],
  "exclude_globs": [".env", ".env.*", "*.pem", "secrets/**"],
  "budgets": {"session_start": 600, "prompt": 200, "failure": 120, "warning": 80, "compact": 400},
  "rules": {"auto_enable": false, "min_corrections": 2},
  "retention": {"payload_days": 30, "backup_keep": 7, "max_db_mb": 1024},
  "semantic": {"enabled": true},
  "summarize": {"enabled": false, "harness": "claude", "daily_limit": 5}
}

exclude_globs replaces the default list (.env*, keys, certificates, secrets/**, …), so keep the defaults you still want. Per project, .agent-mem.json in the repository root can set {"capture": false} or extra "exclude" globs.

summarize.enabled is the only setting that causes generative model calls: once per finished session, in the background, through the harness you already use (claude -p or codex exec). It is off by default.

Privacy and security

• Everything stays local. There is no telemetry. Agent Mem itself only goes online to download the optional embedding model; the optional session summaries run through your harness and its provider.

• Secrets are redacted before storage (API keys, tokens, private keys, passwords in assignments and URLs). <private>…</private> is never stored. Excluded files are recorded by path only.

• Recalled text is framed as data, not instructions. Content from web tools and third-party MCP servers is never injected automatically and never becomes a rule or preference.

• The database is not encrypted at rest. The data directory is created with owner-only permissions on macOS and Linux.

• purge deletes the matching data from the database and the spool, replaces all backups with a fresh one and deletes the page written by agent-mem view.

• agent-mem view writes a copy of recent data to view/agent-mem.html in the data directory (owner-only permissions). With --output you choose another location and are responsible for it.

See SECURITY.md and ARCHITECTURE.md.

Development

uv sync --all-extras
uv run pytest
uv run ruff check src tests && uv run ruff format --check src tests && uv run pyright

License

MIT