Troubleshooting¶

Most problems come down to the daemon, a port clash, or an agent that was not restarted after wiring. Start here, then run pmb doctor for a full check.

First step: run the doctor¶

pmb doctor

It checks the install, the MCP wiring, and the runtime state, and points at what is wrong. Add --remote user@host:/path to print an SSH-tunneled MCP snippet for a remote daemon.

The agent does not seem to use memory¶

Restart the agent after pmb setup or pmb connect. Hosts read their MCP and rules config at startup, so changes only take effect on the next launch.
Confirm the wiring with pmb doctor, and that memory exists with pmb stats.
Remember how each host receives memory: Claude Code uses lifecycle hooks, while Cursor, Zed, VS Code, Windsurf, Gemini, and Continue call PMB as MCP tools when their installed rules say memory is relevant. See Usage.

The dashboard and daemon fight over a port¶

Both default to 127.0.0.1:8765. If you run them at once, give the dashboard a different port:

pmb dashboard --port 18888

The daemon is not warm, or processes piled up¶

pmb daemon status      # is the daemon up and warm?
pmb daemon restart     # restart it, for example after changing the model
pmb daemon kill-all    # stop the daemon and every stray PMB process, then reset

pmb daemon kill-all is the reset button: if duplicate warm processes pile up and slow your machine, it stops all of them and clears the registry so you can start fresh with pmb daemon start.

The first recall is slow¶

The slow part is loading the embedding model. Warm it once so the next recall is instant:

pmb warmup

The shared daemon keeps it warm after that. If no daemon is running, a cold hook answers from an in-process engine and asks a daemon to start in the background, so the following message is warm.

Recall returns nothing for a topic you know is there¶

The precision gates keep the read path quiet, so a vague or conversational query surfaces nothing rather than a weak match. Query it directly and inspect the ranking:

pmb recall "your query"
pmb why "your query"      # which ranking rules fired, and each multiplier

Recall is weak in another language¶

Recall works in any language on day one, but exact top-1 is weaker for CJK and a few lower-resource languages. Switch to a stronger multilingual embedder:

pmb config set embedding.model BAAI/bge-m3
pmb reindex
pmb daemon restart

See Adding a language for the details.

Changing the model did not take effect¶

Switching the embedder needs a re-embed. Use the one-step command instead of editing config by hand:

pmb model            # download, re-embed memory, and restart the daemon

Ollama problems¶

For a fully offline LLM backend, see the dedicated Ollama page, which covers status checks, model presets, and remote hosts.