clawmem 0.8.4 → 0.9.0

package/AGENTS.md

@@ -128,15 +128,15 @@ ln -sf ~/clawmem/bin/clawmem ~/.bun/bin/clawmem
 clawmem bootstrap ~/notes --name notes
 
 # Or step by step:
-./bin/clawmem init
-./bin/clawmem collection add ~/notes --name notes
-./bin/clawmem update --embed
-./bin/clawmem setup hooks
-./bin/clawmem setup mcp
+clawmem init
+clawmem collection add ~/notes --name notes
+clawmem update --embed
+clawmem setup hooks
+clawmem setup mcp
 
 # Verify
-./bin/clawmem doctor    # Full health check
-./bin/clawmem status    # Quick index status
+clawmem doctor    # Full health check
+clawmem status    # Quick index status
 ```
 
 ### Background Services (systemd user units)
@@ -206,18 +206,17 @@ systemctl --user status clawmem-watcher.service clawmem-embed.timer
 
 When using ClawMem with OpenClaw, choose one of two deployment options:
 
-### Option 1: ClawMem Exclusive (Recommended)
+**Active Memory coexistence:** ClawMem is fully compatible with OpenClaw's Active Memory plugin (v2026.4.10+). They search different backends (ClawMem vault vs dreaming/wiki) and inject into different prompt regions (user prompt vs system prompt). Both can run simultaneously — no configuration needed.
+
+**OpenClaw v2026.4.10+ recommended:** Fixes a config normalization bug where `plugins.slots.contextEngine` was silently dropped (#64192).
 
-ClawMem handles 100% of memory operations via hooks + MCP tools. Zero redundancy.
+### Option 1: ClawMem Exclusive (Recommended)
 
-**Benefits:**
-- No context window waste (avoids 10-15% duplicate injection)
-- Prevents OpenClaw native memory auto-initialization on updates
-- All memory in ClawMem's hybrid search + graph traversal system
+ClawMem handles 100% of structured memory. Disable native memory search (not Active Memory — that's separate and compatible):
 
 **Configuration:**
 ```bash
-# Disable OpenClaw's native memory
+# Disable OpenClaw's native memory search
 openclaw config set agents.defaults.memorySearch.extraPaths "[]"
 
 # Verify
@@ -235,7 +234,7 @@ ls ~/.openclaw/agents/main/memory/
 
 ### Option 2: Hybrid (ClawMem + Native)
 
-Run both ClawMem and OpenClaw's native memory for redundancy.
+Run both ClawMem and OpenClaw's native memory search for redundancy.
 
 **Configuration:**
 ```bash
@@ -243,9 +242,9 @@ openclaw config set agents.defaults.memorySearch.extraPaths '["~/documents", "~/
 ```
 
 **Tradeoffs:**
-- ✅ Redundant recall from two independent systems
-- ❌ 10-15% context window waste from duplicate facts
-- ❌ Two memory indices to maintain
+- Redundant recall from two independent systems
+- 10-15% context window waste from duplicate facts
+- Two memory indices to maintain
 
 **Recommendation:** Use Option 1 unless you have a specific need for redundant memory systems.
 
@@ -259,11 +258,11 @@ ClawMem hooks handle ~90% of retrieval automatically. Agent-initiated MCP calls
 
 | Hook | Trigger | Budget | Content |
 |------|---------|--------|---------|
-| `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. |
+| `context-surfacing` | UserPromptSubmit | profile-driven (default 800 + factsTokens sub-budget) | 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) → **session focus topic resolution** (v0.9.0 §11.4: reads per-session focus file at `~/.cache/clawmem/sessions/<id>.focus`, threaded as intent hint to `expandQuery` + `rerank` + `extractSnippet`) → 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) → composite scoring → **session focus topic boost** (v0.9.0 §11.4: 1.4× match / 0.75× demote floor 50%, NO-OP on zero matches to preserve baseline ordering) → adaptive threshold → memory type diversification (E10) → tiered injection (HOT/WARM/COLD snippets) → `<vault-context><instruction>…</instruction><facts>…</facts><relationships>…</relationships><vault-facts>…</vault-facts></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. **v0.9.0 §11.1:** `<vault-facts>` KG injection block appends raw SPO triple lines from entities seeded by the prompt via three-path prompt-only extraction — canonical IDs + proper nouns + longer-first n-grams — with a dedicated `factsTokens` sub-budget per profile (speed=0 disables the stage, balanced=200, deep=250), cross-entity triple dedup, and truncate-at-triple-boundary budget discipline; fail-open on every error path) + optional `<vault-routing>` hint. Budget, max results, vector timeout, min score, and facts sub-budget 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. |
-| `decision-extractor` | Stop | — | LLM extracts observations → `_clawmem/agent/observations/`, infers causal links, detects contradictions, extracts SPO triples from decision/preference/milestone/problem facts. Background consolidation worker synthesizes deductive observations from related facts (Phase 3, every ~15 min). |
+| `decision-extractor` | Stop | — | LLM extracts observations → `_clawmem/agent/observations/`, infers causal links, detects contradictions, persists observer-emitted SPO triples via `ensureEntityCanonical` (canonical `vault:type:slug` IDs shared with A-MEM) using the tight predicate vocabulary (adopted, migrated_to, deployed_to, runs_on, replaced, depends_on, integrates_with, uses, prefers, avoids, caused_by, resolved_by, owned_by). Eligible observation types: decision/preference/milestone/problem/discovery/feature. Background consolidation worker synthesizes deductive observations from related facts (Phase 3, every ~15 min). |
 | `handoff-generator` | Stop | — | LLM summarizes session → `_clawmem/agent/handoffs/` |
 | `feedback-loop` | Stop | — | tracks referenced notes → boosts confidence, records usage relations + co-activations between co-referenced docs, tracks utility signals (surfaced vs referenced ratio for lifecycle automation), per-turn recall attribution (marks which surfaced docs were cited in which turn) |
 
@@ -713,6 +712,18 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
                                 # Uses Jaccard similarity within same collection
 ```
 
+**Session focus topic (v0.9.0 §11.4):** Per-session topic biasing for context-surfacing. Writes a focus file at `~/.cache/clawmem/sessions/<session_id>.focus` that steers query expansion, reranking, snippet extraction, and post-composite-score topic boost (1.4× match / 0.75× demote, NO-OP on zero matches). Session-isolated — never writes to SQLite or lifecycle columns. The session ID is read from `--session-id <id>`, then `CLAUDE_SESSION_ID`, then `CLAWMEM_SESSION_ID`. When to use: user says "focus on authentication for this session" / "only surface X-related docs right now" / "let's work on Y this session." Clear the focus at the end of the subsession to return to baseline surfacing.
+
+```bash
+# Set a focus topic for the current session (multi-word OK)
+clawmem focus set "authentication flow"                       # uses CLAUDE_SESSION_ID / CLAWMEM_SESSION_ID env var
+clawmem focus set "authentication flow" --session-id abc123   # explicit
+
+# Show / clear
+clawmem focus show --session-id abc123
+clawmem focus clear --session-id abc123
+```
+
 ## Integration Notes
 
 - **Memory nudge (v0.2.0):** Every N prompts (default 15) without a lifecycle MCP tool call (`memory_pin`/`memory_forget`/`memory_snooze`), context-surfacing appends `<vault-nudge>` prompting proactive memory management. Counter resets on lifecycle tool use. Configure via `CLAWMEM_NUDGE_INTERVAL` (0 to disable).

package/CLAUDE.md

@@ -128,15 +128,15 @@ ln -sf ~/clawmem/bin/clawmem ~/.bun/bin/clawmem
 clawmem bootstrap ~/notes --name notes
 
 # Or step by step:
-./bin/clawmem init
-./bin/clawmem collection add ~/notes --name notes
-./bin/clawmem update --embed
-./bin/clawmem setup hooks
-./bin/clawmem setup mcp
+clawmem init
+clawmem collection add ~/notes --name notes
+clawmem update --embed
+clawmem setup hooks
+clawmem setup mcp
 
 # Verify
-./bin/clawmem doctor    # Full health check
-./bin/clawmem status    # Quick index status
+clawmem doctor    # Full health check
+clawmem status    # Quick index status
 ```
 
 ### Background Services (systemd user units)
@@ -258,11 +258,11 @@ ClawMem hooks handle ~90% of retrieval automatically. Agent-initiated MCP calls
 
 | Hook | Trigger | Budget | Content |
 |------|---------|--------|---------|
-| `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. |
+| `context-surfacing` | UserPromptSubmit | profile-driven (default 800 + factsTokens sub-budget) | 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) → **session focus topic resolution** (v0.9.0 §11.4: reads per-session focus file at `~/.cache/clawmem/sessions/<id>.focus`, threaded as intent hint to `expandQuery` + `rerank` + `extractSnippet`) → 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) → composite scoring → **session focus topic boost** (v0.9.0 §11.4: 1.4× match / 0.75× demote floor 50%, NO-OP on zero matches to preserve baseline ordering) → adaptive threshold → memory type diversification (E10) → tiered injection (HOT/WARM/COLD snippets) → `<vault-context><instruction>…</instruction><facts>…</facts><relationships>…</relationships><vault-facts>…</vault-facts></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. **v0.9.0 §11.1:** `<vault-facts>` KG injection block appends raw SPO triple lines from entities seeded by the prompt via three-path prompt-only extraction — canonical IDs + proper nouns + longer-first n-grams — with a dedicated `factsTokens` sub-budget per profile (speed=0 disables the stage, balanced=200, deep=250), cross-entity triple dedup, and truncate-at-triple-boundary budget discipline; fail-open on every error path) + optional `<vault-routing>` hint. Budget, max results, vector timeout, min score, and facts sub-budget 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. |
-| `decision-extractor` | Stop | — | LLM extracts observations → `_clawmem/agent/observations/`, infers causal links, detects contradictions, extracts SPO triples from decision/preference/milestone/problem facts. Background consolidation worker synthesizes deductive observations from related facts (Phase 3, every ~15 min). |
+| `decision-extractor` | Stop | — | LLM extracts observations → `_clawmem/agent/observations/`, infers causal links, detects contradictions, persists observer-emitted SPO triples via `ensureEntityCanonical` (canonical `vault:type:slug` IDs shared with A-MEM) using the tight predicate vocabulary (adopted, migrated_to, deployed_to, runs_on, replaced, depends_on, integrates_with, uses, prefers, avoids, caused_by, resolved_by, owned_by). Eligible observation types: decision/preference/milestone/problem/discovery/feature. Background consolidation worker synthesizes deductive observations from related facts (Phase 3, every ~15 min). |
 | `handoff-generator` | Stop | — | LLM summarizes session → `_clawmem/agent/handoffs/` |
 | `feedback-loop` | Stop | — | tracks referenced notes → boosts confidence, records usage relations + co-activations between co-referenced docs, tracks utility signals (surfaced vs referenced ratio for lifecycle automation), per-turn recall attribution (marks which surfaced docs were cited in which turn) |
 
@@ -712,6 +712,18 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
                                 # Uses Jaccard similarity within same collection
 ```
 
+**Session focus topic (v0.9.0 §11.4):** Per-session topic biasing for context-surfacing. Writes a focus file at `~/.cache/clawmem/sessions/<session_id>.focus` that steers query expansion, reranking, snippet extraction, and post-composite-score topic boost (1.4× match / 0.75× demote, NO-OP on zero matches). Session-isolated — never writes to SQLite or lifecycle columns. The session ID is read from `--session-id <id>`, then `CLAUDE_SESSION_ID`, then `CLAWMEM_SESSION_ID`. When to use: user says "focus on authentication for this session" / "only surface X-related docs right now" / "let's work on Y this session." Clear the focus at the end of the subsession to return to baseline surfacing.
+
+```bash
+# Set a focus topic for the current session (multi-word OK)
+clawmem focus set "authentication flow"                       # uses CLAUDE_SESSION_ID / CLAWMEM_SESSION_ID env var
+clawmem focus set "authentication flow" --session-id abc123   # explicit
+
+# Show / clear
+clawmem focus show --session-id abc123
+clawmem focus clear --session-id abc123
+```
+
 ## Integration Notes
 
 - **Memory nudge (v0.2.0):** Every N prompts (default 15) without a lifecycle MCP tool call (`memory_pin`/`memory_forget`/`memory_snooze`), context-surfacing appends `<vault-nudge>` prompting proactive memory management. Counter resets on lifecycle tool use. Configure via `CLAWMEM_NUDGE_INTERVAL` (0 to disable).

package/README.md

@@ -31,6 +31,8 @@ ClawMem turns your markdown notes, project docs, and research dumps into persist
 - **Guards against cross-entity merges** during consolidation — name-aware dual-threshold merge safety compares entity anchors before merging similar observations, preventing "Alice decided X" from merging into "Bob decided X" (v0.7.1)
 - **Prevents context bleed in derived insights** — the Phase 3 deductive synthesis pipeline validates every draft against an anti-contamination wrapper (deterministic entity contamination check + LLM validator + dedupe) before writing cross-session deductive observations (v0.7.1)
 - **Frames surfaced facts as background knowledge** — `context-surfacing` wraps injected content in `<instruction>` + `<facts>` + `<relationships>` blocks, telling the model to treat facts as already-known and exposing memory-graph edges between surfaced docs directly in-prompt (v0.7.1)
+- **Injects knowledge-graph facts as structured triples** — when the user's prompt mentions entities already known to the vault, `context-surfacing` resolves them via a three-path prompt-only extractor (canonical IDs, proper nouns, lowercased n-grams), queries the SPO graph for current-state triples, and appends a `<vault-facts>` block of raw `subject predicate object` lines to `<vault-context>` — off for `speed`, 200 tokens on `balanced`, 250 on `deep`, token-truncated at the triple boundary (v0.9.0)
+- **Session-scoped focus topic boost** — `clawmem focus set "<topic>" --session-id <id>` writes a per-session focus file that steers query expansion, reranking, chunk selection, snippet extraction, and post-composite-score topic boosting (1.4× match / 0.75× demote) for that session only — session-isolated, fail-open, never writes to SQLite or lifecycle columns (v0.9.0)
 - **Scores document quality** using structure, keywords, and metadata richness signals
 - **Boosts co-accessed documents** — notes frequently surfaced together get retrieval reinforcement
 - **Decomposes complex queries** into typed retrieval clauses (BM25/vector/graph) for multi-topic questions
@@ -717,7 +719,7 @@ Registered by `clawmem setup mcp`. Available to any MCP-compatible client.
 |---|---|
 | `build_graphs` | Build temporal and/or semantic graphs from document corpus |
 | `find_causal_links` | Trace decision chains: "what led to X", "how we got from A to B". Follow up `intent_search` with this tool on a top result to walk the full causal chain. Traverses causes / caused_by / both up to N hops with depth-annotated reasoning. |
-| `kg_query` | Query the SPO knowledge graph: "what does X relate to?", "what was true about X when?". Returns temporal entity-relationship triples with validity windows. Uses entity resolution for lookup. |
+| `kg_query` | Query the SPO knowledge graph: "what does X relate to?", "what was true about X when?". Returns temporal entity-relationship triples with validity windows. Accepts entity name (resolved via `searchEntities`) or canonical ID in `vault:type:slug` form. Triples are populated by the decision-extractor hook from observer-emitted `<triples>` blocks. |
 | `memory_evolution_status` | Show how a document's A-MEM metadata evolved over time |
 | `timeline` | Show the temporal neighborhood around a document — what was created/modified before and after it. Progressive disclosure: search → timeline (context) → get (full content). Supports same-collection scoping and session correlation. |
 
@@ -1073,40 +1075,36 @@ Manual layers benefit from periodic re-indexing — a cron job running `clawmem
 ### Setup
 
 ```bash
-# Bootstrap workspace collection (use your agent's workspace path)
-./bin/clawmem bootstrap ~/workspace --name workspace
-
-# Bootstrap each project
-./bin/clawmem bootstrap ~/Projects/my-project --name my-project
+# Bootstrap a content directory (creates vault + indexes + embeds + installs hooks + MCP)
+clawmem bootstrap ~/notes --name notes
 
-# Enable auto-embed for real-time indexing
-# Edit ~/.config/clawmem/config.yaml → autoEmbed: true
+# Bootstrap each project you want indexed
+clawmem bootstrap ~/Projects/my-project --name my-project
 
-# Install watcher as systemd service
-./bin/clawmem install-service --enable
+# Install watcher + embed timer as systemd services
+clawmem install-service --enable
 ```
 
-#### OpenClaw-Specific
+#### OpenClaw-specific
 
 ```bash
-# OpenClaw uses ~/.openclaw/workspace/ as its workspace root
-./bin/clawmem bootstrap ~/.openclaw/workspace --name workspace
+# Install the ContextEngine plugin (auto-symlinks into ~/.openclaw/extensions/)
+clawmem setup openclaw
+# Then follow the printed next steps: restart gateway, set slot, configure GPU endpoints
 ```
 
-#### Hermes-Specific
+Index your content directories with `clawmem bootstrap` as above. The OpenClaw plugin shares the same vault as Claude Code hooks.
 
-```bash
-# Hermes uses ~/.hermes/ as its home directory
-./bin/clawmem bootstrap ~/.hermes --name hermes-home
+#### Hermes-specific
 
-# Install the memory provider plugin
-cp -r src/hermes /path/to/hermes-agent/plugins/memory/clawmem
+```bash
+# Install the memory provider plugin (symlink or copy)
+ln -s $(npm root -g)/clawmem/src/hermes /path/to/hermes-agent/plugins/memory/clawmem
 
-# Start clawmem serve (external mode)
+# Start the REST API (required for Hermes tool calls)
 clawmem serve --port 7438 &
 
-# Configure Hermes to use ClawMem
-# In your Hermes config.yaml:
+# Configure Hermes to use ClawMem (in your Hermes config.yaml):
 #   memory:
 #     provider: clawmem
 ```

package/SKILL.md

@@ -118,15 +118,15 @@ ln -sf ~/clawmem/bin/clawmem ~/.bun/bin/clawmem
 clawmem bootstrap ~/notes --name notes
 
 # Or step by step:
-./bin/clawmem init
-./bin/clawmem collection add ~/notes --name notes
-./bin/clawmem update --embed
-./bin/clawmem setup hooks
-./bin/clawmem setup mcp
+clawmem init
+clawmem collection add ~/notes --name notes
+clawmem update --embed
+clawmem setup hooks
+clawmem setup mcp
 
 # Verify
-./bin/clawmem doctor    # Full health check
-./bin/clawmem status    # Quick index status
+clawmem doctor    # Full health check
+clawmem status    # Quick index status
 ```
 
 ### Background Services (systemd user units)
@@ -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 -> **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. |
+| `context-surfacing` | UserPromptSubmit | profile-driven (default 800 + factsTokens sub-budget) | retrieval gate -> **multi-turn query** (v0.8.1: current + up to 2 recent same-session priors, discovery only) -> **session focus topic resolution** (v0.9.0 §11.4: reads `~/.cache/clawmem/sessions/<id>.focus`, threaded as intent hint to expansion/rerank/snippet) -> profile-driven hybrid search -> FTS supplement -> file-aware search (E13) -> snooze/noise filters -> spreading activation (E11) -> composite scoring -> **session focus topic boost** (v0.9.0 §11.4: 1.4x match / 0.75x demote, NO-OP on zero matches) -> adaptive threshold -> memory type diversification (E10) -> tiered injection (HOT/WARM/COLD) -> `<vault-context><instruction>...</instruction><facts>...</facts><relationships>...</relationships><vault-facts>...</vault-facts></vault-context>` (v0.7.1: instruction always prepended; relationships = memory-graph edges where BOTH endpoints are in the surfaced set, truncated first when over budget. **v0.9.0 §11.1:** `<vault-facts>` appends raw SPO triple lines when the prompt mentions known entities via three-path extraction (canonical-id regex + proper-noun validation + longer-first n-grams), dedicated `factsTokens` sub-budget per profile (speed=0, balanced=200, deep=250), cross-entity triple dedup, truncate-at-triple-boundary, fail-open on every error path) + optional `<vault-routing>` hint. Budget, max results, vector timeout, min score, facts sub-budget all driven by `CLAWMEM_PROFILE`. Raw prompt persisted to `context_usage.query_text` for future lookback — gated skip paths 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. |
@@ -294,7 +294,7 @@ Once escalated, route by query type:
 | `timeline` | Temporal neighborhood around a document — what was modified before/after. Progressive disclosure: search → timeline → get. Supports same-collection scoping and session correlation. |
 | `list_vaults` | Show configured vault names and paths. Empty in single-vault mode. |
 | `vault_sync` | Index markdown from a directory into a named vault. Restricted-path validation rejects sensitive directories. |
-| `kg_query` | Query SPO knowledge graph for entity relationships with temporal validity. Uses entity resolution. |
+| `kg_query` | Query SPO knowledge graph for entity relationships with temporal validity. Accepts entity name or canonical ID (`vault:type:slug`). Triples are populated by decision-extractor from observer-emitted `<triples>` blocks using a canonical predicate vocabulary. |
 | `diary_write` | Write diary entry. Use proactively in non-hooked environments. Do NOT use in Claude Code. |
 | `diary_read` | Read recent diary entries. Filter by agent name. |
 | `lifecycle_status` | Document lifecycle statistics: active, archived, forgotten, pinned, snoozed counts and policy summary. |
@@ -761,6 +761,19 @@ clawmem consolidate [--dry-run] # Find and archive duplicate low-confidence docu
                                 # Jaccard similarity within same collection
 ```
 
+### Session Focus Topic (v0.9.0 §11.4)
+
+Per-session topic biasing for context-surfacing. Writes a focus file at `~/.cache/clawmem/sessions/<session_id>.focus` that steers query expansion, reranking, snippet extraction, and post-composite-score topic boost (1.4x match / 0.75x demote, NO-OP on zero matches). Session-isolated — never writes to SQLite or lifecycle columns. Session ID resolved from `--session-id <id>` > `CLAUDE_SESSION_ID` env > `CLAWMEM_SESSION_ID` env.
+
+**When to use:** user says "focus on X for this session" / "only surface Y right now" / "let's work on Z." Clear at end of subsession to return to baseline.
+
+```bash
+clawmem focus set "authentication flow"                       # uses CLAUDE_SESSION_ID env
+clawmem focus set "authentication flow" --session-id abc123   # explicit session id
+clawmem focus show --session-id abc123
+clawmem focus clear --session-id abc123
+```
+
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmem",
-  "version": "0.8.4",
+  "version": "0.9.0",
   "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/amem.ts

@@ -649,11 +649,18 @@ export async function postIndexEnrich(
 }
 
 /**
- * Observation with document ID for causal inference
+ * Observation with document ID for causal inference and SPO triple extraction.
+ *
+ * Populated by the decision-extractor hook after an observation is successfully
+ * persisted. Consumed by:
+ *   - `inferCausalLinks` (A-MEM) — uses docId + facts
+ *   - `insertObservationTriples` (decision-extractor) — uses docId + obsType + triples
  */
 export interface ObservationWithDoc {
   docId: number;
   facts: string[];
+  obsType?: string;
+  triples?: Array<{ subject: string; predicate: string; object: string }>;
 }
 
 /**

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();
 
@@ -1906,6 +1912,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 +2085,9 @@ async function main() {
       case "profile":
         await cmdProfile(subArgs);
         break;
+      case "focus":
+        await cmdFocus(subArgs);
+        break;
       case "update-context":
         await cmdUpdateContext();
         break;
@@ -2644,6 +2738,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/entity.ts

@@ -354,6 +354,69 @@ export function resolveEntityCanonical(
 // Entity Storage + Mentions + Co-occurrences
 // =============================================================================
 
+/**
+ * Resolve the entity_type for a name via exact case-insensitive match.
+ *
+ * Returns the type only when EXACTLY ONE active entity in the given vault shares
+ * the name. Zero matches → null (caller should default to a safe type). Multiple
+ * matches (ambiguous across buckets, e.g. "Alice" as person AND "Alice" as project)
+ * → null so the caller falls back to a safe default instead of arbitrarily picking.
+ *
+ * Exact match only — no fuzzy matching — to avoid false inheritance on near-names.
+ */
+export function resolveEntityTypeExact(
+  db: Database,
+  name: string,
+  vault: string = 'default'
+): string | null {
+  const rows = db.prepare(`
+    SELECT DISTINCT entity_type FROM entity_nodes
+    WHERE LOWER(name) = LOWER(?) AND vault = ?
+  `).all(name, vault) as Array<{ entity_type: string }>;
+
+  if (rows.length !== 1) return null; // zero or ambiguous
+  return rows[0]!.entity_type;
+}
+
+/**
+ * Resolve-or-create a canonical entity without incrementing mention_count.
+ *
+ * Used by consumers that reference an entity but do NOT constitute a document
+ * mention (e.g. SPO triple extraction). Semantically distinct from upsertEntity,
+ * which treats every call as a doc mention and inflates the count.
+ *
+ * Flow: resolveEntityCanonical (FTS5 + fuzzy + bucket match) → reuse if found,
+ * otherwise mint a new canonical `vault:type:slug` entity with mention_count = 0.
+ *
+ * Returns the entity_id.
+ */
+export function ensureEntityCanonical(
+  db: Database,
+  name: string,
+  type: string,
+  vault: string = 'default'
+): string {
+  const canonicalId = resolveEntityCanonical(db, name, type, vault);
+  if (canonicalId) return canonicalId;
+
+  const entityId = makeEntityId(name, type, vault);
+  db.prepare(`
+    INSERT OR IGNORE INTO entity_nodes (entity_id, entity_type, name, description, created_at, mention_count, last_seen, vault)
+    VALUES (?, ?, ?, NULL, datetime('now'), 0, datetime('now'), ?)
+  `).run(entityId, type, name, vault);
+
+  try {
+    db.prepare(`
+      INSERT OR IGNORE INTO entities_fts (entity_id, name, entity_type)
+      VALUES (?, ?, ?)
+    `).run(entityId, name.toLowerCase(), type);
+  } catch {
+    // FTS insert may fail if table doesn't exist yet — non-fatal
+  }
+
+  return entityId;
+}
+
 /**
  * Upsert an entity into entity_nodes and entities_fts.
  * Returns the entity_id (canonical or new).