Reference

Configuration reference

Core-engine environment variables, greatmemory.toml keys, operational flags, and feature toggles.

Engine configuration reference

This page configures gm-server, the Meivo memory framework. The built-in enterprise gateway and control panel are separate services with their own GM_INGEST_* settings. In particular, a model provider configured in the control panel does not silently replace the engine's fact-extraction/reflection configuration.

Precedence

Configuration is layered in this order:

command flags  >  GM_* environment variables  >  greatmemory.toml  >  defaults

• gm-server serve accepts host, port, data-directory, config, and feature flags.
• gm-server mcp accepts data-directory and config flags.
• greatmemory.toml is read from the current directory when present. --config <path> selects an explicit file, which must exist.
• Unknown TOML keys and invalid values fail startup.

Booleans accept 1/0, true/false, yes/no, and on/off case-insensitively.

Runtime and storage

The main document/vector store is SQLite or Postgres with pgvector. MySQL is not a main-store option.

Engine audit delivery

In integrated mode, mutations are recorded through a durable outbox and reconciled to the gateway. Read events use a bounded asynchronous queue and can be dropped under sustained overload. Monitor audit_backlog_count, audit_backlog_oldest_age_secs, and audit_read_tier_dropped_count from GET /v1/stats.

For a local engine without the gateway:

GM_AUDIT_MODE=standalone gm-server serve

For the packaged path, set both the URL and the shared token from a secret manager.

Embeddings, extraction, and reflection

openai means an endpoint that implements the expected OpenAI-compatible /chat/completions or /embeddings contract. Compatibility, authentication, model names, quotas, and data handling still depend on the selected provider.

Local Ollama example:

GM_EMBEDDER=ollama \
GM_EMBEDDER_URL=http://127.0.0.1:11434 \
GM_EMBEDDER_MODEL=nomic-embed-text \
GM_EMBEDDER_DIM=768 \
GM_LLM=ollama \
GM_LLM_URL=http://127.0.0.1:11434 \
GM_LLM_MODEL=llama3 \
GM_AUDIT_MODE=standalone \
gm-server serve

OpenAI-compatible example:

GM_EMBEDDER=openai \
GM_EMBEDDER_URL=https://approved-provider.example/v1 \
GM_EMBEDDER_API_KEY="$EMBEDDING_API_KEY" \
GM_EMBEDDER_MODEL=approved-embedding-model \
GM_EMBEDDER_DIM=1536 \
GM_LLM=openai \
GM_LLM_URL=https://approved-provider.example/v1 \
GM_LLM_API_KEY="$LLM_API_KEY" \
GM_LLM_MODEL=approved-chat-model \
gm-server serve

The returned embedding length must exactly match GM_EMBEDDER_DIM. Changing the model or dimension requires a controlled re-embedding/migration plan; existing vectors do not become compatible automatically.

Provider-specific deployment notes:

• Google Vertex AI
• Amazon Bedrock
• Azure OpenAI
• Local engine quickstart

Retrieval, graph, and memory features

The three higher-level features also have command flags:

gm-server serve \
  --disable-reflection \
  --disable-usefulness \
  --disable-trust

• Reflection is enabled by default but does nothing with GM_LLM=none.
• Usefulness changes ranking only after an application submits used chunk ids to POST /v1/feedback.
• Trust gating uses provenance and known pattern checks. It is not a complete malicious-content detector.
• Graph expansion is off by default. Start with one hop and evaluate precision.
• MySQL is supported only as a separate graph backend.

Complete greatmemory.toml example

All keys are optional:

host = "127.0.0.1"
port = 7437
data_dir = "./.greatmemory"
# db = "postgres://gm:password@localhost:5432/greatmemory"
db_assume_pgvector = false
db_pool_size = 10
# hnsw_max_scan_tuples = 60000

cors_origins = ["http://localhost:3000"]
api_keys = ["internal-agent:replace-with-a-secret"]

audit_scope = "all"          # all | mutations-only
audit_mode = "standalone"    # integrated | standalone
# ingest_audit_url = "http://gm-ingest-svc:8080/v1/audit/engine-events"
# ingest_internal_token = "replace-with-a-secret"
graph_expand_hops = 0

[embedder]
kind = "fastembed"           # fastembed | ollama | openai
# base_url = "http://127.0.0.1:11434"
# api_key = "replace-with-a-secret"
# model = "nomic-embed-text"
# dim = 768

[llm]
kind = "none"                # none | ollama | openai
# base_url = "http://127.0.0.1:11434"
# api_key = "replace-with-a-secret"
# model = "llama3"

[rerank]
kind = "none"                # none | noop | lexical

[graph]
backend = "store"            # store | sqlite path | postgres URL | mysql URL

[cards]
semantic_linking = false

[features]
reflection = true
usefulness = true
trust = true

Direct-engine auth versus enterprise identity

GM_API_KEYS protects the direct engine with shared bearer secrets. Any valid engine key can address every space; spaces are not authorisation boundaries. The built-in enterprise gateway is the user-facing path for local/LDAP identity, roles, and ACL-derived retrieval filters.

When exposing gm-server beyond loopback:

• set named API keys and store them in the customer's secret manager;
• terminate TLS at a trusted reverse proxy or load balancer;
• restrict network paths so users cannot bypass the enterprise gateway;
• set exact CORS origins;
• monitor audit backlog/drop counters;
• rotate keys by overlapping old and new values during a restart.