sovseal Memory

Local-first, zero-knowledge semantic memory for AI agents with on-device vector search (LanceDB + ONNX) and client-side AES-256-GCM encrypted sync.

GitHub

Documentation

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.

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:

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

Usage with Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.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:

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

Usage with Windsurf / Zed / OpenCode

{
  "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:

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:

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

npm install
npm run build

Development

Prerequisites

Node.js 20.x or higher
npm or pnpm

Setup

Clone the repository:

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

Install dependencies:

npm install

Build the project:

npm run build

Testing via MCP Inspector

Build and start the server:

npm run build
node dist/index.js

In another terminal, start the MCP Inspector:

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

License

Apache 2.0