Install methods

New in 14.6.0 Whichever channel you use, tam setup can then configure your clients, embeddings and an optional LLM, or prepare a company server. Existing installs upgrade silently and stay personal. See Setup wizard.

Which one should I use?

You want…	Use
The easiest setup, with your client wired automatically	npx
Claude Code only, from inside Claude Code	Claude Code plugin
A normal Python command on your PATH	pipx or pip
A Homebrew-managed install on macOS or Linux	Homebrew
Everything in containers	Docker
To read or change the source, run benchmarks, pick background services	Clone and install script
Memory shared by a team on a server	Team server

The npx and install.sh paths also configure your client and hooks. The other channels install the server only; you then run tam setup to connect your clients, or add the server by hand by pointing your client at the total-agent-memory command.

npx (Node.js)

npx -y total-agent-memory connect claude-code

Replace claude-code with claude-desktop, codex, cursor, cline, continue, windsurf, gemini-cli, opencode or aider. Since wrapper 1.9.0, connect registers the client with the installed server’s tam setup register and needs server 14.6.0 or later.

• Creates a Python virtual environment in ~/.tam/.venv (using uv when available, otherwise python3), installs the server from PyPI (falling back to GitHub), and writes your client’s MCP config.
• Registers two background services: the dashboard (http://127.0.0.1:37737) and the reflection worker. On macOS they are LaunchAgents, on Linux systemd user units, on Windows a Scheduled Task. Add --no-services to skip them.
• Requires Node.js 18+ and Python 3.11+.

Other commands of the same tool: install, status, doctor (checks Python, uv and git), dashboard status|start|stop|logs|open, upgrade, uninstall --yes. Useful flags: --server-version 14.8.0 to pin a release, --memory-dir /path to use another data directory.

Claude Code plugin

In Claude Code:

/plugin marketplace add vbcherepanov/total-agent-memory
/plugin install total-agent-memory@vbcherepanov

Installs the MCP server, the memory-protocol skill and the seven capture hooks. It reuses an existing install if it finds one.

Directory plugin: Claude Code, Cowork and Codex

A small separate repository, total-agent-memory-plugin, packages the server for plugin directories. It starts the pinned release with uvx total-agent-memory==14.8.0 and adds the memory-protocol skill. It has no hooks and needs uv.

In Claude Code or Cowork:

/plugin marketplace add vbcherepanov/total-agent-memory-plugin
/plugin install total-agent-memory@vbcherepanov

In Codex CLI:

codex plugin marketplace add vbcherepanov/total-agent-memory-plugin
codex plugin add total-agent-memory@vbcherepanov

Data goes to ~/.tam/, so Claude Code and Codex share one memory. Use either this plugin or the Claude Code plugin above, not both.

pipx, pip and uv

pipx install total-agent-memory     # isolated, puts the commands on PATH
uvx total-agent-memory              # one-off run without installing
pip install total-agent-memory      # into the current virtual environment

These install the commands total-agent-memory and its short alias tam (the MCP server), lookup-memory / tam-lookup (terminal search), and tam-team / tam-remote (the team server and its client bridge). They do not configure any client; add the server to your client yourself.

The reranker is optional. A base install is about 113 MB of wheels with no PyTorch. The CrossEncoder reranker pulls in PyTorch (about 3 GB on Linux with CUDA wheels), so it is a separate extra that the default fast mode does not use:

pip install "total-agent-memory[rerank]"

Turn it on with MEMORY_MODE=deep or MEMORY_RERANK_ENABLED=true.

Homebrew

brew install vbcherepanov/tap/total-memory

Installs the same commands (total-agent-memory, tam, lookup-memory, tam-lookup, tam-team, tam-remote) into Homebrew’s prefix. Configure your client to run total-agent-memory.

Docker

Single container, multi-architecture (linux/amd64 and linux/arm64):

docker run -p 37737:37737 -v ~/.tam:/data ghcr.io/vbcherepanov/total-agent-memory:14.8.0

The dashboard is on port 37737 and your data stays in ~/.tam on the host.

Full local stack with Docker Compose (MCP over HTTP, dashboard, Ollama, reflection worker and scheduler):

git clone https://github.com/vbcherepanov/total-agent-memory.git
cd total-agent-memory
bash install-docker.sh --with-compose

Service	Role	Exposed on
mcp	MCP server over HTTP	127.0.0.1:3737/mcp
dashboard	Web UI	127.0.0.1:37737
ollama	Local LLM runtime	127.0.0.1:11434
reflection	Background queue worker	internal
scheduler	Periodic jobs	internal

The first start downloads qwen2.5-coder:7b (about 4.7 GB) and nomic-embed-text, so expect 5–10 minutes. Docker Desktop on macOS cannot use the Mac GPU; the native install is faster on a Mac. To use a model server outside the stack, add -f docker-compose.external.yml (see Configuration).

Clone and install script

git clone https://github.com/vbcherepanov/total-agent-memory.git ~/total-agent-memory
cd ~/total-agent-memory
bash install.sh --ide claude-code

--ide accepts claude-code, claude-desktop, codex, cursor, cline, continue, aider, windsurf, gemini-cli and opencode. You can run it again with another --ide; the database and environment are shared.

The script creates .venv, installs dependencies, downloads the embedding model, registers the MCP server as memory in each client’s own config file (for Claude Code, ~/.claude.json), copies the hooks into ~/.claude/hooks/, installs the background services for your OS, applies database migrations and starts the dashboard.

On Windows (PowerShell 5.1+):

git clone https://github.com/vbcherepanov/total-agent-memory.git $HOME\total-agent-memory
cd $HOME\total-agent-memory
powershell -ExecutionPolicy Bypass -File install.ps1 -Ide claude-code

WSL2: if your client runs on Windows but TAM runs inside WSL, the MCP command must be wsl with -e and the Linux paths as arguments. If the client runs inside WSL, configure it like native Linux. For systemd user services inside WSL2, enable [boot] systemd=true in /etc/wsl.conf, then wsl --shutdown.

Health check and removal:

bash scripts/diagnose.sh        # prints OK/FAIL per subsystem; exit code 0 = healthy
./install.sh --uninstall        # removes services and hook registrations, keeps your database

Optional: Ollama

Everything works without a language model. With Ollama running locally, background enrichment can add summaries, keywords and entity links to your records:

ollama pull qwen2.5-coder:7b

Then set MEMORY_MODE=balanced (or MEMORY_ENRICHMENT_ENABLED=true). Cloud providers (OpenAI, Anthropic, any OpenAI-compatible endpoint) are also supported; see Configuration and Privacy first.