Hosting

Docker

The fastest way to self host, with a local embedding model built in.

llms.txt

The fastest way to self-host. The image bundles the local Candle embedding model, so semantic search works with zero config and no API key. The model downloads on first start. It is also built with the bedrock feature, so the same image runs on AWS with Bedrock extraction and embeddings on the task role.

Run it

Terminal
docker run -p 6677:6677 -v mentedb-data:/var/mentedb/data ghcr.io/nambok/mentedb:latest

The container serves the REST API on port 6677, and the named mentedb-data volume persists the database at /var/mentedb/data. That is all you need for storage and semantic recall. gRPC listens on 6678; publish it too if you use it. The image runs the maintenance sweep every 24 hours by default, with nothing to schedule.

Non-root user and volumes

The image runs as a non-root user, uid and gid 10001, with its home at /var/mentedb. A named volume picks up that ownership automatically; for a bind mount, give the directory to that user first:

Terminal
mkdir -p ./data && sudo chown 10001:10001 ./data
docker run -p 6677:6677 -v "$PWD/data:/var/mentedb/data" ghcr.io/nambok/mentedb:latest

The local embedding model (about 90 MB) downloads on first start into /var/mentedb/.cache/huggingface. Mount a volume at /var/mentedb/.cache to skip the download when the container is recreated. Files you mount in, such as TLS certificates or a JWT public key, must be readable by uid 10001.

Health check

The image has a Docker HEALTHCHECK that calls GET /v1/ready on port 6677 every 30 seconds (5 second timeout, 60 second start period, 3 retries), so docker ps and orchestrators that read Docker health see when the server can take traffic. It tries plain HTTP and then HTTPS, so it works with TLS on or off without an override:

Terminal
docker run -p 6677:6677 -p 6678:6678 \
  -v mentedb-data:/var/mentedb/data \
  -v /etc/mentedb/tls:/tls:ro \
  -e MENTEDB_TLS_CERT_FILE=/tls/fullchain.pem \
  -e MENTEDB_TLS_KEY_FILE=/tls/privkey.pem \
  ghcr.io/nambok/mentedb:latest

Orchestrators that run their own probes should point liveness at /v1/live and readiness at /v1/ready, and set the stop timeout a few seconds above MENTEDB_SHUTDOWN_DRAIN_SECS (default 10) so a SIGTERM drains and closes cleanly.

Image tags

Release images are tagged with the version (for example 0.43.0), the short commit (sha-1a2b3c4) and latest, and carry the OCI labels org.opencontainers.image.revision, version and source. Pin production to a version tag. The image is built with cargo build --locked (exactly the dependency versions in Cargo.lock) on base images pinned by digest.

Docker Compose

YAML
services:
  mentedb:
    image: ghcr.io/nambok/mentedb:latest
    ports:
      - "6677:6677"
    volumes:
      - mentedb-data:/var/mentedb/data

volumes:
  mentedb-data:

Turn on LLM fact extraction

Semantic search works out of the box. To also extract facts, detect contradictions, and run consolidation, pass an LLM provider and the --auto-extract flag:

Terminal
docker run -p 6677:6677 -v mentedb-data:/var/mentedb/data \
  -e MENTEDB_LLM_PROVIDER=anthropic \
  -e MENTEDB_LLM_API_KEY=sk-ant-... \
  ghcr.io/nambok/mentedb:latest mentedb-server --port 6677 --data-dir /var/mentedb/data --auto-extract

MENTEDB_LLM_PROVIDER accepts openai, anthropic, ollama, or bedrock (bedrock needs a server built with --features bedrock; the Docker image includes it). Running on AWS? See AWS Bedrock for Claude with no API key.