Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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-config or check the opencode logs
  • Permission denied on AppImage: chmod +x it
  • 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