MentisDB

MentisDB is a durable semantic memory engine and versioned skill registry for AI agents — a persistent, hash-chained brain that survives context resets, model swaps, and team turnover.

It stores semantically typed thoughts in an append-only, hash-chained memory log through a swappable storage adapter layer. The skill registry is a git-like immutable version store for agent instruction bundles — every upload is a new version, history is never overwritten, and every version is cryptographically signable.

Why MentisDB

Harness Swapping — the same durable memory works across every AI coding environment. Connect Claude Code, OpenAI Codex, GitHub Copilot CLI, Qwen Code, Cursor, VS Code, or any MCP-capable host to the same mentisdb daemon and your agents share one brain, regardless of which tool you picked up today.

Zero Knowledge Loss Across Context Boundaries — when an agent's context window fills, it writes a Summary checkpoint to MentisDB, compacts, reloads mentisdb_recent_context, and continues without losing a single decision. Chat history is ephemeral. MentisDB is permanent.

Fleet Orchestration at Scale — one project manager agent decomposes work, dispatches a parallel fleet of specialists, each pre-warmed with shared memory, and synthesizes results wave by wave. MentisDB is the coordination substrate: every agent reads from the same chain and writes its lessons back. The fleet's collective intelligence compounds.

Versioned Skill Registry — skills are not just stored, they are versioned like a git repository. Every upload to an existing skill_id creates a new immutable version (stored as a unified diff). Any historical version is reconstructable. Skills can be deprecated or revoked while full audit history is preserved. Uploading agents with registered Ed25519 keys must cryptographically sign their uploads — provenance is verifiable, not assumed.

Session Resurrection — any agent can call mentisdb_recent_context and immediately know exactly where the project stands, what decisions were made, what traps were already hit, and what comes next — without re-reading code, re-running exploratory searches, or asking the human to re-explain context that was earned through hours of work.

Self-Improving Agent Fleets — agents upload updated skill files after learning something new. A skill checked in at the start of a project is better by the end of it. Combine with Ed25519 signing to create a verifiable, tamper-evident record of which agent authored which version of institutional knowledge.

Multi-Agent Shared Brain — multiple agents, multiple roles, multiple owners can write to the same chain key simultaneously. Every thought carries a stable agent_id. Queries filter by agent identity, thought type, role, tags, concepts, importance, and time windows. The chain represents the full collective intelligence of an entire orchestration system, not just one session.

Lessons That Outlive Models — architectural decisions, hard constraints, non-obvious failure modes, and retrospectives written to MentisDB survive chat loss, model upgrades, and team changes. The knowledge compounds instead of evaporating. A new engineer or a new agent boots up, loads the chain, and inherits everything the team learned.

Installation

Prerequisites

macOS

Install the Xcode Command Line Tools (required for native crates):

xcode-select --install

Ubuntu / Debian

On a fresh Ubuntu or Debian system you need a few development packages before cargo install will succeed (especially because the default build enables audio support for the TUI startup chime).

sudo apt update
sudo apt install -y \
    build-essential \
    pkg-config \
    libssl-dev \
    libasound2-dev \
    curl

Then install Rust (if you don't already have it):

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Headless servers / minimal installs

If you are installing on a server and do not want the startup sound (and the ALSA dependency), install without the default features:

cargo install mentisdb --no-default-features --features server

This produces a smaller binary with no audio dependencies.

Quick Start

Install the daemon (after completing the platform-specific prerequisites above):

cargo install mentisdb --features local-embeddings

The local-embeddings feature enables the built-in fastembed-minilm ONNX embedding provider for real semantic vector search. Without it, MentisDB falls back to local-text-v1 (text hashing). The auto-updater also installs with --features local-embeddings.

Connect your local AI tools the fast way:

mentisdb wizard

Or target one integration explicitly:

mentisdb setup codex
mentisdb setup all --dry-run
mentisdb wizard
mentisdb add "The sky is blue"
mentisdb search "cache invalidation" --limit 5 --scope session
mentisdb agents

Then start the daemon:

mentisdb

When run in an interactive terminal, mentisdb launches a full TUI with scrollable panes for configuration, chain/agent/skill tables, and a live event log. On an interactive first run with no configured client integrations, it offers to launch the setup wizard immediately after startup so you do not have to guess the next command.

Run persistently after closing your SSH session:

nohup mentisdb &

Headless mode. The daemon now auto-promotes to headless HTTP mode whenever stdin or stdout is not a TTY — so every common non-interactive launch (Docker without -t, nohup mentisdb &, systemd without StandardInput=tty, cron, an SSH session that was disconnected) gets the right behavior automatically without you having to remember the flag. To force the headless code path on a machine that does have a TTY (for testing, or to suppress the dashboard), pass the explicit flag:

mentisdb --headless               # HTTP/MCP/REST only, no TUI
mentisdb --mode http --headless   # equivalent; the stdio-proxy form

Both forms are accepted in either flag order. mentisdb --help lists the flag in the Usage block and gives a full description under Flags.

Modern MCP clients bootstrap themselves from the MCP handshake:

• initialize.instructions tells the agent to read mentisdb://skill/core
• resources/read(mentisdb://skill/core) delivers the embedded operating skill
• GET /mentisdb_skill_md remains available only as a compatibility fallback

If you need to wire a tool manually, here are the raw MCP commands/configs:

# Claude Code
claude mcp add --transport http mentisdb http://127.0.0.1:9471

# OpenAI Codex
codex mcp add mentisdb --url http://127.0.0.1:9471

# Qwen Code
qwen mcp add --transport http mentisdb http://127.0.0.1:9471

# GitHub Copilot CLI — use /mcp add in interactive mode,
# or write ~/.copilot/mcp-config.json manually (see below)

What Is In This Folder

mentisdb/ contains:

• the standalone mentisdb library crate
• server support for HTTP MCP and REST, enabled by default
• the mentisdb daemon binary
• dedicated tests under mentisdb/tests

Makefile

A Makefile is included at the repository root. All common workflows have a target:

make build          # fmt + release build
make build-mentisdb # build only the daemon binary
make release        # fmt, check, clippy, build, test, doc in sequence
make fmt            # cargo fmt
make check          # cargo check (lib + binary)
make clippy         # cargo fmt + clippy --all-targets -D warnings
make test           # cargo test
make bench          # Criterion benchmarks, output tee'd to /tmp/mentisdb_bench_results.txt
make doc            # cargo doc --all-features
make install        # cargo install --path . --locked --features local-embeddings
make publish        # cargo publish
make publish-dry-run
make clean
make help           # list all targets with descriptions

Build

make build

Or directly with Cargo:

cargo build --release

Build only the library without the default daemon/server stack:

cargo build --no-default-features

Test

make test

Or directly:

cargo test

Run tests for the library-only build:

cargo test --no-default-features

Run rustdoc tests:

cargo test --doc

Benchmarks

MentisDB ships a Criterion benchmark suite and a harness-free HTTP concurrency benchmark:

make bench

Or directly:

cargo bench

Results are also written to /tmp/mentisdb_bench_results.txt so numbers persist across terminal sessions.

Benchmark coverage:

• benches/thought_chain.rs — 10 benchmarks: append throughput, query latency, traversal patterns
• benches/search_baseline.rs — 4 benchmarks: lexical/filter-first search baseline over content, registry text, indexed+text intersections, and newest-tail limits
• benches/search_ranked.rs — 4 benchmarks: additive ranked retrieval over lexical content, filtered ranked queries, and heuristic fallback, plus a baseline append-order comparison
• benches/skill_registry.rs — 12 benchmarks: skill upload, search, delta reconstruction, lifecycle
• benches/http_concurrency.rs — starts mentisdb in-process on a random port; measures write and read throughput at 100 / 1k / 10k concurrent Tokio tasks with p50/p95/p99 latency reporting

Baseline numbers from the DashMap concurrent chain lookup refactor: 750–930 read req/s at 10k concurrent tasks, compared to a sequential bottleneck on the previous RwLock<HashMap> implementation.

Generate Docs

make doc

Or directly:

cargo doc --no-deps

Generate docs for the library-only build:

cargo doc --no-deps --no-default-features

Run The Daemon

The standalone executable is mentisdb.

Run it from source:

cargo run --bin mentisdb

Install it from the crate directory:

make install
# or
cargo install --path . --locked

mentisdb now owns both daemon startup and local integration setup:

mentisdb setup codex
mentisdb setup all --dry-run
mentisdb wizard
mentisdb add "The sky is blue"
mentisdb search "cache invalidation" --limit 5 --scope session
mentisdb agents
mentisdb

When it starts, it serves:

• an MCP server
• a REST server
• an HTTPS web dashboard

Before serving traffic, it:

• migrates or reconciles discovered chains to the current schema and default storage adapter
• verifies chain integrity and attempts repair from valid local sources when possible
• migrates the skill registry from V1 to V2 format if needed (idempotent; safe to run repeatedly)
• migrates chain relations from V2 to V3 format to add temporal edge validity (valid_at/invalid_at) if needed (idempotent; safe to run repeatedly)

Once startup completes, it prints:

• the active chain directory, default chain key, and bound MCP/REST/dashboard addresses
• a catalog of all exposed HTTP endpoints with one-line descriptions
• a per-chain summary with version, adapter, thought count, and per-agent counts

Daemon Configuration

mentisdb is configured with environment variables:

• MENTISDB_DIR Directory where MentisDB storage adapters store chain files.
• MENTISDB_DEFAULT_CHAIN_KEY Default chain_key used when requests omit one. Default: borganism-brain. MENTISDB_DEFAULT_KEY is accepted as a deprecated alias.
• MENTISDB_STORAGE_ADAPTER Default storage backend for newly created chains. Only binary is supported for new chains (JSONL is deprecated — existing JSONL chains remain readable). Default: binary
• MENTISDB_VERBOSE When unset, verbose interaction logging defaults to true. Supported explicit values: 1, 0, true, false.
• MENTISDB_LOG_FILE Optional path for interaction logs. When set, MentisDB writes interaction logs to that file even if console verbosity is disabled. If MENTISDB_VERBOSE=true, the same lines are also mirrored to the console logger.
• MENTISDB_BIND_HOST Bind host for both HTTP servers. Default: 127.0.0.1
• MENTISDB_MCP_PORT MCP server port. Default: 9471
• MENTISDB_REST_PORT REST server port. Default: 9472
• MENTISDB_DASHBOARD_PORT HTTPS dashboard port. Default: 9475. Set to 0 to disable the web dashboard.
• MENTISDB_DASHBOARD_PIN Optional PIN required to access the dashboard. Leave unset only for trusted localhost use.
• MENTISDB_BEARER_TOKEN_ACCESS Require bearer tokens for MCP requests. Default: false. Set true for remote or multi-user MCP servers. This can also be toggled live from the dashboard Settings screen.
• MENTISDB_AUTO_FLUSH Controls per-write durability of the binary storage adapter.
• true (default): every append_thought flushes to disk immediately. Full durability.
• false: writes are batched and flushed every 16 appends (FLUSH_THRESHOLD). Up to 15 thoughts may be lost on a hard crash or power failure, but write throughput increases significantly for multi-agent hubs with many concurrent writers. Supported values: 1, 0, true, false. Has no effect on the jsonl adapter.
• MENTISDB_GROUP_COMMIT_MS Group-commit window in milliseconds for the background binary writer. The writer batches appends within this window before flushing to disk. Lower values = lower latency; higher values = better throughput. Default: 2
• MENTISDB_UPDATE_CHECK Background GitHub release check for mentisdb. Enabled by default; set 0, false, no, or off to disable update checks after startup. Default: true
• MENTISDB_UPDATE_REPO Optional GitHub owner/repo override used by the updater. Default: CloudLLM-ai/mentisdb
• MENTISDB_HTTPS_MCP_PORT HTTPS MCP server port. Default: 9473. Se