clawmem 0.8.5 → 0.10.0

package/src/clawmem.ts

@@ -64,6 +64,12 @@ import { precompactExtract } from "./hooks/precompact-extract.ts";
 import { postcompactInject } from "./hooks/postcompact-inject.ts";
 import { pretoolInject } from "./hooks/pretool-inject.ts";
 import { curatorNudge } from "./hooks/curator-nudge.ts";
+import {
+  readSessionFocus,
+  writeSessionFocus,
+  clearSessionFocus,
+  focusFilePath,
+} from "./session-focus.ts";
 
 enableProductionMode();
 
@@ -1298,8 +1304,28 @@ function cmdPath() {
   console.log(getDefaultDbPath());
 }
 
+/**
+ * Read a single OpenClaw config key via `openclaw config get <key>`. Returns
+ * the trimmed string value, or undefined when the key is unset / the CLI is
+ * unavailable / the key is missing. Callers should treat undefined as
+ * "no opinion" rather than "definitely unset".
+ */
+function readOpenClawConfigValue(key: string): string | undefined {
+  try {
+    const r = Bun.spawnSync(["openclaw", "config", "get", key], { stdout: "pipe", stderr: "pipe" });
+    if (r.exitCode !== 0) return undefined;
+    const out = new TextDecoder().decode(r.stdout).trim();
+    if (!out) return undefined;
+    // `openclaw config get` may print JSON ("clawmem"\n) or raw (clawmem). Strip quotes.
+    return out.replace(/^"(.*)"$/, "$1");
+  } catch {
+    return undefined;
+  }
+}
+
 async function cmdSetupOpenClaw(args: string[]) {
   const remove = args.includes("--remove");
+  const linkMode = args.includes("--link");
   const pluginDir = pathResolve(import.meta.dir, "openclaw");
   const extensionsDir = pathResolve(process.env.HOME || "~", ".openclaw", "extensions");
   const linkPath = pathResolve(extensionsDir, "clawmem");
@@ -1333,10 +1359,21 @@ async function cmdSetupOpenClaw(args: string[]) {
     }
 
     if (hasOpenClawCli) {
-      Bun.spawnSync(["openclaw", "config", "set", "plugins.slots.contextEngine", "legacy"], { stdout: "inherit", stderr: "inherit" });
-      console.log(`${c.green}Reset context engine slot to legacy${c.reset}`);
+      // Reset the memory slot if ClawMem owned it (post-§14.3-migration installs).
+      const memSlot = readOpenClawConfigValue("plugins.slots.memory");
+      if (memSlot === "clawmem") {
+        Bun.spawnSync(["openclaw", "config", "unset", "plugins.slots.memory"], { stdout: "inherit", stderr: "inherit" });
+        console.log(`${c.green}Cleared memory slot (was clawmem)${c.reset}`);
+      }
+      // Reset the legacy context-engine slot if any pre-§14.3-migration install
+      // left it pointing at clawmem.
+      const ceSlot = readOpenClawConfigValue("plugins.slots.contextEngine");
+      if (ceSlot === "clawmem") {
+        Bun.spawnSync(["openclaw", "config", "set", "plugins.slots.contextEngine", "legacy"], { stdout: "inherit", stderr: "inherit" });
+        console.log(`${c.green}Reset context engine slot to legacy (was clawmem)${c.reset}`);
+      }
     } else if (removed) {
-      console.log(`${c.dim}openclaw CLI not found — manually run: openclaw config set plugins.slots.contextEngine legacy${c.reset}`);
+      console.log(`${c.dim}openclaw CLI not found — manually clear: openclaw config unset plugins.slots.memory && openclaw config set plugins.slots.contextEngine legacy${c.reset}`);
     }
     return;
   }
@@ -1348,42 +1385,86 @@ async function cmdSetupOpenClaw(args: string[]) {
   if (!existsSync(pathResolve(pluginDir, "openclaw.plugin.json"))) {
     die(`Plugin manifest not found at ${pluginDir}/openclaw.plugin.json`);
   }
+  if (!existsSync(pathResolve(pluginDir, "package.json"))) {
+    die(`Plugin package.json not found at ${pluginDir}/package.json — required for OpenClaw v2026.4.11+ discovery`);
+  }
 
   // Create extensions directory
   if (!existsSync(extensionsDir)) {
     mkdirSync(extensionsDir, { recursive: true });
   }
 
-  // Remove stale symlink/directory if present
+  // Remove any stale install (symlink or directory) before re-installing.
+  // OpenClaw v2026.4.11+ discovery (discoverInDirectory in ids-*.js) uses
+  // readdirSync({ withFileTypes: true }) where symlinks report
+  // isDirectory() === false and get silently skipped, so copy mode is the
+  // default. The --link flag keeps symlink behavior for older OpenClaw
+  // versions or local development workflows where editing the live source
+  // should take effect without re-running setup.
   try {
     const { lstatSync, unlinkSync, rmSync } = await import("fs");
     const stat = lstatSync(linkPath);
     if (stat.isSymbolicLink()) {
-      const { readlinkSync } = await import("fs");
-      const target = readlinkSync(linkPath);
-      if (target === pluginDir) {
-        console.log(`${c.dim}Symlink already correct at ${linkPath}${c.reset}`);
-      } else {
-        unlinkSync(linkPath);
-        console.log(`${c.dim}Replaced stale symlink (was → ${target})${c.reset}`);
-      }
+      unlinkSync(linkPath);
+      console.log(`${c.dim}Replaced stale symlink at ${linkPath}${c.reset}`);
     } else if (stat.isDirectory()) {
       rmSync(linkPath, { recursive: true });
       console.log(`${c.dim}Replaced existing directory at ${linkPath}${c.reset}`);
     } else {
-      // Regular file or other non-symlink, non-directory — conflict
       die(`${linkPath} exists but is not a symlink or directory. Remove it manually and re-run setup.`);
     }
   } catch (e: any) {
     if (e.code !== "ENOENT") throw e;
   }
 
-  // Create symlink
-  if (!existsSync(linkPath)) {
+  if (linkMode) {
     const { symlinkSync } = await import("fs");
     symlinkSync(pluginDir, linkPath);
+    console.log(`${c.green}Installed plugin: ${linkPath} → ${pluginDir} (symlink)${c.reset}`);
+    console.log(`${c.yellow}  Warning: symlink mode. OpenClaw v2026.4.11+ discovery skips${c.reset}`);
+    console.log(`${c.yellow}  symlinks silently. Re-run without --link on current releases.${c.reset}`);
+  } else {
+    const { cpSync } = await import("fs");
+    cpSync(pluginDir, linkPath, { recursive: true, dereference: true });
+    console.log(`${c.green}Installed plugin: ${linkPath} (copied from ${pluginDir})${c.reset}`);
+  }
+
+  // ----- §14.3 upgrade migration -----
+  // ClawMem v0.10.0 changed `kind: "context-engine"` to `kind: "memory"`.
+  // Existing installs with `plugins.slots.contextEngine = "clawmem"` will hit
+  // a hard runtime error after upgrading because OpenClaw's
+  // `resolveContextEngine()` throws on unknown engine ids. Detect and rewrite
+  // the stale config to "legacy" so OpenClaw's built-in LegacyContextEngine
+  // takes over compaction. Also detect any pre-existing `plugins.slots.memory`
+  // assignment so we don't clobber a user's choice during upgrade.
+  let migrationApplied = false;
+  if (hasOpenClawCli) {
+    const staleContextEngine = readOpenClawConfigValue("plugins.slots.contextEngine");
+    if (staleContextEngine === "clawmem") {
+      console.log();
+      console.log(`${c.bold}${c.cyan}Upgrade migration detected:${c.reset}`);
+      console.log(`  Found legacy ClawMem context-engine slot config from v0.9.x or earlier.`);
+      console.log(`  Rewriting plugins.slots.contextEngine: clawmem → legacy`);
+      console.log(`  ${c.dim}(ClawMem now registers as a memory plugin. OpenClaw's built-in${c.reset}`);
+      console.log(`  ${c.dim} LegacyContextEngine will handle compaction unless you install a${c.reset}`);
+      console.log(`  ${c.dim} third-party context-engine plugin like hermes-lcm.)${c.reset}`);
+      const migrate = Bun.spawnSync(
+        ["openclaw", "config", "set", "plugins.slots.contextEngine", "legacy"],
+        { stdout: "inherit", stderr: "inherit" },
+      );
+      if (migrate.exitCode === 0) {
+        migrationApplied = true;
+      } else {
+        console.log(`${c.yellow}  Warning: failed to rewrite stale config — please run manually:${c.reset}`);
+        console.log(`    ${c.cyan}openclaw config set plugins.slots.contextEngine legacy${c.reset}`);
+      }
+    }
+  } else {
+    console.log();
+    console.log(`${c.dim}Upgrade migration skipped — openclaw CLI not on PATH. If upgrading${c.reset}`);
+    console.log(`${c.dim}from v0.9.x or earlier, manually run:${c.reset}`);
+    console.log(`  ${c.cyan}openclaw config set plugins.slots.contextEngine legacy${c.reset}`);
   }
-  console.log(`${c.green}Installed plugin: ${linkPath} → ${pluginDir}${c.reset}`);
 
   // Version warning
   console.log();
@@ -1391,17 +1472,21 @@ async function cmdSetupOpenClaw(args: string[]) {
   console.log(`have a bug where plugins.slots.contextEngine is silently dropped`);
   console.log(`during config normalization (openclaw/openclaw#64192).`);
 
-  // Remaining steps — gateway must restart BEFORE setting the context engine slot,
-  // otherwise OpenClaw hasn't discovered the plugin yet and the slot assignment
-  // fails or is ignored (the exact bug reported in issue #5).
+  // Remaining steps. CLI discovery finds the plugin immediately because the
+  // plugin dir now ships a package.json with openclaw.extensions declared, so
+  // `openclaw plugins enable clawmem` can run before any gateway restart.
+  // The enable command switches the exclusive memory slot to clawmem and
+  // disables memory-core/memory-lancedb automatically. Then the gateway
+  // restart applies the new slot assignment.
   console.log();
   console.log(`${c.bold}Next steps:${c.reset}`);
   console.log();
-  console.log(`  1. Restart OpenClaw gateway to discover the plugin:`);
-  console.log(`     ${c.cyan}openclaw gateway restart${c.reset}`);
+  console.log(`  1. Enable ClawMem as the active memory plugin:`);
+  console.log(`     ${c.cyan}openclaw plugins enable clawmem${c.reset}`);
+  console.log(`     ${c.dim}(Switches plugins.slots.memory to clawmem and disables memory-core if active.)${c.reset}`);
   console.log();
-  console.log(`  2. Set ClawMem as the active context engine (after restart):`);
-  console.log(`     ${c.cyan}openclaw config set plugins.slots.contextEngine clawmem${c.reset}`);
+  console.log(`  2. Restart the gateway to apply:`);
+  console.log(`     ${c.cyan}openclaw gateway restart${c.reset}`);
   console.log();
   console.log(`  3. Configure GPU endpoints (if not using defaults):`);
   console.log(`     ${c.cyan}openclaw config set plugins.entries.clawmem.config.gpuEmbed http://YOUR_GPU:8088${c.reset}`);
@@ -1411,7 +1496,24 @@ async function cmdSetupOpenClaw(args: string[]) {
   console.log(`  4. Start the REST API (for agent tools):`);
   console.log(`     ${c.cyan}clawmem serve &${c.reset}`);
   console.log();
+  console.log(`${c.bold}Important: keep dreaming disabled${c.reset}`);
+  console.log(`  ClawMem runs its own consolidation workers (CLAWMEM_ENABLE_CONSOLIDATION`);
+  console.log(`  light lane and CLAWMEM_HEAVY_LANE heavy lane). Keep ${c.cyan}dreaming.enabled = false${c.reset}`);
+  console.log(`  in OpenClaw's memory config to avoid auto-loading the bundled memory-core`);
+  console.log(`  dreaming engine alongside ClawMem (#65411 coexistence rule).`);
+  console.log();
+  console.log(`${c.bold}Compaction:${c.reset} OpenClaw's built-in LegacyContextEngine handles compaction`);
+  console.log(`by default. Install a third-party context-engine plugin (hermes-lcm, etc.)`);
+  console.log(`if you want a different compaction strategy. ClawMem injects pre-emptive`);
+  console.log(`precompact state via ${c.cyan}before_prompt_build${c.reset} when token usage approaches the`);
+  console.log(`compaction threshold.`);
+  console.log();
   console.log(`${c.dim}ClawMem will work alongside Claude Code hooks — both modes share the same vault.${c.reset}`);
+
+  if (migrationApplied) {
+    console.log();
+    console.log(`${c.green}✓ Upgrade migration applied — restart OpenClaw to pick up the new plugin kind.${c.reset}`);
+  }
 }
 
 function findClawmemBinary(): string {
@@ -1729,6 +1831,37 @@ async function cmdDoctor() {
     // Skip
   }
 
+  // 8. OpenClaw plugin slot config (§14.3 upgrade migration check)
+  try {
+    const stale = readOpenClawConfigValue("plugins.slots.contextEngine");
+    if (stale === "clawmem") {
+      console.log(
+        `${c.red}✗${c.reset} OpenClaw config: stale ${c.cyan}plugins.slots.contextEngine = "clawmem"${c.reset}`,
+      );
+      console.log(
+        `   ${c.dim}ClawMem v0.10.0 is now a memory plugin. Run ${c.cyan}clawmem setup openclaw${c.dim} to migrate,${c.reset}`,
+      );
+      console.log(
+        `   ${c.dim}or manually: ${c.cyan}openclaw config set plugins.slots.contextEngine legacy${c.reset}`,
+      );
+      issues++;
+    } else if (stale && stale !== "legacy") {
+      console.log(
+        `${c.green}✓${c.reset} OpenClaw context-engine slot: ${c.cyan}${stale}${c.reset} (third-party LCM)`,
+      );
+    }
+    const memSlot = readOpenClawConfigValue("plugins.slots.memory");
+    if (memSlot === "clawmem") {
+      console.log(`${c.green}✓${c.reset} OpenClaw memory slot: ${c.cyan}clawmem${c.reset}`);
+    } else if (memSlot) {
+      console.log(
+        `${c.dim}-${c.reset} OpenClaw memory slot: ${c.cyan}${memSlot}${c.reset} (ClawMem hooks will not fire under this agent)`,
+      );
+    }
+  } catch {
+    // openclaw CLI unavailable — skip silently
+  }
+
   console.log();
   if (issues > 0) {
     console.log(`${c.yellow}${issues} issue(s) found.${c.reset}`);
@@ -1906,6 +2039,91 @@ async function cmdProfile(args: string[]) {
   }
 }
 
+// §11.4 (v0.9.0): session-scoped focus topic — read/write/clear the
+// per-session focus file at ~/.cache/clawmem/sessions/<session_id>.focus.
+// The file is the primary signal read by context-surfacing for topic
+// boosting; the CLAWMEM_SESSION_FOCUS env var is a debug-only override
+// that does NOT provide per-session scoping on multi-session hosts.
+async function cmdFocus(args: string[]) {
+  const subCmd = args[0];
+
+  function resolveSessionId(rest: string[]): string {
+    const sidIdx = rest.indexOf("--session-id");
+    if (sidIdx >= 0 && rest[sidIdx + 1]) return rest[sidIdx + 1]!;
+    const envSid = (
+      process.env.CLAUDE_SESSION_ID ||
+      process.env.CLAWMEM_SESSION_ID ||
+      ""
+    ).trim();
+    if (envSid) return envSid;
+    die(
+      "No session id. Pass --session-id <id>, or set CLAUDE_SESSION_ID " +
+        "(Claude Code exposes this) or CLAWMEM_SESSION_ID env var before " +
+        "invoking this command."
+    );
+  }
+
+  function stripSessionIdArg(rest: string[]): string[] {
+    const sidIdx = rest.indexOf("--session-id");
+    if (sidIdx < 0) return rest;
+    return [...rest.slice(0, sidIdx), ...rest.slice(sidIdx + 2)];
+  }
+
+  switch (subCmd) {
+    case "set": {
+      const rest = args.slice(1);
+      const sessionId = resolveSessionId(rest);
+      const positional = stripSessionIdArg(rest);
+      const topic = positional.join(" ").trim();
+      if (!topic) {
+        die("Usage: clawmem focus set <topic> [--session-id <id>]");
+      }
+      try {
+        writeSessionFocus(sessionId, topic);
+      } catch (err: any) {
+        die(`Failed to set focus: ${err?.message ?? err}`);
+      }
+      console.log(
+        `${c.green}Focus set${c.reset} for session ${c.cyan}${sessionId}${c.reset}: ${topic}`
+      );
+      console.log(`${c.dim}File: ${focusFilePath(sessionId)}${c.reset}`);
+      break;
+    }
+    case "show": {
+      const rest = args.slice(1);
+      const sessionId = resolveSessionId(rest);
+      const topic = readSessionFocus(sessionId);
+      if (topic) {
+        console.log(
+          `${c.green}Focus${c.reset} for session ${c.cyan}${sessionId}${c.reset}: ${topic}`
+        );
+        console.log(`${c.dim}File: ${focusFilePath(sessionId)}${c.reset}`);
+      } else {
+        console.log(
+          `${c.yellow}No focus${c.reset} set for session ${c.cyan}${sessionId}${c.reset}.`
+        );
+        console.log(
+          `${c.dim}Expected file: ${focusFilePath(sessionId)}${c.reset}`
+        );
+      }
+      break;
+    }
+    case "clear": {
+      const rest = args.slice(1);
+      const sessionId = resolveSessionId(rest);
+      clearSessionFocus(sessionId);
+      console.log(
+        `${c.green}Focus cleared${c.reset} for session ${c.cyan}${sessionId}${c.reset}.`
+      );
+      break;
+    }
+    default:
+      die(
+        "Usage: clawmem focus <set|show|clear> [<topic>] [--session-id <id>]"
+      );
+  }
+}
+
 // =============================================================================
 // Main dispatch
 // =============================================================================
@@ -1994,6 +2212,9 @@ async function main() {
       case "profile":
         await cmdProfile(subArgs);
         break;
+      case "focus":
+        await cmdFocus(subArgs);
+        break;
       case "update-context":
         await cmdUpdateContext();
         break;
@@ -2644,6 +2865,9 @@ ${c.bold}Memory:${c.reset}
   clawmem log [--last N]               Session history
   clawmem profile                      Show user profile
   clawmem profile rebuild              Force profile rebuild
+  clawmem focus set <topic> [--session-id ID]   Set per-session focus topic (steers context-surfacing)
+  clawmem focus show [--session-id ID]          Show current focus topic
+  clawmem focus clear [--session-id ID]         Clear focus topic
 
 ${c.bold}Hooks:${c.reset}
   clawmem hook <name>                  Run hook (stdin JSON)

package/src/config.ts

@@ -84,12 +84,23 @@ export interface ProfileConfig {
   deepEscalation: boolean;
   /** Max time (ms) allowed for the fast path before escalation is considered */
   escalationBudgetMs: number;
+  /**
+   * §11.1 (v0.9.0): sub-budget for the `<vault-facts>` KG injection block.
+   * Dedicated token allowance so `<vault-facts>` cannot steal budget from
+   * the existing `<facts>` / `<relationships>` blocks. `speed` profile is
+   * gated off (factsTokens=0 → stage skipped entirely). `balanced` / `deep`
+   * get 200 / 250 respectively. If the serialized facts would exceed this
+   * sub-budget, truncation happens at the triple boundary. If the total
+   * hook output would push past `tokenBudget + factsTokens`, the whole
+   * `<vault-facts>` block is dropped (established blocks take priority).
+   */
+  factsTokens: number;
 }
 
 export const PROFILES: Record<PerformanceProfile, ProfileConfig> = {
-  speed:    { tokenBudget: 400,  maxResults: 5,  useVector: false, vectorTimeout: 0,    minScore: 0.55, minScoreRatio: 0.65, absoluteFloor: 0.18, activationFloor: 0.24, thresholdMode: "adaptive", deepEscalation: false, escalationBudgetMs: 0 },
-  balanced: { tokenBudget: 800,  maxResults: 10, useVector: true,  vectorTimeout: 900,  minScore: 0.45, minScoreRatio: 0.55, absoluteFloor: 0.15, activationFloor: 0.20, thresholdMode: "adaptive", deepEscalation: false, escalationBudgetMs: 0 },
-  deep:     { tokenBudget: 1200, maxResults: 15, useVector: true,  vectorTimeout: 2000, minScore: 0.25, minScoreRatio: 0.45, absoluteFloor: 0.12, activationFloor: 0.16, thresholdMode: "adaptive", deepEscalation: true,  escalationBudgetMs: 4000 },
+  speed:    { tokenBudget: 400,  maxResults: 5,  useVector: false, vectorTimeout: 0,    minScore: 0.55, minScoreRatio: 0.65, absoluteFloor: 0.18, activationFloor: 0.24, thresholdMode: "adaptive", deepEscalation: false, escalationBudgetMs: 0,    factsTokens: 0   },
+  balanced: { tokenBudget: 800,  maxResults: 10, useVector: true,  vectorTimeout: 900,  minScore: 0.45, minScoreRatio: 0.55, absoluteFloor: 0.15, activationFloor: 0.20, thresholdMode: "adaptive", deepEscalation: false, escalationBudgetMs: 0,    factsTokens: 200 },
+  deep:     { tokenBudget: 1200, maxResults: 15, useVector: true,  vectorTimeout: 2000, minScore: 0.25, minScoreRatio: 0.45, absoluteFloor: 0.12, activationFloor: 0.16, thresholdMode: "adaptive", deepEscalation: true,  escalationBudgetMs: 4000, factsTokens: 250 },
 };
 
 export function getActiveProfile(): ProfileConfig {

package/src/hooks/context-surfacing.ts

@@ -31,6 +31,12 @@ import { sanitizeSnippet } from "../promptguard.ts";
 import { shouldSkipRetrieval, isRetrievedNoise } from "../retrieval-gate.ts";
 import { MAX_QUERY_LENGTH } from "../limits.ts";
 import { writeRecallEvents, hashQuery } from "../recall-buffer.ts";
+import { resolveSessionTopic, applyTopicBoost } from "../session-focus.ts";
+import {
+  extractPromptEntities,
+  buildVaultFactsBlock,
+  type VaultFactsTriple,
+} from "../vault-facts.ts";
 
 // =============================================================================
 // Config
@@ -143,6 +149,20 @@ export async function contextSurfacing(
   const tokenBudget = profile.tokenBudget;
   const startTime = Date.now();
 
+  // §11.4: Resolve session-scoped focus topic. Primary signal is the
+  // per-session focus file at ~/.cache/clawmem/sessions/<id>.focus
+  // (file > env var precedence via resolveSessionTopic). Env var
+  // CLAWMEM_SESSION_FOCUS is a debug-only override and does NOT
+  // provide per-session scoping on multi-session hosts. Used as
+  // (a) optional `intent` on expandQuery/rerank/extractSnippet call
+  // sites below, and (b) the driver for the post-composite topic
+  // boost stage. Fail-open: missing / unreadable / corrupt / empty /
+  // oversized focus file → undefined → every consumer no-ops.
+  const sessionTopic = resolveSessionTopic(
+    input.sessionId,
+    process.env.CLAWMEM_SESSION_FOCUS
+  );
+
   const isRecency = hasRecencyIntent(prompt);
   const minScore = isRecency ? MIN_COMPOSITE_SCORE_RECENCY : profile.minScore;
 
@@ -239,7 +259,7 @@ export async function contextSurfacing(
     if (elapsed < profile.escalationBudgetMs) {
       try {
         // Phase 1: Query expansion — discover candidates BM25+vector missed
-        const expanded = await store.expandQuery(retrievalQuery, DEFAULT_QUERY_MODEL);
+        const expanded = await store.expandQuery(retrievalQuery, DEFAULT_QUERY_MODEL, sessionTopic);
         if (expanded.length > 0) {
           const seen = new Set(results.map(r => r.filepath));
           for (const eq of expanded.slice(0, 3)) {
@@ -263,7 +283,7 @@ export async function contextSurfacing(
             file: r.filepath,
             text: (r.body || "").slice(0, 2000),
           }));
-          const reranked = await store.rerank(prompt, toRerank, DEFAULT_RERANK_MODEL);
+          const reranked = await store.rerank(prompt, toRerank, DEFAULT_RERANK_MODEL, sessionTopic);
           if (reranked.length > 0) {
             const rerankedMap = new Map(reranked.map(r => [r.file, r.score]));
             // Blend: 60% original score + 40% reranker score for stability
@@ -335,6 +355,15 @@ export async function contextSurfacing(
   // Apply composite scoring
   const allScored = applyCompositeScoring(enriched, prompt);
 
+  // §11.4: Session-scoped topic boost — post-composite, pre-threshold.
+  // Boosts docs whose title/path/body match all tokens of the declared
+  // session focus topic (1.4×); demotes non-matching docs (0.75×, floor
+  // 50%). Mutates compositeScore in place and re-sorts. Fail-open: no
+  // topic set → no-op (byte-identical pre-§11.4 output).
+  if (sessionTopic) {
+    applyTopicBoost(allScored, sessionTopic, { boostFactor: 1.4, demoteFactor: 0.75 });
+  }
+
   // Threshold filtering — adaptive (ratio-based) or absolute (legacy)
   let scored: typeof allScored;
   if (profile.thresholdMode === "adaptive") {
@@ -400,7 +429,7 @@ export async function contextSurfacing(
   // in afterward using whatever budget remains and are the first thing
   // truncated when the payload would overflow.
   const factsBudget = Math.max(0, tokenBudget - INSTRUCTION_TOKEN_COST);
-  const { context, paths, tokens } = buildContext(scored, prompt, factsBudget);
+  const { context, paths, tokens } = buildContext(scored, prompt, factsBudget, sessionTopic);
 
   if (!context) {
     logEmptyTurn(store, input, prompt);
@@ -489,9 +518,60 @@ export async function contextSurfacing(
   );
   const vaultInner = buildVaultContextInner(context, relationSnippets, relationBudget);
 
+  // §11.1 (v0.9.0): `<vault-facts>` KG injection.
+  //
+  // Stage ordering (frozen in BACKLOG.md §11.1): retrieval + rerank +
+  // scoring + topic boost (§11.4) + threshold + diversification → build
+  // <facts>/<relationships> → compute remaining facts-block budget →
+  // inject <vault-facts> if entities resolve AND budget allows.
+  //
+  // Prompt-only seeding (HARD CONSTRAINT): entity seeds come from the
+  // raw user prompt ONLY, never from `surfacedDocs[i].body`, snippets,
+  // or any retrieval-phase field. Without this, a topic-boosted
+  // off-topic doc (§11.4) could pollute the facts block with facts
+  // about entities that have nothing to do with the user's actual
+  // prompt.
+  //
+  // Profile-gated via `profile.factsTokens`: `speed` profile sets this
+  // to 0, which naturally disables the stage. `balanced`/`deep` get a
+  // dedicated sub-budget that cannot steal from <facts>/<relationships>.
+  //
+  // Fail-open: any DB error, empty entity set, empty triple set, or
+  // budget-too-small case returns the baseline `vaultInner` unchanged
+  // (byte-identical pre-§11.1 output).
+  let vaultInnerWithFacts = vaultInner;
+  if (profile.factsTokens > 0) {
+    try {
+      const entities = extractPromptEntities(prompt, store.db, "default");
+      if (entities.length > 0) {
+        const queryTriples = (entityId: string): VaultFactsTriple[] =>
+          store
+            .queryEntityTriples(entityId)
+            .map(t => ({
+              subject: t.subject,
+              predicate: t.predicate,
+              object: t.object,
+              validTo: t.validTo,
+              confidence: t.confidence,
+            }));
+        const factsBlock = buildVaultFactsBlock(
+          entities,
+          queryTriples,
+          profile.factsTokens,
+          { estimateTokens }
+        );
+        if (factsBlock) {
+          vaultInnerWithFacts = `${vaultInner}\n${factsBlock}`;
+        }
+      }
+    } catch {
+      /* fail-open: degraded vault behaves identically to pre-§11.1 */
+    }
+  }
+
   const parts: string[] = [];
   if (routingHint) parts.push(`<vault-routing>${routingHint}</vault-routing>`);
-  parts.push(`<vault-context>\n${vaultInner}\n</vault-context>`);
+  parts.push(`<vault-context>\n${vaultInnerWithFacts}\n</vault-context>`);
   if (nudge) parts.push(`<vault-nudge>${NUDGE_TEXT}</vault-nudge>`);
 
   return makeContextOutput("context-surfacing", parts.join("\n"));
@@ -552,7 +632,8 @@ function detectRoutingHint(prompt: string): string | null {
 function buildContext(
   scored: ScoredResult[],
   query: string,
-  budget: number = DEFAULT_TOKEN_BUDGET
+  budget: number = DEFAULT_TOKEN_BUDGET,
+  intent?: string
 ): { context: string; paths: string[]; tokens: number } {
   const lines: string[] = [];
   const paths: string[] = [];
@@ -579,7 +660,7 @@ function buildContext(
       if (sanitized === "[content filtered for security]") continue;
 
       const snippet = smartTruncate(
-        extractSnippet(sanitized, query, tier.snippetLen, r.chunkPos).snippet,
+        extractSnippet(sanitized, query, tier.snippetLen, r.chunkPos, intent).snippet,
         tier.snippetLen
       );
       entry = `**${safeTitle}**${typeTag}\n${safePath}\n${snippet}`;