Developer Documentation

Overview

MentisDB is a standalone Rust crate available on crates.io. Add it to your project:

The crate provides the full memory engine, skill registry, storage adapter interface, agent registry, and optional HTTP server stack (MCP + REST + dashboard) behind the server feature flag.

Full API Reference

The complete, generated API documentation is hosted on docs.rs:

MCP Server

MentisDB ships a built-in MCP (Model Context Protocol) HTTP server. Enable it with the server feature. All MentisDB operations are exposed as MCP tools over JSON-RPC 2.0 via HTTP, making it compatible with any MCP-capable AI tool. The canonical onboarding path is not a separate URL: it happens during the MCP initialize call via startup instructions plus the embedded resource mentisdb://skill/core exposed through resources/list and resources/read.

Default HTTP endpoint: http://127.0.0.1:9471 — HTTPS endpoint: https://127.0.0.1:9473.

All 37 MCP Tools

JSON-RPC Request/Response Example

MCP uses JSON-RPC 2.0 over HTTP. Send a POST to the MCP endpoint:

POST / HTTP/1.1
Host: 127.0.0.1:9471
Content-Type: application/json

{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "mentisdb_append",
"arguments": {
"chain_key": "default",
"agent_id": "assistant",
"thought_type": "Insight",
"content": "Memory deduplication triggers when Jaccard similarity exceeds threshold",
"importance": 0.7,
"confidence": 0.9,
"tags": ["feature:dedup"],
"concepts": ["memory-dedup", "jaccard-similarity"]
}
}
}

// Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "Thought appended: a1b2c3... (index 42)"
}
]
}
}

MCP HTTP Ports

The MCP server listens on two ports:

• http://127.0.0.1:9471 — HTTP (unencrypted), suitable for local development
• https://127.0.0.1:9473 — HTTPS (TLS), recommended for production

The daemon binary (mentisdb) starts the MCP server automatically. For embedding in your own Axum app, see the docs.rs API reference for server module details.

REST API

The same daemon also serves a REST API alongside MCP. Key endpoints:

For MCP-native agents, prefer the streamable HTTP root at POST / and let the agent bootstrap itself from the initialize instructions and resource catalog.

For direct crate users, 0.8.0 keeps vector sidecars additive and rebuildable, but ranked search now blends lexical, graph, and managed-sidecar vector signals automatically when sidecars are enabled. The append-only chain remains canonical; sidecars are derived acceleration state.

The daemon now applies persisted managed-vector settings whenever it opens a chain. By default each chain gets the built-in local-text provider (local-text-v1), and ranked search across REST, MCP, and dashboard surfaces upgrades to hybrid scoring when that sidecar is available.

REST Example: POST /v1/thoughts (Append Thought)

POST /v1/thoughts HTTP/1.1
Host: 127.0.0.1:9471
Content-Type: application/json

{
"chain_key": "default",
"agent_id": "assistant",
"thought_type": "Insight",
"content": "Memory deduplication triggers when Jaccard similarity exceeds threshold",
"importance": 0.7,
"confidence": 0.9,
"tags": ["feature:dedup"],
"concepts": ["memory-dedup", "jaccard-similarity"],
"scope": "user",
"relations": [
{ "kind": "ContinuesFrom", "target_id": "<uuid-of-prior-turn>" }
]
}

// Response:
{
"thought": {
"id": "a1b2c3d4-...",
"index": 42,
"hash": "9f14...",
"thought_type": "Insight",
"content": "Memory deduplication triggers when Jaccard similarity exceeds threshold",
"agent_id": "assistant",
"importance": 0.7,
"confidence": 0.9,
"tags": ["feature:dedup"],
"concepts": ["memory-dedup", "jaccard-similarity"],
"created_at": "2026-04-14T12:00:00Z"
}
}

REST Example: POST /v1/ranked-search

POST /v1/ranked-search HTTP/1.1
Host: 127.0.0.1:9471
Content-Type: application/json

{
"chain_key": "default",
"text": "how does memory deduplication work",
"scope": "user",
"limit": 10,
"enable_reranking": true,
"rerank_k": 50
}

// Response:
{
"results": [
{
"thought": {
"id": "a1b2c3d4-...",
"thought_type": "Insight",
"content": "Memory deduplication triggers when Jaccard similarity exceeds threshold",
"importance": 0.7
},
"score": 4.82,
"lexical_score": 1.2,
"vector_score": 3.1,
"session_cohesion": 0.4,
"rank": 1
}
],
"total": 1,
"query_time_ms": 12
}

REST Example: POST /v1/context-bundles

POST /v1/context-bundles HTTP/1.1
Host: 127.0.0.1:9471
Content-Type: application/json

{
"chain_key": "default",
"text": "memory deduplication decision",
"scope": "user",
"limit": 5
}

// Response:
{
"bundles": [
{
"seed": {
"id": "a1b2c3d4-...",
"thought_type": "Decision",
"content": "Enable dedup at 0.85 Jaccard threshold",
"score": 5.1
},
"supporting": [
{
"id": "b2c3d4e5-...",
"thought_type": "LessonLearned",
"content": "Previous attempts at 0.95 threshold produced too many false negatives",
"chain_key": "default"
}
],
"children": []
}
]
}

REST Example: POST /v1/webhooks/register

POST /v1/webhooks/register HTTP/1.1
Host: 127.0.0.1:9471
Content-Type: application/json

{
"chain_key": "default",
"url": "https://myapp.example.com/mentisdb-webhook",
"event_types": ["thought.append", "thought.relation.added"]
}

// Response:
{
"webhook": {
"id": "wh_abc123",
"chain_key": "default",
"url": "https://myapp.example.com/mentisdb-webhook",
"event_types": ["thought.append", "thought.relation.added"],
"created_at": "2026-04-14T12:00:00Z",
"status": "active"
}
}

0.8.0 Search & Storage Improvements

MentisDB 0.8.0 introduces five major improvements to the search and storage pipeline: Porter stemming, tiered vector-lexical fusion, importance weighting, bincode hashing, and managed sidecar entries with auto_sync.

Porter Stemming (Normalizer v2)

The lexical tokenizer now applies English Porter stemming. Words like preferences → prefer and running → run now match in lexical search. Existing chains auto-reindex on first open — no manual migration step required.

Tiered Vector-Lexical Fusion

Ranked search scoring replaces the flat addition model with a tiered boost that respects the relationship between lexical and vector signals:

• Lexical = 0 and vector > 0: vector × 60 — full boost for semantic-only hits
• 0 < lexical < 1.0 and vector > 0: vector × (1 + 20 × fraction) — partial boost proportional to lexical overlap
• Lexical ≥ 1.0: vector as-is — no boost, lexical dominates

Failed logins are rate-limited per-IP to prevent brute-force enumeration; the dashboard is always served over TLS so the PIN is never transmitted in the clear on a local network.

Automatic Thesaurus in Ranked Search (0.9.9)

The static thesaurus (~900 headwords + 300+ lemmas) now applies <strong>automatically by default</strong> to every ranked search query (REST <code>POST /v1/ranked-search</code>, MCP <code>mentisdb_ranked_search</code>, dashboard, and CLI). No client changes or extra parameters are required. With full embeddings this delivered the target LoCoMo-10P $R@10 = 72.6%. The expansion happens server-side via <code>apply_thesaurus_if_text</code> before BM25 scoring.

Benchmarking

MentisDB ships with two benchmark styles:

• Criterion microbenchmarks for in-process append, query, traversal, import, and skill-registry hot paths
• HTTP concurrency benchmarks for live mentisdb write/read waves under concurrent client load

Run the full benchmark suite with:

This currently runs cargo bench and saves stdout to /tmp/mentisdb_bench_results.txt.

Durable vs Buffered Write Mode

Benchmark write-heavy changes in both persistence modes. They now behave differently enough that one run is not representative of the other:

• MENTISDB_BENCH_AUTO_FLUSH=true — durable mode. Appends are queued to the bounded background writer and the request only returns after the writer flushes them. Concurrent appends may share a short group-commit window.
• MENTISDB_BENCH_AUTO_FLUSH=false — buffered mode. Appends are queued and acknowledged before the worker flushes them, trading durability for higher write throughput.

MENTISDB_BENCH_AUTO_FLUSH=true  cargo bench --bench http_concurrency
MENTISDB_BENCH_AUTO_FLUSH=false cargo bench --bench http_concurrency

Criterion Baselines

Criterion benchmarks such as thought_chain and skill_registry automatically compare the current run against the saved baseline in target/criterion/. That is why the output includes messages like Performance has improved, Performance has regressed, or No change in performance detected.

• time: [low mid high] — lower is better
• thrpt: [low mid high] — higher is better
• change — percentage delta versus the saved baseline
• p < 0.05 — the change is statistically meaningful

If you have changed the benchmark harness itself or want a fresh comparison, clear the old Criterion baseline before trusting the regression/improvement messages.

HTTP Concurrency Baselines

The custom http_concurrency benchmark now persists its own baselines under target/http_concurrency/ and prints delta tables on later runs. This means you no longer need to manually compare the Markdown output tables by eye.

MENTISDB_BENCH_AUTO_FLUSH=true  MENTISDB_BENCH_BASELINE=durable  cargo bench --bench http_concurrency
MENTISDB_BENCH_AUTO_FLUSH=false MENTISDB_BENCH_BASELINE=buffered cargo bench --bench http_concurrency

Useful environment variables:

• MENTISDB_BENCH_CONCURRENCY — comma-separated client counts such as 100,1000,10000
• MENTISDB_BENCH_AUTO_FLUSH — true for durable group commit, false for buffered throughput mode
• MENTISDB_BENCH_BASELINE — names the saved baseline file so you can keep separate durable, buffered, nightly, or branch-specific histories

How to Read the HTTP Table

• wall_ms — total time for the whole wave
• req/s — throughput
• p50_ms, p95_ms, p99_ms — median and tail latency
• errors — non-2xx responses or transport failures

For write-path work, focus on the Write — POST /v1/thoughts table at high concurrency. Read-path changes should primarily move the Read — POST /v1/head table and the query/traversal Criterion benches.

What to Benchmark After Storage Changes

• cargo bench --bench thought_chain append_single -- --noplot — strict append latency
• cargo bench --bench thought_chain query_by_tag -- --noplot — indexed query path
• cargo bench --bench thought_chain traverse_filtered_miss_10 -- --noplot — full-scan traversal miss path
• cargo bench --bench http_concurrency — live daemon concurrency behavior

A useful workflow is to measure a clean baseline on master, apply the storage change, rerun the same focused benches, and only then trust the wider make bench output.

Contributing

MentisDB is open source under the MIT license.

Run the test suite:

Run benchmarks: