Get started

Best practices

How to get the most out of MenteDB, and the mistakes to avoid.

llms.txt

How to get the most out of MenteDB, and the mistakes to avoid.

Storing memory

  • Pass the turn, let the engine distill. process_turn extracts the facts, preferences, and corrections worth keeping. You do not need to store raw transcripts, send the exchange and let MenteDB decide what matters.
  • The whole loop is one call. Prepend result.context to your next prompt, generate, call process_turn, repeat.
  • Storage is synchronous. A stored memory is retrievable immediately. Deeper enrichment (semantic extraction, entity linking, the profile) runs as a background sleeptime pass and catches up shortly after.

Isolation

  • Always pass user_id and agent_id. A missing id means global, and global is shared with every user. See Multi-user isolation.
  • One account (API key) per tenant for the hardest boundary; user_id / agent_id inside it.
  • Never use project_context for isolation. It is an advisory tag, not a boundary.

Configuration (self-host)

  • Point it at an LLM. Set MENTEDB_LLM_PROVIDER for fact extraction and contradiction detection. Without it you still get storage and recall, just no automatic distillation.
  • Use a real embedder. candle (local) or a provider gives semantic recall; the hash embedder is for tests only.
  • Let maintenance run. Consolidation, decay, and archival keep memory healthy. Automatic on cloud; on self-host enable --maintenance-interval-hours or cron the sweep. Skipping it degrades recall over weeks.

Reliability

  • Use a stable, monotonic turn_id per conversation.
  • Pass session_id so a turn is not injected back into its own context.
  • State corrections naturally("actually it is X now"). The engine detects the contradiction and supersedes the stale fact, you do not delete and re-add.
  • Update or supersede explicitly when you know. On the self hosted server, PATCH /memories/{id} changes attributes, tags or the validity window in place, and POST /memories/{id}/supersede stores the replacement and closes the old memory, kept for history.
  • Edited memories stay searchable. From 0.41, a memory stored again under its id (an edit, a re store with a new vector, or a re embed) is found by vector search with its current vector. Earlier versions could drop it from vector search.
  • Reserve global (no ids) for genuinely app-wide knowledge: policies, product facts, docs.

Durability and flushing (embedded engine)

  • A write is durable when it returns. The engine appends it to the write ahead log and fsyncs the log before acknowledging, so you do not need flush() for durability.
  • Do not call flush() after every write. Each call is a checkpoint: it fsyncs the data file and rewrites the memory map when anything changed, which turns a cheap write into an expensive one. Flush periodically, or rely on the automatic checkpoint the engine runs once the log grows past 8 MB.
  • Call close() on shutdown. It runs flush_full(), which also saves the index, graph and cognitive snapshots, so the next open loads them instead of rebuilding. close_quick() checkpoints the log and saves only the small salience cache file (salience_bounds.bin), so the next open still finds every memory, rebuilds the snapshots it skipped, and starts with a warm salience cache.
  • The server does this for you. It flushes after maintenance and at shutdown.

Fast reopen

  • Open reads only what changed. At every checkpoint the engine saves a map of which page holds which memory (memory_map.bin in the database directory). Open loads that map and replays only the log written since that checkpoint, instead of reading every page. Measured on 20,000 memories on a local SSD, open after a clean close went from 859 ms and 20,000 page reads to 43 ms and none.
  • Expect one full scan after upgrading. The first open after upgrading to 0.40 reads every page once and writes the map, and the opens after it are fast. The same happens once if the map is missing, damaged, or does not match the log.
  • Keep checkpoints regular. A reopen after a crash reads the pages the log touched since the last checkpoint. In the same benchmark, a crash with 100 writes since the checkpoint reopened with 200 page reads instead of 40,302.
  • Mode rules are warm after open. Their activation probes are saved with the snapshots, so the first recall after open costs about the same as a warm one. If the probe file is missing, InjectionConfig::mode_probe_load_budget (default 256) caps how many probes one request loads, so the reload spreads over several requests instead of one slow one.
  • Warm the salience cache after open. If you embed the engine and serve ORDER BY salience DESC LIMIT queries, call MenteDb::warm_salience_bounds right after open, on a background thread. It returns at once when the cache is already complete (for example after a reopen that restored salience_bounds.bin), and otherwise loads the missing entries in chunks with no lock held across a page load, so stores, recall, queries and maintenance keep running and no query waits for it. A write that lands during the warm wins. Its cancel check runs before every chunk: make it return false before you close the database or hand it to another owner, and wait for the call to return.
    Rust
    let report = db.warm_salience_bounds(
        &SalienceWarmConfig::default(),
        &|| !closing.load(Ordering::Relaxed),
    )?;

Fast queries

  • Filter on type, tag or agent and add a LIMIT. Equality on these (= and IN [...]) is answered from the bitmap index, so only matching memories load, and without ORDER BY loading stops once LIMIT results are found. RECALL memories WHERE type = episodic LIMIT 10 loads 10 memories whatever the database size (on 20,000 memories: 20,000 loads and 982 ms before, 10 loads and 0.5 ms now).
  • A range on created uses the time index. >, >=, < and <= on created are answered from the temporal index, and every other condition, LIMIT and ORDER BY still apply: WHERE created > 1700000000000000 AND type = episodic LIMIT 10 returns at most 10 episodic memories.
  • ORDER BY salience DESC with a LIMIT loads only the top. The engine caches the inputs to each memory's decayed salience (base salience, last access, access count, decay exemption) and saves them with the snapshots, so it visits candidates from the highest current salience down and stops once the next one cannot beat the LIMIT'th result. RECALL memories WHERE type = episodic ORDER BY salience DESC LIMIT 5 loads 5 memories once the cache is warm, more only when several tie at the cutoff. Results, ties included, are identical to sorting every candidate. On a cold cache (the first open after an upgrade, or a lost cache file) the first such query loads every candidate once to fill it, unless warm_salience_bounds already filled it in the background. Set CognitiveConfig::mql_salience_top_k to false to always sort every candidate.
  • Any other ORDER BY sees every candidate. Another field, or ASC, has to load every memory that passes the indexed filters before it can sort. Leave it out when any matches will do; unordered results come back in storage order.
  • Other conditions are checked after loading. Conditions on content, space, salience, confidence, accessed, AS OF and any != run on each loaded memory, and a WHERE with OR, NOT, parentheses, or no indexed filter visits every memory. Pair them with a type, tag, agent or created filter to keep the loaded set small.
  • Agent and space filters apply. agent and space filters narrow the results, and a filter with the wrong operator or value type (for example agent = "alice", which is not a UUID) is a query error instead of a filter that matches everything. See MQL.

Large databases

  • Maintenance no longer stalls traffic. Archival and consolidation copy page ids out of the page map and release its lock before loading pages, so recall and stores keep running during a pass. In the benchmark, recall p50 during an archival pass went from 920 ms to 4.6 ms.
  • On network storage, count page reads. Every page read is a round trip, so regular checkpoints (the server's maintenance flush and the 8 MB automatic checkpoint both count) and type or tag filtered queries with a LIMIT matter most there.

Running the server in production

  • Give shutdown room to drain. On SIGTERM 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 and exits with status 0. Set the orchestrator's stop timeout a few seconds above the drain window so the close finishes before a kill.
  • Bound every request. Set MENTEDB_REQUEST_TIMEOUT_MS as the upper bound; a caller can ask for less with the x-mentedb-deadline-ms header, never more. Past the deadline the answer is 504, and long handlers (paged lists, batch search, consolidation candidates) stop between steps.
  • Size the rate limit per caller. Each caller gets a bucket of MENTEDB_RATE_LIMIT_BURST requests (default 100) refilled at MENTEDB_RATE_LIMIT_PER_SEC (default 10). Authenticated callers are counted by token sub (else jti, else agent), so tenants behind one proxy do not share a budget; anonymous callers by IP. 0 turns it off.
  • Probe liveness and readiness separately. Point liveness at GET /v1/live, which touches no database, disk or embedder, so an embedding outage never restarts a healthy process. Point readiness and load balancer checks at GET /v1/ready, which also checks that the data directory takes a write and a database can take its lock. Add ?embedder=skip when the probe must not call the embedding service.
  • Keep secrets in the environment. A secret store can inject the JWT public key as MENTEDB_JWT_PUBLIC_KEY and the TLS material as MENTEDB_TLS_CERT_PEM and MENTEDB_TLS_KEY_PEM, with no files to mount.
  • Scope every token. Give each tenant a token whose dbs names only its databases, use read for readers, and keep maintenance for the jobs that drop or back up databases. See Databases & tokens.
  • Turn gRPC off if you only use REST. --grpc-port 0 or MENTEDB_GRPC=off, so nothing listens on 6678.
  • Back up on a schedule and copy off the host. POST /v1/db/{db}/backup with a chosen name such as {"name": "nightly/2026-10-19"} writes under MENTEDB_BACKUP_DIR. Restore is offline, so test it.