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

Default features include local-embeddings (FastEmbed MiniLM over ONNX Runtime). The prebuilt Intel macOS (x86_64-apple-darwin) release binary is built without it, because ONNX Runtime ships no prebuilt library for that target; it uses the built-in local-text-v1 vectors instead. Builds with --no-default-features (optionally re-adding --features server) are supported.

Prebuilt Binaries

Every GitHub release ships ready-to-run binaries for macOS (mentisdb-macos-arm64, mentisdb-macos-x86_64), Windows (mentisdb-windows-x86_64.exe) and Linux. Since 0.10.10, Linux binaries come in two flavours (#21):

AssetLocal embeddingsMinimum glibcRuns on
mentisdb-linux-x86_64, mentisdb-linux-arm64yes (FastEmbed)2.39Ubuntu 24.04+, Debian 13+, Fedora 40+, RHEL 10, Arch
mentisdb-linux-x86_64-compat, mentisdb-linux-arm64-compatno2.34Ubuntu 22.04 LTS, Debian 12, RHEL 9, and everything newer

The full builds need a recent glibc because the prebuilt ONNX Runtime they link for local embeddings is itself built against glibc 2.38+. The -compat builds are compiled on Ubuntu 22.04 without the local-embeddings and startup-sound features: lexical search and local-text-v1 vectors work as usual, but there is no fastembed-minilm semantic vector provider (the same trade-off as the Intel macOS binary) and no startup chime, so they need no ALSA (libasound.so.2) on the host. Release CI fails the build if a -compat binary ever needs a glibc newer than 2.35. Check your glibc with:

ldd --version | head -1     # e.g. "ldd (Ubuntu GLIBC 2.35-0ubuntu3) 2.35"

# Example: Ubuntu 22.04 on x86_64
curl -fLo mentisdb https://github.com/CloudLLM-ai/mentisdb/releases/latest/download/mentisdb-linux-x86_64-compat
chmod +x mentisdb && ./mentisdb --help

A full binary started on an older glibc fails immediately with version `GLIBC_2.39' not found. If you are on an older distro and want local embeddings, use the Docker image: it is self-contained and has full features regardless of the host's glibc. (Building from source with --features local-embeddings does not avoid the floor, because the ONNX Runtime library it downloads needs glibc 2.38+ too.)

Docker

Multi-arch (linux/amd64, linux/arm64) images are published to GitHub Container Registry on every release (starting with 0.10.10.55), tagged with the release tag (0.10.10.55), the crate version (0.10.10) and latest. It is also the way to get full features, including local embeddings, on Linux distros older than glibc 2.39. The image runs mentisdb --headless as a non-root user under tini, so no TTY is needed and docker stop shuts the daemon down cleanly.

docker run -d --name mentisdb \
      -p 127.0.0.1:9471:9471 -p 127.0.0.1:9472:9472 -p 127.0.0.1:9475:9475 \
      -v mentisdb-data:/var/lib/mentisdb \
      ghcr.io/cloudllm-ai/mentisdb:latest

    curl http://127.0.0.1:9472/health
  • /var/lib/mentisdb is MENTISDB_DIR: chains, skills, TLS certificates and the local-embedding model cache (.fastembed_cache) persist in the volume. Bind mounts must be writable by uid 991.
  • Ports: 9471 MCP, 9472 REST, 9475 dashboard (HTTPS). HTTPS MCP/REST (9473/9474) are disabled in the image; enable them with MENTISDB_HTTPS_MCP_PORT / MENTISDB_HTTPS_REST_PORT.
  • Base image: debian:trixie-slim (glibc 2.41). The image is self-contained, so the host's glibc does not matter.
  • Any variable from Configuration can be passed with -e.

Security. The container binds 0.0.0.0 so published ports work, and a fresh daemon has no authentication. Publish ports on 127.0.0.1 unless a TLS reverse proxy or VPN is in front, set MENTISDB_BEARER_TOKEN_ACCESS=true (create tokens with docker exec mentisdb mentisdb bearertoken create --global admin), set MENTISDB_DASHBOARD_PIN, and add the hostnames you use to reach the dashboard to MENTISDB_DASHBOARD_ALLOWED_HOSTS.

Running the Daemon

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

mentisdb

To keep it running after closing your terminal:

nohup mentisdb &

The daemon serves both MCP (for AI tools) and REST endpoints plus an HTTPS dashboard for human operators.

Headless Mode

The daemon auto-promotes to headless HTTP mode whenever stdin or stdout is not a TTY. 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. The HTTP/MCP/REST servers come up and the process idles near 0% CPU.

To run 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.

CLI subcommands for quick operations without an MCP client:

mentisdb add "The sky is blue"
mentisdb search "cache invalidation" --limit 5
mentisdb agents

Configuration

MentisDB is configured via environment variables:

VariableDefaultDescription
Storage
MENTISDB_DIR~/.cloudllm/mentisdbWhere chain data and TLS files are stored on disk
MENTISDB_DEFAULT_CHAIN_KEY
(deprecated alias: MENTISDB_DEFAULT_KEY)
borganism-brainThe chain key used when no chain_key is specified
MENTISDB_STORAGE_ADAPTERbinaryStorage format for new chains. Only binary is accepted; the JSONL adapter can no longer be used to create new chains. Existing JSONL chains remain fully readable and migratable — the adapter is retained for reading and migrating legacy data only
MENTISDB_GROUP_COMMIT_MS2Group-commit window in milliseconds for the background binary writer. Appends already queued are batched within this window; a lone append with nothing else queued is flushed immediately. Lower values = lower latency; higher values = better throughput
MENTISDB_AUTO_FLUSHtrueEach append returns after its group commit is written to the chain file. Set to false for higher throughput (less durability)
MENTISDB_FSYNCoffSet 1 to fsync after every group commit (power-loss durability, roughly 4x append latency). Explicit flush, shutdown and drop always sync
Limits
MAX_THOUGHT_PAYLOAD_BYTES10 MBMaximum size of a single thought payload. Lowered from 64 MB as DoS protection. Oversized writes are rejected with an error
MAX_SKILL_SIZE_BYTES1 MBUpload size limit for a single skill file. Exceeding this limit rejects the upload
Networking — HTTP
MENTISDB_BIND_HOST127.0.0.1IP address the server binds to. Use 0.0.0.0 for network-wide access (combine with a dashboard PIN)
MENTISDB_MCP_PORT9471HTTP MCP server port
MENTISDB_REST_PORT9472HTTP REST API port
Networking — HTTPS
MENTISDB_HTTPS_MCP_PORT9473HTTPS MCP server port. Set to 0 to disable
MENTISDB_HTTPS_REST_PORT9474HTTPS REST API port. Set to 0 to disable
TLS
MENTISDB_TLS_CERT~/.cloudllm/mentisdb/tls/cert.pemPath to the TLS certificate PEM (auto-generated on first start)
MENTISDB_TLS_KEY~/.cloudllm/mentisdb/tls/key.pemPath to the TLS private key PEM (auto-generated on first start)
Logging
MENTISDB_VERBOSEtrueEnable verbose startup and request logging
MENTISDB_LOG_FILEunsetOptional path to write logs to a file
RUST_LOGinfoLog level filter (trace, debug, info, warn, error)
Audio
MENTISDB_STARTUP_SOUNDtruePlay a 4-note jingle on startup
MENTISDB_THOUGHT_SOUNDSfalsePlay a unique sound for each ThoughtType on append
Web Dashboard
MENTISDB_DASHBOARD_PORT9475Dashboard HTTPS port. Set to 0 to disable
MENTISDB_DASHBOARD_PINunsetOptional PIN to gate dashboard access. Unset = open (localhost only)
MENTISDB_DASHBOARD_ALLOWED_HOSTSunsetComma-separated extra hostnames/IPs accepted in the Host header (public DNS name or IP, reverse-proxy name). Since 0.11 the dashboard, REST and MCP listeners share this list, and the MCP list is read when the daemon starts. Set via environment, ./.env or <MENTISDB_DIR>/.env; not editable from the dashboard. See Host Allowlist
MENTISDB_BEARER_TOKEN_ACCESSfalseRequire bearer tokens for MCP requests; use this for remote and multi-user MCP servers
MENTISDB_MAX_BODY_BYTES67108864Largest body, in bytes, the import routes (/v1/import-markdown, /v1/skills/upload, /v1/extract-memories) accept from an authenticated caller. 64 MiB by default; must be 1048576 to 1073741824, otherwise the daemon refuses to start. Every other route takes at most 2 MiB; larger bodies get 413. A read proof that does not also send X-Mentis-Content-Sha256 is limited to 1 MiB; the CLI and pymentisdb send it
MENTISDB_MAX_INFLIGHT_BODY_BYTES4 x MENTISDB_MAX_BODY_BYTESBody bytes all import requests in flight may hold together; one peer may hold twice the cap and four bodies. Beyond it: 503 with Retry-After. A smaller value is raised to one cap. Other requests use separate fixed pools, so imports never starve them: 64 MiB for authenticated callers (32 MiB per peer) and 16 MiB for anonymous ones (8 MiB per peer)
MENTISDB_BODY_IDLE_TIMEOUT_SECS30A request body that delivers no data for this long fails with 408; small and anonymous bodies also get a total deadline of twice this, and the minimum rate below applies after a grace period of twice this. Range 1 to 3600; anything else stops the daemon at startup
MENTISDB_MIN_BODY_BYTES_PER_SEC65536Slowest rate a request body may sustain, judged in each window of one idle timeout once the grace period (twice the idle timeout) is over; each window counts only its own bytes. A slower body fails with 408. 64 KiB/s by default; 0 switches the rule off (the idle timeout and deadlines still apply). Lower it for imports over a slow link. Range 0 to 1073741824; anything else stops the daemon at startup
MENTISDB_BEARER_TOKENunsetCLI only: global token that mentisdb backup / restore send to the running daemon's /v1/admin/flush when bearer-token access is on
MENTISDB_WEBHOOK_ALLOWED_CIDRSunsetComma- or space-separated CIDRs or IPs that webhooks may target despite the private-address block (e.g. 100.64.0.0/10,fd7a:115c:a1e0::/48 for Tailscale). Unset = all internal ranges blocked; an invalid entry or one broader than /8 stops startup. Set via environment, ./.env or <MENTISDB_DIR>/.env. See Private webhook targets
Read Proofs (CLI and stdio proxy)
MENTISDB_READ_KEY_FILEunsetEd25519 key file the CLI and the stdio MCP proxy sign every request with, to read private chains (same as --read-key-file). The key never leaves the process
MENTISDB_READ_AGENT_IDunsetAgent id of that key (same as --read-agent)
MENTISDB_READ_KEY_IDunsetKey id of that key (same as --read-key-id)
Migrations
MENTISDB_MIGRATION_CONCURRENCY2How many chains the background migration manager rewrites at once
MENTISDB_MIGRATION_BACKUP_RETENTION_DAYS14How long the original of a migrated chain is kept under <MENTISDB_DIR>/migrations/backup/; 0 keeps backups forever
Daemon Self-Update
MENTISDB_UPDATE_CHECKtrueBackground GitHub release check for mentisdb. Set it to false to disable the startup-time prompt.
MENTISDB_UPDATE_REPOCloudLLM-ai/mentisdbOptional owner/repo override for the GitHub release source used by the updater.
Deduplication
MENTISDB_DEDUP_THRESHOLDunset (disabled)Jaccard threshold for auto-dedup on append (0.0–1.0). When set, MentisDB compares new thoughts against recent memories and auto-emits Supersedes so default search hides the older thought. Recommended for multi-agent / long-lived chains: 0.85. Without this (or agent-written Supersedes/Corrects/Invalidates), the invalidation set stays empty. See Invalidation & Dedup.
MENTISDB_DEDUP_SCAN_WINDOW64Number of recent thoughts to scan for dedup comparison. Only used when MENTISDB_DEDUP_THRESHOLD is set. Raise on chatty chains (e.g. 128).
Search Ranking
MENTISDB_VECTOR_FUSIONrelativeHow vector similarity blends with the lexical score: relative (decays with a hit's lexical score relative to the query's best) or absolute (the 0.10 blend). See Ranking Knobs
MENTISDB_COLLAPSE_DUPLICATES0.9Result-time collapse of near-duplicate hits: a Jaccard threshold in (0, 1], or off. Per request: collapse_duplicates (0 disables)
MENTISDB_DF_SCOPEglobalHow the lexical stop-word gate counts document frequency: global (any field) or field (per field, experimental)
Vector Index &amp; Auto-Edges
MENTISDB_EMBEDDINGSunset (auto)Embeddings mode for managed vector sidecars: off, local-text or fastembed. Unset uses FastEmbed when compiled in
FASTEMBED_CACHE_DIR<MENTISDB_DIR>/.fastembed_cacheWhere the FastEmbed ONNX model is downloaded and cached
MENTISDB_HNSW_THRESHOLD50000Minimum number of vectors before the HNSW approximate backend replaces exact cosine search
MENTISDB_HNSW_EF_CONSTRUCTION400Search width while building the HNSW graph (higher is better recall, slower build)
MENTISDB_HNSW_EF_SEARCH128Search width for HNSW queries (higher is better recall, slower search)
MENTISDB_HNSW_BACKGROUND_BUILDtrueBuild HNSW graphs on a background thread
MENTISDB_AUTO_EDGE_THRESHOLD0.85Similarity threshold for implicit semantic edges used by graph-aware ranked search
MENTISDB_AUTO_EDGE_K5Maximum implicit neighbours per thought

Environment Variables Reference

Every MentisDB environment variable, grouped by concern. Each row lists the default, a one-sentence purpose, and a concrete example with a rationale for when you'd reach for it. All variables are read once at mentisdb startup unless noted otherwise.

Storage

VariableDefaultPurposeWhy / example
MENTISDB_DIR~/.cloudllm/mentisdbRoot directory where chain files, the chain registry, the skill registry, and TLS certs live.MENTISDB_DIR=/mnt/ssd/mentisdb — point storage at a large fast disk in production.
MENTISDB_DEFAULT_CHAIN_KEY
(deprecated alias: MENTISDB_DEFAULT_KEY)
borganism-brainChain used when a request omits chain_key.MENTISDB_DEFAULT_CHAIN_KEY=team-core — make a shared team chain the implicit default.
MENTISDB_STORAGE_ADAPTERbinaryStorage format for new chains; only binary is supported for new chains.MENTISDB_STORAGE_ADAPTER=binary — set explicitly in ops manifests for future-proofing.
MENTISDB_EMBEDDINGSunset (auto)Process-wide embeddings mode: off (no vector sidecars, lexical and graph only), local-text (built-in hashing, never loads ONNX) or fastembed. Unset uses FastEmbed when compiled in, local text otherwise. Unknown values are logged and ignored.MENTISDB_EMBEDDINGS=off — small VPS or container where the ONNX model's memory is not worth it.
FASTEMBED_CACHE_DIR<MENTISDB_DIR>/.fastembed_cacheDirectory where the FastEmbed ONNX model is downloaded and cached.FASTEMBED_CACHE_DIR=/var/cache/fastembed — share one model download between hosts or keep it off the data volume.

Behaviour

VariableDefaultPurposeWhy / example
MENTISDB_AUTO_FLUSHtruetrue makes every append wait until its group commit is written to the chain file (crash-safe; add MENTISDB_FSYNC=1 for power-loss safety); false batches up to 16 records in a background writer (higher throughput, up to 15 records may be lost on hard crash).MENTISDB_AUTO_FLUSH=false — for write-heavy multi-agent hubs where throughput matters more than last-second durability.
MENTISDB_GROUP_COMMIT_MS2Window in milliseconds for the strict-mode writer to coalesce concurrent appends into one flush. A lone append with nothing else queued flushes immediately.MENTISDB_GROUP_COMMIT_MS=5 — bigger window amortises write and fsync cost under concurrent load at the price of a few ms extra p99 latency.
MENTISDB_FSYNCunset (off)When 1 / true / on / yes, fsync the chain file after every group commit. Explicit flush, clean shutdown and dropping a chain always sync regardless.MENTISDB_FSYNC=1 — when losing the last few appends to a power cut is unacceptable. Costs roughly 4x append latency (F_FULLFSYNC on macOS).
MENTISDB_DEDUP_THRESHOLDunset (disabled)Jaccard similarity threshold in [0.0, 1.0] for auto-emitting Supersedes relations on near-duplicate appends.MENTISDB_DEDUP_THRESHOLD=0.85 — recommended for production agent memory so near-duplicates get Supersedes edges and stay out of default search.
MENTISDB_DEDUP_SCAN_WINDOW64How many recent thoughts to scan when dedup is enabled.MENTISDB_DEDUP_SCAN_WINDOW=128 — widen the comparison window on chatty chains where near-duplicates arrive in bursts.
MENTISDB_VERBOSEtrueLog each MentisDB operation to the mentisdb::interaction target.MENTISDB_VERBOSE=false in production where you've attached your own observability and don't need the built-in stream.
MENTISDB_LOG_FILEunset (stdout only)Optional file path for interaction logs.MENTISDB_LOG_FILE=/var/log/mentisdb/interactions.log — persist the interaction stream for later audit or log-shipping.

Durability and crash recovery

  • An append returns once its hash-chained record is durable in the chain file. Derived state (search sidecars, overlays, registries) is updated afterwards; a failure there is logged and retried or rebuilt on the next append or open instead of failing an append that already committed.
  • If the process or machine died mid-write, opening a binary chain truncates the partial final record and saves the dropped bytes beside the chain file as <chain file>.torn-<unix-millis> (mode 0600). Only a genuine partial record is truncated: if the bytes after a bad length prefix still decode as a complete record, the corruption is mid-file, so opening fails with an InvalidData error and the chain file is left untouched.
  • MentisDB assumes one writer process per chain directory; torn-tail repair takes no cross-process lock. Never point two daemons, or a daemon and an embedded writer, at the same MENTISDB_DIR.
  • The implicit-edge overlay records how many thoughts it covers and the chain head it was built against. After a crash it replays the missing tail on open (or rebuilds when the head does not match), so no implicit edges are lost.
  • Chain, agent, webhook and other JSON registries are written to a temporary file and renamed into place, so a crash never leaves a half-written registry.

Networking / TLS

VariableDefaultPurposeWhy / example
MENTISDB_BIND_HOST127.0.0.1IP address for all server sockets.MENTISDB_BIND_HOST=0.0.0.0 — bind to all interfaces (use with care; firewall or set a dashboard PIN first).
MENTISDB_MCP_PORT9471HTTP MCP server port.MENTISDB_MCP_PORT=19471 — move off the default when running a second daemon on the same host.
MENTISDB_REST_PORT9472HTTP REST server port.MENTISDB_REST_PORT=19472 — align with the MCP port offset when running a side-by-side instance.
MENTISDB_HTTPS_MCP_PORT9473HTTPS MCP port; set to 0 to disable.MENTISDB_HTTPS_MCP_PORT=0 — turn off HTTPS MCP entirely on a fully-internal host.
MENTISDB_HTTPS_REST_PORT9474HTTPS REST port; set to 0 to disable.MENTISDB_HTTPS_REST_PORT=0 — disable HTTPS REST when terminating TLS at a reverse proxy.
MENTISDB_TLS_CERT<MENTISDB_DIR>/tls/cert.pemPEM cert path. Auto-generated on first boot if absent.MENTISDB_TLS_CERT=/etc/ssl/mentisdb/fullchain.pem — swap in a CA-signed cert instead of the default self-signed one.
MENTISDB_TLS_KEY<MENTISDB_DIR>/tls/key.pemPEM key path.MENTISDB_TLS_KEY=/etc/ssl/mentisdb/privkey.pem — pair with a CA-signed cert from a secrets mount.

Dashboard

VariableDefaultPurposeWhy / example
MENTISDB_DASHBOARD_PORT9475HTTPS-only dashboard port; set to 0 to disable entirely.MENTISDB_DASHBOARD_PORT=0 — turn the dashboard off on headless servers where only the MCP/REST APIs are needed.
MENTISDB_DASHBOARD_PINunsetShared PIN required to access the dashboard; empty string is treated as absent.MENTISDB_DASHBOARD_PIN=8472-9471 — required whenever you bind the dashboard off 127.0.0.1.
MENTISDB_BEARER_TOKEN_ACCESSfalseWhen true, MCP requests must include an active bearer token. Tokens can be global or limited to one or more chains.MENTISDB_BEARER_TOKEN_ACCESS=true — turn this on before exposing MCP to remote users.

Updates

VariableDefaultPurposeWhy / example
MENTISDB_UPDATE_CHECKtrueEnable/disable the automatic update check on daemon startup.MENTISDB_UPDATE_CHECK=false in CI — keeps test runs deterministic and offline.
MENTISDB_UPDATE_REPOCloudLLM-ai/mentisdbOverride the GitHub repo the updater polls (useful for forks).MENTISDB_UPDATE_REPO=my-org/mentisdb-fork — track an internal fork's release channel instead of upstream.

Audio

VariableDefaultPurposeWhy / example
MENTISDB_STARTUP_SOUNDunset (off)Set to 1/true to play the startup chime.MENTISDB_STARTUP_SOUND=true on a dev workstation — audible cue that the daemon is up after a restart.
MENTISDB_THOUGHT_SOUNDSunset (off)Set to 1/true to play a per-thought-type sound on each append.MENTISDB_THOUGHT_SOUNDS=true — audible feedback while pair-programming with an agent; leave off on shared machines.

Priming Your Agent

Priming an agent for MentisDB is one sentence. Just type:

use mentisdb as your memory system

That is all. The agent handles the rest automatically:

  1. Detect and select chain — calls mentisdb_list_chains to see what chains exist, then picks the one whose name best matches the current project, repository, or working folder. If no chains exist yet, it asks you to name a new one before proceeding.
  2. Bootstrap — calls mentisdb_bootstrap with the chosen chain key to create or reopen that chain, then calls mentisdb_list_agents and reuses the existing specialist that best matches the current task, followed by mentisdb_standing_context (durable preferences, constraints and decisions of any age) and mentisdb_recent_context (where things left off) to reload prior state.
  3. Load skill rules — reads mentisdb://skill/core so it knows exactly how to write thoughts, search, and manage context
  4. Self-seed — writes a Summary checkpoint so every future session recovers state automatically without needing to re-prime

First time? If no memory chains exist yet, the agent will briefly explain what a chain is and ask what to name it — usually your project or repository name works well.

Tip: Add this phrase to your tool's system-prompt or project instructions file and every new agent session will prime itself automatically — you will never need to type it again.

Additional tips

  • Give the agent a stable agent_id — this is how its memories are attributed and retrieved later
  • Tell it which chain_key to use if you run multiple chains (e.g. one per project)
  • Instruct it to load memories before starting — not after it has already made decisions
  • If your client supports MCP resources, tell the agent to read mentisdb://skill/core first; only use GET /mentisdb_skill_md as a fallback for non-MCP or limited clients
  • If you do not specify a chain up front, tell the agent to prefer a chain whose name matches the current repo or working folder
  • Ask it to write a Summary checkpoint before compacting its context or ending a long session

Self-Update

MentisDB's daemon checks GitHub for a newer release after startup by default. On an interactive terminal, the daemon finishes booting, then shows an ASCII prompt asking whether it should update itself with cargo install.

MENTISDB_UPDATE_CHECK=0 mentisdb

Version comparison uses the first three numeric components only. That means a release tag like 0.6.1.14 is treated as core version 0.6.1, and the fourth number is only the monotonically increasing release counter.

If the terminal is non-interactive, MentisDB never blocks on stdin. It prints the exact cargo install --git ... --tag ... command you can run manually instead.

Use MENTISDB_UPDATE_CHECK=0 when you want a quiet daemon with no release prompt.

HTTPS & TLS

MentisDB automatically generates a self-signed TLS certificate on first startup using rcgen. This enables encrypted connections on two dedicated HTTPS ports alongside the plain HTTP ports. No manual certificate management is required.

Port Map

PortProtocolPurpose
9471HTTPMCP server
9472HTTPREST API
9473HTTPSMCP server (TLS)
9474HTTPSREST API (TLS)
9475HTTPSWeb Dashboard

The my.mentisdb.com Hostname

my.mentisdb.com is a public DNS A-record that resolves to 127.0.0.1. The auto-generated certificate includes it as a Subject Alternative Name alongside localhost and 127.0.0.1. Once you trust the certificate on your machine, you can use https://my.mentisdb.com:9473 as a friendly, stable hostname in MCP configs — no port-forwarding or extra DNS setup required.

Since 0.11 the daemon accepts my.mentisdb.com only on its TLS listeners (HTTPS MCP 9473, HTTPS REST 9474, dashboard 9475). It is a public DNS name MentisDB does not control, so the plain HTTP ports 9471 and 9472 answer 403 to it unless you list it in MENTISDB_DASHBOARD_ALLOWED_HOSTS. Use the https:// URL, or http://localhost:9471 for plain HTTP.

Trusting the Self-Signed Certificate

The certificate is saved to ~/.cloudllm/mentisdb/tls/cert.pem on first startup. Run the appropriate command once per machine:

macOS

sudo security add-trusted-cert -d -r trustRoot \
            -k /Library/Keychains/System.keychain \
            ~/.cloudllm/mentisdb/tls/cert.pem

Linux

sudo cp ~/.cloudllm/mentisdb/tls/cert.pem \
    /usr/local/share/ca-certificates/mentisdb.crt
sudo update-ca-certificates

Windows

Double-click cert.pem → Install Certificate → Local Machine → Trusted Root Certification Authorities → Finish.

After trusting the certificate, restart your MCP client (e.g. Claude Desktop) and use https://my.mentisdb.com:9473 as the server URL.

Certificate Lifetime

A generated certificate is valid from one day before it was made to two years after. Since 0.11 the daemon checks the certificate it is about to serve at startup: an expired certificate that MentisDB generated is regenerated with the same names and a new key pair (clients must trust the new one), a certificate expiring within 30 days logs a warning naming mentisdb cert --force, and an expired certificate you supplied yourself is only warned about.

Minting a Custom Certificate

When the auto-generated SAN set is not enough — for example you are running the daemon on a VPS with a public IP, or you need the cert to be valid for a custom hostname your team uses — use the mentisdb cert subcommand to mint a fresh self-signed certificate with an extra Subject Alternative Name (SAN) of your choice. The command also writes the new paths into your local .env so the next daemon start picks the new cert up automatically.

What gets included in the SAN set

  • my.mentisdb.com (DNS) and localhost (DNS) — always present so the daemon is reachable by the friendly local hostname.
  • 127.0.0.1 and every unicast IPv6 / IPv4 address on every active host interface — the cert is valid for any IP the box exposes.
  • MENTISDB_BIND_HOST when it is a DNS name — useful for vps.example.com-style deployments.
  • Your <ip-or-domain> argument, when supplied — IP literals are added as IPAddress SANs, everything else as DnsName SANs.

Usage

# 1. Standard cert into the default location (writes to
#    ~/.cloudllm/mentisdb/tls/ and updates ./.env)
mentisdb cert

# 2. Add a public VPS IP as a SAN so the cert is valid for that IP
mentisdb cert 192.0.2.10

# 3. Add a custom DNS hostname
mentisdb cert vps.example.com

# 4. Regenerate an existing cert (e.g. after adding a new IP to the box)
mentisdb cert 192.0.2.10 --force

# 5. Reset to factory defaults: delete existing cert/key, then generate fresh
mentisdb cert --reset

# 6. Write to a non-default directory and update a custom .env file
mentisdb cert 192.0.2.10 \
    --out-dir /etc/mentisdb/tls \
    --env-file /etc/mentisdb/mentisdb.env

# 7. Print the values without touching any .env (for ephemeral hosts)
mentisdb cert --no-env-update

Options

Argument / FlagDescription
&lt;ip-or-domain&gt;Optional IP literal or DNS hostname to add as an extra SAN. IPv4 and IPv6 literals become IP SANs; anything else becomes a DNS SAN. Omit to mint a cert with only the standard SAN set.
--forceOverwrite an existing cert.pem / key.pem on disk. Without this flag the command refuses to clobber a pre-existing cert so operators do not accidentally invalidate an already-trusted one.
--resetDelete any existing cert.pem / key.pem files first, then generate a fresh factory-default certificate,
--out-dir &lt;path&gt;Directory to write cert.pem and key.pem into. Defaults to the directory of MENTISDB_TLS_CERT (or the platform default ~/.cloudllm/mentisdb/tls/).
--env-file &lt;path&gt;Path to the .env file to update with the new cert paths. Defaults to ./.env.
--no-env-updateSkip updating the .env file. The cert is still minted, the SAN list and SHA-256 fingerprint are still printed, and the command prints the export MENTISDB_TLS_CERT=... lines for you to paste into a shell rc.

When the new cert takes effect

The new cert.pem and key.pem are written immediately and MENTISDB_TLS_CERT / MENTISDB_TLS_KEY are updated on disk. The running daemon keeps using the cert it loaded at startup, so restart the daemon (Ctrl-C in the TUI or stop the background process) for the new cert to be served on the next HTTPS request. Subsequent calls to mentisdb cert without --force reuse the existing cert so the in-flight HTTPS fingerprint stays stable across restarts.

Cross-check the new cert from any machine with openssl s_client -connect &lt;host&gt;:9473 -showcerts &lt;/dev/null 2&gt;/dev/null | openssl x509 -fingerprint -sha256 -noout and compare against the SHA-256 fingerprint: line that mentisdb cert prints. If they match, the running daemon is serving the cert you just minted.

Disabling HTTPS

Set both HTTPS ports to 0 to run HTTP-only:

MENTISDB_HTTPS_MCP_PORT=0
            MENTISDB_HTTPS_REST_PORT=0

Bearer Token MCP Access

Bearer-token access protects the MCP surface when a MentisDB server runs on a remote host or serves multiple users. It is off by default for local development. Turn it on with:

MENTISDB_BIND_HOST=0.0.0.0
MENTISDB_BEARER_TOKEN_ACCESS=true
MENTISDB_DASHBOARD_PIN=change-me
mentisdb

The switch can also be toggled live from the dashboard Settings screen without restarting the daemon. Token records are stored in the MentisDB directory as hashes and metadata; raw tokens are printed once and are never persisted.

Token Scopes

ScopeCreate commandWhat it can access
globalmentisdb bearertoken create --global admin-laptopEvery chain and every server-wide operation: chain listing, webhook list/delete, skill upload/deprecate/revoke/delete, and /v1/admin/flush.
chain:<key> or chains:<key>,<key>mentisdb bearertoken create team-agent --chain alice --chain sharedOnly REST and MCP calls that operate on one of those chains. Server-wide operations require a global token.

REST and MCP share one authorization table. With a chain-scoped token:

  • GET /v1/chains / mentisdb_list_chains, GET /v1/webhooks, DELETE /v1/webhooks/{id}, skill upload/deprecate/revoke/delete and POST /v1/admin/flush are rejected (global-only).
  • Webhook registration is allowed only with a chain_key_filter inside the token's scope.
  • POST /v1/agents and the other agent-registry routes are checked against the requested chain_key; a single-chain token that omits it gets its own chain.
  • Out-of-scope calls return 401.

A token's last_used_at is tracked in memory on every request but written to disk at most once a minute, so mentisdb bearertoken list can lag by up to 60 seconds. Request bodies are limited to 2 MiB on ordinary routes, and up to MENTISDB_MAX_BODY_BYTES (64 MiB by default) on the import routes for a caller with a valid token; larger ones are rejected with 413.

Managing Tokens

mentisdb bearertoken
mentisdb bearertoken create --global admin-laptop
mentisdb bearertoken create --chain alice alice-agent
mentisdb bearertoken create bob-agent --chain bob
mentisdb bearertoken create team-agent --chain alice --chain shared
mentisdb bearertoken list
mentisdb bearertoken list --chain alice
mentisdb bearertoken list --chain alice --chain shared
mentisdb bearertoken remove alice-agent

The dashboard Settings screen exposes the same create, list, and revoke operations with an alias field, a Global/Chains selector, a multi-chain picker, and a token table. Keep global tokens for trusted administrators; issue chain tokens to users or agents that should only work in a bounded set of memory chains.

Harness Configuration Examples

Every remote harness must send the same HTTP header:

Authorization: Bearer mentisdb_replace_me

Codex

Edit ~/.codex/config.toml:

[mcp_servers.mentisdb]
url = "https://my.mentisdb.com:9473"
headers = { Authorization = "Bearer mentisdb_replace_me" }

Claude Code

claude mcp add-json mentisdb \
    '{"type":"http","url":"https://my.mentisdb.com:9473","headers":{"Authorization":"Bearer mentisdb_replace_me"}}' \
    --scope user

Qwen Code

qwen mcp add --scope user --transport http mentisdb https://my.mentisdb.com:9473 \
    --header "Authorization: Bearer mentisdb_replace_me"

Or edit ~/.qwen/settings.json:

{
  "mcpServers": {
    "mentisdb": {
      "httpUrl": "https://my.mentisdb.com:9473",
      "headers": {
        "Authorization": "Bearer mentisdb_replace_me"
      }
    }
  }
}

GitHub Copilot CLI

Edit ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "mentisdb": {
      "type": "http",
      "url": "https://my.mentisdb.com:9473",
      "headers": {
        "Authorization": "Bearer mentisdb_replace_me"
      },
      "tools": ["*"]
    }
  }
}

VS Code + Copilot

Edit .vscode/mcp.json or your user mcp.json:

{
  "servers": {
    "mentisdb": {
      "type": "http",
      "url": "https://my.mentisdb.com:9473",
      "headers": {
        "Authorization": "Bearer mentisdb_replace_me"
      }
    }
  }
}

OpenCode

Edit ~/.config/opencode/opencode.json:

{
  "mcp": {
    "mentisdb": {
      "type": "remote",
      "url": "https://my.mentisdb.com:9473",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer mentisdb_replace_me"
      }
    }
  }
}

Hermes Agent

Edit ~/.hermes/config.yaml:

mcp_servers:
  mentisdb:
    url: "https://my.mentisdb.com:9473"
    headers:
      Authorization: "Bearer mentisdb_replace_me"

Remote Setup Checklist

Most remote-connection problems are not MentisDB problems: the client is talking to the wrong address, a leftover local entry wins over the remote one, or the token never reaches the server. Work through these steps in order.

1. Test the endpoint before configuring any client

Replace the host and token with yours. The first call needs no token; the second proves the token works (it lists the MCP tools).

curl -s https://my.mentisdb.com:9473/health

curl -s -X POST https://my.mentisdb.com:9473/ \
  -H "Authorization: Bearer mentisdb_replace_me" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

If the health check fails, fix the network (host, port, firewall, MENTISDB_BIND_HOST) before touching the client. If tools/list returns 401, the token is missing, mistyped or revoked.

2. Use HTTPS, or plain HTTP only on a private network

The bearer token travels in every request. Use the HTTPS port (9473) from anywhere on the internet. Use the plain-HTTP MCP port (9471) only over a VPN, a private network or an SSH tunnel, because the token is sent in clear text. If your client rejects the daemon's self-signed certificate for a remote IP or hostname, mint one that covers it with mentisdb cert <ip-or-domain> (see the certificate guide) rather than turning off certificate checks.

# Private network / VPN: plain HTTP is acceptable
claude mcp add-json mentisdb \
    '{"type":"http","url":"http://10.0.0.5:9471","headers":{"Authorization":"Bearer mentisdb_replace_me"}}' \
    --scope user

# Anything else: HTTPS
claude mcp add-json mentisdb \
    '{"type":"http","url":"https://my.mentisdb.com:9473","headers":{"Authorization":"Bearer mentisdb_replace_me"}}' \
    --scope user

3. Keep the token out of files you commit

Put the token in your user-level client config, or reference an environment variable from shared project config. Never commit a token to a repository.

Claude Code project file .mcp.json (variables are expanded when the server starts):

{
  "mcpServers": {
    "mentisdb": {
      "type": "http",
      "url": "https://my.mentisdb.com:9473",
      "headers": {
        "Authorization": "Bearer ${MENTISDB_TOKEN}"
      }
    }
  }
}

Codex ~/.codex/config.toml (reads the token from the environment):

[mcp_servers.mentisdb]
url = "https://my.mentisdb.com:9473"
bearer_token_env_var = "MENTISDB_TOKEN"

VS Code mcp.json (prompts once and stores the token securely):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "mentisdb-token",
      "description": "MentisDB bearer token",
      "password": true
    }
  ],
  "servers": {
    "mentisdb": {
      "type": "http",
      "url": "https://my.mentisdb.com:9473",
      "headers": {
        "Authorization": "Bearer ${input:mentisdb-token}"
      }
    }
  }
}

4. Make sure the remote entry is the one in use

Clients merge MCP entries from several scopes, and the narrower scope wins. In Claude Code a local (per-project) or project mentisdb entry overrides your user-level one, so an old entry pointing at http://127.0.0.1:9471 keeps that project on localhost (connection refused) even after you configured the remote server. Check which entry is active and remove the stale one:

claude mcp get mentisdb               # scope, URL and status actually in use
claude mcp list
claude mcp remove mentisdb -s local    # or -s project for a .mcp.json entry

A session that was already running keeps its old connection: reconnect it with /mcp (or restart the client). New sessions pick up the change automatically.

If the log shows SSE stream disconnected: TimeoutError over and over, the daemon is older than 0.12.2: the MCP event stream sent no bytes while idle. Upgrade and restart the daemon; it then sends a : keepalive comment every 15 seconds.

5. Read the error

SymptomUsual causeFix
Connection refused / timeoutWrong host or port, a firewall, or a local entry still pointing at localhostStep 1, then step 4
HTTP 401 UnauthorizedHeader missing, misspelled, without the Bearer prefix, or the token was revokedCheck the header; run mentisdb bearertoken list on the server
HTTP 403 from a browserA browser request from a host or Origin the daemon does not serveUse bearer tokens, or list the host in MENTISDB_DASHBOARD_ALLOWED_HOSTS
Certificate / TLS errorThe self-signed certificate does not cover the IP or hostname you usementisdb cert <ip-or-domain> on the server
Tools work on one chain but fail on anotherThe token is chain-scopedIssue a token that includes that chain (--chain)

The token registry already tracks creation, revocation, and last successful use. Later versions can extend those records with per-token request counters or chain-level usage stats without changing the client authentication model.

Web Dashboard

The web dashboard is a self-contained single-page application embedded directly in the MentisDB binary — no npm, no separate process, no installation required. Open it in any browser at:

https://127.0.0.1:9475/dashboard

The version number is displayed in the nav header. The dashboard connects to the same daemon you already have running, and it keeps showing newly appended thoughts while the daemon stays up — no restart is required to see fresh chain counts or an agent's latest thoughts.

Security note: The dashboard is a read/write admin interface. Protect it with a PIN (MENTISDB_DASHBOARD_PIN) or keep MENTISDB_BIND_HOST=127.0.0.1 (the default) so it is never exposed to the network.

PIN Protection

Set MENTISDB_DASHBOARD_PIN to any string. A login page appears automatically. Leave it unset for open (localhost-only) access.

MENTISDB_DASHBOARD_PIN=my-secret-pin mentisdb

PIN verification uses constant-time comparison (subtle::ConstantTimeEq) to prevent timing attacks — the server does not leak information about how many characters matched.

The Settings API never returns the PIN: GET /dashboard/api/settings reports only whether one is set. Saving settings with the PIN field left blank keeps the current PIN.

Login Rate Limiting

The /dashboard/login endpoint enforces rate limiting: 5 failed PIN attempts from one client within a 5-minute window results in HTTP 429 Too Many Requests with Retry-After. Successful attempts reset the counter. A client is an IPv4 address or an IPv6 /64, and the table holds at most 4,096 clients. On top of that, more than 50 failures from all clients together in 5 minutes lock every PIN attempt for 60 seconds, doubling per repeat up to an hour and forgiven after two quiet hours (a signed-in session is unaffected). Use a long random PIN (12 or more characters) on any dashboard reachable beyond localhost. X-Forwarded-For is ignored, so behind a reverse proxy all clients share the proxy's address and one limit. Since 0.11 the PIN sent as Authorization: Bearer <pin> on any dashboard route (as the CLI does) shares the same limiter, so the PIN cannot be guessed without limit through the API either.

The login POST is under the same CSRF check as the dashboard API. The first signal present decides: an Origin whose host matches the request (Origin: null counts as absent), else Sec-Fetch-Site: same-origin (set by browsers, not by pages), else a same-host Referer. Scripts that send none of these add X-MentisDB-Dashboard: 1. 0.11 fixes real browsers being refused with "cross-origin request rejected" at login.

Security Headers

Since 0.11 dashboard responses carry a Content-Security-Policy (frame-ancestors 'none', base-uri 'none', same-origin connections), X-Content-Type-Options: nosniff, X-Frame-Options: DENY and Referrer-Policy: same-origin. This stops other sites from framing the dashboard and adds a second layer against script injection through stored text. Chains that have private segments are shown only behind a PIN, and access administration (see Public & Private Chains) is PIN-only.

Host Allowlist

To block DNS-rebinding attacks, every dashboard route (pages, API and login, GET included) returns 403 unless the request's Host header names this daemon. Since 0.11 the REST and MCP listeners use the same list. Accepted hosts:

  • localhost, 127.0.0.1, [::1], and my.mentisdb.com on TLS listeners only
  • the configured MENTISDB_BIND_HOST; when it is 0.0.0.0 or ::, the machine's own interface IPs
  • every entry of MENTISDB_DASHBOARD_ALLOWED_HOSTS (comma-separated), set in the environment or .env; it is deliberately not editable from the Settings tab
MENTISDB_DASHBOARD_ALLOWED_HOSTS=mentis.example.com,10.0.0.5 mentisdb

A reverse proxy in front of the dashboard must preserve the original Host header (or forward a name you list in MENTISDB_DASHBOARD_ALLOWED_HOSTS).

How the MCP and REST listeners apply the list (0.11):

  • MCP on a loopback bind (the default) refuses any other Host with 403 Forbidden host, for every client, on POST /, the GET / event stream and the legacy /tools/* and /resources/* routes. If you reach a VPS by its public IP or domain through a reverse proxy, add that name to MENTISDB_DASHBOARD_ALLOWED_HOSTS before the daemon starts; the MCP list is built at startup.
  • MCP on a wildcard bind (0.0.0.0 or ::, as in Docker or on a LAN) does no Host check for programmatic clients, which reach the daemon by service name or DHCP address.
  • REST on a loopback bind (the default) checks Host on every request, like MCP: curl, the CLI, agents and browsers alike get 403 unless the name is in the list (a request with no Host passes). An nginx or Caddy in front of a loopback daemon forwards the public name as Host by default: list that name, or have the proxy send Host: 127.0.0.1:9472.
  • REST on a wildcard bind, and MCP with bearer tokens off, refuse a request from a browser (one that carries Origin or Sec-Fetch-Site) unless its Host and Origin host are in the list. curl, the CLI and agents send neither header and are unaffected.
  • IPv6 entries match in canonical form (2001:db8::7, not 2001:0db8::7).

Disabling the Dashboard

MENTISDB_DASHBOARD_PORT=0 mentisdb

Sections

Chain Manager

Lists all chains with live thought counts and agent counts. Click a chain to open its Thought Explorer. You can bootstrap a new chain or delete an existing one (a type-to-confirm safety gate prevents accidental deletion). Click ↺ Refresh to reload live counts.

Thought Explorer

Paginated table of all thoughts in a chain. Filter by any of the 31 ThoughtTypes using the grouped filter panel — each type is shown with a coloured badge. The explorer also supports chain-scoped text search plus a live agent dropdown; when text search is active it returns hybrid ranked results and grouped context bundles instead of a plain substring list. If a managed vector sidecar is enabled for the chain, the ranking transparently blends lexical, graph, and semantic vector signals. Click any row to open a detail modal showing the full thought content, metadata, positional back-references (displayed as #N), and typed relations (displayed as kind → target_id (chain: other-chain) for cross-chain edges), plus ranked-search provenance such as score breakdowns, matched terms, graph distance, and bundle support preview when the row came from search.

Vector Sidecars

Each chain page also has a Vector Sidecars panel for the daemon's managed embedding indexes. By default `mentisdb` keeps a local `local-text-v1` sidecar in sync for each chain it opens. Operators can expand the panel to inspect freshness, indexed-thought counts, and the sidecar path; disable or re-enable append-time sync; run Sync now; or Rebuild from scratch after an explicit delete-and-recreate confirmation.

Agent Manager

All registered agents grouped by chain. Click an agent to open its detail page where you can edit its display name, description, and owner; revoke or re-activate it; add or revoke Ed25519 signing keys; browse its most recent thoughts; or copy that agent's memories into another chain while preserving its metadata.

Skills Registry

The Skills page summary bar shows total, active, revoked, and deprecated counts. Browse skills with their version count and lifecycle status. Click a skill to view it with three tabs: Rendered (formatted Markdown), Source (raw text), and Diff (side-by-side version comparison). Deprecate or revoke a skill with a confirmation step. After revoke, Delete on the list row or Delete Permanently… on the detail pane (type the skill id to confirm) removes the skill and every version so the same skill_id can be uploaded again.

Dashboard API

The dashboard UI communicates with the daemon through a set of internal browser APIs under /dashboard/api/. These endpoints are not intended for external scripting — they are an implementation detail of the single-page dashboard. All endpoints require PIN authentication when MENTISDB_DASHBOARD_PIN is set.

  • CSRF protection. POST, PATCH and DELETE calls must carry an Origin (or, without it, Referer) header whose host matches the request host. Clients that send neither header, such as curl or scripts, must add X-MentisDB-Dashboard: 1. Anything else is rejected with 403.
  • Chain keys. Chains created from the dashboard (bootstrap, branch target, copy-to target) must use only letters, digits, _ and -, at most 128 characters; otherwise 400.
  • Paging. per_page is clamped to at most 500 and page to at most 1000.
  • Every setting is listed. The Settings screen shows every variable the daemon reads (since 0.12.2). A setting the daemon reads only at startup, such as MENTISDB_VERBOSE or the update check, is labelled restart required; saving it writes the .env file but changes nothing until the daemon restarts.
  • Settings file. Settings saved from the dashboard go to <MENTISDB_DIR>/.env, written with mode 0600 because it can hold the PIN. The daemon loads it at startup after any ./.env in its working directory; neither file overrides a variable already set in the shell.
  • Errors. 500 responses say only internal server error; details go to the daemon log.

Chains

MethodPathDescription
GET/chainsList all chains with live thought and agent counts
POST/chainsBootstrap a new chain; appends a Summary checkpoint if empty
GET/chains/{chain_key}Chain detail including vector sidecar statuses
DELETE/chains/{chain_key}Permanently delete a chain and deregister it
POST/chains/mergeMerge all thoughts from source into target chain, then delete source
POST/chains/{chain_key}/import-markdownImport a MEMORY.md-formatted document as new thoughts

Vector Sidecars

MethodPathDescription
POST/chains/{chain_key}/vectors/{provider_key}/enableEnable append-time sync for a managed vector sidecar
POST/chains/{chain_key}/vectors/{provider_key}/disableDisable append-time sync for a managed vector sidecar
POST/chains/{chain_key}/vectors/{provider_key}/syncRun an immediate sync pass for a managed vector sidecar
POST/chains/{chain_key}/vectors/{provider_key}/rebuildRebuild a vector sidecar from scratch (requires confirm_delete)

Thoughts & Search

MethodPathDescription
GET/chains/{chain_key}/thoughtsPaginated thought listing, filterable by ThoughtType and scope
GET/chains/{chain_key}/searchRanked hybrid search with context bundles when text is provided. Supports as_of for point-in-time queries and scope for scope-filtered results
GET/chains/{chain_key}/search/bundlesSeed-anchored context bundles for a search query. Supports as_of and scope parameters
GET/chains/{chain_key}/search/agentsLive thought authors merged with registry display names
GET/thoughts/{chain_key}/{thought_id}Retrieve a single thought by UUID
GET/chains/{chain_key}/agents/{agent_id}/thoughtsPaginated thoughts authored by a specific agent

Agents

MethodPathDescription
GET/agentsAll registered agents across all chains, grouped by chain
POST/agentsCreate or update an agent registry entry
GET/agents/{chain_key}All agents registered on a specific chain
GET/agents/{chain_key}/{agent_id}Single agent detail with live thought count
PATCH/agents/{chain_key}/{agent_id}Update display name, description, or owner of an agent
POST/agents/{chain_key}/{agent_id}/revokeMark an agent as revoked
POST/agents/{chain_key}/{agent_id}/activateMark an agent as active
POST/agents/{chain_key}/{agent_id}/keysRegister a new Ed25519 public verification key on an agent
DELETE/agents/{chain_key}/{agent_id}/keys/{key_id}Revoke a public key from an agent
GET/agents/{chain_key}/{agent_id}/memory-markdownExport an agent's thoughts as a MEMORY.md Markdown document
POST/agents/{chain_key}/{agent_id}/copy-to/{target_chain_key}Copy all of an agent's thoughts to another chain

Skills

MethodPathDescription
GET/skillsList all registered skills with version count and status
POST/skillsUpload a new skill version (Markdown or JSON)
GET/skills/{skill_id}Get skill summary and latest content
GET/skills/{skill_id}/versionsFull version history for a skill
GET/skills/{skill_id}/diffUnified diff between two skill versions
POST/skills/{skill_id}/revokeMark a skill as revoked (content preserved for audit)
POST/skills/{skill_id}/deprecateMark a skill as deprecated
DELETE/skills/{skill_id}Permanently delete a skill and all versions (same skill_id can be re-uploaded)

Version

MethodPathDescription
GET/versionReturns the crate version baked in at compile time
Note: All paths are relative to /dashboard/api. When a PIN is set, every endpoint requires either an Authorization: Bearer &lt;pin&gt; header or a valid mentisdb_pin cookie. Without a PIN the dashboard is open on localhost.

Import MEMORY.md

The chain detail page in the dashboard has a 📥 Import MEMORY.md button. Use it to bulk-import an existing Markdown memory file into the chain — no CLI or API calls required.

How to use it

  1. Open the dashboard at https://127.0.0.1:9475/dashboard and click into a chain.
  2. Click 📥 Import MEMORY.md — a modal appears.
  3. Paste your Markdown content into the text area.
  4. Enter a Default Agent ID — all imported thoughts are attributed to this agent. The agent must already be registered in the chain.
  5. Click Import — the dashboard reports how many thoughts were created.

Expected format

Any Markdown file where each top-level or second-level heading introduces a distinct memory. The mentisdb_memory_markdown MCP tool produces this format automatically, as does any MentisDB export. Example:

## LessonLearned — 2025-01-10
Use `signal()` not `create_signal()` in Leptos 0.7.
All `create_*` APIs were removed in the 0.7 redesign.

## Decision — 2025-01-11
Adopted binary storage adapter for production.
Rationale: binary is the only supported format for new chains.

After import the memories are fully indexed — searchable, filterable by ThoughtType, and attributable by agent — exactly like any thought appended via MCP or API.

Migrating from a MEMORY.md workflow: If you previously kept project memory in a hand-edited MEMORY.md file, use this button once to seed your chain. From that point forward let MentisDB be the source of truth — the agent writes directly to the chain, and you export with mentisdb_memory_markdown whenever you need a portable snapshot.

Backup & Restore

MentisDB stores all chain data on disk under ~/.cloudllm/mentisdb/. Back up that directory at any time using the built-in mentisdb backup command, and restore from a backup with mentisdb restore.

Archive format

Backups are standard ZIP archives with a .mentis extension. Each archive contains a SHA-256 manifest (MENTISDB_MANIFEST.txt) listing every file path and its digest, so integrity can be verified after download or copy.

mentisdb backup

mentisdb backup [-o &lt;path&gt;] [--dir &lt;path&gt;] [--flush] [--include-tls]
ArgumentDescription
source_dirPath to the MentisDB data directory to back up (e.g. ~/.cloudllm/mentisdb)
output_pathOptional output path for the .mentis archive. Defaults to ~/.cloudllm/mentisdb/backup-&lt;timestamp&gt;.mentis.

Options

FlagDescription
--flushDetects if mentisdb is running on the local machine. If so, calls POST /v1/admin/flush to force a durability flush before archiving. The backup then proceeds with the daemon either stopped or freshly flushed. Use this to ensure the archive captures all committed thoughts. With MENTISDB_BEARER_TOKEN_ACCESS=true the flush endpoint requires a global token: set MENTISDB_BEARER_TOKEN to one and the CLI sends it as Authorization: Bearer <token> (e.g. MENTISDB_BEARER_TOKEN=mentisdb_global_token mentisdb backup). Without it the flush is rejected and the backup warns and archives the files as they are on disk. mentisdb restore uses the same token for its running-daemon probe; any HTTP answer, including 401, counts as running and aborts the restore.
--include-tlsInclude TLS certificate and private key files in the archive. By default these are excluded (they are machine-specific and should be re-generated on the target machine). This flag is opt-in so you consciously choose to include them.

mentisdb restore

mentisdb restore &lt;archive.mentis&gt; [--dir &lt;path&gt;] [--overwrite] [--yes]
ArgumentDescription
archive_pathPath to the .mentis archive to restore.
target_dirDirectory to extract the archive into.

Options

FlagDescription
--overwriteAllow same-path chain files to be replaced when a safe suffix merge is not possible. The local registry is still preserved and merged.
--yesSkip interactive confirmation prompts while keeping the default preserve-and-merge behavior.

Interactive restore behavior

When restoring into an empty directory, MentisDB imports the full instance. When restoring into an existing instance, MentisDB preserves the local registry, uses the backup registry as a hint, adds new chains, appends verified same-key suffixes, ignores older backup chains, and imports same-name chains with different genesis under a non-conflicting -imported chain key.

Restore safety limits

  • Archives that declare any entry larger than 64 GiB, or more than 256 GiB in total, are rejected before extraction.
  • The manifest may be at most 8 MiB and list at most 100,000 files.
  • Every size the manifest declares must equal the entry's uncompressed size in the ZIP; a mismatch rejects the archive.
  • On Unix, free disk space on the target filesystem is checked against the manifest's total size before anything is extracted.
  • Restore refuses to write through a symlink anywhere under the target directory.
  • Files are staged in a .mentisdb-restore-<uuid> directory created beside the target (same filesystem) and moved into place from there.

Example commands

# Create a backup (archive written to ./mentisdb-2026-04-28-153022.mentis)
mentisdb backup

# Create a backup to a specific path
mentisdb backup -o /tmp/my-mentisdb-backup.mentis

# Create a backup from a specific source directory
mentisdb backup --dir ~/.cloudllm/mentisdb -o /tmp/backup.mentis

# Create a backup with a running daemon flush first
mentisdb backup --flush

# Include TLS material in the backup (machine-specific — restore on same machine)
mentisdb backup --include-tls

# Restore a backup (daemon must be stopped)
mentisdb restore /tmp/my-mentisdb-backup.mentis

# Restore to a specific directory
mentisdb restore /tmp/my-mentisdb-backup.mentis --dir ~/.cloudllm/mentisdb

# Restore, allowing same-path chain overwrite when safe merge is impossible
mentisdb restore /tmp/my-mentisdb-backup.mentis --overwrite

Security note on --include-tls

TLS certificates and private keys are machine-specific. Including them in a backup is only appropriate when restoring to the same physical machine. If you restore to a new machine, omit --include-tls and let MentisDB auto-generate a fresh certificate on first start — then re-trust it on that machine.

Back up before destructive operations. Run mentisdb backup before any chain merge, chain deletion, skill revocation, or daemon self-update that involves storage format changes. Backups take only seconds and let you recover exactly where you were if something goes wrong.

Chain Migrations

A release may need to rewrite chain files (a newer thought layout, a better hash algorithm, JSONL to binary). Since 0.11 the daemon does that in the background: it starts in about a second, keeps serving every other chain, says what it is doing, and can always go back. Measured: a 600,000-thought legacy chain finished migrating 17 seconds after a start that took under a second.

What you will see

  • Chains that need work are queued and migrated by a small worker pool (MENTISDB_MIGRATION_CONCURRENCY, default 2).
  • A request for a chain that is still migrating gets HTTP 503 with a Retry-After header and {"retry_after_secs": 5, "migration": {"state": "migrating", "percent": 42, ...}}; MCP clients get the same text as a tool error. Retry after the delay. A chain that is not migrating is never delayed.
  • Progress is logged, shown in the TUI and on a dashboard banner, and reported by mentisdb migrate status, GET /v1/migrations and the mentisdb_migration_status MCP tool (global token).

Why it is safe

  • Backup first. The original chain file is hard-linked (or copied) to <MENTISDB_DIR>/migrations/backup/<chain>/ before anything is replaced, and kept MENTISDB_MIGRATION_BACKUP_RETENTION_DAYS days (default 14, 0 keeps it forever).
  • Journaled and resumable. Each chain moves through planned, backed up, staged, committed and finalized. The upgraded chain is streamed to a staging file, verified end to end, then swapped in with one atomic rename. A kill at any step is resumed or discarded on the next start; a chain interrupted three times is quarantined instead of crash-looping.
  • Never launders corruption. A stored hash that does not verify (corruption or tampering), or a migration that would invalidate a signature, refuses the migration and leaves the chain byte-for-byte untouched. A failing chain is reported and answers with a 503 naming the fix; the other chains and the daemon carry on.
  • Downgrades are refused. A chain or data directory written by a newer release is not opened by an older one that has this check; it says so and exits.
  • Derived data (vector sidecars, HNSW graphs, the implicit-edge overlay, lexical indexes) is rebuilt lazily in the background when a chain's hashes change.

Operator commands

mentisdb migrate status                 # what needs, is in, or finished a migration
mentisdb migrate run --dry-run          # rehearse: check hashes and signatures, write nothing
mentisdb migrate run [--chain KEY]      # migrate now (resumes interrupted runs)
mentisdb migrate verify                 # re-check every hash link of the live chains
mentisdb migrate retry --chain KEY      # clear a quarantine; migrated on the next run
mentisdb migrate skip --chain KEY       # leave a chain alone and unavailable until retried
mentisdb migrate rollback --chain KEY   # restore the backup (stop the daemon first)
mentisdb migrate purge-backups          # delete preserved originals of finished migrations

mentisdb migrate status --url http://127.0.0.1:9472 asks a running daemon. rollback refuses once new thoughts were appended to the migrated chain unless you pass --force, which discards them. Over REST, POST /v1/migrations/retry and POST /v1/migrations/skip take a chain_key (global token).

One daemon per data directory

Two processes appending to the same hash chain corrupt it, so the daemon holds an operating-system lock on <data dir>/mentisdb.lock for its whole life. The OS releases it when the process exits or is killed, so a crash leaves nothing to clean up.

ProcessWhile another process holds the directory
A second daemonRefuses to start; the message names the holder's pid and the directory
--offline operator commands, restoreRefuse before touching any file
migrate run, retry, skip, rollback, purge-backupsRefuse; the daemon runs its own migrations
migrate status, migrate verify, migrate run --dry-runRead-only, always allowed

The lock is advisory and network filesystems may not honour it, so keep the data directory on a local disk.

Connecting AI Tools

Once the daemon is running, connect your AI tools via MCP. The fastest path is to let MentisDB detect what is installed and configure it automatically. Alternatively, configure any tool manually.

Automated Setup (Recommended)

MentisDB ships with two built-in commands that detect which clients are installed on your machine and write the correct MCP configuration for you.

Setup Wizard

Interactive. Scans your machine, shows every detected tool, lets you choose which to configure, and applies changes with your confirmation.

mentisdb wizard

Accept all defaults and skip already-configured integrations (non-interactive):

mentisdb wizard --yes

Point all selected integrations at a custom MCP URL:

mentisdb wizard --url https://my.mentisdb.com:9473

Setup One Agent

Target a specific integration by name. Prints a plan first, then writes the config file. Use --dry-run to preview without touching anything.

mentisdb setup claude-code

Setup all detected agents at once:

mentisdb setup all

Preview what would be written without writing anything:

mentisdb setup all --dry-run

Use a custom MCP URL:

mentisdb setup all --url https://my.mentisdb.com:9473

Supported integrations

Use any of these names with mentisdb setup:

NameToolConfig location
claude-codeClaude Code CLI~/.claude.json
claude-desktopClaude for Desktop~/Library/Application Support/Claude/claude_desktop_config.json
codexOpenAI Codex CLI~/.codex/config.toml
copilotGitHub Copilot CLI~/.copilot/mcp-config.json
geminiGoogle Gemini CLI~/.gemini/settings.json
opencodeOpenCode~/.config/opencode/opencode.json
qwenQwen Code Assistant~/.qwen/settings.json
vscode-copilotVS Code + Copilot~/Library/Application Support/Code/User/mcp.json (macOS) · ~/.config/Code/User/mcp.json (Linux) · %APPDATA%\Code\User\mcp.json (Windows)

How it works

Both commands use PathEnvironment to resolve paths consistently — honouring HOME, XDG_CONFIG_HOME, USERPROFILE, and APPDATA on their respective platforms. They detect whether an integration is already configured, is installed but unconfigured, or is not present, and adapt their output accordingly. They never overwrite an existing MentisDB entry without explicit confirmation.

Manual MCP Configuration

If you prefer to configure manually, or need a custom URL, copy the relevant snippet below. All tools connect to http://127.0.0.1:9471 by default (HTTP, localhost). After trusting the self-signed TLS certificate you can use https://my.mentisdb.com:9473 instead.

Claude for Desktop

Claude for Desktop supports two connection modes. Stdio mode (recommended) requires no daemon, no Node.js, and no mcp-remote — just point Claude Desktop at the mentisdb binary. The stdio process automatically detects a running daemon and proxies to it, or launches one in the background if none is found.

Option 1: Stdio mode (recommended)

Edit your claude_desktop_config.json and add:

{
  "mcpServers": {
    "mentisdb": {
      "command": "mentisdb",
      "args": ["--mode", "stdio"]
    }
  }
}

That's it. No daemon pre-start, no TLS config, no Node.js dependency. The stdio process handles everything.

Option 2: HTTP via mcp-remote

If you prefer the HTTP transport (e.g. for a remote daemon), use the mcp-remote bridge. This requires Node.js >= 20.

Install mcp-remote globally:

npm install -g mcp-remote

Config file location by OS:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
macOS (mcp-remote)
{
  "mcpServers": {
    "mentisdb": {
      "command": "/opt/homebrew/bin/mcp-remote",
      "args": ["https://my.mentisdb.com:9473"],
      "env": { "NODE_TLS_REJECT_UNAUTHORIZED": "0" }
    }
  }
}
The NODE_TLS_REJECT_UNAUTHORIZED: "0" env var is required because MentisDB uses a self-signed TLS certificate. Node.js rejects self-signed certs by default; this env var disables that check for the mcp-remote process only. Alternatively, add the MentisDB cert to your system keychain (see the HTTPS & TLS section above) and remove the env block.

If you installed Node.js via nvm or a non-Homebrew path, find the mcp-remote binary with:

which mcp-remote

and use that full path as the command value.

Windows (mcp-remote)
{
  "mcpServers": {
    "mentisdb": {
      "command": "mcp-remote",
      "args": ["https://my.mentisdb.com:9473"],
      "env": { "NODE_TLS_REJECT_UNAUTHORIZED": "0" }
    }
  }
}

On Windows, npm install -g mcp-remote places the binary on your PATH automatically. If Claude Desktop cannot find it, supply the full path, e.g.:

"command": "C:\\Users\\YourName\\AppData\\Roaming\\npm\\mcp-remote.cmd"
Linux (mcp-remote)
{
  "mcpServers": {
    "mentisdb": {
      "command": "/usr/local/bin/mcp-remote",
      "args": ["https://my.mentisdb.com:9473"],
      "env": { "NODE_TLS_REJECT_UNAUTHORIZED": "0" }
    }
  }
}

Verify the path with which mcp-remote and substitute it if different.

Restart Claude for Desktop after saving the config file for changes to take effect.

Claude Code

`mentisdb setup claude-code` writes the MCP entry under mcpServers.mentisdb in ~/.claude.json (or the platform-equivalent home directory on Windows). The older ~/.claude/mcp/mentisdb.json file is treated as a legacy companion path, not the canonical target.

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:

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

Or using HTTPS after trusting the certificate:

{
  "mcpServers": {
    "mentisdb": {
      "type": "http",
      "url": "https://my.mentisdb.com:9473",
      "headers": {},
      "tools": ["*"]
    }
  }
}

Qwen Code

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

OpenCode

OpenCode stores MCP configuration in ~/.config/opencode/opencode.json on Linux and macOS. Add the mentisdb block under the top-level mcp key:

{
  "mcp": {
    "mentisdb": {
      "type": "remote",
      "url": "http://127.0.0.1:9471",
      "enabled": true
    }
  }
}

Or using HTTPS after trusting the certificate:

{
  "mcp": {
    "mentisdb": {
      "type": "remote",
      "url": "https://my.mentisdb.com:9473",
      "enabled": true
    }
  }
}

Google Gemini CLI

Gemini CLI reads MCP server configuration from ~/.gemini/settings.json. Add the mentisdb block under the top-level mcpServers key. The httpUrl field is required alongside url for HTTP transport:

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

VS Code + Copilot

VS Code stores MCP server configuration in mcp.json inside the VS Code user settings directory. The path varies by OS:

  • macOS: ~/Library/Application Support/Code/User/mcp.json
  • Linux: ~/.config/Code/User/mcp.json
  • Windows: %APPDATA%\Code\User\mcp.json

Add the mentisdb block under the top-level servers key:

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

Chain Topologies

MentisDB supports multiple named chains. Each chain is an independent, append-only ledger. You choose how to map agents to chains based on your team structure and privacy needs.

One agent, one chain (simplest)

A single agent uses the default chain for everything. All memories accumulate in one place. Perfect for a solo developer with one long-running assistant.

chain_key: "default" — one brain, one history.

One agent, multiple chains (context isolation)

The same agent writes to different chains depending on its current assignment. Work memories stay scoped to the right project and don't pollute unrelated contexts.

Orion writes project lessons to "project-alpha" and company-wide conventions to "company-conventions".

  • Each chain has its own agent registry, thought ledger, and skill registry
  • An agent can read from and write to as many chains as needed
  • Set MENTISDB_DEFAULT_CHAIN_KEY so the most-used chain requires no explicit chain_key parameter

Many agents, one shared chain (fleet / organisation)

All agents write to the same chain. Every agent can optionally read thoughts written by its peers by filtering on agent_ids in search queries. This is the foundation of fleet coordination.

Apollo, Orion, and Astro all write to "project-alpha". Each uses its own agent_id. A query without an agent filter returns memories from all three.

Many agents, many chains (per-team or per-tenant)

Use separate chains for separate teams, departments, or clients. Agents that work across teams carry context between chains by reading from one and writing a Summary to another. No data leaks between chains unless you explicitly bridge them.

Fleet Coordination via the Thought Chain

When your harness can spawn background sub-agents in parallel, MentisDB's shared chain becomes a coordination primitive — a lightweight alternative to explicit message passing between agents.

Prefer a walkthrough first? This tutorial shows the fleet coordination flow end to end.

The pattern

  1. The PM agent decomposes the assignment into a task graph, writes each task as a Plan or Subgoal thought tagged "task-pending", then spawns a specialist sub-agent per task.
  2. Each specialist agent calls mentisdb_recent_context on start to load the task graph and any shared constraints, then works autonomously.
  3. When a specialist finishes, it writes a TaskComplete thought tagged "task-done" (and any LessonLearned or Decision thoughts it accumulated).
  4. The PM agent polls the chain (or is notified) and queries tags_any: ["task-done"] to check completion status before unblocking dependent tasks.
No message broker needed. The append-only chain is the bus. Every agent reads the same ledger; writes are immediately visible to all readers.

Avoiding conflicts in parallel agents

  • Each agent uses its own agent_id — writes are attributed and never collide
  • Agents doing independent work read only their own subtree (agent_ids: ["my-id"]) and shared constraints (tags_any: ["constraint", "convention"]) — they don't need to read each other's full history
  • Dependent tasks read their blocker's TaskComplete thought to extract outputs before starting
  • The PM synthesises results by querying all TaskComplete thoughts in one call at the end

Example task graph

PM writes:
Plan  [tag: task-pending, id: design-schema]   → dispatches Orion
Plan  [tag: task-pending, id: write-tests]     → dispatches Apollo (blocks on design-schema)
Plan  [tag: task-pending, id: implement-api]   → dispatches Astro  (blocks on design-schema)

Orion finishes, writes:
TaskComplete [tag: task-done, id: design-schema, content: "...schema decisions..."]

PM queries tags_any=["task-done"] → unblocks Apollo + Astro
Apollo + Astro run in parallel, each reading Orion's TaskComplete for shared context.

PM final query: all TaskComplete thoughts → synthesises result.

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.

The frontmatter at the top of the file is standard YAML (since 0.12.2). description may be a folded (>) or literal (|) block spanning several lines, and triggers, tags and warnings may be block lists of - item lines or inline [a, b] lists. This is what skills written for Claude Code, OpenCode and similar harnesses already use. A one-line value that merely starts with | or >, such as | separates columns, is kept as written.

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 until you permanently delete the skill.

Deprecate, revoke, delete

mentisdb_deprecate_skill marks a skill as superseded but still readable. mentisdb_revoke_skill keeps every version for audit; agents should refuse to execute it. mentisdb_delete_skill is the explicit exception: it removes the skill and all versions from mentisdb-skills.bin so the same skill_id can be uploaded again as Active. REST POST /v1/skills/delete and the dashboard DELETE /dashboard/api/skills/{id} call the same crate API. Prefer revoke when you need a forensic trail.

Upgrading past 0.10.6

0.10.6 inserted SkillVersion.schema_version in the middle of the bincode record. Existing mentisdb-skills.bin files from 0.10.5 then failed to deserialize and the daemon panicked on boot. 0.10.7 decodes that older V2 layout and rewrites the file on open. Do not delete the skill registry. Upgrade with cargo install mentisdb --locked --force and restart the daemon.

Upgrading to 0.12.2

No data migration. Upgrade with cargo install mentisdb --locked --force and restart the daemon. Changes to check:

  • The MCP event stream stays alive. The stream a client opens with GET / on the MCP port used to send nothing until a tool call was broadcast, so clients with an idle timeout, Claude Code among them, dropped it and reconnected over and over (the log filled with SSE stream disconnected: TimeoutError). The daemon now sends an SSE comment line (: keepalive) after 15 seconds with nothing else to send; clients ignore comment lines. Restart the daemon to get it, then reconnect the client.
  • Oversized thoughts are refused. A single thought record (content, tags, concepts and the other fields together) over 10 MiB is now rejected with a 400 before anything is written. Before, such an append was written and the chain then failed to open. Ordinary REST and MCP requests are capped at 2 MiB, so you only meet this through the import routes or the library. If a chain already refuses to open with binary thought payload length ... exceeds maximum 10485760, an oversized thought written by an older version is the cause.
  • source_episode is stored and filterable. Appends accepted the field and dropped it; thoughts now keep it. Search, ranked search, federated search and context bundles take it as an exact-match filter. See source_episode.
  • CLI --source-episode. On thought append, search, search filter, search federated and search bundles.
  • The dashboard Settings screen lists every setting. 18 daemon variables were missing from it, and the HTTPS ports were shown but refused on save. Settings that the daemon reads only at startup now say restart required, including MENTISDB_VERBOSE, MENTISDB_UPDATE_CHECK, MENTISDB_UPDATE_REPO, MENTISDB_STARTUP_SOUND and MENTISDB_THOUGHT_SOUNDS, which were labelled hot-reload.
  • Skills written for agent harnesses import correctly. Markdown skill import now reads standard YAML frontmatter: a folded (>) or literal (|) description and block lists for triggers, tags and warnings. Before, such a skill was stored with a description of just > and no triggers. Re-upload any skill that came in that way.

Upgrading to 0.12.1

No data migration. Search costs agents far fewer tokens, and a memory rewritten many times no longer crowds others off the page. Changes to check:

  • MCP search is lean by default. Ranked, federated and lexical search and context bundles return compact hits over MCP and leave out default values; pass compact: false for the full record. See Compact Search Results.
  • No structuredContent over MCP. Results are minified JSON text, sent once. A client that read structuredContent should read the text content instead.
  • Standing context over MCP drops entries. The rendered prompt already holds the same memories; pass include_entries: true to get the array as well.
  • Non-boolean compact is refused. "false" or 0 used to be read as the default; over MCP it is now an invalid-parameter error.
  • REST and the CLI are unchanged, except that POST /v1/lexical-search now honours compact (default false), which it used to ignore.
  • Agent key pairs in one step. mentisdb agent key generate and the dashboard's Generate key pair create an Ed25519 pair and register its public key; the dashboard's Add Key now works. Existing keys are unaffected. See Giving an agent a key.
  • Security: key changes on the dashboard need a PIN. Before 0.12.1.58 the dashboard's agent-key registration could replace an agent's existing key under the same key id, including a revoked one, so anyone able to reach the dashboard API could register a key that verifies as that agent. Key ids are now never reused or overwritten, and Generate key pair, Add Key and Delete answer 403 on a dashboard without MENTISDB_DASHBOARD_PIN (use mentisdb agent key generate|add|revoke --offline there). If your dashboard was reachable by untrusted local processes or users, review each agent's registered keys and revoke any you did not register.
  • Rotate keys with a new key id. A different key under an existing id, active or revoked, is refused: register the new key under a new id, then revoke the old one.
  • lme-benches/full_bench.sh no longer kills every MentisDB process. It refuses to run while a daemon answers on its REST port (MENTISDB_REST_PORT, default 9472) and stops only the daemon it started.
  • Fuller pages. A search for 5 results on a chain where one decision was rewritten 30 times returned 1 hit; it now returns 5 distinct live memories. Paged REST search no longer repeats or skips hits around contested memories, and a hit's score may be reported just below the hit before it so that pages stay in order.

Upgrading to 0.12

No data migration. Changes to check:

  • Request bodies are admitted before they are read. With bearer tokens on, the token is checked from the headers first, and a caller without a valid token is refused without its body being read. Ordinary routes and every MCP request take at most 2 MiB; only /v1/import-markdown, /v1/skills/upload and /v1/extract-memories take up to MENTISDB_MAX_BODY_BYTES (default 64 MiB), and only from an authenticated caller. Imports, ordinary requests and anonymous requests draw on three separate budgets (64 MiB with 32 MiB per peer for ordinary requests, 16 MiB with 8 MiB per peer for anonymous ones). Every body must keep up at least MENTISDB_MIN_BODY_BYTES_PER_SEC (64 KiB/s by default, 0 = off) in every window after a 60-second grace period; lower it for imports over a slow link. A stalled or too-slow body gets 408, an exhausted budget 503 with Retry-After, on every route. A large import over MCP fails with 413: use the REST route or the CLI.
  • Large signed imports. A read proof that also sends X-Mentis-Content-Sha256 (the digest the proof signs) is verified before the body is read and the body is hashed as it streams; without the header a read proof is still limited to 1 MiB. The CLI and pymentisdb 0.10.1 send the header, so a large mentisdb memory import with a read key works. Existing clients, mentischat included, need no change.
  • Reverse proxies must allow bodies up to MENTISDB_MAX_BODY_BYTES on the import routes (nginx's client_max_body_size defaults to 1 MiB), or large imports fail at the proxy.
  • Chain listing. Each chain in GET /v1/chains carries derived_backlog (embeddings in flight, parked or missing, and the implicit-edge backlog); all zeros means the chain's derived state is caught up.
  • Library users: VectorSidecarEntry::vector is a VectorRow (a handle into one shared vector store; VectorSidecar is built with VectorSidecar::build); call .to_vec() where you need a Vec<f32>, and MentisDbServiceConfig is #[non_exhaustive] (build it with new() and the with_* methods). See the developer docs.
  • Body settings are validated. A bad MENTISDB_MAX_BODY_BYTES, MENTISDB_MAX_INFLIGHT_BODY_BYTES, MENTISDB_BODY_IDLE_TIMEOUT_SECS or MENTISDB_MIN_BODY_BYTES_PER_SEC stops the daemon at startup instead of falling back to a default.

Upgrading to 0.11

Upgrade with cargo install mentisdb --locked --force, a release binary or the Docker image, then restart the daemon. Behaviour changes to check:

  • First start may migrate chains in the background. The daemon comes up at once and upgrades chains that need it through a journaled, backed-up, resumable worker pool. A request for a chain that is still migrating gets 503 with Retry-After and the percent done; every other chain is served normally. Watch progress with mentisdb migrate status, GET /v1/migrations or the dashboard banner. See Chain Migrations. Existing HNSW graph files are rebuilt once in the background.
  • One daemon per data directory. A second daemon on a directory that is already in use now refuses to start and names the holder's pid. Stop the old daemon first.
  • Public IP or domain? Set MENTISDB_DASHBOARD_ALLOWED_HOSTS. The Host allowlist now covers the MCP and REST listeners too. On a loopback bind behind a reverse proxy, MCP answers 403 Forbidden host to any name that is not listed. Add the public name or IP before the daemon starts. See Host Allowlist.
  • Key and access administration is operator-only. Registering or revoking agent keys, disabling agents and changing a chain's access policy are done from the dashboard (behind its PIN) or the local CLI. The REST routes /v1/agents/keys, /v1/agents/keys/revoke, /v1/agents/disable and /v1/access/policy/set answer 403 with any token and the matching MCP tools are gone. Scripts that used them must move to mentisdb agent key add|revoke, mentisdb agent disable|activate and mentisdb chain access set|allow|deny. See Public & Private Chains.
  • Search returns the current version. A superseded thought that would have ranked is replaced by its live successor, near-duplicates collapse into one hit, vector fusion no longer depends on query length, and the library applies the same thesaurus default as the server. Result lists differ from 0.10; every change has an opt-out. See Valid-Version Retrieval and Ranking Knobs.
  • The MCP event stream (GET / on the MCP port) carries metadata only: tool name, chain key, outcome and duration, never arguments, results or error text. With bearer tokens on, subscribing needs a global token (it reports every chain).
  • Request limits. offset + limit above 10,000 on ranked, lexical and federated search and context bundles, and a standing-context per_type_limit above 100, get 400 on REST, MCP and the CLI. Narrow the query with filters or since/until to read deeper.
  • Reverse proxies and my.mentisdb.com. REST on a loopback bind now checks Host for every client: list the name your proxy forwards in MENTISDB_DASHBOARD_ALLOWED_HOSTS. my.mentisdb.com works on the HTTPS ports only; switch http://my.mentisdb.com:9471 clients to https://my.mentisdb.com:9473 or http://localhost:9471.
  • Private chains need a dashboard PIN for admin routes. While the daemon holds a private chain and no MENTISDB_DASHBOARD_PIN is set, deleting chains, writing settings, managing bearer tokens and restarting from the dashboard answer 403.
  • mentisdb key generate never prints the private seed. It writes it to an owner-only file (--out FILE, else $MENTISDB_KEY_DIR, default ~/.mentisdb/keys/). Scripts that parsed the seed from the output must pass --out.
  • File permissions. New directories are created 0700 and data files 0600; existing ones keep their mode and the daemon warns about a data directory others can read. Run chmod 700 on it. Backups leave out operator/operator.key: back it up separately.
  • 1 MiB body limit for signed requests. Requests that carry an X-Mentis-Auth read proof, like REST requests with bearer tokens on, are buffered up to 1 MiB and get 413 above that. 0.12 lifts this for clients that also send X-Mentis-Content-Sha256 (the CLI and pymentisdb do): the body is then limited only by MENTISDB_MAX_BODY_BYTES.
  • Restoring a backup over a signed or private chain no longer fast-forwards it: the chain keeps its history and the backup is imported as a separate, renamed chain.
  • Deprecated: LLM reranking fields of RankedSearchQuery (never implemented, no-ops) and search::ppr (never called by ranked search). Both go away in the next breaking release.
  • Older chains from March and April 2026 (records stamped schema 4, and a later layout that earlier releases decoded with shifted fields) are now read correctly and verified before they migrate; a record that does not verify is refused instead of being rehashed.

Upgrading to 0.10.9

No data migration is needed. Behaviour changes to check before upgrading:

  • Reads no longer create chains. Search, head, agents, thought lookup and metadata calls on an unknown chain_key return 404 instead of silently creating an empty chain. Only bootstrap, append, retrospectives, markdown import, agent and entity-type upserts and merge targets create chains (the configured default chain is still created on demand). Call mentisdb_bootstrap before reading a new chain. Empty, over-256-byte or control-character chain keys return 400.
  • Error statuses. 400 invalid input, 401 missing or out-of-scope token, 403 permission denied (e.g. bad skill signature), 404 unknown chain or resource, 409 conflict (branch into an existing chain), 413 body over 1 MiB with bearer tokens enabled, 500 with a generic internal server error body (details only in the daemon log), 501 for memory extraction on a build without llm-extraction.
  • Chain-scoped tokens lose access to server-wide operations: chain listing, webhook list/delete, skill mutations and /v1/admin/flush. See Bearer Tokens.
  • Webhooks to private, loopback or other internal targets are refused and load inactive if already persisted; redirects are not followed. See Webhook Callbacks.
  • Dashboard scripts that POST, PATCH or DELETE (including the login form) without an Origin or Referer header must send X-MentisDB-Dashboard: 1.
  • Dashboard Host allowlist. Requests whose Host header is not localhost, a loopback IP, my.mentisdb.com, the bind host or a MENTISDB_DASHBOARD_ALLOWED_HOSTS entry now get 403. If you reach the dashboard through a public name or a reverse proxy, add that name. See Host Allowlist.
  • fsync is now opt-in. Group commits are written to the OS but only fsynced with MENTISDB_FSYNC=1; flush, shutdown and drop always sync. Appends are about 4x faster by default.
  • Coming from 0.10.1 to 0.10.8 (issue #23). Those releases loaded one FastEmbed model per chain and could use gigabytes of RAM with many chains. 0.10.9 shares one model per process and rebuilds large sidecars in the background, so for a while after the first start some chains answer ranked search with lexical and graph results only. The model cache moves to <MENTISDB_DIR>/.fastembed_cache; a stray .fastembed_cache in the directory you used to launch the daemon can be deleted. Set MENTISDB_EMBEDDINGS=off or local-text to skip the ONNX model entirely.
  • Intel Macs: the prebuilt x86_64-apple-darwin binary has no FastEmbed and uses local text vectors.

Cryptographic Signatures

Agents can hold Ed25519 keys. A registered key signs skill uploads (every upload from an agent with a key must carry a valid signature) and thoughts. A thought that carries a signature must verify against an active, unrevoked key of its agent or the append is refused (HTTP 403). The current signature format (mentisdb/thought/v2) covers every semantic field and is bound to the chain key and the head hash, so a signed thought cannot be replayed onto another chain or position. A v2-signed append built on an older head fails with "fetch the head, sign again" (HTTP 400).

Giving an agent a key

Registering a public key is an operator action (the dashboard behind its PIN, or the local CLI). The REST route and MCP tool that let any token holder register keys were removed in 0.11. Since 0.12.1 the operator can create the key pair and register its public key in one step, from the command line or the dashboard. MentisDB keeps only the public key.

From the command line

mentisdb agent key generate builder --key-id builder-202610 --chain project --pin 123456
# or with the daemon stopped, against the data directory:
mentisdb agent key generate builder --key-id builder-202610 --chain project --offline

# sign a thought locally with the saved file (the seed is never sent)
mentisdb thought append "Release on Tuesdays" --chain project --type Decision \
  --agent builder --signing-key-id builder-202610 --private-key-file ~/.mentisdb/keys/<prefix>.key

agent key generate creates an Ed25519 key pair on the machine you run it on, saves the private seed to a file only you can read (mode 0600 on macOS and Linux; on Windows the file inherits its folder's permissions, so restrict the folder), registers the public key, and prints the public key and the file's path. Without --out FILE the file is $MENTISDB_KEY_DIR/<public key prefix>.key (default ~/.mentisdb/keys); an existing file is overwritten only with --force, which refuses a symbolic link at --out. The private key is never printed, and --json never includes it. A wrong PIN, an unreachable daemon or a key id the agent already has is reported before anything is written. If the registration fails after the file was written, the file is kept and the error prints the mentisdb agent key add ... --public-key-hex command that registers it later.

From the dashboard

This needs a dashboard protected by a PIN (MENTISDB_DASHBOARD_PIN); a dashboard without one refuses every key change and says why. Open the agent's page, enter a Key ID in the Public Keys card and click Generate key pair. Your browser makes the pair (WebCrypto), signs a proof of possession and registers only the public key; the private key never crosses the network. The private key is then shown once, with Download key file (<agent>-<key-id>.key, which --private-key-file reads; the link is valid for 10 seconds) and Copy. The dialog stays open until you tick I have saved this key, and closing it removes the key from the page. Browsers save downloads readable by other users of the computer, so, as the dialog reminds you, run chmod 600 <file> on macOS or Linux. A browser without Ed25519 in WebCrypto is told to use the CLI instead.

The key file is the only copy of the private key. MentisDB keeps only the public key and cannot recover it. Back the file up somewhere safe, and never paste it into a chat or give it to an AI agent. To give a key to an agent on another machine, hand over only the key file, over a channel you trust.

A key made elsewhere

To register a public key you already have, use agent key add or the dashboard's Add Key (which works since 0.12.1, and accepts 64 hex characters, 0x hex or 32 comma-separated bytes, and also needs the dashboard PIN). The operator vouches for the key, so no proof of possession is needed. A key id is never reused: to rotate, register the new key under a new id and revoke the old one.

mentisdb key generate --out ~/.mentisdb/builder.key
mentisdb key show ~/.mentisdb/builder.key          # prints the public key hex
mentisdb agent key add builder --key-id builder-202610 \
  --public-key-hex <64 hex> --chain project --pin 123456

Rotate a key by adding the new one and running mentisdb agent key revoke builder --key-id <old>. Thoughts and skills signed before the revocation stay valid. mentisdb chain access verify --chain project re-checks every stored signature and exits non-zero if any fails. An empty signature field stored by older clients counts as unsigned, not as an invalid signature.

Why this matters

Signed skills and thoughts mean you always know which key wrote which version. Combined with the hash chain and immutable skill versions, this gives a cryptographically auditable record of your fleet's knowledge. Signatures say who wrote something, not that it is true: see Provenance.

Public & Private Chains

Since 0.11 a chain is either public (anyone who can reach the server writes unsigned and reads freely) or private (writes need a valid signature by an allowed Ed25519 key, and what is written while the chain is private can be read only by a reader who proves possession of an allowed key). Existing chains need no migration: a chain without access records is public.

Segments

The mode is not a flag. Every switch is a signed governance record in the chain itself that opens a new segment, so each thought belongs to the segment its position falls in and every change of mode is a tamper-evident entry. Going private opens a private segment; going public again opens a public one, and the earlier private thoughts stay private.

  • An authorized reader (a key in the chain's current policy, proved on each request) and the operator see everything.
  • Everyone else sees only public segments, on every read surface: ranked, lexical and vector search, recent and standing context, traversal, get by id, head, bundles, federated and branch search, Markdown export, listings and counts. Ranking statistics are computed over the visible thoughts, so scores do not move when private thoughts are added, and a refused write does not say whether an agent or key exists.
  • Public readers can still see that a chain has private segments, where they are and roughly how large, so the public history stays verifiable. Content written while a chain was public stays public.

The operator

Only the operator changes who may write and read. The operator is whoever reaches the dashboard behind its PIN (MENTISDB_DASHBOARD_PIN) or runs the local mentisdb CLI on the host with --offline against the data directory. REST and MCP cannot, with any bearer token. Without a PIN the dashboard neither administers access nor shows chains that have private segments.

# make a chain private (the operator key becomes its first governor)
mentisdb chain access set private --chain vault --pin 123456

# create and register a key (or: agent key add ... --public-key-hex for a key made elsewhere),
# then allow it on the chain with the public key hex it printed
mentisdb agent key generate builder --key-id builder-202610 --chain vault --pin 123456
mentisdb chain access allow builder builder-202610 <64 hex> --chain vault --pin 123456

# remove it, disable or re-activate an agent, inspect the operator view
mentisdb chain access deny builder builder-202610 --chain vault --pin 123456
mentisdb agent disable builder --chain vault --pin 123456
mentisdb agent activate builder --chain vault --pin 123456
mentisdb chain access admin --chain vault --pin 123456

# the same, with the daemon stopped, directly against the data directory
mentisdb chain access set private --chain vault --offline

The operator signs governance records with <data dir>/operator/operator.key (created on first use, mode 0600). That key is always a governor, so a policy can never lock itself out: it is the recovery path if every agent key is lost. Back it up with your chains. --offline refuses to run while a daemon holds the data directory; use the dashboard (--pin) to change a running daemon.

Reading a private chain

A reader proves possession of an allowed key on every request with an X-Mentis-Auth header: an Ed25519 signature over the method, path, query, body hash, key identity, a timestamp and a single-use nonce. The private key never travels over the wire and never has to enter a language model's context: the process that talks to the server holds the key file and signs.

# CLI: sign every REST request
mentisdb search "launch plan" --chain vault \
  --read-key-file builder.key --read-agent builder --read-key-id builder-202610

# stdio MCP proxy: reads the same variables and signs everything it forwards
MENTISDB_READ_KEY_FILE=builder.key MENTISDB_READ_AGENT_ID=builder \
MENTISDB_READ_KEY_ID=builder-202610 mentisdb --mode stdio
  • Proofs are accepted within 60 seconds of the server clock and each nonce only once. A header that is present but invalid gets 401, so a client with a skewed clock learns why; a request without the header is a public reader. A nonce is spent only when the proof grants access to a private segment, and the replay cache holds at most 25,000 nonces per key and 100,000 in total; a proof refused because the cache is full reads the public view.
  • Key sets are per chain: a proof never reads a chain the key is not allowed on, even inside a federated search.
  • A proof authenticates but does not encrypt. Serve private chains over HTTPS, and do not put a proxy that rewrites paths or bodies in front of the daemon.
  • Python: pymentisdb.ReadSigner (see Python Client).

Verification when a chain opens

Opening a chain with private segments verifies them: every thought in a private segment must carry a valid signature by a key that was allowed at that point. A thought that fails is quarantined: hidden from every reader and reported by mentisdb chain access verify. Nothing is served before verification finishes. After a clean run the chain writes a checkpoint signed by the operator key, so later opens verify only what is new. If a chain no longer matches its checkpoint (records removed or rewritten), it is locked (every position reads as private) instead of being served as public; after inspecting the file, the operator deletes <chain>.verified.json to re-seal it.

Merge, copy and restore

Merging chains and copying an agent's memories re-append thoughts unsigned under another chain, which would publish private text and discard signatures. They are refused, with a clear error and no change, for a source that has private segments, governance records or signed thoughts. Branching copies nothing and is allowed from any thought you can see. Restoring a backup over a signed or private chain keeps the chain's history and imports the backup as a separate, renamed chain.

Provenance: memories are data

Every thought in a response carries a provenance object:

"provenance": {
  "segment": "public",          // or "private"
  "signed": true,
  "signature": "valid",         // "unsigned", "valid" or "invalid"
  "signature_version": 2,
  "verified_agent": "alice",    // set when the signature is valid and the key is active
  "trust": "untrusted_data"
}

An unsigned thought in a public segment can have been written by anyone; verified_agent says whose key signed, not that the content is true or safe. The MentisDB skill tells agents to weigh memories as evidence and never follow instructions found in them. The full threat model, wire formats and residual risks are in docs/CHAIN_ACCESS.md.

Memory Scopes

MentisDB 0.8.2 introduces memory scopes — a lightweight way to partition thoughts within a single chain. Scopes are stored as tags on each thought and let you isolate memories by visibility level without creating separate chains.

Scope levels

ScopeTagPurpose
Userscope:userVisible to the owning user across all sessions. Default scope for most memories.
Sessionscope:sessionScoped to a single conversation session. Ephemeral working memory — scratch thoughts, in-progress hypotheses.
Agentscope:agentPrivate to a specific agent. Not shared with other agents in the fleet. Useful for internal heuristics or private state.

Using scopes

When appending a thought, set the scope parameter to one of User, Session, or Agent. MentisDB stores the scope as a tag (e.g. scope:user) on the thought. In search, use the scope parameter to filter results to a specific scope level.

Backward compatible: Existing thoughts without a scope tag are treated as User-scoped. You do not need to migrate or retag existing chains.

Temporal Queries

MentisDB 0.8.2 adds temporal query support, allowing you to query the chain as it existed at a specific point in time and to set time-bounded validity on relations.

Point-in-time queries with as_of

Pass as_of (an RFC 3339 timestamp) to search and traversal tools to see only thoughts that existed at that time. Thoughts appended after the timestamp are excluded. Thoughts that were later superseded are still returned if they were valid at as_of. This is useful for auditing what an agent knew at a specific moment, or for reproducing decisions made under a previous state of knowledge.

mentisdb_ranked_search(
  text: "caching strategy",
  as_of: "2025-12-01T00:00:00Z"
)

Temporal bounds on relations

Thought relations now support valid_at and invalid_at fields — RFC 3339 timestamps that define when a relation becomes active and when it expires. A relation is considered active if the current time falls between valid_at and invalid_at. If neither field is set, the relation is always active (backward compatible with existing chains).

Use invalid_at to model time-limited relationships — for example, a Supersedes edge that only takes effect after a transition date, or a Supports link that expires when a deprecation window closes.

Invalidation & Dedup

MentisDB never deletes corrected or superseded thoughts. Instead it builds an in-memory invalidated_thought_ids set for any thought that is the target of a later Supersedes, Corrects, or Invalidates relation.

Default search hides stale memory

By default, ranked search, plain search, context bundles, recent context, and memory markdown export exclude those IDs so agents see current memory. Pass include_invalidated: true on MCP/REST search tools (or ThoughtQuery::with_include_invalidated(true) in the crate) for full audit archaeology.

The set only fills when edges exist

Filtering alone does not invent edges. The invalidation set stays empty unless:

  1. Agents write typed edges — search before append and link with Supersedes / Corrects / Invalidates (MentisDB skill).
  2. Auto-dedup is enabled — set MENTISDB_DEDUP_THRESHOLD=0.85 (recommended for multi-agent and long-lived chains). Near-duplicate appends then auto-emit Supersedes against a recent match (MENTISDB_DEDUP_SCAN_WINDOW recent thoughts, default 64). Dedup is off when the env var is unset.
Production tip: For long-running agent brains, enable MENTISDB_DEDUP_THRESHOLD=0.85 in .env or the process environment so near-duplicate noise is linked and hidden from default search without relying solely on harness discipline.
# Recommended for multi-agent / long-lived daemons
MENTISDB_DEDUP_THRESHOLD=0.85
MENTISDB_DEDUP_SCAN_WINDOW=64

# Audit: include superseded thoughts in MCP ranked search
# mentisdb_ranked_search(text: "...", include_invalidated: true)

Since 0.11 dedup never retires a thought the author rated more important than the incoming near-copy, so a throwaway restatement cannot hide a critical Constraint or Decision.

Valid-version retrieval (0.11)

Agents rarely type invalidating links. On one real installation none of 14 Correction/AssumptionInvalidated thoughts and none of about 90 Decision thoughts carried a Supersedes, Corrects or Invalidates relation, so the invalidation set stayed empty and an old policy kept winning search. Since 0.11 retrieval reasons about lineage, derived when a chain opens (no migration):

  • Superseded: a superseded thought that would have ranked is replaced by its live successor, which carries successor_of naming the thought it stands in for. Hiding the old version never leaves the agent with nothing.
  • Contested: a thought that a newer Correction, AssumptionInvalidated or Decision only references (through refs or References), or that anything Contradicts, stays visible with version_status: "contested" and the contesting thought is promoted above it. Weak links do not hide memory, because a reference is often just background.
  • Every thought JSON on every surface (search, get, head, recent, traverse, bundles, dashboard) carries version_status, successors and current_version when it is not plainly current, including results returned with include_invalidated: true.
  • Who may replace a thought: on a chain with a signing policy, a strong link replaces its target only when its writer was verified when the chain opened and is the target's own agent or a key authorized on the chain. Anyone else's link only contests (the target stays current with version_status: "contested", the link listed under successors with authorized: false). On an open chain a replacement by another agent still redirects but is flagged: successor notes carry agent_id, trust, cross_agent and authorized. Cross-chain and branch lineage follow the same rules, and a chain of more than 64 versions of one thought is refused.
  • Appending a Correction, AssumptionInvalidated or a Decision that replaces memory without a typed relation returns warnings naming candidate target ids; append the {"kind": "supersedes", "target_id": "..."} link.
  • Standing context replaces a superseded constraint or decision with its successor, context bundles redirect their seeds the same way, and the MEMORY.md export drops superseded thoughts and marks contested ones contested by #N.
  • Across chains: a Supersedes, Corrects or Invalidates relation that carries a chain_key applies wherever one search sees both chains (a branch and its ancestors, federated search); the hit names successor_of_chain. A chain searched alone is unchanged, untyped links are not applied across chains, and a public reader is never redirected to a private successor.

Turn redirection off per request with resolve_successors: false (plain hiding, as in 0.10). An expired supersession (invalid_at in the past) no longer hides its target.

Advanced Retrieval

MentisDB layers four complementary signals over its append-only chain — lexical (BM25), dense-vector (cosine), graph BFS, and session cohesion — and fuses them into a single ranked result set. The full algorithmic pipeline is described in the ranked-search pipeline blog post and the white paper; this section summarises the knobs you can turn. As of 0.9.9, ranked search automatically applies the built-in thesaurus (~900 headwords + lemmas) on every query for better recall on vocabulary mismatch and verb forms — no extra parameters needed. Default search also excludes superseded/corrected/invalidated thoughts; see Invalidation & Dedup.

Reciprocal Rank Fusion (RRF)

Set enable_reranking: true on any mentisdb_ranked_search call to rerank the top rerank_k candidates (default 50) by merging three independent rankings — lexical-only, vector-only, and graph-only — through Reciprocal Rank Fusion with damping constant k=60. RRF is robust when the absolute magnitudes of the component scores are not directly comparable.

Since 0.10.9 the fused RRF score is added to the normal ranked score as a consensus bonus scaled by 50 (a rank-1 hit in all three lists is worth about +2.5), and only lists that actually scored a candidate contribute. Earlier releases replaced the ranked score with the tiny raw RRF total, which badly degraded results when reranking was enabled; if you turned it off for that reason, it is safe to use again.

Also in 0.10.9: thesaurus synonyms are keyed by stem, so inflected query terms ("debugging", "deploys") expand like their base forms, at a damped weight of 0.3 with at most 3 synonyms per term so they aid recall instead of competing with literal matches; ranked, lexical, vector and graph paths are substantially faster; and filtered vector search over an HNSW index falls back to an exact scan or oversamples so filters no longer drop matches.

Ranking Knobs (0.11)

0.11 changes three defaults and makes every ranking knob reachable from REST, MCP and the CLI. Bad values are a 400, not a silent default.

  • Relative vector fusion. The vector weight used to decay with the absolute BM25 score, which grows with the number of query words, so a ten-word paraphrase silenced the vector channel exactly when the wording differed. It now decays with a hit's lexical score relative to the query's best.
  • Near-duplicate collapse. Hits whose text is at least 90% similar (Jaccard) fold into one; the survivor lists the folded ids in collapsed_duplicates. Text queries only. One real chain had 301 of 749 live thoughts in near-duplicate clusters.
  • One thesaurus default. The library and the server both expand queries with the built-in thesaurus at weight 0.3.
Request fieldCLI flagDefault
resolve_successors--resolve-successors BOOLtrue
collapse_duplicates--collapse-duplicates THRESHOLD (0 disables)0.9
vector_fusion--vector-fusion relative|absoluterelative
synonym_weight--synonym-weight WEIGHT (0 disables)0.3
df_scope--df-scope global|fieldglobal
df_cutoffs.{content,tags,concepts,agent_id,agent_registry}--df-cutoff-content, -tags, -concepts, -agent-id, -agent-registry0.30 / 0.30 / 0.30 / 0.70 / 0.60

They apply to ranked search, federated search and context bundles (mentisdb search, search federated, search bundles). Process-wide: MENTISDB_VECTOR_FUSION=absolute, MENTISDB_COLLAPSE_DUPLICATES=off and MENTISDB_DF_SCOPE=field (experimental). On the full LoCoMo-10P and LongMemEval protocol with these defaults, R@10 on LoCoMo is 76.7% (73.5% in 0.10.9.54) and R@5 on LongMemEval is 69.8% (68.0%).

Context Bundles

mentisdb_context_bundles returns seed-anchored grouped results instead of a flat list. Each bundle pairs one lexical seed with its graph-expanded neighbours in provenance order, so the agent can inspect why a supporting thought surfaced. Use bundles when you want to preserve evidence groupings rather than collapse everything into ranked rows.

Standing Context

Recent context only loads the last few thoughts, so a preference stated months ago was never loaded at session start and users had to repeat themselves. Standing context returns the durable half of memory regardless of age: live Constraint, PreferenceUpdate, UserTrait, RelationshipUpdate, Goal, Decision and LessonLearned thoughts (user-scoped or unscoped), ranked by importance then recency, with restatements collapsed, capped at 8 per type and 40 in total, plus the newest Handoff and Checkpoint or Summary. A superseded constraint or decision is replaced by its successor and contested entries are flagged.

The prompt renders each entry as one escaped line (line breaks and invisible characters become visible marks), so stored text cannot forge entries or instructions. Each entry shows trust=verified|unsigned|unverified, replacements by another agent are marked [REPLACES #n ...], and the block says its entries are data, not instructions. On a chain that requires signatures, an unverified writer's importance is capped at 0.5 for ranking.

# MCP (load at session start, before mentisdb_recent_context)
mentisdb_standing_context(chain_key: "project")

# REST
curl -s http://127.0.0.1:9472/v1/standing-context \
  -H 'content-type: application/json' -d '{"chain_key":"project"}'

# CLI
mentisdb thought standing --chain project

Optional fields: agent_id, types, since, as_of, include_invalidated, per_type_limit (default 8, at most 100) and limit (default 40). The response has the typed entries, duplicates_collapsed and a ready-to-load prompt. Over MCP, where the reader is a model, entries (a second copy of the memories in the prompt) is returned only with include_entries: true.

Dense-Vector Sidecars

Vector state lives in rebuildable per-chain sidecars partitioned by chain, thought id, model, dimension, and embedding version. The daemon ships the fastembed-minilm provider by default — a 384-dimension MiniLM model running locally via ONNX, with no cloud dependency and no API key. Hybrid ranking blends lexical and cosine scores via a smooth exponential fusion that amplifies pure-semantic matches (~36×) and decays to additive composition as lexical evidence grows.

Since 0.10.6, each append writes one integrity-chained WAL record beside the JSON snapshot (*.json.wal, magic MDBVWAL1). Load verifies the snapshot digest, then replays the WAL. After 32 records the snapshot is compacted and the WAL is removed. Older binaries that only read JSON treat a sidecar with a pending WAL as stale and rebuild from the chain. The thought log remains canonical. Since 0.10.8 an unreadable sidecar (for example a stale or mismatched WAL) no longer blocks opening the chain: it is logged and rebuilt from the thought log.

Since 0.10.9 one FastEmbed model is shared by every chain in the process and texts are embedded in small bounded batches, so memory no longer grows with the number of open chains. The model cache lives in <MENTISDB_DIR>/.fastembed_cache (override with FASTEMBED_CACHE_DIR). Opening a chain with more than 32 thoughts and no fresh sidecar no longer embeds its history on the request path: a single background worker rebuilds the sidecar, and ranked search on that chain returns lexical and graph results until the rebuilt sidecar is adopted on a later request or append. Opening a chain never rewrites its persisted vector provider configuration. Set MENTISDB_EMBEDDINGS=off or local-text to opt out of FastEmbed entirely.

Branching Chains

mentisdb_branch_from forks a new chain from an existing thought. The branch receives a genesis thought with a BranchesFrom relation pointing at the fork point; ranked search on the branch transparently includes results from ancestor chains, so experimental or tenant-scoped branches can read shared context without cross-contaminating it. Ancestor discovery is transitive.

mentisdb_federated_search runs one ranked-search query across a list of chains concurrently and returns one merged, deduplicated, re-scored result set. Each hit carries the chain_key it originated from, so multi-agent hubs and cross-organisational memory aggregations can share a single query surface. Per-chain overrides let you apply different filters, limits, or RRF settings per chain.

Since 0.10.9 per-chain rankings are fused by the same additive RRF bonus, keyed by chain and thought id, and duplicates are removed before offset / limit paging, so pages no longer repeat or skip results.

Pass compact: true to mentisdb_ranked_search or mentisdb_federated_search (REST POST /v1/ranked-search and POST /v1/federated-search, CLI mentisdb search --compact and mentisdb search federated --compact) to get smaller hits. Responses are about a quarter smaller (23.7% on a copy of a working 11-chain MentisDB, 34.2% on a generated corpus) with the same request time, which is what an agent pays for in tokens when it scans many hits. Over REST and the CLI the default response is unchanged. Compact search was contributed by Austin Faulkner-Pearce. Since 0.12.1, POST /v1/lexical-search accepts compact too.

Over MCP, compact is the default (since 0.12.1) for mentisdb_ranked_search, mentisdb_federated_search, mentisdb_lexical_search and mentisdb_context_bundles, and it goes further: results are minified JSON with no structuredContent copy, and a hit leaves out default values. No provenance means public and unsigned (each response says so once in default_provenance), no role means Memory, no importance means 0.5 and no chain_key means the chain you searched. A private segment, a signature and a verified writer are always shown, and so are version_status, successors and current_version. Pass compact: false for the full record. On a generated 3,500-thought chain a 10-hit ranked search went from 23,657 to 5,948 characters.

A compact hit is chain_key, the total score as a plain number, and the thought, in the same order as the full form. The thought leaves out hash, prev_hash, thought_signature, signing_key_id, schema_version, agent_name, agent_owner (the last two repeat the agent registry entry for agent_id) and top-level fields that are null or empty. Hit-level score components, matched_terms and match_sources are left out too.

In the REST compact form, nothing an agent needs to judge a hit is dropped. The provenance object (segment, signed, signature, verified agent, trust), the version fields (version_status, successors, current_version, successor_of, collapsed_duplicates), relations, concepts, refs, content and the graph provenance of graph-expanded hits are always kept. Who may see a thought is decided before compaction, so a public reader still gets only the public segment of a private chain, and a reader with a valid read proof still gets the private one.

POST /v1/ranked-search
{"chain_key": "project", "text": "job queue storage", "limit": 5, "compact": true}

// Full response (default)
{
  "backend": "hybrid",
  "total": 1,
  "results": [
    {
      "chain_key": "project",
      "score": {
        "confidence": 0.0, "graph": 0.0, "importance": 0.17541419, "lexical": 1.9490464,
        "recency": 0.05, "relation": 0.0, "rrf": 0.0, "seed_support": 0.0,
        "session_cohesion": 0.0, "total": 5.932654, "vector": 0.34079674
      },
      "matched_terms": ["job", "queue", "storag"],
      "match_sources": ["content", "tags", "concepts"],
      "graph_distance": null, "graph_path": null,
      "graph_relation_kinds": [], "graph_seed_paths": 0,
      "thought": {
        "agent_id": "builder", "agent_name": "Builder", "agent_owner": "platform",
        "concepts": ["job queue"], "confidence": null,
        "content": "Use Postgres for the job queue; revisit if throughput exceeds 5k jobs per second.",
        "entity_type": null,
        "hash": "31de8f264b1588a29be30a278a24e8623cf51b8f3ce8483a7e52f69ce80e21e1",
        "id": "1182d44f-3834-4ff0-9121-eab986b1a4f5",
        "importance": 0.800000011920929, "index": 0, "prev_hash": "",
        "provenance": {
          "segment": "public", "signature": "unsigned", "signature_version": null,
          "signed": false, "trust": "untrusted_data", "verified_agent": null
        },
        "refs": [], "relations": [], "role": "Memory", "schema_version": 3,
        "session_id": null, "signing_key_id": null, "source_episode": null,
        "tags": ["storage"], "thought_signature": null, "thought_type": "Decision",
        "timestamp": "2026-11-01T23:03:19.669167Z"
      }
    }
  ]
}

// Same request with "compact": true
{
  "backend": "hybrid",
  "total": 1,
  "results": [
    {
      "chain_key": "project",
      "score": 5.932654,
      "thought": {
        "agent_id": "builder",
        "concepts": ["job queue"],
        "content": "Use Postgres for the job queue; revisit if throughput exceeds 5k jobs per second.",
        "id": "1182d44f-3834-4ff0-9121-eab986b1a4f5",
        "importance": 0.800000011920929, "index": 0,
        "provenance": {
          "segment": "public", "signature": "unsigned", "signature_version": null,
          "signed": false, "trust": "untrusted_data", "verified_agent": null
        },
        "role": "Memory", "tags": ["storage"], "thought_type": "Decision",
        "timestamp": "2026-11-01T23:03:19.669167Z"
      }
    }
  ]
}

Use it for routine recall. Leave it off when you need the hashes or signatures to verify a thought yourself, when you audit a provenance chain, or when you debug per-component scores. mentisdb_get_thought returns the full record of any hit.

Entity Types & Provenance

Per-Chain Entity Types

Attach an entity_type label to any thought — e.g. "incident", "customer", "deploy" — to categorise memory beyond free-form tags. Entity types are registered per chain through mentisdb_upsert_entity_type and discoverable via mentisdb_list_entity_types; each carries an optional description and a usage counter. Ranked search filters by entity type, and the dashboard explorer surfaces them as a first-class facet.

source_episode — Derived Memory Provenance

When a thought is derived from a larger episode (a conversation turn, an ingested document, a batch job), set the optional source_episode field to a stable identifier so every derived thought can later be traced back to its source. Ranked search filters by source_episode exactly the same way it filters by agent or tag.

Since 0.12.2 the field is actually stored: POST /v1/thoughts and mentisdb_append keep it and return it on the thought (earlier versions accepted it and dropped it). It is an exact-match filter (a thought matches only if its source_episode equals the value) on /v1/search, /v1/ranked-search, /v1/federated-search and /v1/context-bundles, and on the matching MCP tools. Lexical search, thought traversal, summary candidates and the MEMORY.md export do not take it yet.

On the CLI, pass --source-episode ID to thought append to store it, or to search, search filter, search federated or search bundles to filter. The commands whose route would ignore it (thought traverse, thought candidates, memory export, search lexical) refuse the flag rather than silently drop the filter.

Webhook Callbacks

Register an HTTP endpoint that MentisDB will POST to whenever a thought is appended to a chain. Useful for syncing an external index, triggering downstream workflows, or mirroring writes to observability pipelines.

Delivery is fire-and-forget: up to 3 attempts per event (5 s timeout each, exponential backoff from 1 s). Registrations persist to mentisdb-webhooks.json next to the chain registry and survive daemon restarts. Fan-out is bounded by a queue and concurrency semaphore, so bursty appends cannot spawn unlimited outgoing tasks.

MCP tools: mentisdb_register_webhook, mentisdb_list_webhooks, mentisdb_delete_webhook. REST routes are documented in the developer guide.

Allowed targets

  • Only http and https URLs are accepted, and redirects are never followed.
  • By default, localhost, loopback, private (RFC 1918), link-local, CGNAT (100.64.0.0/10), documentation and benchmarking ranges, multicast, broadcast, reserved and unspecified addresses are rejected, as are IPv6 unique-local, link-local and documentation addresses and IPv6 forms that embed a blocked IPv4 address (IPv4-mapped, IPv4-translated ::ffff:0:0:0/96, NAT64, 6to4). The local-use NAT64 prefix 64:ff9b:1::/48 and Teredo 2001::/32 are rejected outright.
  • The same check runs on every address a hostname resolves to at delivery time, so DNS names pointing at internal hosts (including DNS rebinding) cannot reach them.
  • Webhooks already persisted in mentisdb-webhooks.json that point at a blocked target are loaded inactive, with a warning in the log.
  • A circuit breaker pauses a webhook for 5 minutes after 5 consecutive failed deliveries; a successful delivery resets it.
  • Logs show only the target's scheme, host and port, never paths, query strings or credentials.

With bearer-token access enabled, listing and deleting webhooks needs a global token. A chain-scoped token may register a webhook only with a chain_key_filter inside its scope.

Private webhook targets

Self-hosted deployments whose webhook consumers live on a private network (a Tailscale tailnet, a WireGuard subnet, a LAN host) can open just those ranges with MENTISDB_WEBHOOK_ALLOWED_CIDRS, set in the environment, ./.env or <MENTISDB_DIR>/.env:

# Tailscale tailnet (IPv4 CGNAT range + Tailscale's IPv6 ULA prefix)
MENTISDB_WEBHOOK_ALLOWED_CIDRS=100.64.0.0/10,fd7a:115c:a1e0::/48
# a WireGuard subnet
MENTISDB_WEBHOOK_ALLOWED_CIDRS=10.8.0.0/24
# a single host (a bare address means /32 or /128)
MENTISDB_WEBHOOK_ALLOWED_CIDRS=192.168.1.50
  • Entries are separated by commas and/or whitespace. Each is address/prefix (IPv4 or IPv6, brackets allowed around IPv6) or a bare address. Host bits are normalized, so 10.8.0.7/24 becomes 10.8.0.0/24.
  • An address inside a listed range is allowed even if it falls in a blocked range; every other internal range stays blocked. IPv4-mapped IPv6 addresses (::ffff:a.b.c.d) match IPv4 ranges.
  • localhost host names are still rejected even if loopback is listed; use the IP literal (http://127.0.0.1:8080/hook).
  • The list applies at registration, when persisted registrations are reloaded, and at delivery time (every resolved DNS address and literal IPs are re-checked). Removing the variable, or narrowing it so a registration is no longer covered, loads that registration inactive again on the next start.
  • Any unparsable entry, or any entry broader than /8 (IPv4 or IPv6; fd00::/8 still fits), makes the daemon refuse to start. The active ranges are logged as a warning at startup, with a dedicated warning for any listed range that covers loopback (127.0.0.1, ::1) or the cloud metadata address 169.254.169.254. Unset keeps the strict default.

Security: list only the narrowest ranges your consumers live in (your tailnet, one /24, one host). Never list cloud metadata (169.254.169.254, 169.254.0.0/16) or broad ranges such as 10.0.0.0/8. Any token allowed to register webhooks (global tokens, and chain-scoped tokens with an in-scope chain_key_filter) can make the daemon send requests into the listed ranges.

LLM-Extracted Memories

Turn raw text — a chat transcript, a pasted document, a ticket comment — into a review-ready slate of typed thoughts. The mentisdb_extract_memories tool calls a configured OpenAI-compatible model, validates the JSON schema of the candidate thoughts, and returns them to the caller. Nothing is written to the chain until the caller explicitly appends the reviewed candidates.

Defaults to gpt-4o, configurable via environment variables. The prompt enforces strict JSON output and the server validates schemas before return, so provider quirks (for example OpenAI-compatible endpoints that reject the response_format hint) cannot poison the chain. See llm-extracted-memories-design.md for the full contract.

Python Client (pymentisdb)

pymentisdb is the official Python client, published to PyPI. It wraps the REST surface with typed request and response objects and integrates natively with LangChain via MentisDbMemory.

pip install pymentisdb                 # 0.10.0 or later; needs only requests
pip install 'pymentisdb[signing]'      # ReadSigner, for reading private chains
pip install 'pymentisdb[langchain]'    # MentisDbMemory (LangChain BaseMemory)

Use 0.10.0 or later: the 0.9.0 wheel on PyPI contained no code. import pymentisdb needs no LangChain; MentisDbMemory needs the langchain extra (langchain-core before 1.0, or 1.0 and later with langchain-classic, which the extra installs) and raises ImportError naming it when it is missing.

from pymentisdb import MentisDbClient, ThoughtType client = MentisDbClient("http://127.0.0.1:9472") client.append_thought( chain_key="my-chain", agent_id="planner", thought_type=ThoughtType.DECISION, content="Adopt LRU eviction for the response cache", ) hits = client.ranked_search(chain_key="my-chain", text="cache eviction", limit=5)

Searches can ask for smaller results with compact=True (see Compact Search Results). The default is unchanged. Compact results come back as a CompactRankedSearchResponse whose hits and thoughts are separate types: the fields the server drops (hashes, signatures, agent name and owner, score components, matched terms) are not attributes, so reading one raises AttributeError instead of returning an invented value, while provenance and the version fields are kept. federated_search searches several chains, and ranked_search, federated_search and context_bundles accept keyword-only graph, as_of, include_invalidated and the ranking knobs (pymentisdb 0.10.0).

from pymentisdb import MentisDbClient, GraphOptions

client = MentisDbClient()
response = client.ranked_search(
    text="job queue", chain_key="project", limit=5,
    compact=True, graph=GraphOptions(max_depth=1),
)
for hit in response.results:          # CompactRankedSearchHit
    print(f"[{hit.total_score:.2f}] {hit.thought.content}")
    print(hit.thought.provenance.signature, hit.thought.version_status)

merged = client.federated_search(["backend", "frontend"], text="auth bug", compact=True)

To read the private segments of a chain (pymentisdb 0.10.0; 0.10.1 also sends X-Mentis-Content-Sha256 so bodies over 1 MiB work), give the client a ReadSigner (pip install pymentisdb[signing]). It signs every request locally with the X-Mentis-Auth read proof; the key never leaves the process. Without a signer the client reads public segments only. When no signer is passed, the client builds one from MENTISDB_READ_KEY_FILE, MENTISDB_READ_AGENT_ID and MENTISDB_READ_KEY_ID if they are set. See Reading a private chain.

from pymentisdb import MentisDbClient, ReadSigner

client = MentisDbClient(read_signer=ReadSigner.from_file("builder.key", "builder", "builder-202610"))

See the PyPI listing and the pymentisdb/ folder for the full API surface, typed relations, context bundles, and a working LangChain example.

CLI Subcommands

Since 0.11 the mentisdb binary is a complete command-line client for everything the MCP tools, the REST API and the web dashboard can do. Commands are mentisdb <group> <command> [options]; mentisdb --help lists them all and every command has --help with copy-paste examples. docs/CLI_PARITY.md maps every MCP tool, REST route and dashboard action to its command.

GroupCommands
thoughtappend, retro, get, genesis, traverse, recent, standing, candidates
searchranked (default), lexical, filter, federated, bundles
chainlist, head, bootstrap, branch, merge, info, delete, access show|verify|admin|set|allow|deny
agentlist, get, registry, upsert, describe, alias, key generate|add|revoke, disable, activate, copy
entity-typelist, upsert
memoryexport, import, extract (MEMORY.md style Markdown)
skillguide, manifest, list, search, read, versions, upload, deprecate, revoke, delete, diff
webhooklist, register, delete
vectorsenable, disable, sync, rebuild
daemonhealth, version, flush, restart, settings list|set
migratestatus, run [--dry-run], verify, retry, skip, rollback, purge-backups (see Chain Migrations)
localsetup, wizard, add, backup, restore, bearertoken, cert, key generate|show
mentisdb chain bootstrap "Project Atlas memory" --chain atlas
mentisdb thought append "Use UTC everywhere" --chain atlas --type Decision --tag time
echo "deploy finished" | mentisdb thought append - --chain atlas --type Summary --role Checkpoint
mentisdb search "why UTC" --chain atlas --type Decision --limit 5
mentisdb thought standing --chain atlas
mentisdb memory export --chain atlas > MEMORY.md
mentisdb chain delete scratch --yes --pin 123456

Memory and registry commands use the running daemon's REST API at --url (default http://127.0.0.1:9472, bearer token from --token or MENTISDB_BEARER_TOKEN). Dashboard-only and operator actions use the PIN-gated dashboard API at --dashboard-url (default https://127.0.0.1:9475, PIN from --pin or MENTISDB_DASHBOARD_PIN); operator commands also run with --offline [--data-dir DIR] directly against the data directory while no daemon holds it. Read commands accept --read-key-file, --read-agent and --read-key-id for private chains. Arguments are validated before any request, --json prints compact JSON, - reads content from standard input, and destructive commands need --yes. backup, restore, bearertoken and cert work on the data directory and do not need the daemon.

The original quick commands remain:

add — Add a thought

Adds a new thought to a chain. Use it for quick notes, scripted entries, or piping data into MentisDB.

mentisdb add "The sky is blue"
mentisdb add "Session fact" --scope session --tag important
mentisdb add "Insight" --type insight --agent my-agent
OptionDescription
--typeThought type, case- and separator-insensitive (insight, Insight, fact-learned, and fact_learned all work). Defaults to fact-learned when omitted
--scopeMemory scope: user, session, or agent
--tagAdd a tag (repeatable)
--agentAgent ID for the thought
--chainChain key (uses daemon default if omitted)
--urlDaemon REST URL (default: http://127.0.0.1:9472)

search — Search memories

Searches thoughts using the same ranked retrieval engine as the REST API and MCP tools. Returns JSON with score breakdowns.

mentisdb search "cache invalidation"
mentisdb search "performance" --limit 5 --scope session

Pipe results through jq for scripting:

mentisdb search "deploy" --limit 20 | jq '.hits[].thought.content'
OptionDescription
--limitMaximum results (default: 10)
--scopeFilter by memory scope: user, session, or agent
--chainChain key (uses daemon default if omitted)
--urlDaemon REST URL (default: http://127.0.0.1:9472)

agents — List registered agents

Shows agent IDs, display names, status, and thought counts. Useful for auditing which agents have written to your MentisDB instance.

mentisdb agents
mentisdb agents --chain my-project
OptionDescription
--chainChain key (uses daemon default if omitted)
--urlDaemon REST URL (default: http://127.0.0.1:9472)