3-Layer AI Memory System

How the three layers work together#

Layer 1 — Storage: your Valkey instance. The persistent brain. Stores all lessons, context, and architecture decisions. Survives restarts, context window resets, and new chat sessions. Lives on your cachly instance.

Layer 2 — Tools: the memory API. learn_from_attempts saves what worked and what failed. recall_best_solution retrieves the best known solution before any task. smart_recall finds context by meaning — no exact key needed.

Layer 3 — Autopilot: copilot-instructions.md. A single file in your repo that tells GitHub Copilot, Claude, Cursor, and Windsurf to run the memory tools automatically — before every task to check memory, and after every task to save lessons. Zero manual effort.

Layer 3 calls Layer 2 automatically, and Layer 2 reads and writes Layer 1. The result: your AI never solves the same problem twice.

Quick setup — 3 steps#

Or use the MCP tool setup_ai_memory to generate everything in one command.

1. Choose your embedding provider#

Switch providers by changing CACHLY_EMBED_PROVIDER in your .mcp.json env — no code changes required.

2. Add to .mcp.json#

Works with Claude, Cursor, GitHub Copilot, Windsurf.

{
  "mcpServers": {
    "cachly": {
      "command": "npx",
      "args": ["-y", "@cachly-dev/mcp-server@latest"],
      "env": {
        "CACHLY_JWT": "your-api-token",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Replace your-api-token with your token from cachly.dev/instances → Settings.

3. Activate Layer 3 — the autopilot#

Create .github/copilot-instructions.md in your project. This tells GitHub Copilot, Claude, Cursor, and Windsurf to run memory tools automatically, before and after every task.

The fastest path is the MCP tool — tell your AI assistant:

setup_ai_memory(
  instance_id = "your-instance-uuid",
  project_dir = "/path/to/your/project",
  embed_provider = "openai"
)

This writes .github/copilot-instructions.md directly to your project and prints the full setup summary. To copy it manually instead:

# cachly AI Memory — 3-Layer Autopilot
 
## BEFORE every task
1. Call `recall_best_solution("topic")` — check for known solutions
2. Call `smart_recall("description")` — find context by meaning
3. If found, use it directly — skip re-discovery
 
## AFTER every task
1. Call `learn_from_attempts(topic, outcome, what_worked, what_failed)`
2. Call `remember_context("key", "analysis", category)` for code findings

Once this is in place, your AI checks memory before every task and saves lessons after. First things to try:

• recall_best_solution("deploy:web") — before deploying, check if it's been done before
• learn_from_attempts(topic="debug:auth", outcome="success", what_worked="...") — after fixing a bug, save it for next time
• smart_recall("how does the database schema work") — find cached architecture notes by meaning

Core MCP tool groups#

Key tools from the 122-tool MCP surface, available in GitHub Copilot, Claude, Cursor, Windsurf, and any MCP-compatible AI tool.

AI Memory — the core feature

Semantic Cache

semantic_search, detect_namespace, cache_warmup, index_project — see Semantic Caching for the full API.

Live Cache Operations

cache_get, cache_set, cache_delete, cache_exists, cache_ttl, cache_keys, cache_stats, cache_mset, cache_mget.

Distributed Locks & Streams

cache_lock_acquire, cache_lock_release (Redlock-lite, fencing token), cache_stream_set, cache_stream_get.

Instance Management

list_instances, create_instance, get_instance, get_connection_string, delete_instance, get_api_status.

Related#

Once memory is running, distill it with Memory Crystals so briefings stay dense instead of noisy, or read the full MCP Integration reference for Ambient Recall hooks and supported editors.

← Back to all docs