# 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

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

Or use with npx:

```bash
npx @zhadyz/mnemosyne-cache-mcp
```

## Configuration

### Environment Variables

```bash
# 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`):

```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:

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

## Available Tools

### cache_get

Retrieve a cached MCP tool response.

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

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

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

**Response:**
```json
{
  "success": true,
  "invalidated_entries": 42
}
```

### cache_stats

Get cache performance statistics.

```json
{}
```

**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:

```typescript
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

```bash
npm install
npm run build
```

### Local Testing

```bash
node dist/index.js
```

Send MCP protocol messages via stdin:

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