START HEREPython: pip install mnemo-protocol, then follow the SDK quickstart. Agents without an account: the agent protocol.

Core API · Reference

Embed and verify

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.

Base URL https://api.trymnemo.com. The machine-readable contract is openapi.json; this page follows it.

Concepts

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 machine payments. 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 machine payments. When the plan has no verifications left, verify answers 402 insufficient_credits with no payment challenge. 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 per verify with x402 on Base or MPP on Tempo, or funds a 500-verification burst for $5 (x402, Tempo or a card via Stripe).
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

Authentication

Send your account API key in the X-API-Key header on every embed and verify request. The API key is not a bearer token. Calls made with an API key use the account's subscription plan and are never offered a machine payment. Get a key by signing in and issuing one from the dashboard. Start with a 30-day free trial (pricing).

Agents without an account create a namespace and send its capability as X-Mnemo-Capability instead; see the agent protocol.

POST /v1/embed

Watermark and register a vector. Store the returned watermarked_vector.

HTTP request

POST https://api.trymnemo.com/v1/embed
X-API-Key: <your API key>
Content-Type: application/json

{
  "vector": [0.0123, -0.0456, ...],
  "model_id": "text-embedding-3-small"
}

Field	Type	Description
vector	number[] (required)	The embedding: 512 to 4096 finite numbers.
model_id	string (required)	A label you supply naming the model that produced the vector. Recorded with the registered vector.
model_version	string	Defaults to "1.0".
request_id	string	Optional. Use a fresh random UUID per request; reusing one answers 409.
parent	object	Optional. Records a verified derivation from a parent you hold (vector_uid, relation, vector). See the agent protocol.
subject	object	Optional description of what the vector represents (subject_uri, subject_type). If accepted, the response carries subject_proof.

Response (200)

{
  "vector_uid": "<vector_uid>",
  "watermarked_vector": [<same number of values as your input>],
  "created_at": "<timestamp>",
  "dimensions": 768,
  "subject_proof": null,
  "lineage": null
}

Field	Type	Description
vector_uid	string	Identifier of the registered object.
watermarked_vector	number[]	A measurably perturbed watermarked copy of your input. Store and use this copy, not the original; it carries the identity.
created_at	string	Registration time.
dimensions	integer	Length of the vector.
subject_proof	object \| null	Opaque. Pass it back unchanged as subject_proof on verify.
lineage	object \| null	parent_uid, relation and depth when a parent was given.
namespace_expires_at, namespace_state, warning		Accountless namespace callers only.

Python SDK

# abridged; see the SDK README for all parameters
client.embed(
    vector,                  # list[float] or numpy array
    model_id,                # str, required
    *,
    model_version="1.0",
    subject=None,
) -> EmbedResult             # vector_uid, watermarked_vector, created_at, dimensions, subject_proof

Errors include 400 for an invalid vector (for example vector_dimension_unsupported), 401 for an invalid API key and 422 for unknown or mistyped fields. The full list is in openapi.json.

POST /v1/verify

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

HTTP request

POST https://api.trymnemo.com/v1/verify
X-API-Key: <your API key>
Content-Type: application/json
Idempotency-Key: <optional replay key>

{
  "vector": <the watermarked_vector array you stored>
}

Field	Type	Description
vector	number[] (required)	The vector to check, usually the watermarked_vector you stored (Vector schema in openapi.json).
subject_proof	object	Optional. The subject_proof returned by embed, unchanged.
request_id	string	Optional. A fresh random UUID if sent.
Idempotency-Key	header	Optional replay key: the same key and body return the stored result without a second charge. The SDK sends one on every call.

Response (200), verified

{
  "verified": true,
  "confidence": <number>,
  "vector_uid": "<vector_uid>",
  "policy_ok": <true | false>,
  "signals": {<diagnostic metadata>},
  "lineage": <object | null>
}

Response (200), not verified

{
  "verified": false,
  "confidence": <number>,
  "vector_uid": null,
  "policy_ok": false,
  "lineage": null
}

Field	Type	Description
verified	boolean	The verdict. Decide on this field.
confidence	number	Returned with every healthy result.
vector_uid	string \| null	The registered object the vector resolves to; null when verified is false.
policy_ok	boolean	A policy signal separate from the verdict; always false when verified is false.
signals	object \| null	Diagnostic metadata. Informational; fields may change. Do not build decisions on it.
lineage	object \| null	has_parent, parent_uid, depth for a verified object; null means unknown.

What the result means

verified: true means the vector resolves to an object registered to your account or namespace, identified by vector_uid.
verified: false is a healthy, normal result, not an error: the vector could not be attributed to your account or namespace. It is not proof that the vector is foreign. Healthy results, true or false, each count as one verification.
A verification that cannot complete is never a 200: it is 503 verification_unavailable and is not charged. With an API key whose plan has no verifications left, verify answers 402 {"code": "insufficient_credits"}, with no payment challenge.
Verify does not establish the truth, authorship or ownership of the content behind a vector.

Python SDK

client.verify(
    vector,
    *,
    subject_proof=None,
    idempotency_key=None,
) -> VerifyResult | None     # None when verified is false

The SDK returns None when the API answers verified false, so check result is not None before reading fields. Full example on the SDK page.

Glossary

watermarked_vector: The copy of your vector that embed returns. It carries the identity; store it instead of the original.
vector_uid: The identifier of a registered object, returned by embed and by a positive verify.
API key: An account credential, sent as X-API-Key. Calls use the account's subscription plan; never a machine payment.
namespace: A short-lived, accountless workspace an agent creates over HTTP. See the agent protocol.
capability: The namespace credential, sent as X-Mnemo-Capability. Verify on a namespace is paid per call ($0.01 with x402 or MPP on Tempo) or from a 500-verification burst.

For pilot access and integration help, request a pilot.