Hosting
Self hosting
Run the server yourself and own the data, the keys and the schedule.
Run the engine yourself. You own the data, the LLM keys, and the schedule. If you would rather not run anything, use the managed cloud instead, one API key and you are done.
There are two moving parts to understand:
- The server handles every conversation turn (store, recall, extract).
- The maintenance sweep runs periodically to keep memory healthy (merge duplicates, forget stale facts, decay old ones). This is the part people forget, so it is built in, see Step 5 below.
Step 1: Install the server
With Cargo:
cargo install mentedb-server
mentedb-server --data-dir ./dataPrefer a container? The Docker image bundles local embeddings and starts with zero config, compose file and env included.
Step 2: Configure an LLM (recommended)
What it does: the LLM extracts what matters from each turn (facts, preferences, corrections), detects contradictions, and powers consolidation. Without it you still get storage and keyword/vector recall, but no automatic fact extraction.
export MENTEDB_LLM_PROVIDER=anthropic # openai | anthropic | ollama | none
export MENTEDB_LLM_API_KEY=sk-ant-...
export MENTEDB_LLM_MODEL=claude-sonnet-5-5 # optional, default claude-haiku-5-5
mentedb-server --data-dir ./data --auto-extract--auto-extract (or MENTEDB_AUTO_EXTRACT=1) turns on per-turn extraction. For a fully local setup, point MENTEDB_LLM_PROVIDER=ollama and MENTEDB_LLM_BASE_URL=http://localhost:11434/api/chat (the full endpoint URL).
Claude 5.5 models think before answering by default, and the thinking counts against the output limit. MENTEDB_LLM_MAX_OUTPUT_TOKENS (default 16000) sets the output ceiling per call, thinking included; a call that hits it fails with a clear error instead of returning a partial answer. MENTEDB_LLM_EFFORT (low, medium, high; unset keeps the model default) trades thinking for speed and cost.
Running on AWS? Use AWS Bedrock for Claude and Cohere embeddings on the ECS task role, with no API key.
Step 3: Choose an embedding provider
What it does: embeddings power semantic search, auto-linking, and contradiction detection. Without a real embedder only keyword recall works.
candle(default in the Docker image): local, semantic (all-MiniLM-L6-v2, 384 dims), no API key. Requires thelocal-embeddingsbuild feature.bedrock: AWS Bedrock, Cohere Embed v3 by default (1024 dims), credentials from env keys or the ECS task role. Requires thebedrockbuild feature (the Docker image has it). See AWS Bedrock.hash: deterministic but not semantic. Fine for testing, weak for recall.none: disables embeddings (not recommended).
mentedb-server --data-dir ./data --embedding-provider candlePick one embedder per data directory and keep it: stored vectors are compared with query vectors, so switching models (or dimensions) means re-embedding.
Contradictions: supersede or flag
When a new memory contradicts an older one (the same sentence with a changed value, like "my favorite coffee is a cortado" then "... a flat white", or an LLM verdict that one fact replaces the other), the engine resolves it at write time. MENTEDB_CONTRADICTION_POLICY picks how:
supersede(default): the older memory is closed. Itsvalid_untilis set, asupersedesedge links the two, and recall serves only the newer one.flag: both memories stay valid and recallable, and acontradictsedge links them. Use this when your application wants to show the conflict to a person or an agent and let it decide. Flagged pairs are listed byGET /v1/conflicts.
Memories stored with the correction type always supersede, under either policy, because the caller already made the decision. Any other value of the variable stops the server at startup.
MENTEDB_CONTRADICTION_POLICY=flag mentedb-server --data-dir ./dataPinned memories never fade
A memory tagged scope:always is pinned: it is included in every heads-up context, keeps its salience instead of decaying, and is never archived by the maintenance sweep. Pin and unpin over REST with POST and DELETE /v1/memories/{id}/pin, and list pins with GET /v1/pins. Keep pins for standing rules; everything else should be allowed to age.
To exempt other memories from decay and archival, list their tags in MENTEDB_DECAY_EXEMPT_TAGS (comma separated; it replaces the default scope:always, so include it to keep pins exempt), or set the attribute named by MENTEDB_DECAY_EXEMPT_ATTRIBUTE (default decay_exempt) to boolean true.
Step 4: Use it
Every turn goes through one call. process_turn embeds the message, runs hybrid recall (vector + keyword + graph), stores the turn, extracts facts, detects contradictions, and returns attention-ordered context for your prompt.
REST (the server serves the same call at /v1/process_turn):
curl -X POST http://localhost:6677/v1/process_turn \
-H "Content-Type: application/json" \
-d '{"user_message":"I switched from Postgres to SQLite",
"assistant_response":"Noted.",
"turn_id":0}'Every other endpoint (hybrid search, heads-up context, history, pins, documents, maintenance) is listed in the REST API reference.
SDK (Python / TypeScript / Rust):
from mentedb import MenteDB
db = MenteDB("./data")
result = db.process_turn(user_message="...", assistant_response="...", turn_id=0)
# result.context -> memories for your prompt; result.facts_extracted -> what was learnedFor the full turn-by-turn agent loop in Python, Node, and Rust, see Self-hosted (embedded).
Step 5: Overnight maintenance
This is what keeps memory from turning into a junk drawer. The sweep runs, in order:
| Job | What it does |
|---|---|
| Consolidation | Merges near-duplicate memories into one richer memory (sources kept, linked). |
| Decay | Ages salience so old, unused memories rank lower over time. |
| Archival | Forgets cold memories flagged for deletion (capped per sweep). |
| Cache eviction | Clears stale speculative pre-assembly cache entries. |
It is built into the server and on by default (every 24h):
mentedb-server --data-dir ./data # sweeps every 24h
mentedb-server --data-dir ./data --maintenance-interval-hours 12
mentedb-server --data-dir ./data --maintenance-interval-hours 0 # disableOr run it one-shot from cron (set the interval to 0 to avoid double-running):
# /etc/cron.d/mentedb, 2am daily
0 2 * * * mentedb-server maintenance --data-dir /var/lib/mentedbThe built in scheduler sweeps every database open at sweep time, the default one and the named ones. The one-shot command sweeps the default database at the data directory root. To run a job on one named database on demand, call POST /v1/db/{db}/maintenance/sweep (or decay, archive, consolidate).
If you never run it: duplicates pile up, stale facts keep getting recalled, and old low-value memories never decay, recall quality degrades over time. Do not skip it.
Production notes
Run with auth on:
export MENTEDB_JWT_SECRET=$(openssl rand -base64 32)
mentedb-server --data-dir ./data --require-authWithout a JWT secret or public key every endpoint is open, fine for local, not for a public host; --require-auth makes the server refuse to start without one. Tokens can be limited to some databases and to a read, write or maintenance scope, and the server can verify tokens with a public key so it holds no secret at all; see Databases & tokens. The full environment variable table is in Environment variables.
HTTPS
The server can terminate TLS itself, no proxy needed. Pass a PEM certificate chain and its private key:
mentedb-server --data-dir ./data \
--tls-cert /etc/mentedb/fullchain.pem \
--tls-key /etc/mentedb/privkey.pemor set MENTEDB_TLS_CERT_FILE and MENTEDB_TLS_KEY_FILE. With both set, the REST API on 6677 serves HTTPS only (HTTP/1.1 and HTTP/2) and gRPC on 6678 uses TLS with the same certificate. With neither set the server speaks plain HTTP. Setting only one of the two, an unreadable file, or a key that does not match the certificate stops the server at startup, so a typo never falls back to plaintext. The files are read once at start; restart after renewing the certificate.
When a secret store injects values rather than files, pass the PEM text itself in MENTEDB_TLS_CERT_PEM and MENTEDB_TLS_KEY_PEM. Both must be set, and setting them together with the file options is a startup error.
Without TLS, keep the server on a private network or behind a proxy that terminates TLS, since tokens and memory content would otherwise cross the network in the clear.
gRPC
gRPC listens on --grpc-port (default 6678) and serves the default database with the same token checks as REST: the token's dbs must admit default, and Store, Forget and Relate need the write scope. If you only use REST, turn it off with --grpc-port 0 or MENTEDB_GRPC=off.
Stopping the server
On SIGTERM (what Docker, ECS and Kubernetes send before killing a task) or Ctrl+C, the server stops accepting connections, lets requests in flight finish for up to MENTEDB_SHUTDOWN_DRAIN_SECS (default 10), then flushes and closes every open database, releasing their directory locks, and exits with status 0. Set the stop timeout a few seconds above the drain window. Acknowledged writes are durable either way; a clean stop also saves the snapshots, so the next start is fast.
Limits, deadlines and timeouts
| Setting | Default | Effect |
|---|---|---|
| MENTEDB_RATE_LIMIT_BURST | 100 | Requests per caller bucket. Callers are keyed by token sub, else jti, else agent, and by IP without a token. 0 turns rate limiting off. Over the limit is 429. |
| MENTEDB_RATE_LIMIT_PER_SEC | 10 | Bucket refill per second. 0 turns rate limiting off. |
| MENTEDB_REQUEST_TIMEOUT_MS | no bound | Upper bound on every request, 504 past it. The x-mentedb-deadline-ms header can only shorten it; a header that is not a whole number is 400. |
| MENTEDB_EMBEDDING_TIMEOUT_MS | 3000 | Each Bedrock embedding call gives up after this, so a stalled call fails a write or search quickly. |
| MENTEDB_LLM_TIMEOUT_SECS | 120 | Each extraction or judge LLM call gives up after this. |
| MENTEDB_LIST_MAX_LIMIT | 1000 | Largest page GET /memories returns. |
| MENTEDB_BATCH_MAX_DATABASES | 32 | Most databases one POST /v1/batch/search may name. |
Health and readiness
GET /v1/liveis liveness only. It answers{"status": "alive"}without touching any database, the disk or the embedder, so a slow dependency never gets a healthy process restarted. Point liveness probes here.GET /v1/healthalso works and adds the version and uptime.GET /v1/readyis readiness. It checks that the default database answers, the data directory takes a write (a read only or full mount shows up here), a probe database opens and takes its lock (MENTEDB_READY_PROBE_DB, defaultreadiness-probe; empty turns the check off), and the embedder, if any, can embed (reused for 30 seconds). Each check times out after 5 seconds.?embedder=skipleaves the embedder out. It returns200, or503naming the failing checks.
{
"status": "ready",
"checks": { "database": "ok", "data_dir": "ok", "database_lock": "ok", "embedder": "ok" }
}None of these needs a token. Route traffic, and point load balancer checks, only at instances whose /v1/ready answers 200, so an instance whose Bedrock access broke or whose volume went read only leaves rotation instead of failing writes.