clawmem 0.1.0 → 0.1.1

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%">
@@ -64,16 +64,16 @@ Runs fully local with no API keys and no cloud services. Integrates via Claude C
 - [Bun](https://bun.sh) v1.0+
 - SQLite with FTS5 support (included with Bun)
 
-### Install via npm (recommended)
+### 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 +84,42 @@ 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:
+
+| 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.
 
-One command to set up a vault:
+### 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
@@ -453,7 +475,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 +486,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 +540,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.1",
   "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,