clawmem 0.5.0 → 0.6.0

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/memory.ts

@@ -20,6 +20,7 @@ export const HALF_LIVES: Record<string, number> = {
   project: 120,
   preference: Infinity,
   decision: Infinity,
+  deductive: Infinity,
   hub: Infinity,
 };
 
@@ -29,6 +30,7 @@ export const HALF_LIVES: Record<string, number> = {
 
 export const TYPE_BASELINES: Record<string, number> = {
   decision: 0.85,
+  deductive: 0.85,
   preference: 0.80,
   hub: 0.80,
   problem: 0.75,
@@ -45,7 +47,7 @@ export const TYPE_BASELINES: Record<string, number> = {
 // Content Type Inference
 // =============================================================================
 
-export type ContentType = "decision" | "preference" | "hub" | "research" | "project" | "handoff" | "conversation" | "progress" | "milestone" | "problem" | "note";
+export type ContentType = "decision" | "deductive" | "preference" | "hub" | "research" | "project" | "handoff" | "conversation" | "progress" | "milestone" | "problem" | "note";
 
 export function inferContentType(path: string, explicitType?: string): ContentType {
   if (explicitType && explicitType in TYPE_BASELINES) return explicitType as ContentType;
@@ -75,7 +77,7 @@ export type MemoryType = "episodic" | "semantic" | "procedural";
  */
 export function inferMemoryType(path: string, contentType: string, body?: string): MemoryType {
   if (["handoff", "progress", "conversation"].includes(contentType)) return "episodic";
-  if (["decision", "hub", "research"].includes(contentType)) return "semantic";
+  if (["decision", "deductive", "hub", "research"].includes(contentType)) return "semantic";
   if (body && /\b(step\s+\d|workflow|recipe|how\s+to|procedure|runbook|playbook)\b/i.test(body)) return "procedural";
   if (path.includes("sop") || path.includes("runbook") || path.includes("playbook")) return "procedural";
   if (contentType === "antipattern") return "semantic";
@@ -150,7 +152,7 @@ export function confidenceScore(
   // Attention decay: reduce confidence if not accessed recently (5% per week)
   // Only apply to episodic/progress content — skip for durable types (decision, hub, research)
   // Also skip if last_accessed_at was backfilled from modified_at (no real access yet)
-  const DECAY_EXEMPT_TYPES = new Set(["decision", "hub", "research", "antipattern", "preference"]);
+  const DECAY_EXEMPT_TYPES = new Set(["decision", "deductive", "hub", "research", "antipattern", "preference"]);
   let attentionDecay = 1.0;
   if (lastAccessedAt && !DECAY_EXEMPT_TYPES.has(contentType)) {
     const lastAccess = typeof lastAccessedAt === "string" ? new Date(lastAccessedAt) : lastAccessedAt;