@cachly-dev/mcp-server 0.5.5 → 0.5.7

package/dist/index.js

@@ -62,6 +62,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) {
+    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, ageDays) {
+    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 = {
+    '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) {
     return createHash('md5').update(text).digest('hex').slice(0, 12);
@@ -1142,7 +1175,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',
@@ -1181,7 +1216,9 @@ const TOOLS = [
         name: 'recall_best_solution',
         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',
@@ -2219,21 +2256,50 @@ async function handleTool(name, args) {
             const { instance_id, topic, outcome, what_worked, what_failed = '', context: ctx = '', severity = 'major', file_paths = [], commands = [], tags = [], } = args;
             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 = [];
+            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);
-                        recallCount = (prev.recall_count ?? 0); // preserve existing recall count
-                        isUpdate = true;
+            let auditTrail = [];
+            const existingRaw = await redis.get(`cachly:lesson:best:${topic}`);
+            if (existingRaw) {
+                try {
+                    const prev = JSON.parse(existingRaw);
+                    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 = [];
+                    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 */ }
                 }
+                catch { /* ignore parse error */ }
+            }
+            else {
+                auditTrail = [{ ts, action: 'created' }];
             }
-            const lesson = JSON.stringify({
+            const lessonObj = {
                 topic,
                 outcome,
                 what_worked,
@@ -2245,15 +2311,30 @@ async function handleTool(name, args) {
                 tags,
                 recall_count: recallCount,
                 ts,
-                version: 2,
-            });
-            // Always append to the history list
+                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 (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';
@@ -2268,8 +2349,9 @@ async function handleTool(name, args) {
                 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');
         }
         case 'recall_best_solution': {
@@ -2279,12 +2361,35 @@ async function handleTool(name, args) {
             const best = await redis.get(`cachly:lesson:best:${topic}`);
             if (best) {
                 const lesson = JSON.parse(best);
-                // Increment recall_count
-                const updatedLesson = { ...lesson, recall_count: (lesson.recall_count ?? 0) + 1 };
+                // ── 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,
+                };
                 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.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}` : '',
@@ -2292,6 +2397,8 @@ async function handleTool(name, args) {
                     (lesson.file_paths ?? []).length > 0 ? `**Files:** ${(lesson.file_paths ?? []).map((f) => `\`${f}\``).join(', ')}` : '',
                     (lesson.commands ?? []).length > 0 ? `**Commands:** ${(lesson.commands ?? []).map((c) => `\`${c}\``).join(', ')}` : '',
                     (lesson.tags ?? []).length > 0 ? `**Tags:** ${(lesson.tags ?? []).map((t) => `#${t}`).join(' ')}` : '',
+                    auditSummary,
+                    suggestPin,
                 ].filter(l => l !== '').join('\n');
             }
             // Partial match: scan all lesson keys for topic substring
@@ -2527,13 +2634,56 @@ async function handleTool(name, args) {
                 ? lessons.filter(l => focusTerms.some(term => l.topic.toLowerCase().includes(term) ||
                     (l.tags ?? []).some((t) => t.toLowerCase().includes(term))))
                 : [];
-            // 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) : 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,
             }), 'EX', 86400); // auto-expire after 24h if session_end never called
             // ── Build briefing ──────────────────────────────────────────────────────
             const lines = ['🧠 **Session Briefing**', ''];
+            if (streakMessage)
+                lines.push(streakMessage, '');
             // Handoff from previous window (if any)
             const handoffRaw = await redis.get('cachly:session:handoff');
             if (handoffRaw) {
@@ -2611,6 +2761,36 @@ async function handleTool(name, args) {
                 }
                 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;
+            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');
         }
         // ── session_end ───────────────────────────────────────────────────────────
@@ -2628,12 +2808,21 @@ async function handleTool(name, args) {
                 }
                 catch { /* ignore */ }
             }
+            // ── Session Replay: capture decision log ─────────────────────────────
+            let decisionLog = [];
+            try {
+                const dlEntries = await redis.lrange('cachly:session:decision-log', 0, -1);
+                decisionLog = dlEntries.map(e => JSON.parse(e));
+                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"
             await redis.set('cachly:session:last', JSON.stringify(sessionRecord));
@@ -3000,6 +3189,10 @@ async function handleTool(name, args) {
             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;
             if (lessonKeys.length >= 5)
@@ -3017,10 +3210,14 @@ async function handleTool(name, args) {
             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);
                 const ageStr = ageMin < 60 ? `${ageMin}m` : ageMin < 1440 ? `${Math.round(ageMin / 60)}h` : `${Math.round(ageMin / 1440)}d`;
@@ -3041,6 +3238,13 @@ async function handleTool(name, args) {
             if (openFailures.length > 0) {
                 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`);
             }