Mnemosyne Cache

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.