vilvona 1.0.0

package/docs/concepts/memory-qmd.md

@@ -0,0 +1,277 @@
+---
+summary: "Local-first search sidecar with BM25, vectors, reranking, and query expansion"
+title: "QMD memory engine"
+read_when:
+  - You want to set up QMD as your memory backend
+  - You want advanced memory features like reranking or extra indexed paths
+---
+
+[QMD](https://github.com/tobi/qmd) is a local-first search sidecar that runs
+alongside OpenClaw. It combines BM25, vector search, and reranking in a single
+binary, and can index content beyond your workspace memory files.
+
+## What it adds over builtin
+
+- **Reranking and query expansion** for better recall.
+- **Index extra directories** -- project docs, team notes, anything on disk.
+- **Index session transcripts** -- recall earlier conversations.
+- **Fully local** -- runs with the official llama.cpp provider plugin and
+  auto-downloads GGUF models.
+- **Automatic fallback** -- if QMD is unavailable, OpenClaw falls back to the
+  builtin engine seamlessly.
+
+## Getting started
+
+### Prerequisites
+
+- Install QMD: `npm install -g @tobilu/qmd` or `bun install -g @tobilu/qmd`
+- SQLite build that allows extensions (`brew install sqlite` on macOS).
+- QMD must be on the gateway's `PATH`.
+- macOS and Linux work out of the box. Windows is best supported via WSL2.
+
+### Enable
+
+```json5
+{
+  memory: {
+    backend: "qmd",
+  },
+}
+```
+
+OpenClaw creates a self-contained QMD home under
+`~/.openclaw/agents/<agentId>/qmd/` and manages the sidecar lifecycle
+automatically -- collections, updates, and embedding runs are handled for you.
+It prefers current QMD collection and MCP query shapes, but still falls back to
+alternate collection pattern flags and older MCP tool names when needed.
+Boot-time reconciliation also recreates stale managed collections back to their
+canonical patterns when an older QMD collection with the same name is still
+present.
+
+## How the sidecar works
+
+- OpenClaw creates collections from your workspace memory files and any
+  configured `memory.qmd.paths`, then runs `qmd update` when the QMD manager is
+  opened and periodically afterward (default every 5 minutes). These refreshes
+  run through QMD subprocesses, not an in-process filesystem crawl. Semantic
+  modes also run `qmd embed`.
+- The default workspace collection tracks `MEMORY.md` plus the `memory/`
+  tree. Lowercase `memory.md` is not indexed as a root memory file.
+- QMD's own scanner ignores hidden paths and common dependency/build
+  directories such as `.git`, `.cache`, `node_modules`, `vendor`, `dist`, and
+  `build`. Gateway startup does not initialize QMD by default, so cold boot
+  avoids importing the memory runtime or creating the long-lived watcher before
+  memory is first used.
+- If you want QMD initialized at gateway start anyway, set
+  `memory.qmd.update.startup` to `idle` or `immediate`. With
+  `memory.qmd.update.onBoot: true`, startup runs the initial refresh. With
+  `onBoot: false`, startup skips that immediate refresh but still opens the
+  long-lived manager when update or embed intervals are configured, so QMD can
+  own its regular watcher and timers.
+- Searches use the configured `searchMode` (default: `search`; also supports
+  `vsearch` and `query`). `search` is BM25-only, so OpenClaw skips semantic
+  vector readiness probes and embedding maintenance in that mode. If a mode
+  fails, OpenClaw retries with `qmd query`.
+- When `searchMode` is `query`, set `memory.qmd.rerank` to `false` to use QMD's
+  hybrid query path without the reranker. OpenClaw passes `--no-rerank` to the
+  direct QMD CLI path and `rerank: false` to QMD's MCP query tool. This option
+  requires QMD 2.1 or newer.
+- With QMD releases that advertise multi-collection filters, OpenClaw groups
+  same-source collections into one QMD search invocation. Older QMD releases
+  keep the compatible per-collection fallback.
+- If QMD fails entirely, OpenClaw falls back to the builtin SQLite engine.
+  Repeated chat-turn attempts back off briefly after an open failure so a
+  missing binary or broken sidecar dependency does not create a retry storm;
+  `openclaw memory status` and one-shot CLI probes still recheck QMD directly.
+
+<Info>
+The first search may be slow -- QMD auto-downloads GGUF models (~2 GB) for
+reranking and query expansion on the first `qmd query` run.
+</Info>
+
+## Search performance and compatibility
+
+OpenClaw keeps the QMD search path compatible with both current and older QMD
+installs.
+
+On startup, OpenClaw checks the installed QMD help text once per manager. If the
+binary advertises support for multiple collection filters, OpenClaw searches all
+same-source collections with one command:
+
+```bash
+qmd search "router notes" --json -n 10 -c memory-root-main -c memory-dir-main
+```
+
+This avoids starting one QMD subprocess for every durable-memory collection.
+Session transcript collections stay in their own source group, so mixed
+`memory` + `sessions` searches still give the result diversifier input from both
+sources.
+
+Older QMD builds only accept one collection filter. When OpenClaw detects one
+of those builds, it keeps the compatibility path and searches each collection
+separately before merging and deduplicating results.
+
+To inspect the installed contract manually, run:
+
+```bash
+qmd --help | grep -i collection
+```
+
+Current QMD help says collection filters can target one or more collections.
+Older help usually describes a single collection.
+
+## Model overrides
+
+QMD model environment variables pass through unchanged from the gateway
+process, so you can tune QMD globally without adding new OpenClaw config:
+
+```bash
+export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
+export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
+export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
+```
+
+After changing the embedding model, rerun embeddings so the index matches the
+new vector space.
+
+## Indexing extra paths
+
+Point QMD at additional directories to make them searchable:
+
+```json5
+{
+  memory: {
+    backend: "qmd",
+    qmd: {
+      paths: [{ name: "docs", path: "~/notes", pattern: "**/*.md" }],
+    },
+  },
+}
+```
+
+Snippets from extra paths appear as `qmd/<collection>/<relative-path>` in
+search results. `memory_get` understands this prefix and reads from the correct
+collection root.
+
+## Indexing session transcripts
+
+Enable session indexing to recall earlier conversations:
+
+```json5
+{
+  memory: {
+    backend: "qmd",
+    qmd: {
+      sessions: { enabled: true },
+    },
+  },
+}
+```
+
+Transcripts are exported as sanitized User/Assistant turns into a dedicated QMD
+collection under `~/.openclaw/agents/<id>/qmd/sessions/`.
+
+## Search scope
+
+By default, QMD search results are surfaced in direct and channel sessions
+(not groups). Configure `memory.qmd.scope` to change this:
+
+```json5
+{
+  memory: {
+    qmd: {
+      scope: {
+        default: "deny",
+        rules: [{ action: "allow", match: { chatType: "direct" } }],
+      },
+    },
+  },
+}
+```
+
+When scope denies a search, OpenClaw logs a warning with the derived channel and
+chat type so empty results are easier to debug.
+
+## Citations
+
+When `memory.citations` is `auto` or `on`, search snippets include a
+`Source: <path#line>` footer. Set `memory.citations = "off"` to omit the footer
+while still passing the path to the agent internally.
+
+## When to use
+
+Choose QMD when you need:
+
+- Reranking for higher-quality results.
+- To search project docs or notes outside the workspace.
+- To recall past session conversations.
+- Fully local search with no API keys.
+
+For simpler setups, the [builtin engine](/concepts/memory-builtin) works well
+with no extra dependencies.
+
+## Troubleshooting
+
+**QMD not found?** Ensure the binary is on the gateway's `PATH`. If OpenClaw
+runs as a service, create a symlink:
+`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`.
+
+If `qmd --version` works in your shell but OpenClaw still reports
+`spawn qmd ENOENT`, the gateway process likely has a different `PATH` than your
+interactive shell. Pin the binary explicitly:
+
+```json5
+{
+  memory: {
+    backend: "qmd",
+    qmd: {
+      command: "/absolute/path/to/qmd",
+    },
+  },
+}
+```
+
+Use `command -v qmd` in the environment where QMD is installed, then recheck
+with `openclaw memory status --deep`.
+
+**First search very slow?** QMD downloads GGUF models on first use. Pre-warm
+with `qmd query "test"` using the same XDG dirs OpenClaw uses.
+
+**Many QMD subprocesses during search?** Update QMD if possible. OpenClaw uses
+one process for same-source multi-collection searches only when the installed
+QMD advertises support for multiple `-c` filters; otherwise it keeps the older
+per-collection fallback for correctness.
+
+**BM25-only QMD still trying to build llama.cpp?** Set
+`memory.qmd.searchMode = "search"`. OpenClaw treats that mode as lexical-only,
+does not run QMD vector status probes or embedding maintenance, and leaves
+semantic readiness checks to `vsearch` or `query` setups.
+
+**Search times out?** Increase `memory.qmd.limits.timeoutMs` (default: 4000ms).
+Set to `120000` for slower hardware.
+
+**Empty results in group chats?** Check `memory.qmd.scope` -- the default only
+allows direct and channel sessions.
+
+**Root memory search suddenly got too broad?** Restart the gateway or wait for
+the next startup reconciliation. OpenClaw recreates stale managed collections
+back to canonical `MEMORY.md` and `memory/` patterns when it detects a same-name
+conflict.
+
+**Workspace-visible temp repos causing `ENAMETOOLONG` or broken indexing?**
+QMD traversal currently follows the underlying QMD scanner behavior rather than
+OpenClaw's builtin symlink rules. Keep temporary monorepo checkouts under
+hidden directories like `.tmp/` or outside indexed QMD roots until QMD exposes
+cycle-safe traversal or explicit exclusion controls.
+
+## Configuration
+
+For the full config surface (`memory.qmd.*`), search modes, update intervals,
+scope rules, and all other knobs, see the
+[Memory configuration reference](/reference/memory-config).
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Builtin memory engine](/concepts/memory-builtin)
+- [Honcho memory](/concepts/memory-honcho)

package/docs/concepts/memory-search.md

@@ -0,0 +1,175 @@
+---
+summary: "How memory search finds relevant notes using embeddings and hybrid retrieval"
+title: "Memory search"
+read_when:
+  - You want to understand how memory_search works
+  - You want to choose an embedding provider
+  - You want to tune search quality
+---
+
+`memory_search` finds relevant notes from your memory files, even when the
+wording differs from the original text. It works by indexing memory into small
+chunks and searching them using embeddings, keywords, or both.
+
+## Quick start
+
+Memory search uses OpenAI embeddings by default. To use another embedding
+backend, set a provider explicitly:
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        provider: "openai", // or "gemini", "local", "ollama", "openai-compatible", etc.
+      },
+    },
+  },
+}
+```
+
+For multi-endpoint setups with memory-specific providers, `provider` can also
+be a custom `models.providers.<id>` entry, such as `ollama-5080`, when that
+provider sets `api: "ollama"` or another memory embedding adapter owner.
+
+For local embeddings with no API key, install
+`@openclaw/llama-cpp-provider` and set `provider: "local"`. Source checkouts
+may still require native build approval: `pnpm approve-builds` then
+`pnpm rebuild node-llama-cpp`.
+
+Some OpenAI-compatible embedding endpoints require asymmetric labels such as
+`input_type: "query"` for searches and `input_type: "document"` or `"passage"`
+for indexed chunks. Configure those with `memorySearch.queryInputType` and
+`memorySearch.documentInputType`; see the [Memory configuration reference](/reference/memory-config#provider-specific-config).
+
+## Supported providers
+
+| Provider          | ID                  | Needs API key | Notes                         |
+| ----------------- | ------------------- | ------------- | ----------------------------- |
+| Bedrock           | `bedrock`           | No            | Uses AWS credential chain     |
+| DeepInfra         | `deepinfra`         | Yes           | Default: `BAAI/bge-m3`        |
+| Gemini            | `gemini`            | Yes           | Supports image/audio indexing |
+| GitHub Copilot    | `github-copilot`    | No            | Uses Copilot subscription     |
+| Local             | `local`             | No            | GGUF model, ~0.6 GB download  |
+| Mistral           | `mistral`           | Yes           |                               |
+| Ollama            | `ollama`            | No            | Local/self-hosted             |
+| OpenAI            | `openai`            | Yes           | Default                       |
+| OpenAI-compatible | `openai-compatible` | Usually       | Generic `/v1/embeddings`      |
+| Voyage            | `voyage`            | Yes           |                               |
+
+## How search works
+
+OpenClaw runs two retrieval paths in parallel and merges the results:
+
+```mermaid
+flowchart LR
+    Q["Query"] --> E["Embedding"]
+    Q --> T["Tokenize"]
+    E --> VS["Vector Search"]
+    T --> BM["BM25 Search"]
+    VS --> M["Weighted Merge"]
+    BM --> M
+    M --> R["Top Results"]
+```
+
+- **Vector search** finds notes with similar meaning ("gateway host" matches
+  "the machine running OpenClaw").
+- **BM25 keyword search** finds exact matches (IDs, error strings, config
+  keys).
+
+If only one path is available, the other runs alone. Intentional FTS-only mode
+(`provider: "none"`) and automatic/default provider selection can still use
+lexical ranking when embeddings are unavailable.
+
+Explicit non-local embedding providers are different. If you set
+`memorySearch.provider` to a concrete remote-backed provider and that provider
+is unavailable at runtime, `memory_search` reports memory as unavailable instead
+of silently using FTS-only results. This keeps a broken configured semantic
+provider visible. Set `provider: "none"` for deliberate FTS-only recall, or fix
+the provider/auth configuration to restore semantic ranking.
+
+## Improving search quality
+
+Two optional features help when you have a large note history:
+
+### Temporal decay
+
+Old notes gradually lose ranking weight so recent information surfaces first.
+With the default half-life of 30 days, a note from last month scores at 50% of
+its original weight. Evergreen files like `MEMORY.md` are never decayed.
+
+<Tip>
+Enable temporal decay if your agent has months of daily notes and stale
+information keeps outranking recent context.
+</Tip>
+
+### MMR (diversity)
+
+Reduces redundant results. If five notes all mention the same router config, MMR
+ensures the top results cover different topics instead of repeating.
+
+<Tip>
+Enable MMR if `memory_search` keeps returning near-duplicate snippets from
+different daily notes.
+</Tip>
+
+### Enable both
+
+```json5
+{
+  agents: {
+    defaults: {
+      memorySearch: {
+        query: {
+          hybrid: {
+            mmr: { enabled: true },
+            temporalDecay: { enabled: true },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+## Multimodal memory
+
+With Gemini Embedding 2, you can index images and audio files alongside
+Markdown. Search queries remain text, but they match against visual and audio
+content. See the [Memory configuration reference](/reference/memory-config) for
+setup.
+
+## Session memory search
+
+You can optionally index session transcripts so `memory_search` can recall
+earlier conversations. This is opt-in via
+`memorySearch.experimental.sessionMemory`. See the
+[configuration reference](/reference/memory-config) for details.
+
+## Troubleshooting
+
+**No results?** Run `openclaw memory status` to check the index. If empty, run
+`openclaw memory index --force`.
+
+**Only keyword matches?** Your embedding provider may not be configured. Check
+`openclaw memory status --deep`.
+
+**Local embeddings time out?** `ollama`, `lmstudio`, and `local` use a longer
+inline batch timeout by default. If the host is simply slow, set
+`agents.defaults.memorySearch.sync.embeddingBatchTimeoutSeconds` and rerun
+`openclaw memory index --force`.
+
+**CJK text not found?** Rebuild the FTS index with
+`openclaw memory index --force`.
+
+## Further reading
+
+- [Active Memory](/concepts/active-memory) -- sub-agent memory for interactive chat sessions
+- [Memory](/concepts/memory) -- file layout, backends, tools
+- [Memory configuration reference](/reference/memory-config) -- all config knobs
+
+## Related
+
+- [Memory overview](/concepts/memory)
+- [Active memory](/concepts/active-memory)
+- [Builtin memory engine](/concepts/memory-builtin)