Hosting

Self hosting

Run the server yourself and own the data, the keys and the schedule.

llms.txt

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:

  1. The server handles every conversation turn (store, recall, extract).
  2. 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:

Terminal
cargo install mentedb-server
mentedb-server --data-dir ./data

Prefer 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.

Terminal
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 the local-embeddings build feature.
  • bedrock: AWS Bedrock, Cohere Embed v3 by default (1024 dims), credentials from env keys or the ECS task role. Requires the bedrock build 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).
Terminal
mentedb-server --data-dir ./data --embedding-provider candle

Pick 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. Its valid_until is set, a supersedes edge links the two, and recall serves only the newer one.
  • flag: both memories stay valid and recallable, and a contradicts edge 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 by GET /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.

Terminal
MENTEDB_CONTRADICTION_POLICY=flag mentedb-server --data-dir ./data

Pinned 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):

Terminal
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):

Python
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 learned

For 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:

JobWhat it does
ConsolidationMerges near-duplicate memories into one richer memory (sources kept, linked).
DecayAges salience so old, unused memories rank lower over time.
ArchivalForgets cold memories flagged for deletion (capped per sweep).
Cache evictionClears stale speculative pre-assembly cache entries.

It is built into the server and on by default (every 24h):

Terminal
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   # disable

Or run it one-shot from cron (set the interval to 0 to avoid double-running):

Terminal
# /etc/cron.d/mentedb, 2am daily
0 2 * * *  mentedb-server maintenance --data-dir /var/lib/mentedb

The 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:

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

Without 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:

Terminal
mentedb-server --data-dir ./data \
  --tls-cert /etc/mentedb/fullchain.pem \
  --tls-key /etc/mentedb/privkey.pem

or 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

SettingDefaultEffect
MENTEDB_RATE_LIMIT_BURST100Requests 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_SEC10Bucket refill per second. 0 turns rate limiting off.
MENTEDB_REQUEST_TIMEOUT_MSno boundUpper 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_MS3000Each Bedrock embedding call gives up after this, so a stalled call fails a write or search quickly.
MENTEDB_LLM_TIMEOUT_SECS120Each extraction or judge LLM call gives up after this.
MENTEDB_LIST_MAX_LIMIT1000Largest page GET /memories returns.
MENTEDB_BATCH_MAX_DATABASES32Most databases one POST /v1/batch/search may name.

Health and readiness

  • GET /v1/live is 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/health also works and adds the version and uptime.
  • GET /v1/ready is 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, default readiness-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=skip leaves the embedder out. It returns 200, or 503 naming the failing checks.
JSON
{
  "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.