Troubleshooting

First, run the health check

Installed with	Command
npx	npx -y total-agent-memory status and npx -y total-agent-memory doctor
install.sh (clone)	bash scripts/diagnose.sh (Windows: .\scripts\diagnose.ps1)
pipx / pip / Homebrew	pip show total-agent-memory (or pipx list) for the installed version; then run the server directly, as in step 3 below

The server does not show up in my client

1. Restart the client completely. Most clients read MCP config only at startup.
2. Check the config file the installer wrote (see the table in Quick start). The command must be an absolute path that exists. Claude Desktop in particular does not expand ~.
3. Run the command yourself. Copy the command from the config and run it in a terminal. It should start and wait silently for input (it speaks MCP over stdin). Press Ctrl+C to stop. An immediate error here is the real problem.
4. Claude Code: /mcp lists servers and their status. The entry is named total-agent-memory (npx, plugin) or memory (install.sh). Choose Reconnect after changes.
5. Two entries? If you used both install.sh and npx, you may have memory and total-agent-memory pointing at different environments. Keep one.

”Python not found” or wrong Python version

TAM needs Python 3.11+. Check with python3 --version. On macOS, brew install python@3.12; on Ubuntu, sudo apt install python3.12 python3.12-venv. With uv installed, the npx installer uses it and installs faster.

First save or search is slow

The first call downloads and loads the embedding model (about 90–220 MB, once). Later calls are fast. To preload, ask the agent to run memory_warmup.

Search returns nothing I know I saved

• Wrong project. A search with project="my-api" does not see records saved to general. Try without project.
• Hidden tags. Records tagged recovery or auto-extract are excluded by default.
• Just saved? Records are searchable immediately; graph links and enrichment arrive later in the background.
• Why this ranking? memory_explain_search shows how each retrieval stage scored the results.
• After changing the embedding model, rebuild vectors: memory_rebuild_embeddings, or python src/reembed.py --fastembed from a clone.

Dashboard does not open (127.0.0.1:37737)

• npx installs: npx -y total-agent-memory dashboard status, then dashboard restart or dashboard logs.
• Port taken: set DASHBOARD_PORT (for install.sh: DASHBOARD_PORT=37800 ./install.sh --ide claude-code).
• macOS: launchctl list | grep -i memory. Linux: systemctl --user status on the dashboard unit. Windows: Task Scheduler.

Ollama features do nothing

Without an LLM, TAM works fully for saving and searching. For enrichment:

curl http://127.0.0.1:11434/api/tags     # should list your models
ollama pull qwen2.5-coder:7b

Then set MEMORY_MODE=balanced or MEMORY_ENRICHMENT_ENABLED=true and restart. In Docker, localhost is the container itself: point OLLAMA_URL at an address the container can reach, such as http://host.docker.internal:11434.

On CPU-only machines, if LLM calls keep timing out, lower MEMORY_TRIPLE_MAX_PREDICT before raising timeouts.

High CPU

Embedding and optional PyTorch models use one compute thread by default (MEMORY_EMBED_THREADS=1, MEMORY_TORCH_THREADS=1). If CPU stays high, check whether background enrichment is on (MEMORY_MODE=balanced or deep) and whether an Ollama model is running. fast mode makes no LLM calls.

WSL2

• If the client runs on Windows and TAM inside WSL, the MCP command must be wsl with -e and Linux paths.
• Keep the data directory on the Linux filesystem, not under /mnt/c/; SQLite over that bridge is very slow.
• No systemd in WSL: add [boot] systemd=true to /etc/wsl.conf, run wsl --shutdown, then reinstall the services.

Still stuck

Open an issue on GitHub with your OS, install method, TAM version (from npx -y total-agent-memory status or pip show total-agent-memory) and the error text. Remove anything private from logs first.