opencode
opencode is the recommended MCP client for llm-mem. It’s an open-source terminal UI for AI coding assistants with first-class MCP support.
1. Install opencode
Follow the opencode install instructions. The quick version:
# macOS / Linux
curl -fsSL https://opencode.ai/install | bash
# Or via Homebrew
brew install opencode
# Or via npm
npm install -g @opencode/cli
2. Locate your opencode.json
opencode reads a config from one of two places:
- Project-local:
<your-project>/opencode.json— only affects this project - Global:
~/.config/opencode/config.json— affects every project
For a project-local config (most common for code work):
cd /path/to/your/project
touch opencode.json
For a global config:
mkdir -p ~/.config/opencode
touch ~/.config/opencode/config.json
3. Add llm-mem
Edit the file you created. The minimum configuration:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"llm-mem": {
"type": "local",
"command": ["/absolute/path/to/llm-mem-mcp"],
"enabled": true
}
}
}
If you installed the AppImage
{
"mcp": {
"llm-mem": {
"type": "local",
"command": ["/home/you/apps/llm-mem-mcp-x86_64.AppImage"],
"enabled": true
}
}
}
Make the AppImage executable first:
chmod +x /home/you/apps/llm-mem-mcp-x86_64.AppImage
If you built from source
{
"mcp": {
"llm-mem": {
"type": "local",
"command": ["/home/you/projects/llm-mem/target/release/llm-mem-mcp"],
"enabled": true
}
}
}
If you have multiple memory banks
You can declare multiple llm-mem instances, one per bank:
{
"mcp": {
"llm-mem-default": {
"type": "local",
"command": ["/path/to/llm-mem-mcp"],
"enabled": true
},
"llm-mem-research": {
"type": "local",
"command": ["/path/to/llm-mem-mcp"],
"args": ["--config", "/path/to/research-config.toml"],
"enabled": true
}
}
}
The first one is the default; the second uses a separate config that points to a different banks_dir.
4. Add env vars (optional)
Common additions:
{
"mcp": {
"llm-mem": {
"type": "local",
"command": ["/path/to/llm-mem-mcp"],
"enabled": true,
"env": {
"LLM_MEM_MODELS_DIR": "/home/you/.cache/llm-mem/models",
"RUST_LOG": "info"
}
}
}
}
See Environment variables for the full list.
5. Restart opencode and verify
opencode
The first MCP handshake can take 10-30 seconds (model download on first run). Watch the status indicator — when it turns green, the server is ready.
In opencode, run:
/tools
You should see 32 llm-mem tools listed. Try:
> Call system_status with llm-mem
If the response includes "backend": "local" and "llm_available": true, the connection is working.
6. Use it
From here on, the AI automatically has access to the llm-mem tools. You can just talk normally:
Remember that the AuthService refresh tokens expire after 7 days. What did I store about authentication? Upload docs/architecture.md to memory. Show me what I stored this week.
The AI decides which tool to call based on your request.
Troubleshooting
If the server doesn’t start or opencode can’t reach it, see Troubleshooting MCP.
Common issues specific to opencode:
- Config not picked up: confirm the path with
opencode --print-configor check the opencode logs - Permission denied on AppImage:
chmod +xit - Server starts but no tools appear: check the opencode version supports MCP (>= 0.5.x)
- Stale config: restart opencode after every config change — it doesn’t hot-reload MCP servers
Next
- VS Code Copilot — alternative client
- Tools overview — what the AI can do with the connected server