# memvid-mcp

MCP (Model Context Protocol) server for [memvid](https://github.com/memvid/memvid) - a memory layer for AI agents.

This server wraps the memvid Rust CLI, exposing 40 tools for persistent memory management with hybrid search (lexical + vector), temporal indexing, knowledge graphs, and RAG capabilities.

## Use Cases

- **Agent Memory**: Give AI agents persistent memory across sessions with semantic search and temporal awareness
- **Document Intelligence**: Ingest documents, code, and web content with automatic entity extraction and fact tracking
- **Knowledge Base**: Build searchable knowledge bases with hybrid lexical/vector search and knowledge graph relationships
- **Audit & Compliance**: Track information sources with citation generation and audit reports
- **Session Replay**: Record and replay agent sessions for debugging and analysis

## Prerequisites

- **Node.js 18+**
- **memvid CLI** binary (see [memvid](https://github.com/memvid/memvid) for installation)
- **Optional**: Embedder configuration for vector search (embedder.toml)
- **Optional**: LLM configuration for RAG (llm.toml)

## Installation

### From Source

```bash
git clone https://github.com/Tapiocapioca/memvid-mcp.git
cd memvid-mcp
npm install
npm run build
```

### Verify Installation

```bash
# Test the server starts
node dist/index.js
# Should output: "memvid-mcp server started"
# Press Ctrl+C to exit
```

## Configuration

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `MEMVID_PATH` | `memvid` | Path to the memvid binary |
| `MEMVID_LOG_LEVEL` | `warning` | Log level: `debug`, `info`, `warning`, `error` |
| `MEMVID_VERBOSE` | `0` | Set to `1` for verbose CLI output |

### MCP Client Setup

#### VS Code (Copilot)

Add to your VS Code MCP settings:

```json
{
  "servers": {
    "memvid": {
      "command": "node",
      "args": ["/path/to/memvid-mcp/dist/index.js"],
      "env": {
        "MEMVID_PATH": "/path/to/memvid"
      }
    }
  }
}
```

#### Claude Desktop

Add to `claude_desktop_config.json`:

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

#### Cursor

Add to MCP settings:

```json
{
  "memvid": {
    "command": "node",
    "args": ["/path/to/memvid-mcp/dist/index.js"],
    "env": {
      "MEMVID_PATH": "/path/to/memvid"
    }
  }
}
```

#### OpenCode

Add to `opencode.json`:

```json
{
  "mcp": {
    "memvid": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/memvid-mcp/dist/index.js"],
      "env": {
        "MEMVID_PATH": "/path/to/memvid"
      }
    }
  }
}
```

## Security Considerations

### Path Validation

The server implements multiple layers of path security:

1. **Path Traversal Protection**: Blocks `..` patterns
2. **System Path Blocklist**: Prevents access to sensitive directories (`/etc/`, `/proc/`, `\windows\`, etc.)
3. **MCP Roots Validation**: Respects client-provided roots boundaries (when supported by client)

### Encryption

Memory files can be encrypted using AES-256-GCM:

```
memvid_lock { "file": "data.mv2", "output": "data.mv2e", "password": "secret" }
memvid_unlock { "file": "data.mv2e", "output": "data.mv2", "password": "secret" }
```

### Recommendations

- Store memory files in dedicated directories
- Use encrypted files (`.mv2e`) for sensitive data
- Configure MCP roots in your client to restrict file access
- Use separate memory files per project/context

## Available Tools (40)

### Lifecycle (5 tools)

| Tool | Description | Annotations |
|------|-------------|-------------|
| `memvid_create` | Create a new .mv2 memory file | write |
| `memvid_open` | Open and display file metadata | read-only |
| `memvid_stats` | Show detailed statistics (frame count, index sizes) | read-only |
| `memvid_verify` | Verify file integrity with optional deep check | read-only |
| `memvid_doctor` | Diagnose and repair corrupted indexes | destructive |

### Content Management (7 tools)

| Tool | Description | Annotations |
|------|-------------|-------------|
| `memvid_put` | Add content from file/directory with optional embeddings | write |
| `memvid_put_many` | Batch add with progress tracking | write |
| `memvid_view` | View frame content by ID | read-only |
| `memvid_update` | Replace frame content | destructive |
| `memvid_delete` | Delete a frame | destructive |
| `memvid_correct` | Amend frame with audit trail | write |
| `memvid_api_fetch` | Fetch URL content and add to memory | network |

### Search (5 tools)

| Tool | Description | Annotations |
|------|-------------|-------------|
| `memvid_find` | Hybrid/lexical/vector search | read-only |
| `memvid_vec_search` | Vector-only semantic search | read-only |
| `memvid_ask` | RAG question answering | read-only |
| `memvid_timeline` | Chronological frame view | read-only |
| `memvid_when` | Temporal search (find when something was mentioned) | read-only |

### Analysis (6 tools)

| Tool | Description | Annotations |
|------|-------------|-------------|
| `memvid_audit` | Generate audit report with citations | read-only |
| `memvid_debug_segment` | Debug internal index segments | read-only |
| `memvid_export` | Export to JSON/CSV/JSONL | write |
| `memvid_tables` | List internal SQLite tables | read-only |
| `memvid_schema` | Schema inference and summary | read-only |
| `memvid_models` | List available embedding models | read-only |

### Knowledge Graph (6 tools)

| Tool | Description | Annotations |
|------|-------------|-------------|
| `memvid_enrich` | NER entity extraction | write |
| `memvid_memories` | Memory card operations | read-only |
| `memvid_state` | Show current memory state | read-only |
| `memvid_facts` | Fact extraction and listing | read-only |
| `memvid_follow` | Traverse entity relationships | read-only |
| `memvid_who` | Entity lookup | read-only |

### Session Management (5 tools)

| Tool | Description | Annotations |
|------|-------------|-------------|
| `memvid_session` | Start/stop/list/replay sessions | write |
| `memvid_binding` | Memory binding operations | destructive |
| `memvid_status` | System status (version, model status) | read-only |
| `memvid_sketch` | SimHash sketch operations | write |
| `memvid_nudge` | Trigger background processing | write |

### Encryption (2 tools)

| Tool | Description | Annotations |
|------|-------------|-------------|
| `memvid_lock` | Encrypt memory file (AES-256-GCM) | write |
| `memvid_unlock` | Decrypt memory file | write |

### Utility (4 tools)

| Tool | Description | Annotations |
|------|-------------|-------------|
| `memvid_process_queue` | Process pending operations | write |
| `memvid_verify_single_file` | Verify single frame integrity | read-only |
| `memvid_config` | Show current configuration | read-only |
| `memvid_version` | Print version information | read-only |

## Example Workflows

### Basic Memory Setup

```
# 1. Create a new memory file
memvid_create { "file": "project.mv2" }

# 2. Ingest documentation
memvid_put { 
  "file": "project.mv2", 
  "input": "./docs", 
  "recursive": true,
  "embed": true  # Generate vector embeddings
}

# 3. Check statistics
memvid_stats { "file": "project.mv2" }
```

### Search and Retrieval

```
# Hybrid search (lexical + vector)
memvid_find { 
  "file": "project.mv2", 
  "query": "authentication flow", 
  "mode": "hybrid",
  "limit": 5 
}

# Semantic search only
memvid_vec_search { 
  "file": "project.mv2", 
  "query": "how to handle user sessions" 
}

# RAG question answering
memvid_ask { 
  "file": "project.mv2", 
  "question": "What authentication methods are supported?" 
}
```

### Knowledge Graph Operations

```
# Extract entities from all frames
memvid_enrich { "file": "project.mv2", "all": true }

# Look up an entity
memvid_who { "file": "project.mv2", "query": "OAuth" }

# Follow entity relationships
memvid_follow { 
  "file": "project.mv2", 
  "entity": "AuthService", 
  "hops": 2 
}
```

### Audit and Export

```
# Generate audit report with sources
memvid_audit { 
  "file": "project.mv2", 
  "query": "security requirements",
  "include_snippets": true 
}

# Export for backup
memvid_export { 
  "file": "project.mv2", 
  "output": "backup.json",
  "format": "json" 
}
```

### Session Recording

```
# Start recording a session
memvid_session { "file": "project.mv2", "start": "debug-session-1" }

# ... agent interactions ...

# Stop recording
memvid_session { "file": "project.mv2", "stop": true }

# Replay later
memvid_session { "file": "project.mv2", "replay": "debug-session-1" }
```

## Embedder Configuration

For vector search capabilities, create `~/.config/memvid/embedder.toml`:

```toml
[embedder]
provider = "openai"
model = "text-embedding-3-large"
api_key_env = "OPENAI_API_KEY"
dimensions = 3072
```

Or for A4F/OpenRouter compatible APIs:

```toml
[embedder]
provider = "openai"
model = "provider-3/text-embedding-3-large"
base_url = "https://api.a]4f.co/v1"
api_key_env = "A4F_API_KEY"
```

## Performance Characteristics

| Operation | Typical Latency | Notes |
|-----------|-----------------|-------|
| `memvid_create` | < 100ms | Creates empty SQLite database |
| `memvid_put` (single file) | 100-500ms | Depends on file size |
| `memvid_put` (with embed) | 500ms-2s | Includes API call for embedding |
| `memvid_find` (lexical) | < 50ms | Tantivy full-text search |
| `memvid_find` (hybrid) | 100-500ms | Combines lexical + vector |
| `memvid_ask` (RAG) | 1-5s | Includes LLM API call |

Timeouts are configured per operation type:
- Default: 120 seconds
- Heavy operations (batch put): 300 seconds
- RAG operations: 180 seconds

## Development

```bash
npm run dev    # Run with tsx (hot reload)
npm run build  # Compile TypeScript
npm start      # Run compiled version
npm run clean  # Remove dist/
```

## Troubleshooting

### Server won't start

1. Check Node.js version: `node --version` (requires 18+)
2. Verify build: `npm run build`
3. Check memvid binary: `memvid --version`

### "MEMVID_PATH not found"

Set the environment variable to the full path:
```bash
export MEMVID_PATH=/path/to/memvid
# or on Windows
set MEMVID_PATH=C:\path\to\memvid.exe
```

### Vector search returns no results

1. Check embeddings were generated: `memvid_stats` shows `vector_count > 0`
2. Verify embedder config: `memvid_config`
3. Re-ingest with embeddings: `memvid_put { ..., "embed": true }`

### Path validation errors

The server validates all paths against:
1. Path traversal patterns (`..`)
2. System directory blocklist
3. MCP roots (if client supports roots capability)

Ensure your paths are within allowed directories.

## License

MIT