clawmem 0.3.4 → 0.4.2

package/AGENTS.md

@@ -620,6 +620,13 @@ Symptom: reindex --force after v0.2.0 upgrade shows no entity extraction
   → `--force` alone only refreshes A-MEM notes (keywords, tags, context). `--enrich`
     is needed after major upgrades that add new enrichment stages.
 
+Symptom: `clawmem update` crashes with "Binding expected string, TypedArray, boolean, number, bigint or null"
+  → YAML frontmatter values like `title: 2023-09-27` or `title: true` are coerced by gray-matter
+    into Date objects or booleans. Bun's SQLite driver rejects these as bind parameters.
+  → Fixed v0.4.2: `parseDocument()` runtime-checks all frontmatter fields via `str()` helper.
+    Defense-in-depth `safeTitle` guards in `insertDocument`/`updateDocument`/`reactivateDocument`.
+  → Affects: title, domain, workstream, content_type, review_by — any field gray-matter can coerce.
+
 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.
@@ -685,3 +692,4 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
 - OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw context engine. Uses `before_prompt_build` for retrieval (prompt-aware), `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation. Shares same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
 - **OpenClaw v2026.3.28+ compaction fix (v0.3.0):** `compact()` now delegates to OpenClaw's runtime compactor via `delegateCompactionToRuntime()` from `openclaw/plugin-sdk/core`. Previous versions returned `compacted: false` expecting legacy fallback — that fallback no longer exists. Without this fix, sessions never compact. Bootstrap context is now cached in `bootstrap()` and consumed once in `before_prompt_build`, eliminating duplicate hook invocations.
+- Hermes Agent MemoryProvider plugin: `src/hermes/` — Python plugin implementing Hermes's `MemoryProvider` ABC. Symlink or copy into `hermes-agent/plugins/memory/clawmem/`. Uses shell-out for lifecycle hooks (session-bootstrap, context-surfacing, extraction) and REST API for tools (retrieve, get, session_log, timeline, similar). Plugin manages its own transcript JSONL for ClawMem hooks. Supports external (you run `clawmem serve`) and managed (plugin starts/stops serve) modes.

package/CLAUDE.md

@@ -620,6 +620,13 @@ Symptom: reindex --force after v0.2.0 upgrade shows no entity extraction
   → `--force` alone only refreshes A-MEM notes (keywords, tags, context). `--enrich`
     is needed after major upgrades that add new enrichment stages.
 
+Symptom: `clawmem update` crashes with "Binding expected string, TypedArray, boolean, number, bigint or null"
+  → YAML frontmatter values like `title: 2023-09-27` or `title: true` are coerced by gray-matter
+    into Date objects or booleans. Bun's SQLite driver rejects these as bind parameters.
+  → Fixed v0.4.2: `parseDocument()` runtime-checks all frontmatter fields via `str()` helper.
+    Defense-in-depth `safeTitle` guards in `insertDocument`/`updateDocument`/`reactivateDocument`.
+  → Affects: title, domain, workstream, content_type, review_by — any field gray-matter can coerce.
+
 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.
@@ -685,3 +692,4 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
 - OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers ClawMem as a native OpenClaw context engine. Uses `before_prompt_build` for retrieval (prompt-aware), `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation. Shares same vault as Claude Code hooks (dual-mode). SQLite busy_timeout=5000ms for concurrent access safety.
 - **OpenClaw v2026.3.28+ compaction fix (v0.3.0):** `compact()` now delegates to OpenClaw's runtime compactor via `delegateCompactionToRuntime()` from `openclaw/plugin-sdk/core`. Previous versions returned `compacted: false` expecting legacy fallback — that fallback no longer exists. Without this fix, sessions never compact. Bootstrap context is now cached in `bootstrap()` and consumed once in `before_prompt_build`, eliminating duplicate hook invocations.
+- Hermes Agent MemoryProvider plugin: `src/hermes/` — Python plugin implementing Hermes's `MemoryProvider` ABC. Symlink or copy into `hermes-agent/plugins/memory/clawmem/`. Uses shell-out for lifecycle hooks (session-bootstrap, context-surfacing, extraction) and REST API for tools (retrieve, get, session_log, timeline, similar). Plugin manages its own transcript JSONL for ClawMem hooks. Supports external (you run `clawmem serve`) and managed (plugin starts/stops serve) modes.

package/README.md

@@ -1,14 +1,14 @@
-# ClawMem — Context engine for Claude Code and OpenClaw agents
+# ClawMem — Context engine for Claude Code, OpenClaw, and Hermes agents
 
 <p align="center">
   <img src="docs/clawmem_hero.jpg" alt="ClawMem" width="100%">
 </p>
 
-**On-device memory for Claude Code and AI agents.** Retrieval-augmented search, hooks, and an MCP server in a single local system. No API keys, no cloud dependencies.
+**On-device memory for Claude Code, OpenClaw, Hermes, and AI agents.** Retrieval-augmented search, hooks, and an MCP server in a single local system. No API keys, no cloud dependencies.
 
 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.
 
-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.
+Integrates via Claude Code hooks, an MCP server (works with any MCP-compatible client), a native OpenClaw ContextEngine plugin, or a Hermes Agent MemoryProvider plugin. All paths write to the same local SQLite vault. A decision captured during a Claude Code session shows up immediately when an OpenClaw or Hermes agent picks up the same project.
 
 TypeScript on Bun. MIT License.
 
@@ -40,7 +40,7 @@ ClawMem turns your markdown notes, project docs, and research dumps into persist
 - **Auto-routes queries** via `memory_retrieve` — classifies intent and dispatches to the optimal search backend
 - **Syncs project issues** from Beads issue trackers into searchable memory
 
-Runs fully local with no API keys and no cloud services. Integrates via Claude Code hooks and MCP tools, or as an OpenClaw ContextEngine plugin. Both modes share the same vault for cross-runtime memory. Works with any MCP-compatible client.
+Runs fully local with no API keys and no cloud services. Integrates via Claude Code hooks and MCP tools, as an OpenClaw ContextEngine plugin, or as a Hermes Agent MemoryProvider plugin. All modes share the same vault for cross-runtime memory. Works with any MCP-compatible client.
 
 ### v0.2.0 Enhancements
 
@@ -85,6 +85,7 @@ Runs fully local with no API keys and no cloud services. Integrates via Claude C
 
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — for hooks + MCP integration
 - [OpenClaw](https://github.com/openclawai/openclaw) — for ContextEngine plugin integration
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — for MemoryProvider 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)
@@ -118,7 +119,7 @@ After installing, here's the full journey from zero to working memory:
 | **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) |
+| **6. Connect your agent** | Hook into Claude Code, OpenClaw, Hermes, or any MCP client | `clawmem setup hooks && clawmem setup mcp` for Claude Code. `clawmem setup openclaw` for OpenClaw. Copy `src/hermes/` to Hermes plugins for Hermes. | [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.
@@ -203,9 +204,48 @@ openclaw config set agents.defaults.memorySearch.extraPaths "[]"
 
 **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
+#### Hermes Agent
 
-Both integrations share the same SQLite vault by default. Claude Code and OpenClaw can run simultaneously - decisions captured in one runtime are immediately available in the other, giving agents persistent shared memory across sessions and platforms. WAL mode + busy_timeout handles concurrent access.
+ClawMem integrates as a native MemoryProvider plugin — Hermes's pluggable interface for agent memory. Same automatic retrieval and extraction, delivered through Hermes's memory lifecycle instead of Claude Code hooks.
+
+**Install:**
+
+```bash
+# Copy or symlink the plugin into Hermes's plugin directory
+cp -r /path/to/ClawMem/src/hermes /path/to/hermes-agent/plugins/memory/clawmem
+
+# Or symlink for development
+ln -s /path/to/ClawMem/src/hermes /path/to/hermes-agent/plugins/memory/clawmem
+```
+
+**Configure** in your Hermes profile's `.env` or environment:
+```bash
+CLAWMEM_BIN=/path/to/clawmem          # Path to clawmem binary (or ensure it's on PATH)
+CLAWMEM_SERVE_PORT=7438                # REST API port (default: 7438)
+CLAWMEM_SERVE_MODE=external            # "external" (you run clawmem serve) or "managed" (plugin manages it)
+CLAWMEM_PROFILE=balanced               # speed | balanced | deep
+```
+
+Then set `memory.provider: clawmem` in your Hermes `config.yaml`, or run `hermes memory setup` to configure interactively.
+
+**What the plugin provides:**
+
+- **`prefetch()`** — prompt-aware retrieval via `context-surfacing` hook (automatic every turn)
+- **`on_session_end()`** — decision extraction, handoff generation, feedback loop (parallel)
+- **`on_pre_compress()`** — pre-compaction state preservation
+- **`session-bootstrap`** — session registration + first-turn context injection
+- **5 agent tools** — `clawmem_retrieve`, `clawmem_get`, `clawmem_session_log`, `clawmem_timeline`, `clawmem_similar`
+- **Plugin-managed transcript** — maintains its own JSONL transcript for ClawMem hooks
+
+**Requirements:** `clawmem` binary on PATH and `clawmem serve` running (external mode) or the plugin starts it automatically (managed mode). Python 3.10+. No pip dependencies beyond Hermes itself (uses `urllib` for REST calls, `httpx` optional for better performance).
+
+**Alternative:** Hermes also has built-in MCP client support. You can add ClawMem as an MCP server in Hermes's `config.yaml` under `mcp_servers` for tool-only access. But this misses the lifecycle hooks (prefetch, session_end, pre_compress), so the native plugin is recommended.
+
+See [Hermes plugin guide](docs/guides/hermes-plugin.md) for architecture details, lifecycle mapping, and troubleshooting.
+
+#### Multi-Framework Operation
+
+All three integrations share the same SQLite vault by default. Claude Code, OpenClaw, and Hermes can run simultaneously — decisions captured in one runtime are immediately available in the others, giving agents persistent shared memory across sessions and platforms. WAL mode + busy_timeout handles concurrent access.
 
 #### Multi-Vault (Optional)
 
@@ -1020,6 +1060,24 @@ Manual layers benefit from periodic re-indexing — a cron job running `clawmem
 ./bin/clawmem bootstrap ~/.openclaw/workspace --name workspace
 ```
 
+#### Hermes-Specific
+
+```bash
+# Hermes uses ~/.hermes/ as its home directory
+./bin/clawmem bootstrap ~/.hermes --name hermes-home
+
+# Install the memory provider plugin
+cp -r src/hermes /path/to/hermes-agent/plugins/memory/clawmem
+
+# Start clawmem serve (external mode)
+clawmem serve --port 7438 &
+
+# Configure Hermes to use ClawMem
+# In your Hermes config.yaml:
+#   memory:
+#     provider: clawmem
+```
+
 ## Dependencies
 
 | Package | Purpose |
@@ -1045,7 +1103,7 @@ Built on the shoulders of:
 - [Beads](https://github.com/steveyegge/beads) — Dolt-backed issue tracker for AI agents
 - [claude-mem](https://github.com/thedotmack/claude-mem) — Claude Code memory integration reference
 - [Engram](https://github.com/Gentleman-Programming/engram) — observation dedup window, topic-key upsert pattern, temporal timeline navigation, duplicate metadata scoring signals
-- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — memory nudge system (periodic lifecycle tool prompting)
+- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — MemoryProvider plugin integration, memory nudge system (periodic lifecycle tool prompting)
 - [Hindsight](https://github.com/vectorize-io/hindsight) — entity resolution, MPFP graph traversal, temporal extraction, 3-tier consolidation, observation invalidation, 4-way parallel retrieval
 - [MAGMA](https://arxiv.org/abs/2501.13956) — multi-graph memory agent
 - [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) — retrieval gate, length normalization, MMR diversity, access reinforcement algorithms

package/SKILL.md

@@ -598,6 +598,30 @@ openclaw config set agents.defaults.memorySearch.extraPaths '["~/documents", "~/
 
 ---
 
+## Hermes Agent Integration
+
+### Install
+
+Copy or symlink `src/hermes/` into `hermes-agent/plugins/memory/clawmem/`. Set `memory.provider: clawmem` in Hermes config.
+
+### How it works
+
+Plugin implements Hermes's `MemoryProvider` ABC:
+- `prefetch()` — context-surfacing hook (automatic per turn)
+- `on_session_end()` — extraction hooks in parallel (decision-extractor, handoff-generator, feedback-loop)
+- `on_pre_compress()` — precompact-extract (side effect only)
+- 5 agent tools via REST: `clawmem_retrieve`, `clawmem_get`, `clawmem_session_log`, `clawmem_timeline`, `clawmem_similar`
+
+### Key difference from OpenClaw/Claude Code
+
+Hermes passes turn pairs, not transcript files. The plugin maintains its own JSONL transcript at `$HERMES_HOME/clawmem-transcripts/<session_id>.jsonl` so ClawMem hooks can read it.
+
+### Requirements
+
+`clawmem` binary on PATH + `clawmem serve` running (external) or `CLAWMEM_SERVE_MODE=managed`. Python 3.10+.
+
+---
+
 ## Troubleshooting
 
 ```
@@ -707,6 +731,7 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
 - Beads integration: `syncBeadsIssues()` queries `bd` CLI (Dolt backend, v0.58.0+), creates markdown docs, maps dependency edges into `memory_relations`. Watcher auto-triggers on `.beads/` changes; `beads_sync` MCP for manual sync.
 - HTTP REST API: `clawmem serve [--port 7438]` — optional REST server on localhost. Search, retrieval, lifecycle, and graph traversal. `POST /retrieve` mirrors `memory_retrieve` with auto-routing (keyword/semantic/causal/timeline/hybrid). `POST /search` provides direct mode selection. Bearer token auth via `CLAWMEM_API_TOKEN` env var (disabled if unset).
 - OpenClaw ContextEngine plugin: `clawmem setup openclaw` — registers as native OpenClaw context engine. Dual-mode: shares vault with Claude Code hooks. Uses `before_prompt_build` for retrieval, `afterTurn()` for extraction, `compact()` for pre-compaction + runtime delegation (v0.3.0+, required for OpenClaw v2026.3.28+).
+- Hermes Agent MemoryProvider plugin: `src/hermes/` — Python plugin for Hermes's memory system. Shell-out hooks for lifecycle (prefetch, extraction, precompact), REST API for tools. Plugin-managed transcript JSONL bridges Hermes turn pairs to ClawMem file format. Shares vault with Claude Code and OpenClaw.
 
 ## Tool Selection (one-liner)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.3.4",
+  "version": "0.4.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/hermes/__init__.py

@@ -0,0 +1,611 @@
+"""ClawMem memory provider plugin for Hermes Agent.
+
+On-device hybrid memory with composite scoring, graph traversal, and
+lifecycle management. Integrates via REST API (tools) and CLI shell-out
+(lifecycle hooks).
+
+Requires:
+  - clawmem binary on PATH (or configured via CLAWMEM_BIN)
+  - clawmem serve running (or managed mode starts it automatically)
+
+Config via environment variables:
+  CLAWMEM_BIN           — Path to clawmem binary (default: auto-detect on PATH)
+  CLAWMEM_SERVE_PORT    — REST API port (default: 7438)
+  CLAWMEM_SERVE_MODE    — "external" (default) or "managed" (plugin starts/stops serve)
+  CLAWMEM_PROFILE       — Retrieval profile: speed, balanced, deep (default: balanced)
+  CLAWMEM_EMBED_URL     — GPU embedding server URL (optional)
+  CLAWMEM_LLM_URL       — GPU LLM server URL (optional)
+  CLAWMEM_RERANK_URL    — GPU reranker server URL (optional)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+import threading
+import time
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from agent.memory_provider import MemoryProvider
+
+logger = logging.getLogger(__name__)
+
+_DEFAULT_PORT = 7438
+_HOOK_TIMEOUT = 30  # seconds
+_REST_TIMEOUT = 5.0  # seconds
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _find_clawmem_bin() -> Optional[str]:
+    """Find the clawmem binary. Check env, then PATH."""
+    env_bin = os.environ.get("CLAWMEM_BIN")
+    if env_bin and os.path.isfile(env_bin) and os.access(env_bin, os.X_OK):
+        return env_bin
+    return shutil.which("clawmem")
+
+
+def _run_hook(bin_path: str, hook_name: str, hook_input: dict,
+              timeout: int = _HOOK_TIMEOUT, env_extra: Optional[dict] = None) -> Optional[str]:
+    """Shell out to clawmem hook <name>. Returns stdout or None on failure."""
+    try:
+        env = {**os.environ, **(env_extra or {})}
+        result = subprocess.run(
+            [bin_path, "hook", hook_name],
+            input=json.dumps(hook_input),
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=env,
+        )
+        if result.returncode == 0:
+            return result.stdout
+        logger.debug("clawmem hook %s exited %d: %s", hook_name, result.returncode, result.stderr)
+        return None
+    except subprocess.TimeoutExpired:
+        logger.debug("clawmem hook %s timed out after %ds", hook_name, timeout)
+        return None
+    except Exception as e:
+        logger.debug("clawmem hook %s failed: %s", hook_name, e)
+        return None
+
+
+def _rest_call(port: int, method: str, path: str,
+               body: Optional[dict] = None, timeout: float = _REST_TIMEOUT) -> Optional[dict]:
+    """Call the ClawMem REST API. Returns parsed JSON or None."""
+    headers: dict = {"Content-Type": "application/json"}
+    token = os.environ.get("CLAWMEM_API_TOKEN")
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+
+    try:
+        import httpx
+    except ImportError:
+        # Fallback to urllib for zero-dependency operation
+        import urllib.request
+        import urllib.error
+        url = f"http://127.0.0.1:{port}{path}"
+        req = urllib.request.Request(
+            url,
+            data=json.dumps(body).encode() if body else None,
+            headers=headers,
+            method=method,
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return json.loads(resp.read().decode())
+        except (urllib.error.URLError, Exception) as e:
+            logger.debug("ClawMem REST %s %s failed: %s", method, path, e)
+            return None
+
+    try:
+        client = httpx.Client(timeout=timeout)
+        if method == "GET":
+            resp = client.get(f"http://127.0.0.1:{port}{path}", headers=headers)
+        else:
+            resp = client.post(
+                f"http://127.0.0.1:{port}{path}",
+                json=body or {},
+                headers=headers,
+            )
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as e:
+        logger.debug("ClawMem REST %s %s failed: %s", method, path, e)
+        return None
+
+
+def _extract_context(hook_output: str) -> str:
+    """Extract additionalContext from hook JSON output."""
+    if not hook_output:
+        return ""
+    try:
+        parsed = json.loads(hook_output.strip().split("\n")[-1])
+        hso = parsed.get("hookSpecificOutput", {})
+        return hso.get("additionalContext", "")
+    except (json.JSONDecodeError, IndexError):
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# Tool schemas
+# ---------------------------------------------------------------------------
+
+RETRIEVE_SCHEMA = {
+    "name": "clawmem_retrieve",
+    "description": (
+        "Search long-term memory with auto-routing. Handles keyword, semantic, "
+        "causal, and timeline queries automatically. Use for recalling past "
+        "decisions, preferences, session history, and learned patterns."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "query": {"type": "string", "description": "Search query."},
+            "limit": {"type": "integer", "description": "Max results (default: 10)."},
+        },
+        "required": ["query"],
+    },
+}
+
+GET_SCHEMA = {
+    "name": "clawmem_get",
+    "description": (
+        "Retrieve full content of a memory document by its docid (6-char hex prefix)."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "docid": {"type": "string", "description": "Document ID (6-char hex prefix)."},
+        },
+        "required": ["docid"],
+    },
+}
+
+SESSION_LOG_SCHEMA = {
+    "name": "clawmem_session_log",
+    "description": "List recent session summaries for cross-session context.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "limit": {"type": "integer", "description": "Number of sessions (default: 5)."},
+        },
+    },
+}
+
+TIMELINE_SCHEMA = {
+    "name": "clawmem_timeline",
+    "description": "Show temporal context around a document — what was created before and after.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "docid": {"type": "string", "description": "Document ID (6-char hex prefix)."},
+            "before": {"type": "integer", "description": "Docs before (default: 5)."},
+            "after": {"type": "integer", "description": "Docs after (default: 5)."},
+        },
+        "required": ["docid"],
+    },
+}
+
+SIMILAR_SCHEMA = {
+    "name": "clawmem_similar",
+    "description": "Find documents semantically similar to a given document.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "docid": {"type": "string", "description": "Document ID (6-char hex prefix)."},
+            "limit": {"type": "integer", "description": "Max results (default: 5)."},
+        },
+        "required": ["docid"],
+    },
+}
+
+
+# ---------------------------------------------------------------------------
+# MemoryProvider implementation
+# ---------------------------------------------------------------------------
+
+class ClawMemProvider(MemoryProvider):
+    """ClawMem memory provider for Hermes Agent."""
+
+    def __init__(self):
+        self._bin: Optional[str] = None
+        self._port: int = _DEFAULT_PORT
+        self._session_id: str = ""
+        self._transcript_path: str = ""
+        self._hermes_home: str = ""
+        self._serve_mode: str = "external"
+        self._serve_proc: Optional[subprocess.Popen] = None
+        self._env_extra: dict = {}
+
+        # Prefetch state (generation counter prevents stale overwrites)
+        self._prefetch_result: str = ""
+        self._prefetch_result_gen: int = 0  # generation of stored result
+        self._prefetch_generation: int = 0  # latest queued generation
+        self._prefetch_consumed_gen: int = 0  # last generation consumed by prefetch()
+        self._prefetch_lock = threading.Lock()
+        self._prefetch_thread: Optional[threading.Thread] = None
+
+        # Bootstrap context (consumed on first prefetch)
+        self._bootstrap_context: str = ""
+
+    @property
+    def name(self) -> str:
+        return "clawmem"
+
+    # -- Config ----------------------------------------------------------------
+
+    def get_config_schema(self) -> List[Dict[str, Any]]:
+        return [
+            {
+                "key": "serve_port",
+                "description": "ClawMem REST API port",
+                "default": str(_DEFAULT_PORT),
+                "env_var": "CLAWMEM_SERVE_PORT",
+            },
+            {
+                "key": "serve_mode",
+                "description": "Server mode: 'external' (you run clawmem serve) or 'managed' (plugin manages it)",
+                "default": "external",
+                "choices": ["external", "managed"],
+                "env_var": "CLAWMEM_SERVE_MODE",
+            },
+            {
+                "key": "profile",
+                "description": "Retrieval profile: speed (BM25 only), balanced (hybrid), deep (full pipeline)",
+                "default": "balanced",
+                "choices": ["speed", "balanced", "deep"],
+                "env_var": "CLAWMEM_PROFILE",
+            },
+            {
+                "key": "bin_path",
+                "description": "Path to clawmem binary (auto-detected if on PATH)",
+                "env_var": "CLAWMEM_BIN",
+            },
+            {
+                "key": "embed_url",
+                "description": "GPU embedding server URL (e.g., http://localhost:8088)",
+                "secret": False,
+                "env_var": "CLAWMEM_EMBED_URL",
+            },
+            {
+                "key": "llm_url",
+                "description": "GPU LLM server URL (e.g., http://localhost:8089)",
+                "secret": False,
+                "env_var": "CLAWMEM_LLM_URL",
+            },
+        ]
+
+    # -- Core lifecycle --------------------------------------------------------
+
+    def is_available(self) -> bool:
+        """Check if clawmem binary is on PATH. No network calls."""
+        return _find_clawmem_bin() is not None
+
+    def initialize(self, session_id: str, **kwargs) -> None:
+        self._bin = _find_clawmem_bin()
+        if not self._bin:
+            logger.warning("clawmem binary not found on PATH — provider disabled")
+            return
+
+        self._session_id = session_id
+        try:
+            self._port = int(os.environ.get("CLAWMEM_SERVE_PORT", _DEFAULT_PORT))
+        except (ValueError, TypeError):
+            self._port = _DEFAULT_PORT
+        self._serve_mode = os.environ.get("CLAWMEM_SERVE_MODE", "external")
+        self._hermes_home = kwargs.get("hermes_home", str(Path.home() / ".hermes"))
+
+        # Build env for hook shell-outs (GPU endpoints, profile)
+        for var in ("CLAWMEM_EMBED_URL", "CLAWMEM_LLM_URL", "CLAWMEM_RERANK_URL", "CLAWMEM_PROFILE"):
+            val = os.environ.get(var)
+            if val:
+                self._env_extra[var] = val
+
+        # Create transcript directory
+        transcript_dir = Path(self._hermes_home) / "clawmem-transcripts"
+        transcript_dir.mkdir(parents=True, exist_ok=True)
+        self._transcript_path = str(transcript_dir / f"{session_id}.jsonl")
+
+        # Start managed serve if configured
+        if self._serve_mode == "managed":
+            self._start_serve()
+
+        # Run session-bootstrap hook
+        hook_input = {
+            "session_id": session_id,
+            "transcript_path": self._transcript_path,
+            "hook_event_name": "SessionStart",
+        }
+        output = _run_hook(self._bin, "session-bootstrap", hook_input, env_extra=self._env_extra)
+        if output:
+            ctx = _extract_context(output)
+            if ctx:
+                self._bootstrap_context = ctx
+                logger.info("clawmem: session-bootstrap returned %d chars of context", len(ctx))
+
+    def system_prompt_block(self) -> str:
+        if not self._bin:
+            return ""
+        return (
+            "# ClawMem Memory System\n"
+            "Active. Use clawmem_retrieve to search memory, clawmem_get for "
+            "full documents, clawmem_session_log for session history, "
+            "clawmem_timeline for temporal context, clawmem_similar for discovery."
+        )
+
+    # -- Prefetch / recall -----------------------------------------------------
+
+    def prefetch(self, query: str, *, session_id: str = "") -> str:
+        """Return cached prefetch result + any unconsumed bootstrap context."""
+        # Wait for background thread if still running
+        if self._prefetch_thread and self._prefetch_thread.is_alive():
+            self._prefetch_thread.join(timeout=3.0)
+
+        parts = []
+
+        # Consume bootstrap context (one-shot, first turn only)
+        if self._bootstrap_context:
+            parts.append(self._bootstrap_context)
+            self._bootstrap_context = ""
+
+        # Consume prefetched context only if it's from a generation we haven't consumed yet
+        with self._prefetch_lock:
+            if (self._prefetch_result
+                    and self._prefetch_result_gen > self._prefetch_consumed_gen):
+                parts.append(self._prefetch_result)
+            # Always advance consumed_gen to current queued generation — this
+            # prevents late-arriving results from leaking into the next turn
+            self._prefetch_consumed_gen = self._prefetch_generation
+            self._prefetch_result = ""
+
+        return "\n\n".join(parts) if parts else ""
+
+    def queue_prefetch(self, query: str, *, session_id: str = "") -> None:
+        """Background: run context-surfacing hook for next turn."""
+        if not self._bin or not query or len(query) < 5:
+            return
+
+        # Increment generation so older threads can't overwrite newer results
+        with self._prefetch_lock:
+            self._prefetch_generation += 1
+            my_gen = self._prefetch_generation
+
+        def _run():
+            hook_input = {
+                "session_id": self._session_id,
+                "transcript_path": self._transcript_path,
+                "prompt": query,
+                "hook_event_name": "UserPromptSubmit",
+            }
+            output = _run_hook(self._bin, "context-surfacing", hook_input,
+                               env_extra=self._env_extra)
+            if output:
+                ctx = _extract_context(output)
+                if ctx:
+                    with self._prefetch_lock:
+                        # Only write if we're still the latest generation
+                        if my_gen == self._prefetch_generation:
+                            self._prefetch_result = ctx
+                            self._prefetch_result_gen = my_gen
+
+        # Wait for any previous prefetch to finish
+        if self._prefetch_thread and self._prefetch_thread.is_alive():
+            self._prefetch_thread.join(timeout=5.0)
+
+        self._prefetch_thread = threading.Thread(
+            target=_run, daemon=True, name="clawmem-prefetch"
+        )
+        self._prefetch_thread.start()
+
+    # -- Sync / transcript management ------------------------------------------
+
+    def sync_turn(self, user_content: str, assistant_content: str, *, session_id: str = "") -> None:
+        """Append turn to plugin-managed transcript JSONL.
+
+        Writes in Claude Code transcript format so ClawMem hooks can read it.
+        """
+        if not self._transcript_path:
+            return
+
+        try:
+            ts = time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())
+            with open(self._transcript_path, "a") as f:
+                # User message
+                f.write(json.dumps({
+                    "type": "message",
+                    "message": {
+                        "role": "user",
+                        "content": user_content,
+                    },
+                    "timestamp": ts,
+                }) + "\n")
+                # Assistant message
+                f.write(json.dumps({
+                    "type": "message",
+                    "message": {
+                        "role": "assistant",
+                        "content": assistant_content,
+                    },
+                    "timestamp": ts,
+                }) + "\n")
+        except Exception as e:
+            logger.debug("clawmem: sync_turn write failed: %s", e)
+
+    # -- Session end / compression hooks ---------------------------------------
+
+    def on_session_end(self, messages: List[Dict[str, Any]]) -> None:
+        """Run extraction hooks in parallel."""
+        if not self._bin or not self._transcript_path:
+            return
+
+        hook_input = {
+            "session_id": self._session_id,
+            "transcript_path": self._transcript_path,
+            "hook_event_name": "Stop",
+        }
+
+        threads = []
+        for hook_name in ("decision-extractor", "handoff-generator", "feedback-loop"):
+            t = threading.Thread(
+                target=_run_hook,
+                args=(self._bin, hook_name, hook_input),
+                kwargs={"env_extra": self._env_extra},
+                daemon=True,
+                name=f"clawmem-{hook_name}",
+            )
+            t.start()
+            threads.append(t)
+
+        # Wait for all extraction hooks (bounded)
+        for t in threads:
+            t.join(timeout=_HOOK_TIMEOUT + 5)
+
+        logger.info("clawmem: session %s extraction complete", self._session_id[:8])
+
+    def on_pre_compress(self, messages: List[Dict[str, Any]]) -> str:
+        """Run precompact-extract (side effect only — Hermes ignores return)."""
+        if not self._bin or not self._transcript_path:
+            return ""
+
+        hook_input = {
+            "session_id": self._session_id,
+            "transcript_path": self._transcript_path,
+            "hook_event_name": "PreCompact",
+        }
+        _run_hook(self._bin, "precompact-extract", hook_input, env_extra=self._env_extra)
+        return ""
+
+    # -- Tools (REST API) ------------------------------------------------------
+
+    def get_tool_schemas(self) -> List[Dict[str, Any]]:
+        return [RETRIEVE_SCHEMA, GET_SCHEMA, SESSION_LOG_SCHEMA, TIMELINE_SCHEMA, SIMILAR_SCHEMA]
+
+    def handle_tool_call(self, tool_name: str, args: Dict[str, Any], **kwargs) -> str:
+        try:
+            if tool_name == "clawmem_retrieve":
+                return self._tool_retrieve(args)
+            elif tool_name == "clawmem_get":
+                return self._tool_get(args)
+            elif tool_name == "clawmem_session_log":
+                return self._tool_session_log(args)
+            elif tool_name == "clawmem_timeline":
+                return self._tool_timeline(args)
+            elif tool_name == "clawmem_similar":
+                return self._tool_similar(args)
+            return json.dumps({"error": f"Unknown tool: {tool_name}"})
+        except Exception as e:
+            return json.dumps({"error": str(e)})
+
+    def _tool_retrieve(self, args: dict) -> str:
+        query = args.get("query", "")
+        if not query:
+            return json.dumps({"error": "query is required"})
+        body = {"query": query, "compact": True}
+        if args.get("limit"):
+            body["limit"] = args["limit"]
+        data = _rest_call(self._port, "POST", "/retrieve", body)
+        if data is None:
+            return json.dumps({"error": "ClawMem REST API unreachable"})
+        return json.dumps(data, ensure_ascii=False)
+
+    def _tool_get(self, args: dict) -> str:
+        docid = args.get("docid", "")
+        if not docid:
+            return json.dumps({"error": "docid is required"})
+        data = _rest_call(self._port, "GET", f"/documents/{docid}")
+        if data is None:
+            return json.dumps({"error": f"Document not found: {docid}"})
+        return json.dumps(data, ensure_ascii=False)
+
+    def _tool_session_log(self, args: dict) -> str:
+        limit = args.get("limit", 5)
+        data = _rest_call(self._port, "GET", f"/sessions?limit={limit}")
+        if data is None:
+            return json.dumps({"error": "ClawMem REST API unreachable"})
+        return json.dumps(data, ensure_ascii=False)
+
+    def _tool_timeline(self, args: dict) -> str:
+        docid = args.get("docid", "")
+        if not docid:
+            return json.dumps({"error": "docid is required"})
+        before = args.get("before", 5)
+        after = args.get("after", 5)
+        data = _rest_call(self._port, "GET", f"/timeline/{docid}?before={before}&after={after}")
+        if data is None:
+            return json.dumps({"error": "ClawMem REST API unreachable"})
+        return json.dumps(data, ensure_ascii=False)
+
+    def _tool_similar(self, args: dict) -> str:
+        docid = args.get("docid", "")
+        if not docid:
+            return json.dumps({"error": "docid is required"})
+        limit = args.get("limit", 5)
+        data = _rest_call(self._port, "GET", f"/graph/similar/{docid}?limit={limit}")
+        if data is None:
+            return json.dumps({"error": "ClawMem REST API unreachable"})
+        return json.dumps(data, ensure_ascii=False)
+
+    # -- Managed serve ---------------------------------------------------------
+
+    def _start_serve(self) -> None:
+        """Start clawmem serve as a managed child process with readiness probe."""
+        if not self._bin:
+            return
+        try:
+            env = {**os.environ, **self._env_extra}
+            self._serve_proc = subprocess.Popen(
+                [self._bin, "serve", "--port", str(self._port)],
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+                env=env,
+            )
+            # Readiness probe — wait up to 5s for /health to respond
+            for attempt in range(10):
+                # Check if process exited immediately (port conflict, crash)
+                if self._serve_proc.poll() is not None:
+                    logger.warning("clawmem: managed serve exited immediately (code=%d)",
+                                   self._serve_proc.returncode)
+                    self._serve_proc = None
+                    return
+                time.sleep(0.5)
+                health = _rest_call(self._port, "GET", "/health", timeout=1.0)
+                if health:
+                    logger.info("clawmem: managed serve ready (pid=%d, port=%d)",
+                                self._serve_proc.pid, self._port)
+                    return
+            logger.warning("clawmem: managed serve started but health check timed out (pid=%d)",
+                           self._serve_proc.pid)
+        except Exception as e:
+            logger.warning("clawmem: failed to start managed serve: %s", e)
+
+    # -- Shutdown --------------------------------------------------------------
+
+    def shutdown(self) -> None:
+        # Wait for background threads
+        if self._prefetch_thread and self._prefetch_thread.is_alive():
+            self._prefetch_thread.join(timeout=5.0)
+
+        # Stop managed serve
+        if self._serve_proc and self._serve_proc.poll() is None:
+            self._serve_proc.terminate()
+            try:
+                self._serve_proc.wait(timeout=5)
+            except subprocess.TimeoutExpired:
+                self._serve_proc.kill()
+            logger.info("clawmem: managed serve stopped")
+
+
+# ---------------------------------------------------------------------------
+# Plugin entry point
+# ---------------------------------------------------------------------------
+
+def register(ctx) -> None:
+    """Register ClawMem as a memory provider plugin."""
+    ctx.register_memory_provider(ClawMemProvider())

package/src/hermes/plugin.yaml

@@ -0,0 +1,10 @@
+name: clawmem
+version: 1.0.0
+description: "ClawMem — on-device hybrid memory with composite scoring, graph traversal, and lifecycle management. Requires clawmem binary and optionally clawmem serve."
+external_dependencies:
+  - name: clawmem
+    install: "See https://github.com/yoloshii/ClawMem#install"
+    check: "clawmem --version"
+hooks:
+  - on_session_end
+  - on_pre_compress

package/src/indexer.ts

@@ -87,17 +87,21 @@ export function extractTitle(content: string, filename: string): string {
 // =============================================================================
 
 export function parseDocument(content: string, relativePath: string): { body: string; meta: DocumentMeta } {
+  // gray-matter coerces YAML values: `title: 2023-09-27` → Date, `title: true` → boolean.
+  // All frontmatter fields must be runtime-checked to prevent SQLite binding errors.
+  const str = (v: unknown): string | undefined =>
+    typeof v === "string" ? v || undefined : undefined;
   try {
     const { data, content: body } = matter(content);
     return {
       body,
       meta: {
-        title: data.title as string | undefined,
+        title: str(data.title),
         tags: Array.isArray(data.tags) ? data.tags.map(String) : undefined,
-        domain: data.domain as string | undefined,
-        workstream: data.workstream as string | undefined,
-        content_type: (data.content_type as ContentType) || inferContentType(relativePath),
-        review_by: data.review_by as string | undefined,
+        domain: str(data.domain),
+        workstream: str(data.workstream),
+        content_type: (str(data.content_type) as ContentType) || inferContentType(relativePath),
+        review_by: str(data.review_by),
       },
     };
   } catch {
@@ -233,7 +237,7 @@ export async function indexCollection(
 
         // Content changed — update
         const { body, meta } = parseDocument(content, relativePath);
-        const title = meta.title || extractTitle(body, relativePath);
+        const title = (typeof meta.title === "string" && meta.title) ? meta.title : extractTitle(body, relativePath);
         const docHash = hashContent(body);
 
         store.insertContent(docHash, body, now);
@@ -265,7 +269,7 @@ export async function indexCollection(
         ).get(collectionName, relativePath) as { id: number; hash: string } | null;
 
         const { body, meta } = parseDocument(content, relativePath);
-        const title = meta.title || extractTitle(body, relativePath);
+        const title = (typeof meta.title === "string" && meta.title) ? meta.title : extractTitle(body, relativePath);
         const docHash = hashContent(body);
         const contentType = meta.content_type || inferContentType(relativePath);
 

package/src/store.ts

@@ -1583,10 +1583,12 @@ export function insertDocument(
   createdAt: string,
   modifiedAt: string
 ): void {
+  // Guard: gray-matter can coerce YAML values to Date/boolean/null — SQLite rejects these
+  const safeTitle = (typeof title === "string") ? title : String(title ?? "Untitled");
   db.prepare(`
     INSERT INTO documents (collection, path, title, hash, created_at, modified_at, active)
     VALUES (?, ?, ?, ?, ?, ?, 1)
-  `).run(collectionName, path, title, hash, createdAt, modifiedAt);
+  `).run(collectionName, path, safeTitle, hash, createdAt, modifiedAt);
 }
 
 // =============================================================================
@@ -1915,8 +1917,9 @@ export function reactivateDocument(
   hash: string,
   modifiedAt: string
 ): void {
+  const safeTitle = (typeof title === "string") ? title : String(title ?? "Untitled");
   db.prepare(`UPDATE documents SET active = 1, title = ?, hash = ?, modified_at = ? WHERE id = ?`)
-    .run(title, hash, modifiedAt, documentId);
+    .run(safeTitle, hash, modifiedAt, documentId);
 }
 
 /**
@@ -1943,8 +1946,9 @@ export function updateDocument(
   hash: string,
   modifiedAt: string
 ): void {
+  const safeTitle = (typeof title === "string") ? title : String(title ?? "Untitled");
   db.prepare(`UPDATE documents SET title = ?, hash = ?, modified_at = ? WHERE id = ?`)
-    .run(title, hash, modifiedAt, documentId);
+    .run(safeTitle, hash, modifiedAt, documentId);
 }
 
 /**