@sovseal/mcp-server

The @sovseal/mcp-server package exposes a local Model Context Protocol server communicating over stdio. It allows LLM agents (such as Cursor, Windsurf, or Claude Desktop) to read and write to the local zero-knowledge memory store with $0$ network RTT.

Stdio Transport Configuration

To register the server with Claude Desktop, Cursor, or Windsurf, add it to your configuration file (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "sovseal": {
      "command": "npx",
      "args": [
        "-y",
        "@sovseal/[email protected]"
      ],
      "env": {
        "SOVSEAL_PROJECT_ID": "sov_proj_00000000-0000-4000-8000-000000000000",
        "SOVSEAL_ENCRYPTION_KEY": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
        "SOVSEAL_VERBOSE": "true"
      }
    }
  }
}

Config File Fallback

If SOVSEAL_PROJECT_ID is not set in the environment, the server falls back to ~/.sovseal/config.json for identity and routing (the file no longer holds key material as of 0.3.5):

{
  "schema_version": 1,
  "project_id": "sov_proj_98c15904-8b65-4293-84f9-b4f3b7d1597f",
  "api_key": "sov_proj_98c15904-8b65-4293-84f9-b4f3b7d1597f",
  "endpoint": "https://<your-project>.supabase.co/functions/v1/v2-agent-state"
}

Key custody

The encryption master key is held in the OS keychain, not the config file. Working keys (k_rest for local at-rest encryption, k_sync for replication) are derived via HKDF and never persisted. On headless hosts, set SOVSEAL_KEY_FALLBACK=file to store the master at ~/.sovseal/ (0600); otherwise an unavailable keychain fails closed. See Key Management & Custody.

Tool Reference

The server exposes exactly two tools. Legacy memory operations like CRUD list/delete are retired to enforce local ciphertext replication.

1. store_memory

Persists a new factual context statement inside the local database node.

• Arguments:
  • content (string, required): The self-contained third-person statement to store (e.g., "User prefers dark mode"). Must be between $1$ and $65,536$ characters.

Zod Schema

const StoreMemoryArgsSchema = z.object({
  content: z
    .string()
    .min(1, "content must be a non-empty string")
    .max(65536, "content must be ≤ 65536 characters"),
});

Example Response

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"success\": true,\n  \"id\": \"7a8b9c0d-e1f2-3a4b-5c6d-7e8f9a0b1c2d\"\n}"
    }
  ]
}

2. recall_memory

Searches the local LanceDB vector index using local ONNX embeddings ($0$ network RTT) to find matches closest to the query.

• Arguments:
  • query (string, required): The search string verbatim (e.g. "user preferences").
  • topK (integer, optional): Number of results to return. Min 1, Max 20, Default 5.

Zod Schema

const RecallMemoryArgsSchema = z.object({
  query: z.string().min(1, "query must be a non-empty string"),
  topK: z
    .number()
    .int()
    .min(1)
    .max(20)
    .optional()
    .default(5),
});

Example Response

{
  "content": [
    {
      "type": "text",
      "text": "[score=0.812402 id=7a8b9c0d-e1f2-3a4b-5c6d-7e8f9a0b1c2d] User prefers dark mode"
    }
  ]
}

If no semantic matches are found, it returns:

{
  "content": [
    {
      "type": "text",
      "text": "no_matches: the local memory store returned 0 hits for this query."
    }
  ]
}

Verbose Logging

Enable verbose debug logs to stderr by setting:

SOVSEAL_VERBOSE=true

This will log initialization, model downloads, local vector search latency metrics, and write-behind replication event states.

sovseal mind (CLI subcommand)

Run a one-shot digest of the local memory store without starting the stdio server or spinning up the embedding pipeline:

npx -y @sovseal/[email protected] mind

It prints a token-budgeted (~1,200 token) summary and exits 0:

• Core Mind State — procedural and semantic memories ranked by composite score.
• Recurring Patterns — memories reinforced more than once ("You've returned to this 3 times").

Useful for shell prompts, agent session-start hooks, or quickly inspecting what an agent "knows."

MCP Resources