Mnemosyne Cache MCP

High-performance MCP (Model Context Protocol) response caching server. Reduces latency from ~3000ms to ~0.001ms for repeated tool calls.

Overview

The Mnemosyne Cache MCP server provides transparent caching for MCP tool responses using a dual-layer architecture:

SQLite: Persistent storage backend
LRU Memory Cache: Hot entry acceleration

Key Features

Intelligent TTL Management: Server-specific expiration policies
Write-Operation Detection: Automatically skips caching for mutations
SHA256 Cache Keys: Deterministic key generation from tool calls
Statistics Tracking: Hits, misses, evictions, and hit rate monitoring
Zero Configuration: Sensible defaults with environment variable overrides

Performance Impact

Uncached serena tool call:    ~3000ms
Cached serena tool call:       ~0.001ms
Performance improvement:       3,000,000% faster

Installation

npm install -g @zhadyz/mnemosyne-cache-mcp

Or use with npx:

npx @zhadyz/mnemosyne-cache-mcp

Configuration

Environment Variables

# Database location (default: ./mcp_cache.db)
export MNEMOSYNE_CACHE_DB="/path/to/cache.db"

# Memory cache settings (default: enabled, 1000 entries)
export MEMORY_CACHE="true"
export MEMORY_CACHE_SIZE="1000"

Default TTL Values

Server	TTL (seconds)	Rationale
serena	1800 (30 min)	Code changes frequently
context7	7200 (2 hours)	Docs are stable
github	600 (10 min)	Repos change
filesystem	300 (5 min)	Files change
memory	0 (never)	Mutable state
mnemosyne	0 (never)	Mutable state

MCP Configuration

Add to your Claude Code MCP settings (.claude/mcp.json):

{
  "mcpServers": {
    "mnemosyne-cache": {
      "command": "npx",
      "args": ["@zhadyz/mnemosyne-cache-mcp"],
      "env": {
        "MNEMOSYNE_CACHE_DB": "./.cache/mcp_cache.db",
        "MEMORY_CACHE": "true",
        "MEMORY_CACHE_SIZE": "1000"
      }
    }
  }
}

Or with local installation:

{
  "mcpServers": {
    "mnemosyne-cache": {
      "command": "node",
      "args": ["/path/to/mnemosyne-cache-mcp/dist/index.js"]
    }
  }
}

Available Tools

cache_get

Retrieve a cached MCP tool response.

{
  "server_name": "serena",
  "tool_name": "find_symbol",
  "args": {
    "name_path": "MyClass",
    "relative_path": "src/main.ts"
  }
}

Response:

{
  "cached": true,
  "data": { /* tool response */ }
}

cache_set

Store an MCP tool response with automatic TTL.

{
  "server_name": "serena",
  "tool_name": "find_symbol",
  "args": { /* tool arguments */ },
  "response": { /* tool response */ }
}

Response:

{
  "success": true,
  "message": "Cached response for serena:find_symbol"
}

cache_invalidate

Invalidate cache entries by server or tool.

{
  "server_name": "github",
  "tool_name": "get_issue"  // optional
}

Response:

{
  "success": true,
  "invalidated_entries": 42
}

cache_stats

Get cache performance statistics.

{}

Response:

{
  "hits": 1523,
  "misses": 287,
  "evictions": 12,
  "totalEntries": 1810,
  "totalSizeBytes": 15728640,
  "sizeMB": 15.0,
  "hitRate": 84.14,
  "avgHitTimeMs": 0.001,
  "avgMissTimeMs": 3127.5
}

Cache Key Generation

Cache keys are deterministically generated using SHA256:

const keyMaterial = `${serverName}:${toolName}:${sortedArgs}`;
const cacheKey = sha256(keyMaterial);

Arguments are JSON-stringified with sorted keys to ensure identical calls produce identical keys regardless of argument order.

Write Operation Detection

The following verbs in tool names are automatically excluded from caching:

create
update
delete
remove
modify
write

Examples of non-cacheable operations:

github__create_issue
filesystem__write_file
serena__replace_symbol_body

Architecture

┌─────────────────────────────────────────┐
│         MCP Client (Claude Code)        │
└────────────────┬────────────────────────┘
                 │
                 │ stdio transport
                 ▼
┌─────────────────────────────────────────┐
│      Mnemosyne Cache MCP Server         │
│                                         │
│  ┌───────────────────────────────────┐ │
│  │     LRU Memory Cache (Hot)        │ │
│  │     - 1000 entries (default)      │ │
│  │     - O(1) lookup                 │ │
│  └───────────┬───────────────────────┘ │
│              │ miss                    │
│              ▼                          │
│  ┌───────────────────────────────────┐ │
│  │     SQLite Database (Cold)        │ │
│  │     - Persistent storage          │ │
│  │     - TTL expiration              │ │
│  └───────────────────────────────────┘ │
│                                         │
│  Cache Key: SHA256(server:tool:args)   │
└─────────────────────────────────────────┘

Development

Build

npm install
npm run build

Local Testing

node dist/index.js

Send MCP protocol messages via stdin:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

License

MIT

Author

ZHADYZ - MENDICANT_BIAS DevOps Agent

Part of the MENDICANT autonomous AI orchestration system.