@cachly-dev/mcp-server 0.10.0 → 0.10.2

package/CHANGELOG.md

@@ -7,6 +7,48 @@
 
 ---
 
+## [0.10.0] – 2026-05-08
+
+### Zero-Friction Onboarding
+
+- **Global Claude Code config** — `setup` now writes `~/.claude/mcp.json` (global) in addition to project-level `.mcp.json`. cachly is available in every Claude Code project after running setup once — no per-project re-configuration needed. Existing MCP servers in the global config are preserved (merge, not overwrite).
+
+- **Device Flow authentication** — No credentials required in MCP config. On the first tool call without a `CACHLY_JWT`, the server starts an OAuth Device Flow: the AI shows a one-click sign-in URL in chat, polls for completion, exchanges the token for a long-lived API key, and auto-provisions a Brain instance. Fully transparent to the user.
+
+- **Fully automatic sessions** — `session_start` and `session_end` are called automatically (on first tool call and on SIGTERM). Users never need to call them manually.
+
+- **Auto project indexing** — On session start, the project is indexed in the background if the last index is older than 24 hours. Zero extra calls.
+
+### CLAUDE.md Rules — Mandatory Brain Behavior
+
+The CLAUDE.md block written by `setup` now instructs the AI with binding rules (not suggestions):
+
+- `smart_recall` before every task
+- `causal_trace` before grepping/reading files when debugging
+- `brain_predict` before deploys, migrations, and dependency upgrades
+- `remember_context` before editing any file (WIP registry)
+- `learn_from_attempts` after every fix, deploy, or discovery
+
+### SEO & Search AI Optimization
+
+- **`llms.txt`** added — AI crawler standard file with complete tool catalog (89 tools + descriptions), competitor comparison, architecture overview. Indexed by Perplexity, ChatGPT Search, Claude web search.
+- **README** — FAQ section, competitor table (cachly vs mem0 vs MemGPT vs CLAUDE.md), `autopilot` tool documented prominently.
+- **GitHub topics** set: `mcp`, `mcp-server`, `ai-memory`, `persistent-memory`, `claude-code`, `cursor`, `github-copilot`, `causal-trace`, `developer-tools`, `typescript`.
+- **package.json** — description and keywords updated: `causal-trace`, `root-cause-analysis`, `failure-prediction`, `long-term-memory`, `llm-memory`, `claude-code-memory`.
+
+### Auth Module
+
+- `jwtExpiryMs`, `checkJwt`, `handleApiError` extracted from `index.ts` into `src/auth.ts`
+- 23 unit tests added for auth module (Vitest)
+- Publish workflow now runs tests before building
+
+### Bug Fixes
+
+- `safeJsonParse` applied to all `JSON.parse` calls in `advanced.ts` and `syndicate.ts`
+- Removed dead warm-up code
+
+---
+
 ## [0.9.3] – 2026-05-06
 
 ### 🧠 10x Vision Phase 2 — Layers 3, 5 & 6

package/README.md

@@ -1,14 +1,9 @@
-# 🔮 cachly AI Brain — MCP Server
+# 🧠 cachly AI Brain — MCP Server
 
 > **Persistent memory for Claude Code, Cursor, GitHub Copilot, Windsurf, Cline & Zed.**  
-> Your AI remembers every lesson, every fix, every architecture decision — forever.  
-> **Now with Live 3D Brain Visualizer — watch your knowledge galaxy grow in real time.**
+> Your AI remembers every lesson, every fix, every architecture decision — forever.
 
 <p align="center">
-  <a href="https://github.com/cachly-dev/mcp-server/stargazers">
-    <img src="https://img.shields.io/github/stars/cachly-dev/mcp-server?style=social" alt="GitHub Stars" />
-  </a>
-  &nbsp;
   <a href="https://www.npmjs.com/package/@cachly-dev/mcp-server">
     <img src="https://img.shields.io/npm/v/@cachly-dev/mcp-server?color=red&logo=npm" alt="npm version" />
   </a>
@@ -30,19 +25,72 @@
 
 ---
 
-## 🆕 v0.6 — Cognitive Cache: Your AI Brain now *thinks* about what it knows
+## The Problem
+
+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.**
+
+---
+
+## One Command. Fully Automatic.
+
+```bash
+npx @cachly-dev/mcp-server@latest setup
+```
+
+Run it once. It handles everything:
+
+1. **Signs you in** — one click in your browser, no password, no credit card
+2. **Detects your editors** — Claude Code, Cursor, Windsurf, VS Code, Copilot, Cline & Zed
+3. **Writes the MCP config** for every detected editor automatically
+4. **Creates `CLAUDE.md`** with Brain rules so your AI acts autonomously
+5. **Installs a git hook** that learns from every commit automatically
+
+**Restart your editor.** From now on your AI arrives pre-briefed — every session.
+
+---
+
+## What happens after setup — everything is automatic
+
+You never type another command. The Brain runs entirely in the background:
+
+| Trigger | What the Brain does automatically |
+|---------|----------------------------------|
+| First tool call | Session starts, project gets indexed in background |
+| Before every task | AI recalls relevant past lessons |
+| During debugging | AI traces root causes through causal memory |
+| Before deploys | AI predicts failure risks from past patterns |
+| After every fix | AI stores the lesson with commands and file paths |
+| Every git commit | Hook extracts lessons from commit message |
+| Editor closes | Session summary saved for next time |
+
+---
+
+## With vs. Without cachly
+
+| Situation | Without cachly | With cachly |
+|-----------|----------------|-------------|
+| Session start | "What's your architecture?" | "Ready. 23 lessons, last session: deployed API." |
+| Known bug hits again | Re-researches from scratch | "You fixed this March 12, here's the exact command" |
+| After holiday / handoff | Context dead | Fully briefed in < 10 seconds |
+| New team member | Weeks to onboard | `setup` gives full context instantly |
+| Pre-deploy check | Hope nothing breaks | Brain predicts failures before they happen |
 
-> Redis stores bytes. LangChain stores text. **cachly v0.6 reasons over knowledge.**
+---
 
-### The 5 tools no other memory system has:
+## What makes cachly different
 
-| 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. |
+| Feature | What it does |
+|---------|-------------|
+| **`causal_trace`** | Root Cause Analysis through memory: problem → chain → solution. **No other system does this.** |
+| **`memory_consolidate`** | Weekly garbage collector — detects contradictions, merges duplicates, expires stale lessons |
+| **`brain_predict`** | Predicts failures before they happen based on past patterns |
+| **Team Brain** | Shared lessons across your whole team with author attribution |
+| **Ambient Git** | git hook auto-extracts lessons from every commit. Zero extra calls. |
+| **Memory Crystals** | Distills all lessons into a compact snapshot for instant session briefing |
+| **11 languages** | BM25+ search in EN, DE, FR, ES, IT, PT, ZH, JA, KO, AR, HE — no config |
 
 **The `causal_trace` moment:**
 ```
@@ -52,93 +100,121 @@ causal_trace(problem="auth breaks after restart")
 → Via:  keycloak:jwks-race  
 → Fix:  PollUntilContextTimeout 3min  ← used this March 12, worked
 ```
-*30 minutes of git blame + log archaeology. In one call.*
+*30 minutes of git blame in one call.*
+
+**The `autopilot` command:**  
+Run `autopilot` once and it generates a fully self-managing `CLAUDE.md` or `copilot-instructions.md` — tailored to your actual Brain content. Every AI (Claude, Cursor, Copilot, Windsurf, Gemini) gets the full ruleset for your project. No copy-paste, no manual writing. As the Brain learns more, re-run `autopilot` to upgrade the file.
 
 ---
 
-## The Problem
+## cachly vs. alternatives
+
+| | cachly | mem0 | MemGPT / Letta | Plain CLAUDE.md |
+|--|--------|------|----------------|-----------------|
+| Persistent memory | ✅ | ✅ | ✅ | Manual |
+| MCP server (no code changes) | ✅ | ✅ | ❌ | ✅ |
+| Causal root cause analysis | ✅ | ❌ | ❌ | ❌ |
+| Fully automatic (no explicit calls) | ✅ | ❌ | ❌ | ❌ |
+| Failure prediction | ✅ | ❌ | ❌ | ❌ |
+| Team knowledge sharing | ✅ | Paid | ❌ | ❌ |
+| Git-ambient learning | ✅ | ❌ | ❌ | ❌ |
+| 11-language search | ✅ | ❌ | ❌ | ❌ |
+| GDPR / EU servers | ✅ | ❌ | ❌ | ✅ |
+| Free tier forever | ✅ | Limited | ❌ | ✅ |
 
-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.
+## MCP Tools (89 total)
 
-## The Fix — One Command
+### 🧠 Session & Memory (most used)
 
-```bash
-npx @cachly-dev/mcp-server@latest setup
-```
+| Tool | What it does |
+|------|-------------|
+| **`session_start`** | Full briefing: last session summary, open failures, recent lessons, brain health |
+| **`session_end`** | Save what you built, auto-extract lessons from summary + git log |
+| **`learn_from_attempts`** | Store structured lessons after any fix, deploy, or discovery |
+| **`recall_best_solution`** | Best known solution for a topic — with success/failure history |
+| **`remember_context`** | Cache architecture findings, decisions, file summaries |
+| **`recall_context`** | Get exact context by key (supports glob) |
+| **`smart_recall`** | BM25+ full-text search across all brain data — 11 languages |
+| **`causal_trace`** | Root cause analysis through memory |
+| **`brain_predict`** | Predict likely failures before they happen |
+| **`memory_consolidate`** | Deduplicate and expire stale lessons |
+| **`compact_recover`** | Full context recovery after hitting context window limit |
 
-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
+### 👥 Team Brain
 
-**Index your project** into the Brain for instant semantic search:
-```bash
-npx @cachly-dev/mcp-server@latest index .
-```
+| Tool | What it does |
+|------|-------------|
+| `team_learn` / `team_recall` | Share lessons across the team with author attribution |
+| `team_synthesize` | Merge conflicting lessons into one canonical version |
+| `madc_deliberate` | 6 specialist AI agents vote to resolve contradictory lessons |
+| `memory_crystalize` | Distill all lessons into a Crystal for instant team context |
+| `brain_doctor` | Health check: lesson count, IQ boost %, open failures |
+| `autopilot` | Generate a self-managing `CLAUDE.md` / `copilot-instructions.md` from Brain content |
+| `global_learn` / `global_recall` | Cross-project universal lessons |
+| `publish_lesson` / `import_public_brain` | Share/import community knowledge |
 
-**Result:** Your AI remembers everything. Always.
+### 🌍 Knowledge Commons (Global)
 
----
+| Tool | What it does |
+|------|-------------|
+| `syndicate` | Contribute verified lesson to global Knowledge Commons |
+| `syndicate_search` | Search community solutions by tech stack |
+| `fedbrain_contribute` | Contribute with cryptographic provenance certificate |
+| `fedbrain_search` | Context-weighted global search |
 
-## Quick Start (Manual)
+### ⚙️ Cache & Infrastructure
 
-**Step 1 — Get your free credentials** at [cachly.dev](https://cachly.dev) (25 MB free, forever, no credit card).
+| Tool | What it does |
+|------|-------------|
+| `list_instances` / `create_instance` / `delete_instance` | Manage Brain instances |
+| `cache_get` / `cache_set` / `cache_delete` | Standard cache operations |
+| `cache_mget` / `cache_mset` | Bulk pipeline (single round-trip) |
+| `semantic_search` | Find cached entries by meaning |
+| `index_project` | Index source files for semantic retrieval |
 
-**Step 2 — Add to your editor's MCP config:**
+### 📋 Roadmap & Planning
 
-<details>
-<summary><b>Claude Code</b> (<code>~/.claude/mcp.json</code> or <code>.mcp.json</code>)</summary>
+| Tool | What it does |
+|------|-------------|
+| `roadmap_add` / `roadmap_update` | Persistent project roadmap stored in Brain |
+| `roadmap_list` / `roadmap_next` | List items or get the single most important next action |
 
-```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.
+## FAQ
 
-**The average developer wastes 45 minutes/day re-establishing context.** That's €15,000+ in lost productivity per engineer per year.
+**Does my AI need to call `session_start` manually?**  
+No. Sessions start and end automatically on the first tool call and when the editor closes.
 
-## The Fix — One Command
+**What happens to memory if I switch projects?**  
+Memory is scoped per Brain instance. You can have one instance per project, or one shared instance across projects.
 
-```bash
-npx @cachly-dev/mcp-server@latest setup
-```
+**Can my whole team share the same Brain?**  
+Yes. `team_learn` / `team_recall` share lessons with author attribution. `memory_crystalize` gives any new team member instant full context.
 
-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
+**What is a Memory Crystal?**  
+A compressed snapshot of all lessons distilled into a compact briefing. Injected at every session start so the AI arrives pre-briefed even with a cold context window.
 
-**Index your project** into the Brain for instant semantic search:
-```bash
-npx @cachly-dev/mcp-server@latest index .
-```
+**What is causal_trace and why is it unique?**  
+Given any error or problem, `causal_trace` walks the Causal Knowledge Graph (CKG) to find: the root cause, intermediate causes, and the exact fix that worked — including the date and commands used. No other memory system builds or queries a causal graph.
 
-**Result:** Your AI remembers everything. Always.
+**How does cachly learn from git commits?**  
+The `setup` wizard installs a git post-commit hook. After each commit, the hook calls `cls_ingest` with the commit message and changed files. The Brain extracts lessons automatically — no `session_end` required.
 
----
+**What happens if I hit the context window limit mid-session?**  
+Call `compact_recover`. It reconstructs full context from the Memory Crystal + recent sessions + WIP registry entries — typically restoring full context in one tool call.
 
-## Quick Start (Manual)
+**Is my code sent to cachly servers?**  
+No code content is stored. cachly stores: lesson text, commit messages, session summaries, and key-value context entries. All data is on German servers, GDPR-compliant.
 
-**Step 1 — Get your free credentials** at [cachly.dev](https://cachly.dev) (25 MB free, forever, no credit card).
+**Does cachly work without an internet connection?**  
+No — cachly is a managed cloud service. The MCP server is a thin client; the Brain runs on cachly's infrastructure.
 
-**Step 2 — Add to your editor's MCP config:**
+---
+
+## Manual Setup (alternative to the wizard)
 
 <details>
 <summary><b>Claude Code</b> (<code>~/.claude/mcp.json</code> or <code>.mcp.json</code>)</summary>
@@ -147,156 +223,31 @@ npx @cachly-dev/mcp-server@latest index .
 {
   "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"
-      }
+      "args": ["-y", "@cachly-dev/mcp-server@latest"]
     }
   }
 }
 ```
+On the first tool call your AI will prompt you to sign in — takes 10 seconds.
 </details>
 
 <details>
-<summary><b>Cursor / Windsurf / VS Code</b> (<code>.cursor/mcp.json</code> / <code>.mcp.json</code>)</summary>
+<summary><b>Cursor / Windsurf / VS Code / Copilot / Cline</b> (<code>.cursor/mcp.json</code> / <code>.mcp.json</code>)</summary>
 
 ```json
 {
-  "servers": {
+  "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"
-      }
+      "args": ["-y", "@cachly-dev/mcp-server@latest"]
     }
   }
 }
 ```
 </details>
 
-**Step 3 — Add to `CLAUDE.md` / `.github/copilot-instructions.md`:**
-
-```markdown
-## AI Brain Rules (cachly)
-- Call session_start BEFORE reading any files or making changes
-- Call learn_from_attempts AFTER every fix, deploy, or discovery
-- Call session_end when closing the window
-```
-
----
-
-## With vs. Without cachly
-
-| Situation | Without cachly | With cachly |
-|-----------|----------------|-------------|
-| Session start | "What's your architecture?" | "Ready. 23 lessons, last session: deployed API." |
-| Known bug hits again | Re-researches from scratch | "You fixed this on March 12, here's the exact command" |
-| After holiday / team handoff | Context dead | Fully briefed in < 10 seconds |
-| Repeated LLM patterns | Pays for each re-discovery | Cached by meaning, ~1,200 tokens saved per hit |
-| New team member | Weeks to onboard | `session_start` gives full context instantly |
-
----
-
-## 51 MCP Tools
-
-### 🧠 Session & Memory (most used)
-
-| Tool | What it does |
-|------|-------------|
-| **`session_start`** | Full briefing: last session summary, open failures, recent lessons, brain health |
-| **`session_end`** | Save what you built, auto-extract lessons from summary + ambient git log |
-| **`session_handoff`** | Hand off remaining tasks to next window, with context |
-| **`auto_learn_session`** | Batch-learn from a list of observations |
-| **`sync_file_changes`** | Sync changed files into brain index |
-| **`learn_from_attempts`** | Store structured lessons after any fix, deploy, or discovery |
-| **`recall_best_solution`** | Best known solution for a topic — with success/failure history |
-| **`recall_at`** | Recall a lesson at a specific point in time |
-| **`remember_context`** | Cache architecture findings, decisions, file summaries |
-| **`recall_context`** | Get exact context by key (supports glob) |
-| **`list_remembered`** | See all cached context entries |
-| **`forget_context`** | Remove stale context |
-| **`smart_recall`** | BM25+ full-text search across all brain data — multilingual: EN, DE, FR, ES, IT, PT, ZH, JA, KO, **AR, HE** |
-| **`setup_ai_memory`** | Interactive wizard to configure AI memory |
-
-### 🌍 Multilingual Brain — Search in Any Language
-
-The Brain's search engine understands **11 languages natively** — no configuration required.
-
-| Script | Languages | Tokenization |
-|--------|-----------|-------------|
-| Latin | EN, DE, FR, ES, IT, PT | Whitespace + stopwords |
-| CJK | Chinese (ZH), Japanese (JA), Korean (KO) | Character bigrams |
-| RTL | Arabic (AR), Hebrew (HE) | Word tokenization + light stemming |
-
-**Romanization matching** — store lessons in Japanese, search in romaji:
-```
-smart_recall("kontena") → finds コンテナ docs
-smart_recall("depuroi") → finds デプロイ docs
-```
-
-**Cross-language retrieval** — 130+ tech term synonyms EN↔JA↔ZH↔KO↔AR↔HE:
-```
-smart_recall("deploy")    → finds デプロイ, 部署, 배포, نشر, פריסה
-smart_recall("デプロイ")  → finds "deploy", "deployment"
-smart_recall("خطأ")       → finds "error", エラー, 错误
-```
-
-### 💡 Legendary Brain Features
-
-| Feature | How it works |
-|---------|-------------|
-| **Team Telepathy** | Multi-dev Brain: the `author` param on `learn_from_attempts` shares fixes across the whole team. Every `session_start` shows colleagues' lessons. |
-| **Ambient Git Learning** | Pass `workspace_path` to `session_end` — it auto-reads `git log`, stores recent commits as Brain lessons. Zero extra calls. |
-| **Memory Crystals** | `memory_crystalize` distills all lessons into a compact Crystal injected at every `session_start`. AI arrives pre-loaded with team knowledge. |
-| **IQ Boost** | `brain_doctor` reports `iq_boost_pct` — how much smarter your AI gets vs. baseline from cached lessons. |
-
-### ⚙️ Instance Management
-
-| Tool | What it does |
-|------|-------------|
-| `list_instances` | List all your cache instances |
-| `create_instance` | Spin up a new instance (free or paid) |
-| `get_connection_string` | Get the `redis://` URL for your app |
-| `delete_instance` | Remove an instance |
-| `get_real_time_stats` | Memory, hit rate, ops/sec |
-
-### 🗄️ Cache Operations
-
-| Tool | What it does |
-|------|-------------|
-| `cache_get` / `cache_set` / `cache_delete` | Standard cache operations |
-| `cache_mget` / `cache_mset` | Bulk pipeline (single round-trip) |
-| `cache_lock_acquire` / `cache_lock_release` | Distributed Redlock-lite |
-| `cache_stream_set` / `cache_stream_get` | LLM token stream caching |
-
-### 🔍 Semantic Cache
-
-| Tool | What it does |
-|------|-------------|
-| `semantic_search` | Find cached entries by meaning (pgvector HNSW, EU-hosted) |
-| `semantic_warmup` | Pre-warm cache with prompt/response pairs |
-| `detect_namespace` | Auto-classify prompt into code/qa/summary/translation/creative |
-
-### 👥 Team Brain
-
-| Tool | What it does |
-|------|-------------|
-| `team_learn` / `team_recall` | Share lessons across the team |
-| `team_synthesize` | Consolidate multiple lessons into one authoritative version |
-| `memory_crystalize` | Distill all lessons into a Crystal snapshot for instant team context |
-| `brain_doctor` | Health check: lesson count, IQ boost %, open failures, quality score |
-| `global_learn` / `global_recall` | Cross-project universal lessons |
-| `publish_lesson` / `import_public_brain` | Share/import community knowledge |
-| `trace_dependency` | Causal chain — find lessons affected by a dependency change |
-| `list_orgs` / `create_org` | Manage team organizations |
-| `invite_member` / `get_org_plan` | Invite a developer to your org by email |
-
 ---
 
 ## Pricing
@@ -306,22 +257,23 @@ smart_recall("خطأ")       → finds "error", エラー, 错误
 | **Free** | 25 MB | **€0/mo forever** | Dev & side projects |
 | **Dev** | 200 MB | €19/mo | Individual developers |
 | **Pro** | 900 MB | €49/mo | Teams |
-| **Speed** | 900 MB + Dragonfly + Semantic Cache | €79/mo | AI-heavy workloads |
+| **Speed** | 900 MB + Dragonfly | €79/mo | AI-heavy workloads |
 | **Business** | 7 GB | €199/mo | Scale-ups |
 
-✅ All plans: **German servers · GDPR-compliant · 99.9% SLA · No credit card for Free tier**
+✅ All plans: **German servers · GDPR-compliant · 99.9% SLA · No credit card for Free**
 
 ---
 
 ## Environment Variables
 
+Set automatically by the setup wizard — only needed for manual configuration.
+
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CACHLY_JWT` | — | **Required.** Your API token from [cachly.dev](https://cachly.dev) |
-| `CACHLY_INSTANCE_ID` | — | Default instance UUID (optional if you pass per-call) |
+| `CACHLY_JWT` | — | API token (set by wizard, or get from cachly.dev) |
+| `CACHLY_BRAIN_INSTANCE_ID` | — | Default instance UUID (optional if passed per-call) |
 | `CACHLY_API_URL` | `https://api.cachly.dev` | Override for self-hosted |
 | `CACHLY_NO_TELEMETRY` | unset | Set to `1` to disable anonymous usage pings |
-| `CACHLY_NO_UPDATE_CHECK` | unset | Set to `1` to disable the version-check on startup |
 
 ---
 
@@ -329,18 +281,15 @@ smart_recall("خطأ")       → finds "error", エラー, 错误
 
 | Package | What it does |
 |---------|-------------|
-| **[`@cachly-dev/mcp-server`](https://www.npmjs.com/package/@cachly-dev/mcp-server)** | ← you are here — AI Brain MCP tools for Claude Code, Cursor, Copilot, Windsurf |
-| **[`@cachly-dev/openclaw`](https://www.npmjs.com/package/@cachly-dev/openclaw)** | JS/TS SDK — cut LLM costs 60–90% with semantic cache + BM25 in your own app, 3 lines of code |
-| **[`@cachly-dev/init`](https://www.npmjs.com/package/@cachly-dev/init)** | One-command setup wizard: auto-detects all your editors and writes the correct MCP config — `npx @cachly-dev/init` |
-| **[`@cachly-dev/cli`](https://www.npmjs.com/package/@cachly-dev/cli)** | Terminal CLI — manage instances, cache data, brain lessons: `npm i -g @cachly-dev/cli` |
-| **[`@cachly-dev/sdk`](https://www.npmjs.com/package/@cachly-dev/sdk)** | Node.js/TypeScript SDK — use managed Redis, semantic cache & AI memory directly in your app |
+| **[`@cachly-dev/mcp-server`](https://www.npmjs.com/package/@cachly-dev/mcp-server)** | ← you are here |
+| **[`@cachly-dev/openclaw`](https://www.npmjs.com/package/@cachly-dev/openclaw)** | Cut LLM costs 60–90% in JS/TS apps |
+| **[`@cachly-dev/cli`](https://www.npmjs.com/package/@cachly-dev/cli)** | Terminal CLI — manage instances and brain |
 
 ---
 
 ## Links
 
 - 🌐 [cachly.dev](https://cachly.dev) — Dashboard & free signup
-- 📖 [AI Brain docs](https://cachly.dev/docs/ai-memory) — Full documentation
-- 💬 [GitHub Issues](https://github.com/cachly-dev/mcp-server/issues) — Bug reports & feature requests
-- ⭐ [Star on GitHub](https://github.com/cachly-dev/mcp-server) — If cachly saves you time, a star means a lot!
-- 📦 [npm](https://www.npmjs.com/package/@cachly-dev/mcp-server)
+- 📖 [Docs](https://cachly.dev/docs/ai-memory) — Full documentation
+- 💬 [GitHub Issues](https://github.com/cachly-dev/cachly-mcp/issues) — Bug reports & feature requests
+- ⭐ [Star on GitHub](https://github.com/cachly-dev/cachly-mcp) — If cachly saves you time, a star means a lot!

package/dist/__tests__/brain-predict-failures.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Unit tests for the brain_predict_failures handler.
+ *
+ * Tests the pure scoring and ranking logic without real Redis:
+ *   - empty brain → "no known failure patterns" message
+ *   - lesson-based predictions: failure-outcome lessons matching context are surfaced
+ *   - deduplication: same failure text appears only once
+ *   - ranking: higher-probability failures come first
+ *   - format=brief: no fix line; format=detailed: fix + lesson lines included
+ *   - high-risk badge: ≥60% probability triggers the ⚠️ warning line
+ *   - no false positives: unrelated lessons are not returned
+ *   - severity boost: critical lessons rank above major ones with equal base score
+ *   - top_k limit: at most top_k results returned
+ *
+ * Run: npx vitest run src/__tests__/brain-predict-failures.test.ts
+ */
+export {};