Mnemosyne Cache MCP

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: ``json { "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: ``json { "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: ``json { "success": true, "invalidated_entries": 42 } ``

cache_stats

Get cache performance statistics.

{}

Response: ``json { "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.