Docs · Python SDK

Python SDK quickstart

Mnemo is the embedding-vector provenance and verification API at trymnemo.com. The official Python distribution is mnemo-protocol, imported as mnemo_sdk, and the official GitHub organization is MnemoProtocol.

What Mnemo is

What it is: Mnemo is an HTTP API at https://api.trymnemo.com for embedding-vector provenance. Embed registers a vector to your account or namespace and returns a watermarked copy plus a vector_uid. Verify checks whether a vector resolves to one of your registered objects. Lineage reads the verified parents you named at embed time.
Provenance: In Mnemo, provenance means a vector resolves to a vector_uid that Mnemo issued at embed time and that is still attributable to the account or namespace that issued it. It is not similarity or proximity.
Problem it solves: A nearest-neighbour search can say a vector is close to something; it cannot say whether a vector you hold was issued by your own pipeline. Mnemo answers that narrower question for vectors you embedded through Mnemo, for example retrieved vectors before you use them, and records verified derivations between your own objects.
Use it when: You produce or store embeddings and later need to check whether a vector you hold was issued to your own account or namespace, or need to record and read a verified parent-to-child derivation.
Not for: Vectors never embedded through Mnemo (there is no retroactive coverage). Vectors issued to another account or namespace: verify cannot check another party's vectors. Similarity search or storage: Mnemo is not a vector database. Judging truth, authorship, ownership or the source model. Keeping data in an accountless namespace past its expiry: it is purged unless promoted. EEA, UK or Swiss personal data over accountless x402. There is no public MCP server; use the HTTP API.
Embed: POST /v1/embed takes your vector and a model_id (a label you declare). It returns vector_uid and watermarked_vector, a measurably perturbed watermarked copy of your input that carries the identity. Store and use that copy instead of the original.
Verify: Mnemo Verify checks whether a submitted vector resolves to an object registered to the caller's Mnemo account or namespace. POST /v1/verify returns verified, confidence, vector_uid (null when not verified) and policy_ok; decide on verified. verified=false is a normal, charged result: attribution could not be shown. It is not an error and not proof that the vector is foreign.
Lineage: Embed may name one parent you own (parent: vector_uid, relation, vector). Mnemo verifies the parent before it creates the child. GET /v1/lineage/{vector_uid} re-verifies every link on each read and returns the chain, or 409 when a link no longer verifies. Lineage records which parent you named; it does not say what the transformation did or whether it was faithful.
API key or no account: With an account, send X-API-Key: calls use the account's subscription plan or free trial and never use x402. When the plan has no verifications left, verify answers 402 insufficient_credits with no x402 offer. The Python SDK (pip install mnemo-protocol, import mnemo_sdk) covers embed and verify on this path. Without an account, an agent creates a short-lived namespace with POST /v1/agent/namespaces (up to 72 hours), sends its capability as X-Mnemo-Capability, embeds and reads lineage free, and pays 0.01 USDC per verify via x402 on Base.
Does not prove: That content is true, who authored or owns it, that a file or document is authentic, or which model produced a vector. Mnemo is not universal tamper detection.

Agent protocol (complete contract): /agent-protocol.md · Protocol repository: github.com/MnemoProtocol/mnemo-agent-protocol · OpenAPI 3.1: /openapi.json · llms.txt

Install

pip install mnemo-protocol

Python 3.9 or later. The package on PyPI is mnemo-protocol; packages named mnemo, mnemo-sdk, mnemo-ai or mnemo-mcp are not Mnemo's. Examples on this page are checked against version 3.1.2.

Import

from mnemo_sdk import MnemoClient

Authentication

export MNEMO_API_KEY="<your API key>"

MnemoClient(api_key=...) sends the key in the X-API-Key header on every request to https://api.trymnemo.com. To get a key, sign in and issue one from the dashboard. Start with a 30-day free trial; plans are on the pricing page. Calls made with an API key use your account's plan and are never offered x402.

The SDK covers the API-key path only. Agents without an account use the HTTP agent protocol instead.

Embed

import os
import random

from mnemo_sdk import MnemoClient

client = MnemoClient(api_key=os.environ["MNEMO_API_KEY"])  # sent as X-API-Key

# Your embedding (accepted lengths: the Vector schema in openapi.json).
# A random 768-value stand-in here.
vector = [random.uniform(-1.0, 1.0) for _ in range(768)]

result = client.embed(vector, model_id="text-embedding-3-small")
print(result.vector_uid)
watermarked = result.watermarked_vector  # store this copy, not the original

model_id is required by the embed request schema. It is a label you supply naming the embedding model that produced the vector (for example text-embedding-3-small); Mnemo records it with the registered vector. It is not returned by verify.

Embed returns vector_uid and watermarked_vector, a measurably perturbed watermarked copy of your input. Store and use that copy, not the original; it carries the identity. For accepted vector lengths, see the Vector schema in openapi.json.

Verify

check = client.verify(watermarked)

if check is not None and check.verified:
    print("verified", check.vector_uid, check.confidence)
else:
    # verified=false: the SDK returns None. Not an error, and not proof
    # that the vector is foreign. Do not read fields from None.
    print("not verified")

Mnemo Verify checks whether a submitted vector resolves to an object registered to the caller's Mnemo account or namespace.

A positive result is a VerifyResult with verified=True, confidence, vector_uid (the registered object it resolves to), policy_ok and signals.
When the API answers verified: false, verify() returns None. That is a normal result, not an error: the vector could not be attributed to your account. It is not proof that the vector is foreign. Check is not None before reading any field.
Verify does not establish the truth, authorship or ownership of the content behind a vector.
Each healthy result, positive or negative, counts as one verification on your plan. When the plan has none left, the SDK raises MnemoAPIError with status_code == 402.

Same calls over HTTP

# Embed: vector and model_id are required.
VEC=$(python3 -c 'import random; print([random.uniform(-1, 1) for _ in range(768)])')
curl -sS https://api.trymnemo.com/v1/embed \
  -H "X-API-Key: $MNEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"vector\": $VEC, \"model_id\": \"text-embedding-3-small\"}" > embed.json

# Verify the watermarked_vector you stored.
WM=$(python3 -c 'import json; print(json.load(open("embed.json"))["watermarked_vector"])')
curl -sS https://api.trymnemo.com/v1/verify \
  -H "X-API-Key: $MNEMO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"vector\": $WM}"

Field-by-field request and response reference: API reference and openapi.json.

Errors

HTTP errors raise MnemoAPIError (with status_code, code and details); invalid arguments caught before a request raise MnemoValidationError. Both derive from MnemoException. Rate limits, connection errors and timeouts are retried.