cachly-dev/cachly-mcp

Solve it once. From then on, your AI knows.

Every fix, decision and dead end becomes a lesson. Your AI finds it again when the same problem comes back, in the next session, in another editor, or on a teammate's machine.

npm version License: Apache-2.0 MCP Registry Hosted in the EU

Works with Claude Code · Cursor · GitHub Copilot · Windsurf · Cline · Continue.dev · Zed · Codex CLI · Gemini CLI · JetBrains IDEs

Quick start · What it looks like · Pricing · FAQ · Reference · cachly.dev

Quick start

Claude Code — two lines, and the next session has a Brain (the store of your lessons):

/plugin marketplace add cachly-dev/cachly-mcp
/plugin install cachly-brain@cachly

cachly creates a test Brain on EU servers when the session starts. It comes with 14 days of the Solo plan and then continues on Free with the same key. Check it with claude mcp list: you should see plugin:cachly-brain:cachly … ✔ Connected.

Cursor, Windsurf, VS Code, Cline, Continue.dev, Zed, Codex CLI, Gemini CLI — one command:

npx @cachly-dev/mcp-server@latest autopilot

autopilot finds your editors, writes the MCP config and the rule file for each, adds a git hook that learns from your commits, and fills your Brain from your git history. You sign in once in the browser with a device code. Restart your editor afterwards.

Already inside Claude, Cursor or Copilot? Paste this to your AI:

Set up cachly for this project. Run: npx @cachly-dev/mcp-server@latest autopilot
Follow the browser sign-in, then restart the editor.

In the IDE: the VS Code extension creates your Brain on first start. The JetBrains plugin brings it to IntelliJ IDEA, PyCharm, GoLand, WebStorm and Rider (guide).

Keep your test Brain with npx @cachly-dev/mcp-server@latest claim. You sign in once, and the Brain moves into your account with all its lessons.

What it looks like

Monday, your AI fixes a bug and keeps what worked (output shortened):

learn_from_attempts(topic="billing:invoice-rounding", outcome="success",
  what_worked="ROUND HALF-EVEN IN invoice_total(): Math.round drifted by one cent on .5 values",
  file_paths=["src/billing/invoice.ts"])

✅ Lesson stored: billing:invoice-rounding

Three weeks later, a new session, a different person, the same symptom:

smart_recall(query="invoice total is one cent off")

💡 billing:invoice-rounding · 👤 anna
   ROUND HALF-EVEN IN invoice_total(): Math.round drifted by one cent on .5 values
   ▸ src/billing/invoice.ts

Your AI starts from the fix. With the hooks, this happens before you type: the matching lessons are placed next to your prompt.

Some fixes come back. After a time/date or a dependency fix, learn_from_attempts adds a relapse watch with counted numbers from 289 open-source projects. For example: 148 of 791 time/date fixes (19 %) were followed within 90 days by another time/date problem in the same files, 4.4× as often as a random issue in the same project. Each hint links a real pair of issues as an example.

Why developers and teams use it

• Your AI keeps what it learned. Lessons outlive the session, the editor and the model. One Brain serves Claude Code, Cursor, Copilot, Codex and the others at the same time.
• Your team learns each thing once. invite [email protected] shares your Brain. Every lesson carries the name of whoever learned it, and a reviewer can confirm it so it ranks higher.
• A light footprint in the context window. Your editor lists 27 tool entries, about 8,000 tokens per request. All 124 MCP tools stay one call away through cachly_tool.
• Your data stays in the EU and stays yours. Storage in Germany, embeddings computed in the EU, and export writes every lesson to Markdown and JSONL whenever you like. The server is open source under Apache-2.0.

How it works

1. A fix, a decision or a dead end is stored as a lesson: topic, what worked, what failed, severity, file paths, commands and author.
2. At the start of a session, your AI receives a briefing with the last session, open failures and recent lessons.
3. When you ask for something, smart_recall looks up the lessons that match. It combines keyword search (BM25), meaning-based search and the causal graph, in 11 languages.
4. When an error appears, causal_trace walks from the symptom to the cause and to the fix that worked.
5. Before a deploy, brain_predict lists failure patterns from past incidents.
6. A git hook and the CI templates add lessons from commits and from red-to-green runs.
7. Lessons are shared in the team. Each one carries the name of whoever learned it.

See it on your own project first: npx @cachly-dev/mcp-server@latest demo reads your git history and prints the fixes, patterns and decisions your AI would know. It runs entirely on your machine.

Our agreement with you. You can leave and take your data: npx @cachly-dev/mcp-server@latest export writes every lesson to lessons.md (to read) and lessons.jsonl (to reuse). Code excerpts are stored only when you call index_project yourself, and then only on your own EU instance. Read what leaves your machine before you decide.

Pricing

Start on Free with a sign-in, without a credit card. Organisations are free; you pay per Brain plan. Yearly billing and the current limits are on cachly.dev/pricing.

Guides

FAQ

How is this different from a CLAUDE.md or a memory folder? A rule file is read in full in every session, so it grows and costs tokens each time. cachly keeps lessons outside the prompt and places only the matching ones next to it, ranked by outcome and review. The comparisons show where a plain file or another product fits better.

Does my AI need to call session_start by hand? No. A session starts on the first tool call and ends when the editor closes.

Can my whole team share one Brain? Yes. Use team_learn and team_recall, and invite people with npx @cachly-dev/mcp-server@latest invite [email protected]. They get an email and accept it with the link or with join <token>. Members can read and learn; deleting the Brain, rotating its password and billing stay with the owner.

Is my code sent to cachly servers? Only if you call index_project yourself. It stores a short excerpt (up to summary_chars, 1200 characters by default) per indexed file, on your own EU instance. Every other tool stores lesson text, commit messages, session summaries and key-value context, but no source code. Storage is in Germany and embeddings are computed in the EU. API traffic passes through Cloudflare, a US company. The EU guide lists every data flow.

What is causal_trace? Given an error, it walks the causal knowledge graph to find the root cause, the intermediate causes and the fix that worked, with its date and commands.

What if I hit the context-window limit mid-session? Call compact_recover. It rebuilds your context from the Crystal, the recent sessions and the registry of work in progress. Usually one tool call is enough.

How do I write lessons my agent finds again? Lead with the decisive fact. The lessons guide shows how, with examples.

Reference

Everything below is for looking things up. The long tables open with a click.

MCP Tools (124 total, 27 listed by default)

Your editor sees 27 entries by default: the daily tools (26 of them) and one dispatcher, cachly_tool. This is on purpose. The full list of 124 costs about 28,000 tokens in every request. The 27 listed entries cost about 8,000. All other tools (98 of them) run through the dispatcher:

cachly_tool(tool: "team_roster")                  run any of them by name
cachly_tool(tool: "team_roster", describe: true)  get its schema first

Every tool stays reachable. The server dispatches by name, so team_roster called directly still works. Set CACHLY_ALLE_WERKZEUGE=1 to list all 124. Set CACHLY_PROFILE=lean to list 8 plus cachly_tool, or CACHLY_PROFILE=recall to list the 3 read-only tools.

causal_trace(problem="auth breaks after restart")

→ Root: k8s:namespace-terminating
→ Via:  keycloak:jwks-race
→ Fix:  PollUntilContextTimeout 3min

CLI commands

npx @cachly-dev/mcp-server@latest autopilot # One command: signs in, configures every editor, fills the Brain from git

Every command below runs as npx @cachly-dev/mcp-server@latest <command>. Key and Brain instance come from the environment or from ~/.cachly/credentials.json, the file autopilot writes.

CI integration

Every CI run is a lesson. A red→green transition is a proven fix, and a green→red one is a known cause. Ready-to-paste templates live in src/ci-integration/:

• GitHub Actions: use cachly-dev/cachly-action. It needs the secrets CACHLY_API_KEY and CACHLY_BRAIN_INSTANCE_ID.
• GitLab CI: pull in the GitLab template with include: remote:. It adds hidden jobs for learn, scan, confirm and hygiene; extend the ones you want.
• Anything else: push-ci-outcome.mjs is a standalone Node.js helper with no dependencies. It always exits 0, so your CI never fails because of a Brain push.

Already have months of CI history? The brain_from_ci tool ingests past outcomes in one call, the way brain_from_git ingests commits.

Editor support matrix

npx @cachly-dev/mcp-server@latest autopilot detects and configures the editors below. Manual snippets are in Manual Setup.

Manual Setup

{
  "mcpServers": {
    "cachly": {
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"]
    }
  }
}

{
  "mcpServers": {
    "cachly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"]
    }
  }
}

{
  "context_servers": {
    "cachly": {
      "command": {
        "path": "npx",
        "args": ["-y", "@cachly-dev/mcp-server@latest"]
      }
    }
  }
}

Self-hosting and bring-your-own embeddings

Embeddings turn text into vectors for the meaning-based search. By default, cachly computes them on its own servers in the EU as soon as you are signed in. Your text goes to a third-party provider only when you name that provider yourself:

# One command: run the setup against your self-hosted backend
npx @cachly-dev/mcp-server@latest autopilot --api-url https://cachly.mycorp.internal

# Or without prompts
npx @cachly-dev/mcp-server@latest autosetup \
  --instance-id <uuid> --api-key <cky_live_...> \
  --api-url https://cachly.mycorp.internal

Environment Variables

Links

The VS Code extension shows the same Brain in the editor:

Solve it once. From then on, your AI knows.

npx @cachly-dev/mcp-server@latest autopilot