Get started
Best practices
How to get the most out of MenteDB, and the mistakes to avoid.
How to get the most out of MenteDB, and the mistakes to avoid.
Storing memory
- Pass the turn, let the engine distill.
process_turnextracts 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.contextto your next prompt, generate, callprocess_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_idinside 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_PROVIDERfor 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; thehashembedder is for tests only. - Let maintenance run. Consolidation, decay, and archival keep memory healthy. Automatic on cloud; on self-host enable
--maintenance-interval-hoursor 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, andPOST /memories/{id}/supersedestores 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.binin 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 LIMITqueries, callMenteDb::warm_salience_boundsright after open, on a background thread. It returns at once when the cache is already complete (for example after a reopen that restoredsalience_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.Rustlet 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 (
=andIN [...]) 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 10loads 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<=oncreatedare answered from the temporal index, and every other condition, LIMIT and ORDER BY still apply:WHERE created > 1700000000000000 AND type = episodic LIMIT 10returns 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 5loads 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, unlesswarm_salience_boundsalready filled it in the background. SetCognitiveConfig::mql_salience_top_kto 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 OFand 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.
agentandspacefilters narrow the results, and a filter with the wrong operator or value type (for exampleagent = "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
SIGTERMor Ctrl+C the server stops accepting connections, lets requests in flight finish for up toMENTEDB_SHUTDOWN_DRAIN_SECS(default10), 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_MSas the upper bound; a caller can ask for less with thex-mentedb-deadline-msheader, never more. Past the deadline the answer is504, 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_BURSTrequests (default100) refilled atMENTEDB_RATE_LIMIT_PER_SEC(default10). Authenticated callers are counted by tokensub(elsejti, else agent), so tenants behind one proxy do not share a budget; anonymous callers by IP.0turns 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 atGET /v1/ready, which also checks that the data directory takes a write and a database can take its lock. Add?embedder=skipwhen 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_KEYand the TLS material asMENTEDB_TLS_CERT_PEMandMENTEDB_TLS_KEY_PEM, with no files to mount. - Scope every token. Give each tenant a token whose
dbsnames only its databases, usereadfor readers, and keepmaintenancefor the jobs that drop or back up databases. See Databases & tokens. - Turn gRPC off if you only use REST.
--grpc-port 0orMENTEDB_GRPC=off, so nothing listens on 6678. - Back up on a schedule and copy off the host.
POST /v1/db/{db}/backupwith a chosen name such as{"name": "nightly/2026-10-19"}writes underMENTEDB_BACKUP_DIR. Restore is offline, so test it.