We built persistent memory
for Claude Code

AI coding assistants are getting remarkably good at writing code. But they have amnesia. Every session you re-explain your architecture, re-describe your deployment process, and watch your AI re-discover the same bugs you fixed two weeks ago.

The obvious answer is memory. But memory for AI assistants is surprisingly hard to get right. You need it to be fast (no extra round-trips before coding starts), relevant (not just a dump of everything), and structured (lessons, not logs).

Cachly AI Dev Brain is an MCP server that gives Claude Code (and Cursor, Copilot, Windsurf) persistent memory backed by Valkey and pgvector. The core pattern is two calls:

// At session start — one call replaces 3+ context-setting prompts
session_start(instance_id="...", focus="deploy api")

// → Returns in a single response:
// 📅 Last session (2h ago): Fixed Valkey connection pool, deployed API v0.5
//    Duration: 47 min | Files: api/internal/cache.go, docker-compose.yml
// 🎯 Relevant for "deploy api":
//    ✅🔴 deploy:api — nohup docker compose up -d --build
//    ✅🟡 deploy:rsync-env — rsync overwrites .env, make changes locally first
// 🕐 Recent lessons: bash:macos-lowercase, infra:k3s-tls-san
// 📊 Brain: 23 lessons · 12 context entries · 0 open failures

At session end, Claude saves what it learned:

session_end(
  instance_id    = "...",
  summary        = "Deployed API v0.6, fixed connection pool timeout",
  files_changed  = ["api/internal/cache.go", "docker-compose.yml"],
  lessons_learned = 2,
)

That's the whole loop. Session start briefs Claude. Session end saves what happened. Over time the brain accumulates real, structured knowledge about your codebase.

The naive approach — store everything, retrieve everything — produces noise. After a few weeks you have hundreds of lessons and Claude drowns in irrelevant context.

We solved this with a quality system built into every lesson:

• →Severity: critical / major / minor — Claude surfaces critical lessons first, always
• →recall_count: every time a lesson helps, its count increments. High-recall lessons rise to the top
• →Deduplication: new lessons that conflict with existing ones are compared; the better one wins
• →Semantic search: smart_recall() finds relevant lessons by meaning, not keyword matching

The result: after a few weeks of use, session_start() returns a tightly curated briefing. The most critical, most-recalled lessons surface automatically. Noise stays buried.

The brain runs on infrastructure we already had: Cachly managed Valkey instances. Key schema:

cachly:lesson:best:{topic}      → serialized lesson JSON (severity, recall_count, …)
cachly:session:last             → last session summary + files changed
cachly:session:file_changes     → list of recent git diff --stat entries
cachly:ctx:{category}:{key}     → long-term context (architecture, patterns, …)
cachly:global:lesson:{topic}    → cross-instance global lessons
cachly:public:lesson:{fw}:{t}   → community lessons (Next.js, Go, Docker, …)

All reads are O(1) key lookups or lightweight pattern scans. The session_start() call does 4–6 Valkey reads. There's no LLM involved in retrieval — it's pure key-value with optional pgvector semantic search for smart_recall().

Two features we're especially excited about:

Team Brain — share one instance ID across your engineering team. When one developer learns that k3s requires WireGuard IP in TLS SAN, every AI assistant on the team gets that lesson. Lessons include an author field so you know whose hard-won experience you're benefiting from.

Public Brain — community-curated lessons for popular frameworks. Run import_public_brain("nextjs") and your brain immediately knows about common Next.js gotchas, App Router patterns, and deployment footguns — contributed by the community, anonymized, and deduplicated.

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

This detects your editor (Claude Code, Cursor, Copilot, Windsurf, Continue.dev), writes the MCP config, and verifies the brain is reachable. Free tier, no credit card.

Or manually add to your MCP config:

{
  "mcpServers": {
    "cachly": {
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"],
      "env": {
        "CACHLY_API_URL": "https://api.cachly.dev",
        "CACHLY_JWT": "your-api-token",
        "CACHLY_BRAIN_INSTANCE_ID": "your-instance-id"
      }
    }
  }
}