Hosting

Databases and tokens

Many databases on one server, and tokens scoped to some of them.

llms.txt

One server can hold many separate databases, one per person, team or organization, and hand out tokens that reach only some of them, or only read. Everything here applies to the self-hosted server.

Named databases

Every database route exists twice: /v1/... acts on the default database at the data directory root, and /v1/db/{db}/... acts on a named one. Each named database lives in <data-dir>/dbs/<name> with its own lock, indexes and files; nothing is shared between them but the process and the embedder. /v1/db/default/... is the same as /v1/....

Terminal
# Store into alice's database, then search it
curl -X POST http://localhost:6677/v1/db/alice/memories \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"agent_id":"00000000-0000-0000-0000-000000000001",
       "memory_type":"semantic","content":"Prefers dark mode"}'

curl -X POST http://localhost:6677/v1/db/alice/search/hybrid \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"query":"display preferences","k":5}'
  • Names use letters, digits, -, _ and ., at most 128 characters, not starting with ..
  • A named database is created on first use. Set MENTEDB_AUTO_CREATE_DATABASES=false to return 404 for unknown names instead and create them only through POST /v1/databases.
  • Databases open on first use and stay open. MENTEDB_MAX_OPEN_DATABASES (default 256) caps how many named ones stay open; past it, the least recently used idle one is flushed and closed, and reopens with its data on the next request.

Managing databases (admin)

EndpointWhat it does
GET /v1/databasesThe default name, every named database on disk, and which are open.
POST /v1/databasesCreate one: {"name": "alice"}. 409 if it exists.
DELETE /v1/databases/{name}Close and permanently delete a named database. The default one cannot be deleted; 409 while a request is using it.
DELETE /v1/db/{db}The same drop, also allowed for a maintenance scope token whose dbs names the database, so a tenant can drop its own databases without the admin key.

Database management, backups and drops accept either the admin key (MENTEDB_ADMIN_KEY) in x-api-key or Authorization: Bearer, or a token with the admin claim. POST .../backup and DELETE /v1/db/{db} also accept a maintenance token naming the database. The console endpoints (/admin/...) take only the admin key.

Scoped tokens

A token is a JWT. Its claims decide what it may touch:

ClaimMeaning
expExpiry as a Unix timestamp. Required.
dbsDatabases the token may use: exact names, or globs where * matches any run of characters (tenant.alice.*). "default" is the root one, "*" means all. Absent means all, unless the server requires the claim (below). Any other database gets 403.
scoperead, write (the default) or maintenance; each includes the ones before it. read may use GET routes and POST to /recall, /search, /search/hybrid, /context, /query and /recall_for_action; every other POST, PATCH and DELETE gets 403. maintenance adds dropping and backing up the databases in dbs, and must carry dbs. Any other value makes the token invalid (401).
read_onlyOlder spelling of scope: "read".
subSubject the token was issued to. Keys the rate limit and, with a subject pattern, binds dbs.
jtiToken id. Keys the rate limit when there is no sub.
agent_idOptional. When set, the token is bound to that agent: a body naming another agent_id gets 403, another agent's memories cannot be read or changed by id, and hybrid search, context and the list endpoints are scoped to it. Leave it empty for a token scoped to databases instead.
adminAdmin endpoints, every database, every agent.

Tightening tokens minted elsewhere

  • dbs is required with a public key. When the server verifies with a public key, a non admin token without dbs is refused (401), so leaving the claim out can never grant every database. MENTEDB_ALLOW_UNSCOPED_TOKENS=1 turns this off. With a shared secret the claim stays optional.
  • Subject binding. MENTEDB_JWT_DBS_SUB_PATTERN=tenant.{sub}.* makes every dbs entry match that pattern with {sub} replaced by the token's sub, or the token is refused. A token for sub: "alice" may name tenant.alice.notes or tenant.alice.*, never tenant.bob.notes or *. The sub must be letters, digits, - and _, and a token without one is refused.

Issuing tokens with a shared secret

With a shared secret, the server issues tokens itself. POST /v1/auth/token needs the admin key and takes agent_id, expiry_hours (default 24), dbs, scope, sub and read_only, all optional. Every token gets a fresh jti. It never issues admin tokens.

Terminal
export MENTEDB_JWT_SECRET=$(openssl rand -base64 32)
export MENTEDB_ADMIN_KEY=$(openssl rand -hex 32)
mentedb-server --data-dir ./data --require-auth

# A read token for alice's databases, valid for 7 days
curl -X POST http://localhost:6677/v1/auth/token \
  -H "x-api-key: $MENTEDB_ADMIN_KEY" -H "Content-Type: application/json" \
  -d '{"dbs":["tenant.alice.*"],"scope":"read","sub":"alice","expiry_hours":168}'
JSON
{ "token": "eyJ...", "agent_id": "", "dbs": ["tenant.alice.*"], "read_only": false, "scope": "read", "sub": "alice" }

Public key verification

To keep no secret on the server, sign tokens in another service and give the server only the public key. MENTEDB_JWT_PUBLIC_KEY_FILE points at a PEM public key; the algorithm follows the key: RSA uses RS256, EC P-256 uses ES256, Ed25519 uses EdDSA. When set, it replaces the shared secret for verification. MENTEDB_JWT_ISSUER and MENTEDB_JWT_AUDIENCE, when set, also require matching iss and aud claims. To pass the key from a secret store instead of a file, set MENTEDB_JWT_PUBLIC_KEY to the PEM text, or to the base64 of the DER encoded public key; setting both is a startup error.

Terminal
openssl genpkey -algorithm ed25519 -out signer.pem      # stays with your token service
openssl pkey -in signer.pem -pubout -out mentedb-jwt.pub  # goes to the server

export MENTEDB_JWT_PUBLIC_KEY_FILE=/etc/mentedb/mentedb-jwt.pub
export MENTEDB_JWT_ISSUER=https://auth.example.com          # optional
export MENTEDB_JWT_AUDIENCE=mentedb                         # optional
mentedb-server --data-dir ./data --require-auth

Sign the same claims as above (exp and dbs, plus scope, sub, jti, agent_id, admin as needed). In this mode the server verifies with the public key only, so tokens from /v1/auth/token are refused; your service mints them.

Python
import time, uuid, jwt  # pip install pyjwt cryptography

claims = {
    "dbs": ["tenant.alice.*"],
    "scope": "write",
    "sub": "alice",
    "jti": str(uuid.uuid4()),
    "exp": int(time.time()) + 3600,
}
token = jwt.encode(claims, open("signer.pem").read(), algorithm="EdDSA")

--require-auth refuses to start without MENTEDB_JWT_SECRET, MENTEDB_JWT_PUBLIC_KEY or MENTEDB_JWT_PUBLIC_KEY_FILE. Without any of them, auth is off and every endpoint is open.

Backups

POST /v1/db/{db}/backup (or /v1/backup for the default database) flushes the database and writes one file, <backup-dir>/<db>/<db>-<UTC time>.mentebackup, and returns its manifest. GET .../backups lists them, newest first. Both take the admin key or an admin token; POST .../backup also accepts a maintenance token whose dbs names the database. The backup directory is MENTEDB_BACKUP_DIR, default <data-dir>/backups. Writes that land while the files are read may or may not be included; pause writers first for an exact point in time.

To choose the file name, send a body such as {"name": "nightly/2026-10-19"}. The name is a relative path of letters, digits, -, _ and . separated by /; absolute paths, empty segments and .. are a 400. It always lands under <backup-dir>/<db>/, with .mentebackup appended when missing, and a name that already exists is a 409.

There is no restore endpoint, because replacing the files of an open database is unsafe. Restore offline: stop the server, restore the file into an empty directory (the data directory root for the default database, <data-dir>/dbs/<name> for a named one) with the Rust API BackupManager::restore_backup(file, dir), then start the server.