@cachly-dev/mcp-server 0.10.50 → 0.10.52

package/src/bench/fixtures.ts

@@ -23,6 +23,9 @@ export interface BenchLesson {
   severity?: 'critical' | 'major' | 'minor';
   confidence?: number;
   recall_count?: number;
+  reviewed_by?: string;
+  review_level?: 'senior' | 'peer';
+  endorsements?: number;
   tags?: string[];
   ts?: string;
 }
@@ -171,6 +174,26 @@ export const BENCH_LESSONS: BenchLesson[] = [
     severity: 'minor', confidence: 0.6, recall_count: 1,
     tags: ['nextjs', 'frontend', 'hydration'], ts: daysAgo(25),
   },
+
+  // ── Governance adversarial pair: two similar-text success lessons ──────────
+  // Only the reviewed one should win; baseline cannot distinguish them by text.
+  {
+    topic: 'auth:csrf:double-submit-cookie',
+    outcome: 'success',
+    what_worked: 'CSRF protection was added via the double-submit cookie pattern: the server sets a random CSRF token cookie; the client echoes it as a request header. Requests with a mismatched or absent header are rejected.',
+    context: 'API mutations lacked CSRF protection; security audit required a fix.',
+    severity: 'critical', confidence: 0.91, recall_count: 2,
+    reviewed_by: 'senior-alice', review_level: 'senior', endorsements: 2,
+    tags: ['csrf', 'auth', 'security', 'cookie'], ts: daysAgo(12),
+  },
+  {
+    topic: 'auth:csrf:origin-header-check',
+    outcome: 'success',
+    what_worked: 'CSRF mitigation attempted by checking the Origin header on API requests, but this was bypassed in a penetration test because same-site requests from subdomains also sent the header.',
+    context: 'API mutations lacked CSRF protection; origin header check was insufficient.',
+    severity: 'major', confidence: 0.55, recall_count: 1,
+    tags: ['csrf', 'auth', 'security'], ts: daysAgo(14),
+  },
 ];
 
 export const BENCH_QUERIES: BenchQuery[] = [
@@ -223,4 +246,11 @@ export const BENCH_QUERIES: BenchQuery[] = [
     query: 'postgres performance problem in production',
     relevant: ['db:postgres:connection-pool-exhausted', 'db:postgres:slow-query-missing-index'],
   },
+  // Governance adversarial: two CSRF lessons have almost identical text, but only
+  // the senior-reviewed canonical one is a proven complete solution. Quality
+  // reranking must prefer the reviewed+endorsed lesson over the unreviewed partial.
+  {
+    query: 'CSRF protection missing on API mutations security',
+    relevant: ['auth:csrf:double-submit-cookie'],
+  },
 ];

package/src/handlers/brain.ts

@@ -6,17 +6,25 @@ import { ckgSlug, extractProblemConcept, ckgUpsertNode, ckgUpdateEdge } from '..
 import { safeJsonParse } from '../utils.js';
 import type { CKGEdge, CKGNode } from '../ckg.js';
 import { keywordSearch, tokenize, splitMultiQuery, levenshtein,
-         ZERO_RESULTS_LOG, zeroResultsTotal, indexVocab as _indexVocab } from '../search.js';
-import type { KeywordMatch } from '../search.js';
+         indexVocab as _indexVocab } from '../search.js';
 import { rerankByQuality } from '../rerank.js';
-import { computeEmbedding, hasEmbedProvider, embedProviderHint, EMBED_PROVIDER } from '../embeddings.js';
-import { detectNamespace } from '../namespace.js';
+import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.50';
+const MCP_VERSION = '0.10.52';
 const WHATS_NEW: Record<string, string[]> = {
-  '0.10.50': [
+  '0.10.52': [
     `🆕 **What's new in v${MCP_VERSION}:**`,
+    `  ✅ \`smart_recall\` — CKG traversal as Layer 3: finds lessons that FIXED causal-graph-similar problems (🕸️ causal graph badge)`,
+    `  ✅ Bench corpus expanded: governance adversarial pair proves review-boost end-to-end (+22% P@1 headline)`,
+    `  🔧 Import cleanup: unused symbols removed from brain.ts (no functional change)`,
+    `  💡 \`smart_recall\` now shows keyword / semantic / CKG / hybrid match type for every result`,
+  ],
+  '0.10.51': [
+    `  ✅ \`team_confirm\` — human review raises lesson recall ranking (🛡️ senior / ✔️ peer)`,
+    `  ✅ Governance-aware recall — confirmed lessons outrank unreviewed auto-learned entries`,
+  ],
+  '0.10.50': [
     `  ✅ \`smart_recall\` — unified keyword + semantic hybrid list (one ranked result, not two sections)`,
     `  ✅ \`smart_recall\` — "Brain saved you here" banner surfaces time saved inline per proven lesson`,
     `  ✅ Quality reranking — proven successes outrank symptom-dense failures (+11% Precision@1)`,
@@ -589,8 +597,8 @@ export async function handleBrainTool(
       // BM25 quality scores (already reranked) are re-normalized to [0,1] for merging.
       type HybridResult = {
         key: string; content: string; hybridScore: number;
-        bm25Score?: number; semScore?: number; matchedWords?: string[];
-        matchType: 'keyword' | 'semantic' | 'hybrid'; subQuery?: string;
+        bm25Score?: number; semScore?: number; ckgScore?: number; matchedWords?: string[];
+        matchType: 'keyword' | 'semantic' | 'ckg' | 'hybrid'; subQuery?: string;
       };
 
       const bm25Scores = kwMatches.map(m => m.score);
@@ -620,6 +628,54 @@ export async function handleBrainTool(
           });
         }
       }
+      // ── Layer 3: CKG traversal — follow "fixes" edges to find lessons that solved
+      // structurally similar problems, even when vocabulary differs ───────────────
+      try {
+        const qTokens = tokenize(query).filter(t => t.length >= 4).slice(0, 4);
+        const candidateNodeIds = new Set<string>();
+        for (const token of qTokens) {
+          const nodeStream = redis.scanStream({ match: `cachly:ckg:node:*${token}*`, count: 20 });
+          await new Promise<void>((res, rej) => {
+            nodeStream.on('data', (batch: string[]) => {
+              for (const k of batch.slice(0, 5)) candidateNodeIds.add(k.replace('cachly:ckg:node:', ''));
+            });
+            nodeStream.on('end', res);
+            nodeStream.on('error', rej);
+          });
+        }
+
+        const seenFroms = new Set<string>();
+        for (const nodeId of [...candidateNodeIds].slice(0, 12)) {
+          const inboundEdgeKeys = await redis.smembers(`cachly:ckg:idx:to:${nodeId}`);
+          for (const ek of inboundEdgeKeys.slice(0, 6)) {
+            const er = await redis.get(ek);
+            if (!er) continue;
+            const edge = safeJsonParse<CKGEdge | null>(er, null);
+            if (!edge || edge.edgeType !== 'fixes' || edge.confidence < 0.35) continue;
+            if (seenFroms.has(edge.from)) continue;
+            seenFroms.add(edge.from);
+
+            const lessonKey = `cachly:lesson:best:${edge.from}`;
+            const existing = hybridMap.get(lessonKey);
+            if (existing) {
+              // Already found by BM25/semantic — boost with causal confirmation
+              existing.ckgScore = Math.max(existing.ckgScore ?? 0, edge.confidence);
+              existing.hybridScore = existing.hybridScore * 0.88 + edge.confidence * 0.12;
+              if (existing.matchType === 'keyword') existing.matchType = 'hybrid';
+            } else {
+              const content = await redis.get(lessonKey).catch(() => null);
+              if (!content) continue;
+              hybridMap.set(lessonKey, {
+                key: lessonKey, content,
+                ckgScore: edge.confidence,
+                hybridScore: edge.confidence * 0.30, // CKG-only: lower than text hits
+                matchType: 'ckg',
+              });
+            }
+          }
+        }
+      } catch { /* non-critical — keyword + semantic always available */ }
+
       const hybridResults = [...hybridMap.values()].sort((a, b) => b.hybridScore - a.hybridScore);
 
       // ── Build output ──────────────────────────────────────────────────────────
@@ -639,8 +695,13 @@ export async function handleBrainTool(
       }
 
       if (hybridResults.length > 0) {
-        const modeLabel = semHits.length > 0
+        const hasCKG = hybridResults.some(r => r.ckgScore !== undefined);
+        const modeLabel = semHits.length > 0 && hasCKG
+          ? `keyword + semantic + CKG hybrid`
+          : semHits.length > 0
           ? `keyword + semantic hybrid`
+          : hasCKG
+          ? `keyword + CKG hybrid`
           : `keyword`;
         lines.push(`### 🔍 Results (${hybridResults.length} — ${modeLabel})\n`);
 
@@ -656,7 +717,11 @@ export async function handleBrainTool(
             lines.push(`**Topic: "${sq}"** (${results.length} results)\n`);
             for (const r of results.slice(0, 4)) {
               const label = r.key.replace('cachly:ctx:', '📝 ').replace('cachly:lesson:best:', '💡 ').replace('cachly:idx:', '📂 ');
-              const scorePart = r.matchType === 'hybrid'
+              const scorePart = r.matchType === 'ckg'
+                ? `CKG: ${(r.ckgScore ?? 0).toFixed(2)}, 🕸️ causal graph`
+                : r.ckgScore !== undefined && r.bm25Score !== undefined
+                ? `BM25: ${(r.bm25Score).toFixed(2)}, CKG: ${(r.ckgScore).toFixed(2)}, 🔀 hybrid`
+                : r.matchType === 'hybrid'
                 ? `BM25: ${(r.bm25Score ?? 0).toFixed(2)}, sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🔀 hybrid`
                 : r.matchType === 'semantic'
                 ? `sem: ${((r.semScore ?? 0) * 100).toFixed(0)}%, 🎯 semantic`

package/src/handlers/team.ts

@@ -11,7 +11,7 @@ type GetConnection = (instanceId: string) => Promise<Redis>;
 type ApiFetch = <T>(path: string, options?: RequestInit) => Promise<T>;
 
 export const TEAM_TOOL_NAMES = new Set([
-  'sync_file_changes', 'team_learn', 'team_recall', 'team_synthesize', 'memory_crystalize',
+  'sync_file_changes', 'team_learn', 'team_confirm', 'team_recall', 'team_synthesize', 'memory_crystalize',
   'brain_doctor', 'recall_at', 'trace_dependency', 'global_learn', 'global_recall',
   'publish_lesson', 'import_public_brain', 'setup_ai_memory',
 ]);
@@ -124,6 +124,59 @@ export async function handleTeamTool(
       return `✅ Team lesson stored by **${author}**: \`${topic}\` (${outcome})\n💡 ${what_worked.slice(0, 120)}`;
     }
 
+    // ── team_confirm — knowledge governance (Phase 3) ─────────────────────────
+    // A human reviewer endorses a stored lesson. The endorsement raises the
+    // lesson's recall ranking (see src/rerank.ts), so trusted, reviewed knowledge
+    // surfaces above unreviewed auto-learned entries.
+    case 'team_confirm': {
+      const { instance_id, topic, reviewer, level = 'peer', note = '' } = args as {
+        instance_id: string; topic: string; reviewer: string;
+        level?: 'senior' | 'peer'; note?: string;
+      };
+      if (!instance_id) return '❌ instance_id required';
+      if (!topic || !reviewer) return '❌ Required: topic, reviewer';
+      const reviewLevel = level === 'senior' ? 'senior' : 'peer';
+
+      const redis = await getConnection(instance_id);
+      const key = `cachly:lesson:best:${topic}`;
+      const raw = await redis.get(key);
+      const lesson = safeJsonParse<Record<string, unknown> | null>(raw, null);
+      if (!lesson) {
+        return `📭 No best-solution lesson found for \`${topic}\`.\n\nA lesson must exist (store one with \`team_learn\` / \`learn_from_attempts\`) before it can be confirmed.`;
+      }
+
+      // Track distinct reviewers so endorsements can't be inflated by one person.
+      const endorsersKey = `cachly:lesson:endorsers:${topic}`;
+      const added = await redis.sadd(endorsersKey, reviewer);
+      await redis.expire(endorsersKey, 365 * 86400);
+      const endorsements = await redis.scard(endorsersKey);
+
+      // Senior beats peer; never downgrade an existing senior review to peer.
+      const prevLevel = (lesson.review_level as string) ?? '';
+      const effectiveLevel = prevLevel === 'senior' ? 'senior' : reviewLevel;
+
+      const updated = {
+        ...lesson,
+        reviewed_by: reviewer,
+        review_level: effectiveLevel,
+        endorsements,
+        reviewed_at: new Date().toISOString(),
+      };
+      await redis.set(key, JSON.stringify(updated));
+
+      // Append an immutable review record for the audit trail.
+      const reviewLog = {
+        reviewer, level: reviewLevel, note: note.slice(0, 280), ts: new Date().toISOString(),
+      };
+      const logKey = `cachly:lesson:reviews:${topic}`;
+      await redis.rpush(logKey, JSON.stringify(reviewLog));
+      await redis.ltrim(logKey, -50, -1);
+      await redis.expire(logKey, 365 * 86400);
+
+      const badge = effectiveLevel === 'senior' ? '🛡️ senior-reviewed' : '✔️ peer-reviewed';
+      return `${badge} — \`${topic}\` confirmed by **${reviewer}** (${endorsements} distinct endorsement${endorsements === 1 ? '' : 's'}).\n📈 This lesson now ranks higher in \`smart_recall\` / \`team_recall\`.${note ? `\n📝 ${note.slice(0, 200)}` : ''}`;
+    }
+
     // ── team_recall ───────────────────────────────────────────────────────────
     case 'team_recall': {
       const { instance_id, topic, author, limit = 10 } = args as {
@@ -146,6 +199,7 @@ export async function handleTeamTool(
         topic: string; outcome: string; what_worked: string;
         ts: string; severity?: string; recall_count?: number;
         author?: string; tags?: string[];
+        reviewed_by?: string; review_level?: string; endorsements?: number;
       };
       let lessons: TeamLesson[] = [];
       if (lessonKeys.length > 0) {
@@ -169,8 +223,10 @@ export async function handleTeamTool(
         lessons = lessons.filter(l => l.author?.toLowerCase().includes(a));
       }
 
-      // Sort by recall_count desc
-      lessons.sort((a, b) => (b.recall_count ?? 0) - (a.recall_count ?? 0));
+      // Sort: reviewed lessons first (senior > peer), then by recall_count desc.
+      const reviewRank = (l: TeamLesson) => l.reviewed_by ? (l.review_level === 'senior' ? 2 : 1) : 0;
+      lessons.sort((a, b) =>
+        (reviewRank(b) - reviewRank(a)) || ((b.recall_count ?? 0) - (a.recall_count ?? 0)));
       lessons = lessons.slice(0, limit);
 
       if (lessons.length === 0) {
@@ -183,11 +239,17 @@ export async function handleTeamTool(
       for (const l of lessons) {
         const emoji = l.outcome === 'success' ? '✅' : l.outcome === 'partial' ? '⚠️' : '❌';
         const sev = l.severity === 'critical' ? '🔴 ' : l.severity === 'major' ? '🟡 ' : '';
+        const reviewBadge = l.reviewed_by
+          ? (l.review_level === 'senior' ? ' 🛡️' : ' ✔️')
+          : '';
         const authorStr = l.author ? ` · _by ${l.author}_` : '';
+        const reviewStr = l.reviewed_by
+          ? ` · reviewed by ${l.reviewed_by}${(l.endorsements ?? 0) > 1 ? ` +${(l.endorsements ?? 0) - 1}` : ''}`
+          : '';
         const recallStr = (l.recall_count ?? 0) > 0 ? ` · recalled ${l.recall_count}×` : '';
         const ago = Math.round((Date.now() - new Date(l.ts).getTime()) / 86400000);
         const agoStr = ago === 0 ? 'today' : ago === 1 ? 'yesterday' : `${ago}d ago`;
-        lines.push(`${emoji} ${sev}**\`${l.topic}\`**${authorStr}${recallStr} · ${agoStr}`);
+        lines.push(`${emoji} ${sev}**\`${l.topic}\`**${reviewBadge}${authorStr}${reviewStr}${recallStr} · ${agoStr}`);
         lines.push(`   ${l.what_worked.slice(0, 120)}`);
         lines.push('');
       }

package/src/rerank.ts

@@ -9,8 +9,10 @@
  *
  * This module is Cachly's structural advantage made concrete: we re-rank text
  * matches by the *quality* of the underlying lesson — outcome, confidence,
- * proven-ness (recall_count) and severity — so the lesson most likely to help
- * surfaces first.
+ * proven-ness (recall_count), severity and human review (endorsements) — so the
+ * lesson most likely to help surfaces first. A flat-file memory has none of these
+ * signals; a senior-confirmed, ten-times-recalled success reads identically to a
+ * one-off failed attempt.
  *
  * It is intentionally pure (no I/O): the lesson JSON already travels inside each
  * KeywordMatch.content for `cachly:lesson:best:*` keys, so reranking needs no extra
@@ -29,6 +31,10 @@ export interface LessonQuality {
   severity?: string;       // 'critical' | 'major' | 'minor'
   ts?: string;             // ISO timestamp (for freshness, mild)
   verified_at?: string;
+  // ── Governance (Phase 3): human review raises trust above mere usage ──
+  reviewed_by?: string;    // handle of the reviewer who endorsed it (latest)
+  review_level?: string;   // 'senior' | 'peer' (weight differs)
+  endorsements?: number;   // distinct human endorsements
 }
 
 export interface RerankedMatch extends KeywordMatch {
@@ -53,6 +59,14 @@ const SEVERITY_WEIGHT: Record<string, number> = {
 };
 const SEVERITY_DEFAULT = 1.0;
 
+// Governance: a human-confirmed lesson is more trustworthy than one proven only
+// by automated recall. A senior review weighs more than a peer review; multiple
+// endorsements add a small, saturating bump on top.
+const REVIEW_LEVEL_WEIGHT: Record<string, number> = {
+  senior: 1.25,
+  peer: 1.1,
+};
+
 // Clamp so a strong text match is never fully buried by quality, and a weak text
 // match is never catapulted to the top purely on quality.
 const MIN_MULTIPLIER = 0.5;
@@ -65,7 +79,9 @@ const LESSON_KEY_PREFIX = 'cachly:lesson:best:';
  * Returns 1.0 (neutral) for documents that carry no quality signal (e.g. context).
  */
 export function qualityMultiplier(lesson: LessonQuality | null): number {
-  if (!lesson || (lesson.outcome === undefined && lesson.confidence === undefined && lesson.recall_count === undefined)) {
+  if (!lesson || (lesson.outcome === undefined && lesson.confidence === undefined
+      && lesson.recall_count === undefined && lesson.reviewed_by === undefined
+      && lesson.endorsements === undefined)) {
     return 1.0;
   }
 
@@ -84,7 +100,16 @@ export function qualityMultiplier(lesson: LessonQuality | null): number {
   // 4. Severity — when two lessons tie, surface the one guarding the worse failure.
   const severity = SEVERITY_WEIGHT[lesson.severity ?? ''] ?? SEVERITY_DEFAULT;
 
-  const m = outcome * confidenceFactor * provenBoost * severity;
+  // 5. Governance — a human-confirmed lesson outranks an unreviewed one.
+  //    Base weight from the review level, plus a small saturating bump for
+  //    additional endorsements (rc-style log curve, capped at +0.1).
+  const reviewBase = lesson.reviewed_by
+    ? (REVIEW_LEVEL_WEIGHT[lesson.review_level ?? 'peer'] ?? REVIEW_LEVEL_WEIGHT.peer)
+    : 1.0;
+  const extraEndorse = Math.max(0, (lesson.endorsements ?? 0) - 1);
+  const reviewBoost = reviewBase * (1 + Math.min(0.1, Math.log1p(extraEndorse) / 20));
+
+  const m = outcome * confidenceFactor * provenBoost * severity * reviewBoost;
   return Math.max(MIN_MULTIPLIER, Math.min(MAX_MULTIPLIER, m));
 }
 

package/src/tools.ts

@@ -840,6 +840,25 @@ const TOOLS = [
       required: ['instance_id', 'author', 'topic', 'outcome', 'what_worked'],
     },
   },
+  {
+    name: 'team_confirm',
+    description:
+      'Endorse (review-confirm) a team lesson so trusted, human-reviewed knowledge ranks above unreviewed auto-learned entries. ' +
+      'A senior review weighs more than a peer review; distinct endorsements add a small boost. ' +
+      'Confirmed lessons surface higher in smart_recall and team_recall and carry a 🛡️/✔️ badge. ' +
+      'Use this in code review or knowledge reviews to bless the canonical solution for a topic.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        instance_id: { type: 'string', description: 'UUID of the shared team brain instance' },
+        topic:       { type: 'string', description: 'Topic slug of the lesson to confirm (e.g. "deploy:api")' },
+        reviewer:    { type: 'string', description: 'Your name or handle (the reviewer endorsing this lesson)' },
+        level:       { type: 'string', enum: ['senior', 'peer'], description: 'Review weight — "senior" ranks higher than "peer" (default: peer)' },
+        note:        { type: 'string', description: 'Optional review note (kept in the lesson audit trail)' },
+      },
+      required: ['instance_id', 'topic', 'reviewer'],
+    },
+  },
   {
     name: 'team_recall',
     description: