chore: import upstream snapshot with attribution

2026-07-13 13:38:09 +08:00
commit 15dadb5432
263 changed files with 88651 additions and 0 deletions
@@ -0,0 +1,166 @@
+# 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.