MentisDB 0.10.3.48 — HNSW Vector Search by Default, Hardened Security, and 16 Critical Fixes

June 20, 2026

This release ships two things: HNSW approximate-nearest-neighbor vector search enabled by default, and a comprehensive security and correctness audit that fixed 16 critical issues across REST auth, dashboard, TLS, webhooks, and the lemma engine. The HNSW backend delivers a 10.9× query speedup at 10k vectors with 91.4% recall, and 100% recall at 50k vectors — all transparent to existing APIs.

HNSW Vector Backend (Headline Feature)

MentisDB now ships with a Hierarchical Navigable Small World (HNSW) graph backend for approximate nearest-neighbor search, enabled by default via the hnsw-backend Cargo feature. The existing exact f32 cosine scan remains the fallback for small sidecars; once a managed vector sidecar exceeds MENTISDB_HNSW_THRESHOLD vectors (default 50,000), MentisDB switches to HNSW automatically.

Both backends implement the same VectorSearchBackend trait, so the public API, hybrid scoring, and ranked search semantics are unchanged. You can disable HNSW at build time by opting out of the hnsw-backend Cargo feature.

Benchmark Results

Corpus	Backend	Query Latency (100 queries)	Recall@10	Speedup
10k × 128d	Exact (linear scan)	95.1 ms	100.0%	—
10k × 128d	HNSW	8.75 ms	91.4%	10.9×
50k × 128d	HNSW	4.23 ms/query	100.0%	—

The 50k result is remarkable: 100% recall at 4.23ms per query. Build time was 232s (one-time, background). HNSW graph persistence means the graph is serialized to disk and reloaded on daemon startup — no rebuild needed after restart.

LoCoMo Regression Check

Full LoCoMo benchmark (1,977 queries, fastembed-minilm vectors) confirmed no regression:

Category	Baseline (0.9.9)	0.10.3.48	Delta
Overall R@10	72.64%	72.53%	−0.11pp (within variance)
Single R@10	76.77%	76.77%	0.00pp (identical)
Multi R@10	57.45%	56.97%	−0.48pp (borderline)

HNSW Runtime Tuning

Four new environment variables control HNSW behavior:

MENTISDB_HNSW_THRESHOLD — corpus size to trigger HNSW (default 50,000)
MENTISDB_HNSW_EF_CONSTRUCTION — build-time search width (default 200)
MENTISDB_HNSW_EF_SEARCH — query-time search width (default 100)
MENTISDB_HNSW_BACKGROUND_BUILD — build off-thread with Exact placeholder (default true)

When background build is enabled, the daemon serves queries from an Exact placeholder while the HNSW graph is constructed off-thread, then swaps the graph in without interrupting queries. Dashboard status exposes backend_kind and backend_building fields.

HNSW Graph Persistence

Built graphs are serialized to {stem}.vectors.{model}.{version}.{dim}d.hnsw.bin and reloaded on daemon startup when the persisted thought count matches the live chain. Stale graphs are deleted when a sidecar is rebuilt from scratch. Writes use an atomic temp-file + rename so readers never see a partial graph.

Security & Correctness Audit — 16 Critical Fixes

A full codebase review identified and fixed 16 critical issues. Here are the most significant:

REST Bearer Auth Scope Bypass (C1)

The REST bearer-token middleware now extracts chain keys from the request body and query string to enforce chain-scoped token authorization. Previously, all REST endpoints accepted any active token regardless of scope, allowing chain-scoped tokens to access any chain.

Dashboard Settings Injection (C2, C3)

The settings API now validates setting names against a whitelist (ALLOWED_SETTING_KEYS) and rejects values containing newlines, preventing arbitrary environment variable injection and .env file injection.

Webhook SSRF Defense (C4)

Webhook URL registration now validates the scheme (http/https only) and rejects URLs pointing to loopback, private, link-local, and CGNAT IP addresses to prevent server-side request forgery.

Constant-Time PIN + Session Tokens (C5, C6)

PIN authentication middleware now uses subtle::ConstantTimeEq for all PIN checks. The session cookie is now a random UUID token instead of the PIN itself, stored in an in-memory sessions map on DashboardState.

TLS Certificate & Key Hardening (C7, C8)

TLS certificates now use dynamic validity (now − 1 day to now + 2 years) instead of the hardcoded 2025–2027 range. TLS private key files are written with 0600 permissions on Unix.

Bearer Token Store Concurrency (C9, C10)

BearerTokenStore now uses a mutex around the read-modify-write cycle on bearer-tokens.json to prevent concurrent token creation from silently losing tokens. Integration config files containing bearer tokens are created with 0600 permissions on Unix.

Other Fixes

Agent/entity-type thought_count no longer doubles on every chain reopen (C11)
compute_thought_hash integrity gap for entity_type and source_episode documented (C12)
BinaryStorageAdapter::clone documentation warns against concurrent writes (C13)
migrate_skill_registry now writes atomically (temp file + rename) (C14)
Lemma -ed stripping: "hoped" → "hope" (was "hop") (C15)
Lemma -ing denylist for common nouns (thing, string, morning, etc.) (C16)

Setup Wizard: Grok CLI Support

The interactive setup wizard (mentisdb wizard) now supports Grok CLI as an integration target, writing to ~/.grok/config.toml on macOS, ~/.config/grok on Linux, and %APPDATA%\grok on Windows. Bearer token collection is now available via --bearer / --token flag or interactive prompt.

Upgrade

cargo install mentisdb --force

For full vector support (real semantic embeddings via ONNX), build with:

cargo install mentisdb --force --features local-embeddings

MentisDB Blog