# sovseal MCP Server

An MCP server that gives Claude, Cursor, and every MCP client **one shared memory that never leaves your machine**. On-device vector search via LanceDB + Transformers.js (384-dim embeddings), AES-256-GCM client-side encryption, and write-behind ciphertext sync. **0 RTT reads.**

[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/sovseal/mcp-server)

## Tools

### Store Memory (`store_memory`)

Embeds and persists a context fact inside the local on-device memory node.

**Parameters:**

- `content` (string, required): A third-person factual statement to store (max 65,536 chars)

**Behavior:**

- Embeds content on-device (intfloat/multilingual-e5-small, 384-dim, ONNX)
- Writes to local LanceDB — returns immediately
- Ciphertext sync runs **write-behind**; nothing blocks the caller
- Automatically de-duplicates and reinforces existing entries
- High-risk PII (SSNs, credit cards, API keys) is automatically redacted before storage

### Recall Memory (`recall_memory`)

Semantic search over stored memory context. Returns top-K relevant memories by L2 distance.

**Parameters:**

- `query` (string, required): Semantic query string to search past memories
- `topK` (number, optional): Maximum number of memories to return (1–20, default: 5)

**Behavior:**

- Embeds query on-device (LRU-cached pipeline) → vector search local LanceDB
- **0 RTT** — network is never on the read path
- Returns `[score=NUMBER id=ID] text` for each match — smaller score = closer semantic match
- Returns `no_matches` when the store has no relevant entries

## Resources

### Briefing Context (`sovseal://context/briefing`)

A summarized, reinforcement-aware briefing of procedural, semantic, and recurring memories. Recommended for bootstrapping new conversations with stored user context.

### Recent Context (`sovseal://context/recent`) — *Deprecated*

Raw list of the most recently stored context facts. Use `sovseal://context/briefing` instead.

## Prompts

### Context Injection (`/sovseal:context`)

System prompt helper that bootstraps a conversation by reading from `sovseal://context/recent` before the first turn.

## Configuration

### No API Key Required

sovseal runs 100% on-device. There is no external API key, no cloud dependency, and no account required for local memory operations.

### Environment Variables

The server supports the following environment variables:

- `SOVSEAL_TRANSPORT`: Transport mode (`"stdio"` or `"sse"`, default: `"stdio"`)
- `SOVSEAL_PORT`: SSE server port (default: `4040`)

## Installation

### Usage with Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sovseal-memory": {
      "command": "npx",
      "args": ["-y", "@sovseal/mcp-server"]
    }
  }
}
```

### Usage with Cursor

Add to your Cursor MCP settings (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "sovseal-memory": {
      "command": "npx",
      "args": ["-y", "@sovseal/mcp-server"]
    }
  }
}
```

### Usage with VS Code (Copilot / Cline / Roo)

Add to your User Settings (JSON) or `.vscode/mcp.json`:

```json
{
  "servers": {
    "sovseal-memory": {
      "command": "npx",
      "args": ["-y", "@sovseal/mcp-server"]
    }
  }
}
```

### Usage with Windsurf / Zed / OpenCode

```json
{
  "mcpServers": {
    "sovseal-memory": {
      "command": "npx",
      "args": ["-y", "@sovseal/mcp-server"]
    }
  }
}
```

### Automatic Onboarding (All Clients)

Detect your IDE, configure global connection settings, and write system instructions automatically:

```bash
npx -y @sovseal/mcp-server onboard --write --register
```

Supported: Cursor, Claude Desktop/Code, Windsurf, VS Code (Copilot/Cline/Roo), Zed, Google Antigravity, and OpenCode.

### HTTP/SSE Transport

For always-on autonomous agents, run as a long-lived HTTP/SSE server:

```bash
SOVSEAL_TRANSPORT=sse SOVSEAL_PORT=4040 npx -y @sovseal/mcp-server
```

### Hosted Endpoint

A hosted HTTP/SSE endpoint is available for web-based MCP clients and marketplace validation:

```
https://sovseal-mcp-server.barrackbobby1.workers.dev/mcp
```

## How It Stays Private

- **AES-256-GCM** client-side encryption with a 96-bit random IV per snapshot
- 256-bit key lives in `~/.sovseal/config.json` (mode `0600`) — **lose this file, lose every snapshot**
- Server only ever sees ciphertext + SHA-256-derived paths; it cannot read your context
- **Verified Semantic Recall (VSR)** — every load re-derives `sha256(canonicalize(payload))` and fails closed on mismatch
- **Packet-Capture Guarantee** — run Wireshark or tcpdump against the server; if you find a single byte of unencrypted context on the wire, the software is free forever

## Performance

| Workload                 | Operation              | p50    | p95     | p99     |
| ------------------------ | ---------------------- | ------ | ------- | ------- |
| 10K records · 1K queries | `recall_memory` (warm) | 6.1 ms | 10.4 ms | 21.8 ms |
| Single write             | `store_memory`         | 3.8 ms | 7.2 ms  | 12.5 ms |
| First call               | `recall_memory` (cold) | ~1.2 s | —       | —       |

All operations are **0 RTT** — network is never on the read path.

## Build

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

## Development

### Prerequisites

- Node.js 20.x or higher
- npm or pnpm

### Setup

1. Clone the repository:

```bash
git clone https://github.com/sovseal/mcp-server.git
cd mcp-server
```

2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

### Testing via MCP Inspector

1. Build and start the server:

```bash
npm run build
node dist/index.js
```

2. In another terminal, start the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

### Available Scripts

- `npm run build`: Build the TypeScript project
- `npm run dev`: Watch for changes and rebuild
- `npm run typecheck`: Type-check without emitting
- `npm run test`: Run test suite (Vitest)
- `npm run test:watch`: Watch mode testing
- `npm run bench`: Run performance benchmarks

## Links

- **Website:** [sovseal.com](https://sovseal.com)
- **Documentation:** [docs.sovseal.com](https://docs.sovseal.com)
- **Trust Center:** [trust.sovseal.com](https://trust.sovseal.com)
- **Chrome Extension:** [Chrome Web Store](https://chromewebstore.google.com/detail/sovseal-private-memory-for-ai/fhffejkgpnnloldaikecmmojedkhcofe)
- **Full Monorepo:** [github.com/sovseal/core](https://github.com/sovseal/core)

## License

[Apache 2.0](./LICENSE)