Quick start

New in 14.6.0 After installing, tam setup asks a few questions and connects your AI clients for you, with one review screen before it changes anything. See Setup wizard.

Before you start

You need:

• Python 3.11 or newer on your PATH (python3 --version). TAM itself is a Python program.
• Node.js 18 or newer if you use the one-command setup below (node --version). If you do not have Node, use another install method.
• About 2 GB of free disk for the program, the small embedding model it downloads on first use, and your memory database.

You do not need an API key, an account or a GPU.

The one-command setup creates everything under ~/.tam/: a private Python environment, your memory database ~/.tam/memory.db, logs, and two background helpers (a local dashboard on http://127.0.0.1:37737 and a reflection worker). Pass --no-services if you do not want the background helpers.

Claude Code

Option A: the plugin (from inside Claude Code). Type these two commands in a Claude Code session:

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

This installs the MCP server, the memory-protocol skill (which teaches Claude when to save and recall) and the capture hooks in one step. If TAM is already installed, the plugin reuses it.

Option B: one terminal command.

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

This installs TAM into ~/.tam (first run only) and registers the server as memory in ~/.claude.json.

Then:

1. Restart Claude Code.
2. Type /mcp. You should see memory as connected. (Installs made with the npm wrapper before 1.9.0 used the name total-agent-memory.)
3. Try it: “Remember that our staging database is on port 5433.” Then open a new session and ask “Which port is staging on?”

Codex CLI

npx -y total-agent-memory connect codex

This writes a marked block (# --- total-agent-memory MCP Server ---) with an [mcp_servers.memory] table into ~/.codex/config.toml (or $CODEX_HOME/config.toml). A hand-written [mcp_servers.memory] table outside that block is reported, not overwritten. Restart Codex and ask it to save something to test.

If you prefer to write it yourself:

[mcp_servers.memory]
command = "/Users/you/.tam/.venv/bin/total-agent-memory"
args = []
env = { MEMORY_MODE = "fast" }

Cursor

npx -y total-agent-memory connect cursor

Writes the server into ~/.cursor/mcp.json. Restart Cursor, open Settings → MCP and check that memory is enabled.

Claude Desktop

New in 14.6.0 Claude Desktop is connected like the others:

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

This writes the server into ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows, keeping anything already there. From a clone, ./install.sh --ide claude-desktop (or install.ps1 -Ide claude-desktop) does the same. Quit and reopen Claude Desktop; the tools appear under the tools icon in a new chat.

To add it by hand (for example with a pipx or Homebrew install, where which total-agent-memory gives the path), open Settings → Developer → Edit Config and add the server under mcpServers. Claude Desktop does not expand ~, so write the full path:

{
  "mcpServers": {
    "memory": {
      "command": "/Users/you/.tam/.venv/bin/total-agent-memory",
      "args": [],
      "env": { "MEMORY_MODE": "fast" }
    }
  }
}

On Windows the npx install puts the server at %USERPROFILE%\.tam\.venv\Scripts\total-agent-memory.exe.

Other clients

The same connect command wires these clients:

Client	Command	Config file it writes
Cline	npx -y total-agent-memory connect cline	cline_mcp_settings.json in VS Code’s global storage for Cline
Continue	npx -y total-agent-memory connect continue	~/.continue/mcpServers/memory.yaml
Windsurf	npx -y total-agent-memory connect windsurf	~/.codeium/windsurf/mcp_config.json
Gemini CLI	npx -y total-agent-memory connect gemini-cli	~/.gemini/settings.json
OpenCode	npx -y total-agent-memory connect opencode	~/.config/opencode/opencode.json (OpenCode’s mcp format)
Aider	npx -y total-agent-memory connect aider	a marked read: block in ~/.aider.conf.yml so Aider reads the memory skill; Aider has no MCP, so search with lookup-memory

Since 14.6.0 (npm wrapper 1.9.0) every installer registers clients through the same code as tam setup, which parses each config file before writing and stops, changing nothing, if one does not parse. Earlier versions wrote some clients into files those clients never read; if the first start logs misplaced files, run tam setup --reconfigure.

Any other MCP client works too: point it at the total-agent-memory command using the JSON shown for Claude Desktop.

Aider and scripts. The lookup-memory command searches memory from a terminal, so any tool that can run a shell command can read memory. With the npx install it lives in ~/.tam/.venv/bin/; pipx and Homebrew put it on your PATH.

~/.tam/.venv/bin/lookup-memory "why did we pick pgvector"

Check that it works

npx -y total-agent-memory status

This prints install paths, database size, the status of the background helpers and whether the dashboard answers. Open http://127.0.0.1:37737 to browse what has been saved.

Inside any connected client you can also ask the agent to run memory_stats. A fresh install reports zero records; after your first save the count goes up.

Next steps

• Build the habits that make memory useful: Your first day.
• Using several clients? They share one database, so something saved in Claude Code can be recalled in Cursor.
• Something did not connect? See Troubleshooting.