@cleocode/core 2026.4.30 → 2026.4.35

package/src/memory/learnings.ts

@@ -12,6 +12,8 @@
 
 import { randomBytes } from 'node:crypto';
 import { getBrainAccessor } from '../store/brain-accessor.js';
+import { upsertGraphNode } from './graph-auto-populate.js';
+import { computeLearningQuality } from './quality-scoring.js';
 
 /** Parameters for storing a new learning. */
 export interface StoreLearningParams {
@@ -44,10 +46,10 @@ function generateLearningId(): string {
  * @task T4769, T5241
  */
 export async function storeLearning(projectRoot: string, params: StoreLearningParams) {
-  if (!params.insight || !params.insight.trim()) {
+  if (!params.insight?.trim()) {
     throw new Error('Insight text is required');
   }
-  if (!params.source || !params.source.trim()) {
+  if (!params.source?.trim()) {
     throw new Error('Source is required');
   }
   if (params.confidence < 0 || params.confidence > 1) {
@@ -55,18 +57,77 @@ export async function storeLearning(projectRoot: string, params: StoreLearningPa
   }
 
   const accessor = await getBrainAccessor(projectRoot);
-  const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
 
-  // Check for duplicate insight
+  // Check for duplicate insight by normalized text
   const existingLearnings = await accessor.findLearnings();
+  const normalizedInput = params.insight.trim().toLowerCase();
   const duplicate = existingLearnings.find(
-    (e) => e.insight.toLowerCase() === params.insight.toLowerCase(),
+    (e) => e.insight.trim().toLowerCase() === normalizedInput,
   );
 
   if (duplicate) {
-    // We would ideally increment confidence here or update. Let's assume we don't have update method on accessor yet.
+    // Take the higher confidence value and update the timestamp
+    const maxConfidence = Math.max(duplicate.confidence, params.confidence);
+    await accessor.updateLearning(duplicate.id, {
+      confidence: maxConfidence,
+    });
+
+    const updated = await accessor.getLearning(duplicate.id);
+
+    // Refresh graph node for the updated learning (best-effort, T537).
+    upsertGraphNode(
+      projectRoot,
+      `learning:${duplicate.id}`,
+      'learning',
+      duplicate.insight.substring(0, 200),
+      duplicate.qualityScore ?? 0.5,
+      duplicate.insight + (duplicate.application ?? ''),
+      { source: duplicate.source, confidence: maxConfidence, actionable: duplicate.actionable },
+    ).catch(() => {
+      /* best-effort */
+    });
+
+    return {
+      ...updated!,
+      applicableTypes: JSON.parse(updated!.applicableTypesJson || '[]'),
+    };
   }
 
+  // T549 Wave 1-A: Tier routing for learnings.
+  // Learnings are short-term semantic entries — they start unverified and must earn promotion.
+  // sourceConfidence routing (spec §4.1 Decision Tree):
+  //   - source contains 'manual' → 'owner' (manually entered learnings are owner-stated)
+  //   - source contains 'transcript:ses_' → 'speculative' (transcript-extracted, low confidence)
+  //   - otherwise → 'agent' (agent-generated during session grading, hooks, etc.)
+  // memoryTier routing:
+  //   - source contains 'manual' → 'medium' (owner-stated facts skip short-term)
+  //   - otherwise → 'short' (auto/agent learnings start short-term, consolidator promotes)
+  // memoryType routing (spec §4.1 Decision Tree for memoryType):
+  //   - source contains 'transcript:ses_' → 'episodic' (event-specific insight)
+  //   - otherwise → 'semantic' (declarative factual learning)
+  // verified = false (learnings need corroboration or manual verify gate)
+  const isManual = params.source.includes('manual');
+  const isTranscript = params.source.includes('transcript:ses_');
+  const sourceConfidence = isManual
+    ? ('owner' as const)
+    : isTranscript
+      ? ('speculative' as const)
+      : ('agent' as const);
+  const memoryTier = isManual ? ('medium' as const) : ('short' as const);
+  const memoryType = isTranscript ? ('episodic' as const) : ('semantic' as const);
+  const verified = false;
+
+  // Compute quality score from confidence, actionability, content richness,
+  // and T549 source multiplier.
+  const qualityScore = computeLearningQuality({
+    confidence: params.confidence,
+    actionable: params.actionable ?? false,
+    insight: params.insight.trim(),
+    application: params.application ?? null,
+    sourceConfidence,
+    memoryTier,
+  });
+
   // Create new entry
   const entry = {
     id: generateLearningId(),
@@ -76,10 +137,29 @@ export async function storeLearning(projectRoot: string, params: StoreLearningPa
     actionable: params.actionable ?? false,
     application: params.application ?? null,
     applicableTypesJson: params.applicableTypes ? JSON.stringify(params.applicableTypes) : '[]',
-    extractedAt: now,
+    qualityScore,
+    // T549 Wave 1-A: tier/type/confidence assigned at write time
+    memoryTier,
+    memoryType,
+    sourceConfidence,
+    verified,
   };
 
   const saved = await accessor.addLearning(entry);
+
+  // Auto-populate graph node for the new learning (best-effort, T537).
+  upsertGraphNode(
+    projectRoot,
+    `learning:${saved.id}`,
+    'learning',
+    saved.insight.substring(0, 200),
+    qualityScore,
+    saved.insight + (saved.application ?? ''),
+    { source: saved.source, confidence: saved.confidence, actionable: saved.actionable },
+  ).catch(() => {
+    /* best-effort */
+  });
+
   return {
     ...saved,
     applicableTypes: JSON.parse(saved.applicableTypesJson || '[]'),

package/src/memory/patterns.ts

@@ -12,6 +12,8 @@
 
 import { randomBytes } from 'node:crypto';
 import { getBrainAccessor } from '../store/brain-accessor.js';
+import { upsertGraphNode } from './graph-auto-populate.js';
+import { computePatternQuality } from './quality-scoring.js';
 
 /** Pattern types from ADR-009. */
 export type PatternType = 'workflow' | 'blocker' | 'success' | 'failure' | 'optimization';
@@ -29,6 +31,12 @@ export interface StorePatternParams {
   mitigation?: string;
   examples?: string[];
   successRate?: number;
+  /**
+   * T549 Wave 1-A: origin of this pattern.
+   * Used to route sourceConfidence at write time.
+   * Values starting with 'auto' map to 'speculative'; otherwise 'agent'.
+   */
+  source?: string;
 }
 
 /** Parameters for searching patterns. */
@@ -53,34 +61,88 @@ function generatePatternId(): string {
  * @task T4768, T5241
  */
 export async function storePattern(projectRoot: string, params: StorePatternParams) {
-  if (!params.pattern || !params.pattern.trim()) {
+  if (!params.pattern?.trim()) {
     throw new Error('Pattern description is required');
   }
-  if (!params.context || !params.context.trim()) {
+  if (!params.context?.trim()) {
     throw new Error('Pattern context is required');
   }
 
   const accessor = await getBrainAccessor(projectRoot);
 
-  // First search for duplicate pattern
-  // Currently we just match on type and exact text
+  // Search for duplicate pattern by normalized text within same type
   const existingPatterns = await accessor.findPatterns({ type: params.type });
+  const normalizedInput = params.pattern.trim().toLowerCase();
   const duplicate = existingPatterns.find(
-    (e) => e.pattern.toLowerCase() === params.pattern.toLowerCase(),
+    (e) => e.pattern.trim().toLowerCase() === normalizedInput,
   );
 
   const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
 
   if (duplicate) {
-    // We would ideally increment frequency here
-    // However, accessor.addPattern handles inserts. Let's just insert it again or
-    // we would need an update method on accessor.
-    // For now, since accessor.updatePattern might not exist, we just insert.
-    // Let's assume brain accessor should support updating, or we'll just add it.
-    // Wait, let's look if accessor has updatePattern. If not, we just insert anew? No, we should update.
-    // Actually, brain.db is meant to store new records or update them. Let's check accessor again.
+    // Merge examples arrays (union of task IDs)
+    const existingExamples: string[] = JSON.parse(duplicate.examplesJson || '[]');
+    const newExamples: string[] = params.examples ?? [];
+    const mergedExamples = Array.from(new Set([...existingExamples, ...newExamples]));
+
+    await accessor.updatePattern(duplicate.id, {
+      frequency: duplicate.frequency + 1,
+      extractedAt: now,
+      examplesJson: JSON.stringify(mergedExamples),
+    });
+
+    const updated = await accessor.getPattern(duplicate.id);
+
+    // Refresh graph node for the updated (incremented) pattern (best-effort, T537).
+    upsertGraphNode(
+      projectRoot,
+      `pattern:${duplicate.id}`,
+      'pattern',
+      duplicate.pattern.substring(0, 200),
+      duplicate.qualityScore ?? 0.5,
+      duplicate.pattern + duplicate.context,
+      {
+        type: duplicate.type,
+        impact: duplicate.impact ?? undefined,
+        frequency: duplicate.frequency + 1,
+      },
+    ).catch(() => {
+      /* best-effort */
+    });
+
+    return {
+      ...updated!,
+      examples: mergedExamples,
+    };
   }
 
+  // T549 Wave 1-A: Tier routing for patterns.
+  // Patterns are medium-term procedural entries — they describe how things work.
+  // sourceConfidence routing (spec §4.1 Decision Tree):
+  //   - source starts with 'auto' → 'speculative' (auto-extracted, unconfirmed)
+  //   - otherwise → 'agent' (agent-observed during work)
+  // memoryTier = 'medium' (patterns have more than one observation and are project-scoped)
+  // memoryType = 'procedural' (patterns are always process knowledge)
+  // verified = false (patterns need validation through repetition, not boolean gate)
+  const memoryTier = 'medium' as const;
+  const memoryType = 'procedural' as const;
+  const sourceConfidence = params.source?.startsWith('auto')
+    ? ('speculative' as const)
+    : ('agent' as const);
+  const verified = false;
+
+  // Compute quality score based on type, content richness, examples,
+  // and T549 source multiplier.
+  const examplesJson = params.examples ? JSON.stringify(params.examples) : '[]';
+  const qualityScore = computePatternQuality({
+    type: params.type,
+    pattern: params.pattern.trim(),
+    context: params.context.trim(),
+    examples_json: examplesJson,
+    sourceConfidence,
+    memoryTier,
+  });
+
   // Create new entry
   const entry = {
     id: generatePatternId(),
@@ -92,11 +154,31 @@ export async function storePattern(projectRoot: string, params: StorePatternPara
     impact: params.impact ?? null,
     antiPattern: params.antiPattern ?? null,
     mitigation: params.mitigation ?? null,
-    examplesJson: params.examples ? JSON.stringify(params.examples) : '[]',
+    examplesJson,
     extractedAt: now,
+    qualityScore,
+    // T549 Wave 1-A: tier/type/confidence assigned at write time
+    memoryTier,
+    memoryType,
+    sourceConfidence,
+    verified,
   };
 
   const saved = await accessor.addPattern(entry);
+
+  // Auto-populate graph node for the new pattern (best-effort, T537).
+  upsertGraphNode(
+    projectRoot,
+    `pattern:${saved.id}`,
+    'pattern',
+    saved.pattern.substring(0, 200),
+    qualityScore,
+    saved.pattern + saved.context,
+    { type: saved.type, impact: saved.impact ?? undefined },
+  ).catch(() => {
+    /* best-effort */
+  });
+
   return {
     ...saved,
     examples: JSON.parse(saved.examplesJson || '[]'),

package/src/memory/quality-scoring.ts

@@ -0,0 +1,257 @@
+/**
+ * Quality scoring for CLEO BRAIN memory entries.
+ *
+ * Computes a 0.0–1.0 quality score at insert time for each typed brain table entry.
+ * Entries with a score below the minimum threshold are excluded from search results.
+ *
+ * Score formula per CA1 spec Section 3: source reliability * content richness * recency signals.
+ * Each helper clamps the result to [0.0, 1.0].
+ *
+ * T549 Wave 1-B: source confidence multipliers and memory tier bonuses are applied
+ * on top of the existing base formulas. The base formulas are unchanged; the
+ * multiplier and tier bonus are additive final transforms.
+ *
+ * Exported for use in backfill (T530) and future scoring hooks.
+ *
+ * @task T531 T549
+ * @epic T523
+ */
+
+import type { BrainMemoryTier, BrainSourceConfidence } from '../store/brain-schema.js';
+
+/** Minimum quality score for inclusion in search results. */
+export const QUALITY_SCORE_THRESHOLD = 0.3;
+
+// ============================================================================
+// T549: Source Confidence Multipliers
+// ============================================================================
+
+/**
+ * Quality multiplier per source confidence level (T549 §3.1.5 and §5.3).
+ *
+ * Applied as a final multiplicative transform on top of the existing base score.
+ * Separate from content richness — captures trustworthiness of the source.
+ *
+ * | Level         | Meaning                                 | Multiplier |
+ * |---------------|-----------------------------------------|------------|
+ * | owner         | Owner explicitly stated this fact       | 1.0        |
+ * | task-outcome  | Verified by completed task with result  | 0.90       |
+ * | agent         | Agent-inferred during work (default)    | 0.70       |
+ * | speculative   | Agent hypothesis, not yet corroborated  | 0.40       |
+ */
+const SOURCE_MULTIPLIERS: Record<BrainSourceConfidence, number> = {
+  owner: 1.0,
+  'task-outcome': 0.9,
+  agent: 0.7,
+  speculative: 0.4,
+};
+
+/**
+ * Tier bonus applied after the source multiplier (T549 Wave 1-B).
+ *
+ * Short-term entries get no bonus (they are new and unproven).
+ * Medium-term entries get a small bonus (survived session consolidation).
+ * Long-term entries get a larger bonus (architecturally proven).
+ */
+const TIER_BONUS: Record<BrainMemoryTier, number> = {
+  short: 0.0,
+  medium: 0.05,
+  long: 0.1,
+};
+
+/**
+ * Apply the source confidence multiplier and optional memory tier bonus.
+ *
+ * This is the final transform in every compute function. It multiplies the
+ * raw content-richness score by the source multiplier, then adds the tier
+ * bonus, then clamps to [0.0, 1.0].
+ *
+ * @param rawScore - Score from the base content-richness formula
+ * @param sourceConfidence - Source reliability level (defaults to 'agent')
+ * @param memoryTier - Memory retention tier (defaults to 'short' = no bonus)
+ */
+export function applySourceMultiplier(
+  rawScore: number,
+  sourceConfidence: BrainSourceConfidence = 'agent',
+  memoryTier: BrainMemoryTier = 'short',
+): number {
+  const multiplied = rawScore * SOURCE_MULTIPLIERS[sourceConfidence];
+  const withTierBonus = multiplied + TIER_BONUS[memoryTier];
+  return clamp(withTierBonus);
+}
+
+// ============================================================================
+// Pattern quality
+// ============================================================================
+
+/** Input shape for pattern quality computation — mirrors StorePatternParams. */
+export interface PatternQualityInput {
+  type: string;
+  pattern: string;
+  context?: string | null;
+  examples_json?: string | null;
+  /** T549: source reliability level — applies multiplier on top of base score. */
+  sourceConfidence?: BrainSourceConfidence;
+  /** T549: memory retention tier — applies tier bonus on top of multiplied score. */
+  memoryTier?: BrainMemoryTier;
+}
+
+/**
+ * Compute quality score for a brain_patterns row.
+ *
+ * Base: 0.4 (auto-generated patterns start lower).
+ * Bonuses:
+ *   +0.10 for 'workflow' type (structured operational knowledge)
+ *   +0.05 for 'success' type (validated positive pattern)
+ *   +0.10 if pattern text exceeds 100 chars (richer description)
+ *   +0.10 if context exceeds 50 chars (contextual detail present)
+ *   +0.10 if examples_json contains more than 3 items (empirically validated)
+ *
+ * T549 Wave 1-B: raw score is then multiplied by the source confidence multiplier
+ * and the memory tier bonus is added. Result clamped to [0.0, 1.0].
+ */
+export function computePatternQuality(params: PatternQualityInput): number {
+  let score = 0.4;
+
+  if (params.type === 'workflow') score += 0.1;
+  if (params.type === 'success') score += 0.05;
+
+  if (params.pattern.length > 100) score += 0.1;
+  if (params.context && params.context.length > 50) score += 0.1;
+
+  if (params.examples_json) {
+    try {
+      const examples = JSON.parse(params.examples_json) as unknown[];
+      if (Array.isArray(examples) && examples.length > 3) score += 0.1;
+    } catch {
+      // Malformed JSON — no bonus
+    }
+  }
+
+  return applySourceMultiplier(score, params.sourceConfidence, params.memoryTier);
+}
+
+// ============================================================================
+// Learning quality
+// ============================================================================
+
+/** Input shape for learning quality computation — mirrors StoreLearningParams. */
+export interface LearningQualityInput {
+  confidence: number;
+  actionable?: boolean | null;
+  insight: string;
+  application?: string | null;
+  /** T549: source reliability level — applies multiplier on top of base score. */
+  sourceConfidence?: BrainSourceConfidence;
+  /** T549: memory retention tier — applies tier bonus on top of multiplied score. */
+  memoryTier?: BrainMemoryTier;
+}
+
+/**
+ * Compute quality score for a brain_learnings row.
+ *
+ * Base: confidence value (already 0.0–1.0, caller-provided).
+ * Bonuses:
+ *   +0.10 if actionable (directly applicable guidance)
+ *   +0.10 if insight text exceeds 100 chars (detailed insight)
+ *   +0.10 if application exceeds 20 chars (concrete application context)
+ *
+ * T549 Wave 1-B: raw score is then multiplied by the source confidence multiplier
+ * and the memory tier bonus is added. Result clamped to [0.0, 1.0].
+ */
+export function computeLearningQuality(params: LearningQualityInput): number {
+  let score = params.confidence ?? 0.5;
+
+  if (params.actionable) score += 0.1;
+  if (params.insight.length > 100) score += 0.1;
+  if (params.application && params.application.length > 20) score += 0.1;
+
+  return applySourceMultiplier(score, params.sourceConfidence, params.memoryTier);
+}
+
+// ============================================================================
+// Decision quality
+// ============================================================================
+
+/** Input shape for decision quality computation — mirrors StoreDecisionParams. */
+export interface DecisionQualityInput {
+  confidence: 'low' | 'medium' | 'high';
+  rationale?: string | null;
+  contextTaskId?: string | null;
+  /** T549: source reliability level — applies multiplier on top of base score. */
+  sourceConfidence?: BrainSourceConfidence;
+  /** T549: memory retention tier — applies tier bonus on top of multiplied score. */
+  memoryTier?: BrainMemoryTier;
+}
+
+/** Numeric value map from confidence level. */
+const CONFIDENCE_SCORE_MAP: Record<'low' | 'medium' | 'high', number> = {
+  high: 0.9,
+  medium: 0.7,
+  low: 0.5,
+};
+
+/**
+ * Compute quality score for a brain_decisions row.
+ *
+ * Base: mapped from confidence level (high=0.9, medium=0.7, low=0.5).
+ * Bonuses:
+ *   +0.10 if rationale exceeds 50 chars (substantiated reasoning)
+ *   +0.05 if linked to a specific task (anchored in real work)
+ *
+ * T549 Wave 1-B: raw score is then multiplied by the source confidence multiplier
+ * and the memory tier bonus is added. Result clamped to [0.0, 1.0].
+ */
+export function computeDecisionQuality(params: DecisionQualityInput): number {
+  let score = CONFIDENCE_SCORE_MAP[params.confidence] ?? 0.5;
+
+  if (params.rationale && params.rationale.length > 50) score += 0.1;
+  if (params.contextTaskId) score += 0.05;
+
+  return applySourceMultiplier(score, params.sourceConfidence, params.memoryTier);
+}
+
+// ============================================================================
+// Observation quality
+// ============================================================================
+
+/** Input shape for observation quality computation — mirrors ObserveBrainParams. */
+export interface ObservationQualityInput {
+  text: string;
+  title?: string | null;
+  /** T549: source reliability level — applies multiplier on top of base score. */
+  sourceConfidence?: BrainSourceConfidence;
+  /** T549: memory retention tier — applies tier bonus on top of multiplied score. */
+  memoryTier?: BrainMemoryTier;
+}
+
+/**
+ * Compute quality score for a brain_observations row.
+ *
+ * Base: 0.6 (manual observations start higher than auto-extracted entries).
+ * Bonuses:
+ *   +0.10 if text exceeds 200 chars (rich narrative)
+ *   +0.05 if title exceeds 10 chars (meaningful label)
+ *
+ * T549 Wave 1-B: raw score is then multiplied by the source confidence multiplier
+ * and the memory tier bonus is added. Result clamped to [0.0, 1.0].
+ */
+export function computeObservationQuality(params: ObservationQualityInput): number {
+  let score = 0.6;
+
+  if (params.text && params.text.length > 200) score += 0.1;
+  if (params.title && params.title.length > 10) score += 0.05;
+
+  return applySourceMultiplier(score, params.sourceConfidence, params.memoryTier);
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Clamp a score to the valid [0.0, 1.0] range.
+ */
+function clamp(score: number): number {
+  return Math.min(1.0, Math.max(0.0, score));
+}