Troubleshooting MCP
Common issues when connecting an MCP client to llm-mem-mcp.
Server doesn’t start
Symptom: Client shows the server as “failed” or “not connected”. Log file (if logging.enabled = true) shows an error.
Check:
- Absolute path:
commandmust be an absolute path, not a relative one or a~-expanded one. - Executable bit: AppImage needs
chmod +x. Native binaries usually don’t. - Run it manually: try
./llm-mem-mcp --versionfrom a terminal. If that fails, the binary itself is broken. - Missing libraries: on Linux, run
ldd /path/to/llm-mem-mcpto check for missing.sofiles. On macOS, useotool -L. On Windows, use Dependencies (https://lucasg.github.io/Dependencies/). - AppImage + no FUSE: add
"env": {"APPIMAGE_EXTRACT_AND_RUN": "1"}to the MCP config.
Server starts but no tools appear
Check:
- MCP version mismatch: confirm your client supports MCP. opencode 0.5+, VS Code 1.85+, Claude Code 1.0+.
- Restart the client: MCP server lists are loaded at startup, not hot-reloaded.
- Check stderr: the server logs to stderr. With
logging.enabled = true, also check the log file. Look for JSON-RPC errors. - Try a different transport: llm-mem only supports stdio. If your client is trying HTTP/SSE, it won’t work.
Server starts, tools appear, but calls fail
Check:
system_statusfirst: ask the AI to call it. The response tells you if models are loaded, what backend is active, and whether the LLM/embedding are reachable.- Wait for model download: on first run, the server downloads ~3 GB of models. Until that’s done, most tools return errors. Watch the log file for “model loaded” messages.
- API key issues: if using the API backend, verify the key is set via
LLM_MEM_LLM_API_KEY(or in the config). The server validates at startup and will refuse to start without it. - Bank creation error: if the
banks_dirisn’t writable, the server fails to create the default bank. Check filesystem permissions and thebanks_dirsetting.
Performance is slow
Check:
- GPU not used: see GPU acceleration. CPU-only inference is 5-20x slower.
- First query is slow: model loading + warmup takes 5-30 seconds. Subsequent queries are fast.
- Concurrent requests: default
max_concurrent_requests = 1for stability. Bump it if you have a beefy machine. max_concurrent_requestsfor API backend: set to0(unlimited) if you have API rate-limit headroom.- Large bank: queries get slower as the bank grows past ~100k memories. Consider per-project banks.
Logs
The server logs to stderr. With logging.enabled = true, it also writes to a rotating log file under log_directory (default llm-mem-data/logs/).
To get more detail, set the RUST_LOG env var in the MCP config’s env block:
"env": {
"RUST_LOG": "info,llama_cpp_2=warn"
}
Useful levels:
| Value | What you get |
|---|---|
error | Only errors |
warn | Errors + warnings |
info (default) | Lifecycle events, request summaries |
debug | Per-request detail |
trace | Everything, including the LLM’s prompts |
See Logging & debugging for more.
Common error messages
Failed to resolve memory bank: ...
The bank name passed to the tool doesn’t exist and can’t be created. Check spelling. Banks are created on first write, not on first read.
LLM timeout after 120 seconds
The LLM is taking too long. Either:
- Increase
llm.llm_timeout_secsin the config - Switch to a smaller/faster model
- Enable GPU acceleration
- If using an API, the upstream is slow — try a different model or provider
No API key configured
You set provider = "api" but didn’t provide a key. Set LLM_MEM_LLM_API_KEY (or in the config), or change provider = "local".
Configuration Error: llm.context_size is too small
llm.context_size must be larger than memory.document_chunk_size / 2 + llm.max_tokens + 512. Increase context_size or decrease document_chunk_size.
Bank deletion requires user confirmation
You called cleanup_resources with target: "banks" but didn’t pass the exact confirmation phrase. This is a safety check — pass confirm: "I confirm this data will be permanently lost".
Still stuck?
- Run
llm-mem-mcp --generate-configto confirm the binary works - Run
llm-mem health-check --live(the CLI binary) to validate the config end-to-end - Check the GitHub issue tracker: https://github.com/vsndev3/llm-mem/issues
- Include the log output and your config (with secrets redacted) when asking for help