clawmem 0.8.0 → 0.8.2

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). |
@@ -259,7 +259,7 @@ ClawMem hooks handle ~90% of retrieval automatically. Agent-initiated MCP calls
 
 | Hook | Trigger | Budget | Content |
 |------|---------|--------|---------|
-| `context-surfacing` | UserPromptSubmit | profile-driven (default 800) | retrieval gate → profile-driven hybrid search (vector if `useVector`, timeout from profile) → FTS supplement → file-aware supplemental search (E13) → snooze filter → noise filter → spreading activation (E11: co-activated doc boost) → memory type diversification (E10) → tiered injection (HOT/WARM/COLD snippets) → `<vault-context><instruction>…</instruction><facts>…</facts><relationships>…</relationships></vault-context>` (v0.7.1: instruction always prepended when context is returned; relationships block lists memory-graph edges where BOTH endpoints are in the surfaced set, truncated first when over budget) + optional `<vault-routing>` hint. Budget, max results, vector timeout, and min score all driven by `CLAWMEM_PROFILE`. |
+| `context-surfacing` | UserPromptSubmit | profile-driven (default 800) | retrieval gate → **multi-turn query construction** (v0.8.1: current prompt + up to 2 recent same-session priors from `context_usage.query_text`, 10-min max age, capped at 2000 chars with current-first preservation — used only for discovery: vector/FTS/expansion, NOT for rerank/scoring/snippet extraction) → profile-driven hybrid search (vector if `useVector`, timeout from profile) → FTS supplement → file-aware supplemental search (E13, raw current prompt) → snooze filter → noise filter → spreading activation (E11: co-activated doc boost) → memory type diversification (E10) → tiered injection (HOT/WARM/COLD snippets) → `<vault-context><instruction>…</instruction><facts>…</facts><relationships>…</relationships></vault-context>` (v0.7.1: instruction always prepended when context is returned; relationships block lists memory-graph edges where BOTH endpoints are in the surfaced set, truncated first when over budget) + optional `<vault-routing>` hint. Budget, max results, vector timeout, and min score all driven by `CLAWMEM_PROFILE`. Raw prompt persisted to `context_usage.query_text` for future multi-turn lookback — except on gated skip paths (slash commands, heartbeats, too-short prompts) where the text is withheld for privacy. |
 | `postcompact-inject` | SessionStart (compact) | 1200 tokens | re-injects authoritative context after compaction: precompact state (600) + recent decisions (400) + antipatterns (150) + vault context (200) → `<vault-postcompact>` |
 | `curator-nudge` | SessionStart | 200 tokens | surfaces curator report actions, nudges when report is stale (>7 days) |
 | `precompact-extract` | PreCompact | — | extracts decisions, file paths, open questions → writes `precompact-state.md` to auto-memory. Query-aware decision ranking. Reindexes auto-memory collection. |

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). |
@@ -259,7 +259,7 @@ ClawMem hooks handle ~90% of retrieval automatically. Agent-initiated MCP calls
 
 | Hook | Trigger | Budget | Content |
 |------|---------|--------|---------|
-| `context-surfacing` | UserPromptSubmit | profile-driven (default 800) | retrieval gate → profile-driven hybrid search (vector if `useVector`, timeout from profile) → FTS supplement → file-aware supplemental search (E13) → snooze filter → noise filter → spreading activation (E11: co-activated doc boost) → memory type diversification (E10) → tiered injection (HOT/WARM/COLD snippets) → `<vault-context><instruction>…</instruction><facts>…</facts><relationships>…</relationships></vault-context>` (v0.7.1: instruction always prepended when context is returned; relationships block lists memory-graph edges where BOTH endpoints are in the surfaced set, truncated first when over budget) + optional `<vault-routing>` hint. Budget, max results, vector timeout, and min score all driven by `CLAWMEM_PROFILE`. |
+| `context-surfacing` | UserPromptSubmit | profile-driven (default 800) | retrieval gate → **multi-turn query construction** (v0.8.1: current prompt + up to 2 recent same-session priors from `context_usage.query_text`, 10-min max age, capped at 2000 chars with current-first preservation — used only for discovery: vector/FTS/expansion, NOT for rerank/scoring/snippet extraction) → profile-driven hybrid search (vector if `useVector`, timeout from profile) → FTS supplement → file-aware supplemental search (E13, raw current prompt) → snooze filter → noise filter → spreading activation (E11: co-activated doc boost) → memory type diversification (E10) → tiered injection (HOT/WARM/COLD snippets) → `<vault-context><instruction>…</instruction><facts>…</facts><relationships>…</relationships></vault-context>` (v0.7.1: instruction always prepended when context is returned; relationships block lists memory-graph edges where BOTH endpoints are in the surfaced set, truncated first when over budget) + optional `<vault-routing>` hint. Budget, max results, vector timeout, and min score all driven by `CLAWMEM_PROFILE`. Raw prompt persisted to `context_usage.query_text` for future multi-turn lookback — except on gated skip paths (slash commands, heartbeats, too-short prompts) where the text is withheld for privacy. |
 | `postcompact-inject` | SessionStart (compact) | 1200 tokens | re-injects authoritative context after compaction: precompact state (600) + recent decisions (400) + antipatterns (150) + vault context (200) → `<vault-postcompact>` |
 | `curator-nudge` | SessionStart | 200 tokens | surfaces curator report actions, nudges when report is stale (>7 days) |
 | `precompact-extract` | PreCompact | — | extracts decisions, file paths, open questions → writes `precompact-state.md` to auto-memory. Query-aware decision ranking. Reindexes auto-memory collection. |

package/README.md

@@ -95,6 +95,35 @@ A second, longer-interval consolidation worker that keeps Phase 2 + Phase 3 runn
 
 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.
+
+### v0.8.2 Dual-Host Worker Architecture
+
+Both maintenance lanes can now be hosted by the long-lived `clawmem watch` watcher service in addition to the existing per-session `clawmem mcp` host. This makes the systemd-managed watcher the canonical 24/7 home for the v0.8.0 heavy maintenance lane — its quiet-window logic finally sees a live worker at the configured hours regardless of whether any Claude Code session is open. The light consolidation lane (Phase 1 backfill + Phase 2 merge + Phase 3 deductive synthesis + Phase 4 recall stats) now also acquires its own DB-backed `worker_leases` row before each tick, symmetric with the heavy lane's existing exclusivity, so multiple host processes against the same vault cannot race on Phase 2 merges or Phase 3 deductive writes.
+
+- **Light-lane worker lease** — `runConsolidationTick` wraps every tick (Phase 1 → 4) in `withWorkerLease` against a new `light-consolidation` worker name with a 10-minute TTL. Two host processes (e.g. one watcher service + one per-session stdio MCP) cannot both consolidate the same near-duplicate observations or both INSERT a duplicate row into `consolidated_observations`. Phase 1 enrichment is also serialized — overkill for cost but cleaner for symmetry. The in-process `isRunning` reentrancy guard remains the cheap first defense before the SQLite lease round-trip.
+- **`cmdWatch` hosts both workers** — `clawmem watch` honors the same `CLAWMEM_ENABLE_CONSOLIDATION` and `CLAWMEM_HEAVY_LANE` env-var gates as `cmdMcp`. Off by default. Mirror the existing systemd unit (or your wrapper `.env`) to opt in. The recommended deployment for v0.8.2+ is to set both env vars on `clawmem-watcher.service` and leave `cmdMcp` unset, so the heavy lane has a continuously available host independent of Claude Code session lifecycle.
+- **`cmdMcp` is now a fallback host with a heavy-lane warning** — `cmdMcp` retains the same env-var gates so non-watcher deployments (e.g. macOS users running everything via Claude Code launchd) keep working unchanged. When `CLAWMEM_HEAVY_LANE=true` is set on a stdio MCP host, `cmdMcp` emits a one-line warning to stderr advising operators to move heavy-lane hosting to `clawmem watch` instead.
+- **Async drain on shutdown** — both worker stop helpers (`stopConsolidationWorker` and the closure returned by `startHeavyMaintenanceWorker`) are now `async`, clearing their `setInterval` AND polling their in-flight running flag until any mid-tick worker drains. This guarantees the worker's `withWorkerLease` finally block runs against a still-open store, so the lease is released cleanly instead of leaking until TTL expiry. Bounded waits (15s light, 30s heavy) prevent a stuck tick from wedging shutdown indefinitely; the next process reclaims any stranded lease atomically.
+- **Signal handlers registered before worker startup** — both `cmdWatch` and `cmdMcp` now register their `SIGINT`/`SIGTERM` handlers BEFORE any worker initialization. A signal arriving in the brief window between worker startup and handler registration would otherwise terminate the host via the default signal action (exit 143) and skip the async drain entirely.
+- **Subprocess smoke test** — new `tests/integration/cmdwatch-workers.integration.test.ts` spawns `bun src/clawmem.ts watch` against a temp vault with short worker intervals, exercises the env-var gates, exercises a real heavy-lane tick (slow path, ~35s), and asserts the lease is released cleanly on `SIGTERM`.
+- **Bug fix: removed dead skill-vault watcher block from `clawmem.ts cmdWatch()`** — a try/catch wrapped block had been silently destructuring `getSkillContentRoot` from `./config.ts`, but that helper is forge-internal and was never exported in public ClawMem. The runtime catch swallowed the failure so it had no observable effect, but TypeScript flagged a static `TS2339` error on the destructure. v0.8.2 removes the dead code path. No behavior change for public users.
+
+Adds +15 tests (9 light-lane lease unit + 5 cmdWatch fast subprocess + 1 cmdWatch slow subprocess) on top of the v0.8.1 baseline.
+
+For operational guidance — enabling the workers via systemd drop-in, tuning intervals to your usage pattern, monitoring queries, and rollback steps — see [docs/guides/systemd-services.md](docs/guides/systemd-services.md#background-maintenance-workers-v082).
+
 ## Architecture
 
 <p align="center">
@@ -160,7 +189,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) |
@@ -210,6 +239,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
@@ -1187,6 +1218,7 @@ Built on the shoulders of:
 - [QMD](https://github.com/tobi/qmd) — search backend (BM25 + vectors + RRF + reranking)
 - [SAME](https://github.com/sgx-labs/statelessagent) — agent memory concepts (recency decay, confidence scoring, session tracking)
 - [supermemory](https://github.com/supermemoryai/clawdbot-supermemory) — hook patterns and context surfacing ideas
+- [Thoth](https://github.com/siddsachar/Thoth) — anti-contamination deductive synthesis, contradiction-aware + name-aware merge gates, post-import conversation fact extraction, quiet-window heavy maintenance lane with worker leases, context instruction framing, relationship snippets, multi-turn prior-query lookback
 
 ## Roadmap
 

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'`. |
@@ -190,7 +190,7 @@ Hooks handle ~90% of retrieval. Zero agent effort.
 
 | Hook | Trigger | Budget | Content |
 |------|---------|--------|---------|
-| `context-surfacing` | UserPromptSubmit | profile-driven (default 800) | retrieval gate -> profile-driven hybrid search (vector if `useVector`, timeout from profile) -> FTS supplement -> file-aware search (E13) -> snooze filter -> noise filter -> spreading activation (E11) -> memory type diversification (E10) -> tiered injection (HOT/WARM/COLD) -> `<vault-context><instruction>...</instruction><facts>...</facts><relationships>...</relationships></vault-context>` (v0.7.1: instruction always prepended; relationships list memory-graph edges where BOTH endpoints are in the surfaced set; relationships truncated first when over budget) + optional `<vault-routing>` hint. Budget, max results, vector timeout, min score all driven by `CLAWMEM_PROFILE`. |
+| `context-surfacing` | UserPromptSubmit | profile-driven (default 800) | retrieval gate -> **multi-turn query** (v0.8.1: current + up to 2 recent same-session priors from `context_usage.query_text`, 10-min max age, 2000-char cap with current-first, used only for discovery — not rerank/scoring/snippet) -> profile-driven hybrid search (vector if `useVector`, timeout from profile) -> FTS supplement -> file-aware search (E13, raw current) -> snooze filter -> noise filter -> spreading activation (E11) -> memory type diversification (E10) -> tiered injection (HOT/WARM/COLD) -> `<vault-context><instruction>...</instruction><facts>...</facts><relationships>...</relationships></vault-context>` (v0.7.1: instruction always prepended; relationships list memory-graph edges where BOTH endpoints are in the surfaced set; relationships truncated first when over budget) + optional `<vault-routing>` hint. Budget, max results, vector timeout, min score all driven by `CLAWMEM_PROFILE`. Raw prompt persisted to `context_usage.query_text` for future lookback — gated skip paths (slash commands, heartbeats, too-short prompts) withhold the text for privacy. |
 | `postcompact-inject` | SessionStart (compact) | 1200 tokens | re-injects authoritative context after compaction: precompact state (600) + decisions (400) + antipatterns (150) + vault context (200) -> `<vault-postcompact>` |
 | `curator-nudge` | SessionStart | 200 tokens | surfaces curator report actions, nudges when report is stale (>7 days) |
 | `precompact-extract` | PreCompact | — | extracts decisions, file paths, open questions -> writes `precompact-state.md`. Query-aware ranking. Reindexes auto-memory. |
@@ -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.0",
+  "version": "0.8.2",
   "description": "On-device context engine and memory for AI agents. Claude Code and OpenClaw. Hooks + MCP server + hybrid RAG search.",
   "type": "module",
   "bin": {

package/src/clawmem.ts

@@ -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/hooks/context-surfacing.ts

@@ -69,6 +69,19 @@ const INSTRUCTION_TOKEN_COST = estimateTokens(INSTRUCTION_XML);
 const RELATIONSHIPS_XML_OVERHEAD_TOKENS = estimateTokens("<relationships>\n\n</relationships>");
 const MAX_RELATION_SNIPPETS = 10;
 
+// Ext 6b: Multi-turn prior-query lookback
+// The retrieval query is built from the current prompt plus up to
+// MULTI_TURN_LOOKBACK recent same-session prior prompts within
+// MULTI_TURN_MAX_AGE_MINUTES. The combined query is clamped to
+// MULTI_TURN_MAX_CHARS with newest content preserved first — so the
+// current prompt is always the first N chars even when older priors
+// would otherwise push it out. All other hook signals (scoring,
+// composite recency intent, recall attribution, routing hints)
+// continue to use the raw current prompt.
+const MULTI_TURN_LOOKBACK = 2;
+const MULTI_TURN_MAX_AGE_MINUTES = 10;
+const MULTI_TURN_MAX_CHARS = 2000;
+
 // File path patterns to extract from prompts (E13 replacement: file-aware UserPromptSubmit)
 const FILE_PATH_RE = /(?:^|\s)((?:\/[\w.@-]+)+(?:\.\w+)?|[\w.@-]+\.(?:ts|js|py|md|sh|yaml|yml|json|toml|rs|go|tsx|jsx|css|html))\b/g;
 
@@ -133,12 +146,25 @@ export async function contextSurfacing(
   const isRecency = hasRecencyIntent(prompt);
   const minScore = isRecency ? MIN_COMPOSITE_SCORE_RECENCY : profile.minScore;
 
+  // Ext 6b: Build the retrieval query from the current prompt plus up to
+  // MULTI_TURN_LOOKBACK recent same-session prior prompts. Used only for
+  // the discovery path (vector, FTS, query expansion, reranking) so that
+  // a short "do that" / "same for X" turn can inherit the vocabulary of
+  // earlier turns. All other prompt-dependent signals (recency intent,
+  // composite scoring, recall attribution, snippet highlighting, routing
+  // hints, dedupe, heartbeat check) continue to use the raw current
+  // prompt. If the session has no priors in the window, the helper
+  // returns the current prompt unchanged.
+  const retrievalQuery = input.sessionId
+    ? buildMultiTurnSurfacingQuery(store, input.sessionId, prompt)
+    : prompt;
+
   // Search: try vector first (if profile allows), fall back to BM25
   // When vector succeeds, also supplement with FTS for keyword-exact recall
   let results: SearchResult[] = [];
   if (profile.useVector) {
     try {
-      const vectorPromise = store.searchVec(prompt, DEFAULT_EMBED_MODEL, maxResults);
+      const vectorPromise = store.searchVec(retrievalQuery, DEFAULT_EMBED_MODEL, maxResults);
       const timeoutPromise = new Promise<SearchResult[]>((_, reject) =>
         setTimeout(() => reject(new Error("vector timeout")), profile.vectorTimeout)
       );
@@ -149,11 +175,11 @@ export async function contextSurfacing(
   }
 
   if (results.length === 0) {
-    results = store.searchFTS(prompt, maxResults);
+    results = store.searchFTS(retrievalQuery, maxResults);
   } else {
     // Supplement vector results with FTS for keyword-exact matches (<10ms)
     const seen = new Set(results.map(r => r.filepath));
-    const ftsSupplemental = store.searchFTS(prompt, 5);
+    const ftsSupplemental = store.searchFTS(retrievalQuery, 5);
     for (const r of ftsSupplemental) {
       if (!seen.has(r.filepath)) {
         seen.add(r.filepath);
@@ -166,7 +192,7 @@ export async function contextSurfacing(
   if (getVaultPath("skill")) {
     try {
       const skillStore = resolveStore("skill");
-      const skillResults = skillStore.searchFTS(prompt, 5);
+      const skillResults = skillStore.searchFTS(retrievalQuery, 5);
       // Tag skill vault results for identification in output
       for (const r of skillResults) {
         (r as any)._fromVault = "skill";
@@ -178,7 +204,9 @@ export async function contextSurfacing(
   }
 
   // File-aware supplemental search (E13 replacement): extract file paths/names from prompt
-  // and run targeted FTS queries to surface file-specific vault context
+  // and run targeted FTS queries to surface file-specific vault context.
+  // File-path extraction stays on the raw current prompt so priors cannot
+  // pollute the file-specific discovery channel with stale filenames.
   const fileMatches = [...prompt.matchAll(FILE_PATH_RE)].map(m => m[1]!.trim()).filter(Boolean);
   if (fileMatches.length > 0) {
     const seen = new Set(results.map(r => r.filepath));
@@ -195,17 +223,23 @@ export async function contextSurfacing(
     }
   }
 
-  if (results.length === 0) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
+  if (results.length === 0) { logEmptyTurn(store, input, prompt); return makeEmptyOutput("context-surfacing"); }
 
   // Budget-aware deep escalation (deep profile only):
   // If the fast path finished quickly and found results, spend remaining time budget
   // on query expansion (discovers new candidates) and cross-encoder reranking (reorders).
+  // Ext 6b: expansion + FTS variants use the multi-turn retrieval query so
+  // short current prompts still inherit prior-turn vocabulary. Reranking
+  // continues to use the RAW current prompt so relevance scoring is not
+  // diluted by older turns — the cross-encoder is asked "how well does
+  // this doc match the user's current question", not "how well does it
+  // match the last 10 minutes of questions".
   if (profile.deepEscalation && results.length >= 2) {
     const elapsed = Date.now() - startTime;
     if (elapsed < profile.escalationBudgetMs) {
       try {
         // Phase 1: Query expansion — discover candidates BM25+vector missed
-        const expanded = await store.expandQuery(prompt, DEFAULT_QUERY_MODEL);
+        const expanded = await store.expandQuery(retrievalQuery, DEFAULT_QUERY_MODEL);
         if (expanded.length > 0) {
           const seen = new Set(results.map(r => r.filepath));
           for (const eq of expanded.slice(0, 3)) {
@@ -253,7 +287,7 @@ export async function contextSurfacing(
     !FILTERED_PATHS.some(p => r.displayPath.includes(p))
   );
 
-  if (results.length === 0) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
+  if (results.length === 0) { logEmptyTurn(store, input, prompt); return makeEmptyOutput("context-surfacing"); }
 
   // Filter out snoozed documents
   const now = new Date();
@@ -269,7 +303,7 @@ export async function contextSurfacing(
     return true;
   });
 
-  if (results.length === 0) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
+  if (results.length === 0) { logEmptyTurn(store, input, prompt); return makeEmptyOutput("context-surfacing"); }
 
   // Deduplicate by filepath (keep best score per path)
   const deduped = new Map<string, SearchResult>();
@@ -311,7 +345,7 @@ export async function contextSurfacing(
       : 0;
 
     // Activation floor: if even the best result is too weak, bail entirely
-    if (bestScore < profile.activationFloor) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
+    if (bestScore < profile.activationFloor) { logEmptyTurn(store, input, prompt); return makeEmptyOutput("context-surfacing"); }
 
     const adaptiveMin = Math.max(bestScore * profile.minScoreRatio, profile.absoluteFloor);
     scored = allScored.filter(r => r.compositeScore >= adaptiveMin);
@@ -320,7 +354,7 @@ export async function contextSurfacing(
     scored = allScored.filter(r => r.compositeScore >= minScore);
   }
 
-  if (scored.length === 0) { logEmptyTurn(store, input); return makeEmptyOutput("context-surfacing"); }
+  if (scored.length === 0) { logEmptyTurn(store, input, prompt); return makeEmptyOutput("context-surfacing"); }
 
   // Spreading activation (E11): boost results co-activated with top HOT results
   if (scored.length > 3) {
@@ -369,7 +403,7 @@ export async function contextSurfacing(
   const { context, paths, tokens } = buildContext(scored, prompt, factsBudget);
 
   if (!context) {
-    logEmptyTurn(store, input);
+    logEmptyTurn(store, input, prompt);
     return makeEmptyOutput("context-surfacing");
   }
 
@@ -377,8 +411,10 @@ export async function contextSurfacing(
   if (input.sessionId) {
     const turnIndex = (input as any)._turnIndex ?? 0;
 
-    // Log the injection — returns usage_id for recall event linkage
-    const usageId = logInjection(store, input.sessionId, "context-surfacing", paths, tokens, turnIndex);
+    // Log the injection — returns usage_id for recall event linkage.
+    // Ext 6b: persist the raw prompt as query_text so future turns in
+    // the same session can reconstitute a multi-turn retrieval query.
+    const usageId = logInjection(store, input.sessionId, "context-surfacing", paths, tokens, turnIndex, prompt);
 
     // Record recall events ONLY for docs that made it into the injected context
     // (post-budget). Docs trimmed by token budget were never seen by the model.
@@ -469,12 +505,21 @@ export async function contextSurfacing(
  * Log an empty context_usage row for a skipped turn.
  * Keeps turn_index aligned with transcript turns so per-turn recall
  * attribution doesn't drift when some prompts are gated.
+ *
+ * Ext 6b: `queryText` is optional. Callers that gated BEFORE the
+ * retrieval stage (slash commands, heartbeat dedupe, too-short prompts,
+ * `shouldSkipRetrieval`) pass nothing — those turns are not meaningful
+ * user questions and their raw text is not worth persisting for future
+ * multi-turn lookback. Callers that gated AFTER retrieval (empty result
+ * set, threshold filter, budget) pass the prompt so a follow-up turn
+ * can still reuse the intent even though the current turn surfaced
+ * nothing.
  */
-function logEmptyTurn(store: Store, input: HookInput): void {
+function logEmptyTurn(store: Store, input: HookInput, queryText?: string): void {
   if (!input.sessionId) return;
   try {
     const turnIndex = (input as any)._turnIndex ?? 0;
-    logInjection(store, input.sessionId, "context-surfacing", [], 0, turnIndex);
+    logInjection(store, input.sessionId, "context-surfacing", [], 0, turnIndex, queryText);
   } catch { /* non-fatal */ }
 }
 
@@ -700,6 +745,105 @@ export function buildVaultContextInner(
   return lines.join("\n");
 }
 
+// =============================================================================
+// Ext 6b: Multi-turn prior-query lookback
+// =============================================================================
+
+/**
+ * Build the retrieval query from the current prompt plus up to `lookback`
+ * recent prior prompts from the same session within `maxAgeMinutes`.
+ *
+ * Returns the current prompt unchanged when:
+ *  - no `sessionId` (nothing to scope by)
+ *  - the `query_text` column is missing (pre-migration store)
+ *  - no prior rows within the window / all NULL
+ *  - any DB error (fail-open — never throws)
+ *
+ * The combined query format is
+ *   `<current>\n\n<newest prior>\n\n<older prior>...`
+ * truncated to `MULTI_TURN_MAX_CHARS` with **current content preserved
+ * first** — so even when older priors would push the current prompt
+ * past the char limit, the truncation drops the tail (older priors),
+ * not the head. This guarantees the retrieval query always contains the
+ * user's current question verbatim.
+ *
+ * Exported for direct unit testing.
+ */
+export function buildMultiTurnSurfacingQuery(
+  store: Store,
+  sessionId: string,
+  currentQuery: string,
+  lookback: number = MULTI_TURN_LOOKBACK,
+  maxAgeMinutes: number = MULTI_TURN_MAX_AGE_MINUTES,
+  maxChars: number = MULTI_TURN_MAX_CHARS,
+): string {
+  if (!sessionId || currentQuery.length === 0) return currentQuery;
+
+  let priors: string[] = [];
+  try {
+    // ISO 8601 cutoff computed in JS (same lesson as the v0.8.0
+    // countRecentContextUsages fix — datetime('now', ...) returns a
+    // space-separated string that sorts incorrectly against the
+    // T-separated ISO 8601 timestamps stored in context_usage).
+    const cutoff = new Date(Date.now() - maxAgeMinutes * 60 * 1000).toISOString();
+    // Self-match guard lives in SQL so a duplicate submit/retry cannot eat
+    // into the lookback budget. Turn 18 review found that filtering in
+    // application code with `LIMIT lookback + 1` under-fills when multiple
+    // prior rows carry the same text as the current prompt — the SELECT
+    // returned only `lookback + 1` rows and application-level skipping
+    // then dropped legitimate distinct priors along with the dupes.
+    // Pushing the inequality into WHERE means every returned row is a
+    // valid non-self prior and the LIMIT == lookback fits exactly.
+    const rows = store.db.prepare(
+      `SELECT query_text FROM context_usage
+        WHERE session_id = ?
+          AND hook_name = 'context-surfacing'
+          AND timestamp > ?
+          AND query_text IS NOT NULL
+          AND query_text != ''
+          AND query_text != ?
+        ORDER BY id DESC
+        LIMIT ?`,
+    ).all(sessionId, cutoff, currentQuery, lookback) as { query_text: string }[];
+
+    for (const row of rows) {
+      if (!row.query_text) continue;
+      priors.push(row.query_text);
+    }
+  } catch {
+    // query_text column may be missing on a pre-migration store, or
+    // the DB might be in a corrupted state — fall back to current-only.
+    return currentQuery;
+  }
+
+  if (priors.length === 0) return currentQuery;
+
+  // Assemble newest-first: current first, then newest prior, then older.
+  // The SQL already ordered rows DESC by id, so `priors[0]` is the newest.
+  const segments = [currentQuery, ...priors];
+  const combined = segments.join("\n\n");
+
+  if (combined.length <= maxChars) return combined;
+
+  // Over budget. Current query ALWAYS wins — include the full current
+  // prompt first, then add priors newest-first until the budget runs out.
+  // If the current prompt alone is already over budget, return it
+  // truncated (same as pre-v0.8.1 behavior — MAX_QUERY_LENGTH is
+  // enforced earlier in the handler so this branch is rare).
+  if (currentQuery.length >= maxChars) return currentQuery.slice(0, maxChars);
+
+  const parts: string[] = [currentQuery];
+  let used = currentQuery.length;
+  const separator = "\n\n";
+  for (const prior of priors) {
+    const cost = separator.length + prior.length;
+    if (used + cost > maxChars) break;
+    parts.push(prior);
+    used += cost;
+  }
+  return parts.join(separator);
+}
+
 /**
  * Check if the agent should be nudged to use lifecycle tools.
  * Returns true if N+ context-surfacing invocations have occurred since the

package/src/hooks.ts

@@ -379,6 +379,12 @@ export function smartTruncate(text: string, maxChars: number = 300): string {
 
 /**
  * Log a context injection to the usage tracking table.
+ *
+ * `queryText` (v0.8.1 Ext 6b) is the raw prompt for this turn. Persisted
+ * only when the caller passes it — logEmptyTurn-style skip paths omit it
+ * so gated turns (slash commands, heartbeats, noise) cannot leak raw
+ * prompt text into `context_usage.query_text`. Pre-migration stores
+ * transparently drop the column via `insertUsageFn`'s feature-detect.
  */
 export function logInjection(
   store: Store,
@@ -386,7 +392,8 @@ export function logInjection(
   hookName: string,
   injectedPaths: string[],
   estimatedTokens: number,
-  turnIndex?: number
+  turnIndex?: number,
+  queryText?: string
 ): number {
   try {
     const usageId = store.insertUsage({
@@ -397,6 +404,7 @@ export function logInjection(
       estimatedTokens,
       wasReferenced: 0,
       turnIndex,
+      queryText,
     });
 
     // Record co-activation for all injected paths (E3)

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

@@ -496,17 +496,36 @@ function initializeDatabase(db: Database): void {
       injected_paths TEXT NOT NULL DEFAULT '[]',
       estimated_tokens INTEGER NOT NULL DEFAULT 0,
       was_referenced INTEGER NOT NULL DEFAULT 0,
-      turn_index INTEGER NOT NULL DEFAULT 0
+      turn_index INTEGER NOT NULL DEFAULT 0,
+      query_text TEXT
     )
   `);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_context_usage_session ON context_usage(session_id)`);
 
   // Migration: add turn_index to existing context_usage
-  const cuCols = db.prepare("PRAGMA table_info(context_usage)").all() as { name: string }[];
+  let cuCols = db.prepare("PRAGMA table_info(context_usage)").all() as { name: string }[];
   if (!cuCols.some(c => c.name === "turn_index")) {
     try { db.exec(`ALTER TABLE context_usage ADD COLUMN turn_index INTEGER NOT NULL DEFAULT 0`); } catch { /* exists */ }
+    cuCols = db.prepare("PRAGMA table_info(context_usage)").all() as { name: string }[];
   }
 
+  // v0.8.1 Ext 6b: add nullable query_text column to existing context_usage
+  // so multi-turn lookback can persist the raw prompt alongside turn_index.
+  // The column is nullable and defaults to NULL — pre-migration rows are
+  // treated as "no prior query" by buildMultiTurnSurfacingQuery, preserving
+  // the current-prompt-only fallback for any session that predates v0.8.1.
+  if (!cuCols.some(c => c.name === "query_text")) {
+    try { db.exec(`ALTER TABLE context_usage ADD COLUMN query_text TEXT`); } catch { /* exists */ }
+  }
+  // Cache the column presence for insertUsageFn so it can build the INSERT
+  // statement without running PRAGMA table_info on every write path.
+  contextUsageHasQueryTextCache.set(
+    db,
+    db.prepare("PRAGMA table_info(context_usage)")
+      .all()
+      .some((c) => (c as { name: string }).name === "query_text"),
+  );
+
   // Hook prompt dedupe: suppress duplicate/heartbeat prompts to reduce GPU churn.
   db.exec(`
     CREATE TABLE IF NOT EXISTS hook_dedupe (
@@ -895,6 +914,12 @@ function initializeDatabase(db: Database): void {
 // Per-database dimension cache (WeakMap keyed by db object — no collisions for in-memory DBs)
 const vecTableDimsCache = new WeakMap<Database, number>();
 
+// v0.8.1 Ext 6b: per-database cache for the query_text column presence on
+// context_usage. Set once at migration time so insertUsageFn can pick the
+// correct INSERT shape without running PRAGMA on every write. Falls back
+// to `false` (safe — equivalent to pre-migration behavior) when absent.
+const contextUsageHasQueryTextCache = new WeakMap<Database, boolean>();
+
 function ensureVecTableInternal(db: Database, dimensions: number): void {
   if (vecTableDimsCache.get(db) === dimensions) return;
 
@@ -1722,6 +1747,13 @@ export type UsageRecord = {
   estimatedTokens: number;
   wasReferenced: number;
   turnIndex?: number;
+  /**
+   * v0.8.1 Ext 6b: raw user prompt for this turn. Written when the caller
+   * wants the row to be usable for multi-turn lookback retrieval. Persisted
+   * via `insertUsageFn` only when the `query_text` column is present on
+   * `context_usage` (pre-migration stores degrade to "no prior query").
+   */
+  queryText?: string;
 };
 
 export type UsageRow = {
@@ -3939,10 +3971,33 @@ function getRecentSessionsFn(db: Database, limit: number): SessionRecord[] {
 // =============================================================================
 
 function insertUsageFn(db: Database, usage: UsageRecord): number {
-  db.prepare(`
-    INSERT INTO context_usage (session_id, timestamp, hook_name, injected_paths, estimated_tokens, was_referenced, turn_index)
-    VALUES (?, ?, ?, ?, ?, ?, ?)
-  `).run(usage.sessionId, usage.timestamp, usage.hookName, JSON.stringify(usage.injectedPaths), usage.estimatedTokens, usage.wasReferenced, usage.turnIndex ?? 0);
+  // v0.8.1 Ext 6b: write query_text when the column is present AND the
+  // caller provided one. The column presence is cached at migration time
+  // in contextUsageHasQueryTextCache — missing entries default to false
+  // so ad-hoc DBs constructed outside createStore() degrade gracefully
+  // to the pre-v0.8.1 INSERT shape.
+  const hasQueryText = contextUsageHasQueryTextCache.get(db) ?? false;
+  if (hasQueryText) {
+    db.prepare(`
+      INSERT INTO context_usage
+        (session_id, timestamp, hook_name, injected_paths, estimated_tokens, was_referenced, turn_index, query_text)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      usage.sessionId,
+      usage.timestamp,
+      usage.hookName,
+      JSON.stringify(usage.injectedPaths),
+      usage.estimatedTokens,
+      usage.wasReferenced,
+      usage.turnIndex ?? 0,
+      usage.queryText ?? null,
+    );
+  } else {
+    db.prepare(`
+      INSERT INTO context_usage (session_id, timestamp, hook_name, injected_paths, estimated_tokens, was_referenced, turn_index)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(usage.sessionId, usage.timestamp, usage.hookName, JSON.stringify(usage.injectedPaths), usage.estimatedTokens, usage.wasReferenced, usage.turnIndex ?? 0);
+  }
   // Return the rowid of the just-inserted row for recall event linkage
   const row = db.prepare("SELECT last_insert_rowid() as id").get() as { id: number };
   return row.id;