cachly

Memory for coding agents: stores every fix, decision and trap in your codebase and recalls it when the problem returns. Works in Claude Code, Cursor, VS Code, Windsurf, Zed and JetBrains. EU-hosted, free plan.

Документация

cachly — memory for coding agents (MCP server)

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.

#1 on LoCoMo in the OmniMemEval comparison, 90.71 points (results).

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

The first time cachly needs a key, it opens your browser once: sign in with GitHub, Google or e-mail, and your Brain is ready on EU servers. A new account 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).

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

Claude Code in detail: the three hooks, auto-update, and the sign-in

The plugin adds three Claude Code hooks:

HookWhat it does
SessionStartGives your AI a short briefing: the 5 most-reused lessons (on a new Brain: starter tips)
UserPromptSubmitPuts the lessons that match your prompt next to it
StopSaves a lesson when the AI's last message clearly reports a fix. It skips messages that say something failed or is unclear. It saves quietly.

Turn on auto-update once: /plugin → Marketplaces → cachly → Enable auto-update. Claude Code leaves it off for marketplaces outside Anthropic's own. The MCP server updates itself on every start; the hooks come with the plugin and update with it. If an update is waiting, the first session_start of a session says so in one line.

Without a key, the first tool call opens your browser once to sign in (GitHub, Google or e-mail). claude mcp list is the reliable check: claude plugin details shows MCP servers (0) even while the server runs.

claim revokes every test key and stores a new key where your editor and hooks look for it. The Brain restarts once, which takes about 20 seconds. The Free plan holds one Brain: if you already have one, claim stops with a message and leaves both Brains as they are.

autopilot writes these rule files, so each editor's AI checks its memory before a task: CLAUDE.md, AGENTS.md, .cursor/rules/cachly.mdc, .github/copilot-instructions.md, .windsurfrules, .clinerules, and GEMINI.md, .junie/guidelines.md and .continue/rules/cachly.md where you use Gemini CLI, Junie or Continue. Claude Code and Gemini CLI also follow the server's own instructions; Cline, Continue and Zed rely on the rule file. You can also add the server by hand (see Manual Setup).

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.

Some fixes need a second file. When you store a security fix and none of the files you name is a manifest or lock file, learn_from_attempts says so: across the same 289 projects, 1127 security fixes changed a dependency file more often than other fixes in the same project, 59 % vs 25 % in the largest dataset.

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 teammate@example.com 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

PlanPricePeopleStorage
Free€0125 MB, one Brain, 500 recalls a month
Solo€19/month1200 MB
Team€49/monthup to 5900 MB
Business€199/monthup to 20, with SSO7 GB

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

GuideWhat you find there
Claude Code hooks: which event to use whenSessionStart, UserPromptSubmit, PreToolUse, Stop and more, sorted by when they fire. What each one can block, add and change.
A UserPromptSubmit hook for Claude CodeThe stdin JSON, additionalContext, a working Node script and five traps to avoid.
The same hooks in VS Code and Copilot CLI, Codex CLI and Gemini CLIWhich event takes context in each editor, and the exact file setup writes there.
Comparisons: Supermemory, Zep, claude-mem, Basic Memory, mem0, LettaSide by side, each row with its source and a visible date, including when the other product fits better.
EU-hosted MCP server: what leaves your machineWhere data lands: storage in Germany, embeddings in the EU, the network edge, and a checklist.
Lessons learned for coding agentsHow to write a lesson your agent finds again: symptom, decisive fact first, what failed, files, a check. With examples and a LESSONS.md.
JetBrains plugin guideWhat the plugin does, and how Claude Code, Junie and JetBrains AI Assistant use the Brain.
Repo X-rayEnter a public GitHub repo. In a few seconds you see how many problems its team has solved, and which ones more than once.

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 teammate@example.com. 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.

All tools by area

Session and lessons (most used)

ToolWhat it does
session_startFull briefing: last session, open failures, recent lessons, Brain health
session_endSave what you built; extract lessons from the summary and the git log
learn_from_attemptsStore a structured lesson after any fix, deploy or discovery (with author, visibility)
recall_best_solutionThe known fix for a topic, with its success and failure history
smart_recallHybrid BM25 + semantic + causal-graph search, 11 languages, quality-reranked
remember_contextKeep architecture findings, decisions and file summaries
compact_recoverRecover your context after you hit the context-window limit

Team Brain and org knowledge graph

ToolWhat it does
team_learn / team_recallShare lessons across the team with author attribution
team_confirmA reviewer confirms a lesson (senior or peer); confirmed lessons rank higher in recall
team_assign_role / team_roster / team_whoamiRoles (admin, reviewer, contributor, viewer), enforced once an admin is set
team_auditAdmin-only governance trail: every role change and lesson confirmation
brain_who_knowsFind your team's experts on a topic, ranked from authorship
brain_file_mapExperts and lessons per file, before you touch it
team_expertise_mapThe team's skills matrix in one table
brain_collab_pairsWho works with whom, with bus-factor alerts
brain_portabilityConfig snippets for 7 MCP clients, so the same Brain serves any model
skill_gapsKnowledge blind spots: unresolved failures, missing attribution
brain_coverageA 0–100 health score for the knowledge of your codebase
madc_deliberateSpecialist AI agents vote to resolve contradictory lessons
memory_crystalizeDistill all lessons into a Crystal for instant team context
team_crystallizeA Team Crystal: fixes that 2 or more teammates reached independently

Causal intelligence

ToolWhat it does
causal_traceRoot-cause analysis through the causal knowledge graph
brain_predict / brain_predict_failuresPredict likely failures before they happen
brain_from_gitFill people, files and lessons from git history, incrementally
brain_from_ciBulk-ingest CI outcomes: red→green becomes a fix lesson with a causal fixes edge, green→red a causes edge
memory_consolidateDetect contradictions, merge duplicates, expire stale lessons
ckg_inspectInspect the causal graph around a concept

Example:

causal_trace(problem="auth breaks after restart")

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

Shareable and public Brains

ToolWhat it does
brain_seed_starterSeed 16 universal lessons so your first smart_recall finds something; runs on a fresh repo
brain_sharePublish a Brain snapshot as a link (public or unlisted). For your own data, run npx @cachly-dev/mcp-server export
brain_importImport a shared Brain into yours: topic_prefix, min_confidence, dry_run
brain_share_list / brain_unshareList your shares; revoke one so the link goes dead
brain_discoverSearch the Brain marketplace for ready-made knowledge bases

Knowledge Commons, infrastructure and roadmap

ToolWhat it does
syndicate / fedbrain_searchContribute to, and search, the global Knowledge Commons
brain_marketplace / brain_installBrowse and install curated Domain Brains (Kubernetes, Auth, databases)
cache_get / cache_set / semantic_search / index_projectCache and semantic operations. Pass org_id on cache_get / cache_set to share the cache org-wide
cache_stats / cache_org_statsHits and requests served from the cache, per instance or across your org
list_instances / create_instance / delete_instanceManage Brain instances
roadmap_add / roadmap_nextA project roadmap stored in the Brain

Run health to see what is wired up in your editor. The full catalog is generated from src/tools.ts.

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.

All CLI commands
Every day
statusLessons, recalls and team at a glance
ambient-statsTokens injected vs saved — the honest net, even when negative
doctorDiagnose a broken or missing install, with the fix for each step
healthCheck key, API, editor configs and git hook
digestWhat your Brain learned this week, shareable
Set up
demoPreview your Brain from git history (no account needed)
setup (alias autosetup)Interactive variant: pick editors yourself
init --editor <id>Write the config for one editor, with flags
claimMove a test Brain into your account, lessons included
upgradeCheck for updates
uninstallTake cachly out of this project again. Shows your numbers first, then the plan; --dry-run only lists, --global adds the home folder
Your data
exportWrite every lesson to lessons.md and lessons.jsonl
index [dir]Index a project's code into the Brain (CI-friendly)
learn-git [repo]Learn lessons from recent git commits
Team & sharing
invite <email>Share your Brain with a teammate. They get an email; members can read and learn
join <token>Accept an invitation (the command is in the email) and connect that Brain
join --brain <id>Connect a Brain you already have access to (for example after accepting on the web)
referShow your personal referral link for new users
shareGenerate a shareable stats card
publishPublish your Brain as an importable link (--public)
badgeGet a live README badge for your Brain
More
benchRun the recall benchmark (no sign-in needed)
tool-specs / openapiTool definitions for other agent frameworks (OpenAI, Anthropic, LangChain, OpenAPI)

The method behind bench is described in BENCH.md.

Tip: learn from every merged PR. Run learn-git in CI with the cachly-brain-setup GitHub Action and mode: learn. Each merged PR then teaches your Brain.

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.

Editors, config files and sign-in paths
Editor / clientAuto-setupConfig file writtenGlobal configNotes
Claude Codeyes.mcp.jsonwith the pluginWithout a key: the first tool call opens the browser once to sign in
Cursoryes, detected via .cursor/.cursor/mcp.json, hooks in .cursor/hooks.jsonnoProject-level; restart Cursor after setup. Lessons arrive with the first tool call of a turn
Windsurfyes, detected via .windsurf/.windsurf/mcp.jsonnoProject-level; restart Windsurf after setup
VS Code + Copilotyes, detected via .vscode/.vscode/mcp.json, hooks in .github/hooks/cachly-ambient.jsonnoNeeds the VS Code MCP support or Copilot chat. Briefing at session start, lessons before each prompt
Codex CLIyes, detected via ~/.codex.codex/config.toml ([mcp_servers.cachly]), hooks in .codex/hooks.jsonnoCodex loads both once you trust the folder; confirm the hook once in /hooks
Gemini CLIyes, detected via ~/.geminimcpServers.cachly and hooks in .gemini/settings.jsonnoGemini loads both once you trust the folder. Lessons are appended to the prompt (BeforeAgent)
Clineyes, detected via VS Code.vscode/mcp.jsonnoShares the config with Copilot; restart VS Code
Continue.devyes, detected via .continue/.continue/config.jsonnoUses the modelContextProtocolServers key
Zedyes, detected via .zed/.zed/settings.jsonnoUses the context_servers key
Windsurf (global)autosetup --editor windsurf~/.windsurf/mcp.jsonyesPass --editor to target the global config
Any other MCP clientautosetup --editor claude.mcp.jsonnoStandard mcpServers stdio format

Which sign-in path each case uses:

ScenarioPath
autosetup or autopilot from a terminal (TTY)OAuth device flow: one click in the browser, the API key is saved automatically
autosetup from a VS Code task or CI (no TTY)Detects the non-interactive run, opens the browser with a step-by-step guide, prints the CACHLY_JWT=... autosetup command
First tool call without any keyInline device flow: the browser opens once with a URL and a code; sign in with GitHub, Google or e-mail. The key is saved to ~/.cachly/credentials.json
First tool call with CACHLY_BRAIN_INSTANCE_ID set but no keyInline device flow. You already have a Brain, so no second account is created
CACHLY_JWT=cky_live_xxx npx ... autosetupSkips the sign-in step and uses the key you pass

Manual Setup

Claude Code (.mcp.json in the project)
{
  "mcpServers": {
    "cachly": {
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"]
    }
  }
}

For all your projects at once, use the plugin above, or claude mcp add -s user cachly -- npx -y @cachly-dev/mcp-server@latest (Claude Code stores that in ~/.claude.json).

Without a key, the first tool call opens your browser once to sign in (GitHub, Google or e-mail). Or run npx @cachly-dev/mcp-server@latest autopilot first: it signs you in and writes the config for every editor it finds.

Cursor / Windsurf / VS Code / Copilot / Cline
{
  "mcpServers": {
    "cachly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"]
    }
  }
}
Zed (.zed/settings.json)
{
  "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:

Embedding providers and your own backend
ProviderEnv varsModel
cachly (default, EU servers)none beyond your keymanaged
Ollama (local)OLLAMA_BASE_URL, detected automaticallynomic-embed-text
OpenAICACHLY_EMBED_PROVIDER=openai and OPENAI_API_KEYtext-embedding-3-small
Google GeminiCACHLY_EMBED_PROVIDER=gemini and GEMINI_API_KEYtext-embedding-004
MistralCACHLY_EMBED_PROVIDER=mistral and MISTRAL_API_KEYmistral-embed
CohereCACHLY_EMBED_PROVIDER=cohere and COHERE_API_KEYembed-english-v3.0

Run npx @cachly-dev/mcp-server@latest health to see which provider is active.

Point at your own backend. Every install can talk to a private backend instead of api.cachly.dev:

# 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

autosetup writes CACHLY_API_URL into the editor config only when it differs from the default cloud. Default installs stay clean, and self-hosted installs keep talking to your backend on every editor start.

Environment Variables

All environment variables
VariableDefaultDescription
CACHLY_JWTnoneAPI key. The setup wizard sets it for you
CACHLY_BRAIN_INSTANCE_IDnoneDefault Brain UUID. Optional, it is resolved automatically
CACHLY_API_URLhttps://api.cachly.devOverride for a self-hosted backend
CACHLY_EMBED_PROVIDERautomaticName an embedding provider yourself (see above)
CACHLY_ALLE_WERKZEUGEunsetSet to 1 to list all 124 tools instead of 27
CACHLY_PROFILEunsetlean lists 8 tools plus cachly_tool, recall lists the 3 read-only tools
CACHLY_UPDATE_CHECKonSet to false to stop the version check. It asks registry.npmjs.org for the newest version number of this package, at most once a day, with a 2-second limit
CACHLY_NO_TELEMETRYunsetSet to 1 to disable usage pings. They carry up to 80 characters of smart_recall queries. Your API key travels only in the Authorization header; the API verifies it before it counts the event for your account
CACHLY_LERNENonLearning from use in the prompt hook. For 5 % of prompts the matching lessons are computed but not shown (control group), up to 10 % try a stricter or shorter setting. At the end of each turn the hook reports which setting ran and whether the agent named a shown lesson; topics are sent hashed, prompts never. Set to 0 (or CACHLY_NO_TELEMETRY=1) to turn it off
CACHLY_KONTROLLE_ANTEIL5%Share of prompts in the control group. 0 turns the control group off, at most 50%
CACHLY_ERKUNDUNG10%Share of prompts that may try another setting. 0 keeps the leading setting, at most 10%

Links

WhereWhat you find there
cachly.devSign-up, dashboard and the product page
cachly.dev/pricingPlans, yearly billing and current limits
MCP docs · AI memory docsSetup, tools and concepts
Release notesWhat changed in each version
github.com/cachly-dev/cachly-mcpSource code of this server
GitHub IssuesBugs and feature requests
MCP RegistryThe official entry, io.github.cachly-dev/mcp-server
Cachly Brain for VS CodeStatus bar, lessons view and ambient learning in the editor
Cachly Brain for JetBrainsThe same Brain in IntelliJ IDEA, PyCharm, GoLand, WebStorm and Rider (source)
cachly-dev/cachly-actionGitHub Action: setup, PR risk scan, learning from merged PRs, weekly hygiene
@cachly-dev/openclawSemantic caching for LLM calls in JS/TS apps

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

The Lessons view inside the Cachly Brain VS Code extension, listing six stored lessons


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

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