@cleocode/core 2026.4.31 → 2026.4.36

package/src/memory/llm-extraction.ts

@@ -0,0 +1,524 @@
+/**
+ * LLM-driven memory extraction gate.
+ *
+ * Replaces the legacy keyword regex in `auto-extract.ts`. Takes a session
+ * transcript and uses an Anthropic model to extract typed, structured
+ * memories (decisions, patterns, learnings, constraints, corrections)
+ * with justification, importance score, and referenced entities.
+ *
+ * Design:
+ *   - Runs only when `brain.llmExtraction.enabled` is true AND an Anthropic
+ *     API key is available (from ANTHROPIC_API_KEY env var OR Claude Code
+ *     credentials at ~/.claude/.credentials.json). Otherwise returns empty.
+ *   - Uses structured output (JSON schema) for reliable parsing — no regex
+ *     post-processing.
+ *   - Never throws — all errors are caught and logged. The pipeline must
+ *     never block session end.
+ *   - Store routing: each extracted memory is sent through the existing
+ *     verify-and-store pipeline. Decisions → brain_decisions, patterns →
+ *     brain_patterns, learnings/constraints/corrections → brain_learnings.
+ *   - Source is tagged `agent-llm-extracted` so downstream dedup, quality
+ *     scoring, and consolidation can distinguish LLM output from other
+ *     pipelines.
+ *
+ * Research basis: `.cleo/agent-outputs/R-llm-memory-systems-research.md`
+ * (Mem0, Hindsight, Letta, Mastra Observational Memory).
+ */
+
+import type Anthropic from '@anthropic-ai/sdk';
+import { z } from 'zod';
+import { resolveAnthropicApiKey } from './anthropic-key-resolver.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Allowed extraction types. Each maps to a downstream BRAIN store:
+ *
+ * - `decision`    → brain_decisions (architectural/design decisions)
+ * - `pattern`     → brain_patterns  (procedural how-to knowledge)
+ * - `learning`    → brain_learnings (semantic facts with confidence)
+ * - `constraint`  → brain_learnings (rules to follow, high-confidence)
+ * - `correction`  → brain_patterns  (anti-patterns stored with antiPattern field)
+ */
+export type ExtractionType = 'decision' | 'pattern' | 'learning' | 'constraint' | 'correction';
+
+/**
+ * A single memory extracted by the LLM. Fields match the research-approved
+ * prompt pattern so downstream storage can route without additional parsing.
+ */
+export interface ExtractedMemory {
+  /** Category of knowledge — routes to the correct BRAIN table. */
+  type: ExtractionType;
+  /** Declarative knowledge content. Capped at 500 characters by the schema. */
+  content: string;
+  /** Importance score 0.0–1.0; only values ≥ minImportance are persisted. */
+  importance: number;
+  /** Code symbols, file paths, or concepts referenced by this memory. */
+  entities: string[];
+  /** Why the model thinks this memory is worth keeping. Capped at 200 chars. */
+  justification: string;
+}
+
+/** Options for extracting memories from a transcript. */
+export interface ExtractFromTranscriptOptions {
+  /** CLEO project root. */
+  projectRoot: string;
+  /** Session ID used as the source tag on stored memories. */
+  sessionId: string;
+  /** Full session transcript to extract from. */
+  transcript: string;
+  /**
+   * Optional injected Anthropic client — used by tests to mock the SDK
+   * without touching the real network. Production callers should omit this
+   * and let the function construct its own client from `ANTHROPIC_API_KEY`.
+   */
+  client?: Pick<Anthropic, 'messages'>;
+}
+
+/** Summary of what the LLM extraction pipeline produced. */
+export interface ExtractionReport {
+  /** Count of extractions returned by the model before filtering. */
+  extractedCount: number;
+  /** Count persisted after importance filter and verify-and-store gate. */
+  storedCount: number;
+  /** Count merged into existing entries by the verify-and-store gate. */
+  mergedCount: number;
+  /** Count rejected (below minImportance, gate-rejected, or errored). */
+  rejectedCount: number;
+  /** Non-fatal warnings collected during extraction. */
+  warnings: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Zod schema for structured output
+// ---------------------------------------------------------------------------
+
+const ExtractedMemorySchema = z.object({
+  type: z.enum(['decision', 'pattern', 'learning', 'constraint', 'correction']),
+  content: z.string().min(1).max(500),
+  importance: z.number().min(0).max(1),
+  entities: z.array(z.string()).max(20),
+  justification: z.string().min(1).max(200),
+});
+
+const ExtractionResponseSchema = z.object({
+  memories: z.array(ExtractedMemorySchema).max(20),
+});
+
+// ---------------------------------------------------------------------------
+// Prompt
+// ---------------------------------------------------------------------------
+
+const SYSTEM_PROMPT = `You are extracting durable knowledge from a coding session transcript.
+Extract ONLY high-value items. Reject noise (greetings, meta-commentary, transient state).
+
+For each extraction provide:
+- type: decision|pattern|learning|constraint|correction
+- content: the knowledge itself (<=500 chars, declarative form)
+- importance: 0.0-1.0 (only >=0.6 will be stored)
+- entities: code symbols, files, concepts mentioned
+- justification: why this is worth remembering (<=200 chars)
+
+Type definitions:
+- decision: architectural or design choice with rationale ("We chose X because Y")
+- pattern: recurring approach that works ("When X, do Y because Z")
+- learning: factual knowledge gained ("X depends on Y via Z")
+- constraint: rule/limitation discovered ("X must always Y")
+- correction: anti-pattern to avoid ("Avoid X because Y; use Z instead")
+
+Rules:
+- Capture the WHY, not just the WHAT
+- If nothing of durable value exists in the transcript, return an empty array
+- Prefer fewer high-quality extractions over many low-quality ones
+- Ignore: tool output noise, routine status messages, file reads without a finding
+- Maximum 7 extractions per call`;
+
+function buildUserPrompt(sessionId: string, transcript: string, maxExtractions: number): string {
+  return `Session ID: ${sessionId}
+
+Transcript:
+${transcript}
+
+Extract up to ${maxExtractions} high-value memories. Return empty array if nothing valuable.`;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Trim a transcript to a maximum character budget, preserving the head and tail
+ * (the ends typically contain the request and the final outcome).
+ */
+function clipTranscript(transcript: string, maxChars: number): string {
+  if (transcript.length <= maxChars) return transcript;
+  const half = Math.floor(maxChars / 2) - 64;
+  const head = transcript.slice(0, half);
+  const tail = transcript.slice(-half);
+  return `${head}\n\n[... ${transcript.length - maxChars} chars omitted ...]\n\n${tail}`;
+}
+
+/**
+ * Build a MemoryCandidate for the verify-and-store gate from an
+ * ExtractedMemory plus session context.
+ *
+ * Routing:
+ *   - decision    → semantic memory (downstream storeLearning is semantic,
+ *     but decisions go through storeDecision via routing below)
+ *   - pattern     → procedural (goes to brain_patterns via extraction gate)
+ *   - learning    → semantic (brain_learnings)
+ *   - constraint  → semantic (brain_learnings, with higher confidence)
+ *   - correction  → procedural (brain_patterns with antiPattern flag)
+ */
+async function storeExtracted(
+  projectRoot: string,
+  sessionId: string,
+  memory: ExtractedMemory,
+): Promise<'stored' | 'merged' | 'rejected'> {
+  const source = `agent-llm-extracted:${sessionId}`;
+
+  // Decisions use storeDecision directly so contextPhase + type flow through.
+  if (memory.type === 'decision') {
+    const { storeDecision } = await import('./decisions.js');
+    try {
+      // decision text is the content before " because "; rationale follows.
+      const { decisionText, rationale } = splitDecisionContent(memory.content);
+      await storeDecision(projectRoot, {
+        type: 'technical',
+        decision: decisionText,
+        rationale,
+        confidence: mapImportanceToConfidence(memory.importance),
+      });
+      return 'stored';
+    } catch {
+      return 'rejected';
+    }
+  }
+
+  // Corrections map to patterns with antiPattern + mitigation fields.
+  if (memory.type === 'correction') {
+    const { storePattern } = await import('./patterns.js');
+    try {
+      await storePattern(projectRoot, {
+        type: 'failure',
+        pattern: memory.content,
+        context: `From session ${sessionId}. ${memory.justification}`,
+        antiPattern: memory.content,
+        mitigation: memory.justification,
+        impact: memory.importance >= 0.8 ? 'high' : memory.importance >= 0.6 ? 'medium' : 'low',
+        source,
+      });
+      return 'stored';
+    } catch {
+      return 'rejected';
+    }
+  }
+
+  // Patterns map to brain_patterns.
+  if (memory.type === 'pattern') {
+    const { storePattern } = await import('./patterns.js');
+    try {
+      await storePattern(projectRoot, {
+        type: 'workflow',
+        pattern: memory.content,
+        context: `From session ${sessionId}. ${memory.justification}`,
+        impact: memory.importance >= 0.8 ? 'high' : memory.importance >= 0.6 ? 'medium' : 'low',
+        source,
+      });
+      return 'stored';
+    } catch {
+      return 'rejected';
+    }
+  }
+
+  // Learnings and constraints map to brain_learnings.
+  const { storeLearning } = await import('./learnings.js');
+  try {
+    await storeLearning(projectRoot, {
+      insight: memory.content,
+      source,
+      confidence:
+        memory.type === 'constraint' ? Math.max(memory.importance, 0.8) : memory.importance,
+      actionable: memory.type === 'constraint',
+    });
+    return 'stored';
+  } catch {
+    return 'rejected';
+  }
+}
+
+/**
+ * Split a decision extraction into decision + rationale at the first " because "
+ * marker. When no marker exists, the full content becomes the decision and the
+ * justification becomes the rationale.
+ */
+function splitDecisionContent(content: string): { decisionText: string; rationale: string } {
+  const idx = content.toLowerCase().indexOf(' because ');
+  if (idx === -1) {
+    return { decisionText: content.trim(), rationale: 'See justification' };
+  }
+  return {
+    decisionText: content.slice(0, idx).trim(),
+    rationale: content.slice(idx + 1).trim(),
+  };
+}
+
+/**
+ * Map an importance score to a BrainDecisionRow confidence bucket.
+ * Importance is continuous 0–1; confidence is `low` | `medium` | `high`.
+ */
+function mapImportanceToConfidence(importance: number): 'low' | 'medium' | 'high' {
+  if (importance >= 0.8) return 'high';
+  if (importance >= 0.6) return 'medium';
+  return 'low';
+}
+
+// ---------------------------------------------------------------------------
+// Anthropic client construction
+// ---------------------------------------------------------------------------
+
+/**
+ * Lazily import and instantiate the Anthropic SDK.
+ *
+ * Resolves the API key from env or Claude Code credentials. Returns null
+ * when no key is available so callers can gracefully degrade to no-op.
+ * The SDK is imported via dynamic import so projects that do not use the
+ * LLM extraction gate don't pay the load cost at startup.
+ */
+async function buildAnthropicClient(): Promise<Pick<Anthropic, 'messages'> | null> {
+  const apiKey = resolveAnthropicApiKey();
+  if (!apiKey) {
+    return null;
+  }
+  try {
+    const AnthropicModule = await import('@anthropic-ai/sdk');
+    const Ctor =
+      (AnthropicModule as { default?: typeof Anthropic }).default ??
+      (AnthropicModule as unknown as typeof Anthropic);
+    return new Ctor({ apiKey }) as Pick<Anthropic, 'messages'>;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Build the zodOutputFormat helper asynchronously (dynamic import matches
+ * SDK's subpath export style). Returns null when the SDK cannot be loaded.
+ */
+async function buildZodFormat<T extends z.ZodType>(schema: T): Promise<unknown | null> {
+  try {
+    const helpers = await import('@anthropic-ai/sdk/helpers/zod');
+    return helpers.zodOutputFormat(schema);
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract and persist structured memories from a session transcript using
+ * an Anthropic model.
+ *
+ * This is the sole entry point replacing the legacy keyword-regex extractor.
+ * Callers (e.g. the session-end hook) invoke this and the function handles:
+ *   1. Config lookup (brain.llmExtraction.enabled, model, thresholds)
+ *   2. API key detection (skips extraction if missing)
+ *   3. Transcript clipping to stay within token budget
+ *   4. Structured-output LLM call with the research-approved prompt
+ *   5. Importance filtering (below minImportance → dropped)
+ *   6. Storage routing through the existing verify-and-store pipeline
+ *
+ * Never throws. Returns an ExtractionReport describing what was stored.
+ *
+ * @example
+ * ```ts
+ * await extractFromTranscript({
+ *   projectRoot: '/path/to/project',
+ *   sessionId: 'ses_20260413192026_519188',
+ *   transcript: rawTranscript,
+ * });
+ * ```
+ */
+export async function extractFromTranscript(
+  options: ExtractFromTranscriptOptions,
+): Promise<ExtractionReport> {
+  const report: ExtractionReport = {
+    extractedCount: 0,
+    storedCount: 0,
+    mergedCount: 0,
+    rejectedCount: 0,
+    warnings: [],
+  };
+
+  const { projectRoot, sessionId, transcript } = options;
+
+  if (typeof transcript !== 'string' || transcript.trim().length === 0) {
+    return report;
+  }
+
+  // -------------------------------------------------------------------------
+  // Config lookup
+  // -------------------------------------------------------------------------
+  const { loadConfig } = await import('../config.js');
+  type LoadedConfig = Awaited<ReturnType<typeof loadConfig>> | undefined;
+  let config: LoadedConfig;
+  try {
+    config = await loadConfig(projectRoot);
+  } catch {
+    report.warnings.push('config load failed, using defaults');
+    config = undefined;
+  }
+
+  const llmCfg = config?.brain?.llmExtraction;
+  const enabled = llmCfg?.enabled ?? true;
+  if (!enabled) {
+    report.warnings.push('llmExtraction.enabled=false');
+    return report;
+  }
+
+  const model = llmCfg?.model ?? 'claude-haiku-4-5-20251001';
+  const minImportance = llmCfg?.minImportance ?? 0.6;
+  const maxExtractions = llmCfg?.maxExtractions ?? 7;
+  const maxTranscriptChars = llmCfg?.maxTranscriptChars ?? 60000;
+
+  // -------------------------------------------------------------------------
+  // Client construction (allow injection for tests)
+  // -------------------------------------------------------------------------
+  const client = options.client ?? (await buildAnthropicClient());
+  if (!client) {
+    report.warnings.push(
+      'No Anthropic API key found (checked ANTHROPIC_API_KEY env and ~/.claude/.credentials.json) — extraction skipped',
+    );
+    return report;
+  }
+
+  // -------------------------------------------------------------------------
+  // Call the model
+  // -------------------------------------------------------------------------
+  const clipped = clipTranscript(transcript, maxTranscriptChars);
+  const userPrompt = buildUserPrompt(sessionId, clipped, maxExtractions);
+
+  let extracted: ExtractedMemory[] = [];
+
+  try {
+    const format = await buildZodFormat(ExtractionResponseSchema);
+    if (format) {
+      // Preferred path: structured output via SDK helper.
+      const messages = client.messages as unknown as {
+        parse: (body: Record<string, unknown>) => Promise<{
+          parsed_output?: { memories?: ExtractedMemory[] };
+        }>;
+      };
+      const response = await messages.parse({
+        model,
+        max_tokens: 4096,
+        system: SYSTEM_PROMPT,
+        messages: [{ role: 'user', content: userPrompt }],
+        output_config: { format },
+      });
+      extracted = response.parsed_output?.memories ?? [];
+    } else {
+      // Degraded path: plain messages.create + manual JSON parsing.
+      extracted = await extractViaPlainCall(client, model, userPrompt);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    report.warnings.push(`extraction call failed: ${message}`);
+    return report;
+  }
+
+  report.extractedCount = extracted.length;
+
+  // -------------------------------------------------------------------------
+  // Filter + store
+  // -------------------------------------------------------------------------
+  for (const memory of extracted) {
+    if (memory.importance < minImportance) {
+      report.rejectedCount += 1;
+      continue;
+    }
+
+    try {
+      const outcome = await storeExtracted(projectRoot, sessionId, memory);
+      if (outcome === 'stored') report.storedCount += 1;
+      else if (outcome === 'merged') report.mergedCount += 1;
+      else report.rejectedCount += 1;
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      report.warnings.push(`store failed: ${message}`);
+      report.rejectedCount += 1;
+    }
+  }
+
+  return report;
+}
+
+/**
+ * Fallback extraction path: calls messages.create and parses the response
+ * content manually. Used when the zod helper cannot be loaded (e.g. SDK
+ * version mismatch) but the messages.create API is still available.
+ */
+async function extractViaPlainCall(
+  client: Pick<Anthropic, 'messages'>,
+  model: string,
+  userPrompt: string,
+): Promise<ExtractedMemory[]> {
+  const response = await client.messages.create({
+    model,
+    max_tokens: 4096,
+    system: `${SYSTEM_PROMPT}\n\nReturn ONLY a JSON object of shape {"memories": [...]} with no prose.`,
+    messages: [{ role: 'user', content: userPrompt }],
+  });
+
+  const text = extractTextFromResponse(response);
+  if (!text) return [];
+
+  const parsed = safeJsonParse(text);
+  if (!parsed) return [];
+
+  const validated = ExtractionResponseSchema.safeParse(parsed);
+  if (!validated.success) return [];
+
+  return validated.data.memories;
+}
+
+/**
+ * Pull plain text from a messages.create response. Anthropic returns a
+ * content array; we concatenate all text blocks.
+ */
+function extractTextFromResponse(response: unknown): string {
+  const content = (response as { content?: Array<{ type?: string; text?: string }> })?.content;
+  if (!Array.isArray(content)) return '';
+  return content
+    .filter((block) => block?.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text ?? '')
+    .join('');
+}
+
+/**
+ * Parse JSON, extracting the first {...} object even if the model wrapped
+ * it in markdown fences or added prose. Returns null on any failure.
+ */
+function safeJsonParse(text: string): unknown {
+  const trimmed = text.trim();
+  // Direct parse first
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    // Fall through to extraction
+  }
+  // Extract between first { and last }
+  const first = trimmed.indexOf('{');
+  const last = trimmed.lastIndexOf('}');
+  if (first === -1 || last === -1 || last < first) return null;
+  try {
+    return JSON.parse(trimmed.slice(first, last + 1));
+  } catch {
+    return null;
+  }
+}

package/src/memory/memory-bridge.ts

@@ -163,7 +163,7 @@ export async function generateMemoryBridgeContent(
     lines.push('');
     for (const d of decisions) {
       const date = (d.created_at ?? '').slice(0, 10);
-      lines.push(`- [${d.id}] ${d.decision.slice(0, 120)} (${date})`);
+      lines.push(`- [${d.id}] ${d.decision.slice(0, 300)} (${date})`);
     }
     lines.push('');
   }
@@ -174,30 +174,30 @@ export async function generateMemoryBridgeContent(
     lines.push('## Key Learnings');
     lines.push('');
     for (const l of learnings) {
-      lines.push(`- [${l.id}] ${l.insight.slice(0, 150)} (confidence: ${l.confidence})`);
+      lines.push(`- [${l.id}] ${l.insight.slice(0, 400)} (confidence: ${l.confidence})`);
     }
     lines.push('');
   }
 
-  // --- Patterns (follow) ---
-  const followPatterns = queryPatterns(nativeDb, 'success', cfg.maxPatterns);
+  // --- Patterns to Follow (success, workflow, optimization) ---
+  const followPatterns = queryUsefulPatterns(nativeDb, 'follow', cfg.maxPatterns);
   if (followPatterns.length > 0) {
     lines.push('## Patterns to Follow');
     lines.push('');
     for (const p of followPatterns) {
-      lines.push(`- [${p.id}] ${p.pattern.slice(0, 150)} (${p.type})`);
+      lines.push(`- [${p.id}] ${p.pattern.slice(0, 300)} (${p.type})`);
     }
     lines.push('');
   }
 
-  // --- Anti-patterns (avoid) ---
+  // --- Anti-Patterns to Avoid (failure, blocker) ---
   if (cfg.includeAntiPatterns) {
-    const avoidPatterns = queryPatterns(nativeDb, 'failure', cfg.maxPatterns);
+    const avoidPatterns = queryUsefulPatterns(nativeDb, 'avoid', cfg.maxPatterns);
     if (avoidPatterns.length > 0) {
       lines.push('## Anti-Patterns to Avoid');
       lines.push('');
       for (const p of avoidPatterns) {
-        lines.push(`- [${p.id}] AVOID: ${p.pattern.slice(0, 150)}`);
+        lines.push(`- [${p.id}] AVOID: ${p.pattern.slice(0, 300)}`);
       }
       lines.push('');
     }
@@ -210,7 +210,7 @@ export async function generateMemoryBridgeContent(
     lines.push('');
     for (const o of observations) {
       const date = (o.created_at ?? '').slice(0, 10);
-      lines.push(`- [${o.id}] ${date}: ${o.title.slice(0, 120)}`);
+      lines.push(`- [${o.id}] ${date}: ${o.title.slice(0, 200)}`);
     }
     lines.push('');
   }
@@ -405,6 +405,7 @@ function queryHighConfidenceLearnings(db: DatabaseSync, limit: number): Learning
       db,
       `SELECT id, insight, confidence, created_at, updated_at FROM brain_learnings
          WHERE CAST(confidence AS REAL) >= 0.3
+           AND insight NOT LIKE 'Completed:%'
          ORDER BY confidence DESC, created_at DESC
          LIMIT ?`,
       limit * 3,
@@ -437,12 +438,28 @@ function queryHighConfidenceLearnings(db: DatabaseSync, limit: number): Learning
   }
 }
 
-function queryPatterns(db: DatabaseSync, type: string, limit: number): PatternRow[] {
+function queryUsefulPatterns(
+  db: DatabaseSync,
+  mode: 'follow' | 'avoid',
+  limit: number,
+): PatternRow[] {
   try {
+    const typeFilter =
+      mode === 'follow'
+        ? "type IN ('success', 'workflow', 'optimization')"
+        : "type IN ('failure', 'blocker')";
+
     return typedAll<PatternRow>(
       db,
-      'SELECT id, pattern, type, impact, extracted_at FROM brain_patterns WHERE type = ? ORDER BY extracted_at DESC LIMIT ?',
-      type,
+      `SELECT id, pattern, type, impact, extracted_at FROM brain_patterns
+         WHERE ${typeFilter}
+           AND pattern NOT LIKE 'Recurring label%'
+           AND pattern NOT LIKE 'Test pattern%'
+           AND pattern NOT LIKE 'test'
+           AND pattern NOT LIKE 'Audit probe:%'
+           AND LENGTH(pattern) > 20
+         ORDER BY extracted_at DESC
+         LIMIT ?`,
       limit,
     );
   } catch {