# tibet-voice-cache-mcp

**MCP server for persistent voice conversation memory.** Plug into Claude Code, Cursor, Windsurf, or any MCP client.

```
pip install tibet-voice-cache-mcp
```

## What it does

Gives any MCP-compatible AI client tools to store and recall voice conversation context. User and AI utterances are stored separately in RAM (or optionally on disk) and formatted as clean context summaries — no fake turns, no role confusion.

```
┌──────────────────────────────────────────────────────────────┐
│  MCP Client (Claude Code / Cursor / Windsurf / etc.)         │
│                                                              │
│  voice_cache_add(actor="user_1", text="...", role="user")    │
│  voice_cache_add(actor="user_1", text="...", role="ai")      │
│  voice_cache_turn(actor="user_1")                            │
│                                                              │
│  voice_cache_inject(actor="user_1",                          │
│    base_instruction="You are a voice assistant.")            │
│  → "You are a voice assistant.                               │
│                                                              │
│     === PRIOR CONTEXT ===                                    │
│     The user previously said:                                │
│       - What's the weather?                                  │
│     You previously responded:                                │
│       - Sunny and 22 degrees!                                │
│     === END CONTEXT ==="                                     │
└──────────────────────────────────────────────────────────────┘
```

## Setup

### Claude Code

```json
// ~/.claude.json
{
  "mcpServers": {
    "voice-cache": {
      "command": "tibet-voice-cache-mcp"
    }
  }
}
```

### With disk persistence

```json
{
  "mcpServers": {
    "voice-cache": {
      "command": "tibet-voice-cache-mcp",
      "env": {
        "VOICE_CACHE_DIR": "/path/to/cache"
      }
    }
  }
}
```

### Cursor / Windsurf

Same pattern — add `tibet-voice-cache-mcp` as an MCP server command.

## Tools

| Tool | Description |
|------|-------------|
| `voice_cache_status` | List all active caches with stats |
| `voice_cache_open` | Open/create cache for an actor |
| `voice_cache_add` | Record user or AI utterance |
| `voice_cache_turn` | Mark turn boundary |
| `voice_cache_context` | Get formatted context summary |
| `voice_cache_inject` | Inject context into system instruction |
| `voice_cache_session` | Bulk import session transcripts |
| `voice_cache_history` | View cached utterances |
| `voice_cache_clear` | Clear cache for an actor |
| `voice_cache_configure` | Change summary style / language |

## Quick workflow

```
# During voice session
voice_cache_open(actor="user_123")
voice_cache_add(actor="user_123", text="What's the weather?", role="user")
voice_cache_add(actor="user_123", text="Sunny and warm!", role="ai")
voice_cache_turn(actor="user_123")

# Next session — inject memory
voice_cache_inject(
    actor="user_123",
    base_instruction="You are a friendly weather assistant."
)
```

## Summary styles

Configure how context is formatted:

```
voice_cache_configure(actor="user_123", summary_style="compact")
```

| Style | Format |
|-------|--------|
| `labeled` | Sectioned with headers (default) |
| `compact` | Minimal tokens, single-line |
| `narrative` | Natural language, conversational |
| `chronological` | Numbered turn pairs |

## Multi-language

```
voice_cache_configure(actor="user_123", language="nl")
```

Built-in: English (`en`), Dutch (`nl`).

## Environment variables

| Variable | Default | Description |
|----------|---------|-------------|
| `VOICE_CACHE_DIR` | _(none — RAM only)_ | Directory for JSON persistence |
| `VOICE_CACHE_MAX_TURNS` | `50` | Max utterances per side before trimming |
| `VOICE_CACHE_STYLE` | `labeled` | Default summary style |

## Resources

The server also exposes MCP resources:

- `voice-cache://actors` — List all actors with open caches
- `voice-cache://actor/{name}` — Full cache content for an actor

## Part of the TIBET ecosystem

| Package | Description |
|---------|-------------|
| [`tibet-voice-cache`](https://github.com/jaspertvdm/tibet-voice-cache) | Core library — voice conversation memory |
| `tibet-voice-cache-mcp` | This package — MCP server wrapper |

## License

MIT — plug it in, give your voice AI a memory.