# 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

| Moment | What happens automatically |
|---|---|
| Session start | A short briefing: commands that work in this project, decisions, dead ends, preferences, unresolved errors, the last session. |
| You send a prompt | Up to three matching memories, only when the match is strong. |
| Before a command or edit | A warning if it matches something you corrected before or a change that was reverted. Optionally a hard block (opt-in rules). |
| A command fails | If this error was fixed before, the agent sees how. |
| Turn ends | The turn (request, actions, result) is stored and indexed. |
| Context compaction | The session goal, decisions and open problems are kept: re-injected after compaction (Claude Code, Codex) or added to the compaction prompt (OpenCode). |

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.

## Install

Requirements: macOS, Linux or Windows and Python 3.11–3.14. [uv](https://docs.astral.sh/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.

```sh
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:

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

Then connect your harnesses:

```sh
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](https://github.com/github/copilot-cli/issues/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:

```sh
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:

```json
{
  "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](SECURITY.md) and [ARCHITECTURE.md](ARCHITECTURE.md).

## Development

```sh
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