clawmem 0.4.2 → 0.5.1

package/src/hooks/decision-extractor.ts

@@ -335,7 +335,11 @@ export async function decisionExtractor(
         const doc = store.findActiveDocument("_clawmem", obsPath);
         if (doc) {
           store.updateDocumentMeta(doc.id, {
-            content_type: obs.type === "decision" ? "decision" : "observation",
+            content_type: obs.type === "decision" ? "decision"
+              : obs.type === "preference" ? "preference"
+              : obs.type === "milestone" ? "milestone"
+              : obs.type === "problem" ? "problem"
+              : "observation",
             confidence: 0.80,
           });
           store.updateObservationFields(obsPath, "_clawmem", {
@@ -370,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)
@@ -659,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
   // ---------------------------------------------------------------------------