@cachly-dev/mcp-server 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -7,7 +7,50 @@
 
 ---
 
-## [0.5.37] – 2026-04-24
+## [0.7.0] – 2026-05-04
+
+### 🌐 Knowledge Syndication — The Global AI Brain
+
+The first collective intelligence layer for AI memory.
+Every instance contributes. Every instance learns. Privacy-preserving by design.
+
+#### New Tools
+
+- **`syndicate`** — Contribute a verified lesson to the **global Knowledge Commons**. Your identity is a one-way HMAC hash — completely anonymous. The lesson is immediately searchable by every other AI brain on the planet. Call this after any `learn_from_attempts` that is worth sharing: critical bugs, deployment gotchas, architecture discoveries. This is how individual knowledge becomes collective intelligence.
+
+- **`syndicate_search`** — Search the **global Knowledge Commons** for solutions discovered by the entire community. Results ranked by `confirm_count` (trust score) then recency. Use this *before* debugging any unknown issue — someone in the global brain likely solved it already. Returns: topic, what worked, what failed, trust bar `████████░░ ×47`.
+
+#### Privacy Design
+- Contributors identified only by HMAC-SHA256 of user_id — irreversible, not linkable to any identity
+- Absolute file paths stripped from all content before storage
+- Community flagging: lessons with 3+ flags are hidden globally
+- Trust scoring: `confirm_count` rises as independent instances verify a lesson works
+
+---
+
+## [0.6.1] – 2026-05-04
+
+### 🧠 Cognitive Cache — v0.6 Major Feature
+
+The first AI Memory system with **reasoning over its own knowledge**. No other cache has ever done this.
+
+#### New Tools
+
+- **`memory_consolidate`** — Weekly garbage collector for your AI Brain. Detects contradictions (same topic, different outcomes), merges duplicate lesson clusters, flags stale entries (0 recalls in N days). Like `git gc` for knowledge. Returns a full consolidation report with before/after counts.
+
+- **`brain_diff`** — `git log` for your AI Brain. Shows exactly what changed since a given time window (`"7d"`, `"30d"`, ISO-8601). New lessons, updated lessons, recalled lessons. Perfect for weekly reviews: *"What did my AI learn this week?"*
+
+- **`causal_trace`** — Root Cause Analysis through memory. Given a problem description, scores all lessons by relevance, reconstructs the failure chain (root → intermediate → symptom), and surfaces the exact solution that worked before. *"auth breaks after restart"* → root: `k8s:namespace-terminating` → via: `keycloak:jwks-race` → fix: `PollUntilContextTimeout 3min`. No other system can do this.
+
+- **`knowledge_decay`** — Confidence scoring per lesson. Age × recall-frequency × outcome = decay score (0–100%). Visual bars: `████░░░░░░ 40%`. Lessons recalled recently score high; 90-day-old untouched lessons score low. Run before a big refactor to know which knowledge to trust.
+
+- **`autopilot`** — Generates a `CLAUDE.md` / `copilot-instructions.md` that turns any AI (Claude, Cursor, Copilot, Windsurf, Gemini) into a self-managing Brain operator. No manual `session_start`, `learn_from_attempts`, or `session_end` calls ever again. One command. Every AI. Forever.
+
+---
+
+## [0.5.80] – 2026-05-01
+
+
 
 ### Added
 

package/README.md

@@ -29,6 +29,32 @@
 
 ---
 
+## 🆕 v0.6 — Cognitive Cache: Your AI Brain now *thinks* about what it knows
+
+> Redis stores bytes. LangChain stores text. **cachly v0.6 reasons over knowledge.**
+
+### The 5 tools no other memory system has:
+
+| Tool | What it does | Why it's different |
+|---|---|---|
+| `memory_consolidate` | Weekly garbage collector — detects contradictions, merges duplicates, expires stale | Like `git gc` for knowledge |
+| `brain_diff` | `git log` for your AI Brain — what changed this week? | See your AI's learning velocity |
+| `causal_trace` | Root Cause Analysis through memory: problem → chain → solution | **No other system can do this** |
+| `knowledge_decay` | Confidence score per lesson: `████░░░░ 40%` | Old knowledge rots. Now you know which |
+| `autopilot` | Generates CLAUDE.md that makes any AI self-managing, forever | Zero manual calls. One command. Done. |
+
+**The `causal_trace` moment:**
+```
+causal_trace(problem="auth breaks after restart")
+
+→ Root: k8s:namespace-terminating
+→ Via:  keycloak:jwks-race  
+→ Fix:  PollUntilContextTimeout 3min  ← used this March 12, worked
+```
+*30 minutes of git blame + log archaeology. In one call.*
+
+---
+
 ## The Problem
 
 Every morning, you open your AI coding assistant. It doesn't remember yesterday.  
@@ -68,6 +94,54 @@ npx @cachly-dev/mcp-server@latest index .
 <details>
 <summary><b>Claude Code</b> (<code>~/.claude/mcp.json</code> or <code>.mcp.json</code>)</summary>
 
+```json
+{
+  "mcpServers": {
+    "cachly": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@cachly-dev/mcp-server@latest"],
+      "env": {
+        "CACHLY_JWT": "your-jwt-token",
+        "CACHLY_INSTANCE_ID": "your-instance-id"
+
+Every morning, you open your AI coding assistant. It doesn't remember yesterday.  
+You explain your architecture. You explain the deployment process. You explain the bug you fixed last week.
+
+**The average developer wastes 45 minutes/day re-establishing context.** That's €15,000+ in lost productivity per engineer per year.
+
+## The Fix — One Command
+
+```bash
+npx @cachly-dev/mcp-server@latest setup
+```
+
+The interactive wizard:
+1. Signs you in (free, no credit card required)
+2. Picks or creates your AI Brain instance
+3. **Auto-detects** Cursor, Windsurf, VS Code, Claude Code, Continue.dev, **Cline & Zed**
+4. Writes the correct MCP config for every detected editor
+5. Creates `CLAUDE.md` with memory rules pre-filled
+6. Shows your Brain Health snapshot right in the terminal
+
+**Index your project** into the Brain for instant semantic search:
+```bash
+npx @cachly-dev/mcp-server@latest index .
+```
+
+**Result:** Your AI remembers everything. Always.
+
+---
+
+## Quick Start (Manual)
+
+**Step 1 — Get your free credentials** at [cachly.dev](https://cachly.dev) (25 MB free, forever, no credit card).
+
+**Step 2 — Add to your editor's MCP config:**
+
+<details>
+<summary><b>Claude Code</b> (<code>~/.claude/mcp.json</code> or <code>.mcp.json</code>)</summary>
+
 ```json
 {
   "mcpServers": {

package/dist/index.js

@@ -47,7 +47,7 @@ import { Redis } from 'ioredis';
 const API_URL = process.env.CACHLY_API_URL ?? 'https://api.cachly.dev';
 const JWT = process.env.CACHLY_JWT ?? '';
 const EMBED_MODEL = process.env.CACHLY_EMBED_MODEL ?? '';
-const CURRENT_VERSION = '0.6.1';
+const CURRENT_VERSION = '0.7.1';
 /**
  * ┌──────────────────────────────────────────────────────────────────────┐
  * │  EMBEDDING PROVIDER — pluggable, client-side first                  │
@@ -3397,6 +3397,57 @@ const TOOLS = [
             required: ['instance_id'],
         },
     },
+    // ── v0.7 Knowledge Syndication ────────────────────────────────────────────
+    {
+        name: 'syndicate',
+        description: 'Contribute a verified lesson to the GLOBAL Cachly Knowledge Commons — ' +
+            'a privacy-preserving shared brain where every AI instance can learn from the discoveries ' +
+            'of every other. Your contributor identity is a one-way HMAC hash: completely anonymous. ' +
+            'The lesson is immediately searchable by any other AI using syndicate_search. ' +
+            'This is how individual knowledge becomes collective intelligence. ' +
+            'Call this AFTER every learn_from_attempts that is worth sharing universally ' +
+            '(critical bugs, deployment gotchas, architecture discoveries).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                topic: { type: 'string', description: 'Topic key in category:keyword format (e.g. "fix:clickhouse-ipv6", "deploy:docker-compose")' },
+                outcome: { type: 'string', enum: ['success', 'failure', 'partial'], description: 'Result of the attempt (default: success)' },
+                what_worked: { type: 'string', description: 'Exact approach, command, or fix that worked. File paths are stripped automatically.' },
+                what_failed: { type: 'string', description: 'What failed or was wrong — helps others avoid the same trap.' },
+                severity: { type: 'string', enum: ['critical', 'major', 'minor'], description: 'How severe the issue was (default: minor)' },
+                tags: { type: 'array', items: { type: 'string' }, description: 'Up to 10 keywords for better discoverability' },
+            },
+            required: ['topic', 'what_worked'],
+        },
+    },
+    {
+        name: 'syndicate_search',
+        description: 'Search the GLOBAL Cachly Knowledge Commons for solutions contributed by the entire community. ' +
+            'Returns lessons ranked by confirm_count (trust score) then recency. ' +
+            'Use this BEFORE debugging any unknown issue — someone in the global brain likely solved it already. ' +
+            'Example: syndicate_search(q="clickhouse localhost connection refused") → ' +
+            '"fix: use 127.0.0.1 not localhost when IPv6 is disabled · confirmed by 47 instances"',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: { type: 'string', description: 'Free-text search query (leave empty for most recent lessons)' },
+                category: { type: 'string', description: 'Filter by category prefix: "fix", "deploy", "debug", "infra", "api", "web"' },
+                limit: { type: 'number', description: 'Max results to return (default: 20, max: 50)' },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'syndicate_stats',
+        description: 'Show the health of the global Knowledge Commons: total lessons, total confirms, ' +
+            'top categories, most-trusted lessons, and growth in the last 7 days. ' +
+            'Use for weekly reviews or to explore what the community knows.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
 ];
 // ── Handlers ──────────────────────────────────────────────────────────────────
 function formatInstance(inst) {
@@ -7002,6 +7053,87 @@ smart_recall(
                 `✨ Once this file is in place, **${editor === 'copilot' ? 'GitHub Copilot' : editor === 'continue' ? 'Continue.dev' : 'Claude/Cursor/Windsurf'}** will manage the Brain automatically — no manual calls needed, ever.`,
             ].join('\n');
         }
+        // ── v0.7 Knowledge Syndication: syndicate ────────────────────────────────
+        case 'syndicate': {
+            const { topic, outcome = 'success', what_worked, what_failed = '', severity = 'minor', tags = [] } = args;
+            if (!topic || !what_worked) {
+                throw new McpError(ErrorCode.InvalidParams, 'topic and what_worked are required');
+            }
+            const body = { topic, outcome, what_worked, what_failed, severity, tags };
+            const res = await apiFetch('/api/v1/syndication/contribute', { method: 'POST', body: JSON.stringify(body) });
+            return [
+                `🌐 **Lesson syndicated to the global Knowledge Commons**`,
+                ``,
+                `**ID:** \`${res.id}\``,
+                `**Topic:** \`${res.topic}\` · **Outcome:** ${res.outcome}`,
+                ``,
+                `Your lesson is now searchable by every AI brain in the network.`,
+                `When another instance confirms it works, its trust score rises automatically.`,
+                ``,
+                `**Tip:** Use \`syndicate_search(q="${topic}")\` to see all community lessons on this topic.`,
+            ].join('\n');
+        }
+        // ── v0.7 Knowledge Syndication: syndicate_search ─────────────────────────
+        case 'syndicate_search': {
+            const { q = '', limit = 20, category = '' } = args;
+            const params = new URLSearchParams();
+            if (q)
+                params.set('q', q);
+            if (category)
+                params.set('category', category);
+            params.set('limit', String(Math.min(Math.max(1, limit), 50)));
+            const res = await apiFetch(`/api/v1/syndication/search?${params}`);
+            if (!res.results || res.results.length === 0) {
+                return q
+                    ? `No lessons found for "${q}" in the global Knowledge Commons yet.\n\nBe the first to contribute: \`syndicate(topic="...", what_worked="...")\``
+                    : `The global Knowledge Commons is empty. Be the first contributor:\n\`syndicate(topic="deploy:api", what_worked="...")\``;
+            }
+            const outcomeIcon = (o) => o === 'success' ? '✅' : o === 'failure' ? '❌' : '⚠️';
+            const severityLabel = (s) => s === 'critical' ? '🔴' : s === 'major' ? '🟡' : '🟢';
+            const confirmBar = (n) => {
+                const filled = Math.min(10, Math.round(n / 5));
+                return '█'.repeat(filled) + '░'.repeat(10 - filled) + ` ×${n}`;
+            };
+            const header = [q, category].filter(Boolean).join(' · ');
+            const lines = [
+                `## 🌐 Global Knowledge Commons${header ? ` — ${header}` : ' — Recent'}`,
+                `*${res.count} lesson${res.count === 1 ? '' : 's'} found*`,
+                ``,
+            ];
+            for (const lesson of res.results) {
+                lines.push(`### ${outcomeIcon(lesson.outcome)} \`${lesson.topic}\` ${severityLabel(lesson.severity)}`, `**Trust:** ${confirmBar(lesson.confirm_count)}`, lesson.what_worked ? `**What worked:** ${lesson.what_worked}` : '', lesson.what_failed ? `**What failed:** ${lesson.what_failed}` : '', `*Contributed ${new Date(lesson.created_at).toLocaleDateString('de-DE')} · ID: \`${lesson.id}\`*`, ``);
+            }
+            lines.push(`---`, `**Confirm** (this helped you): \`syndicate(topic="${res.results[0]?.topic ?? '...'}", what_worked="...")\` → auto-deduped, trust +1`, `**Contribute your own:** \`syndicate(topic="fix:...", what_worked="...")\``, `**Filter by category:** \`syndicate_search(category="fix")\``);
+            return lines.filter(l => l !== '').join('\n');
+        }
+        // ── v0.7 Knowledge Syndication: syndicate_stats ──────────────────────────
+        case 'syndicate_stats': {
+            const res = await apiFetch('/api/v1/syndication/stats');
+            const confirmBar = (n) => {
+                const filled = Math.min(10, Math.round(n / 5));
+                return '█'.repeat(filled) + '░'.repeat(10 - filled) + ` ×${n}`;
+            };
+            const lines = [
+                `## 🌐 Global Knowledge Commons — Stats`,
+                ``,
+                `| Metric | Value |`,
+                `|---|---|`,
+                `| Total lessons | **${res.total_lessons.toLocaleString()}** |`,
+                `| Total confirms | **${res.total_confirms.toLocaleString()}** |`,
+                `| Added last 7 days | **${res.added_last_7_days}** |`,
+                ``,
+                `### Top Categories`,
+            ];
+            for (const cat of res.top_categories ?? []) {
+                lines.push(`- \`${cat.category}\` — ${cat.count} lesson${cat.count === 1 ? '' : 's'}`);
+            }
+            lines.push(``, `### Most Trusted Lessons`);
+            for (const lesson of res.most_trusted ?? []) {
+                lines.push(`**\`${lesson.topic}\`** ${confirmBar(lesson.confirm_count)}`, `> ${lesson.what_worked.slice(0, 120)}${lesson.what_worked.length > 120 ? '…' : ''}`, ``);
+            }
+            lines.push(`---`, `**Contribute:** \`syndicate(topic="...", what_worked="...")\`  |  **Search:** \`syndicate_search(q="your problem")\``);
+            return lines.join('\n');
+        }
         default:
             return null;
     }