@cachly-dev/mcp-server 0.10.5 → 0.10.6

package/llms.txt

@@ -0,0 +1,155 @@
+# cachly AI Brain — MCP Server
+
+> Persistent memory layer for AI coding assistants. Gives Claude Code, Cursor, GitHub Copilot, Windsurf, Cline and Zed a permanent brain that learns from every session, bug fix, git commit, and CI run — automatically.
+
+## What cachly is
+
+cachly is an MCP (Model Context Protocol) server that adds long-term memory to AI coding assistants. Unlike conversation-window context, cachly memory persists forever across sessions, projects, and team members.
+
+It works by maintaining a Causal Knowledge Graph (CKG) — a structured store of lessons, bug fixes, architecture decisions, deployment commands, and failure patterns. On every session start, the AI receives a briefing with relevant lessons. On every fix or commit, new lessons are automatically stored.
+
+**Key differentiator**: causal_trace — given any error or problem description, traces the causal chain through the graph (root cause → intermediate causes → known fix). No other memory system does this.
+
+## Installation (zero config)
+
+```bash
+npx @cachly-dev/mcp-server@latest setup
+```
+
+This command: authenticates via OAuth device flow (one browser click), auto-detects all installed editors, writes the correct MCP config for each, creates CLAUDE.md with Brain rules, installs a git post-commit hook.
+
+Free tier: 25 MB, no credit card, German servers (GDPR).
+
+## Supported editors
+
+Claude Code, Cursor, Windsurf, VS Code, GitHub Copilot, Cline, Zed, Continue.dev
+
+## How memory works
+
+1. Session starts → AI receives: last session summary, open failures, relevant lessons, memory crystal (compressed history)
+2. During work → AI stores: WIP state, architecture decisions, file summaries
+3. Bug fixed → lesson stored: what failed, what worked, commands used, severity, file paths
+4. Editor closes → session summary saved, git log analyzed, ambient lessons extracted
+5. Next session → AI arrives pre-briefed
+
+## Tool catalog (89 tools)
+
+### Session & Memory
+- session_start: Single-call session briefing — last summary, open failures, recent lessons, brain health
+- session_end: Save session summary when finishing work
+- session_handoff: Detailed handoff for next chat window
+- session_ping: Lightweight checkpoint every ~5 tool calls
+- auto_learn_session: Auto-learn from session observations without explicit calls
+- sync_file_changes: Associate recent file changes with brain knowledge
+
+### Lesson Storage & Recall
+- learn_from_attempts: Store structured lesson from any fix, deploy, or discovery
+- recall_best_solution: Best known solution for a topic with success/failure history
+- smart_recall: BM25+ semantic search across all brain data (11 languages: EN DE FR ES IT PT ZH JA KO AR HE)
+- brain_search: Full-text search over all brain data
+- recall_at: Brain archaeology — see what a lesson looked like at a point in time
+
+### Causal Analysis & Prediction
+- causal_trace: Root Cause Analysis through memory — problem → causal chain → known fix
+- brain_predict: Predictive pre-fetch — predicts likely failures given current context, returns fixes
+- brain_predict_failures: Pre-deploy failure prediction with probability percentages
+- trace_dependency: Find all lessons that depend on a given prerequisite
+- knowledge_decay: Confidence scoring for every lesson
+
+### Context Management
+- remember_context: Save architecture findings, decisions, file summaries
+- recall_context: Retrieve saved context by key (supports glob)
+- list_remembered: List all cached context entries
+- forget_context: Delete cached context entries
+- compact_recover: Reconstruct full context from Memory Crystal after context limit
+
+### Memory Maintenance
+- memory_consolidate: Weekly garbage collector — deduplicates, detects contradictions, expires stale lessons
+- memory_crystalize: Compress sessions into dense Memory Crystal snapshot
+- crystal_view: Inspect current Memory Crystal
+- brain_diff: See exactly what changed in the brain since a point in time
+- brain_doctor: Health check — lesson count, IQ boost %, open failures, recommendations
+- brain_from_git: Bootstrap brain lessons from existing git history
+
+### Team Brain
+- team_learn: Store lesson in shared team brain
+- team_recall: Recall from shared team brain (shows who learned what)
+- team_synthesize: Merge multiple contributors' lessons on same topic into canonical version
+- madc_deliberate: Multi-Agent Deliberation Chamber — 6 specialist agents vote on conflicting lessons
+
+### Knowledge Commons (Global)
+- syndicate: Contribute verified lesson to global Knowledge Commons
+- syndicate_search: Search global Knowledge Commons
+- syndicate_trending: Trending lessons globally
+- fedbrain_contribute: Contribute with cryptographic knowledge certificate
+- fedbrain_search: Context-weighted search of global commons
+- fedbrain_confirm: Confirm a syndicated lesson worked for you
+- publish_lesson: Publish lesson to Cachly Public Brain
+- import_public_brain: Import community lessons for a framework
+- global_learn: Store lesson that applies across all your projects
+- global_recall: Retrieve cross-project lessons
+
+### Continuous Learning Stream
+- cls_ingest: Ingest learning signals from git commits, CI runs, IDE diagnostics without session_end
+- cls_install_hooks: Generate git post-commit hook and GitHub Actions step for automatic learning
+
+### Autopilot — self-managing AI instructions
+- autopilot: Generate a CLAUDE.md / copilot-instructions.md / .github/copilot-instructions.md from actual Brain content. Supports Claude, Cursor, Copilot, Windsurf, Gemini. style="minimal" for just the hooks, style="full" for complete ruleset with examples. Re-run as the Brain learns more to continuously upgrade the instructions file.
+
+### Roadmap & Planning
+- roadmap_add: Add item to persistent project roadmap stored in Brain
+- roadmap_update: Update roadmap item status, priority, details
+- roadmap_list: List roadmap items filtered by status, priority, tag, milestone
+- roadmap_next: Get the single most important next actionable item
+
+### Cache & Infrastructure
+- list_instances / create_instance / delete_instance: Manage Brain instances
+- cache_get / cache_set / cache_delete: Standard Redis/Valkey cache operations
+- cache_mget / cache_mset: Bulk pipeline (single round-trip)
+- cache_exists / cache_ttl / cache_keys / cache_stats: Cache introspection
+- semantic_search: Find cached entries by semantic similarity
+- cache_warmup: Pre-warm semantic cache with prompt/value pairs
+- cache_lock_acquire / cache_lock_release: Distributed locking
+- cache_stream_set / cache_stream_get: LLM token stream caching
+- index_project: Index source files for semantic search
+- detect_namespace: Classify prompts into semantic namespaces
+- get_connection_string: Get Redis/Valkey connection string
+- get_api_status: Full diagnostic — call when anything is broken
+
+### Organization & Teams
+- list_orgs / create_org / invite_member / get_org_plan: Multi-tenant organization management
+- ckg_inspect: Inspect Causal Knowledge Graph for a concept
+- autopilot: Generate CLAUDE.md / copilot-instructions.md for self-managing AI
+- setup_ai_memory: One-shot setup of 3-layer AI Memory system
+- brain_federate: Private org knowledge transfer
+
+## Comparison to alternatives
+
+| Feature | cachly | mem0 | Plain CLAUDE.md |
+|---------|--------|------|-----------------|
+| Persistent across sessions | ✅ | ✅ | Manual |
+| Causal root cause analysis | ✅ | ❌ | ❌ |
+| Automatic (no explicit calls) | ✅ | ❌ | ❌ |
+| Team knowledge sharing | ✅ | Paid | ❌ |
+| Failure prediction | ✅ | ❌ | ❌ |
+| Git-ambient learning | ✅ | ❌ | ❌ |
+| 11-language search | ✅ | ❌ | ❌ |
+| Free tier forever | ✅ | Limited | ✅ |
+| GDPR / EU servers | ✅ | ❌ | ✅ |
+
+## Pricing
+
+- Free: 25 MB, 1 instance, €0/month forever
+- Dev: 200 MB, €19/month
+- Pro: 900 MB, team features, €49/month
+- Speed: 900 MB + Dragonfly engine, €79/month
+- Business: 7 GB, €199/month
+
+All plans: German servers, GDPR-compliant, 99.9% SLA.
+
+## Links
+
+- npm: https://www.npmjs.com/package/@cachly-dev/mcp-server
+- GitHub: https://github.com/cachly-dev/cachly-mcp
+- Docs: https://cachly.dev/docs/ai-memory
+- Dashboard: https://cachly.dev

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@cachly-dev/mcp-server",
-  "version": "0.10.5",
+  "version": "0.10.6",
   "mcpName": "io.github.cachly-dev/cachly-mcp",
-  "description": "Give Claude a persistent memory that never forgets. cachly learns automatically from every session, bug fix & git commit — no manual calls needed. Arrives pre-briefed. Predicts failures before they happen. One-click sign-in (OAuth Device Flow, no copy-paste) · 63 tools · Free tier · EU servers · Claude Code · Cursor · GitHub Copilot · Windsurf · Continue.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. Persistent memory + causal root-cause analysis for Claude Code, Cursor, Copilot & Windsurf. Learns from every bug fix, git commit, and CI run automatically. Arrives pre-briefed. Predicts failures before they happen. 89 MCP tools · Free tier forever · GDPR · EU servers.",
   "type": "module",
   "bin": {
     "cachly-mcp": "dist/index.js"
@@ -42,37 +42,53 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
+    "ai-memory",
+    "persistent-memory",
+    "claude-code-memory",
     "claude",
     "claude-code",
     "cursor",
+    "cursor-memory",
     "copilot",
     "github-copilot",
     "windsurf",
+    "cline",
+    "zed",
     "continue",
-    "ai-memory",
     "ai-brain",
-    "persistent-memory",
     "brain",
-    "sessions",
-    "lessons-learned",
-    "semantic-cache",
+    "causal-knowledge-graph",
+    "causal-trace",
+    "root-cause-analysis",
+    "failure-prediction",
+    "brain-predict",
+    "smart-recall",
+    "memory-crystals",
     "team-knowledge",
     "ambient-git",
-    "memory-crystals",
-    "causal-knowledge-graph",
     "continuous-learning",
+    "lessons-learned",
+    "session-memory",
+    "semantic-cache",
+    "semantic-search",
     "predictive-ai",
+    "developer-productivity",
+    "knowledge-base",
+    "knowledge-graph",
+    "ai-context",
+    "context-window",
+    "long-term-memory",
+    "llm-memory",
     "cachly",
     "redis",
     "valkey",
     "cache",
     "ai",
     "llm",
-    "knowledge-base",
-    "developer-productivity",
-    "ckg",
-    "mcp-server"
+    "gdpr",
+    "ckg"
   ],
   "homepage": "https://cachly.dev/docs/mcp",
   "bugs": {

package/scripts/postinstall.js

@@ -2,35 +2,28 @@
 // Shown once after: npm install @cachly-dev/mcp-server
 
 const c = {
-  reset: "\x1b[0m",
-  bold: "\x1b[1m",
+  reset:  "\x1b[0m",
+  bold:   "\x1b[1m",
   violet: "\x1b[35m",
-  green: "\x1b[32m",
-  cyan: "\x1b[36m",
+  green:  "\x1b[32m",
+  cyan:   "\x1b[36m",
+  dim:    "\x1b[2m",
   yellow: "\x1b[33m",
-  dim: "\x1b[2m",
 };
 
 const line = `${c.dim}─────────────────────────────────────────────────────${c.reset}`;
 
 console.log(`
 ${line}
-  ${c.bold}${c.violet}🧠 Cachly Brain MCP Server${c.reset} ${c.dim}v${process.env.npm_package_version ?? ""}${c.reset}
+  ${c.bold}${c.violet}🧠 cachly AI Brain${c.reset} ${c.dim}v${process.env.npm_package_version ?? ""}${c.reset}
 
-  ${c.bold}Give your AI assistant persistent memory in 30 seconds:${c.reset}
+  ${c.bold}One command sets everything up:${c.reset}
 
-  ${c.cyan}1.${c.reset} Get a free Brain instance at ${c.bold}cachly.dev/setup-ai${c.reset}
-  ${c.cyan}2.${c.reset} Add to Claude Code / Cursor / Copilot / Windsurf:
-     ${c.dim}npx @cachly-dev/mcp-server@latest init${c.reset}
+  ${c.cyan}npx @cachly-dev/mcp-server@latest setup${c.reset}
 
-  ${c.green}✅ Free tier · GDPR · German servers · No credit card${c.reset}
-
-  ${c.dim}──────────────────────────────────────────────────────${c.reset}
-  ${c.yellow}📦 Related packages:${c.reset}
-  ${c.cyan}@cachly-dev/openclaw${c.reset}   Cut LLM costs 60–90% in JS/TS apps
-                         ${c.dim}npm install @cachly-dev/openclaw${c.reset}
-  ${c.cyan}cachly${c.reset}                 CLI to manage your Brain instances
-                         ${c.dim}npm install -g cachly${c.reset}
+  Signs you in → detects your editors → writes all MCP configs
+  automatically → adds Brain rules to CLAUDE.md.
 
+  ${c.green}No credentials. No credit card. Free forever.${c.reset}
+  ${c.dim}Other editors: https://cachly.dev/docs/mcp${c.reset}
 ${line}`);
-

package/server.json

@@ -1,27 +1,21 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.cachly-dev/cachly-mcp",
-  "description": "Give Claude a persistent memory that never forgets. cachly learns automatically from every session, bug fix, and git commit — no manual calls needed. Arrives pre-briefed. Predicts failures before they happen. One-click sign-in (OAuth Device Flow) · 63 tools · Free tier · EU servers · works with Claude Code, Cursor, Copilot, Windsurf.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 89 MCP tools · Free tier · EU servers · GDPR.",
   "repository": {
     "url": "https://github.com/cachly-dev/cachly-mcp",
     "source": "github"
   },
-  "version": "0.10.1",
+  "version": "0.10.0",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.10.1",
+      "version": "0.10.0",
       "transport": {
         "type": "stdio"
       }
     }
-  ],
-  "remotes": [
-    {
-      "transportType": "streamable-http",
-      "url": "https://mcp.cachly.dev/mcp"
-    }
   ]
 }

package/smithery.yaml

@@ -5,23 +5,21 @@ startCommand:
     properties:
       CACHLY_JWT:
         type: string
-        title: "API Key"
-        description: "Optional. Leave blank — on your first tool call the server starts a one-click browser sign-in (OAuth Device Flow) and auto-provisions your free Brain instance. No copy-paste, no dashboard visit required. Or pre-fill with your API key from cachly.dev/setup-ai."
-        default: ""
+        title: "API Key (optional — sign in via browser on first use)"
+        description: "Leave blank for zero-config: on your first tool call the server opens a browser sign-in (OAuth Device Flow) and auto-provisions your Brain instance. Or pre-fill with your API key from cachly.dev/setup-ai."
         examples:
           - "cky_live_abc123..."
       CACHLY_BRAIN_INSTANCE_ID:
         type: string
-        title: "Brain Instance ID"
-        description: "Optional. Leave blank — the server auto-detects your active instance. Only set this if you have multiple Brain instances."
-        default: ""
+        title: "Brain Instance ID (optional)"
+        description: "Only needed if you have multiple Brain instances. Leave blank — the server auto-detects your active instance from the API key."
         pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
         examples:
           - "9d4077aa-bfa2-468b-89cd-0a8d8f3ec483"
       CACHLY_API_URL:
         type: string
-        title: "API URL"
-        description: "Optional. Leave blank unless you self-host cachly."
+        title: "API URL (optional)"
+        description: "Leave blank unless you self-host Cachly."
         default: "https://api.cachly.dev"
     required: []
   commandFunction: |-

package/src/__tests__/auth.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from 'vitest';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { jwtExpiryMs, checkJwt, handleApiError } from '../auth.js';
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+  const body   = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return `${header}.${body}.fakesig`;
+}
+
+const nowSec = () => Math.floor(Date.now() / 1000);
+
+describe('jwtExpiryMs', () => {
+  it('returns null for an empty string', () => {
+    expect(jwtExpiryMs('')).toBeNull();
+  });
+
+  it('returns null for a plain (non-JWT) string', () => {
+    expect(jwtExpiryMs('not-a-token')).toBeNull();
+  });
+
+  it('returns null when the JWT has only two parts', () => {
+    expect(jwtExpiryMs('header.payload')).toBeNull();
+  });
+
+  it('returns null when the JWT has four parts', () => {
+    expect(jwtExpiryMs('a.b.c.d')).toBeNull();
+  });
+
+  it('returns null when the payload base64 is invalid', () => {
+    expect(jwtExpiryMs('header.!!!.sig')).toBeNull();
+  });
+
+  it('returns null when the payload has no exp field', () => {
+    expect(jwtExpiryMs(makeJwt({ sub: 'user-123', iat: nowSec() }))).toBeNull();
+  });
+
+  it('returns null when exp is 0', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: 0 }))).toBeNull();
+  });
+
+  it('converts exp (seconds) to milliseconds', () => {
+    const expSec = nowSec() + 3600;
+    expect(jwtExpiryMs(makeJwt({ exp: expSec }))).toBe(expSec * 1000);
+  });
+
+  it('returns a past timestamp for an expired token', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: nowSec() - 300 }))).toBeLessThan(Date.now());
+  });
+
+  it('returns a future timestamp for a valid token', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: nowSec() + 86400 }))).toBeGreaterThan(Date.now());
+  });
+
+  it('handles a token expiring in less than 60 minutes', () => {
+    const expSec = nowSec() + 30 * 60;
+    const result = jwtExpiryMs(makeJwt({ exp: expSec }))!;
+    const minsLeft = Math.floor((result - Date.now()) / 60_000);
+    expect(minsLeft).toBeGreaterThanOrEqual(29);
+    expect(minsLeft).toBeLessThanOrEqual(30);
+  });
+
+  it('ignores extra claims', () => {
+    const expSec = nowSec() + 3600;
+    expect(jwtExpiryMs(makeJwt({ sub: 'u', iat: nowSec(), exp: expSec, plan: 'free' }))).toBe(expSec * 1000);
+  });
+
+  it('handles padding-free base64url payloads', () => {
+    // base64url (no =) — Buffer.from handles this natively
+    const expSec = nowSec() + 7200;
+    expect(jwtExpiryMs(makeJwt({ exp: expSec, x: 'a' }))).toBe(expSec * 1000);
+  });
+});
+
+describe('checkJwt', () => {
+  it('throws InvalidRequest when jwt is empty', () => {
+    expect(() => checkJwt('')).toThrowError(
+      expect.objectContaining({ code: ErrorCode.InvalidRequest, message: expect.stringContaining('CACHLY_JWT env var not set') }),
+    );
+  });
+
+  it('throws with setup URL when jwt is missing', () => {
+    expect(() => checkJwt('')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }),
+    );
+  });
+
+  it('throws InvalidRequest with expiry timestamp for an expired token', () => {
+    const expSec = nowSec() - 60;
+    const token  = makeJwt({ exp: expSec });
+    expect(() => checkJwt(token)).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('expired at'),
+      }),
+    );
+  });
+
+  it('does not throw for a valid non-expired token', () => {
+    expect(() => checkJwt(makeJwt({ exp: nowSec() + 3600 }))).not.toThrow();
+  });
+
+  it('does not throw for a token with no exp claim', () => {
+    expect(() => checkJwt(makeJwt({ sub: 'user' }))).not.toThrow();
+  });
+});
+
+describe('handleApiError', () => {
+  it('throws InvalidRequest for 401 with the detail message', () => {
+    expect(() => handleApiError(401, 'token expired')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('Authentication failed (401): token expired'),
+      }),
+    );
+  });
+
+  it('throws InvalidRequest for 403 with the detail message', () => {
+    expect(() => handleApiError(403, 'plan limit reached')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('Access denied (403): plan limit reached'),
+      }),
+    );
+  });
+
+  it('throws InternalError for other status codes', () => {
+    expect(() => handleApiError(500, 'server crash')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InternalError,
+        message: expect.stringContaining('cachly API error 500: server crash'),
+      }),
+    );
+  });
+
+  it('includes the cachly.dev/setup-ai link for 401 errors', () => {
+    expect(() => handleApiError(401, 'Unauthorized')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }),
+    );
+  });
+
+  it('includes account access hint for 403 errors', () => {
+    expect(() => handleApiError(403, 'Forbidden')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('access to this resource') }),
+    );
+  });
+});

package/src/auth.ts

@@ -0,0 +1,46 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+
+export function jwtExpiryMs(token: string): number | null {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+    const payload = JSON.parse(
+      Buffer.from(parts[1], 'base64url').toString('utf-8'),
+    ) as { exp?: number };
+    return payload.exp ? payload.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}
+
+export function checkJwt(jwt: string): void {
+  if (!jwt) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      'CACHLY_JWT env var not set.\n\nGet your token at https://cachly.dev/setup-ai and add it to your MCP config:\n  CACHLY_JWT=<your-token>',
+    );
+  }
+  const expMs = jwtExpiryMs(jwt);
+  if (expMs !== null && expMs < Date.now()) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      `CACHLY_JWT expired at ${new Date(expMs).toISOString()}.\n\nGet a fresh token at https://cachly.dev/setup-ai and update CACHLY_JWT in your MCP config.`,
+    );
+  }
+}
+
+export function handleApiError(status: number, detail: string): never {
+  if (status === 401) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      `Authentication failed (401): ${detail}\n\nYour CACHLY_JWT may be expired or invalid. Get a fresh token at https://cachly.dev/setup-ai`,
+    );
+  }
+  if (status === 403) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      `Access denied (403): ${detail}\n\nCheck that your CACHLY_JWT belongs to an account with access to this resource.`,
+    );
+  }
+  throw new McpError(ErrorCode.InternalError, `cachly API error ${status}: ${detail}`);
+}