wehub-resource-sync
167 lines
4.1 KiB
Markdown
167 lines
4.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```json5
|
|
{
|
|
// ... 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json5
|
|
{
|
|
"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](https://github.com/openclaw/openclaw/issues/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.
|