clawmem 0.14.0 → 0.15.0

package/docs/quickstart.md

@@ -0,0 +1,158 @@
+# Quickstart
+
+Set up ClawMem as persistent memory for AI coding agents in under 5 minutes. By the end you'll have hooks injecting context on every prompt and an MCP server for agent-initiated retrieval.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) v1.0+ — install via `curl -fsSL https://bun.sh/install | bash`, not snap (snap Bun has stdin restrictions that break hooks)
+- A GPU for local inference (default models need ~4GB VRAM; the full SOTA stack needs ~16GB, the zerank-2 sidecar alone ~9GB). Or use [cloud embedding](guides/cloud-embedding.md)
+- Claude Code, OpenClaw, or any MCP-compatible client
+
+## Install
+
+```bash
+# Via npm (recommended)
+npm install -g clawmem
+
+# If you use Bun as your package manager:
+# bun add -g clawmem
+
+# From source
+git clone https://github.com/yoloshii/clawmem.git ~/clawmem
+cd ~/clawmem && bun install
+ln -sf ~/clawmem/bin/clawmem ~/.bun/bin/clawmem
+```
+
+## Bootstrap a vault
+
+The fastest path — one command to init, index, embed, set up hooks, and register MCP:
+
+```bash
+clawmem bootstrap ~/notes --name notes
+```
+
+This creates a vault at `~/.cache/clawmem/index.sqlite`, indexes all `.md` files under `~/notes`, embeds them for vector search, installs Claude Code hooks, and registers the MCP server.
+
+## Or step by step
+
+```bash
+# 1. Initialize the vault
+clawmem init
+
+# 2. Add a collection (directory of markdown files)
+clawmem collection add ~/notes --name notes
+
+# 3. Index and embed
+clawmem update --embed
+
+# 4. Set up Claude Code hooks (automatic context injection)
+clawmem setup hooks
+
+# 5. Register the MCP server (agent-initiated tools)
+clawmem setup mcp
+```
+
+## Start GPU services
+
+ClawMem uses three llama-server instances for best performance. All three models also auto-download and run locally via `node-llama-cpp` if no server is running — using Metal on Apple Silicon, Vulkan where available, or CPU as last resort. With GPU acceleration (Metal/Vulkan), in-process inference is fast for these small models; on CPU-only systems it is significantly slower. If you're using GPU servers, run them via [systemd services](guides/systemd-services.md) to prevent silent fallback on server crash.
+
+```bash
+# Embedding (recommended for performance — falls back to in-process if no server)
+llama-server -m embeddinggemma-300M-Q8_0.gguf \
+  --embeddings --port 8088 --host 0.0.0.0 -ngl 99 -c 2048 --batch-size 2048
+
+# LLM — query expansion (falls back to in-process if unavailable)
+llama-server -m qmd-query-expansion-1.7B-q4_k_m.gguf \
+  --port 8089 --host 0.0.0.0 -ngl 99 -c 4096
+
+# Reranker (falls back to in-process if unavailable)
+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
+```
+
+> **SOTA upgrade (16GB+ GPU):** Replace embedding with zembed-1-Q4_K_M (2560d, `-b 2048 -ub 2048`). For the reranker, use the **zerank-2 seq-cls sidecar** (transformers, bf16) at [`extras/rerankers/zerank-2-seq/`](../extras/rerankers/zerank-2-seq/) — the `zerank-2-Q4_K_M` GGUF is deprecated (llama.cpp drops its score head). See [the inference services guide](guides/inference-services.md). **CC-BY-NC-4.0** — non-commercial only.
+
+See [GPU services guide](guides/systemd-services.md) for systemd setup and remote GPU configuration.
+
+No GPU? See [cloud embedding](guides/cloud-embedding.md) for OpenAI, Voyage, Jina, or Cohere alternatives.
+
+## Verify
+
+```bash
+clawmem doctor    # Full health check
+clawmem status    # Quick index status
+bun test                # Run test suite
+```
+
+## Build out your collections
+
+The bootstrap command indexed one directory. ClawMem gets more useful as you add more content — the retrieval pipeline surfaces better results from a richer corpus.
+
+```bash
+# Add your project docs
+clawmem collection add ~/projects/myapp --name myapp
+
+# Add research notes, decision records, domain references
+clawmem collection add ~/research --name research
+
+# Re-index and embed the new collections
+clawmem update --embed
+```
+
+A practical starting point: index every `.md` file in each project you regularly work on with agents. Include memory files, research outputs, decision records, learnings, project notes, and domain references. The more relevant context in the vault, the more the context-surfacing hook has to work with on each prompt.
+
+### Customize index patterns
+
+Each collection has a `pattern` field that controls which files get indexed (default: `**/*.md`). Edit `~/.config/clawmem/config.yaml` to customize:
+
+```yaml
+collections:
+  notes:
+    path: ~/notes
+    pattern: "**/*.md"              # default — all markdown recursively
+
+  project:
+    path: ~/projects/myapp
+    pattern: "**/*.md"              # all markdown in the project
+
+  research:
+    path: ~/research
+    pattern: "**/*.{md,txt}"        # markdown and text files
+
+  obsidian:
+    path: ~/vault
+    pattern: "**/*.md"              # works with Obsidian, Logseq, Foam, Dendron
+```
+
+After editing the config, re-index and embed:
+
+```bash
+clawmem update --embed
+```
+
+The [watcher service](guides/systemd-services.md) picks up new files automatically, but adding or changing collections requires a manual `update`. Certain directories are always excluded regardless of pattern: `.git`, `node_modules`, `dist`, `build`, `vendor`, and others listed in [architecture](concepts/architecture.md#excluded-directories).
+
+### Code stays out of the vault
+
+ClawMem indexes prose, not code. Source files (`.ts`, `.py`, `.go`, etc.) are excluded by design — BM25 and embedding models trained on natural language perform poorly on code syntax. Capture technical decisions and architecture rationale in markdown instead. Use a dedicated code search tool for code retrieval.
+
+### Structure documents for better scoring
+
+Documents with headings, lists, and decision keywords score higher in retrieval. Frontmatter adds a 0.2 quality score bonus. The [quality multiplier](concepts/composite-scoring.md#quality-multiplier-07---13) ranges from 0.7x (penalty for flat text) to 1.3x (boost for well-structured docs) — so structure directly affects how often your content gets surfaced.
+
+## What happens next
+
+Once set up, ClawMem works automatically:
+
+1. **Every prompt** — the `context-surfacing` hook searches your vault and injects relevant context as `<vault-context>` XML
+2. **Every response** — the `decision-extractor` and `handoff-generator` hooks capture decisions and session summaries
+3. **On demand** — the agent can call MCP tools like `memory_retrieve`, `query`, or `intent_search` when hooks don't surface enough
+
+No agent configuration needed. The hooks are invisible to the agent — it just sees richer context.
+
+## Next steps
+
+- [Architecture](concepts/architecture.md) — understand how vaults, collections, and scoring work
+- [Setup Hooks](guides/setup-hooks.md) — customize which hooks are installed
+- [OpenClaw Plugin](guides/openclaw-plugin.md) — use ClawMem as OpenClaw's context engine
+- [Multi-Vault](guides/multi-vault-config.md) — separate memory domains for different projects

package/docs/reference/cli.md

@@ -0,0 +1,195 @@
+# ClawMem CLI reference
+
+Complete command reference for the ClawMem memory engine. Always use the `bin/clawmem` wrapper, which sets GPU endpoint defaults.
+
+## Core commands
+
+```bash
+clawmem init                    # Initialize vault (creates SQLite DB)
+clawmem status                  # Quick index status
+clawmem doctor                  # Full health check (GPU connectivity, index integrity)
+```
+
+## Collection management
+
+```bash
+clawmem collection add <path> --name <name>   # Add a collection
+clawmem collection list                        # List all collections
+clawmem collection remove <name>               # Remove a collection
+```
+
+## Indexing
+
+```bash
+clawmem update                  # Index all collections (BM25 only)
+clawmem update --embed          # Index + embed in one pass
+clawmem mine <dir>                             # Import conversation exports (Claude, ChatGPT, Slack)
+clawmem mine <dir> -c convos                   # Import with custom collection name
+clawmem mine <dir> --embed                     # Import + embed in one pass
+clawmem mine <dir> --dry-run                   # Preview without importing
+clawmem mine <dir> --synthesize                # v0.7.2: import + post-import LLM fact extraction
+clawmem mine <dir> --synthesize --synthesis-max-docs 50   # Cap synthesis to first 50 conversations (default 20)
+clawmem reindex                                # Force re-scan all collections
+clawmem embed                   # Embed all un-embedded fragments
+clawmem embed --force           # Re-embed everything (clears existing vectors)
+```
+
+### Conversation Import
+
+`clawmem mine` normalizes and imports conversation exports from multiple AI chat formats:
+
+- **Claude Code JSONL** — session transcripts (`.jsonl`)
+- **Claude.ai JSON** — flat messages or privacy export with `chat_messages`
+- **ChatGPT JSON** — `conversations.json` with mapping tree
+- **Slack JSON** — 2-party DM exports
+- **Plain text** — files with `User:`/`Assistant:` markers
+
+Each user+assistant exchange pair becomes one indexed document with `content_type: conversation`. Files are chunked, written to a temporary staging directory, indexed through the standard pipeline (including A-MEM enrichment), then staging is cleaned up.
+
+#### `--synthesize` (v0.7.2)
+
+Adds a post-import LLM fact extraction pass. After `indexCollection` commits the raw conversations, the synthesis pipeline walks the freshly imported docs and extracts structured facts (`decision`, `preference`, `milestone`, `problem`) plus cross-fact relations via a two-pass LLM pipeline. Each extracted fact is saved as a first-class searchable document alongside the raw conversation exchanges. Cross-fact links bind across conversations in the same batch — not just within a single conversation.
+
+- **Off by default.** Raw mine import semantics are byte-identical when `--synthesize` is omitted.
+- **Opt-in user consent required** — each pass drives one additional LLM call per conversation doc.
+- **`--synthesis-max-docs N`** caps the number of conversations scanned per run (default 20).
+- **Idempotent reruns** — synthesized fact paths are hash-stable, so rerunning over the same collection updates facts in place rather than creating parallel rows. Relation weights are monotone (`MAX(weight, excluded.weight)`).
+- **Non-fatal failures** — any LLM failure, JSON parse error, or relation insert error is counted and logged. Synthesis failure never rolls back the mine import.
+- See [post-import conversation synthesis](../concepts/architecture.md#post-import-conversation-synthesis-v072) for the full architectural walkthrough.
+
+## Search (CLI)
+
+```bash
+clawmem search <query>          # BM25 search
+clawmem search <query> --vec    # Vector search
+clawmem search <query> --hybrid # BM25 + vector (default)
+```
+
+## Bootstrap
+
+```bash
+clawmem bootstrap <path> --name <name>   # One-command setup: init + collection + index + embed + hooks + mcp
+```
+
+## Watch
+
+```bash
+clawmem watch                   # Start file watcher (indexes on .md changes)
+```
+
+## Setup
+
+```bash
+clawmem setup hooks             # Install Claude Code hooks
+clawmem setup hooks --remove    # Remove installed hooks
+clawmem setup mcp               # Register MCP server
+clawmem setup openclaw                   # Install OpenClaw memory plugin. v0.10.4+ delegates to `openclaw plugins install --force` when the CLI is on PATH (profile-aware via OPENCLAW_STATE_DIR; auto-enabled). Falls back to recursive copy honoring OPENCLAW_STATE_DIR when the CLI is absent.
+clawmem setup openclaw --link            # Load-path mode: delegates `openclaw plugins install -l` when CLI is on PATH (records source in plugins.load.paths — NOT a filesystem symlink). In CLI-absent fallback, creates a real symlink (note: OpenClaw v2026.4.11+ discovery skips fallback symlinks).
+clawmem setup openclaw --remove          # Uninstall. Tries `openclaw plugins uninstall clawmem --force` first; falls back to manual cleanup at the resolved extensions path for legacy unmanaged installs.
+clawmem setup openclaw --help            # Print full flag + env-var reference (v0.10.4+).
+clawmem setup curator                    # Install curator agent
+```
+
+### `setup openclaw` env vars (v0.10.4+)
+
+Both the delegated and fallback paths honor:
+
+| Env var | Effect |
+|---------|--------|
+| `OPENCLAW_STATE_DIR` | Override the OpenClaw config root. Plugin installs into `<OPENCLAW_STATE_DIR>/extensions/clawmem`. |
+| `OPENCLAW_CONFIG_PATH` | Override the OpenClaw config file path; config root becomes `dirname(OPENCLAW_CONFIG_PATH)`. |
+| `OPENCLAW_HOME` | Override the home directory used to resolve the default `~/.openclaw` root. |
+| `HOME` / `USERPROFILE` | Standard home-dir env vars; consulted in that order when `OPENCLAW_HOME` is unset. |
+
+```bash
+# Install ClawMem into the `dev` profile (~/.openclaw-dev/extensions/clawmem)
+OPENCLAW_STATE_DIR=~/.openclaw-dev clawmem setup openclaw
+```
+
+## Server
+
+```bash
+clawmem serve                            # Start REST API (localhost:7438)
+clawmem serve --port 8080                # Custom port
+clawmem serve --host 0.0.0.0             # Listen on all interfaces
+```
+
+## Hook execution (internal)
+
+```bash
+clawmem hook context-surfacing    # Execute a hook (reads JSON from stdin)
+clawmem hook decision-extractor
+clawmem hook handoff-generator
+clawmem hook feedback-loop
+clawmem hook precompact-extract
+clawmem hook session-bootstrap
+clawmem hook staleness-check
+clawmem hook curator-nudge
+```
+
+## IO6 surface commands (daemon integration)
+
+For non-hook integrations where a host process needs to inject context programmatically (e.g., daemon mode, custom orchestrators):
+
+```bash
+echo "user query" | clawmem surface --context --stdin     # Per-prompt context injection
+echo "session-id" | clawmem surface --bootstrap --stdin    # Per-session bootstrap
+```
+
+## Analysis
+
+```bash
+clawmem reflect [N]             # Cross-session reflection (last N days, default 14)
+clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence documents
+```
+
+## Session focus topic (v0.9.0)
+
+Per-session topic biasing for the context-surfacing hook. Writes a focus file at `~/.cache/clawmem/sessions/<session_id>.focus` that steers query expansion, reranking, snippet extraction, and applies a post-composite-score topic boost (1.4× match, 0.75× demote, NO-OP on zero matches). Session-scoped — never writes to SQLite or mutates any lifecycle column.
+
+```bash
+clawmem focus set "<topic>"                        # uses CLAUDE_SESSION_ID / CLAWMEM_SESSION_ID env
+clawmem focus set "<topic>" --session-id <id>      # explicit session id
+clawmem focus show                                 # reads session id from env
+clawmem focus show --session-id <id>
+clawmem focus clear                                # uses env-resolved session id
+clawmem focus clear --session-id <id>
+```
+
+The session ID is resolved from `--session-id <id>`, then `CLAUDE_SESSION_ID`, then `CLAWMEM_SESSION_ID`. `CLAWMEM_SESSION_FOCUS` env var is a debug-only override that does NOT provide per-session scoping on multi-session hosts. `CLAWMEM_FOCUS_ROOT` overrides the focus file root directory for hermetic testing.
+
+## Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CLAWMEM_EMBED_URL` | `http://localhost:8088` | Embedding server |
+| `CLAWMEM_EMBED_API_KEY` | — | API key for cloud embedding |
+| `CLAWMEM_EMBED_MODEL` | `embedding` | Model name for embedding requests |
+| `CLAWMEM_EMBED_MAX_CHARS` | `6000` | Max chars per embedding input |
+| `CLAWMEM_EMBED_TPM_LIMIT` | `100000` | Tokens-per-minute limit for cloud embedding pacing |
+| `CLAWMEM_EMBED_DIMENSIONS` | — | Output dimensions for OpenAI `text-embedding-3-*` models |
+| `CLAWMEM_LLM_URL` | `http://localhost:8089` | LLM server |
+| `CLAWMEM_LLM_MODEL` | `qwen3` | Model name sent to the configured LLM endpoint |
+| `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 `false` for standard OpenAI models and other endpoints that reject or treat it as literal prompt text |
+| `CLAWMEM_RERANK_URL` | `http://localhost:8090` | Reranker server |
+| `CLAWMEM_NO_LOCAL_MODELS` | `false` | Block node-llama-cpp auto-downloads |
+| `CLAWMEM_PROFILE` | `balanced` | Performance profile: `speed` (BM25 only), `balanced` (BM25+vector), `deep` (BM25+vector+expansion+reranking) |
+| `CLAWMEM_VAULTS` | — | JSON map of vault name to SQLite path |
+| `CLAWMEM_API_TOKEN` | — | Bearer token for REST API auth |
+| `CLAWMEM_ENABLE_AMEM` | enabled | A-MEM note construction during indexing |
+| `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Background consolidation worker (light lane, 5-min interval). **v0.8.2:** every tick wraps in a `worker_leases` row (`light-consolidation` key) so dual-host (`clawmem watch` + `clawmem mcp`) is safe. Hosted by either `cmdWatch` (canonical, long-lived) or `cmdMcp` (per-session fallback). |
+| `CLAWMEM_CONSOLIDATION_INTERVAL` | `300000` | Light-lane worker interval in ms |
+| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance lane (second consolidation worker with DB-backed lease + stale-first batching + `maintenance_runs` journaling). See [heavy maintenance lane](../concepts/architecture.md#heavy-maintenance-lane-v080). **v0.8.2:** canonical host is `clawmem watch`; `clawmem mcp` retains the same gate as a fallback host but emits a stderr warning advising operators to move heavy-lane hosting to the watcher because per-session stdio MCPs may never be alive during the configured quiet window. |
+| `CLAWMEM_HEAVY_LANE_INTERVAL` | `1800000` | **v0.8.0.** Heavy-lane tick interval in ms (default 30 min, min 30 s). |
+| `CLAWMEM_HEAVY_LANE_WINDOW_START` | — | **v0.8.0.** Start hour (0-23) of the quiet window. Unset → no window. |
+| `CLAWMEM_HEAVY_LANE_WINDOW_END` | — | **v0.8.0.** End hour (0-23, exclusive). Supports midnight wrap (22→6). |
+| `CLAWMEM_HEAVY_LANE_MAX_USAGES` | `30` | **v0.8.0.** Max `context_usage` rows in the last 10 min before the heavy lane skips with `reason='query_rate_high'`. |
+| `CLAWMEM_HEAVY_LANE_OBS_LIMIT` | `100` | **v0.8.0.** Phase 2 stale-first observation batch size for the heavy lane. |
+| `CLAWMEM_HEAVY_LANE_DED_LIMIT` | `40` | **v0.8.0.** Phase 3 stale-first deductive candidate batch size for the heavy lane. |
+| `CLAWMEM_HEAVY_LANE_SURPRISAL` | `false` | **v0.8.0.** When `true`, seed Phase 2 with k-NN anomaly-ranked doc ids from `computeSurprisalScores` instead of stale-first ordering. Degrades to stale-first on vaults without embeddings. |
+| `CLAWMEM_SESSION_FOCUS` | — | **v0.9.0 §11.4.** Debug-only override for the session focus topic. NOT session-scoped — do not use in multi-session deployments. Use `clawmem focus set <topic> --session-id <id>` instead. |
+| `CLAWMEM_FOCUS_ROOT` | `~/.cache/clawmem/sessions` | **v0.9.0 §11.4.** Override directory for per-session focus files. Primarily for hermetic testing. |
+| `INDEX_PATH` | `~/.cache/clawmem/index.sqlite` | Override default vault path |
+
+The `bin/clawmem` wrapper sets endpoint defaults. Always use it instead of `bun run src/clawmem.ts` directly.

package/docs/reference/configuration.md

@@ -0,0 +1,101 @@
+# Configuration reference (environment variables)
+
+All ClawMem tuning knobs are environment variables. The `bin/clawmem` wrapper sets the endpoint defaults; **always run ClawMem via the wrapper.** For remote GPU setups, add the same vars to your systemd units via a drop-in.
+
+**Precedence:** shell environment > `.env` file (project root) > `bin/clawmem` wrapper defaults. The wrapper sources `.env` before applying defaults, so `.env` overrides defaults but explicit shell exports still win.
+
+See also: [../guides/inference-services.md](../guides/inference-services.md) (stack choice + server setup) · [../guides/cloud-embedding.md](../guides/cloud-embedding.md) (cloud providers) · [../guides/systemd-services.md](../guides/systemd-services.md) (services).
+
+## Inference routing
+
+| Variable | Default (via wrapper) | Effect |
+|---|---|---|
+| `CLAWMEM_EMBED_URL` | `http://localhost:8088` | Embedding server URL. Local `llama-server`, cloud API, or in-process `node-llama-cpp` fallback if unset. |
+| `CLAWMEM_LLM_URL` | `http://localhost:8089` | LLM server for intent, expansion, A-MEM, entity extraction. Falls to `node-llama-cpp` if unset + `NO_LOCAL_MODELS=false`. Point at a 7B+ model or cloud API during `reindex --enrich` for better entity extraction. |
+| `CLAWMEM_RERANK_URL` | `http://localhost:8090` | Reranker server. Falls to `node-llama-cpp` if unset + `NO_LOCAL_MODELS=false`. |
+| `CLAWMEM_LLM_MODEL` | `qwen3` | Model name sent on LLM requests. |
+| `CLAWMEM_LLM_REASONING_EFFORT` | (none) | Top-level `reasoning_effort` for Chat Completions endpoints that support it (e.g. a remote reasoning model). Optional. |
+| `CLAWMEM_LLM_NO_THINK` | enabled | Appends `/no_think` to remote LLM prompts (Qwen3 emits thinking tokens by default). Set `false` for standard OpenAI-compatible models that would treat `/no_think` as literal text. |
+| `CLAWMEM_NO_LOCAL_MODELS` | `false` | Blocks `node-llama-cpp` from auto-downloading GGUFs. Set `true` for remote-only setups to fail fast on unreachable endpoints. |
+
+## Cloud embedding
+
+Full provider matrix and behavior: [../guides/cloud-embedding.md](../guides/cloud-embedding.md).
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CLAWMEM_EMBED_API_KEY` | (none) | API key for cloud embedding providers (Bearer token). Enables cloud mode: skips client-side truncation, sends `truncate: true` + provider params, batch embedding with adaptive TPM pacing. |
+| `CLAWMEM_EMBED_MODEL` | `embedding` | Model name for embedding requests. Override for cloud (e.g. `jina-embeddings-v5-text-small`). |
+| `CLAWMEM_EMBED_MAX_CHARS` | `6000` | Max chars per embedding input (local only; fits EmbeddingGemma's 2048 tokens). Set `1100` for granite-278m (512 tokens). Cloud providers skip truncation. |
+| `CLAWMEM_EMBED_TPM_LIMIT` | `100000` | Tokens-per-minute limit for cloud pacing. Match your tier (e.g. Jina Free 100000, Paid 2000000, Premium 50000000). |
+| `CLAWMEM_EMBED_DIMENSIONS` | (none) | Output dimensions for OpenAI `text-embedding-3-*` Matryoshka models (e.g. `512`, `1024`). Sent only when the URL contains `openai.com`. |
+
+## Retrieval profile
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CLAWMEM_PROFILE` | `balanced` | `speed` / `balanced` / `deep`. Sets the kept-score ratio (65% / 55% / 45%), vector timeout, max results, and the `factsTokens` sub-budget. Only `deep` adds query expansion + reranking to the hook path. `speed` makes hooks BM25-only (sub-500ms). |
+| `CLAWMEM_NUDGE_INTERVAL` | `15` | Prompts between lifecycle tool use before a `<vault-nudge>` is injected. `0` to disable. |
+
+The context-surfacing hook `timeout` is **not** an env var — it lives in `~/.claude/settings.json` (8s default). See [../troubleshooting.md](../troubleshooting.md) → *Tuning the context-surfacing hook timeout*.
+
+## Multi-vault
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CLAWMEM_VAULTS` | (none) | JSON map of vault name → SQLite path. E.g. `{"work":"~/.cache/clawmem/work.sqlite"}`. Paths support `~`. (Also configurable in `~/.config/clawmem/config.yaml` under `vaults:`.) |
+
+## A-MEM & consolidation
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CLAWMEM_ENABLE_AMEM` | enabled | A-MEM note construction + link generation during indexing. |
+| `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs + runs Phase 2/3 consolidation + deductive synthesis. Each tick wrapped in a DB-backed `worker_leases` row (`light-consolidation`) so multiple hosts can't race Phase 2 writes. Hosted by `clawmem watch` (canonical) or `clawmem mcp` (per-session fallback). |
+| `CLAWMEM_CONSOLIDATION_INTERVAL` | `300000` | Light-worker interval in ms (min 15000). |
+
+## Heavy maintenance lane (v0.8.0)
+
+A second, longer-interval consolidation lane with DB-backed exclusivity, stale-first batching, and `maintenance_runs` journaling. Off by default; canonical host is `clawmem watch`.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CLAWMEM_HEAVY_LANE` | disabled | Enable the quiet-window heavy lane. |
+| `CLAWMEM_HEAVY_LANE_INTERVAL` | `1800000` | Tick interval in ms (min 30000, default 30 min). |
+| `CLAWMEM_HEAVY_LANE_WINDOW_START` | (none) | Start hour (0–23) of the quiet window. Unset → no window. |
+| `CLAWMEM_HEAVY_LANE_WINDOW_END` | (none) | End hour (0–23, exclusive). Supports midnight wrap (22→6). |
+| `CLAWMEM_HEAVY_LANE_MAX_USAGES` | `30` | Max `context_usage` rows in the last 10 min before the lane skips (`reason='query_rate_high'`). |
+| `CLAWMEM_HEAVY_LANE_OBS_LIMIT` | `100` | Phase 2 stale-first observation batch size. |
+| `CLAWMEM_HEAVY_LANE_DED_LIMIT` | `40` | Phase 3 stale-first deductive candidate batch size. |
+| `CLAWMEM_HEAVY_LANE_SURPRISAL` | `false` | When `true`, seed Phase 2 with k-NN anomaly-ranked doc ids instead of stale-first. Degrades to stale-first on vaults without embeddings. |
+
+## Merge & contradiction safety (v0.7.1)
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CLAWMEM_MERGE_SCORE_NORMAL` | `0.93` | Phase 2 merge-safety threshold (normalized 3-gram cosine) when anchors align. |
+| `CLAWMEM_MERGE_SCORE_STRICT` | `0.98` | Strictest merge-safety threshold (fallback when anchors are ambiguous). |
+| `CLAWMEM_MERGE_GUARD_DRY_RUN` | `false` | When `true`, merge-safety rejections are logged but not enforced — calibration before switching the gate on. |
+| `CLAWMEM_CONTRADICTION_POLICY` | `link` | How the merge-time contradiction gate handles a contradictory merge. `link` keeps both rows + adds a `contradicts` edge; `supersede` marks the old row `status='inactive'`. |
+| `CLAWMEM_CONTRADICTION_MIN_CONFIDENCE` | `0.5` | Minimum combined (heuristic + LLM) confidence before the gate blocks a merge. Below this, the merge proceeds. |
+
+## REST API & Hermes plugin
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CLAWMEM_API_TOKEN` | (none) | When set, `clawmem serve` requires `Authorization: Bearer <token>` on all requests. Unset → open (localhost-only by default). |
+| `CLAWMEM_SERVE_PORT` | `7438` | REST API port read by the **Hermes plugin** (to launch/connect to `clawmem serve`). Manual `clawmem serve` takes `--port` instead — it does not read this env var. |
+| `CLAWMEM_SERVE_MODE` | `external` | Hermes plugin serve mode: `external` (you run `clawmem serve`) or `managed` (the plugin starts/stops `serve`). |
+| `CLAWMEM_BIN` | (auto-detect on PATH) | Path to the `clawmem` binary, for the Hermes plugin when it is not on `PATH`. |
+
+## Hooks, session & paths
+
+| Variable | Default | Effect |
+|---|---|---|
+| `CLAWMEM_CONFIG_DIR` | `~/.config/clawmem` | Override the config directory (holds `config.yaml`). |
+| `CLAWMEM_SESSION_ID` | (Claude Code exposes its own) | Session id for the per-session focus topic; set explicitly in non-Claude-Code environments. |
+| `CLAWMEM_FOCUS_ROOT` | `~/.cache/clawmem/sessions` | Directory for per-session focus files (`clawmem focus`). |
+| `CLAWMEM_SESSION_FOCUS` | (none) | **Debug only.** Directly overrides the session focus topic, bypassing the focus file. |
+| `CLAWMEM_HEARTBEAT_PATTERNS` | (built-in set) | Comma-separated prompt patterns treated as heartbeats (skipped by context-surfacing). |
+| `CLAWMEM_DISABLE_HEARTBEAT_SUPPRESSION` | `false` | Set `true` to disable heartbeat-prompt suppression in the context-surfacing hook. |
+| `CLAWMEM_HOOK_DEDUP_WINDOW_SEC` | (built-in) | Window (seconds) for deduplicating hook-generated observations by normalized content hash. |
+| `CLAWMEM_PRECOMPACT_PROXIMITY_RATIO` | (built-in, clamped [0.5, 0.95]) | OpenClaw `before_prompt_build` precompact trigger: fraction of the compaction threshold at which pre-emptive extraction fires. |