Skip to content

Installation

  • Python 3.11 to 3.14 (uv installs one if needed)
  • uv or pipx
  • At least one agent: Claude Code, Codex CLI, GitHub Copilot CLI (or the Copilot app on macOS), OpenCode
  • For background facts: the CLI of the agent, logged in (claude, codex, copilot, opencode). Nothing else: no API key.
Terminal window
uv tool install "agent-mem[semantic,observer] @ git+https://github.com/Abuarchiv/agent-mem"
agent-mem setup all --write
agent-mem doctor

Agent in a container (Docker, Dev Containers)

Section titled “Agent in a container (Docker, Dev Containers)”

If your agent itself runs in a container, install agent-mem into that image and keep its data on a volume:

COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
USER node
ENV PATH=/home/node/.local/bin:$PATH AGENT_MEM_DATA_DIR=/home/node/.agent-mem
RUN uv tool install --python 3.13 "agent-mem[semantic,observer] @ git+https://github.com/Abuarchiv/agent-mem" \
&& agent-mem setup claude --write
Terminal window
docker run -it -v agent-mem-data:/home/node/.agent-mem -v claude-home:/home/node/.claude <your-image>

Log in to the agent inside the container once; agent-mem writes facts through that login. The viewer listens on 127.0.0.1 inside the container, so open it there.

InstallSizeYou get
agent-memabout 10 MBrecording, search by words, reminders for the agent, MCP server, requests saved word for word
agent-mem[semantic]plus 220 MB modelsearch by meaning (paraphrase-multilingual-MiniLM-L12-v2, ONNX, no PyTorch)
agent-mem[semantic,observer]plus about 400 MBbackground facts, work log, lessons, daily review (mem0, Qdrant local mode, spaCy)

Add an extra later with agent-mem upgrade --extras semantic observer.

agent-mem setup all --write connects every agent it finds on PATH. Name one instead of all to connect just that one. Without --write it only prints the steps.

  1. Hooks with the absolute path of the agent-mem command, so sessions started from an editor or a launcher with a short PATH find it:
    • Claude Code: ~/.claude/settings.json
    • Codex: ~/.codex/hooks.json
    • Copilot: ~/.copilot/hooks/agent-mem.json
    • OpenCode: ~/.config/opencode/plugins/agent-mem.ts
  2. The MCP server: claude mcp add --scope user agent-mem, [mcp_servers.agent-mem] in ~/.codex/config.toml, ~/.copilot/mcp-config.json, opencode.json.
  3. Models: the search model (about 220 MB) and the spaCy topic model (about 13 MB) into the data folder. Skip with --no-models.
  4. The viewer as a login item, started now: launchd on macOS, a systemd user unit on Linux, the Startup folder on Windows.

Every file is written atomically, the previous version is kept as <file>.agent-mem-backup, and your own hooks stay. A config file that is not valid JSON stops setup with “Nothing was changed”.

agent-mem setup all --write (excerpt)
claude: hooks and MCP server registered with /Users/you/.local/share/uv/tools/agent-mem/bin/agent-mem.
wrote /Users/you/.claude/settings.json
facts: written in the background by `claude` (haiku), with your existing login.
codex: hooks and MCP server registered with /Users/you/.local/share/uv/tools/agent-mem/bin/agent-mem.
wrote /Users/you/.codex/hooks.json
wrote /Users/you/.codex/config.toml
Codex asks you to trust the hooks once: start codex and run /hooks.
facts: written in the background by `codex` (gpt-6-luna), with your existing login.
search model sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 ready.
viewer: http://localhost:37778/, starts at login (/Users/you/Library/LaunchAgents/io.github.abuarchiv.agent-mem.viewer.plist).
Start a session, then run `agent-mem doctor`. `agent-mem view` opens the viewer.
  • Codex: start codex, run /hooks and trust the agent-mem hooks once. Codex asks again after an upgrade changed them.
  • Facts: each agent’s CLI must be logged in once (claude, codex, copilot). agent-mem uses that login and never reads or stores a token.
Terminal window
agent-mem doctor

Every line should be ✓ or !. A ! names the next step; see doctor. After your first session, agent-mem status shows what was saved.

Terminal window
agent-mem paths
macOSLinuxWindows
Data~/Library/Application Support/agent-mem~/.local/share/agent-mem%LOCALAPPDATA%\agent-mem
Command (uv)~/.local/bin/agent-mem~/.local/bin/agent-mem%USERPROFILE%\.local\bin\agent-mem.exe

AGENT_MEM_DATA_DIR moves the data folder.