VaultZero Client

An MCP server that gives an AI agent long-term memory it cannot read. VaultZero is a privacy-first memory vault: this package embeds and encrypts every memory on your machine before it is sent, so the server stores ciphertext and vectors and never holds a key.

This repository is the trusted, customer-side client: the SDK, the crypto, the embedding adapters, and the Model Context Protocol server. It is the only code that ever sees plaintext or holds payload keys.

The server stores ciphertext, vector embeddings (which can be partially inverted to text), scope labels, record sizes and timestamps. It cannot read your memories, but it is not "a server that knows nothing". See the trust model below.

MCP server

Two tools, so an agent can remember across sessions and recall by meaning rather than by key:

The model never chooses a tenant, a user, or a key, and cannot grant itself a scope. Remembered text comes back explicitly framed as untrusted data, so a stored instruction cannot become a command.

Install

Requires Python 3.10 or newer.

pip install vaultzero    # or: uv tool install vaultzero

Configure a client

{
  "mcpServers": {
    "vaultzero": {
      "command": "uvx",
      "args": ["--from", "vaultzero", "vaultzero-mcp"],
      "env": {
        "VZ_BASE_URL": "https://api.vaultzero.cc",
        "VZ_CREDENTIAL": "<your 64-hex-character bearer credential>",
        "VZ_KEY_STORE_PATH": "~/.vaultzero/keys.json",
        "VZ_EMBEDDING_BASE_URL": "https://<your-embeddings-endpoint>/v1"
      }
    }
  }
}

--from vaultzero is not optional. vaultzero-mcp is the console script inside the vaultzero package, not a package name, so uvx vaultzero-mcp fails with "Because vaultzero-mcp was not found in the package registry". The flag tells uvx which package to install before running that script.

VZ_BASE_URL and VZ_CREDENTIAL are required. The other three are strongly recommended and are described under Configuration.

Docker

docker build -t vaultzero-mcp .
docker run -i --rm \
  -e VZ_BASE_URL=https://api.vaultzero.cc \
  -e VZ_CREDENTIAL=... \
  -v vaultzero-keys:/keys -e VZ_KEY_STORE_PATH=/keys/keys.json \
  vaultzero-mcp

-i without -t: stdio transport needs a raw stdin, not a TTY. The image runs as UID 10001 and ships no pip.

Related MCP server: Decay Memory

Configuration

Trust model

What the server can and cannot see, stated precisely:

• It cannot read a memory: payloads are AES-256-GCM ciphertext, and keys exist only in this process's key store.

• It can see vector embeddings, which are partially invertible to text. Treat the embeddings endpoint and the API origin as part of your data path.

• It can see the shape of your data: scope labels, record sizes, timestamps, and identifiers.

Memory contents are only as safe as the key store. Losing every copy of a key makes its memories unrecoverable by design; production hosts should use FileKeyStore or a KMS/keychain adapter, not the in-memory default.

Contents

• SDK (vaultzero.client.sdk): HTTP lifecycle, retries, key lookup, and local decryption.

• Crypto (vaultzero.client.crypto): AES-256-GCM envelope encryption with authenticated associated data.

• Embeddings (vaultzero.client.embeddings): embedding-provider adapters with pinned embedding-space configuration.

• MCP host (vaultzero.client.mcp_server): a Model Context Protocol server exposing remember_fact and recall_context tools to an agent.

Layout

vaultzero/client/      SDK, MCP adapter, crypto, embedding providers
tests/unit/            golden vectors and unit tests for the client

Installing the SDK

Requires Python 3.10 or newer.

pip install vaultzero

The dependencies (cryptography, httpx, mcp) are installed with the package: this is an MCP server first, so there is no extra to remember. It installs the vaultzero-mcp console script and makes vaultzero.client.sdk.VaultZeroClient importable.

SDK usage

import asyncio

from vaultzero.client.embeddings import EmbeddingSpace, OpenAICompatibleEmbeddings
from vaultzero.client.sdk import FileKeyStore, VaultZeroClient


async def main() -> None:
    client = VaultZeroClient(
        base_url="https://api.example.com",
        credential="<64-hex-character bearer secret>",
        key_store=FileKeyStore("~/.vaultzero/keys.json"),
        embedding_provider=OpenAICompatibleEmbeddings(
            space=EmbeddingSpace(
                space_id="my-space-v1",
                model="text-embedding-3-small",
                revision="1",
                preprocessing="nfc-strip-v1",
            ),
            base_url="https://<customer-controlled-embeddings>",
            api_key=None,
        ),
    )
    memory_id = await client.remember_fact("prefers oat milk in coffee", scope="preferences")
    results = await client.recall_context("coffee milk", scopes=["preferences"])
    await client.delete(memory_id)
    await client.aclose()


asyncio.run(main())

Keys: one active key per scope, resolved only from the bound subject's trusted key store and reused across writes until rotated. Losing every copy of a key makes its memories unrecoverable, so production hosts must use a persistent store (FileKeyStore or a KMS/keychain adapter).

MCP host

Run the MCP host (the trusted process that holds keys and sees plaintext):

VZ_BASE_URL=https://... VZ_CREDENTIAL=<secret> VZ_KEY_STORE_PATH=~/.vaultzero/keys.json \
VZ_EMBEDDING_BASE_URL=https://<customer-controlled-embeddings> vaultzero-mcp

Without VZ_KEY_STORE_PATH keys live in memory and every memory becomes unreadable when the process exits. Optional: VZ_PERMITTED_SCOPES, VZ_RETENTION_CHOICES (add forever only for credentials with a retention grant), VZ_SERVERLESS_TOKEN for IAM-protected endpoints.

Security model

• Local encryption: AES-256-GCM; the associated data binds every envelope to its exact tenant, user, agent, subject epoch, memory id, scope, entity token, key id, embedding space, and expiration.

• No plaintext to the server: the SDK embeds and encrypts before sending anything.

• Integrity on recall: every recalled envelope is re-checked against the authenticated request context before decryption; tampered or mismatched envelopes raise IntegrityError.

• No redirects: the HTTP client never forwards credentials to a redirect target.

Golden vectors live in tests/unit/golden_vectors.json; any other SDK implementation must reproduce them.

Tests

uv run --python .venv/bin/python -m pytest