mentisdb 0.3.0

Semantic, hash-chained durable memory for long-running and multi-agent systems.
Documentation

MentisDB

MentisDB, formerly ThoughtChain, is the standalone durable-memory crate in this repository.

It stores semantically typed thoughts in an append-only, hash-chained memory log through a swappable storage adapter layer. The current default backend is binary, but the chain model is no longer tied to that format. Agents can:

  • persist important insights, decisions, constraints, and checkpoints
  • record retrospectives and lessons learned after hard failures or non-obvious fixes
  • relate new thoughts to earlier thoughts with typed graph edges
  • query memory by type, role, agent, tags, concepts, text, and importance
  • reconstruct context for agent resumption
  • export a Markdown memory view that can back MEMORY.md, MCP, REST, or CLI flows

The crate is intentionally independent from cloudllm so it can be embedded in other agent systems without creating circular dependencies.

Quick Start

If you just want the daemon:

cargo install mentisdb
mentisdbd

If you want to leave it running after closing your SSH session:

nohup mentisdbd &

What Is In This Folder

mentisdb/ contains:

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

Build

From inside mentisdb/:

cargo build

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

cargo build --no-default-features

Test

Run the crate tests:

cargo test

Run tests for the library-only build:

cargo test --no-default-features

Run rustdoc tests:

cargo test --doc

Generate Docs

Build local Rust documentation:

cargo doc --no-deps

Generate docs for the library-only build:

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

Run The Daemon

The standalone daemon binary is mentisdbd.

Run it from source:

cargo run --bin mentisdbd

Install it from the crate directory while working in this repo:

cargo install --path . --locked

When it starts, it serves both:

  • an MCP server
  • a REST server

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

Once startup completes, it prints:

  • the active chain directory, default chain key, and bound MCP/REST 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

mentisdbd is configured with environment variables:

  • MENTISDB_DIR Directory where MentisDB storage adapters store chain files.
  • MENTISDB_DEFAULT_KEY Default chain_key used when requests omit one. Default: borganism-brain
  • MENTISDB_DEFAULT_STORAGE_ADAPTER Default storage backend for newly created chains. Supported values: binary, jsonl. Default: binary
  • MENTISDB_STORAGE_ADAPTER Optional short alias for MENTISDB_DEFAULT_STORAGE_ADAPTER.
  • 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

Example:

MENTISDB_DIR=/tmp/mentisdb \
MENTISDB_DEFAULT_KEY=borganism-brain \
MENTISDB_DEFAULT_STORAGE_ADAPTER=binary \
MENTISDB_BIND_HOST=127.0.0.1 \
MENTISDB_MCP_PORT=9471 \
MENTISDB_REST_PORT=9472 \
cargo run --bin mentisdbd

Server Surfaces

MCP endpoints:

  • GET /health
  • POST /
  • POST /tools/list
  • POST /tools/execute

REST endpoints:

  • GET /health
  • GET /v1/chains
  • POST /v1/bootstrap
  • POST /v1/agents
  • POST /v1/agent
  • POST /v1/agent-registry
  • POST /v1/agents/upsert
  • POST /v1/agents/description
  • POST /v1/agents/aliases
  • POST /v1/agents/keys
  • POST /v1/agents/keys/revoke
  • POST /v1/agents/disable
  • POST /v1/thoughts
  • POST /v1/retrospectives
  • POST /v1/search
  • POST /v1/recent-context
  • POST /v1/memory-markdown
  • POST /v1/head

MCP Tool Catalog

The daemon currently exposes 17 MCP tools:

  • mentisdb_bootstrap Create a chain if needed and write one bootstrap checkpoint when it is empty.
  • mentisdb_append Append a durable semantic thought with optional tags, concepts, refs, and signature metadata.
  • mentisdb_append_retrospective Append a retrospective memory intended to prevent future agents from repeating a hard failure.
  • mentisdb_search Search thoughts by semantic filters, identity filters, time bounds, and scoring thresholds.
  • mentisdb_list_chains List known chains with version, storage adapter, counts, and storage location.
  • mentisdb_list_agents List the distinct agent identities participating in one chain.
  • mentisdb_get_agent Return one full agent registry record, including status, aliases, description, keys, and per-chain activity metadata.
  • mentisdb_list_agent_registry Return the full per-chain agent registry.
  • mentisdb_upsert_agent Create or update a registry record before or after an agent writes thoughts.
  • mentisdb_set_agent_description Set or clear the description stored for one registered agent.
  • mentisdb_add_agent_alias Add a historical or alternate alias to a registered agent.
  • mentisdb_add_agent_key Add or replace one public verification key on a registered agent.
  • mentisdb_revoke_agent_key Revoke one previously registered public key.
  • mentisdb_disable_agent Disable one agent by marking its registry status as revoked.
  • mentisdb_recent_context Render recent thoughts into a prompt snippet for session resumption.
  • mentisdb_memory_markdown Export a MEMORY.md-style Markdown view of the full chain or a filtered subset.
  • mentisdb_head Return head metadata, latest thought summary, and integrity state.

The detailed request and response shapes for the MCP surface live in MENTISDB_MCP.md. The REST equivalents live in MENTISDB_REST.md.

Using With MCP Clients

mentisdbd exposes both:

  • a standard streamable HTTP MCP endpoint at POST /
  • the legacy CloudLLM-compatible MCP endpoints at POST /tools/list and POST /tools/execute

That means you can:

  • use native MCP clients such as Codex and Claude Code against http://127.0.0.1:9471
  • keep using direct HTTP calls or cloudllm's MCP compatibility layer when needed

Codex

Codex CLI expects a streamable HTTP MCP server when you use --url:

codex mcp add mentisdb --url http://127.0.0.1:9471

Useful follow-up commands:

codex mcp list
codex mcp get mentisdb

This connects Codex to the daemon's standard MCP root endpoint.

Qwen Code

Qwen Code uses the same HTTP MCP transport model:

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

Useful follow-up commands:

qwen mcp list

For user-scoped configuration:

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

Claude Code

Claude Code supports MCP servers through its claude mcp commands and project/user MCP config. For a remote HTTP MCP server, the configuration shape is transport-based:

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

Useful follow-up commands:

claude mcp list
claude mcp get mentisdb

Claude Code also supports JSON config files such as .mcp.json. A MentisDB HTTP MCP config looks like this:

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

Important:

  • /mcp inside Claude Code is mainly for managing or authenticating MCP servers that are already configured
  • the server itself must already be running at the configured URL

GitHub Copilot CLI

GitHub Copilot CLI can also connect to mentisdbd as a remote HTTP MCP server.

From interactive mode:

  1. Run /mcp add
  2. Set Server Name to mentisdb
  3. Set Server Type to HTTP
  4. Set URL to http://127.0.0.1:9471
  5. Leave headers empty unless you add auth later
  6. Save the config

You can also configure it manually in ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "mentisdb": {
      "type": "http",
      "url": "http://127.0.0.1:9471",
      "headers": {},
      "tools": ["*"]
    }
  }
}

Retrospective Memory

MentisDB supports a dedicated retrospective workflow for lessons learned.

  • Use mentisdb_append for ordinary durable facts, constraints, decisions, plans, and summaries.
  • Use mentisdb_append_retrospective after a repeated failure, a long snag, or a non-obvious fix when future agents should avoid repeating the same struggle.

The retrospective helper:

  • defaults thought_type to LessonLearned
  • always stores the thought with role = Retrospective
  • still supports tags, concepts, confidence, importance, and refs to earlier thoughts such as the original mistake or correction

Shared-Chain Multi-Agent Use

Multiple agents can write to the same chain_key.

Each stored thought carries a stable:

  • agent_id

Agent profile metadata now lives in the per-chain agent registry instead of being duplicated into every thought record. Registry records can store:

  • display_name
  • agent_owner
  • description
  • aliases
  • status
  • public_keys
  • per-chain activity counters such as thought_count, first_seen_index, and last_seen_index

That allows a shared chain to represent memory from:

  • multiple agents in one workflow
  • multiple named roles in one orchestration system
  • multiple tenants or owners writing to the same chain namespace

Queries can filter by:

  • agent_id
  • agent_name
  • agent_owner

Administrative tools can also inspect and mutate the agent registry directly, so agents can be documented, disabled, aliased, or provisioned with public keys before they start writing thoughts.

Related Docs

At the repository root:

  • MENTISDB_MCP.md
  • MENTISDB_REST.md
  • mentisdb/WHITEPAPER.md
  • mentisdb/changelog.txt