{
  "markdown": "# echocache — MCP server for cached LLM responses\n\nAn MCP server for a **cached LLM response** — the way an HTTP cache caches an expensive server\nresponse, not the way a browser caches a static asset. Ask a question you already answered once,\nand the answer echoes back instead of being re-derived.\n\nTwo lookup paths, inspired by two different kinds of caching:\n\n- **Exact-match, HTTP-style** — `cache_get` / `cache_set` key on `(model, prompt, params)`, with\n  `ttl_seconds` and `stale_while_revalidate_seconds` behaving like `Cache-Control`: fresh, stale,\n  or expired.\n- **Knowledge-graph recall** — every stored entry is a node in a small similarity graph.\n  `cache_query` finds related entries by meaning, not just exact key; `cache_related` walks\n  graph edges (auto-linked \"similar\" entries, or explicit \"derived-from\" parents) to surface\n  everything already known before an agent redoes work from scratch. `cache_invalidate` can\n  cascade through those `derived-from` edges when a source changes.\n\nRuns as a standard stdio MCP server, so it works with Claude Code, Claude Desktop, Cursor, VS\nCode + Copilot, or any other MCP-capable host — see [Install](#install) below, and\n[`AGENTS.md`](./AGENTS.md) for the tool-use protocol any connected agent should follow.\n\n## What it's for — and what it isn't\n\nCache what an agent **concluded**, never what it **read**. This is the whole design, and it is\nworth stating plainly because the intuitive use is the wrong one: serving a cached file read costs\nthe reader exactly the tokens that reading the file cost, since the content still has to enter the\ncontext. So caching file reads saves nothing at any hit rate, and if the agent re-emits the file to\nstore it, that's output-rate tokens paid for zero benefit. A cache only pays when a hit stands in\nfor *regenerating* something.\n\nWhere it pays, and where measurement said it does not:\n\n- **Pays best: an expensive research or judgment call.** A real 22-tool-call research chain in\n  this project's own history cost 37,119 output tokens to reach a 255-token conclusion — a 728x\n  gap against serving that conclusion back, weighted for output pricing. A single reuse pays for\n  the write ~145x over. Live-validated the same way with a fresh web-search-derived design\n  decision, correctly recalled by different wording and correctly outranking an unrelated entry\n  sharing surface vocabulary. Not proven to recur yet in this project's own history — but the\n  payoff on one hit is large enough that low frequency isn't disqualifying, unlike a file read.\n- **Pays conditionally: re-orientation across sessions.** An agent reads a codebase to understand\n  it, the session ends, and a later session needs that understanding again. On `express/lib` — six\n  files, 62KB — re-reading the source costs 15,504 tokens against 549 to serve the cached\n  orientation, about **28× fewer**. That holds when the later session genuinely needs broad\n  understanding; if it only needs one specific answer, it will grep and read a slice for ~900\n  tokens, and the cache isn't competitive.\n- **Does not pay: replacing reads in a parallel dispatch.** Thirty subagents in one code-review\n  dispatch pulled ~374,000 tokens of content a sibling had already read — but 127 of their 166\n  reads used `offset`/`limit`, so they were already taking slices rather than whole files.\n  Substituting a shared derivation for those slices measured **27% worse** than what they actually\n  did: grep is already a cheap, precise pointer, and a cached map competes with it on its own\n  ground and loses.\n\nThe rule all three point at: **cache what grep cannot reconstruct.** A conclusion, a judgement,\nthe reason something is the way it is, a cross-file synthesis no single search reveals, a\nresearch finding, the fact that something is *absent*. Never a location — grep finds those for\nless than the cache costs to consult — and never a file.\n\nWhen a cached entry does carry file paths or line numbers, that is to point a reader at exact\ndetail, not to replace reading it. And reach for `cache_query` rather than `cache_get` when\nlooking for a match: a later session, or another agent, will not phrase the question the way the\nwriter did.\n\nWhat this is not: a way to avoid reading files, a source of truth, or a substitute for\n[prompt caching](https://docs.claude.com/en/docs/build-with-claude/prompt-caching) *within* one\nconversation, which is cheaper and needs no server. echocache is for results that must outlive\nthe context that produced them.\n\n### What Claude Code already does for free\n\nIf your only host is Claude Code, its own [persistent memory](https://docs.claude.com/en/docs/claude-code)\nalready does the core of this: write a conclusion to a memory file instead of the files it came\nfrom, and a later session reads it back before redoing the work. That's the same rule this project\nconverged on, running for free, with no server to register. This project's own findings and\nmeasurements from building it are stored there, not in echocache itself — worth noticing, since\nit means the tool wasn't used to cache the very research that produced it.\n\nWhat's actually different, in order of how much it matters:\n\n- **Cross-project sharing.** Claude Code's memory is scoped to one project directory. echocache is\n  one SQLite file any project on the machine can register against, so a conclusion reached in one\n  repo is queryable from another. Real, but unproven: this project's own history shows zero\n  instances of a conclusion actually getting reused across sessions, and cross-project reuse is a\n  narrower bar than that.\n- **Semantic recall.** `cache_query` finds a match by meaning, independent of how it was phrased or\n  which file it's filed under. Memory is retrieved by an always-loaded index plus the agent's own\n  judgment about what to open — no vector search.\n- **Host-agnostic.** Works from Cursor, VS Code, Claude Desktop, or any other MCP client — memory\n  is native to Claude Code specifically.\n- **Explicit freshness.** TTL/stale-while-revalidate freshness and hash-based `derived_from`\n  invalidation catch a source going stale automatically. Memory has neither; staleness is caught\n  only if an agent happens to notice.\n\nFor a single user on a single host in one project, memory already captures most of the value here\nfor free. What's left as echocache's actual case is narrower than \"a cache for LLM responses\":\nit's specifically sharing a derivation across projects or hosts that don't already share a memory\nstore — and that narrower case is unproven, not just untested, until it's been measured the way\neverything else in this document has.\n\n## Install\n\nNo clone or build needed — register it straight from npm.\n\n**Claude Code**\n\n```sh\nclaude mcp add echocache -- npx -y echocache\n```\n\n**Claude Desktop / Cursor / VS Code** — add a stdio entry to the host's MCP config\n(`claude_desktop_config.json`, `.cursor/mcp.json`, `.vscode/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"echocache\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"echocache\"]\n    }\n  }\n}\n```\n\n**OpenCode** — add an entry to `opencode.jsonc` (global: `~/.config/opencode/opencode.jsonc`, or\nproject-level in the repo root):\n\n```jsonc\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"echocache\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"echocache\"],\n      \"enabled\": true\n    }\n  }\n}\n```\n\nAny other MCP-capable host takes the same launch command; only the config file differs. Then point\nyour agent at [`AGENTS.md`](./AGENTS.md) so it knows *when* to reach for the cache — the protocol\nmatters more than the wiring, since caching the wrong things costs tokens rather than saving them.\n\nThis repo also ships the usage protocol as skills, discovered automatically by hosts that support\nproject skills: [`.claude/skills/`](./.claude/skills/) for Claude Code, [`.opencode/skills/`](./.opencode/skills/)\nfor OpenCode (`echocache-cache`, `echocache-deps`, `echocache-gain`). No extra setup beyond\nregistering the MCP server above — the skill directory is discovered from the project root.\n\n### Configuration\n\nEvery setting is an environment variable, all optional:\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `ECHOCACHE_DB_PATH` | `~/.echocache/cache.db` | SQLite file location |\n| `ECHOCACHE_MAX_ENTRIES` | `10000` | LRU ceiling on retained entries |\n| `ECHOCACHE_MAX_BYTES` | `268435456` (256MB) | LRU ceiling on retained response bytes |\n| `ECHOCACHE_DEFAULT_TTL_SECONDS` | `86400` (1 day) | Freshness lifetime when a caller omits one |\n| `ECHOCACHE_SIMILARITY_THRESHOLD` | `0.25` | Similarity floor for auto-linking entries |\n| `ECHOCACHE_LINK_CANDIDATE_POOL` | `500` | Recent entries a new write is compared against |\n| `ECHOCACHE_ENCRYPTION_KEY` | unset | 64 hex chars (32 bytes); enables AES-256-GCM at rest |\n\nThe database directory is created `0700` and its files `0600`. Set an encryption key to also\nencrypt entry contents at rest:\n\n```sh\nexport ECHOCACHE_ENCRYPTION_KEY=$(node -e \"console.log(require('crypto').randomBytes(32).toString('hex'))\")\n```\n\nTurning encryption on or off requires a fresh database — there is no in-place migration, and a\nkey/database mismatch is refused at startup rather than failing on some later read.\n\n## Tools\n\n| Tool               | Purpose                                                                |\n|---------------------|--------------------------------------------------------------------------|\n| `cache_get`         | Exact-match lookup with fresh / stale / expired freshness                |\n| `cache_set`         | Store a result; auto-links it into the similarity graph                  |\n| `cache_query`       | Semantic search across all cached entries                                |\n| `cache_related`     | Graph traversal from one entry to entries linked to it                   |\n| `cache_invalidate`  | Delete an entry, optionally cascading to its dependents                  |\n| `cache_stats`       | Exact-match hit rate, `queryHits`/`queryMisses`, and tokens served       |\n\nOne SQLite file backs all of them, shared across every project that registers the server — a\nconclusion reached in one repo is queryable from another. Concurrent readers and writers from\nseparate processes are the expected case, not an edge case.\n\n## Developing\n\n```sh\ngit clone https://github.com/kskurtveit/echocache && cd echocache\nnpm install\nnpm run check        # typecheck + tests\nnpm start            # or: npm run dev\n```\n\nSee [`CLAUDE.md`](./CLAUDE.md) for architecture and the module reference.\n\n## License\n\nMIT\n",
  "bytes": 10564,
  "sha": "2a62dd758d313118cd5289c1acaefcc6428f96e36a7ec4d094627f362a1244f5",
  "repo_slug": "kskurtveit/echocache",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kskurtveit_echocache_89d6750c/readme"
}