clawmem 0.8.1 → 0.8.3

package/AGENTS.md

@@ -94,9 +94,9 @@ curl http://host:8090/v1/models
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Blocks `node-llama-cpp` from auto-downloading GGUF models. Set `true` for remote-only setups. |
 | `CLAWMEM_VAULTS` | (none) | JSON map of vault name → SQLite path for multi-vault mode. E.g. `{"work":"~/.cache/clawmem/work.sqlite"}` |
 | `CLAWMEM_ENABLE_AMEM` | enabled | A-MEM note construction + link generation during indexing. |
-| `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs. Needs long-lived MCP process. |
+| `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs and runs Phase 2/3 consolidation + deductive synthesis. **v0.8.2:** every tick is wrapped in a DB-backed `worker_leases` row (`light-consolidation` key), so multiple host processes against the same vault cannot race on Phase 2 merge writes. Hosted by either `clawmem watch` (canonical, long-lived) or `clawmem mcp` (per-session fallback). |
 | `CLAWMEM_CONSOLIDATION_INTERVAL` | 300000 | Worker interval in ms (min 15000). |
-| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance worker — a second, longer-interval consolidation lane with DB-backed `worker_leases` exclusivity, stale-first batching, and `maintenance_runs` journaling. Runs alongside the light lane; off by default. |
+| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance worker — a second, longer-interval consolidation lane with DB-backed `worker_leases` exclusivity, stale-first batching, and `maintenance_runs` journaling. Runs alongside the light lane; off by default. **v0.8.2:** canonical host is `clawmem watch` (e.g. systemd `clawmem-watcher.service`); `clawmem mcp` retains the same gate as a fallback host but emits a stderr warning advising operators to move heavy-lane hosting to the watcher because per-session stdio MCPs may never be alive during the configured quiet window. |
 | `CLAWMEM_HEAVY_LANE_INTERVAL` | 1800000 | **v0.8.0.** Heavy-lane tick interval in ms (min 30000, default 30 min). |
 | `CLAWMEM_HEAVY_LANE_WINDOW_START` | (none) | **v0.8.0.** Start hour (0-23) of the quiet window. Unset → no window. |
 | `CLAWMEM_HEAVY_LANE_WINDOW_END` | (none) | **v0.8.0.** End hour (0-23, exclusive) of the quiet window. Supports midnight wrap (22→6). |

package/CLAUDE.md

@@ -94,9 +94,9 @@ curl http://host:8090/v1/models
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Blocks `node-llama-cpp` from auto-downloading GGUF models. Set `true` for remote-only setups. |
 | `CLAWMEM_VAULTS` | (none) | JSON map of vault name → SQLite path for multi-vault mode. E.g. `{"work":"~/.cache/clawmem/work.sqlite"}` |
 | `CLAWMEM_ENABLE_AMEM` | enabled | A-MEM note construction + link generation during indexing. |
-| `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs. Needs long-lived MCP process. |
+| `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs and runs Phase 2/3 consolidation + deductive synthesis. **v0.8.2:** every tick is wrapped in a DB-backed `worker_leases` row (`light-consolidation` key), so multiple host processes against the same vault cannot race on Phase 2 merge writes. Hosted by either `clawmem watch` (canonical, long-lived) or `clawmem mcp` (per-session fallback). |
 | `CLAWMEM_CONSOLIDATION_INTERVAL` | 300000 | Worker interval in ms (min 15000). |
-| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance worker — a second, longer-interval consolidation lane with DB-backed `worker_leases` exclusivity, stale-first batching, and `maintenance_runs` journaling. Runs alongside the light lane; off by default. |
+| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance worker — a second, longer-interval consolidation lane with DB-backed `worker_leases` exclusivity, stale-first batching, and `maintenance_runs` journaling. Runs alongside the light lane; off by default. **v0.8.2:** canonical host is `clawmem watch` (e.g. systemd `clawmem-watcher.service`); `clawmem mcp` retains the same gate as a fallback host but emits a stderr warning advising operators to move heavy-lane hosting to the watcher because per-session stdio MCPs may never be alive during the configured quiet window. |
 | `CLAWMEM_HEAVY_LANE_INTERVAL` | 1800000 | **v0.8.0.** Heavy-lane tick interval in ms (min 30000, default 30 min). |
 | `CLAWMEM_HEAVY_LANE_WINDOW_START` | (none) | **v0.8.0.** Start hour (0-23) of the quiet window. Unset → no window. |
 | `CLAWMEM_HEAVY_LANE_WINDOW_END` | (none) | **v0.8.0.** End hour (0-23, exclusive) of the quiet window. Supports midnight wrap (22→6). |

package/README.md

@@ -47,66 +47,7 @@ ClawMem turns your markdown notes, project docs, and research dumps into persist
 
 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
-
-- **Entity resolution + co-occurrence graph** — LLM entity extraction with quality filters, type-agnostic canonical resolution within [compatibility buckets](docs/internals/entity-resolution.md) (extensible type vocabulary), IDF-based entity edge scoring, co-occurrence tracking, entity graph traversal for ENTITY intent queries
-- **MPFP graph retrieval** — Multi-Path Fact Propagation with meta-path patterns per intent, hop-synchronized edge cache, Forward Push with α=0.15 teleport probability. Replaces single-beam traversal for causal/entity/temporal queries.
-- **Temporal query extraction** — regex-based date range extraction from natural language queries ("last week", "March 2026"), wired as WHERE filters into BM25 and vector search
-- **4-way parallel retrieval** — temporal proximity and entity graph channels added as parallel RRF legs in `query` tool (Tier 3 only), alongside existing BM25 + vector channels
-- **3-tier consolidation** — facts to observations (auto-generated, with proof_count and trend enum) to mental models. Background worker synthesizes clusters of related observations into consolidated patterns.
-- **Observation invalidation** — soft invalidation (invalidated_at/invalidated_by/superseded_by columns). Observations with confidence ≤ 0.2 after contradiction are filtered from search results.
-- **Memory nudge** — periodic ephemeral `<vault-nudge>` injection prompting lifecycle tool use after N turns of inactivity. Configurable via `CLAWMEM_NUDGE_INTERVAL`.
-
-### v0.7.1 Safety Release
-
-Five independent safety gates around the consolidation pipeline and context surfacing, aimed at preventing contamination, cross-entity merges, and unchecked contradictions from landing in the vault. Every extraction ships with full unit + integration test coverage (+158 tests on top of the v0.7.0 baseline). See [consolidation safety](docs/concepts/architecture.md#consolidation-safety-v071) for the architectural walkthrough.
-
-- **Taxonomy cleanup** — standardized on the A-MEM `contradicts` (plural) convention across the entire codebase, eliminating silent query misses on the legacy singular form
-- **Name-aware merge safety** — the Phase 2 consolidation worker gate extracts entity anchors (via `entity_mentions`, with lexical proper-noun fallback) and runs dual-threshold normalized 3-gram cosine similarity before merging similar observations. Cross-entity merges are hard-rejected when anchor sets differ materially, preventing context bleed where "Alice decided X" merges into "Bob decided X". Thresholds are env-overridable (`CLAWMEM_MERGE_SCORE_NORMAL`=0.93, `_STRICT`=0.98). Dry-run mode via `CLAWMEM_MERGE_GUARD_DRY_RUN` for calibration.
-- **Contradiction-aware merge gate** — after the name-aware gate passes, a deterministic heuristic (negation asymmetry, number/date mismatch) plus an LLM check detect contradictory merges. Blocked merges route to `link` policy (insert new row + `contradicts` edge, default) or `supersede` policy (mark old row `status='inactive'`). Configurable via `CLAWMEM_CONTRADICTION_POLICY` and `CLAWMEM_CONTRADICTION_MIN_CONFIDENCE`. Phase 3 deductive synthesis applies the same gate to deductive dedupe matches.
-- **Anti-contamination deductive synthesis** — every Phase 3 draft runs through a three-layer validator: deterministic pre-checks (empty conclusion, invalid source_indices, pool-only entity contamination via `entity_mentions`) + LLM validator (fail-open with `validatorFallbackAccepts` counter) + dedupe. Per-reason rejection stats exposed via `DeductiveSynthesisStats` so Phase 3 yield can be diagnosed without enabling extra logging.
-- **Context instruction + relationship snippets** — `context-surfacing` now always prepends an `<instruction>` block framing the surfaced facts as background knowledge the model already holds, and appends an optional `<relationships>` block listing memory-graph edges where BOTH endpoints are in the surfaced doc set. The relationships block is the first thing dropped when the payload would overflow `CLAWMEM_PROFILE`'s token budget, preserving facts-first behaviour while giving the model graph-level reasoning hooks directly in-prompt.
-
-### v0.7.2 Post-Import Conversation Synthesis
-
-Opt-in LLM pass that runs **after** `clawmem mine` finishes indexing an imported collection. Operates on the freshly imported `content_type='conversation'` documents and extracts structured knowledge facts (decisions / preferences / milestones / problems) plus cross-fact relations, writing each fact as a first-class searchable document alongside the raw conversation exchanges. See [post-import synthesis](docs/concepts/architecture.md#post-import-conversation-synthesis-v072) for the architectural walkthrough.
-
-- **New CLI flag** — `clawmem mine <dir> --synthesize [--synthesis-max-docs N]`. Off by default. When omitted, existing mine behaviour is byte-identical to v0.7.1.
-- **Two-pass pipeline** — Pass 1 extracts facts per conversation via the existing LLM, saves each via dedup-aware `saveMemory`, and populates a local alias map. Pass 2 resolves cross-fact links against the local map first, falling back to collection-scoped SQL lookup. Forward references (link to a fact extracted later in the same run) are resolved correctly.
-- **Idempotent reruns** — synthesized fact paths are a pure function of `(sourceDocId, slug(title), short sha256(normalizedTitle))`, so reruns over the same conversation batch hit the `saveMemory` update branch instead of creating parallel rows. Same-slug collisions are disambiguated by the stable hash suffix, not encounter order.
-- **Fail-closed link resolution** — when two different facts claim the same normalized title or alias, the resolver treats the link as ambiguous and counts it unresolved. Pre-existing docs with duplicate titles in the collection do not silently bind either.
-- **Weight-monotonic relation upsert** — `memory_relations` insert uses `ON CONFLICT DO UPDATE SET weight = MAX(weight, excluded.weight)`, which is idempotent on equal-weight reruns but still accepts stronger later evidence without double-counting.
-- **Non-fatal failure model** — any LLM failure, JSON parse error, saveMemory collision, or relation insert error is counted and logged, never re-thrown. Synthesis failure after `indexCollection` commits does not roll back the mine import.
-- **Split operator counters** — `llmFailures` counts actual LLM path failures (null, thrown, non-array JSON), while `docsWithNoFacts` counts docs where the LLM responded validly but returned zero structured facts. Previously these were conflated as `nullCalls`.
-
-Adds +63 tests (46 unit + 5 integration + 12 regression) on top of the v0.7.1 baseline.
-
-### v0.8.0 Quiet-Window Heavy Maintenance Lane
-
-A second, longer-interval consolidation worker that keeps Phase 2 + Phase 3 running on large vaults without starving interactive sessions. Off by default — set `CLAWMEM_HEAVY_LANE=true` to enable. The existing 5-minute light-lane worker is unchanged. See [heavy maintenance lane](docs/concepts/architecture.md#heavy-maintenance-lane-v080) for the architectural walkthrough.
-
-- **Quiet-window gating** — the heavy lane only runs inside the hours set by `CLAWMEM_HEAVY_LANE_WINDOW_START` / `CLAWMEM_HEAVY_LANE_WINDOW_END` (0-23). Supports midnight wraparound (e.g., 22→6). Null on either bound means "always in window".
-- **Query-rate gating via `context_usage`** — counts hook injections in the last 10 minutes and skips the tick when the rate exceeds `CLAWMEM_HEAVY_LANE_MAX_USAGES` (default 30). No new `query_activity` table; reuses v0.7.0 telemetry.
-- **DB-backed worker leases** — exclusivity enforced via a new `worker_leases` table with atomic `INSERT ... ON CONFLICT DO UPDATE ... WHERE expires_at <= ?` acquisition, random 16-byte fencing tokens, and TTL reclaim. Safe under multi-process contention; any SQLite error translates to a `lease_unavailable` skip rather than a thrown exception.
-- **Stale-first selection** — Phase 2 and Phase 3 reorder their candidate sets by `COALESCE(recall_stats.last_recalled_at, documents.last_accessed_at, documents.modified_at) ASC` so long-unseen docs bubble up first. Empty `recall_stats` falls through to access-time without erroring.
-- **Optional surprisal selector** — `CLAWMEM_HEAVY_LANE_SURPRISAL=true` plumbs k-NN anomaly-ranked doc ids (via the existing `computeSurprisalScores`) into Phase 2 as an explicit `candidateIds` filter. Degrades to stale-first on vaults without embeddings and logs `selector: 'surprisal-fallback-stale'` in the journal.
-- **`maintenance_runs` journal** — every scheduled attempt writes a row: `status` (`started`/`completed`/`failed`/`skipped`), `reason` for skips, selected/processed/created/null_call counts, and a `metrics_json` payload with selector type and full `DeductiveSynthesisStats` breakdown. Operators can reconstruct any lane decision without reading worker logs.
-- **Force-enforce merge gate** — the heavy lane passes `guarded: true` to `consolidateObservations`, which overrides `CLAWMEM_MERGE_GUARD_DRY_RUN` inside `findSimilarConsolidation` so experimenting operators cannot weaken heavy-lane enforcement via env flag.
-
-Adds +56 tests (13 worker-lease + 35 maintenance unit + 8 maintenance integration) on top of the v0.7.2 baseline.
-
-### v0.8.1 Multi-Turn Prior-Query Lookback
-
-`context-surfacing` now builds its retrieval query from the current prompt plus up to two recent same-session prior prompts, so a short follow-up turn ("do the same for X", "explain the rationale") can still inherit the vocabulary of earlier turns. The raw prompt is persisted in a new nullable `context_usage.query_text` column so future hook ticks can reconstitute the multi-turn query from the DB. See [multi-turn lookback](docs/concepts/architecture.md#multi-turn-prior-query-lookback-v081) for the full walkthrough.
-
-- **Additive schema migration** — new nullable `query_text TEXT` column on `context_usage`, guarded by `PRAGMA table_info`. Pre-v0.8.1 stores get the column added on first open; ad-hoc stores that skip the migration path degrade transparently via a feature-detect WeakMap so `insertUsageFn` never writes a column that doesn't exist.
-- **Discovery path only** — the multi-turn query feeds vector search, BM25, and query expansion. Cross-encoder reranking continues to use the RAW current prompt so relevance scoring is not diluted by older turns, and composite scoring / snippet extraction / dedupe / routing-hint detection all remain on the raw prompt as well.
-- **Privacy-conscious persistence split** — gated skip paths (slash commands, `MIN_PROMPT_LENGTH`, `shouldSkipRetrieval`, heartbeat dedupe) do NOT persist their raw text because those turns are not meaningful user questions and carry a higher sensitivity profile. Post-retrieval empty paths (empty result set, threshold blocked, budget blocked) DO persist so a follow-up turn can still inherit the intent even when the current turn surfaced nothing.
-- **Current-first truncation** — the combined query is clamped to 2000 chars with the current prompt preserved verbatim at the head. Older priors are dropped first when the budget runs out. If the current prompt alone already exceeds the cap, priors are omitted entirely and the current prompt is truncated.
-- **SQL-level self-match guard** — duplicate submits of the same prompt are filtered out of the lookback SELECT via `AND query_text != ?` so a retry burst cannot eat into the 2-prior budget and leave the lookback window underfilled.
-- **10-minute max age, session-scoped** — priors older than 10 minutes or from a different `session_id` are invisible to the lookback. All fallback paths (missing column, DB error, no matching rows) return the current prompt unchanged — the hook never throws on lookback failures.
-
-Adds +27 tests (22 unit + 5 integration) on top of the v0.8.0 baseline.
+Full version history is in [RELEASE_NOTES.md](RELEASE_NOTES.md). Upgrade instructions for existing vaults are in [docs/guides/upgrading.md](docs/guides/upgrading.md).
 
 ## Architecture
 
@@ -173,7 +114,7 @@ After installing, here's the full journey from zero to working memory:
 | **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) |
+| **4. Start services** | Run GPU servers (if using dedicated GPU) and background services. Optionally enable the v0.8.2 background maintenance workers in the watcher unit so consolidation + deductive synthesis run automatically. | `llama-server` for each model. systemd units for watcher + embed timer. Drop-in for the watcher to enable workers + tune intervals + set the quiet window. | [systemd services](docs/guides/systemd-services.md), [background workers](docs/guides/systemd-services.md#background-maintenance-workers-v082) |
 | **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, 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) |
@@ -223,6 +164,8 @@ clawmem embed             # Re-embed if upgrading embedding models (not needed f
 
 Routine patch updates (e.g. 0.2.0 → 0.2.1) do not require reindexing.
 
+For version-specific upgrade notes (opt-in features, optional cleanup steps, verification commands), see [docs/guides/upgrading.md](docs/guides/upgrading.md).
+
 ### Integration
 
 #### Claude Code

package/SKILL.md

@@ -85,14 +85,14 @@ curl http://host:8090/v1/models
 | `CLAWMEM_RERANK_URL` | `http://localhost:8090` | Reranker server. Falls to `node-llama-cpp` if unset + `NO_LOCAL_MODELS=false`. |
 | `CLAWMEM_NO_LOCAL_MODELS` | `false` | Blocks `node-llama-cpp` auto-downloads. Set `true` for remote-only. |
 | `CLAWMEM_ENABLE_AMEM` | enabled | A-MEM note construction + link generation during indexing. |
-| `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Background worker backfills unenriched docs. Needs long-lived MCP process. |
+| `CLAWMEM_ENABLE_CONSOLIDATION` | disabled | Light-lane consolidation worker (Phase 1 backfill + Phase 2 merge + Phase 3 deductive synthesis + Phase 4 recall stats). **v0.8.2:** every tick wraps in a `worker_leases` row (`light-consolidation` key) so multiple host processes against the same vault cannot race on Phase 2 merges. Hosted by `clawmem watch` (canonical) or `clawmem mcp` (per-session fallback). |
 | `CLAWMEM_CONSOLIDATION_INTERVAL` | 300000 | Worker interval in ms (min 15000). |
 | `CLAWMEM_MERGE_SCORE_NORMAL` | `0.93` | **v0.7.1.** Phase 2 merge-safety score threshold when candidate and existing anchors align. |
 | `CLAWMEM_MERGE_SCORE_STRICT` | `0.98` | **v0.7.1.** Strictest merge-safety threshold (fallback when anchors are ambiguous). |
 | `CLAWMEM_MERGE_GUARD_DRY_RUN` | `false` | **v0.7.1.** When `true`, Phase 2 merge-safety rejections are logged but not enforced — use for calibration. |
 | `CLAWMEM_CONTRADICTION_POLICY` | `link` | **v0.7.1.** How the merge-time contradiction gate handles a blocked merge. `link` (default) keeps both rows + inserts `contradicts` edge. `supersede` marks the old row `status='inactive'`. |
 | `CLAWMEM_CONTRADICTION_MIN_CONFIDENCE` | `0.5` | **v0.7.1.** Minimum combined heuristic+LLM confidence required before the contradiction gate blocks a merge. |
-| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance worker — a second, longer-interval consolidation lane with DB-backed `worker_leases` exclusivity, stale-first batching, and `maintenance_runs` journaling. Runs alongside the light lane. |
+| `CLAWMEM_HEAVY_LANE` | disabled | **v0.8.0.** Enable the quiet-window heavy maintenance worker — a second, longer-interval consolidation lane with DB-backed `worker_leases` exclusivity, stale-first batching, and `maintenance_runs` journaling. Runs alongside the light lane. **v0.8.2:** canonical host is `clawmem watch` (e.g. systemd `clawmem-watcher.service`); `clawmem mcp` retains the same gate as a fallback host but emits a stderr warning advising operators to move heavy-lane hosting to the watcher because per-session stdio MCPs may never be alive during the configured quiet window. |
 | `CLAWMEM_HEAVY_LANE_INTERVAL` | 1800000 | **v0.8.0.** Heavy-lane tick interval in ms (min 30000, default 30 min). |
 | `CLAWMEM_HEAVY_LANE_WINDOW_START` / `_END` | (none) | **v0.8.0.** Start/end hours (0-23) of the quiet window. Supports midnight wrap (22→6). Null on either bound = always in window. |
 | `CLAWMEM_HEAVY_LANE_MAX_USAGES` | 30 | **v0.8.0.** Max `context_usage` rows in the last 10 min before the heavy lane skips with `reason='query_rate_high'`. |
@@ -767,7 +767,7 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
 - SAME (composite scoring), MAGMA (intent + graph), A-MEM (self-evolving notes) layer on top of QMD substrate.
 - Three `llama-server` instances on local or remote GPU. Wrapper defaults to `localhost:8088/8089/8090`.
 - `CLAWMEM_NO_LOCAL_MODELS=false` (default) allows in-process fallback. Set `true` for remote-only to fail fast.
-- Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs. Only runs if MCP process stays alive long enough (every 5min).
+- Consolidation worker (`CLAWMEM_ENABLE_CONSOLIDATION=true`) backfills unenriched docs and runs Phase 2 merge / Phase 3 deductive synthesis. **v0.8.2:** hosted by either `clawmem watch` (long-lived, canonical) or `clawmem mcp` (per-session fallback); every tick acquires a `light-consolidation` `worker_leases` row before doing work, so dual-hosting against the same vault is safe.
 - 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+).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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

@@ -45,6 +45,14 @@ import { enrichResults, reciprocalRankFusion, toRanked, type RankedResult } from
 import { splitDocument } from "./splitter.ts";
 import { getProfile, updateProfile, isProfileStale } from "./profile.ts";
 import { regenerateAllDirectoryContexts } from "./directory-context.ts";
+import {
+  startConsolidationWorker,
+  stopConsolidationWorker,
+} from "./consolidation.ts";
+import {
+  parseHeavyLaneConfigFromEnv,
+  startHeavyMaintenanceWorker,
+} from "./maintenance.ts";
 import { readHookInput, writeHookOutput, makeEmptyOutput, type HookOutput } from "./hooks.ts";
 import { contextSurfacing } from "./hooks/context-surfacing.ts";
 import { sessionBootstrap } from "./hooks/session-bootstrap.ts";
@@ -1363,13 +1371,74 @@ async function cmdWatch() {
   const dirs = collections.map(col => col.path);
   const s = getStore();
 
+  // v0.8.2 Codex Turn 1 fix: register signal handlers BEFORE any async
+  // startup work or worker startup. Resources are declared as null and
+  // assigned once their respective creators run; the shutdown closure
+  // captures the variable references so updates after registration are
+  // visible. Without this ordering, a SIGTERM arriving during the brief
+  // window between the worker startup banner and the handler registration
+  // would terminate the watcher via the default signal action (exit 143)
+  // instead of running the async drain → release → close sequence.
+  let stopHeavyLane: (() => Promise<void>) | null = null;
+  let watcherHandle: { close: () => void } | null = null;
+  let checkpointTimerHandle: Timer | null = null;
+
+  // Graceful shutdown — stop workers, close watchers, then exit. SIGTERM
+  // handling is critical for systemd `systemctl --user stop` to shut down
+  // cleanly instead of being killed by the unit timeout. Both worker stops
+  // are awaited so any mid-tick worker drains and releases its lease via
+  // its own withWorkerLease finally block before we close the store.
+  const shutdown = async (signal: string) => {
+    console.log(`\n${c.dim}[watch] Received ${signal}, shutting down...${c.reset}`);
+    if (stopHeavyLane) {
+      await stopHeavyLane();
+      stopHeavyLane = null;
+    }
+    await stopConsolidationWorker();
+    if (checkpointTimerHandle) {
+      clearInterval(checkpointTimerHandle);
+      checkpointTimerHandle = null;
+    }
+    if (watcherHandle) {
+      watcherHandle.close();
+      watcherHandle = null;
+    }
+    closeStore();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => { void shutdown("SIGINT"); });
+  process.on("SIGTERM", () => { void shutdown("SIGTERM"); });
+
   console.log(`${c.bold}Watching ${dirs.length} collection(s) for changes...${c.reset}`);
   for (const col of collections) {
     console.log(`  ${c.dim}${col.name}: ${col.path}${c.reset}`);
   }
   console.log(`${c.dim}Press Ctrl+C to stop.${c.reset}`);
 
-  const watcher = startWatcher(dirs, {
+  // v0.8.2: Light + heavy maintenance lane workers (opt-in via env vars).
+  // Hosting them in `cmdWatch` makes the long-lived watcher service the
+  // canonical host for both lanes — `clawmem-watcher.service` runs 24/7
+  // under systemd, so the heavy lane's quiet-window logic actually sees a
+  // live worker at the configured hours regardless of whether any Claude
+  // Code session is open. `cmdMcp` (stdio MCP) keeps the same env-var
+  // gates as a fallback host, but warns when CLAWMEM_HEAVY_LANE=true
+  // since per-session MCPs are short-lived. Both hosts share the same
+  // DB-backed `worker_leases` exclusivity (heavy lane v0.8.0, light lane
+  // v0.8.2), so running both at once is safe.
+  if (Bun.env.CLAWMEM_ENABLE_CONSOLIDATION === "true") {
+    const llm = getDefaultLlamaCpp();
+    const intervalMs = parseInt(Bun.env.CLAWMEM_CONSOLIDATION_INTERVAL || "300000", 10);
+    console.log(`${c.dim}[watch] Starting consolidation worker (light lane, interval=${intervalMs}ms)${c.reset}`);
+    startConsolidationWorker(s, llm, intervalMs);
+  }
+  if (Bun.env.CLAWMEM_HEAVY_LANE === "true") {
+    const llm = getDefaultLlamaCpp();
+    const cfg = parseHeavyLaneConfigFromEnv();
+    console.log(`${c.dim}[watch] Starting heavy maintenance lane worker${c.reset}`);
+    stopHeavyLane = startHeavyMaintenanceWorker(s, llm, cfg);
+  }
+
+  watcherHandle = startWatcher(dirs, {
     debounceMs: 2000,
     onChanged: async (fullPath, event) => {
       // Find which collection this belongs to
@@ -1424,45 +1493,12 @@ async function cmdWatch() {
     },
   });
 
-  // Skill vault watcher: watch _clawmem-skills/ content root if configured
-  let skillWatcher: { close: () => void } | null = null;
-  try {
-    const { getVaultPath, getSkillContentRoot } = await import("./config.ts");
-    const { resolveStore } = await import("./store.ts");
-    const skillVaultPath = getVaultPath("skill");
-    const skillRoot = getSkillContentRoot();
-
-    if (skillVaultPath && existsSync(skillRoot)) {
-      const skillStore = resolveStore("skill");
-      console.log(`${c.bold}Watching skill vault content root...${c.reset}`);
-      console.log(`  ${c.dim}skill: ${skillRoot} → ${skillVaultPath}${c.reset}`);
-
-      skillWatcher = startWatcher([skillRoot], {
-        debounceMs: 2000,
-        onChanged: async (fullPath, event) => {
-          const relativePath = fullPath.slice(skillRoot.length + 1);
-          console.log(`${c.dim}[${event}]${c.reset} skill/${relativePath}`);
-
-          const stats = await indexCollection(skillStore, "skill-observations", skillRoot, "**/*.md");
-          if (stats.added > 0 || stats.updated > 0 || stats.removed > 0) {
-            console.log(`  skill: +${stats.added} ~${stats.updated} -${stats.removed}`);
-          }
-        },
-        onError: (err) => {
-          console.error(`${c.red}Skill watch error: ${err.message}${c.reset}`);
-        },
-      });
-    }
-  } catch {
-    // Skill vault not configured — skip
-  }
-
   // Periodic WAL checkpoint: the watcher holds a long-lived DB connection which
   // prevents SQLite auto-checkpoint from shrinking the WAL file. Without this,
   // the WAL grows unbounded (observed 77MB+), slowing every concurrent DB access
   // (hooks, MCP) and eventually causing UserPromptSubmit hook timeouts.
   const WAL_CHECKPOINT_INTERVAL = 5 * 60 * 1000; // 5 minutes
-  const checkpointTimer = setInterval(() => {
+  checkpointTimerHandle = setInterval(() => {
     try {
       s.db.exec("PRAGMA wal_checkpoint(PASSIVE)");
     } catch {
@@ -1470,16 +1506,7 @@ async function cmdWatch() {
     }
   }, WAL_CHECKPOINT_INTERVAL);
 
-  // Keep running until Ctrl+C
-  process.on("SIGINT", () => {
-    clearInterval(checkpointTimer);
-    watcher.close();
-    skillWatcher?.close();
-    closeStore();
-    process.exit(0);
-  });
-
-  // Block forever
+  // Block forever — shutdown is driven by signal handlers registered above.
   await new Promise(() => {});
 }
 

package/src/consolidation.ts

@@ -17,6 +17,7 @@ import type { LlamaCpp } from "./llm.ts";
 import { extractJsonFromLLM } from "./amem.ts";
 import { hashContent } from "./indexer.ts";
 import { passesMergeSafety } from "./text-similarity.ts";
+import { withWorkerLease } from "./worker-lease.ts";
 import {
   checkContradiction,
   isActionableContradiction,
@@ -166,22 +167,68 @@ let consolidationTimer: Timer | null = null;
 let isRunning = false;
 let tickCount = 0;
 
+/**
+ * DB-backed worker lease name for the light consolidation lane (v0.8.2).
+ * Distinct from the heavy-maintenance lane's lease so both lanes can hold
+ * independent exclusivity against the same SQLite vault without colliding.
+ */
+export const DEFAULT_LIGHT_LANE_WORKER_NAME = "light-consolidation";
+
+/**
+ * Default worker-lease TTL for the light lane (10 min). A tick normally
+ * finishes in seconds, but Phase 2 consolidation + Phase 3 deductive
+ * synthesis can stack many LLM calls under worst-case conditions. A 10-min
+ * ceiling covers that case without leaving a stranded lease forever if the
+ * process is SIGKILL'd mid-tick — the next worker reclaims it atomically
+ * via the single-statement upsert in `acquireWorkerLease` once the TTL
+ * has elapsed.
+ */
+export const DEFAULT_LIGHT_LANE_LEASE_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * Options for a single consolidation tick (v0.8.2). All fields optional;
+ * omitting the bag reproduces pre-v0.8.2 behavior except for the newly
+ * added DB-backed lease wrap, which is always on.
+ *
+ *  - `workerName`   override the lease name (default "light-consolidation").
+ *                   Tests should pass a unique name to avoid cross-test
+ *                   contention with other suites running in the same bun
+ *                   process.
+ *  - `leaseTtlMs`   override the lease TTL. Tests use short TTLs (e.g.
+ *                   100 ms with a past `now`) to exercise expiry reclaim
+ *                   without real delay.
+ */
+export interface ConsolidationTickOptions {
+  workerName?: string;
+  leaseTtlMs?: number;
+}
+
 // =============================================================================
 // Worker Functions
 // =============================================================================
 
 /**
- * Starts the consolidation worker that enriches documents missing A-MEM metadata
- * and periodically consolidates observations.
+ * Starts the consolidation worker that enriches documents missing A-MEM
+ * metadata and periodically consolidates observations.
  *
- * @param store - Store instance with A-MEM methods
- * @param llm - LLM instance for memory note construction
- * @param intervalMs - Tick interval in milliseconds (default: 300000 = 5 min)
+ * v0.8.2 — every tick is wrapped in a DB-backed worker lease (see
+ * `runConsolidationTick`), so multiple host processes running this worker
+ * against the same vault cannot run Phase 2 merge / Phase 3 deductive
+ * synthesis concurrently. The tick still uses an in-process `isRunning`
+ * reentrancy guard that fires before the lease round-trip, so the common
+ * case (single process, overlapping timer fires) is handled without
+ * touching SQLite.
+ *
+ * @param store      - Store instance with A-MEM methods
+ * @param llm        - LLM instance for memory note construction
+ * @param intervalMs - Tick interval in milliseconds (default 300000 = 5 min)
+ * @param opts       - Optional lease overrides (worker name, TTL)
  */
 export function startConsolidationWorker(
   store: Store,
   llm: LlamaCpp,
-  intervalMs: number = 300000
+  intervalMs: number = 300000,
+  opts: ConsolidationTickOptions = {},
 ): void {
   // Clamp interval to minimum 15 seconds
   const interval = Math.max(15000, intervalMs);
@@ -190,7 +237,7 @@ export function startConsolidationWorker(
 
   // Set up periodic tick
   consolidationTimer = setInterval(async () => {
-    await tick(store, llm);
+    await runConsolidationTick(store, llm, opts);
   }, interval);
 
   // Use unref() to avoid blocking process exit
@@ -200,55 +247,133 @@ export function startConsolidationWorker(
 }
 
 /**
- * Stops the consolidation worker.
+ * Stops the consolidation worker. Async since v0.8.2 — clears the interval
+ * AND awaits any in-flight tick before resolving, so callers (signal
+ * handlers, test fixtures) can safely close the store afterward without
+ * yanking the DB out from under a mid-tick worker. The wait is bounded by
+ * `STOP_DRAIN_TIMEOUT_MS` (15s) so a pathologically stuck tick cannot
+ * wedge shutdown indefinitely; if the timeout fires, the function logs
+ * and returns anyway (the next process will reclaim the stale lease via
+ * the v0.8.0 `worker_leases` TTL upsert).
  */
-export function stopConsolidationWorker(): void {
+export async function stopConsolidationWorker(): Promise<void> {
   if (consolidationTimer) {
     clearInterval(consolidationTimer);
     consolidationTimer = null;
+    console.log("[consolidation] Worker stop signaled — draining in-flight tick");
+  }
+  const deadline = Date.now() + STOP_DRAIN_TIMEOUT_MS;
+  while (isRunning && Date.now() < deadline) {
+    await new Promise<void>((resolve) => setTimeout(resolve, 50));
+  }
+  if (isRunning) {
+    console.log(
+      `[consolidation] Worker stop drain timed out after ${STOP_DRAIN_TIMEOUT_MS}ms — tick still running`,
+    );
+  } else {
     console.log("[consolidation] Worker stopped");
   }
 }
 
 /**
- * Single worker tick: A-MEM backfill + periodic observation consolidation.
+ * v0.8.2 — bounded wait for in-flight light-lane tick during shutdown.
+ * 15 seconds is more than enough for Phase 1 + Phase 4 to drain (the
+ * cheap phases) and lets Phase 2/3 mid-flight LLM calls finish naturally
+ * in most environments. Stuck-tick scenarios (e.g. unreachable LLM with
+ * no socket timeout) fall back to the v0.8.0 worker_leases TTL reclaim.
+ */
+const STOP_DRAIN_TIMEOUT_MS = 15_000;
+
+/**
+ * Run one consolidation tick: Phase 1 (A-MEM backfill) → Phase 2 (observation
+ * consolidation, every 6th tick) → Phase 3 (deductive synthesis, every 3rd
+ * tick) → Phase 4 (recall stats recomputation, every tick).
+ *
+ * v0.8.2 — wrapped in a DB-backed worker lease so at most one host process
+ * ticks at a time against the same vault, symmetric with the v0.8.0 heavy
+ * maintenance lane's `worker_leases` exclusivity pattern. Phase 2 is the
+ * race-sensitive phase Codex flagged in the v0.8.2 pre-rollout review:
+ * without the lease, two concurrent workers could both INSERT a new
+ * consolidated observation for the same cluster, or both merge into the
+ * same existing row and lose source_ids from the read-modify-write update
+ * in `mergeIntoExistingConsolidation`.
+ *
+ * An in-process reentrancy guard (`isRunning`) fires before the lease
+ * round-trip, so overlapping setInterval timer fires from the same process
+ * do not incur a SQLite round-trip per skip.
+ *
+ * Returns `{ acquired }` so integration tests (and the setInterval wrapper)
+ * can distinguish ticks that did real work from ticks skipped by the lease
+ * or reentrancy gate.
+ *
+ * Exported in v0.8.2 so tests can drive individual ticks directly without
+ * spinning up the setInterval loop.
  */
-async function tick(store: Store, llm: LlamaCpp): Promise<void> {
-  // Reentrancy guard
+export async function runConsolidationTick(
+  store: Store,
+  llm: LlamaCpp,
+  opts: ConsolidationTickOptions = {},
+): Promise<{ acquired: boolean }> {
+  // In-process reentrancy guard: catches overlapping setInterval fires in
+  // the same process before we hit SQLite. Cheap; the lease is the
+  // cross-process authority.
   if (isRunning) {
-    console.log("[consolidation] Skipping tick (already running)");
-    return;
+    console.log("[consolidation] Skipping tick (already running in-process)");
+    return { acquired: false };
   }
 
-  isRunning = true;
-  tickCount++;
+  const workerName = opts.workerName ?? DEFAULT_LIGHT_LANE_WORKER_NAME;
+  const leaseTtlMs = opts.leaseTtlMs ?? DEFAULT_LIGHT_LANE_LEASE_TTL_MS;
 
+  isRunning = true;
   try {
-    // Phase 1: A-MEM backfill (every tick)
-    await backfillAmem(store, llm);
+    const lease = await withWorkerLease(
+      store,
+      workerName,
+      leaseTtlMs,
+      async () => {
+        tickCount++;
+        try {
+          // Phase 1: A-MEM backfill (every tick)
+          await backfillAmem(store, llm);
+
+          // Phase 2: Observation consolidation (every 6th tick — ~30 min
+          // at default interval). Race-sensitive — see doc comment above.
+          if (tickCount % 6 === 0) {
+            await consolidateObservations(store, llm);
+          }
 
-    // Phase 2: Observation consolidation (every 6th tick, ~30 min at default interval)
-    if (tickCount % 6 === 0) {
-      await consolidateObservations(store, llm);
-    }
+          // Phase 3: Deductive synthesis (every 3rd tick — ~15 min).
+          // Writes are mostly idempotent on the hash-stable path but the
+          // anti-contamination validator still burns LLM calls, so
+          // running two workers in parallel is pure cost.
+          if (tickCount % 3 === 0) {
+            await generateDeductiveObservations(store, llm);
+          }
 
-    // Phase 3: Deductive synthesis (every 3rd tick, ~15 min at default interval)
-    if (tickCount % 3 === 0) {
-      await generateDeductiveObservations(store, llm);
-    }
+          // Phase 4: Recall stats recomputation (every tick — lightweight
+          // SQL aggregation). Non-critical — recall stats are
+          // informational, not retrieval-blocking.
+          try {
+            const updated = store.recomputeRecallStats();
+            if (updated > 0) {
+              console.log(`[consolidation] Phase 4: recomputed recall_stats for ${updated} docs`);
+            }
+          } catch (err) {
+            console.error("[consolidation] Phase 4 recall stats failed:", err);
+          }
+        } catch (err) {
+          console.error("[consolidation] Tick failed:", err);
+        }
+      },
+    );
 
-    // Phase 4: Recall stats recomputation (every tick — lightweight SQL aggregation)
-    try {
-      const updated = store.recomputeRecallStats();
-      if (updated > 0) {
-        console.log(`[consolidation] Phase 4: recomputed recall_stats for ${updated} docs`);
-      }
-    } catch (err) {
-      // Non-critical — recall stats are informational, not retrieval-blocking
-      console.error("[consolidation] Phase 4 recall stats failed:", err);
+    if (!lease.acquired) {
+      console.log(
+        `[consolidation] Skipping tick (lease '${workerName}' held by another worker)`,
+      );
     }
-  } catch (err) {
-    console.error("[consolidation] Tick failed:", err);
+    return { acquired: lease.acquired };
   } finally {
     isRunning = false;
   }

package/src/entity.ts

@@ -161,6 +161,53 @@ function makeEntityId(name: string, type: string, vault: string = 'default'): st
   return `${vault}:${type}:${normalized}`;
 }
 
+// =============================================================================
+// Entity Cap (content-type-aware, §1.5 v0.8.3)
+// =============================================================================
+
+/**
+ * Per-content-type entity cap applied to LLM extraction output.
+ *
+ * Long-form content (research dumps, conversation synthesis, hub/index docs)
+ * legitimately mentions more distinct entities than short decision records or
+ * handoff notes. A flat cap of 10 silently dropped real entities on long-form
+ * documents. This map lets each content type keep its full entity set up to a
+ * type-appropriate ceiling, while short types stay tight to suppress LLM noise.
+ *
+ * Unknown or untyped documents fall through to the default cap of 10 (matches
+ * pre-v0.8.3 behavior — backward compatible for any caller that doesn't pass
+ * a contentType).
+ */
+const ENTITY_CAP_BY_TYPE: Record<string, number> = {
+  research: 15,       // long-form research dumps
+  hub: 12,            // architecture docs, indexes
+  conversation: 12,   // synthesized conversation exports
+  decision: 8,        // short decision records
+  deductive: 8,       // inferred observations
+  note: 8,            // session notes
+  handoff: 8,         // session handoffs
+  progress: 8,        // progress logs
+  project: 10,        // generic project content
+};
+
+/**
+ * Return the entity cap for a given content type. Falls back to 10 for
+ * undefined or unknown types (pre-v0.8.3 behavior).
+ *
+ * Input is trimmed + lowercased before lookup so values from hand-authored
+ * frontmatter or older imported docs (e.g. "Research", " conversation ") map
+ * cleanly to the canonical lowercase keys in `ENTITY_CAP_BY_TYPE`. The DB
+ * `documents.content_type` column is not normalized at the write boundary,
+ * so normalization has to happen here to avoid silent fall-through to the
+ * default cap of 10.
+ */
+export function entityCapForContentType(contentType?: string): number {
+  if (!contentType) return 10;
+  const key = contentType.trim().toLowerCase();
+  if (!key) return 10;
+  return ENTITY_CAP_BY_TYPE[key] ?? 10;
+}
+
 // =============================================================================
 // Entity Extraction (LLM-based)
 // =============================================================================
@@ -168,14 +215,25 @@ function makeEntityId(name: string, type: string, vault: string = 'default'): st
 /**
  * Extract named entities from document content using LLM.
  * Returns a list of (name, type) pairs.
+ *
+ * @param contentType Optional document content_type. When provided, caps the
+ *   returned entity list using `entityCapForContentType`. When omitted, uses
+ *   the default cap of 10 (backward compatible).
  */
 export async function extractEntities(
   llm: LLM,
   title: string,
-  content: string
+  content: string,
+  contentType?: string
 ): Promise<ExtractedEntity[]> {
   const truncated = content.slice(0, 2000);
 
+  // v0.8.3 (§1.5): compute the cap up front so we can thread it into BOTH
+  // the prompt ("0-N entities") and the post-LLM slice. Without the dynamic
+  // prompt, a compliant model stops at the hardcoded 10 even when we'd
+  // accept 15 — the slice becomes a no-op and §1.5 is only half-effective.
+  const cap = entityCapForContentType(contentType);
+
   const prompt = `Extract named entities from this document. Include people, projects, services, tools, organizations, and specific technical components.
 
 Title: ${title}
@@ -189,7 +247,7 @@ Return ONLY valid JSON array:
 Rules:
 - Only include specific, named entities (not generic concepts like "database" or "testing")
 - Normalize names: "VM 202" not "vm202", "ClawMem" not "clawmem"
-- 0-10 entities. Return empty array [] if no specific entities found
+- 0-${cap} entities. Return empty array [] if no specific entities found
 - Include the most specific type for each entity
 - Do NOT extract the document's title as an entity
 - Do NOT extract heading labels, section names, or sentence fragments
@@ -217,7 +275,7 @@ Return ONLY the JSON array. /no_think`;
         ['person', 'project', 'service', 'tool', 'concept', 'org', 'location'].includes(e.type)
       )
       .filter(e => !isLowQualityEntity(e.name, e.type, title))
-      .slice(0, 10);
+      .slice(0, cap);
   } catch (err) {
     console.log(`[entity] LLM extraction failed:`, err);
     return [];
@@ -454,12 +512,14 @@ export async function enrichDocumentEntities(
 ): Promise<number> {
   try {
     // Get document content (snapshot for extraction)
+    // v0.8.3 (§1.5): fetch content_type so extractEntities can apply a
+    // content-type-aware cap instead of the flat slice(0, 10).
     const doc = db.prepare(`
-      SELECT d.title, c.doc as body
+      SELECT d.title, d.content_type, c.doc as body
       FROM documents d
       JOIN content c ON c.hash = d.hash
       WHERE d.id = ? AND d.active = 1
-    `).get(docId) as { title: string; body: string } | null;
+    `).get(docId) as { title: string; content_type: string | null; body: string } | null;
 
     if (!doc) {
       console.log(`[entity] Document ${docId} not found or inactive`);
@@ -478,8 +538,8 @@ export async function enrichDocumentEntities(
       return 0; // Same input, already enriched — skip
     }
 
-    // Step 1: Extract entities via LLM
-    const entities = await extractEntities(llm, doc.title, doc.body);
+    // Step 1: Extract entities via LLM (cap is content-type-aware as of v0.8.3 §1.5)
+    const entities = await extractEntities(llm, doc.title, doc.body, doc.content_type ?? undefined);
 
     // Recheck input hash before writing — abort if content changed during LLM call
     const recheckHash = db.prepare(`

package/src/maintenance.ts

@@ -77,6 +77,37 @@ const DEFAULT_CONFIG: Required<Omit<HeavyMaintenanceConfig, "workerName" | "cloc
 
 const DEFAULT_WORKER_NAME = "heavy-maintenance";
 
+/**
+ * Parse a `HeavyMaintenanceConfig` from `Bun.env` (v0.8.2). Shared by every
+ * host that can start the heavy lane (`cmdMcp` in mcp.ts, `cmdWatch` in
+ * clawmem.ts) so the env var convention stays in one place. Each field is
+ * left undefined when its env var is unset, so `DEFAULT_CONFIG` continues
+ * to drive any field the operator did not explicitly override.
+ */
+export function parseHeavyLaneConfigFromEnv(): HeavyMaintenanceConfig {
+  return {
+    intervalMs: Bun.env.CLAWMEM_HEAVY_LANE_INTERVAL
+      ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_INTERVAL, 10)
+      : undefined,
+    windowStartHour: Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_START
+      ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_START, 10)
+      : null,
+    windowEndHour: Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_END
+      ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_END, 10)
+      : null,
+    maxContextUsagesPer10m: Bun.env.CLAWMEM_HEAVY_LANE_MAX_USAGES
+      ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_MAX_USAGES, 10)
+      : undefined,
+    staleObservationLimit: Bun.env.CLAWMEM_HEAVY_LANE_OBS_LIMIT
+      ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_OBS_LIMIT, 10)
+      : undefined,
+    staleDeductiveLimit: Bun.env.CLAWMEM_HEAVY_LANE_DED_LIMIT
+      ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_DED_LIMIT, 10)
+      : undefined,
+    useSurprisalSelector: Bun.env.CLAWMEM_HEAVY_LANE_SURPRISAL === "true",
+  };
+}
+
 // =============================================================================
 // Journal helpers
 // =============================================================================
@@ -503,7 +534,7 @@ export function startHeavyMaintenanceWorker(
   store: Store,
   llm: LlamaCpp,
   cfg: HeavyMaintenanceConfig = {},
-): () => void {
+): () => Promise<void> {
   const merged = { ...DEFAULT_CONFIG, ...cfg };
   // Clamp interval to minimum 30 seconds so buggy configs can't pin the CPU.
   const interval = Math.max(30_000, merged.intervalMs);
@@ -530,11 +561,35 @@ export function startHeavyMaintenanceWorker(
   }, interval);
   heavyTimer.unref();
 
-  return () => {
+  // v0.8.2 — async stop handle. Clears the timer AND awaits any in-flight
+  // tick before resolving, so callers can safely close the store afterward
+  // without yanking the DB from under a mid-tick worker. Bounded wait —
+  // a pathologically stuck tick cannot wedge shutdown indefinitely; the
+  // worker_leases TTL upsert reclaims any stranded lease on the next
+  // process startup.
+  return async () => {
     if (heavyTimer) {
       clearInterval(heavyTimer);
       heavyTimer = null;
+      console.log("[heavy-lane] Worker stop signaled — draining in-flight tick");
+    }
+    const deadline = Date.now() + HEAVY_STOP_DRAIN_TIMEOUT_MS;
+    while (heavyRunning && Date.now() < deadline) {
+      await new Promise<void>((resolve) => setTimeout(resolve, 50));
+    }
+    if (heavyRunning) {
+      console.log(
+        `[heavy-lane] Worker stop drain timed out after ${HEAVY_STOP_DRAIN_TIMEOUT_MS}ms — tick still running`,
+      );
+    } else {
       console.log("[heavy-lane] Worker stopped");
     }
   };
 }
+
+/**
+ * v0.8.2 — bounded wait for in-flight heavy-lane tick during shutdown.
+ * 30 seconds covers a Phase 2 + Phase 3 stack with reasonable LLM latencies
+ * before falling back to the worker_leases TTL reclaim path.
+ */
+const HEAVY_STOP_DRAIN_TIMEOUT_MS = 30_000;

package/src/mcp.ts

@@ -39,7 +39,10 @@ import { classifyIntent, decomposeQuery, extractTemporalConstraint, type IntentT
 import { adaptiveTraversal, mergeTraversalResults, mpfpTraversal } from "./graph-traversal.ts";
 import { getDefaultLlamaCpp } from "./llm.ts";
 import { startConsolidationWorker, stopConsolidationWorker } from "./consolidation.ts";
-import { startHeavyMaintenanceWorker, type HeavyMaintenanceConfig } from "./maintenance.ts";
+import {
+  parseHeavyLaneConfigFromEnv,
+  startHeavyMaintenanceWorker,
+} from "./maintenance.ts";
 import { listVaults, loadVaultConfig } from "./config.ts";
 import { getEntityGraphNeighbors, searchEntities } from "./entity.ts";
 
@@ -2595,8 +2598,37 @@ This is the recommended entry point for ALL memory queries.`,
   await server.connect(transport);
 
   // ---------------------------------------------------------------------------
-  // Consolidation Worker
-  // ---------------------------------------------------------------------------
+  // Shutdown wiring + Workers
+  // ---------------------------------------------------------------------------
+
+  // v0.8.2 Codex Turn 2 fix: register signal handlers BEFORE any worker
+  // startup, mirroring the same null-handle capture pattern that cmdWatch
+  // uses. The handler is the only thing that suppresses Node's default
+  // signal action (terminate), so a SIGTERM arriving in the brief window
+  // between worker startup and `process.on(...)` registration would
+  // exit-143 the process and skip the async drain entirely, leaking any
+  // lease the worker had just acquired. Capturing `stopHeavyLane` as a
+  // mutable closure variable lets the registration happen before the
+  // worker is actually created — the handler reads whatever value is
+  // bound at the moment a signal arrives.
+  let stopHeavyLane: (() => Promise<void>) | null = null;
+
+  // Signal handlers for graceful shutdown. async stop sequence: both
+  // worker stops await any in-flight tick before resolving so the store
+  // is not closed underneath a mid-tick worker. Bounded waits inside the
+  // stop functions guarantee the handler cannot wedge indefinitely.
+  const shutdownMcp = async (signal: string) => {
+    console.error(`\n[mcp] Received ${signal}, shutting down...`);
+    if (stopHeavyLane) {
+      await stopHeavyLane();
+      stopHeavyLane = null;
+    }
+    await stopConsolidationWorker();
+    closeAllStores();
+    process.exit(0);
+  };
+  process.on("SIGINT", () => { void shutdownMcp("SIGINT"); });
+  process.on("SIGTERM", () => { void shutdownMcp("SIGTERM"); });
 
   // Start consolidation worker if enabled
   if (Bun.env.CLAWMEM_ENABLE_CONSOLIDATION === "true") {
@@ -2609,49 +2641,25 @@ This is the recommended entry point for ALL memory queries.`,
   // longer interval than the light lane, only inside a configurable quiet
   // window, and gated by context_usage query-rate so interactive sessions
   // are never starved. Off by default.
-  let stopHeavyLane: (() => void) | null = null;
+  //
+  // v0.8.2: warn when this lane is enabled on a stdio MCP host. Per-session
+  // MCPs spawned by Claude Code die with the session, which means the
+  // configured quiet window may never see a live worker if no Claude Code
+  // session is open at that time. The watcher service (`clawmem watch`) is
+  // the canonical long-lived host for the heavy lane as of v0.8.2 — see
+  // docs/concepts/architecture.md and docs/guides/upgrading.md for the
+  // dual-host rationale.
   if (Bun.env.CLAWMEM_HEAVY_LANE === "true") {
+    console.error(
+      "[mcp] WARNING: CLAWMEM_HEAVY_LANE=true on a stdio MCP host. " +
+        "Per-session MCPs are short-lived; the configured quiet window may " +
+        "never see a live worker. As of v0.8.2 the canonical heavy-lane host " +
+        "is `clawmem watch` (e.g. systemd user unit clawmem-watcher.service). " +
+        "Set the same env var on the watcher service for reliable operation.",
+    );
     const llm = getDefaultLlamaCpp();
-    const cfg: HeavyMaintenanceConfig = {
-      intervalMs: Bun.env.CLAWMEM_HEAVY_LANE_INTERVAL
-        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_INTERVAL, 10)
-        : undefined,
-      windowStartHour: Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_START
-        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_START, 10)
-        : null,
-      windowEndHour: Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_END
-        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_WINDOW_END, 10)
-        : null,
-      maxContextUsagesPer10m: Bun.env.CLAWMEM_HEAVY_LANE_MAX_USAGES
-        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_MAX_USAGES, 10)
-        : undefined,
-      staleObservationLimit: Bun.env.CLAWMEM_HEAVY_LANE_OBS_LIMIT
-        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_OBS_LIMIT, 10)
-        : undefined,
-      staleDeductiveLimit: Bun.env.CLAWMEM_HEAVY_LANE_DED_LIMIT
-        ? parseInt(Bun.env.CLAWMEM_HEAVY_LANE_DED_LIMIT, 10)
-        : undefined,
-      useSurprisalSelector: Bun.env.CLAWMEM_HEAVY_LANE_SURPRISAL === "true",
-    };
-    stopHeavyLane = startHeavyMaintenanceWorker(store, llm, cfg);
+    stopHeavyLane = startHeavyMaintenanceWorker(store, llm, parseHeavyLaneConfigFromEnv());
   }
-
-  // Signal handlers for graceful shutdown
-  process.on("SIGINT", () => {
-    console.error("\n[mcp] Received SIGINT, shutting down...");
-    stopConsolidationWorker();
-    if (stopHeavyLane) stopHeavyLane();
-    closeAllStores();
-    process.exit(0);
-  });
-
-  process.on("SIGTERM", () => {
-    console.error("\n[mcp] Received SIGTERM, shutting down...");
-    stopConsolidationWorker();
-    if (stopHeavyLane) stopHeavyLane();
-    closeAllStores();
-    process.exit(0);
-  });
 }
 
 if (import.meta.main) {

package/src/store.ts

@@ -1543,6 +1543,10 @@ export function createStore(dbPath?: string, opts?: { readonly?: boolean; busyTi
 
     // Usage relation tracking — records relations between documents
     insertRelation: (fromDoc: number, toDoc: number, relType: string, weight: number = 1.0) => {
+      // v0.8.3 (§1.3): reject self-loops at the API boundary. A document
+      // relating to itself has no informational value for graph traversal
+      // and would pollute intent_search/find_similar neighborhoods.
+      if (fromDoc === toDoc) return;
       db.prepare(`
         INSERT INTO memory_relations (source_id, target_id, relation_type, weight, created_at)
         VALUES (?, ?, ?, ?, ?)
@@ -4224,6 +4228,10 @@ export async function syncBeadsIssues(
     const targetRow = db.prepare(`SELECT doc_id FROM beads_issues WHERE beads_id = ?`).get(dep.target_id) as { doc_id: number } | undefined;
 
     if (sourceRow && targetRow) {
+      // v0.8.3 (§1.3): mirror of insertRelation self-loop guard. Beads can
+      // theoretically express a self-dependency (e.g. a `relates-to` edge
+      // from an issue to itself); skip those before they land in the graph.
+      if (sourceRow.doc_id === targetRow.doc_id) continue;
       db.prepare(`
         INSERT OR IGNORE INTO memory_relations (source_id, target_id, relation_type, weight, metadata, created_at)
         VALUES (?, ?, ?, 1.0, ?, ?)