clawmem 0.19.0 → 0.20.2

package/AGENTS.md

@@ -175,7 +175,7 @@ compositeScore = (0.50·searchScore + 0.25·recencyScore + 0.25·confidenceScore
 - **Vector search empty but BM25 works** → missing embeddings (the watcher indexes but does NOT embed). Run `clawmem embed`.
 - **`intent_search` weak for WHY/ENTITY** → sparse graph. Run `build_graphs`. Don't run it after every reindex (A-MEM links per-doc automatically).
 - **Rankings look RRF-flat / reranker suspect** → `clawmem rerank-health`. A mis-served reranker (e.g. a GGUF that drops the score head) returns HTTP 200 but inert scores, silently collapsing ranking to RRF.
-- **Intermittent `UserPromptSubmit hook timed out after 8s — output discarded`** → **fixed in v0.16.0** (upgrade). Root cause was not inference or host RAM alone: the `context-surfacing` vector leg ran a *synchronous* `sqlite-vec` scan that the `Promise.race(vectorTimeout)` guard could not bound (a synchronous call blocks the event loop, so the timer never fires), and every writable hook open ran an unconditional backfill `UPDATE` that could wait out `busy_timeout` under writer contention. v0.16.0 bounds both vector legs with real deadlines + timer cleanup, read-guards the init backfill, caps the init `busy_timeout`, and adds a watcher-side vector prewarm. A cold OS page cache still adds latency to the first post-boot call, so RAM headroom helps the margin — but on a large vault the scan cost, not RAM, was the dominant trigger. Still seeing it after upgrading? Raise the hook `timeout` in `~/.claude/settings.json` (8s default; no CLI knob) as a secondary margin. Detail: [docs/troubleshooting.md](docs/troubleshooting.md).
+- **Intermittent `UserPromptSubmit hook timed out after 8s — output discarded`** → **fixed in v0.16.0** (upgrade). Root cause was not inference or host RAM alone: the `context-surfacing` vector leg ran a *synchronous* `sqlite-vec` scan that the `Promise.race(vectorTimeout)` guard could not bound (a synchronous call blocks the event loop, so the timer never fires), and every writable hook open ran an unconditional backfill `UPDATE` that could wait out `busy_timeout` under writer contention. v0.16.0 bounds both vector legs with real deadlines + timer cleanup, read-guards the init backfill, caps the init `busy_timeout`, and adds a watcher-side vector prewarm. **v0.20.0** closes the residual with an opt-in vector-query daemon (run `clawmem watch`): it runs the blocking sqlite-vec scan off the hook's event loop, so a cold scan times out fast and falls back to FTS instead of blocking the turn — a true hard cap, not just a probability reduction; when the watcher isn't running, behavior is unchanged. A cold OS page cache still adds latency to the first post-boot call, so RAM headroom helps the margin — but on a large vault the scan cost, not RAM, was the dominant trigger. Still seeing it after upgrading? Raise the hook `timeout` in `~/.claude/settings.json` (8s default; no CLI knob) as a secondary margin. Detail: [docs/troubleshooting.md](docs/troubleshooting.md).
 - **Anything setup-shaped** (download blocked, server unreachable, watcher memory bloat, indexer bugs) → [docs/troubleshooting.md](docs/troubleshooting.md).
 
 ---

package/README.md

@@ -85,7 +85,7 @@ Full version history is in [RELEASE_NOTES.md](RELEASE_NOTES.md). Upgrade instruc
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — for hooks + MCP integration
 - [OpenClaw](https://github.com/openclaw/openclaw) — for native 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)
+- [bd CLI](https://github.com/gastownhall/beads) v0.58.0+ (verified through v1.1.0) — for Beads issue tracker sync (only if using Beads)
 
 ### Install from npm (recommended)
 
@@ -572,7 +572,7 @@ Registered by `clawmem setup mcp`. Available to any MCP-compatible client.
 
 | Tool | Description |
 |---|---|
-| `beads_sync` | Sync Beads issues from Dolt backend (`bd` CLI) into memory: creates docs, bridges all dep types to `memory_relations`, runs A-MEM enrichment |
+| `beads_sync` | Sync Beads issues from Dolt backend (`bd` CLI) into memory: syncs the full backlog (no 50-issue cap), creates docs, bridges all dep types to `memory_relations`, surfaces bd ≥1.1.0 claim leases, runs A-MEM enrichment |
 
 ### Vault Management
 

package/docs/reference/mcp-tools.md

@@ -280,6 +280,8 @@ Sync Beads issues from Dolt backend into the search index.
 |-------|------|---------|-------------|
 | `project_path` | string | cwd | Path to project with `.beads/` directory |
 
+Runs `bd list --json --limit 0` — the full backlog, not bd's default 50-issue page (v0.20.1). The spawned call disables bd usage metrics (`BD_DISABLE_METRICS=1`, ignored by pre-1.1.0 binaries). Issues carrying bd ≥1.1.0 claim-lease fields render a `**Claim Lease**` line in the indexed document (v0.20.1); upstream's removed `quality_score` field is no longer parsed.
+
 ## Vault management
 
 ### list_vaults

package/docs/troubleshooting.md

@@ -136,7 +136,7 @@ Common issues when running ClawMem with hooks, MCP server, or OpenClaw plugin. O
 - If the error persists after v0.1.8: restart the watcher to clear accumulated state (`systemctl --user restart clawmem-watcher.service`). Check `systemctl --user status clawmem-watcher.service` for memory usage — healthy is under 100MB, bloated is 400MB+.
 - **v0.2.4 fix:** Hook's SQLite `busy_timeout` was 500ms — too tight. During A-MEM enrichment or heavy indexing, the watcher can hold write locks for 500ms+, causing the hook's DB open to fail with SQLITE_BUSY. Raised to 5000ms (matches MCP server). The hook's 8s outer timeout still leaves 3s for actual work after a 5s busy wait.
 - **v0.3.1 fix:** Shell `timeout` wrappers (e.g., `timeout 8 clawmem hook context-surfacing`) kill the process with exit 124 and no stderr — Claude Code reports "Failed with non-blocking status code: No stderr output". This affects all hook events (UserPromptSubmit, Stop, SessionStart, PreCompact), not just Stop hooks. Fix: Remove shell `timeout` from all hook commands and use Claude Code's native `timeout` property instead. Run `clawmem setup hooks` to reinstall with correct config (v0.3.1+), or manually update `~/.claude/settings.json` — see [setup-hooks](guides/setup-hooks.md).
-- **Large vault + intermittent hook timeout (`timed out after 8s`) — FIXED in v0.16.0.** Earlier this was diagnosed as pure cold-start (fresh Bun process, opening a large `index.sqlite`, re-reading evicted index pages) with "give the host more RAM" as the durable fix — but the dominant causes were two code-level defects: (1) the `context-surfacing` vector leg ran a *synchronous* `sqlite-vec` scan that the `Promise.race(vectorTimeout)` guard could not bound (a synchronous call blocks the event loop, so the timer never fires), and (2) every writable hook open ran an unconditional backfill `UPDATE` that could wait out `busy_timeout` under writer contention. **v0.16.0 fixes both:** `searchVec` takes a real wall-clock deadline and self-aborts before the blocking scan; both vector legs race the embed against the remaining budget and clear their timers; the init backfill is read-guarded and the init `busy_timeout` is capped to the caller's value; and the watcher prewarms the sqlite-vec payload into the page cache on startup (embed-independent, watcher-only). A cold page cache still adds latency to the genuine first post-boot call, so host RAM headroom + the prewarm help the margin — but on a large vault the scan cost, not RAM, was the trigger. A modest `timeout` bump (see the tradeoffs table under *Hooks slow or near timeout*) remains a secondary margin. The `deep` profile additionally reranks (extra remote round-trips), widening the cold-call window; `balanced` (default) does not rerank.
+- **Large vault + intermittent hook timeout (`timed out after 8s`) — FIXED in v0.16.0.** Earlier this was diagnosed as pure cold-start (fresh Bun process, opening a large `index.sqlite`, re-reading evicted index pages) with "give the host more RAM" as the durable fix — but the dominant causes were two code-level defects: (1) the `context-surfacing` vector leg ran a *synchronous* `sqlite-vec` scan that the `Promise.race(vectorTimeout)` guard could not bound (a synchronous call blocks the event loop, so the timer never fires), and (2) every writable hook open ran an unconditional backfill `UPDATE` that could wait out `busy_timeout` under writer contention. **v0.16.0 fixes both:** `searchVec` takes a real wall-clock deadline and self-aborts before the blocking scan; both vector legs race the embed against the remaining budget and clear their timers; the init backfill is read-guarded and the init `busy_timeout` is capped to the caller's value; and the watcher prewarms the sqlite-vec payload into the page cache on startup (embed-independent, watcher-only). A cold page cache still adds latency to the genuine first post-boot call, so host RAM headroom + the prewarm help the margin — but on a large vault the scan cost, not RAM, was the trigger. A modest `timeout` bump (see the tradeoffs table under *Hooks slow or near timeout*) remains a secondary margin. The `deep` profile additionally reranks (extra remote round-trips), widening the cold-call window; `balanced` (default) does not rerank. **v0.20.0** adds the true hard cap: run `clawmem watch` and the hook sends the query to the watcher, which runs the blocking scan off the hook's event loop and returns the raw matches for local hydration — a cold scan then times out fast and falls back to FTS instead of blocking the turn. It is a pure optimization layer: when the watcher isn't running the hook uses the in-process, deadline-bounded path unchanged.
 
 **Watcher memory bloat (400MB+)**
 - The watcher accumulates memory when processing high-frequency file change events. The most common trigger was Claude Code session transcript `.jsonl` files changing on every keystroke during active conversations. Each event opened the database briefly, and over hours of active use, memory grew to 400-800MB.
@@ -222,7 +222,7 @@ Common issues when running ClawMem with hooks, MCP server, or OpenClaw plugin. O
 
   The timeout applies per invocation. A slow first prompt (cold start) doesn't mean subsequent prompts will be slow — Bun caches modules after the first load, and `node-llama-cpp` model files are cached on disk after the first download. Subsequent prompts in the same session are typically faster.
 
-  **Exception — large vaults (intermittent, pre-v0.16.0):** before v0.16.0 the hook could time out on *certain* turns (not just the first) because of an unbounded synchronous `sqlite-vec` scan plus an init-time write-lock wait — see *"UserPromptSubmit hook error" (intermittent)* above. **Upgrade to v0.16.0**, which bounds the scan and the init path and prewarms the cache. Host RAM headroom + the watcher prewarm still help the genuine cold-call margin, but they were not the root cause.
+  **Exception — large vaults (intermittent, pre-v0.16.0):** before v0.16.0 the hook could time out on *certain* turns (not just the first) because of an unbounded synchronous `sqlite-vec` scan plus an init-time write-lock wait — see *"UserPromptSubmit hook error" (intermittent)* above. **Upgrade to v0.16.0**, which bounds the scan and the init path and prewarms the cache (v0.20.0 adds the vector-query daemon — a true hard cap on the cold scan when the watcher runs). Host RAM headroom + the watcher prewarm still help the genuine cold-call margin, but they were not the root cause.
 
   **Stop hooks** (`decision-extractor`, `handoff-generator`, `feedback-loop`) default to 30s (v0.3.1+, was 10s prior) because they run LLM inference (observer model). These run at session end, so latency doesn't block the user.
 

package/package.json

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

package/src/beads.ts

@@ -9,7 +9,7 @@
 
 import { existsSync } from "node:fs";
 import { join } from "node:path";
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 
 // =============================================================================
 // Types (matches bd list --json output: IssueWithCounts)
@@ -43,7 +43,8 @@ export interface BeadsIssue {
   metadata?: Record<string, unknown>;
   labels?: string[];
   dependencies?: BeadsDependency[];
-  quality_score?: number;
+  lease_expires_at?: string;
+  heartbeat_at?: string;
   // Computed counts from bd list --json
   dependency_count?: number;
   dependent_count?: number;
@@ -92,11 +93,13 @@ function runBd(projectDir: string, args: string[], timeoutMs = 10000): string |
   }
 
   try {
-    return execSync(`${bd} ${args.join(" ")}`, {
+    return execFileSync(bd, args, {
       cwd: projectDir,
       encoding: "utf-8",
       timeout: timeoutMs,
-      env: { ...process.env },
+      // No shell interpolation of args; bd usage metrics + event flush stay off
+      // (default-on with a remote endpoint as of bd 1.1.0).
+      env: { ...process.env, BD_DISABLE_METRICS: "1", BD_DISABLE_EVENT_FLUSH: "1" },
       stdio: ["pipe", "pipe", "pipe"],
     });
   } catch (err: any) {
@@ -114,7 +117,7 @@ function runBd(projectDir: string, args: string[], timeoutMs = 10000): string |
  * Returns parsed issues with labels and dependencies populated.
  */
 export function queryBeadsList(projectDir: string): BeadsIssue[] {
-  const output = runBd(projectDir, ["list", "--json"]);
+  const output = runBd(projectDir, ["list", "--json", "--limit", "0"]);
   if (!output) return [];
 
   try {
@@ -158,7 +161,8 @@ function normalizeBeadsIssue(raw: any): BeadsIssue {
     metadata: raw.metadata,
     labels: raw.labels || [],
     dependencies: deps,
-    quality_score: raw.quality_score,
+    lease_expires_at: raw.lease_expires_at,
+    heartbeat_at: raw.heartbeat_at,
     dependency_count: raw.dependency_count,
     dependent_count: raw.dependent_count,
     comment_count: raw.comment_count,
@@ -213,7 +217,7 @@ export function formatBeadsIssueAsMarkdown(issue: BeadsIssue): string {
   }
   if (issue.blocks && issue.blocks.length > 0) lines.push(`**Blocks**: ${issue.blocks.join(", ")}`);
   if (issue.external_ref) lines.push(`**External Ref**: ${issue.external_ref}`);
-  if (issue.quality_score != null) lines.push(`**Quality Score**: ${issue.quality_score}`);
+  if (issue.lease_expires_at) lines.push(`**Claim Lease**: expires ${issue.lease_expires_at}`);
 
   if (issue.description) {
     lines.push("", "## Description", "", issue.description);

package/src/clawmem.ts

@@ -27,6 +27,7 @@ import {
   VecModelMismatchError,
   EmbedLeaseLostError,
 } from "./store.ts";
+import { startVectorDaemon, type VectorDaemonHandle } from "./vector-daemon.ts";
 import {
   getDefaultLlamaCpp,
   setDefaultLlamaCpp,
@@ -96,9 +97,9 @@ enableProductionMode();
 
 let store: Store | null = null;
 
-function getStore(): Store {
+function getStore(busyTimeout: number = 5000): Store {
   if (!store) {
-    store = createStore(undefined, { busyTimeout: 5000 });
+    store = createStore(undefined, { busyTimeout });
   }
   return store;
 }
@@ -1087,7 +1088,10 @@ async function cmdHook(args: string[]) {
   if (!hookName) die("Usage: clawmem hook <name>");
 
   const input = await readHookInput();
-  const s = getStore();
+  // Open the store capped from the START for the context-surfacing hook (not just after open via the
+  // PRAGMA below) so a contended init cannot wait the full 5000ms default before it is narrowed. Other
+  // hooks (Stop-lane, 30s budget) keep the 5000ms default.
+  const s = getStore(hookName === "context-surfacing" ? CONTEXT_SURFACING_WRITE_BUSY_TIMEOUT_MS : 5000);
   let output: HookOutput;
 
   try {
@@ -1848,6 +1852,7 @@ async function cmdWatch() {
   let watcherHandle: { close: () => void } | null = null;
   let checkpointTimerHandle: Timer | null = null;
   let prewarmTimerHandle: ReturnType<typeof setInterval> | null = null;
+  let vectorDaemonHandle: VectorDaemonHandle | null = null;
 
   // Graceful shutdown — stop workers, close watchers, then exit. SIGTERM
   // handling is critical for systemd `systemctl --user stop` to shut down
@@ -1863,6 +1868,12 @@ async function cmdWatch() {
       clearInterval(prewarmTimerHandle);
       prewarmTimerHandle = null;
     }
+    // Stop the vector daemon early — before the awaited worker drain below — so no new socket-driven
+    // scan starts mid-shutdown. close() stops the listener and unlinks the socket file.
+    if (vectorDaemonHandle) {
+      vectorDaemonHandle.close();
+      vectorDaemonHandle = null;
+    }
     if (stopHeavyLane) {
       await stopHeavyLane();
       stopHeavyLane = null;
@@ -1940,6 +1951,11 @@ async function cmdWatch() {
     console.log(`${c.dim}[watch] periodic vector prewarm every ${Math.round(prewarmIntervalMs / 1000)}s${c.reset}`);
   }
 
+  // BACKLOG Source 46: vector-query daemon — HARD cap on the cold synchronous MATCH. Runs Step 1 off
+  // the hook's event loop on this long-lived watcher; the hook connects only when the socket exists,
+  // so it is a pure optimization layer (null on bind failure → the hook keeps its in-process fallback).
+  vectorDaemonHandle = await startVectorDaemon(s, (msg) => console.log(`${c.dim}${msg}${c.reset}`));
+
   watcherHandle = startWatcher(dirs, {
     debounceMs: 2000,
     onChanged: async (fullPath, event) => {

package/src/hooks/context-surfacing.ts

@@ -8,6 +8,7 @@
 
 import type { Store, SearchResult } from "../store.ts";
 import { DEFAULT_EMBED_MODEL, DEFAULT_QUERY_MODEL, DEFAULT_RERANK_MODEL, warnOnceOnVectorModelMismatch, extractSnippet, resolveStore } from "../store.ts";
+import { searchVecBounded } from "../vector-daemon.ts";
 import { getVaultPath, getActiveProfile } from "../config.ts";
 import type { HookInput, HookOutput } from "../hooks.ts";
 import {
@@ -205,7 +206,11 @@ export async function contextSurfacing(
       // deadline makes searchVec self-abort before the blocking MATCH, so a slow embed cannot let
       // an already-timed-out vector leg resume and re-block the hook after it fell back to FTS.
       const vectorDeadline = Date.now() + profile.vectorTimeout;
-      const vectorPromise = store.searchVec(retrievalQuery, DEFAULT_EMBED_MODEL, maxResults, undefined, undefined, undefined, vectorDeadline);
+      // searchVecBounded runs Step 1 (the blocking MATCH) in the vector daemon when it is live, so the
+      // Promise.race timer below can ACTUALLY fire (this event loop stays free during the scan). When the
+      // daemon is absent it falls back to the in-process searchVec unchanged; when the daemon is
+      // busy/errors it returns [] and we drop to FTS below.
+      const vectorPromise = searchVecBounded(store, retrievalQuery, DEFAULT_EMBED_MODEL, maxResults, undefined, undefined, undefined, vectorDeadline);
       const timeoutPromise = new Promise<SearchResult[]>((_, reject) => {
         vectorTimer = setTimeout(() => reject(new Error("vector timeout")), profile.vectorTimeout);
       });
@@ -305,7 +310,7 @@ export async function contextSurfacing(
               if (remainingMs <= 0) break;
               let deepTimer: ReturnType<typeof setTimeout> | undefined;
               try {
-                const deepVec = store.searchVec(eq.query, DEFAULT_EMBED_MODEL, 5, undefined, undefined, undefined, startTime + 6000);
+                const deepVec = searchVecBounded(store, eq.query, DEFAULT_EMBED_MODEL, 5, undefined, undefined, undefined, startTime + 6000);
                 const deepTimeout = new Promise<SearchResult[]>((_, reject) => {
                   deepTimer = setTimeout(() => reject(new Error("vector timeout")), remainingMs);
                 });

package/src/store.ts

@@ -3519,7 +3519,13 @@ function assertQueryEmbedModelConsistent(db: Database, endpointModel: string): v
   verifiedQueryEmbedModels.set(db, { dataVersion, model: endpointModel });
 }
 
-export async function searchVec(db: Database, query: string, model: string, limit: number = 20, collectionId?: number, collections?: string[], dateRange?: { start: string; end: string }, deadlineMs?: number): Promise<SearchResult[]> {
+// Step 1 of vector search — the expensive, off-loadable half: embed the query, guard the wall-clock
+// deadline, then run the SYNCHRONOUS sqlite-vec MATCH. Returns raw {hash_seq, distance} hits;
+// collection/date filtering is a Step-2 concern. Split out (BACKLOG Source 46) so the vector-query
+// daemon can run JUST this half on the long-lived watcher — keeping the blocking MATCH off the hook's
+// event loop — while the hook hydrates locally via hydrateVecResults(). In-process searchVec() below
+// composes the two, so its public contract is unchanged.
+export async function searchVecMatch(db: Database, query: string, model: string, limit: number = 20, deadlineMs?: number): Promise<{ hash_seq: string; distance: number }[]> {
   const tableExists = db.prepare(`SELECT name FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get();
   if (!tableExists) return [];
 
@@ -3546,12 +3552,17 @@ export async function searchVec(db: Database, query: string, model: string, limi
   // See: https://github.com/tobi/qmd/pull/23
 
   // Step 1: Get vector matches from sqlite-vec (no JOINs allowed)
-  const vecResults = db.prepare(`
+  return db.prepare(`
     SELECT hash_seq, distance
     FROM vectors_vec
     WHERE embedding MATCH ? AND k = ?
   `).all(new Float32Array(embedding), limit * 3) as { hash_seq: string; distance: number }[];
+}
 
+// Step 2 of vector search — the cheap, local half: hydrate raw {hash_seq, distance} hits into
+// SearchResult[] via indexed JOINs, collection/date filtering, and per-doc dedup. Pure primary-key
+// SQLite lookups — safe to run in the short-lived hook process even when Step 1 ran in the daemon.
+export function hydrateVecResults(db: Database, vecResults: { hash_seq: string; distance: number }[], limit: number = 20, collectionId?: number, collections?: string[], dateRange?: { start: string; end: string }): SearchResult[] {
   if (vecResults.length === 0) return [];
 
   // Step 2: Get chunk info and document data
@@ -3635,6 +3646,14 @@ export async function searchVec(db: Database, query: string, model: string, limi
     });
 }
 
+// In-process vector search — Step 1 (MATCH) + Step 2 (hydrate) composed. Public contract unchanged;
+// the daemon-backed hook path (context-surfacing) instead calls searchVecMatch (in the daemon) +
+// hydrateVecResults (locally), so the blocking MATCH never runs on the hook's event loop.
+export async function searchVec(db: Database, query: string, model: string, limit: number = 20, collectionId?: number, collections?: string[], dateRange?: { start: string; end: string }, deadlineMs?: number): Promise<SearchResult[]> {
+  const vecResults = await searchVecMatch(db, query, model, limit, deadlineMs);
+  return hydrateVecResults(db, vecResults, limit, collectionId, collections, dateRange);
+}
+
 // =============================================================================
 // Embeddings
 // =============================================================================

package/src/vector-daemon.ts

@@ -0,0 +1,320 @@
+/**
+ * Vector-query daemon (BACKLOG Source 46) — HARD cap on the cold synchronous sqlite-vec MATCH.
+ *
+ * The context-surfacing UserPromptSubmit hook runs a SYNCHRONOUS sqlite-vec MATCH (searchVecMatch).
+ * bun:sqlite exposes no interrupt/progress handler, so a cold scan on a large vault blocks the hook's
+ * single event loop past its 8-15s budget — an in-thread `Promise.race(vectorTimeout)` cannot fire
+ * while a synchronous call runs. This daemon relocates JUST Step 1 (the MATCH) onto the long-lived
+ * watcher process: the hook sends the query string over a per-vault unix socket and races the reply
+ * against a REAL setTimeout (its own event loop is now free), then hydrates locally (Step 2).
+ *
+ * The daemon is a strict OPTIMIZATION LAYER, never a dependency:
+ *   - daemon absent/refused  → the hook uses the in-process searchVec path UNCHANGED (today's behavior;
+ *                              users who don't run the watcher lose nothing).
+ *   - daemon busy/error/timeout → the hook returns [] and falls back to FTS (it must NOT re-run the scan
+ *                              in-process, which would reintroduce the very block this exists to avoid).
+ *
+ * Design record: BACKLOG.md Source 46 "DESIGN-gate outcome + build contract" (2026-07-05, codex-cleared).
+ */
+
+import { existsSync, mkdirSync, chmodSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import type { Socket } from "bun";
+import { searchVecMatch, hydrateVecResults, VecReadModelMismatchError, type Store, type SearchResult } from "./store.ts";
+
+// Newline-delimited JSON, one request/response per connection. A query string and a list of
+// {hash_seq, distance} are both small; anything over this cap is a protocol violation, so both sides
+// reject it rather than buffer unbounded on a runaway/hostile peer.
+const MAX_FRAME_BYTES = 256 * 1024;
+const DEFAULT_IPC_TIMEOUT_MS = 5000;
+// A stray/hostile `limit` (same-user socket) must not become an unbounded `k = limit * 3` scan. The
+// hook only ever asks for ~5-10; clamp anything outside a sane range.
+const MAX_VEC_LIMIT = 500;
+
+// Env-gated phase timing (CLAWMEM_VEC_TIMING=1): logs each hook vector leg's outcome + elapsed to
+// stderr so a future `UserPromptSubmit hook timed out` is attributable — daemon engaged & fast, vs
+// daemon-absent in-process fallback (the old slow path), vs daemon busy/error → FTS. Off by default.
+const VEC_TIMING = process.env.CLAWMEM_VEC_TIMING === "1" || process.env.CLAWMEM_VEC_TIMING === "true";
+
+type VecHit = { hash_seq: string; distance: number };
+type VecReq = { query: string; model: string; limit: number; deadlineMs?: number };
+type VecResp = { results: VecHit[] } | { error: string; storedModels?: string[]; activeModel?: string };
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Socket path — shared by daemon + hook client, keyed per vault DB path
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Parent dir for all clawmem daemon sockets ($XDG_RUNTIME_DIR/clawmem, fallback tmpdir). */
+export function vecDaemonSocketDir(): string {
+  const base = process.env.XDG_RUNTIME_DIR || tmpdir();
+  return join(base, "clawmem");
+}
+
+/**
+ * Per-vault socket path, keyed by a short hash of the vault DB path so multiple vaults
+ * (general/work/personal) never collide on one socket. The daemon and the hook client both derive
+ * the SAME path from the SAME `store.dbPath`, so they rendezvous without any shared registry.
+ */
+export function vecDaemonSocketPath(dbPath: string): string {
+  const key = createHash("sha256").update(dbPath).digest("hex").slice(0, 16);
+  return join(vecDaemonSocketDir(), `vec-${key}.sock`);
+}
+
+/** Brief liveness probe: true if a listener accepts a connection on `sockPath`, false if refused/timeout. */
+function isSocketAlive(sockPath: string): Promise<boolean> {
+  return new Promise<boolean>((resolve) => {
+    let done = false;
+    const finish = (v: boolean) => { if (done) return; done = true; clearTimeout(timer); resolve(v); };
+    const timer = setTimeout(() => finish(false), 250);
+    Bun.connect<undefined>({
+      unix: sockPath,
+      socket: {
+        open(s) { try { s.end(); } catch { /* ignore */ } finish(true); },
+        connectError() { finish(false); },
+        error() { finish(false); },
+      },
+    }).catch(() => finish(false));
+  });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Daemon (server) — hosted in the long-lived watcher (cmdWatch)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type VectorDaemonHandle = { close: () => void };
+
+/**
+ * Start the vector-query daemon on `store`'s DB. Returns a handle whose close() stops the listener and
+ * unlinks the socket, or null if the socket could not be bound (best-effort — the hook's in-process
+ * fallback still works, so a bind failure degrades to today's behavior, it never breaks the hook).
+ *
+ * SINGLE-FLIGHT: at most one MATCH runs at a time per vault. A request arriving while a scan is in
+ * flight gets {error:"busy"} immediately (→ hook falls to FTS), never queues — this is what stops
+ * abandoned cold scans from serializing and starving the watcher. Paired with a deadline check on
+ * receipt: a request whose deadline already elapsed is rejected WITHOUT scanning, so requests that
+ * piled up behind a cold-scan freeze are dropped (their hooks already gave up) instead of each
+ * triggering a fresh wasted scan.
+ */
+export async function startVectorDaemon(
+  store: Store,
+  log: (msg: string) => void = () => {},
+  // The Step-1 scan is injectable so tests can exercise the socket/single-flight/framing logic without
+  // a live embedding server. Production omits it → the real searchVecMatch on the watcher's warm store.
+  scan: (query: string, model: string, limit: number, deadlineMs?: number) => Promise<VecHit[]> =
+    (query, model, limit, deadlineMs) => searchVecMatch(store.db, query, model, limit, deadlineMs),
+): Promise<VectorDaemonHandle | null> {
+  const sockPath = vecDaemonSocketPath(store.dbPath);
+  try {
+    // 0700 dir is the real access control (UnixSocketOptions has no `mode` field); the socket chmod
+    // below is defense-in-depth. mkdir's `mode` only applies on CREATE, so chmod an existing dir too.
+    mkdirSync(vecDaemonSocketDir(), { recursive: true, mode: 0o700 });
+    try { chmodSync(vecDaemonSocketDir(), 0o700); } catch { /* best-effort */ }
+    if (existsSync(sockPath)) {
+      // A socket file already exists. If a LIVE daemon (another watcher for this vault) owns it, do NOT
+      // clobber it — unlinking a live socket only makes the old listener unreachable-by-path while it
+      // keeps running, stranding it. Probe first: bind only over a stale (dead) socket.
+      if (await isSocketAlive(sockPath)) {
+        log(`[vec-daemon] a live daemon already owns ${sockPath}; not starting a second`);
+        return { close() { /* not ours — nothing to stop or unlink */ } };
+      }
+      rmSync(sockPath, { force: true }); // stale socket from a crashed watcher
+    }
+  } catch (e) {
+    log(`[vec-daemon] socket dir prep failed: ${(e as Error).message}`);
+    return null;
+  }
+
+  let scanInFlight = false;
+
+  const respond = (socket: Socket<{ buf: string }>, resp: VecResp) => {
+    try {
+      socket.write(JSON.stringify(resp) + "\n");
+      socket.end();
+    } catch { /* peer already gone — nothing to send */ }
+  };
+
+  const handleRequest = async (socket: Socket<{ buf: string }>, line: string) => {
+    let req: VecReq;
+    try {
+      req = JSON.parse(line) as VecReq;
+      if (typeof req.query !== "string" || typeof req.model !== "string" || typeof req.limit !== "number" || !Number.isFinite(req.limit)) {
+        throw new Error("bad request shape");
+      }
+    } catch {
+      respond(socket, { error: "malformed" });
+      return;
+    }
+    // Deadline-on-receipt: drop already-expired requests without scanning (the pile-up guard).
+    if (req.deadlineMs !== undefined && Date.now() >= req.deadlineMs) {
+      respond(socket, { error: "expired" });
+      return;
+    }
+    if (scanInFlight) {
+      respond(socket, { error: "busy" });
+      return;
+    }
+    // Clamp limit so a stray/hostile value can't drive an unbounded k = limit*3 scan.
+    const safeLimit = Math.min(Math.max(1, Math.trunc(req.limit)), MAX_VEC_LIMIT);
+    scanInFlight = true;
+    try {
+      const results = await scan(req.query, req.model, safeLimit, req.deadlineMs);
+      respond(socket, { results });
+    } catch (e) {
+      // Preserve the v0.18 read-model-mismatch "warn loudly once" contract across the wire: return a
+      // TYPED error the client reconstructs into VecReadModelMismatchError so the hook's
+      // warnOnceOnVectorModelMismatch (an instanceof check) still fires. Other errors stay generic.
+      if (e instanceof VecReadModelMismatchError) {
+        respond(socket, { error: "read_model_mismatch", storedModels: e.storedModels, activeModel: e.activeModel });
+      } else {
+        respond(socket, { error: `internal: ${(e as Error).message}` });
+      }
+    } finally {
+      scanInFlight = false;
+    }
+  };
+
+  let server: { stop: (closeActiveConnections?: boolean) => void };
+  try {
+    server = Bun.listen<{ buf: string }>({
+      unix: sockPath,
+      socket: {
+        open(socket) { socket.data = { buf: "" }; },
+        data(socket, chunk) {
+          socket.data.buf += chunk.toString();
+          if (socket.data.buf.length > MAX_FRAME_BYTES) { respond(socket, { error: "oversized" }); return; }
+          const nl = socket.data.buf.indexOf("\n");
+          if (nl < 0) return; // partial frame — wait for the newline
+          const line = socket.data.buf.slice(0, nl);
+          socket.data.buf = ""; // one request per connection
+          void handleRequest(socket, line);
+        },
+        error(_socket, err) { log(`[vec-daemon] socket error: ${err.message}`); },
+      },
+    });
+  } catch (e) {
+    log(`[vec-daemon] bind failed: ${(e as Error).message}`);
+    return null;
+  }
+
+  try { chmodSync(sockPath, 0o600); } catch { /* best-effort; 0700 dir already restricts to owner */ }
+  log(`[vec-daemon] listening on ${sockPath}`);
+
+  return {
+    close() {
+      try { server.stop(true); } catch { /* already stopped */ }
+      try { if (existsSync(sockPath)) rmSync(sockPath, { force: true }); } catch { /* best-effort */ }
+    },
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook client + bounded search — used by BOTH context-surfacing vector legs
+// ─────────────────────────────────────────────────────────────────────────────
+
+type DaemonOutcome =
+  | { status: "ok"; results: VecHit[] }
+  | { status: "busy" }    // daemon busy/expired → hook falls to FTS (do NOT re-run in-process)
+  | { status: "error" }   // daemon present but timed out/misbehaving → fall to FTS
+  | { status: "absent" }  // daemon not running → hook uses the in-process path
+  | { status: "model_mismatch"; storedModels: string[]; activeModel: string }; // typed → hook warns once
+
+/**
+ * Send one Step-1 request to the daemon and classify the outcome. Self-bounds to `ipcTimeoutMs`
+ * (the caller passes the remaining wall-clock budget) so the client cleans up its own socket well
+ * before the hook's outer timer fires. Every failure mode resolves — this promise never rejects.
+ */
+export async function daemonVecMatch(dbPath: string, req: VecReq, ipcTimeoutMs: number): Promise<DaemonOutcome> {
+  const sockPath = vecDaemonSocketPath(dbPath);
+  if (!existsSync(sockPath)) return { status: "absent" };
+  if (ipcTimeoutMs <= 0) return { status: "error" }; // no budget left — don't even connect
+
+  return await new Promise<DaemonOutcome>((resolve) => {
+    let settled = false;
+    let buf = "";
+    let sock: Socket<undefined> | null = null;
+    const finish = (o: DaemonOutcome) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { sock?.end(); } catch { /* ignore */ }
+      resolve(o);
+    };
+    const timer = setTimeout(() => finish({ status: "error" }), ipcTimeoutMs);
+
+    Bun.connect<undefined>({
+      unix: sockPath,
+      socket: {
+        open(socket) {
+          sock = socket;
+          try { socket.write(JSON.stringify(req) + "\n"); }
+          catch { finish({ status: "error" }); }
+        },
+        data(_socket, chunk) {
+          buf += chunk.toString();
+          if (buf.length > MAX_FRAME_BYTES) { finish({ status: "error" }); return; }
+          const nl = buf.indexOf("\n");
+          if (nl < 0) return; // partial frame — keep reading
+          try {
+            const resp = JSON.parse(buf.slice(0, nl)) as VecResp;
+            if ("results" in resp) finish({ status: "ok", results: resp.results });
+            else if (resp.error === "busy" || resp.error === "expired") finish({ status: "busy" });
+            else if (resp.error === "read_model_mismatch") finish({ status: "model_mismatch", storedModels: resp.storedModels ?? [], activeModel: resp.activeModel ?? "" });
+            else finish({ status: "error" });
+          } catch { finish({ status: "error" }); }
+        },
+        // Connection refused / stale socket file (no live listener) → daemon effectively absent.
+        connectError() { finish({ status: "absent" }); },
+        error() { finish({ status: "error" }); },
+        close() { finish({ status: "error" }); }, // closed before a full frame arrived
+      },
+    }).catch(() => finish({ status: "absent" })); // belt-and-suspenders for connect rejection
+  });
+}
+
+/**
+ * Bounded vector search for the hook path. Tries the daemon (Step-1 MATCH off the hook's event loop),
+ * hydrates locally (Step-2), and degrades cleanly per the design contract:
+ *   - ok               → hydrate the daemon's hits and return
+ *   - absent/refused   → in-process searchVec (today's self-bounded behavior; daemon not deployed)
+ *   - model_mismatch   → throw VecReadModelMismatchError (mirrors in-process; the leg warns once → FTS)
+ *   - busy/error/timeout → return [] so the caller falls back to FTS
+ *
+ * Used by BOTH the primary and deep-escalation vector legs in context-surfacing, so every hook vector
+ * call is bounded — not just the first.
+ */
+export async function searchVecBounded(
+  store: Store,
+  query: string,
+  model: string,
+  limit: number,
+  collectionId?: number,
+  collections?: string[],
+  dateRange?: { start: string; end: string },
+  deadlineMs?: number,
+): Promise<SearchResult[]> {
+  const startedAt = VEC_TIMING ? Date.now() : 0;
+  const ipcTimeoutMs = deadlineMs !== undefined ? deadlineMs - Date.now() : DEFAULT_IPC_TIMEOUT_MS;
+  const outcome = await daemonVecMatch(store.dbPath, { query, model, limit, deadlineMs }, ipcTimeoutMs);
+  let results: SearchResult[];
+  switch (outcome.status) {
+    case "ok":
+      results = hydrateVecResults(store.db, outcome.results, limit, collectionId, collections, dateRange);
+      break;
+    case "absent":
+      results = await store.searchVec(query, model, limit, collectionId, collections, dateRange, deadlineMs);
+      break;
+    case "model_mismatch":
+      // Mirror the in-process path: throw the typed error so the leg's catch fires
+      // warnOnceOnVectorModelMismatch (a persistent config error, warned loudly once), then FTS.
+      throw new VecReadModelMismatchError(outcome.storedModels, outcome.activeModel);
+    default: // "busy" | "error" → let the caller's FTS fallback take over
+      results = [];
+      break;
+  }
+  if (VEC_TIMING) {
+    console.error(`[vec-timing] path=${outcome.status} elapsedMs=${Date.now() - startedAt} results=${results.length}`);
+  }
+  return results;
+}