Hybrid Local Memory in OpenClaw: BM25 + Vectors + sqlite-vec + Local Embeddings

OpenClaw “memory” isn’t a mysterious model feature—it’s a set of Markdown files you own (MEMORY.md plus daily notes in memory/YYYY-MM-DD.md) plus a retrieval layer that helps the agent find the right snippet at the right time. ClawSetup’s Basic Setup configures this so recall stays reliable as your notes grow: exact keyword matches (config keys, IDs, error strings) still work, semantic matches still work, and—where feasible—embeddings can be generated locally on your VPS.

What “memory” means in OpenClaw (source of truth matters)

The biggest operational win is that OpenClaw’s long-term memory is plain text you can read, edit, and back up:

• MEMORY.md is curated “long-term” context (preferences, decisions, stable runbooks)
• memory/YYYY-MM-DD.md is daily scratchpad/logs

That means the agent can reboot, models can change, and context windows can reset—your memory still exists as normal files. The retrieval/index is an acceleration layer, not the source of truth.

Why “hybrid” retrieval (keyword + vector) beats “vector-only” for real ops work

In home-lab / VPS operations, a lot of the queries you want to answer are not poetic—they’re literal:

• “Where did we set memorySearch.provider?”
• “What did we decide about PR-only patterns?”
• “What’s the Hetzner firewall rule name?”
• “What was that cron job id?”

These queries contain exact tokens. Vector similarity is great for paraphrases (“how do we harden SSH?”), but it’s not optimized for exact-token lookups (config keys, IDs, filenames). That’s why a hybrid approach is operationally useful:

• Keyword search (BM25-style) for exact tokens and sparse terms
• Vectors (semantic similarity) for paraphrases and fuzzy matches

Practical implication: “find the exact line” and “find the concept” both work.

Where sqlite-vec fits

Vector search can be done in a few ways. The sqlite-vec extension lets OpenClaw store embeddings in SQLite and run vector distance queries inside the database (using a vec0 virtual table), rather than loading everything into memory and filtering in JavaScript.

In the Basic Setup, the goal isn’t to turn your VPS into an ML server—it’s to keep memory lookup:

• fast enough for day-to-day chat operations
• predictable as your notes grow
• simple to back up (SQLite + Markdown)

If sqlite-vec isn’t available on a given box, OpenClaw can fall back without hard failure; ClawSetup documents which mode you’re running.

Local embeddings: what “local” means (privacy + cost control)

“Local embeddings” means the text chunks used for indexing are embedded on your VPS.

Note: other parts of your setup (e.g., the chat model/provider) may still be remote depending on configuration.

The trade-off is that local embeddings use CPU/RAM/disk; the handoff should include sizing expectations and what to do if you later choose a remote provider.

Practical setup & verification steps

Commands can differ by OpenClaw version; run openclaw help or openclaw memory --help to confirm what’s available.

A pragmatic “does it work end-to-end?” checklist is:

1. Confirm memory subsystem status (if supported):

openclaw memory status

2. Force an index build (useful after big edits or first setup):

openclaw memory index

3. Validate both keyword and semantic queries:

openclaw memory search "memorySearch.provider"
openclaw memory search "how do we restrict telegram groups"
openclaw memory search "fail2ban sshd"

4. Make sure memory remains “file-first” operationally:

• edit MEMORY.md with your normal editor
• re-run openclaw memory search "<a line you added>"
• if you want immediate consistency, run openclaw memory index

What ClawSetup leaves behind for memory (deliverables)

A good Basic Setup handoff includes:

• A short “Memory architecture” page: Markdown source-of-truth + hybrid retrieval
• The chosen provider (local vs remote) + model identifier and config location
• Where the SQLite store lives (so it can be backed up or safely rebuilt)
• A tiny “How to verify memory” section with example commands