Configuration

Set parameters in a YAML file or environment variables. If a parameter appears in both, the environment variable takes precedence.

Naming rule

For an environment variable, replace dots in the parameter name with underscores and add the MNEMOS_ prefix.

database.password        →  MNEMOS_DATABASE_PASSWORD
embeddings.base_url      →  MNEMOS_EMBEDDINGS_BASE_URL
recall.min_similarity    →  MNEMOS_RECALL_MIN_SIMILARITY
consolidate.decay_half_life → MNEMOS_CONSOLIDATE_DECAY_HALF_LIFE

Required

variable	what it is
MNEMOS_DATABASE_PASSWORD	the database user's password
MNEMOS_AUTH_ISSUER_URL	your OAuth server's address
MNEMOS_AUTH_PUBLIC_URL	mnemos's public address

Both are required: there is no unauthenticated mode, and the server will not start without them.

Database

variable	default
MNEMOS_DATABASE_HOST	none — required (or MNEMOS_DATABASE_DSN)
MNEMOS_DATABASE_PORT	5432
MNEMOS_DATABASE_USER	mnemos
MNEMOS_DATABASE_NAME	mnemos
MNEMOS_DATABASE_SSLMODE	disable
MNEMOS_DATABASE_MAX_CONNS	8

Use MNEMOS_DATABASE_DSN to provide a connection string instead of the individual database parameters.

The database user needs permission to create the vector, pg_trgm and btree_gist extensions. They are installed on the first start.

Embeddings

variable	default
MNEMOS_EMBEDDINGS_BASE_URL	none — required
MNEMOS_EMBEDDINGS_MODEL	bge-m3
MNEMOS_EMBEDDINGS_DIMENSIONS	1024
MNEMOS_EMBEDDINGS_API_KEY	ollama
MNEMOS_EMBEDDINGS_TIMEOUT	30s
MNEMOS_EMBEDDINGS_MAX_CHARS	8000

Use a service with a /v1/embeddings API and 1024 dimensions. Examples for Ollama and OpenAI.

Server

variable	default
MNEMOS_SERVER_ADDR	:8090
MNEMOS_LOG_LEVEL	info
MNEMOS_LOG_FORMAT	json
MNEMOS_OBSERVABILITY_METRICS_ENABLED	true

Embedding queue

variable	default
MNEMOS_EMBED_QUEUE_WORKERS	0
MNEMOS_EMBED_QUEUE_DEPTH	1024
MNEMOS_EMBED_QUEUE_SWEEP_LIMIT	500
MNEMOS_EMBED_QUEUE_SWEEP_INTERVAL	15m

With MNEMOS_EMBED_QUEUE_WORKERS=0, processing runs during each write. A value of 2 or more enables background processing for some data. Those notes appear in search by meaning after processing completes.

Processing older notes

variable	default
MNEMOS_CONSOLIDATE_ENABLED	true
MNEMOS_CONSOLIDATE_INTERVAL	15m
MNEMOS_CONSOLIDATE_DECAY_HALF_LIFE	30d
MNEMOS_CONSOLIDATE_DECAY_FLOOR	0.05
MNEMOS_CONSOLIDATE_DEDUP_SIMILARITY	0.9

MNEMOS_CONSOLIDATE_DECAY_HALF_LIFE sets how long an unused note takes to lose half its relevance weight.

:::warning One instance per database Run one MCP server per database. For a separate HTTP API, use the api service from the installation example. :::

Search

variable	default
MNEMOS_RECALL_MIN_SIMILARITY	0.45
MNEMOS_RECALL_MAX_QUERIES	6
MNEMOS_RECALL_MAX_FACTS_PER_SOURCE	2
MNEMOS_RECALL_MAX_FACTS_PER_RELATION	3
MNEMOS_RECALL_HOP_DEPTH	2
MNEMOS_RECALL_IMPORTANCE_WEIGHT	0.15

Start with the defaults. If you change the model, check search quality with your own queries.

Configuration file

Example YAML:

database:
  host: postgres
  password: change-me
embeddings:
  base_url: http://ollama:11434/v1
  model: bge-m3
  dimensions: 1024
auth:
  issuer_url: https://auth.example.com
  public_url: https://mnemos.example.com
consolidate:
  decay_half_life: 30d

Pass the file path with --config.