clawmem 0.8.0 → 0.8.1

package/AGENTS.md

@@ -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

@@ -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,19 @@ 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.
+
 ## Architecture
 
 <p align="center">
@@ -1187,6 +1200,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

@@ -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. |

package/package.json

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

package/src/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/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;