# cachly-dev/cachly-mcp [Health: Active] **Category:** 🧠 Knowledge & Memory **Repository:** https://github.com/cachly-dev/cachly-mcp **GitHub Stars:** 2 **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: - **list_instances** β€” List all your cachly cache instances with their status and connection details. Read-only. Returns an array of instance objects β€” each with id, name, tier, status, region, RAM, and redis:// connection string. Returns an empty array if no instances exist. No pagination: all instances are returned in one call (typical accounts have < 20). Use this first to discover instance UUIDs required by get_instance, cache_get, cache_set, and all other cache tools. Use get_instance to retrieve full metadata for a single instance. - **create_instance** β€” Create a new managed Valkey/Redis cache instance on cachly.dev. Free tier provisions in ~30 seconds. Paid tiers return a Stripe checkout URL. Available tiers: free (25 MB), dev (200 MB, €19/mo), pro (900 MB, €49/mo), speed (900 MB Dragonfly + Semantic Cache, €79/mo), business (7 GB, €199/mo). - **get_instance** β€” Get full metadata for a specific cache instance: name, tier, status (provisioning / running / paused), region, RAM limit, Redis connection string, created_at, and expiry. Read-only. Returns an error if the instance_id is not found or belongs to another account. Call list_instances first to discover valid UUIDs. Use get_connection_string instead if you only need the redis:// URL for your app config. - **get_connection_string** β€” Get the Redis/Valkey connection string (redis:// URL) for a running instance. Use this to configure your application or set environment variables. - **delete_instance** β€” Permanently delete a cache instance. Deprovisions the Kubernetes workload and removes all data. This action is irreversible. - **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). - **cache_delete** β€” Permanently delete one or more keys from a running cache instance (uses Redis DEL). This operation is destructive and irreversible β€” deleted keys cannot be recovered. Deleting a non-existent key is safe and returns 0 for that key (no error). Returns the count of keys that were actually deleted (existing keys only). Use this to explicitly remove stale entries; prefer cache_set with a short TTL for auto-expiring data. Do NOT use this to clear an entire instance β€” use the dashboard or delete_instance for that. - **cache_exists** β€” Check whether one or more keys exist in a running cache instance (uses Redis EXISTS). Read-only β€” no side effects. Returns the count of keys that currently exist (integer 0 to N). If none of the keys exist, returns 0. If all exist, returns the total key count passed in. Duplicate keys in the input array are each counted separately (Redis behavior). Use this to check presence before a cache_get to avoid null handling, or to verify a cache warm-up completed. Use cache_get instead if you also need the value; use cache_ttl if you need expiry info. - **cache_ttl** β€” Get the remaining time-to-live (TTL) of a key in seconds. Returns -1 if the key exists but has no expiry, -2 if the key does not exist. Read-only β€” no side effects. Use cache_set with a ttl parameter to set or update the expiry. - **cache_keys** β€” List keys in a cache instance matching an optional glob pattern (e.g. "user:*", "session:*"). Uses SCAN to avoid blocking the server. Returns at most `count` keys. - **cache_stats** β€” Get real-time stats for a cache instance: memory usage, hit/miss rate, commands/sec, connected clients, keyspace info, and uptime. Read-only β€” no side effects. The instance_id identifies the target instance (obtain from list_instances). Use this for monitoring, capacity planning, or debugging performance issues β€” not for reading cached values (use cache_get for that). Use cache_exists or cache_ttl if you only need key-level information. - **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. - **detect_namespace** β€” Classify a prompt into one of 5 semantic namespaces using text heuristics. Overhead: <0.1 ms, no embedding required. Useful to understand which namespace cachly will use for a given prompt. Returns one of: cachly:sem:code, cachly:sem:translation, cachly:sem:summary, cachly:sem:qa, cachly:sem:creative. - **cache_warmup** β€” Pre-warm the semantic cache with a list of prompt/value pairs. For each entry: computes an embedding, checks if a similar entry already exists (similarity β‰₯ 0.98), and writes new entries to Valkey + pgvector index. Use this to seed FAQ responses, product descriptions, or known-good LLM answers before the first real user traffic. Requires OPENAI_API_KEY. - **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. - **cache_mset** β€” Set multiple key-value pairs in a single pipeline round-trip. Supports per-key TTL – unlike native MSET. Uses one TCP round-trip for N keys via Redis pipeline. Each item overwrites any existing value for that key. On partial failure the successfully pipelined keys are committed; a per-key error list is returned for any that failed. Returns a summary: { set: N, errors: [...] }. Use cache_set for a single key; use cache_stream_set for large streaming payloads. - **cache_mget** β€” Retrieve multiple keys in one round-trip using native Redis MGET. Returns values in the same order as the keys array; missing keys are null. - **cache_lock_acquire** β€” Acquire a distributed lock using Redis SET NX PX (Redlock-lite). Returns a fencing token on success. The lock auto-expires after ttl_ms to prevent deadlocks. Use cache_lock_release to free the lock early. - **cache_lock_release** β€” Release a previously acquired distributed lock. Uses a Lua script for atomic release – only deletes the key if the fencing token matches. - **get_api_status** β€” Full diagnostic for your cachly Brain β€” call this FIRST whenever anything is not working. Returns: API reachability, JWT validity + expiry, your user ID, all Brain instances with live status (🟒 running / 🟑 provisioning / πŸ”΄ stopped), Redis ping on the active connection, and actionable fix steps for every issue found. Workflow: run get_api_status β†’ read the issue it flags β†’ fix it β†’ retry your tool. - **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 learned from a failed or successful attempt. Call this AFTER completing any non-trivial task (deploy, debug, fix, architecture decision). The lesson will be recalled automatically in future sessions via recall_best_solution. Fields: topic (short slug like "deploy:web"), outcome ("success"|"failure"), what_worked (what solved it), what_failed (what did NOT work), context (extra details). Supports structured metadata: severity, file_paths (files involved), commands (working commands), tags. Deduplication: if a lesson for this topic already exists, it is updated with full audit trail. Contradiction detection: warns if new outcome conflicts with existing lesson outcome. Confidence: lesson starts at 1.0, decays after 5d (β†’0.7) and 10d (β†’0.5) without recall. Example: learn_from_attempts(topic="deploy:api", outcome="success", what_worked="nohup docker compose up -d --build", what_failed="docker compose up hangs on SSH timeout", severity="critical", commands=["nohup docker compose up -d --build"]) - **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). Example: recall_best_solution(topic="deploy:web") β†’ returns the working deploy command. - **smart_recall** β€” Semantically search cached context using natural language. 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_start_summary** β€” Focused session briefing for large brains. Returns only the top-N most relevant lessons for the given focus topic, scored by relevance, recall count, severity, recency, and outcome. Ideal when session_start returns too many lessons to fit in context (1000+ lesson brains). Use session_start for the full briefing including handoffs, streak, roadmap, and team telepathy. - **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. - **session_ping** β€” Lightweight checkpoint β€” call this every ~5 tool calls or whenever you complete a significant step. Stores the current task + files touched so session_start on the NEXT provider can reconstruct what happened even if session_end was never called (e.g. Claude context limit hit, window crashed). This solves the provider-switching problem: Claude β†’ Copilot β†’ Cursor all see the same last checkpoint. Extremely fast β€” one Redis SET, no blocking operations. - **auto_learn_session** β€” Auto-learn from a list of session observations WITHOUT explicit learn_from_attempts calls. Pass what happened (commands run, errors seen, solutions found) and the brain classifies and stores lessons automatically. Use at session_end to capture everything you did, even if you forgot to call learn_from_attempts. Returns a summary of what was auto-stored. - **brain_who_knows** β€” Find who in your team has the most expertise on a given topic. Queries the org-wide knowledge graph (built automatically from learn_from_attempts author fields) and returns a ranked list of contributors whose lessons match the query, ordered by lesson count and confidence. Use to find the right person to ask before starting a task, or to understand knowledge distribution. Example: brain_who_knows(topic="kubernetes deployment") β†’ "πŸ₯‡ alice β€” 5 lessons, 94% confidence". - **brain_file_map** β€” Show what cachly knows about a list of files β€” experts + related lessons per file. Call this before starting work on unfamiliar files, or in sync_file_changes to see what knowledge exists. For each file path: shows who has previously touched it (from learn_from_attempts author+file_paths) and which lessons reference it. Example: brain_file_map(file_paths=["src/auth/jwt.ts"]) β†’ "πŸ₯‡ alice (3Γ— Β· today) β€” related: fix:jwt-expiry". - **team_expertise_map** β€” Full team expertise overview β€” who knows what, at a glance. Returns a ranked table of all contributors with their lesson count, top domains, and last-active date. Use for onboarding (who to ask about X?), retrospectives, or to find knowledge gaps. Built automatically from learn_from_attempts(author=...) calls β€” no setup needed. - **brain_collab_pairs** β€” Show the Person↔Person Collaboration Graph for your team (W5). Lists every pair of contributors who have worked together β€” either by touching the same files in learn_from_attempts or by recalling each other's lessons via smart_recall(requester=...). Each pair includes a "Frag @X und @Y" routing suggestion β€” ideal for onboarding and bus-factor analysis. Also flags solo contributors whose knowledge no teammate has yet recalled (bus-factor risk). Example: brain_collab_pairs() β†’ "@alice ↔ @bob β€” 12 events Β· ask them together about auth/payments". - **brain_portability** β€” W9 β€” Model-Neutrality as Feature. Proves "Bring your own model, keep your brain." Returns your Brain ID plus ready-to-paste MCP config snippets for every compatible AI client: Claude Code, Cursor, Windsurf, GitHub Copilot (VS Code), Cline, Zed, Continue. All 7 clients connect to the same Brain β€” same lessons, crystals, predictions, and team data. Use autopilot to configure all detected editors in one command. Example: brain_portability() β†’ config blocks for 7 clients + model-neutrality proof table. - **skill_gaps** β€” Show knowledge blind spots in your Brain β€” domains with unresolved failures, lessons with missing attribution, and areas where brain_who_knows cannot help. Run periodically to find where to focus knowledge capture effort. Returns a prioritized list: πŸ”΄ critical (failures with no solutions) β†’ 🟑 warn β†’ πŸ”΅ info. Pairs with brain_coverage for a full knowledge-health picture. - **brain_coverage** β€” Knowledge-coverage health score for your codebase β€” scored 0-100. Reports: total lessons, success ratio, attribution completeness, team engagement, and file coverage vs git ls-files. Run after brain_from_git or periodically to track knowledge-capture progress. Use skill_gaps to find what to fix. Example: brain_coverage() β†’ "🟒 Overall score: 78/100 Β· 42 lessons Β· 6 contributors Β· 31% files covered". - **brain_metrics** β€” Report the three decisive Brain metrics: (1) time-to-first-recall (onboarding friction), (2) recall-lift vs. raw BM25 (the moat proof, from Cachly-Bench), and (3) team-knowledge-reuse β€” what % of proven recalls used a teammate's lesson. Use to track whether the Brain is delivering its core value. Pass author="handle" to smart_recall so cross-author reuse can be measured. - **brain_changelog** β€” Generate a human-readable Markdown changelog of lessons learned in the last N days. Groups lessons by topic category, annotates with author, recall count and confidence. Ideal for weekly standups, sprint retros, or async team updates β€” share the output directly in Slack or a doc. Example: brain_changelog(instance_id="...", days=7) β†’ grouped Markdown changelog of the week's learning. - **brain_service_map** β€” Map everything the Brain knows about a running service or system: who operates it, which files run in it, every known failure, and every proven fix. Built from lessons tagged with `service="..."` in learn_from_attempts. Ideal for incident triage β€” when a service is misbehaving (e.g. a restarting pod), instantly surface who knows it and what has gone wrong with it before. Example: brain_service_map(service="prometheus") β†’ operators, known OOM failures, and the fixes that worked. - **sync_file_changes** β€” Associate recent file changes with brain knowledge. Pass a list of changed file paths (from `git diff --stat`). Returns lessons relevant to those files, and records the file changes in session history. Call this after commits so the brain tracks what changed and why. - **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 " so the team knows who learned it. - **team_confirm** β€” Endorse (review-confirm) a team lesson so trusted, human-reviewed knowledge ranks above unreviewed auto-learned entries. A senior review weighs more than a peer review; distinct endorsements add a small boost. Confirmed lessons surface higher in smart_recall and team_recall and carry a πŸ›‘οΈ/βœ”οΈ badge. Use this in code review or knowledge reviews to bless the canonical solution for a topic. - **team_assign_role** β€” Assign a role (admin | reviewer | contributor | viewer) to a team member on a shared brain instance. Roles control what each person can do: admin can manage roles and delete lessons; reviewer can senior-review (πŸ›‘οΈ badge, stronger recall boost); contributor can store lessons and peer-review (βœ”οΈ badge); viewer is read-only. First call bootstraps governance (no auth required when no admins exist yet). After that, only an admin can assign or change roles. Example: team_assign_role(handle="alice", role="reviewer", assigned_by="bob") β€” bob must be an admin. - **team_whoami** β€” Show your own role and capabilities on a shared brain instance. Tells you what you can do (store, review, manage roles) and who to contact if you need a higher role. Run this after onboarding to confirm your role was set correctly. - **team_roster** β€” Show all team members and their assigned roles on a shared brain instance. Returns a table of handles, roles (πŸ‘‘ admin Β· πŸ›‘οΈ reviewer Β· ✏️ contributor Β· πŸ‘οΈ viewer), and capabilities. Use during onboarding to see who can do what, or to verify role assignments. - **team_audit** β€” View the governance audit log for a shared brain β€” an immutable trail of who changed roles and who confirmed which lessons, with timestamps. Essential for enterprise compliance and security reviews. Admin-only once governance is active (an admin has been assigned). Events are recorded automatically on team_assign_role and team_confirm β€” no setup. Example: team_audit(requester="alice") β†’ "πŸ‘‘ role: bob set carol viewer β†’ contributor Β· βœ… confirm: dave confirmed auth:jwt-skew (senior)". - **team_grant_scope** β€” Add or remove a team member to/from a named group (sub-team) on a shared brain. Group-scoped lessons (stored with group="...") only surface in smart_recall for members of that group (and admins). This is team-level visibility, orthogonal to lesson-level private. Admin-gated after the role model is bootstrapped. Example: team_grant_scope(handle="alice", group="security", assigned_by="bob") β€” bob must be admin. - **team_scopes** β€” List team groups and their members, or the groups a specific person belongs to. Pass handle to see one person's scopes; omit it to see all groups on the instance. Use to audit who can see group-scoped lessons. - **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. - **team_synthesize** β€” Team Brain Synthesis β€” merge multiple contributors' lessons on the same topic into one canonical version. When 2+ developers store lessons for the same topic with different details, this proposes the best merged version. Shows: all contributions by author, what worked (consensus), what failed (union), canonical lesson to store. Use this when onboarding new team members or before documenting a process. - **memory_crystalize** β€” Compress the last 30-50 sessions and auto-learned lessons into a dense Memory Crystal. A crystal is a compact, structured summary of everything the brain learned β€” grouped by category (deploy, fix, debug, …). Crystals survive session cleanup and appear in session_start once enough sessions have accumulated. Run this monthly or after a big milestone to preserve institutional knowledge. Returns a digest of what was crystallized. - **team_crystallize** β€” Create a Team Crystal β€” the team-wide, causal counterpart to memory_crystalize. Where memory_crystalize compresses ONE brain by category, team_crystallize surfaces what a per-user memory structurally cannot: which fixes solved structurally SIMILAR problems across MULTIPLE people. A pattern only crystallizes when 2+ distinct authors independently converged on it β€” that cross-person signal is the moat against single-user "Dreaming"-style memory. Needs attributed lessons (learn_from_attempts(author=...) / team_learn). Surfaces in crystal_view. Example: team_crystallize() β†’ "🧩 pool β€” 3 people converged (alice, bob, carol): bounded pool + timeout". - **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. - **brain_hygiene** β€” Autonomously sweep and maintain your Brain β€” flags stale lessons as provisional, archives long-dormant ones, and resolves contradictions where success clearly dominates failure. Safe to run on a schedule (weekly CI job) or on-demand before a big release. Lesson state lifecycle: active β†’ provisional (confidence < threshold) β†’ archived (stale + low-recall + old). Archived lessons are excluded from smart_recall but preserved for audit. dry_run=true (default false) shows what would change without writing anything. - **global_learn** β€” Store a lesson that applies across ALL your projects (cross-project knowledge). Idempotent: if a lesson with the same topic already exists, it is updated in place β€” no duplicates are created. Returns a confirmation with the stored lesson key. No rate limits. Global lessons are stored with the prefix cachly:global:lesson: and recalled from any instance via global_recall. Use for tool preferences, personal workflows, platform quirks, and universal gotchas. Example: global_learn(topic="bash:macos-arrays", lesson="Arrays work differently on macOS bash 3.2"). Use learn_from_attempts for project-specific session lessons; use team_learn to share lessons with your team. - **global_recall** β€” Read-only retrieval of cross-project lessons stored via global_learn. No side effects. Returns a list of matching global lesson objects, each with topic, lesson text, severity, and tags. If no topic is provided, returns all global lessons (up to 50). If topic is provided, returns all lessons whose topic key contains that string (partial match). Use this for lessons that apply universally across all projects (tool quirks, shell gotchas, platform behavior). Use recall_best_solution instead for project-specific lessons; use team_recall for org-scoped lessons. - **publish_lesson** β€” Publish a lesson to the Cachly Public Brain (anonymized community knowledge base). Published lessons can be imported by other developers via import_public_brain. PII is stripped automatically. Visible under the framework/category tag. Returns { lesson_id, topic, framework, published_at } confirming the publish. Irreversible β€” once published to the public brain, lessons cannot be deleted via the MCP interface. Use learn_from_attempts or global_learn for private lessons; use syndicate for anonymized global sharing without framework tagging. - **import_public_brain** β€” Import community lessons from the Cachly Public Brain for a framework. Non-destructive: existing lessons with the same topic key are not overwritten. Returns the count of lessons imported and their topic slugs. Available frameworks: nextjs, fastapi, go, docker, kubernetes, react, typescript, python, rust, laravel, rails, spring. Use this to bootstrap a new brain with battle-tested community knowledge before your first session_start. Use publish_lesson to contribute your own lessons to the Public Brain; use learn_from_attempts for storing lessons from your own sessions. - **recall_at** β€” Brain Archaeology β€” see what a lesson looked like at a specific point in time. "What did we know about deployments 3 months ago?" Returns the history of a topic filtered to entries before the given date. Shows how the lesson evolved: failure β†’ partial β†’ success. Also useful to understand WHY old code decisions were made. - **trace_dependency** β€” Causal Chain β€” find all lessons that depend on a given prerequisite. "What lessons are affected if node version changes?" When a dependency changes (new version, different provider, new OS), call this to see which lessons need review. Lessons store dependencies via the depends_on field in learn_from_attempts. - **list_orgs** β€” List your Cachly organizations (team/org plans). Returns each org with plan, seat count, and member info. Org plans (Team €99, Business €299, Enterprise custom) are billed separately from cache tiers. - **create_org** β€” Create a new Cachly organization for team collaboration. After creation, invite team members with invite_member and upgrade the plan via the billing portal. Org plans: Team (€99/mo, 10 seats), Business (€299/mo, 50 seats), Enterprise (custom). - **invite_member** β€” MUTATION β€” sends an invite email immediately and cannot be undone via MCP. Invite a team member to a Cachly organization by email. Requires the caller to be an admin or owner of the organization. Valid roles: admin (manage members + instances), member (read + cache ops). Default role: member. Returns an error if the email is already a member or has a pending invite. - **get_org_plan** β€” Get the current org plan, seat usage, and billing info for an organization. Shows: plan name, price, seats used/max, next billing date. To upgrade: use the billing portal URL returned by this tool. - **setup_ai_memory** β€” One-shot setup of the cachly 3-layer AI Memory system for a project. Layer 1 β€” Storage: your cachly instance (Valkey, persistent across sessions) Layer 2 β€” Tools: learn_from_attempts + recall_best_solution + smart_recall (the memory API) Layer 3 β€” Autopilot: generates a copilot-instructions.md / .github/copilot-instructions.md that instructs any MCP-compatible AI to recall known solutions BEFORE each task and save lessons AFTER β€” fully automatic, zero manual effort. Returns the copilot-instructions.md content + provider-specific .mcp.json snippet. Optionally writes copilot-instructions.md directly to the project directory. - **cache_stream_set** β€” Cache a list of string chunks (e.g. LLM token stream) via Redis RPUSH. Each chunk is stored as a separate list element under cachly:stream:{key}. Replay with cache_stream_get. - **cache_stream_get** β€” Retrieve a previously cached stream as an ordered list of string chunks. Returns null on cache miss (key absent or empty list). Stored under cachly:stream:{key}. - **cache_org_stats** β€” Show shared cache statistics for an org namespace. Scans all keys under org:{org_id}:sem:* and reports how many entries are shared. Use this to verify org-sharing is working and to monitor cross-instance cache utilization. Also aggregates org-wide ROI via the Cachly API: total cache hits, hits in the last 24h, estimated total and projected monthly USD savings across all org instances, plus a per-instance breakdown. Zero-config: no API changes required β€” any cache_set call with org_id writes to this namespace. - **set_cost_per_call** β€” Set the assumed cost per avoided LLM API call (USD) for this instance. This is used to compute accurate ROI savings estimates in cache_stats. The default ($0.002) is calibrated for a small model (gpt-5.5-mini class). Set your actual model cost for accurate numbers: claude-opus-4.8 β†’ $0.02, gpt-5.5 β†’ $0.015, claude-sonnet-4.6 β†’ $0.009, claude-haiku-4.5 β†’ $0.001. After updating, cache_stats will show savings computed from your real cost. Use list_instances to find your instance_id. - **memory_consolidate** β€” Cognitive memory consolidation β€” the weekly garbage collector for your AI Brain. Scans all lessons, detects contradictions (same topic with conflicting outcomes), merges duplicates, flags stale entries (not recalled in 90+ days), and computes a health score. Returns a full consolidation report with conflicts resolved, duplicates merged, and a before/after count. Run weekly or when brain_doctor reports > 20 lessons. Like git gc for knowledge. - **brain_diff** β€” git log for your AI Brain β€” see exactly what changed since a point in time. Returns a structured changelog: new lessons added, lessons updated (outcome changed), lessons recalled (hit count increased), and lessons that decayed. Perfect for weekly reviews: "What did my AI learn this week?" Example: brain_diff(instance_id="...", since="7d") β†’ "12 new Β· 4 updated Β· 2 stale" - **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. - **knowledge_decay** β€” Confidence scoring for every lesson in your Brain β€” because old knowledge rots. Computes a decay score (0–100%) per lesson based on age, recall frequency, and outcome. Lessons recalled recently score high. Lessons from 90 days ago never recalled score low. Returns a ranked list with visual confidence bars: "β–ˆβ–ˆβ–ˆβ–ˆβ–‘β–‘β–‘β–‘ 40%". Use this before a big refactor to know which lessons to trust and which to re-validate. - **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. - **syndicate** β€” Contribute a verified lesson to the GLOBAL Cachly Knowledge Commons β€” a privacy-preserving shared brain where every AI instance can learn from the discoveries of every other. Your contributor identity is a one-way HMAC hash: completely anonymous. The lesson is immediately searchable by any other AI using syndicate_search. This is how individual knowledge becomes collective intelligence. Call this AFTER every learn_from_attempts that is worth sharing universally (critical bugs, deployment gotchas, architecture discoveries). If a lesson with the same topic already exists in the commons, it is updated in place (idempotent). Returns { key, confirm_count, scope } confirming the stored lesson. Use scope="org" to keep the lesson private to your organisation. Do NOT use for secrets or PII β€” content is stored in a shared knowledge base. - **syndicate_search** β€” Search the GLOBAL Cachly Knowledge Commons for solutions contributed by the entire community. Returns lessons ranked by confirm_count (trust score) then recency. Use this BEFORE debugging any unknown issue β€” someone in the global brain likely solved it already. Example: syndicate_search(q="clickhouse localhost connection refused") β†’ "fix: use 127.0.0.1 not localhost when IPv6 is disabled Β· confirmed by 47 instances" - **syndicate_stats** β€” Show the health of the global Knowledge Commons: total lessons, total confirms, top categories, most-trusted lessons, growth in the last 7 days, and top contributors (anonymous scores). Use for weekly reviews or to explore what the community knows. - **syndicate_trending** β€” Show the TRENDING lessons in the global Knowledge Commons β€” those with the fastest confirmation velocity in the last 7 days (confirm_count / age_in_days). Use this at the start of a session or weekly review to see what the community is actively validating. Lessons need at least 2 independent confirms to appear here. - **brain_marketplace** β€” Browse the Domain Brain marketplace β€” curated, installable packs of high-trust community lessons, grouped by domain (Kubernetes, Auth, Database, React, Payments, …). Each brain is built from verified, community-confirmed lessons in the global Knowledge Commons. Use at onboarding or when starting work in an unfamiliar domain to bootstrap your Brain instantly. Install one with brain_install(slug="..."). Example: brain_marketplace() β†’ "☸️ Kubernetes Incident Brain Β· 42 lessons Β· install: brain_install(slug=\"k8s\")". - **brain_install** β€” Install a Domain Brain into your local Brain β€” pulls its curated, high-trust lessons so they surface in smart_recall immediately, even offline. Idempotent and non-destructive: it NEVER overrides your own lessons (only prior installs of the same brain). Re-run anytime to pull updates. Browse available brains first with brain_marketplace(). Example: brain_install(slug="k8s") β†’ "πŸ“¦ Installed: Kubernetes Incident Brain Β· 42 lessons merged". - **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. - **ckg_inspect** β€” Inspect the Causal Knowledge Graph (CKG) for a concept. Shows all typed edges (fixes, requires, co-occurs, causes) with Bayesian confidence scores. Use to understand what the brain knows about a topic and which fixes have the highest confidence. Also shows related concepts via graph traversal. - **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_plan** β€” READ-ONLY β€” no side effects, no writes, no external network calls. Generative planning layer on top of the CKG: given a task you are ABOUT to do (e.g. "upgrade Postgres 14β†’16", "add Stripe webhooks"), returns an ordered action plan grounded in your own proven lessons β€” the failure modes most likely to bite (ranked by confidence), the concrete steps that fixed them before (with commands), and a pre-flight checklist. Where brain_predict answers "what might fail?", brain_plan answers "what should I do, in what order?". Requires a valid instance_id (your Redis brain). Call before starting non-trivial work. - **brain_conflicts** β€” READ-ONLY β€” list every unresolved belief_conflict (a previously confirmed fix now contradicted by a failure) plus the agents currently writing to this Brain (last 1h). This is the arbitration inbox for multi-agent teams: when several AI sessions share one Brain, contradictory writes surface here instead of silently overwriting each other. Resolve any listed conflict with brain_resolve_conflict. - **brain_resolve_conflict** β€” Arbitrate a contested topic by picking the winning side. winner="success" reaffirms the fix (the contradicting failure stops blocking recall); winner="failure" retires the fix (its CKG fixes-edges decay to ~0 and the losing lesson is archived). Human-in-the-loop resolution is the strongest possible confidence signal. List open conflicts first with brain_conflicts. - **brain_confirm_ci** β€” Close the CI feedback loop: tell the Brain whether a CI job passed or failed and which topics it covered. The Brain adjusts lesson confidence automatically β€” confirmed failures get +15%, false positives (brain predicted failure but CI passed) get βˆ’10%. Called automatically by cachly-action at the end of every pipeline. Also use manually after a deploy to confirm or refute the brain's last prediction. - **brain_briefing** β€” Push-based Brain warning: instead of waiting for you to ask, the Brain proactively checks whether the file you just opened, the PR you are about to raise, or the deploy you are about to run matches any known failure pattern β€” and surfaces warnings BEFORE something breaks. Call this on file_open (with the file path as context), pr_open (with the PR title/body), or deploy (with a short description of what is being deployed). Returns a risk_level (low/medium/high) plus up to 5 ranked warnings with confidence and a known fix. - **brain_contribute_signal** β€” Contribute a privacy-safe signal to the global Brain commons. Only the topic category, outcome, and confidence bucket (high/medium/low) are shared β€” no lesson text, no org identity. When β‰₯ k independent orgs contribute the same pattern, a meta-lesson is derived in the commons. Use this instead of fedbrain_contribute when privacy is required (enterprise, GDPR). - **brain_import_meta** β€” Import k-anonymous meta-lessons from the global Brain commons into your local Brain. Meta-lessons are derived from β‰₯ k independent org signals β€” no individual org data is revealed. Imported lessons get state="meta" and never overwrite your own lessons. Filter by category to target relevant patterns. - **madc_deliberate** β€” Multi-Agent Deliberation Chamber (MADC β€” Layer 3): When conflicting lessons exist for a topic, run deliberation between 6 specialist expert agents (InfraAgent, AuthAgent, DeployAgent, DatabaseAgent, DebugAgent, APIAgent). Each agent votes based on its domain CKG coverage. Unanimous vote β†’ loser superseded. Split vote β†’ contested flag, causal_trace required before acting. Resolution stored as permanent CKG node. Called automatically when learn_from_attempts detects a contradiction. - **cls_ingest** β€” Continuous Learning Stream (CLS β€” Layer 5): Ingest learning signals WITHOUT explicit session_end calls. Sources: git_commit (commit message + files β†’ CKG edges), ci_outcome (green/red build β†’ confirms fix), ide_diagnostic (compiler error + fix pair β†’ instant lesson). Install automatic ingestion with cls_install_hooks β€” brain learns from every commit and CI run. - **cls_install_hooks** β€” READ-ONLY β€” outputs text only, writes no files, makes no network calls, has no side effects. Generates ready-to-paste shell scripts: a git post-commit hook and/or a GitHub Actions step. You must manually copy and install the output. Once the generated scripts are installed, each git commit or CI run will make outbound HTTPS calls to api.cachly.dev to feed learning signals to your brain. No auth required to call this tool β€” only an instance_id. Run once per repository. - **fedbrain_contribute** β€” FedBrain (Layer 6): Contribute a lesson to the global Knowledge Commons with a cryptographic knowledge certificate. Certificate includes: domain fingerprint, confidence, outcome chain hash. Lessons with 10+ independent confirmations become Gold Standard. Context-weighted: other brains with similar tech stacks see your lesson ranked higher in fedbrain_search. - **fedbrain_search** β€” FedBrain context-weighted search: Search the global commons, weighting results by tech-stack similarity. Brains with matching domain context (Go/Kubernetes/Postgres) rank higher than unrelated stacks. Shows certificate provenance, confirm_count, and Gold Standard badges. - **fedbrain_confirm** β€” Confirm that a syndicated lesson from the global commons worked for you. Propagates confirmation back β€” increments confirm_count on the knowledge certificate. Also updates your local CKG confidence. At 10 independent confirmations β†’ Gold Standard. - **fedbrain_status** β€” Show your FedBrain federation status: lessons contributed to global commons, recent confirmations, Gold Standard lessons, pending propagations. Use to track your brain's global knowledge contribution. - **brain_federate** β€” FedBrain Layer 6 β€” Private org knowledge transfer: copy CKG edges + lessons from a source brain into your brain for a specific domain (e.g. "billing", "auth", "deploy"). The new hire use case: one command gives you the senior engineer's 5 years of typed, confidence-weighted knowledge in your domain. Unlike syndicate_search (global, anonymous), brain_federate is org-private β€” both brains must be in the same Cachly org, or the source instance_id must be explicitly shared. Example: brain_federate(source="prod-brain-id", domain="billing", min_confidence=0.6) - **crystal_view** β€” Inspect the current Memory Crystal β€” the compressed wisdom distilled from all past sessions. Shows top patterns per category, lesson count, and when the crystal was last refreshed. Call after session_start when you want to quickly see accumulated wisdom across all past work. - **compact_recover** β€” Call FIRST after any context limit hit / compaction. Reconstructs full context from Memory Crystal + recent sessions + WIP registry + open failures. Returns a condensed briefing so the new context window starts exactly where the previous one left off β€” no lost progress. - **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. - **brain_from_ci** β€” Bulk-ingest CI run outcomes into the Brain β€” the brain_from_git equivalent for CI history. Feed it an array of {job, status, prev_status} objects from your CI system and it will learn which jobs have been fixed, broken, or are stable. Use it to bootstrap the Brain from historical CI logs. - **brain_watch** β€” Install an ambient git post-commit hook that automatically learns from every commit β€” no manual brain_from_git needed. After installation every `git commit` silently POSTs the commit message, SHA, and changed files to the cachly Brain API in the background. Idempotent: running brain_watch twice installs the hook only once. Uses curl (not Node/npx) so it works in any environment. The hook always exits 0 and runs asynchronously β€” it never blocks a commit. Returns the hook path and installation status (written/upgraded/appended/unchanged/skipped-no-git). - **brain_predict_failures** β€” Pre-deploy failure prediction with probability percentages. Given a change context (e.g. "upgrading Keycloak 21β†’24" or "deploying Redis 7 to prod"), returns the top likely failure modes ranked by probability, with pre-loaded fixes. Uses CKG causal edges + lesson history. Call before any significant deploy, migration, or infrastructure change. - **brain_share** β€” Export a Brain snapshot and create a publicly shareable link that anyone can import. Optionally filter by topic prefix (e.g. only "auth:" or "deploy:" lessons). Visibility can be "public" (discoverable) or "unlisted" (link-only). Returns a share URL and the import command to give to teammates or the community. Example: brain_share(instance_id="...", title="My Auth Patterns", topic_filter=["auth"]) - **brain_import** β€” Import lessons from a publicly shared Brain snapshot into your own Brain instance. Accepts a share ID (UUID) or the full share URL from brain_share. Optionally prefix all imported topics to avoid naming collisions (e.g. topic_prefix="team"). Existing lessons are NOT overwritten by default β€” pass overwrite=true to replace them. Example: brain_import(instance_id="...", share_id="abc123", topic_prefix="imported") - **brain_share_list** β€” List all Brain snapshots you have previously shared with brain_share. Shows share ID, title, lesson count, visibility, and creation date for each share. Checks the local provenance log and the cachly API. Example: brain_share_list(instance_id="...") - **brain_unshare** β€” Revoke and permanently delete a public Brain share by its share ID. After calling this, the share URL becomes invalid and no one can import it. Note: users who already imported the Brain keep their local copy. Example: brain_unshare(instance_id="...", share_id="abc123") - **brain_discover** β€” Search and browse publicly shared Brain snapshots in the cachly marketplace. Find ready-made knowledge bases on specific topics (TypeScript, Docker, auth, CI/CD, etc.) created and shared by the community. Returns a ranked list with lesson counts, topics, and import commands. Example: brain_discover(query="kubernetes deployment") Β· brain_discover(topic="auth") - **brain_seed_starter** β€” Seed a fresh Brain with a curated set of universal, high-value engineering lessons (Docker layer cache, JWT clock skew, Postgres migration locks, K8s OOM limits, N+1 queries, cache stampede, CORS preflight, and more). Makes the very first smart_recall return a useful hit instead of nothing β€” ideal right after setup or in a fresh repo with no git history to learn from. Starter lessons are tagged source:"starter", never override your own lessons, and are idempotent (won't double-seed). Example: brain_seed_starter(instance_id="...") Β· brain_seed_starter(instance_id="...", topic_filter=["docker","redis"]) - **brain_graph** β€” Export the Causal Knowledge Graph as a 3D-render-ready node/link payload (schema cachly.brain_graph/v1) β€” the data layer behind the brain viz: the visual, explorable 3D map of every concept, person, file and service the brain knows, and how they causally relate. Node kinds (concept/person/file/service) carry stable color groups and a size (val) scaled by reference count; links carry edgeType (fixes/causes/co-occurs/authored/collaborates) and confidence (value). Consumed verbatim by react-force-graph-3d / three.js frontends. Example: brain_graph(instance_id="...") Β· brain_graph(instance_id="...", domain="auth", min_confidence=0.5, format="summary") - **brain_stats** β€” Get deep statistics about a Brain instance: lesson count, confidence distribution, learning velocity (lessons/day), top topics, top tags, session count, average session length, recall hit rate, and memory crystal count. Use to understand Brain health, measure growth, and surface insights for the team. Example: brain_stats(instance_id="...") Β· brain_stats(instance_id="...", period_days=30) - **brain_export_md** β€” Export all lessons from a Brain instance as a Markdown document. Groups lessons by topic, sorted by confidence (highest first). Ideal for onboarding new teammates: share the exported file so their AI starts pre-loaded with your team's accumulated knowledge without needing a Brain connection. Optionally filter to a minimum confidence threshold or specific topic prefix. Example: brain_export_md(instance_id="...") Β· brain_export_md(instance_id="...", min_confidence=0.8, topic_prefix="auth") - **brain_daily_digest** β€” Generate or send a daily digest of Brain activity: lessons learned today, confidence changes, sessions run, top patterns emerging, and predictions for tomorrow. Can be sent to a Telegram chat, a webhook URL, or returned as text. Schedule this in a cron job or CI pipeline to keep the whole team informed about what the Brain learned without anyone having to check manually. Example: brain_daily_digest(instance_id="...") Β· brain_daily_digest(instance_id="...", webhook_url="https://...", period_hours=24) - **brain_onboard_teammate** β€” Generate a complete onboarding bundle for a new teammate: a shareable link to the Brain, a pre-filled CLAUDE.md / .mcp.json snippet, the top-30 lessons as a quick-start brief, and a setup command they can run in one line. The bundle is returned as a single Markdown document they can paste into any AI assistant or share via Slack/email. Example: brain_onboard_teammate(instance_id="...", name="Sarah") - **brain_set_pref** β€” Persist a user preference for this Brain instance. Preferences are stored in Redis and survive restarts. Known keys: `auto_changelog` (set to "false" to disable the automatic changelog shown at session_start). - **brain_get_pref** β€” Read back one or all preferences stored for this Brain instance. Call with a `key` to get a single value, or omit `key` to list every preference that has been set. Returns a default note when a key has never been set. Complement to `brain_set_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"], "env": { "CACHLY_API_KEY": "", "REDIS_URL": "", "VALKEY_SECRET": "" } } } ``` **Requires environment variables:** `CACHLY_API_KEY`, `REDIS_URL`, `VALKEY_SECRET` β€” the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for). ## Documentation & README # 🧠 cachly AI Brain β€” MCP Server > ### ChatGPT and Claude remember your conversations. > ### cachly remembers your codebase. > > The bug you fixed. Why you chose Postgres. The deploy step that always breaks β€” and > everything your teammates learned. **It stays when someone leaves the team, and it > comes along when you switch assistants.**

npm version   npm downloads   Free tier   GDPR: EU servers   124 MCP tools   License: Apache-2.0

⚑ Get your free Brain β†’ cachly.dev
Free forever Β· no credit card Β· 1-command setup Β· German servers Β· GDPR

--- ## The story you already live every day You are a good engineer. You want to **ship**, not babysit a forgetful assistant. But every session starts at zero. Your AI doesn't remember the race condition you chased for three hours on Tuesday. It doesn't know your deploy gotchas. It can't tell you that **Carol already solved this exact bug in March** β€” because Carol's knowledge lives in Carol's head, and yours in yours. So you re-explain. You re-research. Your team makes the same mistake in five different branches. And when someone leaves, their hard-won knowledge walks out the door with them. > **The villain isn't your AI. It's amnesia.** Context death between sessions, and > knowledge silos between people. The average developer loses **~45 minutes a day** > re-establishing context that should already exist. You don't need a smarter model. **You need a memory that doesn't reset β€” and one that your whole team shares.** --- ## Meet your guide cachly is the brain layer that sits under whatever AI you already use. We've watched hundreds of teams lose the same knowledge the same way, and we built the fix: - **It learns automatically** β€” from every commit, every fix, every session. No extra calls. - **It arrives pre-briefed** β€” your AI opens each session already knowing your stack. - **It's shared** β€” one engineer's solved bug becomes the whole team's reflex. - **It's provable** β€” **78.6 % Precision@1** on an external labelled corpus, with a CI gate that fails the build below 71.0 % ([see the benchmark](https://github.com/cachly-dev/cachly-mcp/blob/HEAD/BENCH.md)). A claim without a number is marketing; a number without a gate is a screenshot. - **It's neutral** β€” speaks [MCP](https://modelcontextprotocol.io), so it works with Claude, Cursor, Copilot, Windsurf, Cline, Zed. Switch models anytime β€” **your brain stays.** We're not the hero of this story. **You are.** cachly is the thing that makes you the engineer whose AI never forgets and whose team compounds knowledge instead of losing it. --- ## Taste it first β€” no account, no risk ```bash npx @cachly-dev/mcp-server@latest demo ``` Run it in any project folder. It reads YOUR git history and shows what your AI *would* know β€” your bugs fixed, your patterns, your past decisions. Nothing leaves your machine. ``` β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ Brain Preview β€” What your AI would know β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Commits: 847 Lessons: 634 Contributors: 7 β”‚ β”‚ Date range: 2024-01-12 β†’ 2026-05-14 β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Security fixes your AI would know: β”‚ β”‚ β€’ fix(auth): JWT expiry check before signature validation β”‚ β”‚ β€’ security: sanitize webhook payload before JSON.parse β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ Bug fixes your AI would remember: β”‚ β”‚ β€’ fix: Redis pub/sub race condition under high concurrency β”‚ β”‚ β€’ fix: k8s readinessProbe threshold too low for cold start β”‚ β”‚ β€’ fix: Stripe idempotency_key missing on retry path β”‚ β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ β”‚ With cachly, your AI arrives pre-briefed every session. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` Like what you see? Make it permanent in the next step. --- ## Brain-first β€” Semantic Cache as Proof-Point cachly is not a semantic cache with a brain bolt-on. The Brain is the product. The Semantic Cache is the **proof-point** β€” it shows ROI in dollars from day one, with zero trust required. It opens the door. The Brain is why teams never leave. | | Wedge β€” Land | Moat β€” Retain | |---|---|---| | **Feature** | Semantic Cache | AI Brain (Lessons, Recall, Team-Sharing) | | **Value** | Measurable cost savings from day one | Compounding team intelligence | | **Metric** | Cache-hit rate, $/month saved | Lessons retained, WoW trend, recall quality | | **Analogy** | Datadog APM (surfaces the problem) | Stripe (becomes critical infrastructure) | **The org-level advantage:** Brain lessons and cache hits are shared across the whole team β€” one person's fix becomes every agent's reflex. Anthropic Projects Memory is per-user and model-locked. cachly is team-wide and model-neutral. That's the structural moat no first-party tool can build. --- ## Setup β€” pick the shortest path for your editor ### Claude Code β€” two lines ``` /plugin marketplace add cachly-dev/cachly-mcp /plugin install cachly-brain@cachly ``` Claude Code declares the MCP server for you; there is no JSON to write and no path to set. Paste your brain ID once with `/plugin configure cachly-brain@cachly` and you are done. (From v0.10.139 the server sets itself up on first use β€” an anonymous 14-day trial brain, nothing to copy.) Check it worked with `claude mcp list` β€” you should see `plugin:cachly-brain:cachly … βœ” Connected`. Note that `claude plugin details` reports `MCP servers (0)` even when the server is running; it does not count them. ### VS Code β€” one click Install the **[cachly Brain](https://marketplace.visualstudio.com/items?itemName=cachly-dev.cachly-brain)** extension. It signs you in silently and creates your brain β€” no account form. ### JetBrains β€” one click Install **[Cachly Brain](https://plugins.jetbrains.com/plugin/32059-cachly-brain)** from the JetBrains Marketplace (IntelliJ, PyCharm, GoLand, WebStorm, Rider). Status bar, brain health and the lessons view live in the IDE; the source is at [cachly-dev/cachly-intellij](https://github.com/cachly-dev/cachly-intellij). The `npx … autopilot` path below also configures JetBrains AI Assistant. ### MCP Registry β€” for any client that reads it The server is listed in the official **[MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=cachly)** as `io.github.cachly-dev/mcp-server`, every release, same day. Clients that browse the registry (Claude Desktop, Goose, VS Code's MCP gallery and others) find it there by name; the entry points at this npm package. ### Anything else β€” one command ```bash npx @cachly-dev/mcp-server@latest autopilot ``` Autopilot does everything in a single command: it auto-detects every AI editor you use, writes the MCP config, signs you in via browser device-flow (one click, no password, no credit card), and bootstraps your brain from git history. Restart your editor and your AI arrives pre-briefed β€” every session, automatically. > **Already inside Claude / Cursor / Copilot?** Paste this to your AI and it configures everything itself: > ``` > Set up cachly for this project. Run: npx @cachly-dev/mcp-server@latest autopilot > It gives my AI persistent memory across sessions. Follow the browser login > (one click, no credit card), then restart the editor. > ``` **Our agreement with you:** Free forever tier. GDPR, EU servers. No model lock-in β€” leave anytime 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 if you call `index_project` yourself β€” and only on your own EU instance. --- ## What changes the moment you turn it on | The moment | Without cachly | With cachly | |-----------|----------------|-------------| | Session start | *"What's your architecture again?"* | *"Ready. 23 lessons. Last session: deployed API."* | | A known bug returns | Re-researches from scratch | *"You fixed this March 12 β€” here's the exact command."* | | You open an unfamiliar file | Cold start | *"Carol fixed 3 bugs here. Related: `fix:stripe-retry`."* | | A teammate leaves | Their knowledge leaves too | Their lessons stay, attributed, searchable | | New hire, day one | Weeks to onboard | `setup` β†’ full team context instantly | | Pre-deploy | Hope nothing breaks | Brain predicts failure risks from past patterns | This is the transformation: from the engineer who **re-explains everything every morning** β†’ to the team whose **collective brain never forgets and gets sharper with every commit.** --- ## cachly vs. Claude's built-in memory Anthropic now ships memory for Claude β€” and it's genuinely good for **one developer, using only Claude, alone.** That's not the game we're playing. Here's the honest map: | | **cachly** | **Claude built-in memory** | |--|------------|----------------------------| | Works across **teams** | βœ… one engineer's fix β†’ everyone's reflex | ❌ per-user / per-agent only | | Works across **models & tools** | βœ… MCP β€” Claude, Cursor, Copilot, Windsurf, Zed… | ❌ Claude + Anthropic API only | | **Structured** knowledge | βœ… topic Β· outcome Β· severity Β· causal graph | ⚠️ flat text files, read linearly | | **Causal root-cause** (`causal_trace`) | βœ… problem β†’ chain β†’ proven fix | ❌ | | **Provable recall quality** | βœ… 78.6 % Precision@1, CI gate at 71.0 % ([benchmark](https://github.com/cachly-dev/cachly-mcp/blob/HEAD/BENCH.md)) | ❌ no public metric | | **Governance** (review, attribution, audit) | βœ… `team_confirm`, roles, audit trail | ❌ | | **Self-hosting / BYOK / VPC** | βœ… data stays in your infra | ❌ Anthropic-hosted | | Survives a **model switch** | βœ… your brain is yours | ❌ memory is gone or fragmented | | Zero-setup for one solo user | ⚠️ ~1 command | βœ… built in | **The honest takeaway:** if you're a solo dev who only ever uses Claude, the built-in memory is great β€” use it. If you work on a **team**, switch tools, care about **proof**, or need **governance and data residency**, that's a gap Anthropic structurally can't close without breaking its own lock-in. **That gap is where cachly wins.** --- ## vs. other memory tools | | cachly | mem0 | MemGPT / Letta | Plain CLAUDE.md | |--|--------|------|----------------|-----------------| | Persistent memory | βœ… | βœ… | βœ… | Manual | | MCP server (no code changes) | βœ… | βœ… | ❌ | βœ… | | Causal root cause analysis | βœ… | ❌ | ❌ | ❌ | | Fully automatic (no explicit calls) | βœ… | ❌ | ❌ | ❌ | | Team knowledge graph + attribution | βœ… | Paid | ❌ | ❌ | | Provable recall lift (published) | βœ… | ❌ | ❌ | ❌ | | Git-ambient learning | βœ… | ❌ | ❌ | ❌ | | GDPR / EU servers | βœ… | ❌ | ❌ | βœ… | | Free tier forever | βœ… | Limited | ❌ | βœ… | --- ## The standout moves | Capability | What it does | |---------|-------------| | **`causal_trace`** | Root-cause analysis *through memory*: problem β†’ causal chain β†’ the fix that worked, with date and commands. **No other system builds and queries a causal graph.** | | **`brain_who_knows`** | *"Who on my team knows about Kubernetes deploys?"* β†’ ranked experts πŸ₯‡πŸ₯ˆπŸ₯‰, built automatically from authorship. | | **`brain_file_map`** | Before you touch a file: who's worked on it and which lessons reference it. | | **`team_expertise_map`** | The whole team's skills matrix in one table β€” onboarding and bus-factor insurance. | | **`brain_collab_pairs`** | Person↔Person Collaboration Graph β€” *"Frag X und Y, die haben das zusammen gelΓΆst."* Bus-factor alerts included. | | **`brain_portability`** | W9 Model-Neutrality β€” config for 7 clients (Claude, Cursor, Copilot, Windsurf, Cline, Zed, Continue). *"Same Brain, any model."* | | **`brain_from_git`** | Reads your entire git history and populates the team knowledge graph (people + files + lessons) β€” zero setup, retroactively. | | **`brain_coverage` / `skill_gaps`** | A 0–100 health score for your knowledge + a ranked list of blind spots to fix. | | **`brain_predict`** | Predicts likely failures *before* they happen, from past incident patterns. | | **Ambient Git** | A git hook auto-extracts lessons from every commit. Zero extra calls. | **`causal_trace` in action:** ``` causal_trace(problem="auth breaks after restart") β†’ Root: k8s:namespace-terminating β†’ Via: keycloak:jwks-race β†’ Fix: PollUntilContextTimeout 3min ← used this March 12, worked ``` *30 minutes of git blame in one call.* --- ## What runs automatically after setup | Trigger | What the Brain does β€” no prompting | |---------|----------------------------------| | First tool call | Session starts; project indexed in background | | Before every task | Recalls relevant past lessons | | During debugging | Traces root causes through causal memory | | Before deploys | Predicts failure risks from past patterns | | After every fix | Stores the lesson with commands + file paths + author | | Every git commit | Hook extracts a lesson from the commit | | Editor closes | Session summary saved for next time | --- ## CLI Commands ```bash npx @cachly-dev/mcp-server@latest autopilot # One command β€” signs in, configures every editor, bootstraps from git npx @cachly-dev/mcp-server@latest demo # Preview your Brain (no account needed) npx @cachly-dev/mcp-server@latest bench # Recall quality vs flat-file memory (no auth required) npx @cachly-dev/mcp-server@latest autosetup # Interactive variant β€” pick editors yourself npx @cachly-dev/mcp-server@latest health # Check token, API, editors, git hook npx @cachly-dev/mcp-server@latest digest # Weekly Brain summary β€” shareable npx @cachly-dev/mcp-server@latest share # Generate a shareable stats card + tweet npx @cachly-dev/mcp-server@latest publish # Publish your Brain as an importable link (--public) npx @cachly-dev/mcp-server@latest badge # Get a live README badge for your Brain npx @cachly-dev/mcp-server@latest invite # Invite a teammate to share your Brain npx @cachly-dev/mcp-server@latest index . # Index a project's code into the Brain (CI-friendly) npx @cachly-dev/mcp-server@latest learn-git # Auto-learn lessons from recent git commits ``` > **Tip β€” auto-learn on every merged PR:** run `learn-git` in CI via the > [cachly-brain-setup GitHub Action](https://github.com/cachly-dev/cachly-action) > with `mode: learn`. Each merged PR teaches your Brain automatically. --- ## CI integration β€” your pipeline teaches the Brain Every CI run is a lesson: a redβ†’green transition is a proven fix, a greenβ†’red one is a known cause. Ready-to-paste templates live in [`src/ci-integration/`](https://github.com/cachly-dev/cachly-mcp/blob/HEAD/src/ci-integration/): - **GitHub Actions** β€” copy [`brain-from-ci-action.yml`](https://github.com/cachly-dev/cachly-mcp/blob/HEAD/../github-action/templates/brain-from-ci-action.yml) into `.github/workflows/`. It triggers on `workflow_run` (completed) and pushes the outcome to your Brain. Requires `CACHLY_API_KEY` + `CACHLY_BRAIN_INSTANCE_ID` secrets (`CACHLY_JWT` still works as a fallback). - **GitLab CI** β€” copy [`brain-from-ci-gitlab.yml`](https://github.com/cachly-dev/cachly-mcp/blob/HEAD/src/ci-integration/brain-from-ci-gitlab.yml) into your pipeline: two `.post` jobs (`on_success` / `on_failure`) with `allow_failure: true`. Want more than outcome pushes? The full GitLab template [`cachly.gitlab-ci.yml`](https://github.com/cachly-dev/cachly-action/blob/main/templates/cachly.gitlab-ci.yml) adds hidden jobs for `learn` / `scan` / `confirm` β€” pull it in with `include: remote:` (it is an includable template, not a CI/CD Catalog component). - **Anything else** β€” [`push-ci-outcome.mjs`](https://github.com/cachly-dev/cachly-mcp/blob/HEAD/src/ci-integration/push-ci-outcome.mjs) is a standalone Node.js helper with zero dependencies. It always exits 0 β€” your CI never fails because of a Brain push. Already have months of CI history? Backfill it in one call with the **`brain_from_ci`** MCP tool β€” bulk-ingests past outcomes the same way `brain_from_git` ingests commits. --- ## MCP Tools (123 total, 27 in the default catalogue) **Your editor sees 27 of them, not 123 β€” on purpose.** The full list cost ~27,750 tokens in *every* request, which is 14 % of a 200k window gone before you type anything. The tools you use daily are listed individually; the other 96 sit behind one dispatcher: ``` cachly_tool(tool: "team_roster") run any of them by name cachly_tool(tool: "team_roster", describe: true) get its schema first ``` Nothing is unreachable: the server dispatches by name and never consults the catalogue, so `team_roster` called directly still works. Set `CACHLY_ALLE_WERKZEUGE=1` to get all 123 listed again. The full tool catalog is generated from `sdk/mcp/src/tools.ts`. Cross-surface coverage is tracked in [`../../docs/generated/surface-parity.md`](https://github.com/cachly-dev/cachly-mcp/blob/HEAD/../../docs/generated/surface-parity.md), and pinned OpenAPI/OpenAI/Anthropic/LangChain projections live in [`../../docs/generated/tool-specs/`](https://github.com/cachly-dev/cachly-mcp/blob/HEAD/../../docs/generated/tool-specs/). ### 🧠 Session & Memory (most used) | Tool | What it does | |------|-------------| | **`session_start`** | Full briefing: last session, 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 (with `author`, `visibility`) | | **`recall_best_solution`** | Best known solution for a topic β€” with success/failure history | | **`smart_recall`** | Hybrid BM25 + semantic + causal-graph search β€” 11 languages, quality-reranked | | **`remember_context`** | Cache architecture findings, decisions, file summaries | | **`compact_recover`** | Full context recovery after hitting the context-window limit | ### πŸ‘₯ Team Brain & Org Knowledge Graph | Tool | What it does | |------|-------------| | `team_learn` / `team_recall` | Share lessons across the team with author attribution | | `team_confirm` | A reviewer confirms a lesson (πŸ›‘οΈ senior / βœ”οΈ peer) β†’ ranks higher in recall Β· reviewer-gated | | `team_assign_role` / `team_roster` / `team_whoami` | Roles (πŸ‘‘ admin Β· πŸ›‘οΈ reviewer Β· ✏️ contributor Β· πŸ‘οΈ viewer) β€” enforced once an admin is set | | `team_audit` | Immutable, admin-only governance trail: every role change & lesson confirmation | | **`brain_who_knows`** | Find your team's experts on any topic β€” ranked πŸ₯‡πŸ₯ˆπŸ₯‰ | | **`brain_file_map`** | Experts + lessons per file, before you touch it | | **`team_expertise_map`** | Full team skills matrix in one table | | **`brain_collab_pairs`** | Person↔Person Collaboration Graph β€” who collaborates with whom, bus-factor alerts | | **`brain_portability`** | Config snippets for 7 MCP clients β€” proves model-neutrality, same Brain everywhere | | **`skill_gaps`** | Knowledge blind spots: unresolved failures, missing attribution | | **`brain_coverage`** | 0–100 knowledge-health score for your codebase | | `madc_deliberate` | Specialist AI agents vote to resolve contradictory lessons | | `memory_crystalize` | Distill all lessons into a Crystal for instant team context | | `team_crystallize` | Team Crystal β€” fixes that 2+ teammates independently converged on (the cross-person, causal layer) | ### 🧬 Causal Intelligence | Tool | What it does | |------|-------------| | **`causal_trace`** | Root-cause analysis through the Causal Knowledge Graph | | **`brain_predict`** / `brain_predict_failures` | Predict likely failures before they happen | | **`brain_from_git`** | Bootstrap people + files + lessons from git history β€” incremental | | **`brain_from_ci`** | Bulk-ingest CI outcomes: redβ†’green becomes a fix lesson + causal `fixes` edge, greenβ†’red a `causes` edge β€” `brain_from_git` for CI logs | | `memory_consolidate` | Detect contradictions, merge duplicates, expire stale lessons | | `ckg_inspect` | Inspect the causal graph around any concept | ### 🌐 Shareable & Public Brains | Tool | What it does | |------|-------------| | **`brain_seed_starter`** | Seed 16 universal lessons so your **first** `smart_recall` hits β€” auto-runs on a fresh repo | | **`brain_share`** | Publish a Brain snapshot as a shareable link (public or unlisted) β€” a link to show off, not your data. For that, run `npx @cachly-dev/mcp-server export` | | **`brain_import`** | Import any shared Brain into yours β€” `topic_prefix`, `min_confidence`, `dry_run` | | `brain_share_list` / `brain_unshare` | List your shares Β· revoke a share (link goes dead) | | **`brain_discover`** | Search the Brain marketplace for ready-made knowledge bases | ### 🌍 Knowledge Commons Β· βš™οΈ Infrastructure Β· πŸ“‹ Roadmap | Tool | What it does | |------|-------------| | `syndicate` / `fedbrain_search` | Contribute to / search the global Knowledge Commons | | `brain_marketplace` / `brain_install` | Browse + install curated Domain Brains (Kubernetes, Auth, DB…) into your Brain | | `cache_get` / `cache_set` / `semantic_search` / `index_project` | Cache + semantic ops β€” pass `org_id` on `cache_get`/`cache_set` to share the cache org-wide (writes mirror to `org:{org_id}:sem`, reads fall back to it on miss) | | `cache_stats` / `cache_org_stats` | Tokenmaxxing ROI: hits, estimated USD saved + monthly projection β€” per instance or aggregated across your whole org. Zero hits yet? You get a day-1 ROI projection instead. | | `list_instances` / `create_instance` / `delete_instance` | Manage Brain instances | | `roadmap_add` / `roadmap_next` | Persistent project roadmap stored in the Brain | *…and ~70 more. Run `health` to see what's wired up in your editor.* --- ## FAQ **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. **How is this different from Claude's built-in memory?** Claude's memory is per-user, Claude-only, flat-file, and unbenchmarked. cachly is team-shared, model-neutral (any MCP client), structured + causal, governed, and has a [published recall benchmark](https://github.com/cachly-dev/cachly-mcp/blob/HEAD/BENCH.md). See the comparison table above. **Can my whole team share one Brain?** Yes β€” that's the point. `team_learn` / `team_recall`, or `npx @cachly-dev/mcp-server@latest invite teammate@example.com`. **Is my code sent to cachly servers?** Only if you call `index_project` yourself: it stores a short excerpt (up to `summary_chars`, default 1200 characters) per indexed file, on your own EU instance. Every other tool stores lesson text, commit messages, session summaries, and key-value context β€” no source code. All data on EU servers, GDPR-compliant. **What is `causal_trace` and why is it unique?** Given any error, it walks the Causal Knowledge Graph to find root cause, intermediate causes, and the exact fix that worked β€” including date and commands. No other memory system builds or queries a causal graph. **What if I hit the context-window limit mid-session?** Call `compact_recover`. It reconstructs full context from Memory Crystal + recent sessions + WIP registry β€” typically one tool call. --- ## Editor support matrix `npx @cachly-dev/mcp-server@latest autopilot` auto-detects and configures all of the following. Manual snippets are in the **Manual Setup** section below. | Editor / Client | Auto-setup | Config file written | Global config | Notes | |---|---|---|---|---| | **Claude Code** | βœ… | `~/.claude/mcp.json` + `.mcp.json` | βœ… global always | Runtime device-flow sign-in on first tool call | | **Cursor** | βœ… detected via `.cursor/` | `.cursor/mcp.json` | β€” | Project-level; restart Cursor after setup | | **Windsurf** | βœ… detected via `.windsurf/` | `.windsurf/mcp.json` | β€” | Project-level; restart Windsurf after setup | | **VS Code + Copilot** | βœ… detected via `.vscode/` | `.vscode/mcp.json` | β€” | Requires VS Code MCP extension or Copilot chat | | **Cline** | βœ… detected via VS Code | `.vscode/mcp.json` | β€” | Shares config with Copilot; restart VS Code | | **Continue.dev** | βœ… detected via `.continue/` | `.continue/config.json` | β€” | Uses `modelContextProtocolServers` key | | **Zed** | βœ… detected via `.zed/` | `.zed/settings.json` | β€” | Uses `context_servers` key | | **Windsurf (global)** | `autosetup --editor windsurf` | `~/.windsurf/mcp.json` | βœ… | Pass `--editor` to target global config | | **Any other MCP client** | `autosetup --editor claude` | `.mcp.json` | β€” | Standard `mcpServers` stdio format | **Which sign-in path each editor uses:** | Scenario | Path | |---|---| | `autosetup` from a real terminal (TTY) | OAuth device-flow β†’ browser click β†’ API key saved automatically | | `autosetup` from VSCode task / CI (non-TTY) | Auto-detects non-interactive, opens browser with step-by-step guide, prints `CACHLY_JWT=... autosetup` instruction | | First tool call from Claude Code (no JWT yet) | Inline device-flow: MCP returns URL + code, browser opens automatically, next call proceeds | | `CACHLY_JWT=cky_live_xxx npx ... autosetup` | Skips auth step entirely, uses provided key | > **Tip β€” fastest per-project setup from inside Claude Code:** > ``` > Set up cachly for this project: npx @cachly-dev/mcp-server@latest autopilot > ``` > Claude runs it and restarts automatically. --- ## Manual Setup
Claude Code (~/.claude/mcp.json or .mcp.json) ```json { "mcpServers": { "cachly": { "command": "npx", "args": ["-y", "@cachly-dev/mcp-server@latest"] } } } ``` On the first tool call your AI will prompt you to sign in β€” takes 10 seconds.
Cursor / Windsurf / VS Code / Copilot / Cline ```json { "mcpServers": { "cachly": { "type": "stdio", "command": "npx", "args": ["-y", "@cachly-dev/mcp-server@latest"] } } } ```
Zed (.zed/settings.json) ```json { "context_servers": { "cachly": { "command": { "path": "npx", "args": ["-y", "@cachly-dev/mcp-server@latest"] } } } } ```
--- ## Self-hosting & BYOK cachly is **bring-your-own-key and self-host friendly out of the box** β€” no enterprise contract required to keep data in your own infra. **Bring your own embedding key (BYOK).** Semantic search runs on the embedding provider *you* choose. Set one env var and cachly auto-detects it; no key needed if you prefer cachly's server-side embeddings (uses your JWT): | Provider | Env var | Model | |---|---|---| | OpenAI | `OPENAI_API_KEY` | `text-embedding-3-small` | | Google Gemini | `GEMINI_API_KEY` | `text-embedding-004` | | Mistral | `MISTRAL_API_KEY` | `mistral-embed` | | Cohere | `COHERE_API_KEY` | `embed-english-v3.0` | | Ollama (local, free) | `OLLAMA_BASE_URL` | `nomic-embed-text` | | cachly (server-side) | *(none β€” uses JWT)* | managed | Force a specific one with `CACHLY_EMBED_PROVIDER=openai`. Run `npx @cachly-dev/mcp-server@latest health` to confirm which provider is active. **Point at your own backend (self-hosting).** Every cachly install can talk to a private backend instead of `api.cachly.dev`: ```bash # One-shot: wire up the wizard against your self-hosted backend npx @cachly-dev/mcp-server@latest autopilot --api-url https://cachly.mycorp.internal # Or non-interactively npx @cachly-dev/mcp-server@latest autosetup \ --instance-id --api-key \ --api-url https://cachly.mycorp.internal ``` `autosetup` bakes `CACHLY_API_URL` into the editor config **only** when it differs from the default cloud β€” so default installs stay clean, and self-hosted installs keep talking to your backend on every editor launch. All data stays in your infra. --- ## Pricing | Tier | RAM | Price | Best for | |------|-----|-------|----------| | **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 | €79/mo | AI-heavy workloads | | **Business** | 7 GB | €199/mo | Scale-ups | βœ… All plans: **EU servers Β· GDPR-compliant Β· No credit card for Free** --- ## Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `CACHLY_JWT` | β€” | API token (set by wizard automatically) | | `CACHLY_BRAIN_INSTANCE_ID` | β€” | Default instance UUID (optional β€” auto-resolved) | | `CACHLY_API_URL` | `https://api.cachly.dev` | Override for self-hosted | | `CACHLY_NO_TELEMETRY` | unset | Set to `1` to disable usage pings (these include your API token and up to 80 characters of `smart_recall` queries) | --- ## 🧠 Brain v3 β€” what's new | Feature | Tool | What it does | |---|---|---| | Autonomous hygiene | `brain_hygiene` | Sweeps stale lessons, flags provisional, archives orphans | | PR risk scan | `cachly-action` `scan` / `predict` modes | Matches PR title, body and changed files against Brain lessons via the `/scan` API β€” posts a PR comment with risk score before CI runs | | Multi-agent arbitration | `brain_conflicts` Β· `brain_resolve_conflict` | Detects + resolves conflicting lessons across agents | | Plans dashboard | `brain_plan` | Persistent plans in the UI with step tracking and brain-viz overlay | | Privacy federation | `brain_contribute_signal` Β· `brain_import_meta` | Share patterns without sharing data β€” k-anonymous global commons | --- ## πŸ› οΈ Ecosystem & Docs **One brain, wherever you work.** Start with the MCP server, or drop the same memory straight into your editor β€” your lessons follow you across all of them. | Package | What it does | |---------|-------------| | **[`@cachly-dev/mcp-server`](https://www.npmjs.com/package/@cachly-dev/mcp-server)** | ← you are here Β· works with Claude, Cursor, Copilot, Windsurf, Cline, Zed | | **[Cachly Brain for VS Code](https://marketplace.visualstudio.com/items?itemName=cachly-dev.cachly-brain)** | One-click memory in the editor β€” status bar, lessons view, ambient learning. No terminal needed. | | **[Cachly Brain for JetBrains](https://plugins.jetbrains.com/plugin/32059-cachly-brain)** | Same brain for IntelliJ / PyCharm / GoLand / WebStorm / Rider β€” status bar, brain health, lessons view. | | **[`@cachly-dev/openclaw`](https://www.npmjs.com/package/@cachly-dev/openclaw)** | Cut LLM costs with semantic caching in JS/TS apps | | **[cachly-dev/cachly-action](https://github.com/cachly-dev/cachly-action)** | GitHub Action: auto-setup, PR risk scan, auto-learn from merged PRs, weekly hygiene | Prefer a visual view over the terminal? The VS Code companion extension shows the same Brain, live, in the editor: ![The Lessons view inside the Cachly Brain VS Code extension, listing six stored lessons](https://cachly.dev/screenshots/vscode/shot3-lesson-card.png) *The Lessons view in the VS Code companion extension β€” the same lessons this server stores, browsable without leaving the editor.* - 🌐 [cachly.dev](https://cachly.dev) β€” Dashboard & free signup - πŸ“– [Docs](https://cachly.dev/docs/ai-memory) β€” Full documentation - πŸ—ΊοΈ [Public Roadmap](https://cachly.dev/roadmap) β€” what's coming next - πŸ’¬ [GitHub Issues](https://github.com/cachly-dev/cachly-mcp/issues) β€” Bugs & feature requests --- > **Stop re-explaining yourself to your own tools.** Give your AI β€” and your team β€” a > brain that remembers, learns, and gets sharper with every commit. > > ```bash > npx @cachly-dev/mcp-server@latest autopilot > ```