User Guide

Installation

MentisDB requires Rust. If you don't have it:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Then install MentisDB:

cargo install mentisdb

Running the Daemon

Start the daemon — it listens on port 9471 by default:

mentisdbd

To keep it running after closing your terminal:

nohup mentisdbd &

The daemon serves both MCP (for AI tools) and REST endpoints from the same port.

Configuration

MentisDB is configured via environment variables:

Variable	Default	Description
`MENTISDB_DATA_DIR`	`~/.mentisdb`	Where chain data is stored on disk
`MENTISDB_PORT`	`9471`	Port for the HTTP server
`MENTISDB_AUTO_FLUSH`	`true`	Flush to disk on every write. Set to `false` for higher throughput (less durability)
`MENTISDB_DEFAULT_CHAIN`	`default`	The chain key used when no `chain_key` is specified

Connecting Your AI Tool

Once the daemon is running, connect your AI coding tool via MCP:

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

GitHub Copilot CLI

Add to ~/.copilot/mcp-config.json:

{
  "servers": {
    "mentisdb": {
      "url": "http://127.0.0.1:9471",
      "type": "http"
    }
  }
}

Qwen Code

qwen mcp add --transport http mentisdb http://127.0.0.1:9471

The Skills Registry

The skills registry is a versioned, immutable store for agent instruction bundles (skill files). Think of it like git for your agent's operating procedures.

Uploading a skill

Skills are uploaded as Markdown files. Each upload to an existing skill_id creates a new immutable version (stored as a diff):

Call mentisdb_upload_skill with three required fields: agent_id (the uploading agent's registered identity), skill_id (a stable slug like "my-project-conventions"), and content (the raw Markdown of the skill file). If the agent has registered public keys, also provide signing_key_id and skill_signature to create a cryptographically verified upload.

Retrieving a skill

Use mentisdb_read_skill(skill_id) to get the latest version, or pass version_id for a specific historical version. Full version history is always preserved.

Cryptographic Signatures

Agents with registered Ed25519 public keys must cryptographically sign their skill uploads. This creates a verifiable, tamper-evident record of authorship.

Registering an agent key

Use mentisdb_add_agent_key to register an Ed25519 public key for an agent. Once registered, all uploads from that agent must include a valid signature over the skill content.

Why this matters

Signed skills mean you always know which agent authored which version. Combined with the immutable version history, this creates a cryptographically auditable record of your fleet's institutional knowledge.