clawmem 0.13.0 → 0.15.0

package/docs/guides/hermes-plugin.md

@@ -0,0 +1,187 @@
+# Hermes Agent MemoryProvider plugin
+
+ClawMem integrates with Hermes Agent as a native MemoryProvider plugin, giving Hermes agents the same persistent memory available to Claude Code and OpenClaw. All three runtimes share a single vault, so decisions captured in one are available in the others.
+
+## Install
+
+Hermes scans two directories for memory provider plugins (since Hermes #10529, in v2026.4.13+):
+
+1. **User plugins** at `$HERMES_HOME/plugins/<name>/` — typically `~/.hermes/plugins/<name>/`. **Preferred.** Survives `git pull` of hermes-agent and avoids the dual-registration trap that previously caused duplicate tool names with strict providers.
+2. **Bundled plugins** at `hermes-agent/plugins/memory/<name>/` — always supported. Bundled-first precedence on name collisions.
+
+```bash
+# Preferred — user-plugin path
+cp -r /path/to/ClawMem/src/hermes ${HERMES_HOME:-~/.hermes}/plugins/clawmem
+
+# Or symlink for development (either path)
+ln -s /path/to/ClawMem/src/hermes ${HERMES_HOME:-~/.hermes}/plugins/clawmem
+
+# Bundled-style — only when working in the hermes-agent source tree
+cp -r /path/to/ClawMem/src/hermes /path/to/hermes-agent/plugins/memory/clawmem
+```
+
+Discovery is heuristic — Hermes looks for `register_memory_provider` or `MemoryProvider` substrings in `__init__.py`. Both are present in `src/hermes/__init__.py`, so the plugin is discovered correctly under either path.
+
+Activate via `memory.provider: clawmem` in `~/.hermes/config.yaml` (or run `hermes memory setup` and pick `clawmem`). Memory providers are an exclusive category — exactly one is active at a time, selected via `memory.provider`, completely separate from the general plugin loader.
+
+> **Do NOT add `clawmem` to `plugins.enabled` in `config.yaml`.** That list is the general-plugin opt-in roster (Hermes #11xxx onwards made all general plugins opt-in by default). Memory providers have their own activation channel via `memory.provider` and the general loader explicitly skips bundled `plugins/memory/` and treats user-installed memory providers as separate from the standalone-plugin gate. Adding `clawmem` to `plugins.enabled` would make the general loader try to import it as a `kind: standalone` plugin and call `register(ctx)` against the general `PluginContext` — which doesn't expose `register_memory_provider`, so the import errors and the warning gets logged. Harmless but noisy.
+
+Verify discovery:
+```bash
+hermes memory list   # Should show "clawmem" as available
+```
+
+## Architecture
+
+The plugin uses shell-out for lifecycle hooks and REST API for interactive tools:
+
+| Component | Transport | Role |
+|-----------|-----------|------|
+| `initialize()` | Shell-out | Create transcript, run `session-bootstrap`, cache bootstrap context |
+| `prefetch()` / `queue_prefetch()` | Shell-out | Prompt-aware retrieval via `context-surfacing` hook (automatic every turn) |
+| `sync_turn()` | Local file I/O | Append user+assistant to plugin-managed transcript JSONL |
+| `on_session_end()` | Shell-out | `decision-extractor`, `handoff-generator`, `feedback-loop` in parallel |
+| `on_pre_compress()` | Shell-out | `precompact-extract` for state preservation |
+| `system_prompt_block()` | In-process | Static provider info and tool names |
+| Agent tools (5) | REST API | `clawmem_retrieve`, `clawmem_get`, `clawmem_session_log`, `clawmem_timeline`, `clawmem_similar` |
+
+### Why shell-out for hooks?
+
+ClawMem's lifecycle hooks (context-surfacing, decision-extractor, etc.) are Bun/TypeScript programs that read a transcript JSONL file and interact with the SQLite vault directly. The Python plugin shells out to the `clawmem` binary to invoke them, avoiding a cross-language library dependency. This is the same pattern used by the OpenClaw plugin.
+
+### Why REST for tools?
+
+Interactive tool calls need structured JSON responses and benefit from the REST server's connection pooling. The `clawmem serve` process stays warm, so tool calls complete in milliseconds.
+
+### Plugin-managed transcript
+
+Hermes passes turn data via `sync_turn(user_content, assistant_content)`, but ClawMem hooks expect a `.jsonl` transcript file. The plugin bridges this by maintaining its own transcript at `$HERMES_HOME/clawmem-transcripts/<session_id>.jsonl`, appending each turn in Claude Code transcript format (`{"type":"message","message":{"role":"...","content":"..."}}`).
+
+## Configuration
+
+Set in your Hermes profile's `.env` or shell environment:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAWMEM_BIN` | auto-detect on PATH | Path to `clawmem` binary |
+| `CLAWMEM_SERVE_PORT` | `7438` | REST API port |
+| `CLAWMEM_SERVE_MODE` | `external` | `external` (you run `clawmem serve`) or `managed` (plugin starts/stops it) |
+| `CLAWMEM_PROFILE` | `balanced` | Retrieval profile: `speed` (BM25 only), `balanced` (hybrid), `deep` (full pipeline) |
+| `CLAWMEM_EMBED_URL` | — | GPU embedding server URL (e.g., `http://localhost:8088`) |
+| `CLAWMEM_LLM_URL` | — | GPU LLM server URL (e.g., `http://localhost:8089`) |
+| `CLAWMEM_LLM_MODEL` | `qwen3` | Model name sent to the GPU/cloud LLM endpoint (e.g., `qwen3`, `gpt-5.4-mini`) |
+| `CLAWMEM_LLM_REASONING_EFFORT` | — | Optional top-level `reasoning_effort` field for Chat Completions endpoints that support it (for example OpenAI reasoning models). Leave unset for llama-server/vLLM unless explicitly supported. |
+| `CLAWMEM_LLM_NO_THINK` | `true` | Append `/no_think` to remote prompts; set to `false` for standard OpenAI models and other endpoints that reject or treat the Qwen-style suffix as literal prompt text |
+| `CLAWMEM_RERANK_URL` | — | GPU reranker server URL (e.g., `http://localhost:8090`) |
+| `CLAWMEM_API_TOKEN` | — | Bearer token for REST API auth (optional, must match `clawmem serve` config) |
+
+Or configure interactively:
+```bash
+hermes memory setup   # Walks through provider configuration
+```
+
+## Server modes
+
+### External (recommended for production)
+
+You manage `clawmem serve` yourself, either as a systemd service or a background process:
+
+```bash
+clawmem serve --port 7438 &
+# or via systemd — see docs/guides/systemd-services.md
+```
+
+The plugin connects to the existing server. If the server is unreachable, tools fail gracefully but hooks still work (shell-out transport).
+
+### Managed
+
+The plugin starts `clawmem serve` during `initialize()` and stops it on `shutdown()`. Includes a readiness probe (5s health check loop) and early-exit detection.
+
+```bash
+export CLAWMEM_SERVE_MODE=managed
+```
+
+Suitable for development. Not recommended for production — the process doesn't survive plugin crashes or Hermes restarts.
+
+## Agent-context isolation
+
+Hermes's `run_agent.py` passes an `agent_context` kwarg to every `MemoryProvider.initialize()` call with one of four values: `"primary"`, `"subagent"`, `"cron"`, or `"flush"`. The `MemoryProvider` ABC docstring is explicit about why this matters: *"Providers should skip writes for non-primary contexts (cron system prompts would corrupt user representations)."*
+
+The plugin honours this contract by gating only the **write-side** surfaces — read-side hooks always run so non-primary agents still benefit from retrieval:
+
+| Surface | Direction | `agent_context != "primary"` behaviour |
+|---|---|---|
+| `session-bootstrap` (in `initialize`) | Read | Runs — context still surfaced |
+| `prefetch()` / `queue_prefetch()` (`context-surfacing`) | Read | Runs — context still surfaced |
+| `system_prompt_block()` | Read | Runs — provider info still injected |
+| Agent tools (REST) | Read | Runs — agents can still call `clawmem_retrieve` etc. |
+| `sync_turn()` (transcript append) | Write | **Suppressed** |
+| `on_session_end()` (extraction) | Write | **Suppressed** |
+| `on_pre_compress()` (precompact) | Write | **Suppressed** |
+
+Net effect: subagents, cron jobs, and flush passes get the benefit of vault recall without contaminating the vault with intermediate state or system-prompt reasoning. The `initialize()` log line records the active context for operator visibility:
+
+```
+clawmem: agent_context=cron — reads enabled, writes suppressed
+```
+
+## Hermes built-in memory coexistence
+
+Hermes always runs its built-in memory provider (MEMORY.md / USER.md) alongside the external provider. ClawMem is additive — it does not replace or disable built-in memory. Both inject into the context independently.
+
+This means some duplication is possible (built-in memory captures a fact, ClawMem extracts the same fact from the transcript). In practice the overlap is minimal because:
+- Built-in memory captures explicit `add_to_memory` tool calls
+- ClawMem captures implicit decisions, handoffs, and patterns from conversation flow
+- Different storage formats (markdown files vs SQLite vault) serve different retrieval strategies
+
+`on_memory_write()` is intentionally a no-op in v1 to avoid amplifying duplication.
+
+## Shared vault across frameworks
+
+Claude Code, OpenClaw, and Hermes all access the same SQLite vault file (`~/.cache/clawmem/index.sqlite` by default). A decision captured in a Claude Code session is visible to Hermes agents, and vice versa.
+
+SQLite WAL mode + `busy_timeout=5000ms` handles concurrent access. The plugin-managed transcript is stored separately under `$HERMES_HOME/clawmem-transcripts/` and does not affect the shared vault.
+
+## What needs to be running
+
+| Service | Purpose | Managed by |
+|---------|---------|------------|
+| `clawmem serve` | REST API for agent tools | External (systemd) or managed (plugin) |
+| `clawmem-watcher` | Auto-index on file changes | [systemd](systemd-services.md#watcher-service) |
+| `clawmem-embed.timer` | Daily embedding sweep | [systemd](systemd-services.md#embed-timer) |
+| GPU servers (optional) | Embedding, LLM, reranker | [systemd](systemd-services.md#gpu-service-units) or in-process fallback |
+
+## Verify
+
+```bash
+# Plugin discovered
+hermes memory list | grep clawmem
+
+# REST API responding
+curl http://localhost:7438/health
+
+# Hooks working
+clawmem status
+
+# Watcher active
+systemctl --user status clawmem-watcher.service
+```
+
+## Lifecycle mapping reference
+
+| Hermes MemoryProvider | ClawMem equivalent | Notes |
+|---|---|---|
+| `is_available()` | PATH check for `clawmem` binary | No network calls |
+| `initialize(session_id, **kwargs)` | `session-bootstrap` hook | Creates transcript, caches bootstrap context. Reads `agent_context` and `hermes_home` from kwargs. Other kwargs Hermes passes (`platform`, `agent_identity`, `agent_workspace`, `parent_session_id`, `user_id`, `gateway_session_key`, `session_title`) are absorbed via `**kwargs` and currently unused. |
+| `system_prompt_block()` | Static text | Provider active, tool names |
+| `prefetch(query)` | `context-surfacing` hook output | Returns cached result from background thread |
+| `queue_prefetch(query)` | `context-surfacing` hook | Background thread, generation-safe |
+| `sync_turn(user, assistant)` | Transcript JSONL append | Bridges Hermes turn pairs to ClawMem file format. Suppressed when `agent_context != "primary"`. |
+| `on_turn_start()` | — | Not overridden — base no-op |
+| `on_session_end(messages)` | `decision-extractor` + `handoff-generator` + `feedback-loop` | Parallel, 30s timeout each. Suppressed when `agent_context != "primary"`. |
+| `on_pre_compress(messages)` | `precompact-extract` | Side effect only (Hermes ignores return). Suppressed when `agent_context != "primary"`. |
+| `on_memory_write()` | No-op | Avoids duplication with built-in memory (filesystem watcher already indexes MEMORY.md / USER.md if they live under a configured collection). |
+| `on_delegation()` | No-op | Subagent observation handled at the parent's primary context already; nothing useful to add here. |
+| `get_tool_schemas()` | 5 REST-backed tools | retrieve, get, session_log, timeline, similar |
+| `handle_tool_call()` | REST API dispatch | Bearer auth when `CLAWMEM_API_TOKEN` is set |
+| `shutdown()` | Thread cleanup + managed serve stop | Joins prefetch thread, terminates managed process |

package/docs/guides/inference-services.md

@@ -0,0 +1,144 @@
+# Inference services — choosing and running your stack
+
+ClawMem uses three inference services: **embedding**, **LLM** (query expansion / intent classification / A-MEM enrichment), and **reranker** (cross-encoder). In the **default** stack all three run as `llama-server` (llama.cpp) instances, each with an in-process `node-llama-cpp` fallback that auto-downloads on first use — so ClawMem works with no manual setup and no dedicated GPU. The `bin/clawmem` wrapper points the three endpoint vars at `localhost:8088` (embedding), `localhost:8089` (LLM), `localhost:8090` (reranker) by default.
+
+> **Always run ClawMem via the `bin/clawmem` wrapper.** It exports the endpoint defaults. Invoking `bun run src/clawmem.ts` directly skips them and silently falls back to in-process CPU inference (slow). For remote GPU, add the same vars to your systemd units — see [systemd-services.md](systemd-services.md).
+
+## Choosing your inference stack
+
+Three stacks, picked by hardware, license, and quality needs. This is the decision; the rest of this guide is how to run each.
+
+| Stack | Models | VRAM | License | Retrieval quality / context | Pick when |
+|---|---|---|---|---|---|
+| **QMD native** (default) | EmbeddingGemma-300M (768d) + qmd-query-expansion-1.7B + qwen3-reranker-0.6B | ~4 GB total, or **in-process** (Metal/Vulkan/CPU) | **Permissive — commercial OK** | Good · 2K embed context | Any GPU **or no GPU**; **commercial use**; zero-config start (auto-downloads) |
+| **z / SOTA** | zembed-1 (2560d, zELO-distilled from zerank-2) + qmd-query-expansion-1.7B + zerank-2 seq-cls **sidecar** (bf16) | ~16 GB (4.4 + 2.2 + 9) | **CC-BY-NC-4.0 — non-commercial only** | Best (zerank-2 NDCG@10 ahead of Cohere rerank-3.5) · 32K embed context | 16 GB+ GPU **and** non-commercial; want top recall |
+| **Cloud embedding** | Jina v5-text-small (1024d, rec.) / OpenAI / Voyage / Cohere — **embedding only** | none (embedding) | provider ToS | provider-dependent · up to 128K (Cohere) | No local GPU for embedding, or prefer managed. **LLM + reranker still run local/in-process.** |
+
+**Decision axes:** VRAM budget · license (commercial vs non-commercial) · retrieval quality · context length. The default native stack is the right starting point for most users and the only stack with no licensing restriction; upgrade to the z-stack only with a 16 GB+ GPU and a non-commercial use case; use cloud embedding when you have no local GPU to spare for embeddings.
+
+## Landmines (read before serving)
+
+- **The zerank-2 GGUF is deprecated and inert.** llama.cpp's converter drops zerank's CrossEncoder/LogitScore head, so under `--reranking` it returns HTTP 200 with near-zero, non-discriminating scores — the final ordering silently collapses to RRF. Serve the SOTA reranker via the **seq-cls sidecar** (`extras/rerankers/zerank-2-seq/`), never as a GGUF. Run `clawmem rerank-health` to confirm a reranker actually discriminates (liveness ≠ correctness).
+- **`-ub` must equal `-b`** for embedding/reranking models (non-causal attention) or `llama-server` asserts (`non-causal attention requires n_ubatch >= n_tokens`). The zerank-2 sidecar is transformers-served and exempt; the qwen3-reranker GGUF does not need it. See [llama.cpp#12836](https://github.com/ggml-org/llama.cpp/issues/12836).
+- **Changing embedding dimensions requires a full re-embed:** `clawmem embed --force` (idempotent, safe to interrupt/resume).
+- **Set `CLAWMEM_NO_LOCAL_MODELS=true`** for remote-only / dedicated-server setups to fail fast on an unreachable endpoint instead of silently auto-downloading multi-GB GGUFs and running CPU inference.
+
+## Default stack — QMD native (any GPU or in-process)
+
+Total ~4 GB VRAM, or runs in-process via `node-llama-cpp` (Metal on Apple Silicon, Vulkan where available, CPU as last resort — fast with GPU acceleration, significantly slower CPU-only). All three auto-download on first use if no server is running.
+
+| Service | Port | Model | VRAM | Purpose |
+|---|---|---|---|---|
+| Embedding | 8088 | [EmbeddingGemma-300M-Q8_0](https://huggingface.co/ggml-org/embeddinggemma-300M-GGUF) (314 MB, 768d, 2K ctx) | ~400 MB | Vector search, indexing, context-surfacing |
+| LLM | 8089 | [qmd-query-expansion-1.7B-q4_k_m](https://huggingface.co/tobil/qmd-query-expansion-1.7B-gguf) (~1.1 GB) | ~2.2 GB | Intent classification, query expansion, A-MEM |
+| Reranker | 8090 | [qwen3-reranker-0.6B-Q8_0](https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF) (~600 MB) | ~1.3 GB | Cross-encoder reranking |
+
+```bash
+# Embedding (--embeddings flag required)
+llama-server -m embeddinggemma-300M-Q8_0.gguf \
+  --embeddings --port 8088 --host 0.0.0.0 -ngl 99 -c 2048 --batch-size 2048
+
+# LLM (QMD finetuned model)
+llama-server -m qmd-query-expansion-1.7B-q4_k_m.gguf \
+  --port 8089 --host 0.0.0.0 -ngl 99 -c 4096 --batch-size 512
+
+# Reranker
+llama-server -m Qwen3-Reranker-0.6B-Q8_0.gguf \
+  --reranking --port 8090 --host 0.0.0.0 -ngl 99 -c 2048 --batch-size 512
+```
+
+On CPU, omit `-ngl 99`. If a server is unreachable (ECONNREFUSED/ETIMEDOUT), ClawMem sets a 60-second cooldown and falls back to in-process inference; HTTP 4xx/5xx and user-cancelled requests do not trigger cooldown.
+
+## SOTA stack — z models (16 GB+ GPU, CC-BY-NC-4.0, non-commercial only)
+
+ZeroEntropy's distillation-paired stack — best retrieval quality, total ~16 GB VRAM. zembed-1 is distilled from zerank-2 via [zELO](https://docs.zeroentropy.dev), so the pair is mutually optimal.
+
+| Service | Port | Model | VRAM | Purpose |
+|---|---|---|---|---|
+| Embedding | 8088 | [zembed-1-Q4_K_M](https://huggingface.co/Abhiray/zembed-1-Q4_K_M-GGUF) (2.4 GB, 2560d, 32K ctx) | ~4.4 GB | SOTA embedding |
+| LLM | 8089 | qmd-query-expansion-1.7B-q4_k_m | ~2.2 GB | (same as default) |
+| Reranker | 8090 | [zerank-2 seq-cls sidecar](../../extras/rerankers/zerank-2-seq/) (transformers, bf16) | ~9 GB | SOTA reranker — **not** a GGUF |
+
+```bash
+# Embedding (zembed-1) — -ub MUST equal -b for non-causal attention
+llama-server -m zembed-1-Q4_K_M.gguf \
+  --embeddings --port 8088 --host 0.0.0.0 -ngl 99 -c 8192 -b 2048 -ub 2048
+
+# Reranker (zerank-2) — seq-cls SIDECAR (transformers, bf16), NOT a llama-server GGUF:
+cd extras/rerankers/zerank-2-seq
+docker compose build
+HF_TOKEN=hf_xxx docker compose run --rm convert   # download + convert + verify (all gates must pass)
+docker compose up -d reranker                      # serves /v1/rerank on :8090
+```
+
+## Embedding (detail)
+
+ClawMem calls the OpenAI-compatible `/v1/embeddings` endpoint for all embedding operations — works with local `llama-server` and cloud providers alike.
+
+- **GPU with VRAM to spare:** zembed-1 (Option above) — SOTA, multilingual out of the box.
+- **No GPU / limited VRAM:** EmbeddingGemma-300M-Q8_0 (Option above). For a lightweight multilingual alternative use [granite-embedding-278m-multilingual-Q6_K](https://huggingface.co/bartowski/granite-embedding-278m-multilingual-GGUF) (314 MB; set `CLAWMEM_EMBED_MAX_CHARS=1100` for its 512-token context).
+- **Cloud:** any OpenAI-compatible `/v1/embeddings` provider — Jina (recommended `jina-embeddings-v5-text-small`, 1024d), OpenAI, Voyage, Cohere. Full provider matrix, batch/TPM behavior, and per-provider params are in [cloud-embedding.md](cloud-embedding.md).
+
+```bash
+# Verify an embedding endpoint is reachable
+curl $CLAWMEM_EMBED_URL/v1/embeddings \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $CLAWMEM_EMBED_API_KEY" \
+  -d "{\"input\":\"test\",\"model\":\"$CLAWMEM_EMBED_MODEL\"}"
+```
+
+## LLM server
+
+Intent classification, query expansion, and A-MEM extraction use [qmd-query-expansion-1.7B](https://huggingface.co/tobil/qmd-query-expansion-1.7B-gguf) — a Qwen3-1.7B finetuned by QMD for generating search-expansion terms (hyde, lexical, vector variants). ~1.1 GB at q4_k_m, served on port 8089. If `CLAWMEM_LLM_URL` is unset, `node-llama-cpp` auto-downloads it.
+
+- **Performance (RTX 3090):** intent classification ~27 ms; query expansion ~333 tok/s; VRAM ~2.2–2.8 GB.
+- **Qwen3 `/no_think`:** Qwen3 emits thinking tokens by default; ClawMem appends `/no_think` to all prompts automatically for structured output.
+- **Dual-path intent:** a heuristic regex classifier handles strong why/when/who signals instantly (0.8+ confidence); the LLM refines only ambiguous queries below that threshold.
+
+```bash
+llama-server -m qmd-query-expansion-1.7B-q4_k_m.gguf \
+  --port 8089 --host 0.0.0.0 -ngl 99 -c 4096 --batch-size 512
+```
+
+For better entity-extraction quality during `reindex --enrich`, point `CLAWMEM_LLM_URL` at a 7B+ model or cloud API (see [../internals/entity-resolution.md](../internals/entity-resolution.md)).
+
+## Reranker server
+
+Cross-encoder reranking for the `query` (4000-char context, deep) and `intent_search` (200-char context, fast) pipelines on port 8090, via the `/v1/rerank` endpoint.
+
+- **GPU with VRAM to spare:** the zerank-2 seq-cls sidecar (recipe above). **CC-BY-NC-4.0.**
+- **CPU / limited VRAM:** qwen3-reranker-0.6B-Q8_0 (~600 MB, ~1.3 GB VRAM), the QMD native reranker — auto-downloaded if no server is running.
+
+```bash
+llama-server -m Qwen3-Reranker-0.6B-Q8_0.gguf \
+  --reranking --port 8090 --host 0.0.0.0 -ngl 99 -c 2048 --batch-size 512
+```
+
+See the landmines above: the zerank-2 **GGUF is inert** (use the sidecar), and verify discrimination with `clawmem rerank-health`.
+
+## Remote GPU
+
+If the GPU lives on a separate machine, point the env vars at it and disable local fallback:
+
+```bash
+export CLAWMEM_EMBED_URL=http://gpu-host:8088
+export CLAWMEM_LLM_URL=http://gpu-host:8089
+export CLAWMEM_LLM_MODEL=qwen3
+export CLAWMEM_RERANK_URL=http://gpu-host:8090
+export CLAWMEM_NO_LOCAL_MODELS=true   # fail fast instead of auto-downloading multi-GB GGUFs
+```
+
+## Verify endpoints
+
+```bash
+curl http://host:8088/v1/embeddings -d '{"input":"test","model":"embedding"}' -H 'Content-Type: application/json'
+curl http://host:8089/v1/models
+curl http://host:8090/v1/models
+```
+
+## See also
+
+- **Cloud embedding** — provider matrix, batch embedding, TPM-aware pacing, per-provider params → [cloud-embedding.md](cloud-embedding.md)
+- **All environment variables** (endpoints, profiles, consolidation, merge gates) → [../reference/configuration.md](../reference/configuration.md)
+- **Keeping servers up** (systemd units, GPU env in services) → [systemd-services.md](systemd-services.md)
+- **Reranker health** — the degenerate-reranker failure mode and `clawmem rerank-health` → [../troubleshooting.md](../troubleshooting.md)

package/docs/guides/multi-vault-config.md

@@ -0,0 +1,84 @@
+# Multi-vault configuration
+
+Step-by-step guide for setting up multiple independent ClawMem vaults to isolate AI agent memory by project or team.
+
+## 1. Define vaults
+
+Edit `~/.config/clawmem/config.yaml`:
+
+```yaml
+vaults:
+  work: ~/.cache/clawmem/work.sqlite
+  personal: ~/.cache/clawmem/personal.sqlite
+  research: ~/data/research-vault.sqlite
+```
+
+Or use the environment variable:
+
+```bash
+export CLAWMEM_VAULTS='{"work":"~/.cache/clawmem/work.sqlite","personal":"~/.cache/clawmem/personal.sqlite"}'
+```
+
+Paths support `~` expansion. Environment variables override config file values.
+
+## 2. Populate vaults
+
+Use `vault_sync` via MCP or CLI:
+
+```
+vault_sync(vault="work", content_root="~/projects/work-notes")
+vault_sync(vault="personal", content_root="~/notes/personal")
+```
+
+Or add collections to a vault manually:
+
+```bash
+INDEX_PATH=~/.cache/clawmem/work.sqlite ./bin/clawmem collection add ~/projects/work-notes --name work-notes
+INDEX_PATH=~/.cache/clawmem/work.sqlite ./bin/clawmem update --embed
+```
+
+## 3. Embed vault content
+
+Each vault needs its own embedding pass:
+
+```bash
+INDEX_PATH=~/.cache/clawmem/work.sqlite ./bin/clawmem embed
+INDEX_PATH=~/.cache/clawmem/personal.sqlite ./bin/clawmem embed
+```
+
+## 4. Query vaults
+
+All MCP tools accept `vault`:
+
+```
+# Search work vault
+query("API authentication flow", vault="work", compact=true)
+
+# Check personal vault lifecycle
+lifecycle_status(vault="personal")
+
+# Pin something in research vault
+memory_pin("important finding", vault="research")
+```
+
+## 5. List configured vaults
+
+```
+list_vaults()
+```
+
+Returns:
+
+```
+Configured vaults (2):
+  work: /home/user/.cache/clawmem/work.sqlite
+  personal: /home/user/.cache/clawmem/personal.sqlite
+```
+
+## Notes
+
+- The default (unnamed) vault at `~/.cache/clawmem/index.sqlite` always exists and is used when `vault` is omitted
+- Hooks always operate on the default vault
+- Named vault stores are cached in memory and reused across tool calls
+- Each vault is fully independent — separate documents, embeddings, graphs, and sessions
+- `vault_sync` validates paths against a deny-list (rejects `/etc/`, `.ssh`, `.env`, `credentials`, etc.)