clawmem 0.5.0 → 0.5.1

package/AGENTS.md

@@ -307,9 +307,15 @@ All other retrieval is handled by Tier 2 hooks. Do NOT call MCP tools speculativ
 4. Chain tracing → find_causal_links(docid, direction="both", depth=5)
    Traverses causal edges between _clawmem/agent/observations/ docs (from decision-extractor).
 
-5. Memory debugging → memory_evolution_status(docid)
+5. Entity facts → kg_query(entity, as_of?, direction?)
+   Structured SPO triples with temporal validity. Different from intent_search:
+   - kg_query: "what does ClawMem relate to?" → returns structured facts (subject-predicate-object)
+   - intent_search: "why did we choose ClawMem?" → returns documents with causal reasoning
+   Use kg_query for entity lookup, intent_search for causal chains.
 
-6. Temporal context → timeline(docid, before=5, after=5, same_collection=false)
+6. Memory debugging → memory_evolution_status(docid)
+
+7. Temporal context → timeline(docid, before=5, after=5, same_collection=false)
    Shows what was created/modified before and after a document.
    Use after search to understand chronological neighborhood.
 ```
@@ -327,6 +333,9 @@ All other retrieval is handled by Tier 2 hooks. Do NOT call MCP tools speculativ
 - `timeline(docid, before=5, after=5, same_collection=false)` — temporal neighborhood around a document. 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 (default).
 - `vault_sync(vault, content_root, pattern?, collection_name?)` — index markdown from a directory into a named vault. Restricted-path validation rejects sensitive directories (`/etc/`, `/root/`, `.ssh`, `.env`, `credentials`, etc.).
+- `kg_query(entity, as_of?, direction?)` — query the SPO knowledge graph for an entity's relationships. Returns temporal triples with validity windows. USE THIS for "what does X relate to?", "what was true about X in January?". Uses entity resolution for lookup.
+- `diary_write(entry, topic?, agent?)` — write a diary entry. USE PROACTIVELY in non-hooked environments (Hermes, Gemini, plain MCP) for recording important events and decisions. Do NOT use in Claude Code (hooks handle this automatically).
+- `diary_read(last_n?, agent?)` — read recent diary entries.
 
 ### Multi-Vault
 
@@ -355,6 +364,8 @@ Pin, snooze, and forget are **manual MCP tools** — not automated. The agent sh
 - Do NOT forget memories to "clean up" — let confidence decay and contradiction detection handle it naturally.
 - Do NOT run `build_graphs` after every reindex — A-MEM creates per-doc links automatically. Only after bulk ingestion or when `intent_search` returns weak graph results.
 - Do NOT run `clawmem mine` autonomously — it is a bulk ingestion command (same category as `update`/`reindex`). Suggest it to the user when they mention old conversation exports, but let them run it. Bulk import has disk/embedding cost implications that need user consent.
+- Do NOT use `diary_write` in Claude Code — hooks (`decision-extractor`, `handoff-generator`) capture this automatically. Diary is for non-hooked environments only (Hermes, Gemini, plain MCP clients).
+- Do NOT use `kg_query` for causal "why" questions — use `intent_search` or `memory_retrieve`. `kg_query` returns structured entity facts (SPO triples), not reasoning chains.
 
 ## Tool Selection (one-liner)
 
@@ -564,6 +575,12 @@ Symptom: "Local model download blocked" error
   → llama-server endpoint unreachable while CLAWMEM_NO_LOCAL_MODELS=true.
   → Fix: Start the llama-server instance. Or set CLAWMEM_NO_LOCAL_MODELS=false for in-process fallback.
 
+Symptom: "[generate] Remote LLM in cooldown, falling back to in-process generation"
+  → Remote LLM server had a transport failure (ECONNREFUSED/ETIMEDOUT). ClawMem set a 60s cooldown
+    and is using local node-llama-cpp. Remote will be retried after cooldown expires.
+  → Not an error if you expect local fallback. If you want remote only: ensure llama-server is running,
+    or set CLAWMEM_NO_LOCAL_MODELS=true to get null instead of slow local inference.
+
 Symptom: Query expansion always fails / returns garbage
   → On CPU-only systems, in-process inference is significantly slower and less reliable. Systems with GPU acceleration (Metal/Vulkan) handle these models well in-process.
   → Fix: Run llama-server on a GPU. Even a low-end NVIDIA card handles 1.7B models.

package/CLAUDE.md

@@ -307,9 +307,15 @@ All other retrieval is handled by Tier 2 hooks. Do NOT call MCP tools speculativ
 4. Chain tracing → find_causal_links(docid, direction="both", depth=5)
    Traverses causal edges between _clawmem/agent/observations/ docs (from decision-extractor).
 
-5. Memory debugging → memory_evolution_status(docid)
+5. Entity facts → kg_query(entity, as_of?, direction?)
+   Structured SPO triples with temporal validity. Different from intent_search:
+   - kg_query: "what does ClawMem relate to?" → returns structured facts (subject-predicate-object)
+   - intent_search: "why did we choose ClawMem?" → returns documents with causal reasoning
+   Use kg_query for entity lookup, intent_search for causal chains.
 
-6. Temporal context → timeline(docid, before=5, after=5, same_collection=false)
+6. Memory debugging → memory_evolution_status(docid)
+
+7. Temporal context → timeline(docid, before=5, after=5, same_collection=false)
    Shows what was created/modified before and after a document.
    Use after search to understand chronological neighborhood.
 ```
@@ -327,6 +333,9 @@ All other retrieval is handled by Tier 2 hooks. Do NOT call MCP tools speculativ
 - `timeline(docid, before=5, after=5, same_collection=false)` — temporal neighborhood around a document. 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 (default).
 - `vault_sync(vault, content_root, pattern?, collection_name?)` — index markdown from a directory into a named vault. Restricted-path validation rejects sensitive directories (`/etc/`, `/root/`, `.ssh`, `.env`, `credentials`, etc.).
+- `kg_query(entity, as_of?, direction?)` — query the SPO knowledge graph for an entity's relationships. Returns temporal triples with validity windows. USE THIS for "what does X relate to?", "what was true about X in January?". Uses entity resolution for lookup.
+- `diary_write(entry, topic?, agent?)` — write a diary entry. USE PROACTIVELY in non-hooked environments (Hermes, Gemini, plain MCP) for recording important events and decisions. Do NOT use in Claude Code (hooks handle this automatically).
+- `diary_read(last_n?, agent?)` — read recent diary entries.
 
 ### Multi-Vault
 
@@ -355,6 +364,8 @@ Pin, snooze, and forget are **manual MCP tools** — not automated. The agent sh
 - Do NOT forget memories to "clean up" — let confidence decay and contradiction detection handle it naturally.
 - Do NOT run `build_graphs` after every reindex — A-MEM creates per-doc links automatically. Only after bulk ingestion or when `intent_search` returns weak graph results.
 - Do NOT run `clawmem mine` autonomously — it is a bulk ingestion command (same category as `update`/`reindex`). Suggest it to the user when they mention old conversation exports, but let them run it. Bulk import has disk/embedding cost implications that need user consent.
+- Do NOT use `diary_write` in Claude Code — hooks (`decision-extractor`, `handoff-generator`) capture this automatically. Diary is for non-hooked environments only (Hermes, Gemini, plain MCP clients).
+- Do NOT use `kg_query` for causal "why" questions — use `intent_search` or `memory_retrieve`. `kg_query` returns structured entity facts (SPO triples), not reasoning chains.
 
 ## Tool Selection (one-liner)
 
@@ -564,6 +575,12 @@ Symptom: "Local model download blocked" error
   → llama-server endpoint unreachable while CLAWMEM_NO_LOCAL_MODELS=true.
   → Fix: Start the llama-server instance. Or set CLAWMEM_NO_LOCAL_MODELS=false for in-process fallback.
 
+Symptom: "[generate] Remote LLM in cooldown, falling back to in-process generation"
+  → Remote LLM server had a transport failure (ECONNREFUSED/ETIMEDOUT). ClawMem set a 60s cooldown
+    and is using local node-llama-cpp. Remote will be retried after cooldown expires.
+  → Not an error if you expect local fallback. If you want remote only: ensure llama-server is running,
+    or set CLAWMEM_NO_LOCAL_MODELS=true to get null instead of slow local inference.
+
 Symptom: Query expansion always fails / returns garbage
   → On CPU-only systems, in-process inference is significantly slower and less reliable. Systems with GPU acceleration (Metal/Vulkan) handle these models well in-process.
   → Fix: Run llama-server on a GPU. Even a low-end NVIDIA card handles 1.7B models.

package/README.md

@@ -176,7 +176,7 @@ ClawMem integrates via hooks (`settings.json`) and an MCP stdio server. Hooks ha
 
 ```bash
 clawmem setup hooks    # Install lifecycle hooks (SessionStart, UserPromptSubmit, Stop, PreCompact)
-clawmem setup mcp      # Register MCP server in ~/.claude.json (28 tools)
+clawmem setup mcp      # Register MCP server in ~/.claude.json (31 tools)
 ```
 
 **Automatic (90%):** `context-surfacing` injects relevant memory on every prompt. `postcompact-inject` re-injects state after compaction. `decision-extractor`, `handoff-generator`, `feedback-loop` capture session state on stop.
@@ -203,7 +203,7 @@ Disable OpenClaw's native memory and `memory-lancedb` auto-recall/capture to avo
 openclaw config set agents.defaults.memorySearch.extraPaths "[]"
 ```
 
-**Alternative:** OpenClaw agents can also use ClawMem's MCP server directly (`clawmem setup mcp`), with or without hooks. This gives full access to all 28 MCP tools but bypasses OpenClaw's ContextEngine lifecycle, so you lose token budget awareness, native compaction orchestration, and the `afterTurn()` message pipeline. The ContextEngine plugin is recommended for new OpenClaw setups; MCP is available as an additional or standalone integration.
+**Alternative:** OpenClaw agents can also use ClawMem's MCP server directly (`clawmem setup mcp`), with or without hooks. This gives full access to all 31 MCP tools but bypasses OpenClaw's ContextEngine lifecycle, so you lose token budget awareness, native compaction orchestration, and the `afterTurn()` message pipeline. The ContextEngine plugin is recommended for new OpenClaw setups; MCP is available as an additional or standalone integration.
 
 #### Hermes Agent
 
@@ -310,9 +310,9 @@ ClawMem uses three `llama-server` (llama.cpp) instances for neural inference. Al
 | LLM | 8089 | [qmd-query-expansion-1.7B-q4_k_m](https://huggingface.co/tobil/qmd-query-expansion-1.7B-gguf) | ~2.2GB | Intent classification, query expansion, A-MEM |
 | Reranker | 8090 | [qwen3-reranker-0.6B-Q8_0](https://huggingface.co/ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF) | ~1.3GB | Cross-encoder reranking (query, intent_search) |
 
-The `bin/clawmem` wrapper defaults to `localhost:8088/8089/8090`. If a server is unreachable, ClawMem silently falls back to in-process inference via `node-llama-cpp` (auto-downloads the QMD native models on first use, uses Metal/Vulkan/CPU depending on hardware). With GPU acceleration this is fast; on CPU-only it is significantly slower. ClawMem always works either way, but **if you're running dedicated GPU servers, use [systemd services](docs/guides/systemd-services.md) to ensure they stay up** — otherwise a crashed server silently degrades without warning.
+The `bin/clawmem` wrapper defaults to `localhost:8088/8089/8090`. If a server is unreachable (transport error like ECONNREFUSED/ETIMEDOUT), ClawMem sets a 60-second cooldown and falls back to in-process inference via `node-llama-cpp` (auto-downloads the QMD native models on first use, uses Metal/Vulkan/CPU depending on hardware). HTTP errors (400/500) and user-cancelled requests do not trigger cooldown — the remote server is retried normally on the next call. With GPU acceleration the fallback is fast; on CPU-only it is significantly slower. ClawMem always works either way, but **if you're running dedicated GPU servers, use [systemd services](docs/guides/systemd-services.md) to ensure they stay up**.
 
-To prevent silent fallback and fail fast instead, set `CLAWMEM_NO_LOCAL_MODELS=true`.
+To prevent fallback and fail fast instead, set `CLAWMEM_NO_LOCAL_MODELS=true`.
 
 #### Remote GPU (optional)
 
@@ -473,7 +473,7 @@ llama-server -m Qwen3-Reranker-0.6B-Q8_0.gguf \
 
 ### MCP Server
 
-ClawMem exposes 28 MCP tools via the [Model Context Protocol](https://modelcontextprotocol.io) and an optional HTTP REST API. Any MCP-compatible client or HTTP client can use it.
+ClawMem exposes 31 MCP tools via the [Model Context Protocol](https://modelcontextprotocol.io) and an optional HTTP REST API. Any MCP-compatible client or HTTP client can use it.
 
 **Claude Code (automatic):**
 
@@ -678,7 +678,7 @@ clawmem doctor                                  Full health check
 clawmem status                                  Quick index status
 ```
 
-## MCP Tools (28)
+## MCP Tools (31)
 
 Registered by `clawmem setup mcp`. Available to any MCP-compatible client.
 
@@ -715,6 +715,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. |
 | `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. |
 
@@ -731,6 +732,13 @@ Registered by `clawmem setup mcp`. Available to any MCP-compatible client.
 | `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. |
 
+### Agent Diary
+
+| Tool | Description |
+|---|---|
+| `diary_write` | Write a diary entry. Use for recording important events, decisions, or observations in environments without hook support. Stored as searchable memories. |
+| `diary_read` | Read recent diary entries. Filter by agent name. |
+
 ### Memory Management & Lifecycle
 
 | Tool | Description |
@@ -1112,6 +1120,7 @@ Built on the shoulders of:
 - [Hermes Agent](https://github.com/NousResearch/hermes-agent) — MemoryProvider plugin integration, memory nudge system (periodic lifecycle tool prompting)
 - [Hindsight](https://github.com/vectorize-io/hindsight) — entity resolution, MPFP graph traversal, temporal extraction, 3-tier consolidation, observation invalidation, 4-way parallel retrieval
 - [MAGMA](https://arxiv.org/abs/2501.13956) — multi-graph memory agent
+- [MemPalace](https://github.com/milla-jovovich/mempalace) — conversation import patterns, broadened observation taxonomy (preference/milestone/problem), session-bootstrap synthesis
 - [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) — retrieval gate, length normalization, MMR diversity, access reinforcement algorithms
 - [OpenViking](https://github.com/volcengine/OpenViking) — query decomposition patterns, collection-scoped retrieval, transaction-safe indexing
 - [QMD](https://github.com/tobi/qmd) — search backend (BM25 + vectors + RRF + reranking)

package/SKILL.md

@@ -242,9 +242,15 @@ Once escalated, route by query type:
 4. Chain tracing -> find_causal_links(docid, direction="both", depth=5)
    Traverses causal edges between _clawmem/agent/observations/ docs.
 
-5. Memory debugging -> memory_evolution_status(docid)
+5. Entity facts -> kg_query(entity, as_of?, direction?)
+   Structured SPO triples with temporal validity. Different from intent_search:
+   - kg_query: "what does ClawMem relate to?" -> returns structured facts (subject-predicate-object)
+   - intent_search: "why did we choose ClawMem?" -> returns documents with causal reasoning
+   Use kg_query for entity lookup, intent_search for causal chains.
 
-6. Temporal context -> timeline(docid, before=5, after=5, same_collection=false)
+6. Memory debugging -> memory_evolution_status(docid)
+
+7. Temporal context -> timeline(docid, before=5, after=5, same_collection=false)
    Shows what was created/modified before and after a document.
    Use after search to understand chronological neighborhood.
 ```
@@ -277,6 +283,9 @@ 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. |
+| `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. |
 | `lifecycle_sweep` | Run lifecycle policies: archive stale docs. Defaults to dry_run (preview only). |
 | `lifecycle_restore` | Restore auto-archived documents. Filter by query, collection, or all. Does NOT restore manually forgotten docs. |
@@ -567,6 +576,8 @@ When `decision-extractor` detects a new decision contradicting an old one, the o
 - Do NOT forget memories to "clean up" — let confidence decay and contradiction detection handle it.
 - Do NOT run `build_graphs` after every reindex — A-MEM creates per-doc links automatically.
 - Do NOT run `clawmem mine` autonomously — it is a bulk ingestion command. Suggest it to the user when they mention old conversation exports, but let them run it.
+- Do NOT use `diary_write` in Claude Code — hooks capture this automatically. Diary is for non-hooked environments only (Hermes, Gemini, plain MCP).
+- Do NOT use `kg_query` for causal "why" questions — use `intent_search` or `memory_retrieve`. `kg_query` returns structured entity facts (SPO triples), not reasoning chains.
 
 ---
 

package/package.json

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

@@ -1868,6 +1868,9 @@ async function main() {
       case "curate":
         await cmdCurate(subArgs);
         break;
+      case "diary":
+        await cmdDiary(subArgs);
+        break;
       case "help":
       case "--help":
       case "-h":
@@ -2207,6 +2210,99 @@ interface CuratorReport {
   actions: string[];
 }
 
+async function cmdDiary(args: string[]) {
+  const subCmd = args[0];
+  const subArgs = args.slice(1);
+
+  switch (subCmd) {
+    case "write": {
+      const { values, positionals } = parseArgs({
+        args: subArgs,
+        options: {
+          topic: { type: "string", short: "t", default: "general" },
+          agent: { type: "string", short: "a", default: "user" },
+        },
+        allowPositionals: true,
+      });
+
+      const entry = positionals.join(" ");
+      if (!entry) die("Usage: clawmem diary write <entry text> [-t topic] [-a agent-name]");
+
+      const s = getStore();
+      const now = new Date();
+      const dateStr = now.toISOString().slice(0, 10);
+      const timeStr = now.toISOString().slice(11, 19).replace(/:/g, "");
+      const ms = String(now.getMilliseconds()).padStart(3, "0");
+      const diaryPath = `diary/${dateStr}-${timeStr}${ms}-${values.topic}.md`;
+      const body = [
+        "---",
+        `title: "${entry.slice(0, 80).replace(/"/g, '\\"')}"`,
+        `content_type: note`,
+        `tags: [diary, ${values.topic}]`,
+        `domain: "${values.agent}"`,
+        "---",
+        "",
+        entry,
+      ].join("\n");
+
+      const result = s.saveMemory({
+        collection: "_clawmem",
+        path: diaryPath,
+        title: entry.slice(0, 80),
+        body,
+        contentType: "note",
+        confidence: 0.7,
+        semanticPayload: `${diaryPath}::${entry}`,
+      });
+
+      console.log(`${c.green}✓${c.reset} Diary entry saved (${result.action}, doc #${result.docId})`);
+      break;
+    }
+
+    case "read": {
+      const { values } = parseArgs({
+        args: subArgs,
+        options: {
+          last: { type: "string", short: "n", default: "10" },
+          agent: { type: "string", short: "a" },
+        },
+        allowPositionals: false,
+      });
+
+      const limit = parseInt(values.last || "10", 10);
+      const s = getStore();
+
+      const rows = s.db.prepare(`
+        SELECT d.id, d.path, d.title, d.modified_at as modifiedAt, d.domain,
+               c.doc as body
+        FROM documents d
+        JOIN content c ON c.hash = d.hash
+        WHERE d.active = 1 AND d.collection = '_clawmem' AND d.path LIKE 'diary/%'
+        ${values.agent ? "AND d.domain = ?" : ""}
+        ORDER BY d.modified_at DESC
+        LIMIT ?
+      `).all(...(values.agent ? [values.agent, limit] : [limit])) as any[];
+
+      if (rows.length === 0) {
+        console.log("No diary entries found.");
+        break;
+      }
+
+      console.log(`${c.bold}Diary${c.reset} (${rows.length} entries)\n`);
+      for (const row of rows) {
+        const agent = row.domain ? ` [${row.domain}]` : "";
+        console.log(`${c.dim}${row.modifiedAt.slice(0, 16)}${c.reset}${agent} ${row.title}`);
+      }
+      break;
+    }
+
+    default:
+      console.log(`Usage:
+  clawmem diary write <entry> [-t topic] [-a agent]   Write diary entry
+  clawmem diary read [-n limit] [-a agent]            Read recent entries`);
+  }
+}
+
 async function cmdCurate(_args: string[]) {
   const s = getStore();
   const report: CuratorReport = {
@@ -2422,6 +2518,8 @@ ${c.bold}Intelligence:${c.reset}
   clawmem reflect [days]               Cross-session pattern analysis
   clawmem consolidate [--dry-run]      Merge duplicate low-confidence docs
   clawmem curate                       Automated maintenance (health, sweep, dedup, hygiene)
+  clawmem diary write <entry> [-t topic]  Write a diary entry (for non-hooked environments)
+  clawmem diary read [-n N] [-a agent]    Read recent diary entries
 
 ${c.bold}Integration:${c.reset}
   clawmem mcp                          Start stdio MCP server

package/src/hooks/decision-extractor.ts

@@ -374,6 +374,32 @@ export async function decisionExtractor(
         console.log(`[decision-extractor] Error in causal inference:`, err);
       }
     }
+
+    // Extract SPO triples from observation facts (preference/decision types get priority)
+    for (const obs of observations) {
+      if (!obs.facts || obs.facts.length === 0) continue;
+      for (const fact of obs.facts) {
+        const triple = extractTripleFromFact(fact, obs.type);
+        if (triple) {
+          try {
+            store.db.prepare(
+              "INSERT OR IGNORE INTO entity_nodes (entity_id, name, entity_type, created_at) VALUES (?, ?, ?, ?)"
+            ).run(triple.subjectId, triple.subject, "auto", new Date().toISOString());
+            if (triple.objectId) {
+              store.db.prepare(
+                "INSERT OR IGNORE INTO entity_nodes (entity_id, name, entity_type, created_at) VALUES (?, ?, ?, ?)"
+              ).run(triple.objectId, triple.object, "auto", new Date().toISOString());
+            }
+            store.addTriple(triple.subjectId, triple.predicate, triple.objectId, triple.objectId ? null : triple.object, {
+              confidence: obs.type === "decision" || obs.type === "preference" ? 0.9 : 0.7,
+              sourceFact: fact,
+            });
+          } catch {
+            // Triple insertion errors are non-fatal
+          }
+        }
+      }
+    }
   }
 
   // Extract decisions (observer-first, regex fallback)
@@ -663,3 +689,69 @@ function formatObservation(obs: Observation, dateStr: string, sessionId: string)
 
   return lines.join("\n");
 }
+
+// =============================================================================
+// SPO Triple Extraction from Facts
+// =============================================================================
+
+type ExtractedTriple = {
+  subject: string;
+  subjectId: string;
+  predicate: string;
+  object: string;
+  objectId: string | null;
+};
+
+function toEntityId(name: string): string {
+  return name.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+}
+
+function extractTripleFromFact(fact: string, obsType: string): ExtractedTriple | null {
+  // Only extract from decision/preference/milestone/problem types — skip noisy bugfix/feature/change facts
+  if (!["decision", "preference", "milestone", "problem"].includes(obsType)) return null;
+
+  // Conservative verb patterns — only clear relational predicates
+  const verbPatterns = [
+    /^(.+?)\s+(chose|selected|switched to|migrated to|adopted)\s+(.+?)\.?$/i,
+    /^(.+?)\s+(deployed to|runs on|hosted on|installed on)\s+(.+?)\.?$/i,
+    /^(.+?)\s+(replaced|superseded|deprecated)\s+(.+?)\.?$/i,
+    /^(.+?)\s+(depends on|integrates with|connects to)\s+(.+?)\.?$/i,
+  ];
+
+  for (const pattern of verbPatterns) {
+    const match = fact.match(pattern);
+    if (match) {
+      const subject = match[1]!.trim();
+      const predicate = match[2]!.trim();
+      const object = match[3]!.trim();
+
+      // Reject subjects/objects that look like sentences rather than entity names
+      if (subject.length < 3 || object.length < 3 || subject.length > 60 || object.length > 60) continue;
+      if (subject.includes(",") || object.includes(",")) continue; // likely a clause, not an entity
+
+      return {
+        subject,
+        subjectId: toEntityId(subject),
+        predicate: predicate.toLowerCase().replace(/\s+/g, "_"),
+        object,
+        objectId: toEntityId(object),
+      };
+    }
+  }
+
+  // Preference facts only: "User prefers X" / "Prefers X"
+  if (obsType === "preference") {
+    const prefMatch = fact.match(/^(?:user\s+)?(?:prefers?|avoids?)\s+(.+?)\.?$/i);
+    if (prefMatch && prefMatch[1]!.trim().length > 2) {
+      return {
+        subject: "user",
+        subjectId: "user",
+        predicate: "prefers",
+        object: prefMatch[1]!.trim(),
+        objectId: null, // literal, not entity
+      };
+    }
+  }
+
+  return null;
+}

package/src/hooks/session-bootstrap.ts

@@ -78,13 +78,13 @@ export async function sessionBootstrap(
     }
   }
 
-  // 2. Recent decisions
-  const decisionSection = getRecentDecisions(store, DECISION_TOKEN_BUDGET);
-  if (decisionSection) {
-    const tokens = estimateTokens(decisionSection.text);
+  // 2. Current focus (recent preferences + active problems)
+  const focusSection = getCurrentFocus(store, DECISION_TOKEN_BUDGET);
+  if (focusSection) {
+    const tokens = estimateTokens(focusSection.text);
     if (totalTokens + tokens <= TOTAL_TOKEN_BUDGET) {
-      sections.push(decisionSection.text);
-      paths.push(...decisionSection.paths);
+      sections.push(focusSection.text);
+      paths.push(...focusSection.paths);
       totalTokens += tokens;
     }
   }
@@ -252,38 +252,90 @@ function extractSection(body: string, sectionName: string): string | null {
   return text.length > 10 ? `**${sectionName}:**\n${text}` : null;
 }
 
-function getRecentDecisions(
+function getCurrentFocus(
   store: Store,
   maxTokens: number
 ): { text: string; paths: string[] } | null {
-  const decisions = store.getDocumentsByType("decision", 5);
-  if (decisions.length === 0) return null;
-
   const cutoff = new Date();
   cutoff.setDate(cutoff.getDate() - DECISION_LOOKBACK_DAYS);
   const cutoffStr = cutoff.toISOString();
 
-  // Filter to recent decisions
-  const recent = decisions.filter(d => d.modifiedAt >= cutoffStr);
-  if (recent.length === 0) return null;
+  // Gather recent decisions, preferences, and active problems
+  const decisions = store.getDocumentsByType("decision", 10);
+  const preferences = store.getDocumentsByType("preference", 5);
+  const problems = store.getDocumentsByType("problem", 5);
+
+  // Rank by: pinned first, then recency, then access_count
+  const now = Date.now();
+  const rankDoc = (d: any) => {
+    const pinBoost = d.pinned ? 1000 : 0;
+    const daysSince = (now - new Date(d.modifiedAt).getTime()) / 86400000;
+    const recencyScore = Math.max(0, 100 - daysSince * 5); // 0-100, loses 5 per day
+    const accessScore = (d.accessCount ?? 0) * 2;
+    return pinBoost + recencyScore + accessScore;
+  };
+
+  const recentDecisions = decisions
+    .filter(d => d.modifiedAt >= cutoffStr)
+    .sort((a, b) => rankDoc(b) - rankDoc(a));
+
+  const activeProblems = problems
+    .filter(d => d.modifiedAt >= cutoffStr && (d.confidence ?? 0.5) > 0.2);
+
+  // Preferences are durable — no date filter, just rank
+  const rankedPrefs = [...preferences].sort((a, b) => rankDoc(b) - rankDoc(a));
+
+  if (recentDecisions.length === 0 && rankedPrefs.length === 0 && activeProblems.length === 0) {
+    return null;
+  }
 
   const maxChars = maxTokens * 4;
-  const lines: string[] = ["### Recent Decisions"];
+  const lines: string[] = ["### Current Focus"];
   const paths: string[] = [];
-  let charCount = 25; // header
-
-  for (const d of recent) {
-    if (charCount >= maxChars) break;
-    let body = store.getDocumentBody({ filepath: `${d.collection}/${d.path}`, displayPath: `${d.collection}/${d.path}` } as any);
-    if (body) body = sanitizeSnippet(body);
-    if (body === "[content filtered for security]") continue;
-    const snippet = body ? smartTruncate(body, 200) : d.title;
-    const entry = `- **${d.title}** (${d.modifiedAt.slice(0, 10)})\n  ${snippet}`;
-    const entryLen = entry.length;
-    if (charCount + entryLen > maxChars && lines.length > 1) break;
-    lines.push(entry);
-    paths.push(`${d.collection}/${d.path}`);
-    charCount += entryLen;
+  let charCount = 20;
+
+  // Active problems first (high priority)
+  if (activeProblems.length > 0) {
+    lines.push("**Active Problems:**");
+    charCount += 22;
+    for (const d of activeProblems) {
+      if (charCount >= maxChars) break;
+      const entry = `- ${d.title} (${d.modifiedAt.slice(0, 10)})`;
+      lines.push(entry);
+      paths.push(`${d.collection}/${d.path}`);
+      charCount += entry.length + 2;
+    }
+  }
+
+  // Recent decisions
+  if (recentDecisions.length > 0) {
+    lines.push("**Recent Decisions:**");
+    charCount += 24;
+    for (const d of recentDecisions) {
+      if (charCount >= maxChars) break;
+      let body = store.getDocumentBody({ filepath: `${d.collection}/${d.path}`, displayPath: `${d.collection}/${d.path}` } as any);
+      if (body) body = sanitizeSnippet(body);
+      if (body === "[content filtered for security]") continue;
+      const snippet = body ? smartTruncate(body, 200) : d.title;
+      const entry = `- **${d.title}** (${d.modifiedAt.slice(0, 10)})\n  ${snippet}`;
+      if (charCount + entry.length > maxChars && lines.length > 2) break;
+      lines.push(entry);
+      paths.push(`${d.collection}/${d.path}`);
+      charCount += entry.length;
+    }
+  }
+
+  // User preferences (compact — title only, they're durable context)
+  if (rankedPrefs.length > 0) {
+    lines.push("**Preferences:**");
+    charCount += 18;
+    for (const d of rankedPrefs) {
+      if (charCount >= maxChars) break;
+      const entry = `- ${d.title}`;
+      lines.push(entry);
+      paths.push(`${d.collection}/${d.path}`);
+      charCount += entry.length + 2;
+    }
   }
 
   return lines.length > 1 ? { text: lines.join("\n"), paths } : null;
@@ -299,12 +351,15 @@ function getStaleNotes(
 
   if (stale.length === 0) return null;
 
+  // Rank by confidence descending — higher confidence notes are more important to review
+  const ranked = [...stale].sort((a, b) => (b.confidence ?? 0.5) - (a.confidence ?? 0.5));
+
   const maxChars = maxTokens * 4;
   const lines: string[] = ["### Notes to Review"];
   const paths: string[] = [];
   let charCount = 25;
 
-  for (const d of stale.slice(0, 5)) {
+  for (const d of ranked.slice(0, 5)) {
     const entry = `- ${d.title} (${d.collection}/${d.path}) — last modified ${d.modifiedAt.slice(0, 10)}`;
     if (charCount + entry.length > maxChars && lines.length > 1) break;
     lines.push(entry);

package/src/llm.ts

@@ -290,6 +290,12 @@ export class LlamaCpp implements LLM {
   // Track disposal state to prevent double-dispose
   private disposed = false;
 
+  // Cooldown-based down-cache for remote services.
+  // Timestamps (ms since epoch) until which we skip remote and use local fallback.
+  // Resets after cooldown expires — one network hiccup doesn't permanently disable GPU.
+  private remoteEmbedDownUntil = 0;
+  private remoteLlmDownUntil = 0;
+  private static readonly REMOTE_COOLDOWN_MS = 60_000; // 60s cooldown on transport failure
 
   constructor(config: LlamaCppConfig = {}) {
     this.embedModelUri = config.embedModel || DEFAULT_EMBED_MODEL;
@@ -563,14 +569,19 @@ export class LlamaCpp implements LLM {
 
   async embed(text: string, options: EmbedOptions = {}): Promise<EmbeddingResult | null> {
     // Remote server or cloud API — preferred path
-    if (this.remoteEmbedUrl) {
+    if (this.remoteEmbedUrl && !this.isRemoteEmbedDown()) {
       const extraParams = this.getCloudEmbedParams(!!options.isQuery);
       const result = await this.embedRemote(text, extraParams);
       if (result) return result;
       // Cloud providers don't fall back — if API key is set, the user chose cloud
       if (this.isCloudEmbedding()) return null;
-      // Local server unreachable — fall through to in-process fallback
-      console.error("[embed] Remote server unreachable, falling back to in-process embedding");
+      // Transport failure already set cooldown in embedRemote — fall through
+    }
+
+    // Remote is in cooldown or was never configured — try local fallback
+    if (this.remoteEmbedUrl && this.isRemoteEmbedDown()) {
+      if (process.env.CLAWMEM_NO_LOCAL_MODELS === "true") return null;
+      console.error("[embed] Remote embed in cooldown, using in-process fallback");
     }
 
     // In-process fallback via node-llama-cpp (auto-downloads EmbeddingGemma on first use)
@@ -586,15 +597,20 @@ export class LlamaCpp implements LLM {
     if (texts.length === 0) return [];
 
     // Remote server or cloud API
-    if (this.remoteEmbedUrl) {
+    if (this.remoteEmbedUrl && !this.isRemoteEmbedDown()) {
       const extraParams = this.getCloudEmbedParams(false);
       const results = await this.embedRemoteBatch(texts, extraParams);
       // If we got at least one result, remote is working
       if (results.some(r => r !== null)) return results;
       // Cloud providers don't fall back
       if (this.isCloudEmbedding()) return results;
-      // Local server unreachable — fall through to in-process fallback
-      console.error("[embed] Remote server unreachable, falling back to in-process embedding");
+      // Transport failure already set cooldown in embedRemoteBatch — fall through
+    }
+
+    // Remote is in cooldown or was never configured — try local fallback
+    if (this.remoteEmbedUrl && this.isRemoteEmbedDown()) {
+      if (process.env.CLAWMEM_NO_LOCAL_MODELS === "true") return texts.map(() => null);
+      console.error("[embed] Remote embed in cooldown, using in-process fallback");
     }
 
     // In-process fallback via node-llama-cpp
@@ -645,6 +661,46 @@ export class LlamaCpp implements LLM {
     return text.slice(0, this.maxRemoteEmbedChars);
   }
 
+  // ---------- Remote failure classification ----------
+
+  /**
+   * Classify whether an error is a transport failure (server unreachable)
+   * vs an HTTP error (server received request but rejected it) or abort.
+   * Only transport failures should trigger the down-cache cooldown.
+   */
+  private isTransportError(error: unknown): boolean {
+    if (error instanceof TypeError && String(error.message).includes("fetch")) return true; // fetch network error
+    const code = (error as any)?.code || (error as any)?.cause?.code;
+    if (code === "ECONNREFUSED" || code === "ETIMEDOUT" || code === "ENOTFOUND" ||
+        code === "EHOSTUNREACH" || code === "ENETUNREACH" || code === "ECONNRESET" ||
+        code === "UND_ERR_CONNECT_TIMEOUT") return true;
+    const msg = String((error as any)?.message || "").toLowerCase();
+    if (msg.includes("econnrefused") || msg.includes("etimedout") || msg.includes("enotfound") ||
+        msg.includes("ehostunreach") || msg.includes("enetunreach")) return true;
+    return false;
+  }
+
+  private isAbortError(error: unknown): boolean {
+    return (error instanceof DOMException && error.name === "AbortError") ||
+           (error as any)?.name === "AbortError";
+  }
+
+  private isRemoteLlmDown(): boolean {
+    return Date.now() < this.remoteLlmDownUntil;
+  }
+
+  private isRemoteEmbedDown(): boolean {
+    return Date.now() < this.remoteEmbedDownUntil;
+  }
+
+  private markRemoteLlmDown(): void {
+    this.remoteLlmDownUntil = Date.now() + LlamaCpp.REMOTE_COOLDOWN_MS;
+  }
+
+  private markRemoteEmbedDown(): void {
+    this.remoteEmbedDownUntil = Date.now() + LlamaCpp.REMOTE_COOLDOWN_MS;
+  }
+
   // ---------- Remote embedding (GPU server or cloud API via /v1/embeddings) ----------
 
   // Default: 6000 chars for EmbeddingGemma-300M (2048-token context).
@@ -712,6 +768,7 @@ export class LlamaCpp implements LLM {
   }
 
   private async embedRemote(text: string, extraParams: Record<string, unknown> = {}, retries = 5): Promise<EmbeddingResult | null> {
+    if (this.isRemoteEmbedDown()) return null;
     const input = this.truncateForEmbed(text);
     for (let attempt = 0; attempt < retries; attempt++) {
       try {
@@ -741,11 +798,16 @@ export class LlamaCpp implements LLM {
           model: data.model || this.remoteEmbedUrl!,
         };
       } catch (error) {
-        console.error("Remote embed error:", error);
+        if (this.isTransportError(error)) {
+          console.error("[embed] Remote embed server unreachable, cooldown 60s");
+          this.markRemoteEmbedDown();
+        } else {
+          console.error("[embed] Remote embed error:", error);
+        }
         return null;
       }
     }
-    console.error("Remote embed: max retries exceeded (rate limit)");
+    console.error("[embed] Remote embed: max retries exceeded (rate limit)");
     return null;
   }
 
@@ -753,6 +815,7 @@ export class LlamaCpp implements LLM {
   lastBatchTokens = 0;
 
   private async embedRemoteBatch(texts: string[], extraParams: Record<string, unknown> = {}, retries = 3): Promise<(EmbeddingResult | null)[]> {
+    if (this.isRemoteEmbedDown()) return texts.map(() => null);
     const truncated = texts.map(t => this.truncateForEmbed(t));
     for (let attempt = 0; attempt < retries; attempt++) {
       try {
@@ -787,11 +850,16 @@ export class LlamaCpp implements LLM {
         }
         return results;
       } catch (error) {
-        console.error("Remote batch embed error:", error);
+        if (this.isTransportError(error)) {
+          console.error("[embed] Remote batch embed server unreachable, cooldown 60s");
+          this.markRemoteEmbedDown();
+        } else {
+          console.error("[embed] Remote batch embed error:", error);
+        }
         return texts.map(() => null);
       }
     }
-    console.error("Remote batch embed: max retries exceeded (rate limit)");
+    console.error("[embed] Remote batch embed: max retries exceeded (rate limit)");
     return texts.map(() => null);
   }
 
@@ -800,8 +868,18 @@ export class LlamaCpp implements LLM {
     const temperature = options.temperature ?? 0;
 
     // Remote LLM server (GPU) — preferred path
-    if (this.remoteLlmUrl) {
-      return this.generateRemote(prompt, maxTokens, temperature, options.signal);
+    if (this.remoteLlmUrl && !this.isRemoteLlmDown()) {
+      const result = await this.generateRemote(prompt, maxTokens, temperature, options.signal);
+      if (result) return result;
+      // If remote failed but NOT transport error (HTTP 400/500, abort), don't fall through
+      if (!this.isRemoteLlmDown()) return null;
+      // Transport failure set cooldown — fall through to local
+    }
+
+    // Remote is in cooldown or was never configured — try local fallback
+    if (this.remoteLlmUrl && this.isRemoteLlmDown()) {
+      if (process.env.CLAWMEM_NO_LOCAL_MODELS === "true") return null;
+      console.error("[generate] Remote LLM in cooldown, falling back to in-process generation");
     }
 
     // Local fallback via node-llama-cpp (CPU)
@@ -840,6 +918,8 @@ export class LlamaCpp implements LLM {
     temperature: number,
     signal?: AbortSignal
   ): Promise<GenerateResult | null> {
+    // Re-check: concurrent call may have set cooldown while we were awaited
+    if (this.isRemoteLlmDown()) return null;
     try {
       const resp = await fetch(`${this.remoteLlmUrl}/v1/chat/completions`, {
         method: "POST",
@@ -854,7 +934,8 @@ export class LlamaCpp implements LLM {
       });
 
       if (!resp.ok) {
-        console.error(`[generate] Remote LLM error: ${resp.status} ${resp.statusText}`);
+        console.error(`[generate] Remote LLM HTTP ${resp.status}: ${resp.statusText}`);
+        // HTTP errors mean the server IS reachable — don't trigger down-cache
         return null;
       }
 
@@ -869,7 +950,16 @@ export class LlamaCpp implements LLM {
         done: true,
       };
     } catch (error) {
-      console.error("[generate] Remote LLM error:", error);
+      if (this.isAbortError(error)) {
+        // User/caller cancelled — don't cache as "down"
+        return null;
+      }
+      if (this.isTransportError(error)) {
+        console.error("[generate] Remote LLM server unreachable, cooldown 60s");
+        this.markRemoteLlmDown();
+      } else {
+        console.error("[generate] Remote LLM error:", error);
+      }
       return null;
     }
   }
@@ -939,8 +1029,22 @@ Output:`;
     const intent = options.intent;
 
     // Remote LLM path — no grammar constraint, parse output instead
-    if (this.remoteLlmUrl) {
-      return this.expandQueryRemote(query, includeLexical, context, intent);
+    if (this.remoteLlmUrl && !this.isRemoteLlmDown()) {
+      const result = await this.expandQueryRemote(query, includeLexical, context, intent);
+      // Check if transport failure set cooldown during this call
+      if (!this.isRemoteLlmDown()) return result;
+      // Transport failure — fall through to local grammar path
+    }
+
+    // Remote is in cooldown (pre-existing or just set) — fall through to local
+    if (this.remoteLlmUrl && this.isRemoteLlmDown()) {
+      if (process.env.CLAWMEM_NO_LOCAL_MODELS === "true") {
+        // Can't fall back — return passthrough
+        const fallback: Queryable[] = [{ type: 'vec', text: query }];
+        if (includeLexical) fallback.unshift({ type: 'lex', text: query });
+        return fallback;
+      }
+      console.error("[expandQuery] Remote LLM in cooldown, falling back to in-process grammar expansion");
     }
 
     const llama = await this.ensureLlama();

package/src/mcp.ts

@@ -1918,6 +1918,61 @@ This is the recommended entry point for ALL memory queries.`,
     }
   );
 
+  // ---------------------------------------------------------------------------
+  // Tool: kg_query (SPO Knowledge Graph)
+  // ---------------------------------------------------------------------------
+
+  server.registerTool(
+    "kg_query",
+    {
+      title: "Knowledge Graph Query",
+      description: "Query the knowledge graph for an entity's relationships. Returns structured facts with temporal validity (valid_from/valid_to). Use for 'what does X relate to?', 'what was true about X on date Y?', 'who/what is connected to X?'.",
+      inputSchema: {
+        entity: z.string().describe("Entity name or ID to query"),
+        as_of: z.string().optional().describe("Date filter (YYYY-MM-DD) — only facts valid at this date"),
+        direction: z.enum(["outgoing", "incoming", "both"]).optional().default("both").describe("Relationship direction"),
+        vault: z.string().optional().describe("Named vault (omit for default vault)"),
+      },
+    },
+    async ({ entity, as_of, direction, vault }) => {
+      const store = getStore(vault);
+
+      const entityResults = store.searchEntities(entity, 1);
+      const entityId = entityResults.length > 0
+        ? entityResults[0]!.entity_id
+        : entity.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_|_$/g, "");
+
+      const triples = store.queryEntityTriples(entityId, { asOf: as_of, direction });
+      const stats = store.getTripleStats();
+
+      if (triples.length === 0) {
+        return {
+          content: [{ type: "text", text: `No knowledge graph facts found for "${entity}". The KG has ${stats.totalTriples} total triples (${stats.currentFacts} current).` }],
+        };
+      }
+
+      const lines = [`Knowledge graph for "${entity}" (${triples.length} fact${triples.length === 1 ? '' : 's'}):\n`];
+
+      for (const t of triples) {
+        const validity = t.current ? "current" : `ended ${t.validTo}`;
+        const from = t.validFrom ? ` (since ${t.validFrom})` : "";
+        const conf = Math.round(t.confidence * 100);
+        lines.push(`[${t.direction}] ${t.subject} → ${t.predicate} → ${t.object}${from} [${validity}, ${conf}%]`);
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join('\n') }],
+        structuredContent: {
+          entity,
+          direction,
+          as_of: as_of ?? null,
+          facts: triples,
+          stats,
+        },
+      };
+    }
+  );
+
   // ---------------------------------------------------------------------------
   // Tool: memory_evolution_status (A-MEM)
   // ---------------------------------------------------------------------------
@@ -2407,6 +2462,99 @@ This is the recommended entry point for ALL memory queries.`,
     }
   );
 
+  // ---------------------------------------------------------------------------
+  // Tool: diary_write
+  // ---------------------------------------------------------------------------
+
+  server.registerTool(
+    "diary_write",
+    {
+      title: "Write Diary Entry",
+      description: "Write to the agent's diary. Use for recording important events, decisions, or observations in environments without hook support. Entries are stored as memories and are searchable.",
+      inputSchema: {
+        entry: z.string().describe("Diary entry text"),
+        topic: z.string().optional().default("general").describe("Topic tag (e.g., 'technical', 'user_facts', 'session')"),
+        agent: z.string().optional().default("agent").describe("Agent name writing the entry"),
+        vault: z.string().optional().describe("Named vault (omit for default vault)"),
+      },
+    },
+    async ({ entry, topic, agent, vault }) => {
+      const store = getStore(vault);
+      const now = new Date();
+      const dateStr = now.toISOString().slice(0, 10);
+      const timeStr = now.toISOString().slice(11, 19).replace(/:/g, "");
+      const ms = String(now.getMilliseconds()).padStart(3, "0");
+      const diaryPath = `diary/${dateStr}-${timeStr}${ms}-${topic}.md`;
+      const body = `---\ntitle: "${entry.slice(0, 80).replace(/"/g, '\\"')}"\ncontent_type: note\ntags: [diary, ${topic}]\ndomain: "${agent}"\n---\n\n${entry}`;
+
+      const result = store.saveMemory({
+        collection: "_clawmem",
+        path: diaryPath,
+        title: entry.slice(0, 80),
+        body,
+        contentType: "note",
+        confidence: 0.7,
+        semanticPayload: `${diaryPath}::${entry}`,
+      });
+
+      return {
+        content: [{ type: "text", text: `Diary entry saved (${result.action}, doc #${result.docId})` }],
+        structuredContent: { action: result.action, docId: result.docId, path: diaryPath },
+      };
+    }
+  );
+
+  // ---------------------------------------------------------------------------
+  // Tool: diary_read
+  // ---------------------------------------------------------------------------
+
+  server.registerTool(
+    "diary_read",
+    {
+      title: "Read Diary Entries",
+      description: "Read recent diary entries. Use to review past observations and events recorded by the agent.",
+      inputSchema: {
+        last_n: z.number().optional().default(10).describe("Number of recent entries to return"),
+        agent: z.string().optional().describe("Filter by agent name"),
+        vault: z.string().optional().describe("Named vault (omit for default vault)"),
+      },
+    },
+    async ({ last_n, agent, vault }) => {
+      const store = getStore(vault);
+      const params: any[] = [];
+      let agentFilter = "";
+      if (agent) {
+        agentFilter = "AND d.domain = ?";
+        params.push(agent);
+      }
+      params.push(last_n);
+
+      const rows = store.db.prepare(`
+        SELECT d.id, d.path, d.title, d.modified_at as modifiedAt, d.domain
+        FROM documents d
+        WHERE d.active = 1 AND d.collection = '_clawmem' AND d.path LIKE 'diary/%'
+        ${agentFilter}
+        ORDER BY d.modified_at DESC
+        LIMIT ?
+      `).all(...params) as any[];
+
+      if (rows.length === 0) {
+        return { content: [{ type: "text", text: "No diary entries found." }] };
+      }
+
+      const lines = [`Diary (${rows.length} entries):\n`];
+      for (const row of rows) {
+        const agentLabel = row.domain ? ` [${row.domain}]` : "";
+        lines.push(`${row.modifiedAt.slice(0, 16)}${agentLabel} ${row.title}`);
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join('\n') }],
+        structuredContent: { entries: rows },
+      };
+    }
+  );
+
   // ---------------------------------------------------------------------------
   // Connect
   // ---------------------------------------------------------------------------

package/src/store.ts

@@ -708,6 +708,31 @@ function initializeDatabase(db: Database): void {
   db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_cooccurrences_a ON entity_cooccurrences(entity_a)`);
   db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_cooccurrences_b ON entity_cooccurrences(entity_b)`);
 
+  // SPO knowledge graph: temporal entity-relationship triples
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS entity_triples (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      subject_entity_id TEXT NOT NULL,
+      predicate TEXT NOT NULL,
+      object_entity_id TEXT,
+      object_literal TEXT,
+      valid_from TEXT,
+      valid_to TEXT,
+      confidence REAL DEFAULT 1.0,
+      source_doc_id INTEGER,
+      source_fact TEXT,
+      created_at TEXT DEFAULT (datetime('now')),
+      FOREIGN KEY (subject_entity_id) REFERENCES entity_nodes(entity_id),
+      FOREIGN KEY (object_entity_id) REFERENCES entity_nodes(entity_id),
+      FOREIGN KEY (source_doc_id) REFERENCES documents(id)
+    )
+  `);
+
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_triples_subject ON entity_triples(subject_entity_id)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_triples_object ON entity_triples(object_entity_id)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_triples_predicate ON entity_triples(predicate)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_entity_triples_valid ON entity_triples(valid_from, valid_to)`);
+
   // Entity FTS5 for fuzzy name lookup
   db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(entity_id, name, entity_type)`);
 
@@ -904,6 +929,12 @@ export type Store = {
   searchEntities: (query: string, limit?: number) => { entity_id: string; name: string; type: string; mention_count: number; cooccurrence_count: number }[];
   getEntityGraphNeighbors: (seedDocIds: number[], limit?: number) => { docId: number; score: number; viaEntity: string }[];
 
+  // SPO knowledge graph
+  addTriple: (subjectEntityId: string, predicate: string, objectEntityId: string | null, objectLiteral: string | null, options?: { validFrom?: string; validTo?: string; confidence?: number; sourceDocId?: number; sourceFact?: string }) => number;
+  invalidateTriple: (subjectEntityId: string, predicate: string, objectEntityId: string | null, objectLiteral: string | null, endedDate?: string) => number;
+  queryEntityTriples: (entityId: string, options?: { asOf?: string; direction?: "outgoing" | "incoming" | "both" }) => { id: number; direction: string; subject: string; predicate: string; object: string; validFrom: string | null; validTo: string | null; confidence: number; current: boolean }[];
+  getTripleStats: () => { totalTriples: number; currentFacts: number; expiredFacts: number; predicateTypes: string[] };
+
   // Co-activation tracking
   recordCoActivation: (paths: string[]) => void;
   getCoActivated: (path: string, limit?: number) => { path: string; count: number }[];
@@ -1070,6 +1101,93 @@ export function createStore(dbPath?: string, opts?: { readonly?: boolean; busyTi
     searchEntities: (query: string, limit?: number) => searchEntities(db, query, limit),
     getEntityGraphNeighbors: (seedDocIds: number[], limit?: number) => getEntityGraphNeighbors(db, seedDocIds, limit),
 
+    // SPO knowledge graph
+    addTriple: (subjectEntityId: string, predicate: string, objectEntityId: string | null, objectLiteral: string | null, options?: { validFrom?: string; validTo?: string; confidence?: number; sourceDocId?: number; sourceFact?: string }) => {
+      const pred = predicate.toLowerCase().replace(/\s+/g, "_");
+      const now = new Date().toISOString();
+      const objClause = objectEntityId
+        ? "object_entity_id = ? AND object_literal IS NULL"
+        : "object_entity_id IS NULL AND object_literal = ?";
+      const objParam = objectEntityId ?? objectLiteral;
+      const existing = db.prepare(
+        `SELECT id FROM entity_triples WHERE subject_entity_id = ? AND predicate = ? AND ${objClause} AND valid_to IS NULL`
+      ).get(subjectEntityId, pred, objParam) as { id: number } | null;
+      if (existing) return existing.id;
+
+      const result = db.prepare(`
+        INSERT INTO entity_triples (subject_entity_id, predicate, object_entity_id, object_literal, valid_from, valid_to, confidence, source_doc_id, source_fact, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        subjectEntityId, pred, objectEntityId, objectLiteral,
+        options?.validFrom ?? null, options?.validTo ?? null,
+        options?.confidence ?? 1.0, options?.sourceDocId ?? null,
+        options?.sourceFact ?? null, now
+      );
+      return Number(result.lastInsertRowid);
+    },
+
+    invalidateTriple: (subjectEntityId: string, predicate: string, objectEntityId: string | null, objectLiteral: string | null, endedDate?: string) => {
+      const pred = predicate.toLowerCase().replace(/\s+/g, "_");
+      const ended = endedDate || new Date().toISOString().slice(0, 10);
+      const objClause = objectEntityId
+        ? "object_entity_id = ? AND object_literal IS NULL"
+        : "object_entity_id IS NULL AND object_literal = ?";
+      const objParam = objectEntityId ?? objectLiteral;
+      const result = db.prepare(
+        `UPDATE entity_triples SET valid_to = ? WHERE subject_entity_id = ? AND predicate = ? AND ${objClause} AND valid_to IS NULL`
+      ).run(ended, subjectEntityId, pred, objParam);
+      return result.changes;
+    },
+
+    queryEntityTriples: (entityId: string, options?: { asOf?: string; direction?: "outgoing" | "incoming" | "both" }) => {
+      const direction = options?.direction ?? "both";
+      const asOf = options?.asOf;
+      const results: { id: number; direction: string; subject: string; predicate: string; object: string; validFrom: string | null; validTo: string | null; confidence: number; current: boolean }[] = [];
+
+      if (direction === "outgoing" || direction === "both") {
+        let query = `SELECT t.id, t.predicate, t.object_entity_id, t.object_literal, t.valid_from, t.valid_to, t.confidence,
+                      COALESCE(s.name, t.subject_entity_id) as sub_name, COALESCE(o.name, t.object_literal, t.object_entity_id) as obj_name
+                     FROM entity_triples t
+                     LEFT JOIN entity_nodes s ON t.subject_entity_id = s.entity_id
+                     LEFT JOIN entity_nodes o ON t.object_entity_id = o.entity_id
+                     WHERE t.subject_entity_id = ?`;
+        const params: any[] = [entityId];
+        if (asOf) {
+          query += " AND (t.valid_from IS NULL OR t.valid_from <= ?) AND (t.valid_to IS NULL OR t.valid_to >= ?)";
+          params.push(asOf, asOf);
+        }
+        for (const row of db.prepare(query).all(...params) as any[]) {
+          results.push({ id: row.id, direction: "outgoing", subject: row.sub_name, predicate: row.predicate, object: row.obj_name, validFrom: row.valid_from, validTo: row.valid_to, confidence: row.confidence, current: row.valid_to === null });
+        }
+      }
+
+      if (direction === "incoming" || direction === "both") {
+        let query = `SELECT t.id, t.predicate, t.valid_from, t.valid_to, t.confidence,
+                      COALESCE(s.name, t.subject_entity_id) as sub_name, COALESCE(o.name, t.object_literal, t.object_entity_id) as obj_name
+                     FROM entity_triples t
+                     LEFT JOIN entity_nodes s ON t.subject_entity_id = s.entity_id
+                     LEFT JOIN entity_nodes o ON t.object_entity_id = o.entity_id
+                     WHERE t.object_entity_id = ?`;
+        const params: any[] = [entityId];
+        if (asOf) {
+          query += " AND (t.valid_from IS NULL OR t.valid_from <= ?) AND (t.valid_to IS NULL OR t.valid_to >= ?)";
+          params.push(asOf, asOf);
+        }
+        for (const row of db.prepare(query).all(...params) as any[]) {
+          results.push({ id: row.id, direction: "incoming", subject: row.sub_name, predicate: row.predicate, object: row.obj_name, validFrom: row.valid_from, validTo: row.valid_to, confidence: row.confidence, current: row.valid_to === null });
+        }
+      }
+
+      return results;
+    },
+
+    getTripleStats: () => {
+      const total = (db.prepare("SELECT COUNT(*) as n FROM entity_triples").get() as any).n;
+      const current = (db.prepare("SELECT COUNT(*) as n FROM entity_triples WHERE valid_to IS NULL").get() as any).n;
+      const predicates = db.prepare("SELECT DISTINCT predicate FROM entity_triples ORDER BY predicate").all().map((r: any) => r.predicate);
+      return { totalTriples: total, currentFacts: current, expiredFacts: total - current, predicateTypes: predicates };
+    },
+
     // Co-activation tracking
     recordCoActivation: (paths: string[]) => {
       if (paths.length < 2) return;
@@ -1333,6 +1451,7 @@ export type DocumentRow = {
   confidence: number;
   accessCount: number;
   bodyLength: number;
+  pinned: number;
 };
 
 // =============================================================================
@@ -3560,7 +3679,7 @@ function getDocumentsByTypeFn(db: Database, contentType: string, limit: number =
     SELECT d.id, d.collection, d.path, d.title, d.hash, d.modified_at as modifiedAt,
            d.domain, d.workstream, d.tags, d.content_type as contentType,
            d.review_by as reviewBy, d.confidence, d.access_count as accessCount,
-           LENGTH(c.doc) as bodyLength
+           LENGTH(c.doc) as bodyLength, d.pinned
     FROM documents d
     JOIN content c ON c.hash = d.hash
     WHERE d.active = 1 AND d.content_type = ?