clawmem 0.1.0 → 0.1.2

package/AGENTS.md

@@ -625,6 +625,14 @@ Symptom: embed --force with new model produces 3 docs stuck as "Unembedded" but
 Symptom: CLI reindex/update falls back to node-llama-cpp Vulkan (not GPU server)
   → GPU env vars only in systemd drop-in, not in wrapper script. CLI invocations missed them.
   → Fixed 2026-02-12: bin/clawmem wrapper exports CLAWMEM_EMBED_URL/LLM_URL/RERANK_URL defaults.
+
+Symptom: "UserPromptSubmit hook error" on context-surfacing hook (intermittent)
+  → SQLite contention between the watcher and the hook. The watcher processes filesystem events
+    (including non-.md files like session .jsonl transcripts) and holds brief write locks. If the
+    hook fires during a lock, it can exceed its timeout. More likely during active conversations
+    when the watcher is processing rapid transcript changes.
+  → Fix: Bump the hook timeout from 5s to 8s in ~/.claude/settings.json. If persistent, restart
+    the watcher to clear memory bloat: `systemctl --user restart clawmem-watcher.service`.
 ```
 
 ## CLI Reference

package/CLAUDE.md

@@ -625,6 +625,14 @@ Symptom: embed --force with new model produces 3 docs stuck as "Unembedded" but
 Symptom: CLI reindex/update falls back to node-llama-cpp Vulkan (not GPU server)
   → GPU env vars only in systemd drop-in, not in wrapper script. CLI invocations missed them.
   → Fixed 2026-02-12: bin/clawmem wrapper exports CLAWMEM_EMBED_URL/LLM_URL/RERANK_URL defaults.
+
+Symptom: "UserPromptSubmit hook error" on context-surfacing hook (intermittent)
+  → SQLite contention between the watcher and the hook. The watcher processes filesystem events
+    (including non-.md files like session .jsonl transcripts) and holds brief write locks. If the
+    hook fires during a lock, it can exceed its timeout. More likely during active conversations
+    when the watcher is processing rapid transcript changes.
+  → Fix: Bump the hook timeout from 5s to 8s in ~/.claude/settings.json. If persistent, restart
+    the watcher to clear memory bloat: `systemctl --user restart clawmem-watcher.service`.
 ```
 
 ## CLI Reference

package/README.md

@@ -1,4 +1,4 @@
-# ClawMem — Context engine for Claude Code and AI agents
+# ClawMem — Context engine for Claude Code and OpenClaw agents
 
 <p align="center">
   <img src="docs/clawmem_hero.jpg" alt="ClawMem" width="100%">
@@ -8,7 +8,7 @@
 
 ClawMem fuses recent research into a retrieval-augmented memory layer that agents actually use. The hybrid architecture combines [QMD](https://github.com/tobi/qmd)-derived multi-signal retrieval (BM25 + vector search + reciprocal rank fusion + query expansion + cross-encoder reranking), [SAME](https://github.com/sgx-labs/statelessagent)-inspired composite scoring (recency decay, confidence, content-type half-lives, co-activation reinforcement), [MAGMA](https://arxiv.org/abs/2501.13956)-style intent classification with multi-graph traversal (semantic, temporal, and causal beam search), and [A-MEM](https://arxiv.org/abs/2510.02178) self-evolving memory notes that enrich documents with keywords, tags, and causal links between entries. Pattern extraction from [Engram](https://github.com/Gentleman-Programming/engram) adds deduplication windows, frequency-based durability scoring, and temporal navigation.
 
-Two integration paths: Claude Code hooks paired with an MCP server, or a native OpenClaw ContextEngine plugin. Both write to the same local SQLite vault. A decision captured during a Claude Code session shows up immediately when an OpenClaw agent picks up the same project.
+Integrates via Claude Code hooks, an MCP server (works with any MCP-compatible client including OpenClaw), or a native OpenClaw ContextEngine plugin. All paths write to the same local SQLite vault. A decision captured during a Claude Code session shows up immediately when an OpenClaw agent picks up the same project.
 
 TypeScript on Bun. MIT License.
 
@@ -61,19 +61,32 @@ Runs fully local with no API keys and no cloud services. Integrates via Claude C
 
 ### Prerequisites
 
-- [Bun](https://bun.sh) v1.0+
-- SQLite with FTS5 support (included with Bun)
+**Required:**
 
-### Install via npm (recommended)
+- [Bun](https://bun.sh) v1.0+ — runtime for ClawMem
+- SQLite with FTS5 — included with Bun. On macOS, install `brew install sqlite` for extension loading support (ClawMem detects and uses Homebrew SQLite automatically).
+
+**Optional (for better performance):**
+
+- [llama.cpp](https://github.com/ggml-org/llama.cpp) (`llama-server`) — for dedicated GPU inference. Without it, `node-llama-cpp` runs models in-process (auto-downloads on first use). GPU servers give better throughput and prevent silent CPU fallback.
+- systemd (Linux) or launchd (macOS) — for persistent background services (watcher, embed timer, GPU servers). ClawMem ships systemd unit templates; macOS users can create equivalent launchd plists. See [systemd services](docs/guides/systemd-services.md).
+
+**Optional integrations:**
+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — for hooks + MCP integration
+- [OpenClaw](https://github.com/openclawai/openclaw) — for ContextEngine plugin integration
+- [bd CLI](https://github.com/dolthub/dolt) v0.58.0+ — for Beads issue tracker sync (only if using Beads)
+
+### Install from npm (recommended)
 
 ```bash
-bun add -g clawmem
+npm install -g clawmem
 ```
 
-Or with npm:
+If you use Bun as your package manager:
 
 ```bash
-npm install -g clawmem
+bun add -g clawmem
 ```
 
 ### Install from source
@@ -84,20 +97,44 @@ cd ~/clawmem && bun install
 ln -sf ~/clawmem/bin/clawmem ~/.bun/bin/clawmem
 ```
 
-### Quick Start (Bootstrap)
+### Setup roadmap
+
+After installing, here's the full journey from zero to working memory:
 
-One command to set up a vault:
+| Step | What | How | Details |
+|------|------|-----|---------|
+| **1. Bootstrap** | Create a vault, index your first collection, embed, install hooks and MCP | `clawmem bootstrap ~/notes --name notes` | One command does it all. Or run each step manually (see below). |
+| **2. Choose models** | Pick embedding + reranker models based on your hardware | 12GB+ VRAM → SOTA stack (zembed-1 + zerank-2). Less → QMD native combo. No GPU → cloud embedding or CPU fallback. | [GPU Services](#gpu-services) |
+| **3. Download models** | Get the GGUF files for your chosen stack | `wget` from HuggingFace, or let `node-llama-cpp` auto-download the QMD native models on first use | [Embedding](#embedding), [LLM Server](#llm-server), [Reranker Server](#reranker-server) |
+| **4. Start services** | Run GPU servers (if using dedicated GPU) and background services | `llama-server` for each model. systemd units for watcher + embed timer. | [systemd services](docs/guides/systemd-services.md) |
+| **5. Decide what to index** | Add collections for your projects, notes, research, and domain docs | `clawmem collection add ~/project --name project` | The more relevant markdown you index, the better retrieval works. See [building a rich context field](docs/introduction.md#building-a-rich-context-field). |
+| **6. Connect your agent** | Hook into Claude Code, OpenClaw, or any MCP client | `clawmem setup hooks && clawmem setup mcp` for Claude Code. `clawmem setup openclaw` for OpenClaw. | [Integration](#integration) |
+| **7. Verify** | Confirm everything is working | `clawmem doctor` (full health check) or `clawmem status` (quick index stats) | [Verify Installation](#verify-installation) |
+
+**Fastest path:** Step 1 alone gets you a working system with in-process CPU/GPU inference and default models — no manual model downloads or service configuration needed. Steps 2-4 are optional upgrades for better performance. Steps 5-6 are where you customize what gets indexed and how your agent connects.
+
+**Customize what gets indexed:** Each collection has a `pattern` field in `~/.config/clawmem/config.yaml` (default: `**/*.md`). Tailor it per collection — index project docs, research notes, decision records, Obsidian vaults, or anything else your agents should know about. The more relevant content in the vault, the better retrieval works. See the [quickstart](docs/quickstart.md#customize-index-patterns) for config examples.
+
+### Quick start commands
 
 ```bash
-# Initialize, index, embed, install hooks, register MCP
-./bin/clawmem bootstrap ~/notes --name notes
+# One command: init + index + embed + hooks + MCP
+clawmem bootstrap ~/notes --name notes
 
 # Or step by step:
-./bin/clawmem init
-./bin/clawmem collection add ~/notes --name notes
-./bin/clawmem update --embed
-./bin/clawmem setup hooks
-./bin/clawmem setup mcp
+clawmem init
+clawmem collection add ~/notes --name notes
+clawmem update --embed
+clawmem setup hooks
+clawmem setup mcp
+
+# Add more collections (the more you index, the richer retrieval gets)
+clawmem collection add ~/projects/myapp --name myapp
+clawmem collection add ~/research --name research
+clawmem update --embed
+
+# Verify
+clawmem doctor
 ```
 
 ### Integration
@@ -108,7 +145,7 @@ ClawMem integrates via hooks (`settings.json`) and an MCP stdio server. Hooks ha
 
 ```bash
 clawmem setup hooks    # Install lifecycle hooks (SessionStart, UserPromptSubmit, Stop, PreCompact)
-clawmem setup mcp      # Register MCP server in ~/.claude.json (20+ agent tools)
+clawmem setup mcp      # Register MCP server in ~/.claude.json (28 tools)
 ```
 
 **Automatic (90%):** `context-surfacing` injects relevant memory on every prompt. `postcompact-inject` re-injects state after compaction. `decision-extractor`, `handoff-generator`, `feedback-loop` capture session state on stop.
@@ -135,7 +172,7 @@ Disable OpenClaw's native memory and `memory-lancedb` auto-recall/capture to avo
 openclaw config set agents.defaults.memorySearch.extraPaths "[]"
 ```
 
-**Alternative:** You can also use the Claude Code-style hooks + MCP approach with OpenClaw (`clawmem setup hooks && clawmem setup mcp`). This works but bypasses OpenClaw's ContextEngine lifecycle - you lose token budget awareness, native compaction orchestration, and the `afterTurn()` message pipeline. The ContextEngine plugin is recommended for new OpenClaw setups.
+**Alternative:** OpenClaw agents can also use ClawMem's MCP server directly (`clawmem setup mcp`), with or without hooks. This gives full access to all 28 MCP tools but bypasses OpenClaw's ContextEngine lifecycle, so you lose token budget awareness, native compaction orchestration, and the `afterTurn()` message pipeline. The ContextEngine plugin is recommended for new OpenClaw setups; MCP is available as an additional or standalone integration.
 
 #### Dual-Mode Operation
 
@@ -366,7 +403,7 @@ llama-server -m Qwen3-Reranker-0.6B-Q8_0.gguf \
 
 ### MCP Server
 
-ClawMem exposes 26 MCP tools via the [Model Context Protocol](https://modelcontextprotocol.io) and an optional HTTP REST API. Any MCP-compatible client or HTTP client can use it.
+ClawMem exposes 28 MCP tools via the [Model Context Protocol](https://modelcontextprotocol.io) and an optional HTTP REST API. Any MCP-compatible client or HTTP client can use it.
 
 **Claude Code (automatic):**
 
@@ -453,7 +490,7 @@ ClawMem ships three instruction files and an optional maintenance agent:
 |------|--------|---------|
 | `CLAUDE.md` | Automatically (Claude Code, when working in this repo) | Complete operational reference — hooks, tools, query optimization, scoring, pipeline details, troubleshooting |
 | `AGENTS.md` | Framework-dependent | Identical to CLAUDE.md — cross-framework compatibility (Cursor, Windsurf, Codex, etc.) |
-| `SKILL.md` | On-demand via Claude Code skill system | Same reference as CLAUDE.md, available across all projects |
+| `SKILL.md` | On-demand (agent reads when needed) | Same reference as CLAUDE.md, shipped with the package for cross-project use |
 | `agents/clawmem-curator.md` | On-demand via `clawmem setup curator` | Maintenance agent — lifecycle triage, retrieval health checks, dedup sweeps, graph rebuilds |
 
 **Working in the ClawMem repo:** No action needed — `CLAUDE.md` loads automatically.
@@ -464,16 +501,9 @@ ClawMem ships three instruction files and an optional maintenance agent:
 
 Copy the contents of `CLAUDE.md` (or the relevant sections) into your project's own `CLAUDE.md` or `AGENTS.md`. Simple but requires manual updates when ClawMem changes.
 
-### Option B: Install as a skill (recommended)
-
-Symlink ClawMem into Claude Code's skill directory for on-demand reference across all projects:
-
-```bash
-mkdir -p ~/.claude/skills
-ln -sf ~/clawmem ~/.claude/skills/clawmem
-```
+### Option B: Add a trigger block (recommended)
 
-Then add this minimal trigger block to your global `~/.claude/CLAUDE.md`:
+Add this minimal trigger block to your global `~/.claude/CLAUDE.md`. It gives the agent routing rules always loaded, and tells it how to find the full reference (SKILL.md) shipped with your installation when deeper guidance is needed:
 
 ```markdown
 ## ClawMem
@@ -525,15 +555,12 @@ ALWAYS `compact=true` first → review → `multi_get` for full content.
 - Do NOT forget memories to "clean up" — let confidence decay handle it
 - Do NOT wait for curator to pin decisions — pin immediately when critical
 
-Invoke `Skill tool with skill="clawmem"` when:
-- Retrieval quality is poor or results miss expected content (query optimization, troubleshooting)
-- Adding new content directories or indexing something (collection setup, embedding workflow)
-- After bulk document creation or ingestion (graph building, embedding)
-- Need lifecycle triage beyond basic status/sweep (run curator: "curate memory")
-- Any operation beyond the basic tool routing above
+For detailed operational guidance (query optimization, troubleshooting, collection setup, embedding workflow, graph building, curator), find and read the shipped SKILL.md:
+  Bash: CLAWMEM_ROOT=$(cd "$(dirname "$(which clawmem)")/.." && pwd) && echo "$CLAWMEM_ROOT/SKILL.md"
+  Then: Read the file at that path.
 ```
 
-This gives your agent the 3-rule gate, tool routing, and proactive behaviors always loaded, with situation-triggered skill invocation for the ~10% manual operations.
+This gives your agent the 3-rule gate, tool routing, and proactive behaviors always loaded. When it needs deeper guidance, it locates and reads the full SKILL.md reference shipped with your installation — no symlinks or skill registration required.
 
 ---
 

package/SKILL.md

@@ -630,6 +630,13 @@ Symptom: reindex --force crashes with UNIQUE constraint
 Symptom: CLI reindex/update falls back to node-llama-cpp
   -> GPU env vars only in systemd drop-in, not in wrapper script.
   -> Fixed: bin/clawmem wrapper exports CLAWMEM_EMBED_URL/LLM_URL/RERANK_URL defaults.
+
+Symptom: "UserPromptSubmit hook error" on context-surfacing hook (intermittent)
+  -> SQLite contention between watcher and hook. Watcher processes filesystem events (including
+     non-.md files like session .jsonl transcripts) and holds brief write locks. If the hook fires
+     during a lock, it can exceed its timeout. More likely during active conversations.
+  -> Fix: Bump hook timeout from 5s to 8s in ~/.claude/settings.json. If persistent, restart
+     the watcher: `systemctl --user restart clawmem-watcher.service`.
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "On-device context engine and memory for AI agents. Claude Code and OpenClaw. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {

package/src/clawmem.ts

@@ -976,7 +976,7 @@ async function cmdSetupHooks(args: string[]) {
 
     // Timeout per event type (seconds)
     const timeouts: Record<string, number> = {
-      UserPromptSubmit: 5,
+      UserPromptSubmit: 8,
       SessionStart: 5,
       PreCompact: 5,
       Stop: 10,