startrail-org--leann/docs/openclaw-setup.md

OpenClaw + LEANN Setup Guide

Two ways to connect LEANN to your OpenClaw agent: MCP server (recommended) or ClawHub skill.

---

Option A: MCP Server (Recommended)

OpenClaw natively supports MCP tools. LEANN ships an MCP server that exposes leann_search and leann_list as tools your agent can call directly.

1. Install LEANN

pip install leann-core
# or
uv tool install leann-core --with leann

2. Build an index on your memory files

Using Ollama embeddings (recommended if you already run Ollama):

leann build openclaw-memory \
  --docs ~/.openclaw/workspace/MEMORY.md ~/.openclaw/workspace/memory/ \
  --embedding-mode ollama \
  --embedding-model nomic-embed-text

Or using local sentence-transformers (no Ollama required):

leann build openclaw-memory \
  --docs ~/.openclaw/workspace/MEMORY.md ~/.openclaw/workspace/memory/ \
  --embedding-mode sentence-transformers \
  --embedding-model all-MiniLM-L6-v2

Add extra directories if you have them:

leann build openclaw-memory \
  --docs ~/.openclaw/workspace/MEMORY.md \
        ~/.openclaw/workspace/memory/ \
        ~/Documents/notes/ \
  --embedding-mode ollama \
  --embedding-model nomic-embed-text

3. Register the MCP server with OpenClaw

Add to ~/.openclaw/openclaw.json:

{
  // ... your existing config ...
  "mcpServers": {
    "leann": {
      "command": "leann_mcp",
      "args": [],
      "env": {}
    }
  }
}

4. Use it

Ask your agent:

• "Search my memories for database decisions"
• "What did we decide about the API design?"
• "Find my notes on deployment"

The agent will call leann_search via MCP and return structured results.

5. Keep the index fresh

# Re-run build (idempotent — only processes changed files)
leann build openclaw-memory \
  --docs ~/.openclaw/workspace/MEMORY.md ~/.openclaw/workspace/memory/

# Or use watch mode for continuous auto-sync
leann watch openclaw-memory --interval 30

---

Option B: ClawHub Skill

If you prefer the skill-based approach:

clawhub install leann-team/leann-memory

Or copy skills/leann-memory/ from this repo to ~/.openclaw/workspace/skills/leann-memory/.

The skill tells your agent how to call leann search via shell commands. Setup steps (install + build index) are the same as above.

---

Important: Ollama Configuration

If you use Ollama as your OpenClaw model provider, make sure your ~/.openclaw/openclaw.json uses the native Ollama API — not the OpenAI-compatible endpoint:

{
  "models": {
    "providers": {
      "ollama": {
        "baseUrl": "http://127.0.0.1:11434",  // no /v1 suffix
        "apiKey": "ollama-local",
        "api": "ollama"  // NOT "openai-completions" or "openai-responses"
      }
    }
  }
}

Using "openai-completions" or "openai-responses" silently breaks tool calling — the model outputs tool calls as plain text instead of structured tool_calls. See astral-sh/ty#21243.

---

Storage Comparison

Scenario	Default memory-core	LEANN
1 year daily logs (~12K chunks)	~23 MB	~0.7 MB
+ session transcripts (~100K chunks)	~190 MB	~6 MB
+ 10 GB indexed documents (~500K chunks)	~950 MB	~30 MB

All numbers assume 384-dimensional embeddings (all-MiniLM-L6-v2 or nomic-embed-text).

---

Troubleshooting

"leann: command not found" Ensure LEANN is on your PATH. If installed via uv tool install, run uv tool update-shell and restart your terminal.

"Index not found" Run leann list to see available indexes. Build one first with leann build.

Slow first search The first query loads the embedding model (~90 MB). Subsequent queries reuse the warm daemon and are fast (~0.5s). Use leann warmup openclaw-memory to pre-warm.

Memory files changed but search results are stale Re-run leann build openclaw-memory --docs ... — it detects changes automatically and only re-indexes what changed.

Agent doesn't use LEANN tools Make sure your Ollama model supports tool calling (e.g. qwen3:8b or larger). Smaller models like qwen3:4b may not reliably invoke tools.