@cachly-dev/mcp-server 0.5.5 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "MCP server – manage cachly.dev instances from any AI assistant (Copilot, Claude, Cursor, Windsurf)",
   "type": "module",
   "bin": {

package/src/index.ts

@@ -71,6 +71,39 @@ const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
  */
 const EMBED_PROVIDER = (process.env.CACHLY_EMBED_PROVIDER ?? detectEmbedProvider()).toLowerCase();
 
+// ── Confidence Decay Config (all values configurable via env) ─────────────────
+const CONFIDENCE_WARN_DAYS  = Number(process.env.CACHLY_CONFIDENCE_WARN_DAYS  ?? 5);   // → 0.7
+const CONFIDENCE_STALE_DAYS = Number(process.env.CACHLY_CONFIDENCE_STALE_DAYS ?? 10);  // → 0.5
+const CONFIDENCE_WARN_VALUE  = 0.7;
+const CONFIDENCE_STALE_VALUE = 0.5;
+
+/** Calculate current confidence for a lesson based on how long since last verified. */
+function calculateConfidence(lesson: { verified_at?: string; ts: string; recall_count?: number }): number {
+  const ref = lesson.verified_at ?? lesson.ts;
+  const ageMs = Date.now() - new Date(ref).getTime();
+  const ageDays = ageMs / 86400000;
+  if (ageDays >= CONFIDENCE_STALE_DAYS) return CONFIDENCE_STALE_VALUE;
+  if (ageDays >= CONFIDENCE_WARN_DAYS)  return CONFIDENCE_WARN_VALUE;
+  // Linear interpolation between fresh (1.0) and warn threshold
+  return 1.0 - (ageDays / CONFIDENCE_WARN_DAYS) * (1.0 - CONFIDENCE_WARN_VALUE);
+}
+
+/** Render a confidence badge string. */
+function confidenceBadge(confidence: number, ageDays: number): string {
+  if (confidence >= 0.9) return '✅';
+  if (confidence >= 0.7) return `⚠️ (${Math.round(ageDays)}d old, confidence ${(confidence * 100).toFixed(0)}% — verify before applying)`;
+  return `🔴 STALE (${Math.round(ageDays)}d old, confidence ${(confidence * 100).toFixed(0)}% — likely outdated!)`;
+}
+
+/** Category-specific required fields for structured lessons. */
+const STRUCTURED_TEMPLATES: Record<string, { required: string[]; hint: string }> = {
+  'deploy':  { required: ['commands'],                hint: 'deploy:* needs commands[]' },
+  'bash':    { required: ['commands'],                hint: 'bash:* needs commands[]' },
+  'infra':   { required: ['commands'],                hint: 'infra:* needs commands[] + verified on real system' },
+  'pricing': { required: [],                          hint: 'pricing:* — add context with source (e.g. "Stripe Dashboard Apr 2026")' },
+  'stripe':  { required: [],                          hint: 'stripe:* — add context with Stripe API version' },
+};
+
 /** Fast content hash for index invalidation (not cryptographic, just change detection) */
 function simpleHash(text: string): string {
   return createHash('md5').update(text).digest('hex').slice(0, 12);
@@ -1277,7 +1310,9 @@ const TOOLS = [
       'Fields: topic (short slug like "deploy:web"), outcome ("success"|"failure"), ' +
       'what_worked (what solved it), what_failed (what did NOT work), context (extra details). ' +
       'Supports structured metadata: severity, file_paths (files involved), commands (working commands), tags. ' +
-      'Deduplication: if a lesson for this topic already exists, it is updated instead of duplicated. ' +
+      'Deduplication: if a lesson for this topic already exists, it is updated with full audit trail. ' +
+      'Contradiction detection: warns if new outcome conflicts with existing lesson outcome. ' +
+      'Confidence: lesson starts at 1.0, decays after 5d (→0.7) and 10d (→0.5) without recall. ' +
       'Example: learn_from_attempts(topic="deploy:api", outcome="success", what_worked="nohup docker compose up -d --build", what_failed="docker compose up hangs on SSH timeout", severity="critical", commands=["nohup docker compose up -d --build"])',
     inputSchema: {
       type: 'object',
@@ -1317,7 +1352,9 @@ const TOOLS = [
     description:
       'Recall the best known solution for a topic from past lessons. ' +
       'Call this BEFORE attempting any task that might have been done before. ' +
-      'Returns the most recent successful lesson for the topic, or a summary of attempts. ' +
+      'Returns the most recent successful lesson for the topic, with confidence indicator. ' +
+      '⚠️ badge = lesson is >5d old (verify before applying). 🔴 = >10d old (likely stale!). ' +
+      'Recalling a lesson resets its confidence clock to 1.0 (marks as recently verified). ' +
       'Example: recall_best_solution(topic="deploy:web") → returns the working deploy command.',
     inputSchema: {
       type: 'object',
@@ -2535,21 +2572,59 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       const redis = await getConnection(instance_id);
       const ts = new Date().toISOString();
 
-      // ── Deduplication: check for existing lesson with same topic ─────────────
+      // ── Structured template hints ──────────────────────────────────────────
+      const category = topic.split(':')[0];
+      const template = STRUCTURED_TEMPLATES[category];
+      const templateWarnings: string[] = [];
+      if (template) {
+        for (const req of template.required) {
+          if (req === 'commands' && commands.length === 0) {
+            templateWarnings.push(`📋 ${template.hint}`);
+          }
+        }
+      }
+
+      // ── Deduplication + audit trail ────────────────────────────────────────
       let isUpdate = false;
       let recallCount = 0;
-      if (outcome === 'success') {
-        const existing = await redis.get(`cachly:lesson:best:${topic}`);
-        if (existing) {
-          try {
-            const prev = JSON.parse(existing) as { recall_count?: number };
-            recallCount = (prev.recall_count ?? 0); // preserve existing recall count
-            isUpdate = true;
-          } catch { /* ignore parse error */ }
-        }
+      let auditTrail: Array<{ ts: string; action: string; prev_outcome?: string }> = [];
+      const existingRaw = await redis.get(`cachly:lesson:best:${topic}`);
+      if (existingRaw) {
+        try {
+          const prev = JSON.parse(existingRaw) as {
+            recall_count?: number;
+            outcome?: string;
+            audit_trail?: Array<{ ts: string; action: string; prev_outcome?: string }>;
+          };
+          recallCount = prev.recall_count ?? 0;
+          auditTrail = prev.audit_trail ?? [];
+          auditTrail.push({ ts, action: 'updated', prev_outcome: prev.outcome });
+          if (auditTrail.length > 20) auditTrail = auditTrail.slice(-20);
+          isUpdate = true;
+
+          // ── Contradiction detection ─────────────────────────────────────────
+          const contradictionWarning: string[] = [];
+          if (prev.outcome === 'success' && outcome === 'failure') {
+            contradictionWarning.push(
+              `⚠️ **Contradiction detected!** Existing lesson has outcome: \`success\`, but you're storing \`failure\`.`,
+              `The existing "success" lesson will be preserved. Only the audit trail is updated.`,
+              `If you meant to mark this as failed permanently, store a new lesson with a distinct topic slug.`,
+            );
+          } else if (prev.outcome === 'failure' && outcome === 'success') {
+            contradictionWarning.push(
+              `✅ **Conflict resolved!** Previous lesson was \`failure\` — now overwriting with \`success\`.`,
+            );
+          }
+          if (contradictionWarning.length > 0) {
+            // Store contradiction audit but don't block
+            auditTrail[auditTrail.length - 1].action = 'contradiction-resolved';
+          }
+        } catch { /* ignore parse error */ }
+      } else {
+        auditTrail = [{ ts, action: 'created' }];
       }
 
-      const lesson = JSON.stringify({
+      const lessonObj = {
         topic,
         outcome,
         what_worked,
@@ -2561,18 +2636,32 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         tags,
         recall_count: recallCount,
         ts,
-        version: 2,
-      });
+        verified_at: outcome === 'success' || outcome === 'partial' ? ts : undefined,
+        confidence: 1.0,
+        audit_trail: auditTrail,
+        version: 3,
+      };
+      const lesson = JSON.stringify(lessonObj);
 
-      // Always append to the history list
+      // Always append to the history list (audit log)
       const listKey = `cachly:lessons:${topic}`;
       await redis.rpush(listKey, lesson);
 
-      // Update best key only for success/partial (not for failures)
+      // Update best key for success/partial; for failure only update if no success exists
       if (outcome === 'success' || outcome === 'partial') {
         await redis.set(`cachly:lesson:best:${topic}`, lesson);
+      } else if (!existingRaw) {
+        await redis.set(`cachly:lesson:best:${topic}`, lesson);
       }
 
+      // Track in decision log for session replay
+      try {
+        const dlKey = 'cachly:session:decision-log';
+        const dlEntry = JSON.stringify({ ts, topic, outcome, what_worked: what_worked.slice(0, 120) });
+        await redis.rpush(dlKey, dlEntry);
+        await redis.ltrim(dlKey, -50, -1);
+      } catch { /* non-critical */ }
+
       const emoji = outcome === 'success' ? '✅' : outcome === 'partial' ? '⚠️' : '❌';
       const sevEmoji = severity === 'critical' ? '🔴' : severity === 'major' ? '🟡' : '🟢';
       const action = isUpdate ? 'updated' : 'stored';
@@ -2587,8 +2676,9 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         tags.length > 0 ? `**Tags:** ${tags.map(t => `#${t}`).join(' ')}` : '',
         ``,
         isUpdate
-          ? `♻️ Updated existing lesson (preserved recall count: ${recallCount})`
+          ? `♻️ Updated (recall count: ${recallCount} · audit entries: ${auditTrail.length})`
           : `💡 Recall later with \`recall_best_solution(topic="${topic}")\``,
+        ...templateWarnings,
       ].filter(l => l !== '').join('\n');
     }
 
@@ -2601,16 +2691,45 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       if (best) {
         const lesson = JSON.parse(best) as {
           topic: string; outcome: string; what_worked: string; what_failed?: string;
-          context?: string; ts: string; severity?: string; file_paths?: string[];
-          commands?: string[]; tags?: string[]; recall_count?: number;
+          context?: string; ts: string; verified_at?: string; severity?: string;
+          file_paths?: string[]; commands?: string[]; tags?: string[];
+          recall_count?: number; audit_trail?: unknown[];
+        };
+
+        // ── Confidence decay check ───────────────────────────────────────────
+        const confidence = calculateConfidence(lesson);
+        const ref = lesson.verified_at ?? lesson.ts;
+        const ageDays = (Date.now() - new Date(ref).getTime()) / 86400000;
+        const badge = confidenceBadge(confidence, ageDays);
+
+        // Recall resets verified_at (confidence clock restart)
+        const updatedLesson = {
+          ...lesson,
+          recall_count: (lesson.recall_count ?? 0) + 1,
+          verified_at: new Date().toISOString(),
+          confidence: 1.0,
         };
-        // Increment recall_count
-        const updatedLesson = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1 };
         await redis.set(`cachly:lesson:best:${topic}`, JSON.stringify(updatedLesson));
 
         const sevEmoji = lesson.severity === 'critical' ? '🔴' : lesson.severity === 'major' ? '🟡' : lesson.severity ? '🟢' : '';
+        const auditSummary = (lesson.audit_trail ?? []).length > 1
+          ? `_Audit: ${(lesson.audit_trail ?? []).length} changes · stored ${new Date(lesson.ts).toLocaleDateString('de-DE')}_`
+          : '';
+
+        // "Remember when..." — emotional header for lessons > 60 days old
+        const ageFromStoreDays = (Date.now() - new Date(lesson.ts).getTime()) / 86400000;
+        const rememberWhen = ageFromStoreDays > 60
+          ? `💭 _Remember when you solved this ${Math.round(ageFromStoreDays / 30)} months ago? Still works._`
+          : '';
+
+        // "Never Google This Again" — suggest pinning after 3rd recall
+        const suggestPin = updatedLesson.recall_count === 3 && !(lesson as { pinned?: boolean }).pinned
+          ? `📌 **You've looked this up 3 times.** Consider pinning it for instant access: add \`pinned: true\` via \`learn_from_attempts\` to always surface it first.`
+          : '';
+
         return [
-          `✅ **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}× · ${new Date(lesson.ts).toLocaleDateString('de-DE')}`,
+          rememberWhen,
+          `${badge} **Best solution for \`${topic}\`** ${sevEmoji}${lesson.severity ? ` (${lesson.severity})` : ''} · recalled ${updatedLesson.recall_count}×`,
           ``,
           `**What worked:** ${lesson.what_worked}`,
           lesson.what_failed ? `**What failed (avoid this):** ${lesson.what_failed}` : '',
@@ -2618,6 +2737,8 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
           (lesson.file_paths ?? []).length > 0 ? `**Files:** ${(lesson.file_paths ?? []).map((f: string) => `\`${f}\``).join(', ')}` : '',
           (lesson.commands ?? []).length > 0 ? `**Commands:** ${(lesson.commands ?? []).map((c: string) => `\`${c}\``).join(', ')}` : '',
           (lesson.tags ?? []).length > 0 ? `**Tags:** ${(lesson.tags ?? []).map((t: string) => `#${t}`).join(' ')}` : '',
+          auditSummary,
+          suggestPin,
         ].filter(l => l !== '').join('\n');
       }
 
@@ -2848,7 +2969,8 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       // 2. Fetch all lesson values for recency sorting + focus matching
       type Lesson = {
         topic: string; outcome: string; what_worked: string; what_failed?: string;
-        ts: string; severity?: string; recall_count?: number; tags?: string[];
+        ts: string; verified_at?: string; severity?: string; recall_count?: number;
+        tags?: string[]; confidence?: number; audit_trail?: unknown[];
       };
       const lessons: Lesson[] = [];
       for (const k of lessonKeys) {
@@ -2887,7 +3009,43 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
           )
         : [];
 
-      // 6. Save session start marker
+      // 6. Streak tracking
+      let streakDays = 0;
+      let streakRecord = 0;
+      let streakMessage = '';
+      try {
+        const streakRaw = await redis.get('cachly:streak:current');
+        const streak = streakRaw ? JSON.parse(streakRaw) as { days: number; last_date: string; record: number } : null;
+        const today = new Date().toISOString().slice(0, 10);
+        if (streak) {
+          const lastDate = streak.last_date;
+          const yesterday = new Date(Date.now() - 86400000).toISOString().slice(0, 10);
+          if (lastDate === today) {
+            // Already counted today
+            streakDays = streak.days;
+            streakRecord = streak.record;
+          } else if (lastDate === yesterday) {
+            // Continuing streak
+            streakDays = streak.days + 1;
+            streakRecord = Math.max(streakDays, streak.record);
+            await redis.set('cachly:streak:current', JSON.stringify({ days: streakDays, last_date: today, record: streakRecord }));
+          } else {
+            // Streak broken
+            streakDays = 1;
+            streakRecord = streak.record;
+            await redis.set('cachly:streak:current', JSON.stringify({ days: 1, last_date: today, record: streakRecord }));
+          }
+        } else {
+          // First session ever
+          streakDays = 1;
+          streakRecord = 1;
+          await redis.set('cachly:streak:current', JSON.stringify({ days: 1, last_date: today, record: 1 }));
+        }
+        if (streakDays >= 7) streakMessage = `🔥 **${streakDays}-day streak!** ${streakDays === streakRecord ? ' New record!' : `Best: ${streakRecord}d`}`;
+        else if (streakDays > 1) streakMessage = `🔥 ${streakDays}-day streak`;
+      } catch { /* non-critical */ }
+
+      // 7. Save session start marker
       await redis.set('cachly:session:current', JSON.stringify({
         started: new Date().toISOString(),
         focus,
@@ -2895,6 +3053,7 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
 
       // ── Build briefing ──────────────────────────────────────────────────────
       const lines: string[] = ['🧠 **Session Briefing**', ''];
+      if (streakMessage) lines.push(streakMessage, '');
 
       // Handoff from previous window (if any)
       const handoffRaw = await redis.get('cachly:session:handoff');
@@ -2977,6 +3136,35 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         lines.push('');
       }
 
+      // ── Stale / low-confidence lessons (confidence decay) ─────────────────
+      const staleSuccessLessons = lessons.filter(l => {
+        if (l.outcome !== 'success' && l.outcome !== 'partial') return false;
+        return calculateConfidence(l) < CONFIDENCE_WARN_VALUE;
+      });
+      if (staleSuccessLessons.length > 0) {
+        lines.push(`🔴 **Stale lessons** (not recalled in >${CONFIDENCE_WARN_DAYS}d — verify before applying):`);
+        for (const l of staleSuccessLessons.slice(0, 4)) {
+          const conf = calculateConfidence(l);
+          const ageDays = Math.round((Date.now() - new Date(l.verified_at ?? l.ts).getTime()) / 86400000);
+          const flag = conf < CONFIDENCE_STALE_VALUE ? '🔴' : '⚠️';
+          lines.push(`  ${flag} \`${l.topic}\` — ${ageDays}d stale, ${(conf * 100).toFixed(0)}% confidence`);
+        }
+        lines.push(`  _Run \`recall_best_solution\` on these to reset their confidence clock._`);
+        lines.push('');
+      }
+
+      // ── Session Replay: show last session's decision log ──────────────────
+      const lastSessionAny = lastSession as unknown as { decision_log?: Array<{ topic: string; outcome: string; what_worked: string }> } | null;
+      if (lastSessionAny?.decision_log?.length) {
+        const dl = lastSessionAny.decision_log;
+        const successes = dl.filter(d => d.outcome === 'success');
+        const failures  = dl.filter(d => d.outcome === 'failure');
+        lines.push(`🎬 **Last session decisions** (${dl.length} lessons stored):`);
+        if (successes.length > 0) lines.push(`  ✅ Worked: ${successes.slice(0, 3).map(d => `\`${d.topic}\``).join(', ')}`);
+        if (failures.length > 0)  lines.push(`  ❌ Failed: ${failures.slice(0, 3).map(d => `\`${d.topic}\``).join(', ')}`);
+        lines.push('');
+      }
+
       return lines.join('\n');
     }
 
@@ -3007,12 +3195,21 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         } catch { /* ignore */ }
       }
 
+      // ── Session Replay: capture decision log ─────────────────────────────
+      let decisionLog: Array<{ ts: string; topic: string; outcome: string; what_worked: string }> = [];
+      try {
+        const dlEntries = await redis.lrange('cachly:session:decision-log', 0, -1);
+        decisionLog = dlEntries.map(e => JSON.parse(e) as { ts: string; topic: string; outcome: string; what_worked: string });
+        await redis.del('cachly:session:decision-log');
+      } catch { /* non-critical */ }
+
       const sessionRecord = {
         ts: now.toISOString(),
         summary,
         files_changed,
         ...(lessons_learned !== undefined ? { lessons_learned } : {}),
         ...(durationMin !== undefined ? { duration_min: durationMin } : {}),
+        ...(decisionLog.length > 0 ? { decision_log: decisionLog } : {}),
       };
 
       // Save as "last session"
@@ -3425,12 +3622,15 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       });
 
       // Load lessons for analysis
-      type Lesson = { topic: string; outcome: string; recall_count?: number; ts: string; severity?: string };
-      const lessons: Lesson[] = [];
+      type DrLesson = {
+        topic: string; outcome: string; recall_count?: number; ts: string;
+        verified_at?: string; severity?: string; audit_trail?: unknown[];
+      };
+      const lessons: DrLesson[] = [];
       for (const k of lessonKeys) {
         const raw = await redis.get(k);
         if (!raw) continue;
-        try { lessons.push(JSON.parse(raw) as Lesson); } catch { /* skip */ }
+        try { lessons.push(JSON.parse(raw) as DrLesson); } catch { /* skip */ }
       }
 
       // Last session
@@ -3446,6 +3646,10 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       const unusedLessons = lessons.filter(l => (l.recall_count ?? 0) === 0);
       // Critical lessons
       const criticalLessons = lessons.filter(l => l.severity === 'critical');
+      // Confidence decay analysis
+      const staleLessons  = lessons.filter(l => l.outcome === 'success' && calculateConfidence(l) < CONFIDENCE_STALE_VALUE);
+      const warnLessons   = lessons.filter(l => l.outcome === 'success' && calculateConfidence(l) >= CONFIDENCE_STALE_VALUE && calculateConfidence(l) < CONFIDENCE_WARN_VALUE);
+      const withAudit     = lessons.filter(l => (l.audit_trail ?? []).length > 1);
 
       // Quality score (0-100)
       let score = 50;
@@ -3457,12 +3661,15 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
       if (openFailures.length === 0) score += 5;
       const unusedRatio = lessons.length > 0 ? unusedLessons.length / lessons.length : 0;
       if (unusedRatio < 0.5)       score += 10;
+      if (staleLessons.length === 0) score += 5;
 
       const scoreEmoji = score >= 80 ? '🟢' : score >= 50 ? '🟡' : '🔴';
 
       checks.push(`${scoreEmoji} **Brain Quality Score: ${score}/100**`);
-      checks.push(`📚 **Lessons:** ${lessonKeys.length} (${criticalLessons.length} critical)`);
+      checks.push(`📚 **Lessons:** ${lessonKeys.length} (${criticalLessons.length} critical · ${withAudit.length} with audit trail)`);
       checks.push(`💾 **Context entries:** ${ctxCount}`);
+      checks.push(`🎯 **Confidence:** ${lessons.length - staleLessons.length - warnLessons.length} fresh · ${warnLessons.length} warn · ${staleLessons.length} stale`);
+      checks.push(`⏱️ **Decay config:** warn after ${CONFIDENCE_WARN_DAYS}d · stale after ${CONFIDENCE_STALE_DAYS}d`);
 
       if (lastSession) {
         const ageMin = Math.round((Date.now() - new Date(lastSession.ts).getTime()) / 60000);
@@ -3486,6 +3693,15 @@ async function handleTool(name: string, args: Record<string, unknown>): Promise<
         issues.push(`⚠️ ${openFailures.length} unresolved failure${openFailures.length > 1 ? 's' : ''}: ${openFailures.slice(0, 3).map(l => `\`${l.topic}\``).join(', ')}`);
       }
 
+      if (staleLessons.length > 0) {
+        issues.push(`🔴 ${staleLessons.length} STALE lesson${staleLessons.length > 1 ? 's' : ''} (>${CONFIDENCE_STALE_DAYS}d, confidence <${CONFIDENCE_STALE_VALUE * 100}%): ${staleLessons.slice(0, 3).map(l => `\`${l.topic}\``).join(', ')}`);
+        issues.push(`   → Re-verify with \`recall_best_solution\` to reset confidence clock`);
+      }
+
+      if (warnLessons.length > 0) {
+        issues.push(`⚠️ ${warnLessons.length} lesson${warnLessons.length > 1 ? 's' : ''} aging (>${CONFIDENCE_WARN_DAYS}d): ${warnLessons.slice(0, 3).map(l => `\`${l.topic}\``).join(', ')}`);
+      }
+
       if (unusedRatio > 0.7 && lessons.length > 5) {
         issues.push(`💡 ${unusedLessons.length} lessons never recalled — verify topics match your workflow`);
       }