clawmem 0.1.7 → 0.2.0

package/src/graph-traversal.ts

@@ -201,6 +201,238 @@ export function adaptiveTraversal(
   return Array.from(visited.values()).sort((a, b) => b.score - a.score);
 }
 
+// =============================================================================
+// MPFP: Multi-Path Fact Propagation (Pattern E)
+// =============================================================================
+
+/**
+ * Predefined meta-path patterns for graph traversal.
+ * Each pattern is a sequence of edge types to follow at each hop.
+ */
+export type MetaPath = string[];
+
+/**
+ * Get MPFP meta-path patterns based on intent.
+ */
+export function getMetaPathsForIntent(intent: IntentType): MetaPath[] {
+  switch (intent) {
+    case 'WHY':
+      return [
+        ['semantic', 'causal'],      // forward causal reasoning
+        ['causal', 'semantic'],      // backward reasoning → context
+        ['semantic', 'semantic'],    // topic expansion
+      ];
+    case 'ENTITY':
+      return [
+        ['entity', 'semantic'],      // entity → related topics
+        ['entity', 'entity'],        // entity co-occurrence chains
+        ['semantic', 'entity'],      // topic → entity discovery
+      ];
+    case 'WHEN':
+      return [
+        ['temporal', 'semantic'],    // timeline → context
+        ['semantic', 'temporal'],    // context → timeline
+      ];
+    case 'WHAT':
+      return [
+        ['semantic', 'semantic'],    // topic expansion
+        ['semantic', 'supporting'],  // evidence chains
+      ];
+  }
+}
+
+/**
+ * Shared edge cache for hop-synchronized loading.
+ * All patterns share this cache to avoid redundant DB queries.
+ */
+type EdgeCache = Map<number, Map<string, { docId: number; weight: number }[]>>;
+
+/**
+ * Batch-load edges for a set of node IDs, filtered by edge type.
+ * Results cached in edgeCache for reuse across patterns.
+ */
+function batchLoadEdges(
+  db: Database,
+  nodeIds: number[],
+  edgeType: string,
+  edgeCache: EdgeCache,
+  topK: number = 10
+): void {
+  // Only load nodes not already cached for this edge type
+  const uncached = nodeIds.filter(id => {
+    const cached = edgeCache.get(id);
+    return !cached || !cached.has(edgeType);
+  });
+
+  if (uncached.length === 0) return;
+
+  const placeholders = uncached.map(() => '?').join(',');
+
+  // Outbound edges (source → target)
+  const outbound = db.prepare(`
+    SELECT source_id, target_id as docId, weight
+    FROM memory_relations
+    WHERE source_id IN (${placeholders}) AND relation_type = ?
+    ORDER BY weight DESC
+  `).all(...uncached, edgeType) as { source_id: number; docId: number; weight: number }[];
+
+  // Inbound edges for symmetric types (semantic, entity)
+  let inbound: { source_id: number; docId: number; weight: number }[] = [];
+  if (edgeType === 'semantic' || edgeType === 'entity') {
+    inbound = db.prepare(`
+      SELECT target_id as source_id, source_id as docId, weight
+      FROM memory_relations
+      WHERE target_id IN (${placeholders}) AND relation_type = ?
+      ORDER BY weight DESC
+    `).all(...uncached, edgeType) as typeof inbound;
+  }
+
+  // Populate cache (top-k per node)
+  for (const nodeId of uncached) {
+    if (!edgeCache.has(nodeId)) edgeCache.set(nodeId, new Map());
+    const nodeEdges = [
+      ...outbound.filter(e => e.source_id === nodeId),
+      ...inbound.filter(e => e.source_id === nodeId),
+    ].slice(0, topK);
+    edgeCache.get(nodeId)!.set(edgeType, nodeEdges.map(e => ({ docId: e.docId, weight: e.weight })));
+  }
+}
+
+/**
+ * Execute a single meta-path traversal using Forward Push with teleport.
+ *
+ * @param db - Database instance
+ * @param anchors - Seed nodes with initial scores
+ * @param metaPath - Edge type sequence to follow at each hop
+ * @param edgeCache - Shared edge cache (hop-synchronized)
+ * @param alpha - Teleport probability (default 0.15)
+ * @param threshold - Mass pruning threshold (default 1e-4)
+ * @returns Nodes discovered with scores
+ */
+function executeMetaPath(
+  db: Database,
+  anchors: { docId: number; score: number }[],
+  metaPath: MetaPath,
+  edgeCache: EdgeCache,
+  alpha: number = 0.15,
+  threshold: number = 1e-4
+): TraversalNode[] {
+  const results = new Map<number, number>(); // docId → accumulated score
+
+  // Initialize residual with anchor scores
+  let residual = new Map<number, number>();
+  for (const a of anchors) {
+    residual.set(a.docId, a.score);
+    results.set(a.docId, a.score * alpha); // teleport portion stays at seed
+  }
+
+  // Walk each hop in the meta-path
+  for (let hop = 0; hop < metaPath.length; hop++) {
+    const edgeType = metaPath[hop]!;
+    const activeNodes = [...residual.entries()].filter(([_, mass]) => mass > threshold);
+    if (activeNodes.length === 0) break;
+
+    // Batch-load edges for this hop (shared cache)
+    const nodeIds = activeNodes.map(([id]) => id);
+    batchLoadEdges(db, nodeIds, edgeType, edgeCache);
+
+    const nextResidual = new Map<number, number>();
+
+    for (const [nodeId, mass] of activeNodes) {
+      const propagated = mass * (1 - alpha);
+      const nodeEdges = edgeCache.get(nodeId)?.get(edgeType) || [];
+
+      if (nodeEdges.length === 0) continue;
+
+      // Distribute mass evenly across neighbors (weighted by edge weight)
+      const totalWeight = nodeEdges.reduce((sum, e) => sum + e.weight, 0);
+      if (totalWeight === 0) continue;
+
+      for (const edge of nodeEdges) {
+        const share = (propagated * edge.weight) / totalWeight;
+        const current = nextResidual.get(edge.docId) || 0;
+        nextResidual.set(edge.docId, current + share);
+
+        // Accumulate in results (teleport portion)
+        const existing = results.get(edge.docId) || 0;
+        results.set(edge.docId, existing + share * alpha);
+      }
+    }
+
+    residual = nextResidual;
+  }
+
+  // Convert to TraversalNode array
+  return [...results.entries()]
+    .filter(([_, score]) => score > threshold)
+    .map(([docId, score]) => ({
+      docId,
+      path: getDocPath(db, docId),
+      score,
+      hops: metaPath.length,
+      viaRelation: metaPath.join('→'),
+    }))
+    .sort((a, b) => b.score - a.score);
+}
+
+/**
+ * MPFP Multi-Path Fact Propagation traversal.
+ * Runs multiple meta-path patterns in parallel, fuses results.
+ *
+ * @param db - Database instance
+ * @param anchors - Seed documents (from BM25/vector search)
+ * @param intent - Query intent for pattern selection
+ * @param budget - Maximum total nodes to return
+ * @returns Traversed nodes with scores
+ */
+export function mpfpTraversal(
+  db: Database,
+  anchors: { hash: string; score: number }[],
+  intent: IntentType,
+  budget: number = 30
+): TraversalNode[] {
+  // Convert hashes to IDs
+  const anchorNodes: { docId: number; score: number }[] = [];
+  for (const anchor of anchors) {
+    const docId = getDocIdFromHash(db, anchor.hash);
+    if (docId !== null) {
+      anchorNodes.push({ docId, score: anchor.score });
+    }
+  }
+
+  if (anchorNodes.length === 0) return [];
+
+  const metaPaths = getMetaPathsForIntent(intent);
+  const edgeCache: EdgeCache = new Map(); // Shared across all patterns
+
+  // Execute all meta-paths (synchronous — SQLite is single-threaded anyway)
+  const pathResults: TraversalNode[][] = metaPaths.map(path =>
+    executeMetaPath(db, anchorNodes, path, edgeCache)
+  );
+
+  // Fuse results via max-score (not RRF): Forward Push produces absolute propagation mass
+  // where magnitude carries signal. Rank-only fusion (RRF) would discard the difference
+  // between a strong path hit (0.9) and a barely-surviving tail hit (0.01). Meta-paths are
+  // alternative explanations — "best supporting path wins" is the correct fusion rule here.
+  const fused = new Map<number, TraversalNode>();
+  for (const results of pathResults) {
+    for (const node of results) {
+      const existing = fused.get(node.docId);
+      if (!existing || node.score > existing.score) {
+        fused.set(node.docId, node);
+      }
+    }
+  }
+
+  return [...fused.values()]
+    .sort((a, b) => b.score - a.score)
+    .slice(0, budget);
+}
+
+// =============================================================================
+// Merge Helpers
+// =============================================================================
+
 /**
  * Merge graph traversal results with original search results.
  * Returns results with both hash and score for re-integration.

package/src/hooks/context-surfacing.ts

@@ -52,6 +52,11 @@ function getTierConfig(score: number): { snippetLen: number; showMeta: boolean;
 // Directories to never surface
 const FILTERED_PATHS = ["_PRIVATE/", "experiments/", "_clawmem/"];
 
+// Memory nudge: prompt agent to use lifecycle tools after N prompts without use
+const NUDGE_INTERVAL = parseInt(process.env.CLAWMEM_NUDGE_INTERVAL || "15", 10);
+const LIFECYCLE_HOOK_NAMES = ["memory_pin", "memory_forget", "memory_snooze", "lifecycle-archive"];
+const NUDGE_TEXT = "You haven't managed memory recently. If vault-context is surfacing noise → snooze it. If a critical decision was just made → pin it. If stale knowledge appeared → forget it.";
+
 // File path patterns to extract from prompts (E13 replacement: file-aware UserPromptSubmit)
 const FILE_PATH_RE = /(?:^|\s)((?:\/[\w.@-]+)+(?:\.\w+)?|[\w.@-]+\.(?:ts|js|py|md|sh|yaml|yml|json|toml|rs|go|tsx|jsx|css|html))\b/g;
 
@@ -331,12 +336,15 @@ export async function contextSurfacing(
   // This makes routing instructions salient at the moment of tool selection (per research)
   const routingHint = detectRoutingHint(prompt);
 
-  return makeContextOutput(
-    "context-surfacing",
-    routingHint
-      ? `<vault-routing>${routingHint}</vault-routing>\n<vault-context>\n${context}\n</vault-context>`
-      : `<vault-context>\n${context}\n</vault-context>`
-  );
+  // Memory nudge: periodically remind agent to use lifecycle tools
+  const nudge = NUDGE_INTERVAL > 0 ? shouldNudge(store) : null;
+
+  const parts: string[] = [];
+  if (routingHint) parts.push(`<vault-routing>${routingHint}</vault-routing>`);
+  parts.push(`<vault-context>\n${context}\n</vault-context>`);
+  if (nudge) parts.push(`<vault-nudge>${NUDGE_TEXT}</vault-nudge>`);
+
+  return makeContextOutput("context-surfacing", parts.join("\n"));
 }
 
 // =============================================================================
@@ -422,3 +430,28 @@ function buildContext(
     tokens: totalTokens,
   };
 }
+
+/**
+ * Check if the agent should be nudged to use lifecycle tools.
+ * Returns true if N+ context-surfacing invocations have occurred since the
+ * last lifecycle tool use (memory_pin, memory_forget, memory_snooze).
+ */
+function shouldNudge(store: Store): boolean {
+  try {
+    // Count context-surfacing invocations since last lifecycle tool use
+    const lastLifecycle = store.db.prepare(`
+      SELECT MAX(id) as max_id FROM context_usage
+      WHERE hook_name IN (${LIFECYCLE_HOOK_NAMES.map(() => "?").join(",")})
+    `).get(...LIFECYCLE_HOOK_NAMES) as { max_id: number | null } | undefined;
+
+    const sinceId = lastLifecycle?.max_id ?? 0;
+    const count = store.db.prepare(`
+      SELECT COUNT(*) as cnt FROM context_usage
+      WHERE hook_name = 'context-surfacing' AND id > ?
+    `).get(sinceId) as { cnt: number } | undefined;
+
+    return (count?.cnt ?? 0) >= NUDGE_INTERVAL;
+  } catch {
+    return false; // DB error — fail silent, no nudge
+  }
+}

package/src/hooks/decision-extractor.ts

@@ -254,13 +254,35 @@ Only include pairs with confidence >= 0.7. Return [] if no relationships found.
       if (rel.relation === "contradiction") {
         // Lower old doc confidence by 0.25 (floor 0.2)
         const currentConfidence = existingDoc.confidence ?? 0.5;
+        const newConfidence = Math.max(0.2, currentConfidence - 0.25);
         store.updateDocumentMeta(existingDoc.id, {
-          confidence: Math.max(0.2, currentConfidence - 0.25),
+          confidence: newConfidence,
         });
         contradictionCount++;
         console.error(
           `[decision-extractor] CONTRADICTION: "${newFacts[rel.new_idx]}" vs "${oldDoc.displayPath}" (conf: ${rel.confidence})`
         );
+
+        // Soft invalidation: if confidence drops to floor AND content is observation type,
+        // mark as invalidated (Pattern I — prevents stale contradicted knowledge from surfacing)
+        if (newConfidence <= 0.2) {
+          try {
+            // Find the new contradicting observation's doc ID (if already persisted in this session)
+            const newObsDoc = store.db.prepare(`
+              SELECT id FROM documents
+              WHERE collection = '_clawmem' AND path LIKE ? AND active = 1
+              ORDER BY created_at DESC LIMIT 1
+            `).get(`%${sessionId.slice(0, 8)}%decision%`) as { id: number } | undefined;
+
+            store.db.prepare(`
+              UPDATE documents
+              SET invalidated_at = datetime('now'),
+                  invalidated_by = ?
+              WHERE id = ? AND invalidated_at IS NULL AND content_type = 'observation'
+            `).run(newObsDoc?.id || null, existingDoc.id);
+          } catch { /* non-fatal — invalidation is best-effort */ }
+        }
+
       } else if (rel.relation === "update") {
         // Lower old doc confidence by 0.15 (floor 0.3)
         const currentConfidence = existingDoc.confidence ?? 0.5;
@@ -313,7 +335,7 @@ export async function decisionExtractor(
         const doc = store.findActiveDocument("_clawmem", obsPath);
         if (doc) {
           store.updateDocumentMeta(doc.id, {
-            content_type: obs.type === "decision" ? "decision" : "note",
+            content_type: obs.type === "decision" ? "decision" : "observation",
             confidence: 0.80,
           });
           store.updateObservationFields(obsPath, "_clawmem", {

package/src/hooks/staleness-check.ts

@@ -51,6 +51,33 @@ export async function stalenessCheck(
     }
   }
 
+  // Auto-archive if lifecycle policy is configured (runs regardless of stale report results)
+  try {
+    const { loadVaultConfig } = await import("../config.ts");
+    const config = loadVaultConfig();
+    if (config.lifecycle) {
+      const candidates = store.getArchiveCandidates(config.lifecycle);
+      if (candidates.length > 0 && !config.lifecycle.dry_run) {
+        const archived = store.archiveDocuments(candidates.map(c => c.id));
+        if (archived > 0 && input.sessionId) {
+          store.insertUsage({
+            sessionId: input.sessionId,
+            timestamp: now.toISOString(),
+            hookName: "lifecycle-archive",
+            injectedPaths: candidates.map(c => `${c.collection}/${c.path}`),
+            estimatedTokens: 0,
+            wasReferenced: 0,
+          });
+        }
+      }
+      if (config.lifecycle.purge_after_days && !config.lifecycle.dry_run) {
+        store.purgeArchivedDocuments(config.lifecycle.purge_after_days);
+      }
+    }
+  } catch {
+    // Fail-open: lifecycle errors never block the hook
+  }
+
   if (allStale.size === 0) return makeEmptyOutput("staleness-check");
 
   // Build context within budget

package/src/hooks.ts

@@ -84,6 +84,7 @@ const HOOK_EVENT_MAP: Record<string, string | null> = {
   "feedback-loop": null,           // Stop — no hookSpecificOutput
   "precompact-extract": null,      // PreCompact — side-effect only, no context injection
   "postcompact-inject": "SessionStart", // SessionStart(compact) — injects additionalContext
+  "curator-nudge": "SessionStart",     // SessionStart — surfaces curator report actions
   "pretool-inject": null,          // PreToolUse — disabled (cannot inject additionalContext; E13 folded into context-surfacing)
 };
 

package/src/intent.ts

@@ -29,40 +29,114 @@ const ENTITY_PATTERNS = /\b(who|person|team|project|(?:@|#)\w+|relationship|ment
 // Temporal extraction patterns
 type TemporalExtractor = (now: Date, match?: RegExpMatchArray) => { start?: string; end?: string };
 
+const MONTH_MAP: Record<string, number> = { jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5, jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11 };
+
+/** Format a Date as YYYY-MM-DD in local timezone (avoids UTC shift from toISOString). */
+function localDateStr(d: Date): string {
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
+}
+
 const TEMPORAL_RELATIVE: [RegExp, TemporalExtractor][] = [
+  [/\btoday\b/i, (now: Date) => {
+    const d = localDateStr(now);
+    return { start: d, end: d };
+  }],
+  [/\byesterday\b/i, (now: Date) => {
+    const s = new Date(now); s.setDate(s.getDate() - 1);
+    return { start: localDateStr(s), end: localDateStr(s) };
+  }],
+  [/\bthis week\b/i, (now: Date) => {
+    const s = new Date(now); s.setDate(s.getDate() - s.getDay());
+    return { start: localDateStr(s), end: localDateStr(now) };
+  }],
   [/\blast week\b/i, (now: Date) => {
     const s = new Date(now); s.setDate(s.getDate() - 7);
-    return { start: s.toISOString().slice(0, 10), end: now.toISOString().slice(0, 10) };
+    return { start: localDateStr(s), end: localDateStr(now) };
+  }],
+  [/\bthis month\b/i, (now: Date) => {
+    const s = new Date(now.getFullYear(), now.getMonth(), 1);
+    return { start: localDateStr(s), end: localDateStr(now) };
   }],
   [/\blast month\b/i, (now: Date) => {
     const s = new Date(now); s.setMonth(s.getMonth() - 1);
-    return { start: s.toISOString().slice(0, 10), end: now.toISOString().slice(0, 10) };
-  }],
-  [/\byesterday\b/i, (now: Date) => {
-    const s = new Date(now); s.setDate(s.getDate() - 1);
-    return { start: s.toISOString().slice(0, 10), end: s.toISOString().slice(0, 10) };
+    return { start: localDateStr(s), end: localDateStr(now) };
   }],
   [/\b(\d+)\s*days?\s*ago\b/i, (now: Date, m?: RegExpMatchArray) => {
     const s = new Date(now); s.setDate(s.getDate() - parseInt(m?.[1] ?? "1"));
-    return { start: s.toISOString().slice(0, 10), end: now.toISOString().slice(0, 10) };
+    return { start: localDateStr(s), end: localDateStr(now) };
+  }],
+  [/\b(\d+)\s*weeks?\s*ago\b/i, (now: Date, m?: RegExpMatchArray) => {
+    const s = new Date(now); s.setDate(s.getDate() - parseInt(m?.[1] ?? "1") * 7);
+    return { start: localDateStr(s), end: localDateStr(now) };
   }],
-  [/\bin\s+(jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\s*(\d{4})?\b/i, (_now: Date, m?: RegExpMatchArray) => {
-    const months: Record<string, number> = { jan: 0, feb: 1, mar: 2, apr: 3, may: 4, jun: 5, jul: 6, aug: 7, sep: 8, oct: 9, nov: 10, dec: 11 };
-    const mo = months[(m?.[1] ?? "jan").slice(0, 3).toLowerCase()] ?? 0;
-    const yr = m?.[2] ? parseInt(m[2]) : new Date().getFullYear();
+  [/\b(\d+)\s*months?\s*ago\b/i, (now: Date, m?: RegExpMatchArray) => {
+    const s = new Date(now); s.setMonth(s.getMonth() - parseInt(m?.[1] ?? "1"));
+    return { start: localDateStr(s), end: localDateStr(now) };
+  }],
+  [/\bsince\s+(jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\s*(\d{4})?\b/i, (now: Date, m?: RegExpMatchArray) => {
+    const mo = MONTH_MAP[(m?.[1] ?? "jan").slice(0, 3).toLowerCase()] ?? 0;
+    const yr = m?.[2] ? parseInt(m[2]) : now.getFullYear();
+    const s = new Date(yr, mo, 1);
+    return { start: localDateStr(s), end: localDateStr(now) };
+  }],
+  [/\bin\s+(jan(?:uary)?|feb(?:ruary)?|mar(?:ch)?|apr(?:il)?|may|jun(?:e)?|jul(?:y)?|aug(?:ust)?|sep(?:tember)?|oct(?:ober)?|nov(?:ember)?|dec(?:ember)?)\s*(\d{4})?\b/i, (now: Date, m?: RegExpMatchArray) => {
+    const mo = MONTH_MAP[(m?.[1] ?? "jan").slice(0, 3).toLowerCase()] ?? 0;
+    const yr = m?.[2] ? parseInt(m[2]) : now.getFullYear();
     const s = new Date(yr, mo, 1);
     const e = new Date(yr, mo + 1, 0);
-    return { start: s.toISOString().slice(0, 10), end: e.toISOString().slice(0, 10) };
+    return { start: localDateStr(s), end: localDateStr(e) };
+  }],
+  [/\blast\s+(\d+)\s*days?\b/i, (now: Date, m?: RegExpMatchArray) => {
+    const s = new Date(now); s.setDate(s.getDate() - parseInt(m?.[1] ?? "7"));
+    return { start: localDateStr(s), end: localDateStr(now) };
   }],
 ];
 
+/**
+ * Convert a local date string (YYYY-MM-DD) to a UTC ISO timestamp for the start of that local day.
+ * Accounts for timezone offset so comparisons against UTC modified_at are correct.
+ */
+function localDateToUtcStart(localDate: string): string {
+  const d = new Date(localDate + 'T00:00:00');
+  return d.toISOString();
+}
+
+/**
+ * Convert a local date string (YYYY-MM-DD) to a UTC ISO timestamp for the end of that local day.
+ */
+function localDateToUtcEnd(localDate: string): string {
+  const d = new Date(localDate + 'T23:59:59.999');
+  return d.toISOString();
+}
+
+/**
+ * Extract temporal constraint from query. Returns {start, end} as UTC ISO timestamps or null.
+ * Pure regex — no LLM, ~0ms.
+ */
+export function extractTemporalConstraint(query: string): { start: string; end: string } | null {
+  const q = query.toLowerCase();
+  for (const [pattern, extractor] of TEMPORAL_RELATIVE) {
+    const match = q.match(pattern);
+    if (match) {
+      const result = extractor(new Date(), match);
+      if (result.start && result.end) {
+        return {
+          start: localDateToUtcStart(result.start),
+          end: localDateToUtcEnd(result.end),
+        };
+      }
+    }
+  }
+  return null;
+}
+
 /**
  * Fast heuristic intent classification (no LLM, instant).
  */
 function classifyIntentHeuristic(query: string): IntentResult {
   const q = query.toLowerCase();
 
-  // Extract temporal info
+  // Extract temporal info (local date strings for intent scoring; UTC conversion at query time)
   let temporal_start: string | undefined;
   let temporal_end: string | undefined;
   const now = new Date();