@cachly-dev/mcp-server 0.10.111 → 0.10.114

package/README.md

@@ -101,6 +101,26 @@ Like what you see? Make it permanent in the next step.
 
 ---
 
+## Brain-first — Semantic Cache as Proof-Point
+
+cachly is not a semantic cache with a brain bolt-on. The Brain is the product. The
+Semantic Cache is the **proof-point** — it shows ROI in dollars from day one, with zero
+trust required. It opens the door. The Brain is why teams never leave.
+
+| | Wedge — Land | Moat — Retain |
+|---|---|---|
+| **Feature** | Semantic Cache | AI Brain (Lessons, Recall, Team-Sharing) |
+| **Value** | Measurable cost savings from day one | Compounding team intelligence |
+| **Metric** | Cache-hit rate, $/month saved | Lessons retained, WoW trend, recall quality |
+| **Analogy** | Datadog APM (surfaces the problem) | Stripe (becomes critical infrastructure) |
+
+**The org-level advantage:** Brain lessons and cache hits are shared across the whole
+team — one person's fix becomes every agent's reflex. Anthropic Projects Memory is
+per-user and model-locked. cachly is team-wide and model-neutral. That's the structural
+moat no first-party tool can build.
+
+---
+
 ## Setup — one command
 
 ```bash
@@ -229,7 +249,7 @@ causal_trace(problem="auth breaks after restart")
 npx @cachly-dev/mcp-server@latest autopilot # One command — signs in, configures every editor, bootstraps from git
 npx @cachly-dev/mcp-server@latest demo      # Preview your Brain (no account needed)
 npx @cachly-dev/mcp-server@latest bench     # Recall quality vs flat-file memory (no auth required)
-npx @cachly-dev/mcp-server@latest setup     # Interactive variant — pick editors yourself
+npx @cachly-dev/mcp-server@latest autosetup # Interactive variant — pick editors yourself
 npx @cachly-dev/mcp-server@latest health    # Check token, API, editors, git hook
 npx @cachly-dev/mcp-server@latest digest    # Weekly Brain summary — shareable
 npx @cachly-dev/mcp-server@latest share     # Generate a shareable stats card + tweet
@@ -378,17 +398,17 @@ following. Manual snippets are in the **Manual Setup** section below.
 | **Cline** | ✅ detected via VS Code | `.vscode/mcp.json` | — | Shares config with Copilot; restart VS Code |
 | **Continue.dev** | ✅ detected via `.continue/` | `.continue/config.json` | — | Uses `modelContextProtocolServers` key |
 | **Zed** | ✅ detected via `.zed/` | `.zed/settings.json` | — | Uses `context_servers` key |
-| **Windsurf (global)** | `setup --editor windsurf` | `~/.windsurf/mcp.json` | ✅ | Pass `--editor` to target global config |
-| **Any other MCP client** | `init --editor claude` | `.mcp.json` | — | Standard `mcpServers` stdio format |
+| **Windsurf (global)** | `autosetup --editor windsurf` | `~/.windsurf/mcp.json` | ✅ | Pass `--editor` to target global config |
+| **Any other MCP client** | `autosetup --editor claude` | `.mcp.json` | — | Standard `mcpServers` stdio format |
 
 **Which sign-in path each editor uses:**
 
 | Scenario | Path |
 |---|---|
-| `setup` from a real terminal (TTY) | OAuth device-flow → browser click → API key saved automatically |
-| `setup` from VSCode task / CI (non-TTY) | Auto-detects non-interactive, opens browser with step-by-step guide, prints `CACHLY_JWT=... setup` instruction |
+| `autosetup` from a real terminal (TTY) | OAuth device-flow → browser click → API key saved automatically |
+| `autosetup` from VSCode task / CI (non-TTY) | Auto-detects non-interactive, opens browser with step-by-step guide, prints `CACHLY_JWT=... autosetup` instruction |
 | First tool call from Claude Code (no JWT yet) | Inline device-flow: MCP returns URL + code, browser opens automatically, next call proceeds |
-| `CACHLY_JWT=cky_live_xxx npx ... setup` | Skips auth step entirely, uses provided key |
+| `CACHLY_JWT=cky_live_xxx npx ... autosetup` | Skips auth step entirely, uses provided key |
 
 > **Tip — fastest per-project setup from inside Claude Code:**
 > ```
@@ -480,12 +500,12 @@ private backend instead of `api.cachly.dev`:
 npx @cachly-dev/mcp-server@latest autopilot --api-url https://cachly.mycorp.internal
 
 # Or non-interactively
-npx @cachly-dev/mcp-server@latest init \
+npx @cachly-dev/mcp-server@latest autosetup \
   --instance-id <uuid> --api-key <cky_live_...> \
   --api-url https://cachly.mycorp.internal
 ```
 
-`setup`/`init` bake `CACHLY_API_URL` into the editor config **only** when it differs
+`autosetup` bakes `CACHLY_API_URL` into the editor config **only** when it differs
 from the default cloud — so default installs stay clean, and self-hosted installs
 keep talking to your backend on every editor launch. All data stays in your infra.
 

package/dist/src/brain-watch-hook.d.ts

@@ -0,0 +1,21 @@
+/** Bumped whenever the hook script changes so installers can upgrade old hooks. */
+export declare const BRAIN_WATCH_HOOK_VERSION = "v1";
+export type BrainWatchHookResult = 'written' | 'upgraded' | 'appended' | 'unchanged' | 'skipped-no-git';
+/**
+ * Idempotently install/upgrade the brain_watch post-commit hook in `projectDir`.
+ * Never throws — returns a status string the caller can report. Safe to run
+ * repeatedly; a second call with the same version returns 'unchanged'.
+ */
+export declare function installBrainWatchHook(projectDir: string, instanceId: string, apiKey?: string): Promise<{
+    result: BrainWatchHookResult;
+    hookPath: string;
+}>;
+/**
+ * Build the `.git/hooks/post-commit` shell script for brain_watch.
+ * Uses curl (not Node) so it works without npx. Runs in the background and
+ * always exits 0 — never blocks a commit.
+ *
+ * @param instanceId  Cachly Brain instance to learn into.
+ * @param apiKey      Optional cky_… key; if absent, the script reads $CACHLY_JWT from env.
+ */
+export declare function buildBrainWatchHook(instanceId: string, apiKey?: string): string;

package/dist/src/brain-watch-hook.js

@@ -0,0 +1,86 @@
+// Ambient git post-commit hook builder for Brain auto-learning.
+//
+// Installs a .git/hooks/post-commit script that POSTs the commit data
+// directly to the cachly API via curl — no Node required at hook runtime,
+// so it works even without npx or the MCP server installed locally.
+//
+// Safety contract:
+//   • exit 0 is ALWAYS the last line — the hook never blocks a commit.
+//   • All network calls run in the background (&) with 2>/dev/null.
+//   • Commit message / sha / files are never interpolated into JS source;
+//     they're passed as shell variables in the JSON body (curl --data-raw).
+import { existsSync } from 'node:fs';
+import { readFile, writeFile, chmod, mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+/** Bumped whenever the hook script changes so installers can upgrade old hooks. */
+export const BRAIN_WATCH_HOOK_VERSION = 'v1';
+/**
+ * Matches any previously-installed cachly brain_watch block (from its marker
+ * comment down to the trailing `exit 0`), optionally including a shebang.
+ * Used to upgrade old hooks in place rather than duplicating them.
+ */
+const BRAIN_WATCH_BLOCK_RE = /(?:#!\/bin\/sh\n)?# cachly brain_watch[\s\S]*?\nexit 0\n?/;
+/**
+ * Idempotently install/upgrade the brain_watch post-commit hook in `projectDir`.
+ * Never throws — returns a status string the caller can report. Safe to run
+ * repeatedly; a second call with the same version returns 'unchanged'.
+ */
+export async function installBrainWatchHook(projectDir, instanceId, apiKey) {
+    if (!existsSync(resolve(projectDir, '.git'))) {
+        return { result: 'skipped-no-git', hookPath: '' };
+    }
+    const hookDir = resolve(projectDir, '.git', 'hooks');
+    const hookPath = resolve(hookDir, 'post-commit');
+    await mkdir(hookDir, { recursive: true });
+    const script = buildBrainWatchHook(instanceId, apiKey);
+    let existing = '';
+    try {
+        existing = await readFile(hookPath, 'utf-8');
+    }
+    catch { /* no existing hook */ }
+    if (!existing) {
+        await writeFile(hookPath, script + '\n', 'utf-8');
+        await chmod(hookPath, 0o755).catch(() => { });
+        return { result: 'written', hookPath };
+    }
+    if (existing.includes(`cachly brain_watch — Auto-Learn ${BRAIN_WATCH_HOOK_VERSION}`)) {
+        return { result: 'unchanged', hookPath };
+    }
+    if (BRAIN_WATCH_BLOCK_RE.test(existing)) {
+        const replaced = existing.replace(BRAIN_WATCH_BLOCK_RE, script);
+        await writeFile(hookPath, replaced.endsWith('\n') ? replaced : replaced + '\n', 'utf-8');
+        await chmod(hookPath, 0o755).catch(() => { });
+        return { result: 'upgraded', hookPath };
+    }
+    // Foreign hook with no brain_watch block → append ours.
+    await writeFile(hookPath, existing.trimEnd() + '\n\n' + script + '\n', 'utf-8');
+    await chmod(hookPath, 0o755).catch(() => { });
+    return { result: 'appended', hookPath };
+}
+/**
+ * Build the `.git/hooks/post-commit` shell script for brain_watch.
+ * Uses curl (not Node) so it works without npx. Runs in the background and
+ * always exits 0 — never blocks a commit.
+ *
+ * @param instanceId  Cachly Brain instance to learn into.
+ * @param apiKey      Optional cky_… key; if absent, the script reads $CACHLY_JWT from env.
+ */
+export function buildBrainWatchHook(instanceId, apiKey) {
+    return [
+        `#!/bin/sh`,
+        `# cachly brain_watch — Auto-Learn ${BRAIN_WATCH_HOOK_VERSION}`,
+        `# Silently teaches your Brain after every commit — no manual brain_from_git needed.`,
+        ...(apiKey ? [`CACHLY_JWT="${apiKey}"`] : []),
+        `_BW_SHA=$(git rev-parse HEAD 2>/dev/null || echo "")`,
+        `_BW_MSG=$(git log -1 --pretty=%B 2>/dev/null | head -1 | cut -c1-200)`,
+        `_BW_FILES=$(git diff-tree --no-commit-id -r --name-only HEAD 2>/dev/null | tr '\\n' '\\t' | sed 's/\\t$//')`,
+        `(curl -s -o /dev/null -m 8 \\`,
+        `  -X POST "https://api.cachly.dev/api/v1/instances/${instanceId}/learn" \\`,
+        `  -H "Authorization: Bearer \${CACHLY_JWT}" \\`,
+        `  -H "Content-Type: application/json" \\`,
+        `  --data-raw "{\\"message\\":\\"$(echo "$_BW_MSG" | sed 's/"/\\\\"/g')\\",\\"sha\\":\\"$_BW_SHA\\",\\"files\\":[$(echo "$_BW_FILES" | tr '\\t' '\\n' | grep -v '^$' | sed 's/.*/\\"&\\"/' | tr '\\n' ',' | sed 's/,$//')],\\"source\\":\\"brain_watch\\"}" \\`,
+        `) 2>/dev/null &`,
+        `exit 0`,
+    ].join('\n');
+}
+//# sourceMappingURL=brain-watch-hook.js.map

package/dist/src/brain-watch-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-watch-hook.js","sourceRoot":"","sources":["../../src/brain-watch-hook.ts"],"names":[],"mappings":"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"}

package/dist/src/handlers/brain.js

@@ -7,8 +7,28 @@ 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.111';
+const MCP_VERSION = '0.10.114';
 const WHATS_NEW = {
+    '0.10.114': [
+        `📋 **\`brain_changelog\` — weekly knowledge digest in one call**`,
+        `  📅 Generates a grouped Markdown changelog of lessons learned in the last N days.`,
+        `  👥 Grouped by topic category, annotated with author, recall count, and confidence — paste directly into standup or Slack.`,
+        `  ⚙️ Params: \`days\` (default 7), \`max_lessons\` (default 30), \`include_failures\` (default true).`,
+        `  📊 138 MCP tools`,
+    ],
+    '0.10.113': [
+        `📈 **Week-over-week savings trend in \`cache_stats\`**`,
+        `  📅 \`cache_stats\` now shows **7-day hits** + **WoW trend %** (e.g. \`+23.0% vs prev week\`) so ROI momentum is visible, not just the cumulative total.`,
+        `  ⬇️ Goes red (📉) on drops, green (📈) on growth — first week always shows +100% (new).`,
+        `  🔧 Backed by new \`CountHitsInWindow\` repo method + \`hits_last_7d\`, \`hits_prev_7d\`, \`week_over_week_pct\` fields in \`SavingsEstimate\`.`,
+        `  📊 137 MCP tools`,
+    ],
+    '0.10.112': [
+        `⚙️ **Configurable cost_per_call_usd — accurate ROI for any LLM**`,
+        `  💡 New \`set_cost_per_call\` tool: set your real per-call cost (claude-opus-4.8 → $0.02, gpt-5.5 → $0.015, claude-sonnet-4.6 → $0.009, claude-haiku-4.5 → $0.001) so savings estimates in \`cache_stats\` reflect your actual bill.`,
+        `  🔧 New API: \`PUT /api/v1/instances/:id/cost-per-call\` — persisted per instance, used by \`cache_stats\`, org savings, and SSE analytics stream.`,
+        `  📊 137 MCP tools`,
+    ],
     '0.10.111': [
         `🏢 **Org-wide ROI + GitLab CI — the CFO number, aggregated**`,
         `  💰 \`cache_org_stats\` now shows **org-wide Tokenmaxxing ROI**: total savings summed across every instance in your org, monthly projection, top-5 instances by savings. One number for the whole team.`,
@@ -335,7 +355,7 @@ export const BRAIN_TOOL_NAMES = new Set([
     'session_start', 'session_start_summary', 'session_end', 'session_ping', 'session_handoff', 'auto_learn_session',
     'brain_who_knows', 'brain_file_map', 'team_expertise_map',
     'skill_gaps', 'brain_coverage', 'brain_metrics', 'brain_service_map',
-    'brain_collab_pairs', 'brain_portability',
+    'brain_collab_pairs', 'brain_portability', 'brain_changelog',
 ]);
 // ── Free-tier Teaser-Gate ──────────────────────────────────────────────────
 // When a Free-tier Brain crosses its recall limit, smart_recall still delivers
@@ -3252,6 +3272,82 @@ export async function handleBrainTool(name, args, getConnection, apiFetch) {
             lines.push(`---`, ``, `### What travels with you`, ``, `| Data | Model-neutral? |`, `|------|---------------|`, `| Lessons (learn_from_attempts) | ✅ Full access in all clients |`, `| Memory Crystals (memory_crystalize) | ✅ Included in every session_start |`, `| Causal Knowledge Graph (brain_predict) | ✅ Same graph, same predictions |`, `| Team lessons (team_learn, team_confirm) | ✅ Team is per-Brain, not per-model |`, `| Domain Brain Marketplace installs | ✅ Installed once, available everywhere |`, `| Session handoffs (session_handoff) | ✅ Cross-client continuity |`, ``, `---`, ``, `### One-command setup for any new client`, ``, '```bash', `npx @cachly-dev/mcp-server@latest autopilot`, '```', ``, `Autopilot detects all installed editors and writes the config for each — with your \`${instance_id}\` Brain ID pre-filled.`, ``, `---`, `_Docs: cachly.dev/docs/model-neutral • Your Brain, Any Model_`);
             return lines.join('\n');
         }
+        // ── brain_changelog ───────────────────────────────────────────────────────
+        // Generates a human-readable Markdown changelog of recent lessons.
+        // Useful for weekly standups, sprint reviews, or async team updates.
+        case 'brain_changelog': {
+            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) {
+                const raw = await redis.get(k).catch(() => null);
+                if (!raw)
+                    continue;
+                const lesson = safeJsonParse(raw, {});
+                const ts = lesson.ts ? new Date(lesson.ts).getTime() : 0;
+                if (ts < cutoff)
+                    continue;
+                if (!include_failures && lesson.outcome === 'failure')
+                    continue;
+                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;
+                return tb - ta;
+            });
+            const lessons = recent.slice(0, Number(max_lessons));
+            if (lessons.length === 0) {
+                return [
+                    `## 📋 Brain Changelog — last ${days} day${Number(days) !== 1 ? 's' : ''}`,
+                    ``,
+                    `_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';
+                const arr = groups.get(cat) ?? [];
+                arr.push(l);
+                groups.set(cat, arr);
+            }
+            const severityEmoji = (s) => s === 'critical' ? '🚨' : s === 'major' ? '⚠️' : s === 'minor' ? '💡' : '✨';
+            const outcomeEmoji = (o) => o === 'failure' ? '❌' : o === 'partial' ? '🔶' : '✅';
+            const dateStr = new Date().toISOString().slice(0, 10);
+            const lines = [
+                `## 📋 Brain Changelog — ${dateStr} (last ${days} day${Number(days) !== 1 ? 's' : ''})`,
+                ``,
+                `_${lessons.length} lesson${lessons.length !== 1 ? 's' : ''} learned across ${groups.size} topic area${groups.size !== 1 ? 's' : ''}_`,
+                ``,
+            ];
+            for (const [cat, catLessons] of Array.from(groups.entries()).sort((a, b) => b[1].length - a[1].length)) {
+                lines.push(`### ${cat}`);
+                lines.push('');
+                for (const l of catLessons) {
+                    const icon = l.outcome === 'failure' ? outcomeEmoji(l.outcome) : severityEmoji(l.severity);
+                    const body = l.outcome === 'failure' ? l.what_failed : l.what_worked;
+                    const meta = [];
+                    if (l.author)
+                        meta.push(`by **${l.author}**`);
+                    if (l.recall_count)
+                        meta.push(`${l.recall_count} recall${l.recall_count !== 1 ? 's' : ''}`);
+                    if (l.confidence !== undefined)
+                        meta.push(`${Math.round(l.confidence * 100)}% confidence`);
+                    lines.push(`- ${icon} **${l.topic}**${body ? ` — ${body}` : ''}`);
+                    if (meta.length)
+                        lines.push(`  _${meta.join(' · ')}_`);
+                }
+                lines.push('');
+            }
+            lines.push('---', `_Generated from Brain \`${instance_id}\` · Share this in your standup or Slack_`);
+            return lines.join('\n');
+        }
         // ── sync_file_changes ─────────────────────────────────────────────────────
         default:
             return null;