# cachly-dev/cachly-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/cachly-dev/cachly-mcp  
**GitHub Stars:** 2  
**npm Downloads (last month):** 15210  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cachly-dev-cachly-mcp

## Description
Persistent AI memory brain for Claude Code, Cursor, Copilot, Windsurf, Cline & Zed. sessionstart() briefs your AI on last session, lessons, and open tasks in one call. 84 tools — Team Brain, semantic BM25+ search, Team Telepathy, Ambient Git Learning, Memory Crystals, Analytics, and managed Valkey/Redis. npx @cachly-dev/init — free tier, no credit card. Website

## Tools
Capabilities this server exposes over MCP:

- **cache_get** — Get a value from a running cache instance by key. Returns the stored value (string or deserialized JSON object) or null if the key does not exist or has expired. Read-only — no side effects. Use cache_mget when you need multiple keys in one round-trip. Use cache_exists to check existence without retrieving the value. Use semantic_search when you need fuzzy/vector search across stored values.
- **cache_set** — Set a key-value pair in a running cache instance. Overwrites any existing value at the key — not idempotent for new data. Returns "OK" on success; returns an error if the instance_id is invalid or the instance is paused. Value can be a string or a JSON-serialized object. Optionally set a TTL in seconds (omit for no expiry). Use cache_mset instead for setting multiple keys in a single pipeline round-trip. Use cache_stream_set instead for caching LLM token streams (ordered string chunks).
- **semantic_search** — Find cached entries that are semantically similar to a natural-language query. Read-only — no side effects. Returns an array of objects, each with: key, value, similarity_score (0–1), and namespace. Returns an empty array if no entries meet the similarity threshold. Requires OPENAI_API_KEY (or compatible provider) and the Speed/Business tier with CACHLY_VECTOR_URL. Embeddings are computed server-side and never leave Germany (pgvector HNSW index). Example: "find all cached responses about password reset" or "what did we answer about pricing?". Use cache_get for exact key lookup; use smart_recall for brain lessons.
- **index_project** — Index local source files into the cachly semantic cache so AI assistants can use semantic_search to find relevant files instead of re-reading the whole codebase every time. Walks a directory recursively, reads each matching file, and stores a summary + path as a semantic cache entry (prompt = file path + content excerpt, value = relative path). Requires an embedding provider (OPENAI_API_KEY or CACHLY_EMBED_PROVIDER + key). Run once, then re-run after major refactors. TTL=86400 (24h) keeps entries fresh.
- **remember_context** — Save context information to the cache so you can recall it later without re-computing. Perfect for caching: codebase overviews, file summaries, project structure, frequently-accessed data, or "thinking" results like dependency analysis. The AI assistant can use this to avoid re-reading the entire codebase every time. Overwrites any existing value stored under the same key. Returns { key, stored_at, ttl } confirming the saved context. Example: remember_context("project overview", "This is a Next.js app with...") then later: recall_context("project overview"). Use recall_context to retrieve; use list_remembered to see all stored keys.
- **recall_context** — Retrieve previously saved context from the cache. Returns the saved content or null if not found. Use this at the START of any task to check if you already have relevant context cached, before doing expensive operations like reading many files. Supports glob patterns: "file:*" matches all file summaries, "arch*" matches architecture-related keys.
- **list_remembered** — List all cached context entries for this project. Shows what knowledge the AI assistant has already cached, so you can decide whether to recall existing context or refresh it. Returns: key, category, size, TTL remaining, and a content preview.
- **forget_context** — Delete one or more cached context entries. Use when context is stale or you want to force a fresh analysis. Supports glob patterns: "file:*" deletes all file summaries.
- **learn_from_attempts** — Store a lesson AFTER any non-trivial task (deploy, debug, fix, decision); future sessions recall it. instance_id may be omitted; the configured instance is used — never guess one. If the topic already exists, the write is an UPDATE and REQUIRES `grund` (one line: WHY the previous version was wrong) — without it the update is rejected. A conflicting outcome triggers a contradiction warning. Example: learn_from_attempts(topic="deploy:api", outcome="success", what_worked="PORT 3095 SERVES WHISPER — nohup docker compose up -d", severity="critical")
- **recall_best_solution** — Recall the best known solution for a topic from past lessons. Call this BEFORE attempting any task that might have been done before. Returns the most recent successful lesson for the topic, with confidence indicator. ⚠️ badge = lesson is >5d old (verify before applying). 🔴 = >10d old (likely stale!). Recalling a lesson resets its confidence clock to 1.0 (marks as recently verified). A superseded lesson shows a banner naming its successor; if the successor was deleted, the banner says so and the lesson counts as the best remaining answer. Example: recall_best_solution(topic="deploy:web") → returns the working deploy command.
- **smart_recall** — Semantically search cached context using natural language. instance_id may be omitted; the configured instance is used — never guess one.Instead of exact key matching, finds context by meaning. Example: smart_recall("how does authentication work") → returns cached auth architecture summary. Falls back to remember_context keys if no semantic match is found.
- **session_start** — Single-call session briefing. Call this at the START of every session INSTEAD of multiple separate smart_recall/recall_best_solution calls. Returns: last session summary, recent lessons sorted by recency, relevant lessons for your focus area, open failures (topics with only failure outcomes), brain health stats, team telepathy (what teammates learned this week), predictive pre-warnings (if your focus area has known failure patterns), and memory crystals (compressed wisdom from old sessions). Also saves a session start marker so session_end can compute duration.
- **session_end** — Save a session summary when you finish working. Records what was accomplished, files changed, and lesson count. The next session_start will show this summary as "Last session". Call this when ending a work session, before going idle, or before summarizing. Ambient Learning: if workspace_path is provided, reads git log since session start and auto-learns from commits.
- **session_handoff** — Save a detailed handoff for the NEXT chat window / session. Stores: current progress, TODO list (done + remaining), changed files with descriptions, instructions for the next assistant, and any incomplete work. The next session_start automatically includes this handoff so the new window knows EXACTLY what happened and what remains. Call this BEFORE closing a chat window, especially if work is incomplete. This prevents the "continue" problem where new windows lose context, skip tasks, or produce broken code.
- **team_learn** — Store a lesson in a shared team brain so all team members benefit. Like learn_from_attempts, but REQUIRES an author name for attribution. Shows up in team_recall with "by <author>" so the team knows who learned it.
- **team_recall** — Recall lessons from a shared team brain, showing who learned what. Works on any shared instance (all team members using the same instance_id). Shows author, recency, and severity for each lesson. Use this to onboard new team members or find who knows about a topic.
- **roadmap_add** — Add a new item to the persistent project roadmap stored in the Brain. Items survive across sessions and editors — the roadmap is always up to date. Use for features, bugs, refactors, or any planned work. Call roadmap_list to see all open items, roadmap_next to get the next actionable item.
- **roadmap_update** — Update the status, priority, or details of a roadmap item. Use to move items through the lifecycle: planned → in-progress → done (or blocked/cancelled). Also use to add notes/findings while working on an item.
- **roadmap_list** — List all roadmap items, optionally filtered by status, priority, tag, or milestone. Returns items sorted by priority then creation date. Called automatically by session_start to show open work.
- **roadmap_next** — Get the single most important next actionable roadmap item. Returns the highest-priority in-progress item first, then planned items, sorted by priority. Call at session start to immediately know what to work on next.
- **brain_doctor** — Check the health of your AI Brain and get actionable recommendations. Reports: lesson count, context entries, last session age, open failures, quality score, effective IQ boost, stale index. Returns a prioritized list of issues with fix instructions.
- **causal_trace** — Root Cause Analysis through memory: given a problem description, traces the causal chain from root cause through intermediate failures to the current symptom, then surfaces the exact solution that worked before. Read-only — does not modify any stored data. Requires prior learning: brain must have lessons stored via learn_from_attempts or brain_from_git. Returns an ordered chain of concepts with confidence scores plus the matching solution; returns an empty chain with a message if no causal path is found. Example: causal_trace(problem="auth breaks after restart") → "Root: k8s:namespace-terminating → keycloak:jwks-race → Solution: PollUntilContextTimeout 3min". Use recall_best_solution for direct topic lookup, syndicate_search for community patterns, and causal_trace when you have a symptom and need the full root-cause chain.
- **autopilot** — Generate a CLAUDE.md / copilot-instructions.md that makes any AI self-managing forever. Writes a configuration file to disk — will overwrite an existing file at the target path. No auth required beyond a valid instance_id. The generated file instructs Claude, Cursor, Copilot, Windsurf, or Gemini to automatically call session_start at window open, learn_from_attempts after every fix, and session_end before closing — without being asked. Returns the generated file content as a string and the path where it was written. Use style="minimal" for just the three hooks; style="full" for the complete ruleset with examples. One command. Every AI. Always on. Use setup_ai_memory instead if you want an interactive one-shot setup that also creates an instance.
- **brain_search** — BM25+ full-text search over ALL brain data: lessons, context entries, session history, CKG nodes, roadmap items. Unlike smart_recall (which focuses on lessons + context), brain_search casts a wider net. Use when smart_recall returns nothing or when you want to find anything the brain knows about a topic.
- **brain_predict** — READ-ONLY — no side effects, no writes, no external network calls. Predictive Pre-fetch Engine (PPE): given your current context, reads the CKG in your Redis instance to predict likely failures and return the highest-confidence fixes. "Pre-load" means results are returned inline — nothing is cached or persisted. Requires a valid instance_id (your Redis brain). No rate limits. Call at session start when working on a specific feature or debugging area. Set scope="org" to widen prediction across your whole organisation — surfaces cross-team risks ("failed 3× across 2 other teams") from the Org Knowledge Graph, so an incident in one team becomes a vaccine for yours.
- **brain_from_git** — Bootstrap brain lessons from git history. Parses commit messages and infers fix/feature/refactor lessons automatically. Great for onboarding an existing codebase — run once and the brain instantly knows your team's accumulated patterns. Incremental by default: only processes new commits since the last run, so repeated calls are fast. Emits progress updates to stderr during long scans.
- **cachly_tool** — Run any of cachly's specialist tools by name.

The most-used tools are listed separately above. This one reaches the
other 98 without their schemas taking up room in every request.

Unsure about a tool's arguments? Call it with describe:true first — that
returns its input schema instead of running it.

Available: list_instances, create_instance, get_instance, get_connection_string, delete_instance, cache_delete, cache_exists, cache_ttl, cache_keys, cache_stats, detect_namespace, cache_warmup, cache_mset, cache_mget, cache_lock_acquire, cache_lock_release, get_api_status, recall_feedback, lesson_verified, session_start_summary, session_ping, auto_learn_session, brain_who_knows, brain_file_map, team_expertise_map, brain_collab_pairs, brain_portability, skill_gaps, brain_coverage, brain_metrics, brain_changelog, brain_service_map, sync_file_changes, team_confirm, team_assign_role, team_whoami, team_roster, team_audit, team_grant_scope, team_scopes, team_synthesize, memory_crystalize, team_crystallize, brain_hygiene, global_learn, global_recall, publish_lesson, import_public_brain, recall_at, trace_dependency, list_orgs, create_org, invite_member, get_org_plan, setup_ai_memory, cache_stream_set, cache_stream_get, cache_org_stats, set_cost_per_call, memory_consolidate, brain_diff, knowledge_decay, syndicate, syndicate_search, syndicate_stats, syndicate_trending, brain_marketplace, brain_install, ckg_inspect, brain_plan, brain_conflicts, brain_resolve_conflict, brain_confirm_ci, brain_briefing, brain_contribute_signal, brain_import_meta, madc_deliberate, cls_ingest, cls_install_hooks, fedbrain_contribute, fedbrain_search, fedbrain_confirm, fedbrain_status, brain_federate, crystal_view, compact_recover, brain_from_ci, brain_watch, brain_predict_failures, brain_share, brain_import, brain_share_list, brain_unshare, brain_discover, brain_seed_starter, brain_graph, brain_set_pref, brain_get_pref

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What cachly-dev/cachly-mcp does

cachly-dev/cachly-mcp gives coding agents a persistent memory layer connected to Cachly. Agents can save context, lessons, session summaries, handoffs, roadmap items, and shared team knowledge, then retrieve that information during later tasks. The service also exposes cache operations for key-value data and a dispatcher for specialist Cachly functions.

The memory is organized around a Brain stored on EU servers. Lessons can record topics, outcomes, successful approaches, failed attempts, severity, file paths, commands, and authors. Shared lessons help teammates learn from one another, while roadmap records preserve planned, active, blocked, and completed work.

## How it works

At the beginning of a work period, `session_start` returns a briefing with the previous session, recent and relevant lessons, open failures, roadmap information, team discoveries, predictive warnings, and older condensed knowledge. `session_end` records accomplishments, changed files, and lesson counts. `session_handoff` preserves progress and remaining tasks for the next chat window.

`smart_recall` searches remembered context by meaning, while `brain_search` searches more broadly across lessons, context, sessions, knowledge-graph data, and roadmap items. `recall_best_solution` finds the strongest known solution for a topic. `causal_trace` follows stored relationships from a symptom toward a root cause and a previously successful fix. `brain_predict` uses stored knowledge to surface likely failure patterns.

Git-oriented tools can infer lessons from commit history, and session completion can learn from commits made during the session. `index_project` stores file summaries and paths for later semantic lookup rather than requiring an agent to reread the entire project.

## Setup and configuration

Claude Code can install the Cachly plugin through its marketplace commands. Other supported editors can use the `autopilot` command, which detects editors, writes their MCP configuration and instruction files, and adds a Git hook for learning from commits. A browser sign-in associates the Brain with an account; without a key, the first session can create a test Brain on EU servers.

The npm package can also be run with the `@latest` tag. The VS Code extension and JetBrains plugin provide editor-specific setup paths. After configuration, restart the editor. `claude mcp list` can verify the Claude Code connection.

## Tools and capabilities

- Save and retrieve project context with `remember_context`, `recall_context`, `list_remembered`, and `forget_context`.
- Record and recall lessons with `learn_from_attempts` and `recall_best_solution`.
- Brief, close, and hand off sessions with `session_start`, `session_end`, and `session_handoff`.
- Share knowledge through `team_learn` and `team_recall`.
- Manage persistent work with `roadmap_add`, `roadmap_update`, `roadmap_list`, and `roadmap_next`.
- Search memory using semantic, BM25-based, or causal queries.
- Inspect Brain health with `brain_doctor` and related analytics tools.
- Store, retrieve, and search cache values through the cache tools.
- Access less frequently used specialist functions through `cachly_tool`; calling it with `describe:true` returns a tool schema before execution.

## Limitations and notes

Semantic search and project indexing require an embedding provider. The documented options include `OPENAI_API_KEY` or a compatible provider configuration; vector search also requires the appropriate Cachly tier and `CACHLY_VECTOR_URL`. Exact key lookup and context recall are separate from semantic search, so the matching tool depends on whether the agent knows the key or only the meaning.

Some editors receive MCP instructions automatically, while others rely on the rule files created by `autopilot`. The `autopilot` command writes configuration files and can overwrite an existing target file. Cached project entries from `index_project` use a 24-hour TTL and should be refreshed after major refactors. Lessons and other Brain data can be exported with the package’s export command.

_Full upstream README: https://allmcps.com/mcp/cachly-dev-cachly-mcp/readme_