Hosting
Databases and tokens
Many databases on one server, and tokens scoped to some of them.
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/....
# 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=falseto return404for unknown names instead and create them only throughPOST /v1/databases. - Databases open on first use and stay open.
MENTEDB_MAX_OPEN_DATABASES(default256) 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)
| Endpoint | What it does |
|---|---|
| GET /v1/databases | The default name, every named database on disk, and which are open. |
| POST /v1/databases | Create 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:
| Claim | Meaning |
|---|---|
| exp | Expiry as a Unix timestamp. Required. |
| dbs | Databases 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. |
| scope | read, 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_only | Older spelling of scope: "read". |
| sub | Subject the token was issued to. Keys the rate limit and, with a subject pattern, binds dbs. |
| jti | Token id. Keys the rate limit when there is no sub. |
| agent_id | Optional. 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. |
| admin | Admin endpoints, every database, every agent. |
Tightening tokens minted elsewhere
dbsis required with a public key. When the server verifies with a public key, a non admin token withoutdbsis refused (401), so leaving the claim out can never grant every database.MENTEDB_ALLOW_UNSCOPED_TOKENS=1turns this off. With a shared secret the claim stays optional.- Subject binding.
MENTEDB_JWT_DBS_SUB_PATTERN=tenant.{sub}.*makes everydbsentry match that pattern with{sub}replaced by the token'ssub, or the token is refused. A token forsub: "alice"may nametenant.alice.notesortenant.alice.*, nevertenant.bob.notesor*. Thesubmust 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.
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}'{ "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.
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-authSign 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.
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.