MindMemOS Deployment & Configuration Guide

August 2, 2026 · View on GitHub

1. Overview

MindMemOS uses a uv workspace to manage three core Python packages, organized into server, client, and evaluation layers:

Applications / Agents ──────────────┐
Agent Plugins ───── CLI ─────────────┼──> mindmemos_sdk ── HTTP ──> mindmemos
mindmemos_eval ──────────────────────┘

mindmemos is the core server-side algorithm package. It provides FastAPI endpoints, memory and Skill workflows, model calls, data persistence, and asynchronous tasks.
mindmemos_sdk provides the Python SDK and CLI for applications and plugins. It calls mindmemos over HTTP without depending on server internals.
mindmemos_eval is an independent evaluation package. It uses mindmemos_sdk to call the service, load datasets, run evaluations, and aggregate results.

The main runtime-related directories are:

.
├── src/
│   ├── mindmemos/          # Core server package
│   ├── mindmemos_sdk/      # Python SDK and mindmemos CLI
│   └── mindmemos_eval/     # Benchmark evaluation tools
├── config/
│   ├── mindmemos/          # Server runtime and authentication configuration
│   ├── mindmemos_eval/     # Evaluation task configuration
│   └── presets/            # Algorithm preset resources
├── dockers/                # Qdrant, Neo4j, Kafka, and observability components
├── plugins/                # Agent plugin integrations
├── Makefile                # Entry points for local services and dependencies
└── pyproject.toml          # uv workspace and development dependencies

The primary configuration entry points are:

Scope	Configuration File	Description
`mindmemos`	`.env`	Docker dependencies, service ports, and connection addresses.
`mindmemos`	`config/mindmemos/dev.yaml`	Server models, databases, pipelines, and runtime configuration.
`mindmemos`	`config/mindmemos/api_keys.yaml`	API keys, `project_id`, memory algorithms, and access permissions.
`mindmemos`	`config/presets/*.json`	Memory algorithm presets.
`mindmemos_sdk`	`~/.mindmemos/settings.json`	SDK and CLI connection information and default user.
`mindmemos_eval`	`config/mindmemos_eval/*.yaml`	Evaluation models, datasets, concurrency, and algorithm configuration.

2. Minimal Startup Flow

cp .env.example .env
cp config/mindmemos/dev.example.yaml config/mindmemos/dev.yaml

# Edit .env and config/mindmemos/dev.yaml, then start the service.
make dev-setup
make dev

Default addresses:

FastAPI: http://127.0.0.1:8000
API Docs: http://127.0.0.1:8000/docs
Qdrant: http://localhost:6333
Neo4j Browser: http://localhost:7474

make dev starts the full Docker dependency stack before starting FastAPI. To start only core dependencies:

make dev-core          # Qdrant + Neo4j + Kafka
make db-observability  # Qdrant + Neo4j + Kafka + ClickHouse + OTel + Grafana

Stop local dependencies:

make dev-down

3. Required Environment Variables

Configuration file selection:

Variable	Purpose	Default
`MINDMEMOS_CONFIG_NAME`	Selects the configuration name; `dev` reads `config/mindmemos/dev.yaml`.	`dev`
`MINDMEMOS_CONFIG_PATH`	Specifies a configuration file path directly; takes precedence over `MINDMEMOS_CONFIG_NAME` when set.	Empty

Qdrant:

Variable	Purpose	Default
`MINDMEMOS_QDRANT_URL`	HTTP address used by FastAPI to access Qdrant.	`http://localhost:6333`
`MINDMEMOS_QDRANT_HTTP_PORT`	Qdrant HTTP port exposed by Docker.	`6333`
`MINDMEMOS_QDRANT_GRPC_PORT`	Qdrant gRPC port exposed by Docker; also overrides `database.qdrant.grpc_port` in the configuration.	`6334`
`MINDMEMOS_QDRANT_PREFER_GRPC`	Whether the Qdrant client prefers gRPC.	`false`
`MINDMEMOS_QDRANT_API_KEY`	Qdrant API key; can be left empty for an unauthenticated local setup.	Empty
`MINDMEMOS_GRAFANA_QDRANT_URL`	HTTP address used by the Grafana container to access Qdrant.	`http://qdrant:6333`

Neo4j:

Variable	Purpose	Default
`MINDMEMOS_NEO4J_URI`	Bolt address used by FastAPI to access Neo4j.	`bolt://localhost:7687`
`MINDMEMOS_NEO4J_HTTP_PORT`	Neo4j Browser port exposed by Docker.	`7474`
`MINDMEMOS_NEO4J_BOLT_PORT`	Neo4j Bolt port exposed by Docker.	`7687`
`MINDMEMOS_NEO4J_USERNAME`	Neo4j username; also used as the username in Docker `NEO4J_AUTH`.	`neo4j`
`MINDMEMOS_NEO4J_PASSWORD`	Neo4j password; also used as the password in Docker `NEO4J_AUTH`.	`mindmemos_dev_password`

Optional dependencies:

Variable	Purpose	Default
`MINDMEMOS_KAFKA_BOOTSTRAP_SERVERS`	Kafka address; the service starts consumers/producers only when `kafka.enabled=true` in the configuration.	`localhost:9092`
`MINDMEMOS_TELEMETRY_ENDPOINT`	OTel HTTP endpoint; telemetry is reported only when `telemetry.enabled=true` in the configuration.	`http://localhost:4318`
`MINDMEMOS_CLICKHOUSE_USER` / `MINDMEMOS_CLICKHOUSE_PASSWORD` / `MINDMEMOS_CLICKHOUSE_DB`	ClickHouse/Grafana observability data configuration.	See `.env.example`

API bind address:

Variable	Purpose	Default
`MINDMEMOS_API_HOST`	Host used by `make dev` / `make api` to start FastAPI.	`127.0.0.1`
`MINDMEMOS_API_PORT`	Port used by `make dev` / `make api` to start FastAPI.	`8000`

4. Docker

Start local dependencies with:

docker compose --env-file .env -f dockers/docker-compose.memory.yml up -d --wait qdrant neo4j kafka kafka-ui kafka-exporter

make dev-core starts Qdrant, Neo4j, Kafka, Kafka UI, and kafka-exporter. make dev starts the full Docker dependency stack before starting FastAPI. make db remains available as a compatibility entry point for the full dependency tier and is equivalent to make db-observability.

Core services in Docker Compose:

qdrant: stores memory/entity/source vectors and payloads.
neo4j: stores graph relationships.
kafka: asynchronous task queue; it can run even when it is disabled in the default configuration.
clickhouse + otel-collector + grafana: observability stack; disable telemetry.enabled in the configuration when observability is not needed.

For local deployment, the port variables in .env must align with the connection addresses in config/mindmemos/dev.yaml. At startup, environment variables also override the following configuration fields:

database.qdrant.url
database.qdrant.api_key
database.qdrant.grpc_port
database.qdrant.prefer_grpc
database.neo4j.uri
database.neo4j.username
database.neo4j.password
kafka.bootstrap_servers
telemetry.telemetry_endpoint

5. LLM Configuration

LLMs are used for memory extraction, schema processing, dreaming, and other generation tasks. Configure chat_model_router:

chat_model_router:
  routing_strategy: simple-shuffle
  endpoints:
    - model: openai/gpt-4.1-mini
      api_key: your-api-key
      api_base: https://your-base-url/v1
      timeout: 1200
      temperature: 0.0
      num_retries: 3
      extra_body: {}

Notes:

model uses LiteLLM-style model names. OpenAI-compatible endpoints usually use openai/<model-name>.
api_base should include /v1, unless your provider explicitly documents a different format.
Do not commit api_key; keep it in the uncommitted local config/mindmemos/dev.yaml.
Multiple endpoints can be configured, and the router dispatches according to routing_strategy.

6. Embedding Configuration

Embedding must be configured. At startup, the service validates that the embedding output dimension matches the Qdrant vector dimension.

embed_model_router:
  routing_strategy: simple-shuffle
  endpoints:
    - model: openai/qwen3-embedding-4b
      api_key: your-api-key
      api_base: https://your-base-url/v1
      timeout: 600
      num_retries: 3
      dimensions: 2560
      extra_body: {}

database:
  qdrant:
    vector_size: 2560
    semantic_vector_name: semantic
    bm25_vector_name: bm25

Key points:

database.qdrant.vector_size must equal the actual output dimension of the embedding model.
If the embedding model supports custom dimensions, dimensions and vector_size must also match.
If a Qdrant collection has already been created with an old dimension, changing vector_size alone will not migrate it. For local development, run make db-clean to clear the volume and rebuild.

7. Rerank Configuration (Optional)

Rerank improves search precision by reranking retrieval candidates, but it is not required for service startup. Without an external rerank endpoint, basic add/search still works; the code uses existing recall results or fallback logic.

Configure an external reranker when needed:

rerank_model_router:
  routing_strategy: simple-shuffle
  endpoints:
    - model: openai/qwen3-reranker-4b
      api_key: your-api-key
      api_base: https://your-base-url/v1
      timeout: 600
      num_retries: 3

algo_config:
  search:
    rerank:
      enabled: true
      max_query_length: 100
      max_doc_length: 5000
      max_batch_size: 20
      max_concurrent_batches: 1
      request_timeout: 5.0
    vanilla:
      use_reranker: true
    schema_search:
      entity:
        use_reranker: true

When not using an external reranker:

rerank_model_router:
  routing_strategy: simple-shuffle
  endpoints: []

algo_config:
  search:
    rerank:
      enabled: false
    vanilla:
      use_reranker: false
    schema_search:
      entity:
        use_reranker: false

rerank is an optional enhancement. For production, stabilize Docker, LLM, and Embedding first, then add rerank.

8. Authentication Configuration

Local setup uses API keys by default:

auth:
  mode: api_key
  api_key_file: api_keys.yaml

api_key_file is resolved relative to the configuration file directory, so by default it points to config/mindmemos/api_keys.yaml. The local example includes:

dev-api-key-001: vanilla memory
dev-api-key-002: schema memory

Use this header when calling APIs:

Authorization: Bearer <api_key>

9. Minimal Checklist

Before starting, confirm at least the following:

Qdrant and Neo4j ports in .env do not conflict with services already running locally.
config/mindmemos/dev.yaml exists.
chat_model_router.endpoints[0].api_key / api_base / model are valid.
embed_model_router.endpoints[0].api_key / api_base / model are valid.
database.qdrant.vector_size equals the embedding output dimension.
If rerank is not needed, rerank_model_router.endpoints can remain empty and the related use_reranker flags should be disabled.