April 17, 2026

MentisDB 0.9.2.38 — Smart Stdio MCP, Shared Service State, and Reproducible Benchmarks

0.9.2.38 is a release about correctness. Two fixes in particular close long-standing integration gaps that were easy to miss and expensive to debug: stdio MCP clients no longer need a pre-launched daemon, and the multi-surface server no longer splits brain across HTTP, HTTPS, MCP, REST, and the dashboard. Benchmarks are now reproducible bit-identical across full-scale runs.

Headline: plug MentisDB into Claude Desktop with zero pre-flight steps. No mentisdbd &, no mcp-remote, no shell init. The stdio process finds or launches the daemon itself and proxies cleanly to it so every surface shares the same live chain cache.

Smart Stdio MCP Mode

When an MCP client (Claude Desktop, Cursor, or anything that spawns an stdio subprocess) starts mentisdbd in stdio mode, the process now:

Probes the local daemon's health endpoint.
If a daemon is already running, it proxies stdio requests to the HTTP MCP surface so every client sees the same live chain cache.
If not, it launches a background daemon (nohup on Unix, start /B on Windows), waits for health, and proxies to it.
If launch fails, it falls back to in-process stdio mode so the client still works.

The result is that Claude Desktop users stop fighting MCP bootstrap. One entry in claude_desktop_config.json pointing at mentisdbd is the whole setup. Multiple stdio clients running side-by-side observe each other's appends in real time because they all talk to the same daemon process.

Background and details: see the Stdio MCP Mode with Smart Daemon Detection post.

Cross-Surface State Coherency in `start_servers`

Before 0.9.2.38, start_servers constructed each surface — HTTP MCP, HTTP REST, HTTPS MCP, HTTPS REST, and the dashboard — with its own MentisDbService::new(...). Each service owned a private DashMap<chain_key, Arc<RwLock<MentisDb>>>, so an append that went in through REST was invisible to MCP (and vice versa) until the daemon restarted and both services happened to reload the chain from disk.

The fix is small and surgical: start_servers now constructs one MentisDbService and shares it across every surface it boots. Single-surface entry points (start_mcp_server, start_rest_server, start_https_*_server) are unchanged.

A regression test (start_servers_shares_state_across_mcp_and_rest) pre-warms the MCP service, appends a thought via REST, and asserts the MCP side immediately sees the new head_hash, thought_count, and latest_thought.index — no restart, no reload.

Backup and Restore

Two new subcommands, mentisdbd backup and mentisdbd restore, create and restore .mbak archives of the full MENTISDB_DIR.

SHA-256 manifest for every file; verification before any file is written on restore.
--flush, --include-tls, --overwrite flags.
CLI auto-detects a running daemon and calls POST /v1/admin/flush before reading files.
Interactive conflict prompt lists conflicting files when --overwrite is not supplied; declining exits cleanly with no changes.
Restore rejects path-traversal entries (../escape.txt, absolute paths) with InvalidData before extraction.
33 integration tests covering roundtrip, TLS inclusion, idempotent restore, overwrite, corruption detection, manifest round-trip, and subdirectory creation.

POST /v1/admin/flush

A new REST endpoint iterates every open chain and calls flush() on its BinaryStorageAdapter. Backup uses it automatically; operators can call it directly before snapshotting the data directory with an external tool.

Search and Relation Correctness

Federated search dedup now keeps the higher-scoring duplicate occurrence instead of whichever chain surfaced the UUID first — matching the documented contract.
Relation dedup no longer collapses distinct edges that differ by chain_key, valid_at, or invalid_at; only exact duplicates are removed.
Branch ancestor discovery is transitive — branch-aware search walks child to parent to grandparent instead of stopping at the direct parent.
Webhook registry persistence now uses temp-file-plus-rename instead of truncating the live registry in place; delivery fan-out is bounded by a queue and semaphore so bursty append workloads no longer spawn unbounded tasks.

Wizard and Client Fixes

Wizard prompts before brew install mcp-remote on macOS (previously silent); brew is tried first, npm is the fallback; dead check_node_version and detect_brew_mcp_remote helpers removed.
When mcp-remote is installed as an absolute executable, the wizard uses it directly without a node wrapper; the shebang-based fallback is retained for npm-installed scripts.
Restore's interactive confirmation actually enables overwrite mode when the user answers yes (previously it silently kept overwrite=false unless --overwrite was passed).
pymentisdb.context_bundles() now decodes typed ContextBundleSeed and ContextBundleHit objects instead of nesting ContextBundle inside itself; append_thought() uses one canonical ThoughtInput builder; ranked_search() and context_bundles() accept MemoryScope enums directly.
LLM memory extraction no longer sends an OpenAI response_format hint — some OpenAI-compatible endpoints rejected the schema; MentisDB now relies on the prompt plus strict JSON validation of the returned payload, preserving provider portability.

Startup: Terminal-Close Warning

mentisdbd now prints a yellow warning at daemon startup that closing the terminal stops the process, followed by an OS-specific background-launch tip:

macOS: nohup mentisdbd > ~/.cloudllm/mentisdb/mentisdbd.log 2>&1 &
Linux: systemd user service unit snippet or a nohup one-liner.
Windows: schtasks /create one-liner or Start-Process -WindowStyle Hidden.

Benchmarks

Benchmarks on 0.9.2.38 are deterministic: three independent full-scale runs (2026-04-14 and two on 2026-04-17) produced bit-identical scores.

Benchmark	Metric	Result
LoCoMo 10-persona	R@10	71.9%
LongMemEval	R@5	66.8%
LongMemEval	R@10	72.2%
LongMemEval	R@20	78.0%

The WHITEPAPER now documents the reproducibility caption under the results table and fills in previously empty LoCoMo cells (single-hop 75.8%, multi-hop 57.4%, R@20 79.1%).

The retrieval pipeline that produces these numbers is described end-to-end in Inside MentisDB Ranked Search — One Call, One Pipeline.

WHITEPAPER Refresh

WHITEPAPER.md was rewritten in academic register with formal definitions (Thought, Chain, BM25, RRF, Jaccard dedup, temporal validity), a tamper-evidence proof sketch, and a References section. A LaTeX port (WHITEPAPER.tex) uses amsmath/amsthm/booktabs, and build-whitepaper.sh includes macOS and Ubuntu install instructions with --open/--clean flags.

Upgrade

cargo install mentisdb --locked --force

Claude Desktop users: you no longer need to pre-launch mentisdbd. Point your MCP config at the mentisdbd binary in stdio mode and the process will find or start the daemon itself. See the stdio MCP walkthrough for the exact config.

No schema migration. Webhook registrations, backups, and existing chains from 0.9.1.x carry forward unchanged.