@cachly-dev/mcp-server 0.10.114 → 0.10.116

package/README.md

@@ -22,11 +22,16 @@
     <img src="https://img.shields.io/badge/GDPR-EU%20servers-green" alt="GDPR: EU servers" />
   </a>
   &nbsp;
-  <img src="https://img.shields.io/badge/136%20MCP%20tools-violet" alt="136 MCP tools" />
+  <img src="https://img.shields.io/badge/140%20MCP%20tools-violet" alt="140 MCP tools" />
   &nbsp;
   <img src="https://img.shields.io/badge/License-Apache--2.0-yellow" alt="License: Apache-2.0" />
 </p>
 
+<p align="center">
+  <strong><a href="https://cachly.dev/sign-up">⚡ Get your free Brain → cachly.dev</a></strong><br/>
+  <sub>Free forever · no credit card · 1-command setup · German servers · GDPR</sub>
+</p>
+
 ---
 
 ## The story you already live every day
@@ -286,7 +291,7 @@ MCP tool — bulk-ingests past outcomes the same way `brain_from_git` ingests co
 
 ---
 
-## MCP Tools (136 total)
+## MCP Tools (140 total)
 
 ### 🧠 Session & Memory (most used)
 

package/dist/src/handlers/brain.js

@@ -7,8 +7,15 @@ import { keywordSearch, tokenize, splitMultiQuery, levenshtein, indexVocab as _i
 import { rerankByQuality } from '../rerank.js';
 import { computeEmbedding, hasEmbedProvider } from '../embeddings.js';
 // ── Changelog (shown once per version in session_start) ──────────────────────
-const MCP_VERSION = '0.10.114';
+const MCP_VERSION = '0.10.115';
 const WHATS_NEW = {
+    '0.10.115': [
+        `🔧 **\`brain_get_pref\` + \`brain_set_pref\` — persistent Brain preferences**`,
+        `  📖 \`brain_get_pref\` reads back any stored preference (omit key to list all).`,
+        `  ✏️ \`brain_set_pref\` saves a preference to Redis — survives restarts, scoped per Brain instance.`,
+        `  💡 Known key: \`auto_changelog\` — set to "false" to silence the new-lessons digest at session_start.`,
+        `  📊 140 MCP tools`,
+    ],
     '0.10.114': [
         `📋 **\`brain_changelog\` — weekly knowledge digest in one call**`,
         `  📅 Generates a grouped Markdown changelog of lessons learned in the last N days.`,
@@ -356,6 +363,7 @@ export const BRAIN_TOOL_NAMES = new Set([
     'brain_who_knows', 'brain_file_map', 'team_expertise_map',
     'skill_gaps', 'brain_coverage', 'brain_metrics', 'brain_service_map',
     'brain_collab_pairs', 'brain_portability', 'brain_changelog',
+    'brain_set_pref', 'brain_get_pref',
 ]);
 // ── Free-tier Teaser-Gate ──────────────────────────────────────────────────
 // When a Free-tier Brain crosses its recall limit, smart_recall still delivers
@@ -364,7 +372,6 @@ export const BRAIN_TOOL_NAMES = new Set([
 // DEPTH gate (hide the tail), never an access wall: the #1 result is always
 // returned. Usage/limit come from the same authoritative numbers as the Brain
 // Health bar (GET /instances/:id/memory), cached briefly to avoid per-call latency.
-const FREE_TIER_VISIBLE_RECALLS = 3;
 const UPGRADE_URL = 'https://cachly.dev/billing';
 const _recallGateCache = new Map();
 async function getRecallGate(instanceId, apiFetch) {
@@ -375,7 +382,12 @@ async function getRecallGate(instanceId, apiFetch) {
         const mem = await apiFetch(`/api/v1/instances/${instanceId}/memory`);
         const limit = mem?.recall_limit ?? -1;
         const used = mem?.total_recall_count ?? 0;
-        const gate = { reached: limit > 0 && used >= limit, limit, used };
+        const gate = {
+            reached: limit > 0 && used >= limit,
+            limit,
+            used,
+            goodwillMessage: mem?.goodwill_message,
+        };
         _recallGateCache.set(instanceId, { gate, expiresAt: Date.now() + 60_000 });
         return gate;
     }
@@ -1089,10 +1101,18 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 .sort((a, b) => b.hybridScore - a.hybridScore);
             // ── Teaser-Gate: free tier over its recall limit hides the long tail ──────
             const recallGate = await getRecallGate(instance_id, apiFetch);
-            const gateActive = recallGate.reached && hybridResults.length > FREE_TIER_VISIBLE_RECALLS;
-            const visibleCount = gateActive ? FREE_TIER_VISIBLE_RECALLS : 8;
+            // Hard gate: once a free user is over their (monthly, goodwill-adjusted)
+            // recall limit, the long tail is fully withheld until they upgrade or the
+            // month resets. We still show the single highest-value proven lesson below
+            // as a teaser so the tool isn't dead and the value is obvious.
+            const gateActive = recallGate.reached;
+            const visibleCount = gateActive ? 0 : 8;
             // ── Build output ──────────────────────────────────────────────────────────
             const lines = [`🧠 **Smart Recall** for: _"${query}"_\n`];
+            // Warm goodwill note — shown the month a free user is gifted +250 recalls.
+            if (recallGate.goodwillMessage) {
+                lines.push(`${recallGate.goodwillMessage}\n`);
+            }
             // "Brain saved you here" banner — surfaces value inline for proven recalled lessons
             const SORDER = { critical: 0, major: 1, minor: 2 };
             const topLesson = savedHere.sort((a, b) => (SORDER[a.severity] ?? 1) - (SORDER[b.severity] ?? 1))[0];
@@ -1140,7 +1160,7 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 // Group by sub-query for multi-topic queries
                 if (subQueries.length > 1) {
                     const grouped = new Map();
-                    for (const r of hybridResults.slice(0, gateActive ? FREE_TIER_VISIBLE_RECALLS : 12)) {
+                    for (const r of hybridResults.slice(0, gateActive ? 0 : 12)) {
                         const sq = r.subQuery ?? query;
                         if (!grouped.has(sq))
                             grouped.set(sq, []);
@@ -1190,12 +1210,12 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                         lines.push(`> ${preview}${r.content.length > 400 ? '…' : ''}\n`);
                     }
                 }
-                // ── Teaser-Gate footer: sell the withheld tail at the moment of need ──
+                // ── Hard gate footer: over the recall limit, the tail is withheld ──────
                 if (gateActive) {
                     const withheld = Math.max(0, hybridResults.length - visibleCount);
-                    if (withheld > 0) {
-                        lines.push(`🔒 **${withheld} more relevant lesson${withheld !== 1 ? 's' : ''} available** — you've reached your Free recall limit (${recallGate.used}/${recallGate.limit}). Unlock your full Brain → ${UPGRADE_URL}\n`);
-                    }
+                    lines.push(`🔒 **Free recall limit reached** (${recallGate.used}/${recallGate.limit} this month). ` +
+                        `${withheld} relevant lesson${withheld !== 1 ? 's' : ''} withheld. ` +
+                        `Your limit resets next month, or unlock your full Brain now → ${UPGRADE_URL}\n`);
                 }
             }
             else {
@@ -2012,6 +2032,49 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     reasons.push('stale lessons');
                 lines.push(`🩺 _Run \`brain_doctor\` to fix: ${reasons.join(', ')}._`);
             }
+            // ── Auto-Changelog — new lessons since last session ──────────────────────
+            // Appended at the end so it never competes with the core briefing.
+            // Skipped on: first session, no new lessons, or when disabled via prefs.
+            try {
+                const autoChangelogPref = await redis.get(`cachly:prefs:auto_changelog:${instance_id}`).catch(() => null);
+                const autoChangelogEnabled = autoChangelogPref !== 'false';
+                if (autoChangelogEnabled && lastSession?.ts && !isFirstSession) {
+                    const lastTs = new Date(lastSession.ts).getTime();
+                    if (!Number.isNaN(lastTs)) {
+                        const newLessons = lessons.filter(l => {
+                            const t = new Date(l.ts).getTime();
+                            return !Number.isNaN(t) && t > lastTs;
+                        });
+                        if (newLessons.length > 0) {
+                            const ago = Math.round((Date.now() - lastTs) / 60000);
+                            const agoStr = ago < 60 ? `${ago}m` : ago < 1440 ? `${Math.round(ago / 60)}h` : `${Math.round(ago / 1440)}d`;
+                            lines.push('');
+                            lines.push(`📋 **${newLessons.length} new lesson${newLessons.length !== 1 ? 's' : ''} since your last session** (${agoStr} ago):`);
+                            // Group by category
+                            const catMap = new Map();
+                            for (const l of newLessons.slice(0, 20)) {
+                                const cat = l.topic.includes(':') ? l.topic.split(':')[0] : 'general';
+                                const arr = catMap.get(cat) ?? [];
+                                arr.push(l);
+                                catMap.set(cat, arr);
+                            }
+                            for (const [cat, catLessons] of catMap) {
+                                lines.push(`  **${cat}**`);
+                                for (const l of catLessons) {
+                                    const icon = l.outcome === 'failure' ? '❌' : l.severity === 'critical' ? '🚨' : l.severity === 'major' ? '⚠️' : '✅';
+                                    const body = (l.outcome === 'failure' ? l.what_failed : l.what_worked) ?? '';
+                                    lines.push(`    ${icon} \`${l.topic}\`${body ? ` — ${body.slice(0, 80)}` : ''}`);
+                                }
+                            }
+                            if (newLessons.length > 20) {
+                                lines.push(`  … and ${newLessons.length - 20} more. Call \`brain_changelog\` for the full list.`);
+                            }
+                            lines.push(`  _Disable auto-changelog: \`brain_set_pref(instance_id="${instance_id}", key="auto_changelog", value="false")\`_`);
+                        }
+                    }
+                }
+            }
+            catch { /* changelog must never block session_start */ }
             return lines.join('\n');
         }
         // ── session_start_summary ─────────────────────────────────────────────────
@@ -3279,7 +3342,6 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             const { instance_id, days = 7, max_lessons = 30, include_failures = true, } = args;
             const redis = await getConnection(instance_id);
             const cutoff = Date.now() - Number(days) * 86_400_000;
-            // Scan all lessons and collect recent ones.
             const keys = await scanKeys(redis, 'cachly:lesson:best:*', { max: 4000, timeoutMs: 4000 });
             const recent = [];
             for (const k of keys) {
@@ -3295,7 +3357,6 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                 const topic = k.replace('cachly:lesson:best:', '');
                 recent.push({ ...lesson, topic });
             }
-            // Sort by timestamp desc, cap at max_lessons.
             recent.sort((a, b) => {
                 const ta = a.ts ? new Date(a.ts).getTime() : 0;
                 const tb = b.ts ? new Date(b.ts).getTime() : 0;
@@ -3309,7 +3370,6 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
                     `_No new lessons learned in this window. Your Brain already knows everything it knows — add new lessons with \`learn_from_attempts\`._`,
                 ].join('\n');
             }
-            // Group by category (topic prefix before first ':').
             const groups = new Map();
             for (const l of lessons) {
                 const cat = l.topic.includes(':') ? l.topic.split(':')[0] : 'general';
@@ -3348,6 +3408,37 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             lines.push('---', `_Generated from Brain \`${instance_id}\` · Share this in your standup or Slack_`);
             return lines.join('\n');
         }
+        // ── brain_set_pref ────────────────────────────────────────────────────────
+        case 'brain_set_pref': {
+            const { instance_id, key, value, } = args;
+            if (!key || !key.trim())
+                throw new Error('key is required');
+            const redis = await getConnection(instance_id);
+            const redisKey = `cachly:prefs:${key.trim()}:${instance_id}`;
+            await redis.set(redisKey, String(value));
+            return `✅ Preference \`${key}\` set to \`${value}\` for this Brain instance.`;
+        }
+        // ── brain_get_pref ────────────────────────────────────────────────────────
+        case 'brain_get_pref': {
+            const { instance_id, key } = args;
+            const redis = await getConnection(instance_id);
+            if (key && key.trim()) {
+                const val = await redis.get(`cachly:prefs:${key.trim()}:${instance_id}`).catch(() => null);
+                return val === null
+                    ? `ℹ️ Preference \`${key}\` is not set (using default).`
+                    : `🔧 Preference \`${key}\` = \`${val}\``;
+            }
+            const prefKeys = await scanKeys(redis, `cachly:prefs:*:${instance_id}`, { max: 200, timeoutMs: 2000 });
+            if (prefKeys.length === 0)
+                return 'ℹ️ No preferences set for this Brain instance.';
+            const vals = await redis.mget(...prefKeys);
+            const lines = ['🔧 **Brain preferences:**', ''];
+            for (let i = 0; i < prefKeys.length; i++) {
+                const k = prefKeys[i].replace('cachly:prefs:', '').replace(`:${instance_id}`, '');
+                lines.push(`- \`${k}\` = \`${vals[i] ?? '(null)'}\``);
+            }
+            return lines.join('\n');
+        }
         // ── sync_file_changes ─────────────────────────────────────────────────────
         default:
             return null;