YAML Config Files

The YAML configuration files baked into the Engrammic self-hosted image, and how to override them from the host.

The self-hosted Engrammic image ships with a set of YAML files that control behaviour ranging from the SAGE generation model to the names your agents see for MCP tools. These files are baked into the image, so you cannot edit them in place. Instead, the self-hosted compose mounts a host directory where you can drop replacement files that take precedence.

The override directory

The compose file mounts ~/.engrammic/config into every service and points ENGRAMMIC_CONFIG_DIR at it:

environment:
  - ENGRAMMIC_CONFIG_DIR=/app/config-override
volumes:
  - ./config:/app/config-override:ro

The ./config path resolves next to your docker-compose.yml, so for the default install it is ~/.engrammic/config. Any file you place there whose name matches a config file wins over the copy baked into the image. Files are matched by bare name, so you do not need to know where the original lives inside the container. You only add the files you actually want to change; everything else falls back to the shipped default. An empty or missing directory means all defaults apply.

For the most common changes you do not need a file at all. EMBEDDING_MODEL, EMBEDDING_DIMENSIONS, MODELS__TIER, and TELEMETRY__ENABLED are environment variables. Reach for a file override only when the setting you want has no env var, such as switching the SAGE LLM provider or editing tool descriptions. See Configuration.

Overriding a file

Create the directory

mkdir -p ~/.engrammic/config

Copy the default out of the image

Start from the shipped file so you keep the full structure:

docker run --rm --entrypoint cat \
  europe-north1-docker.pkg.dev/engrammic/releases/engrammic-api:latest \
  /app/config/models.yaml > ~/.engrammic/config/models.yaml

Adjust the path for the file you want (see the table below).

Edit it

Edit ~/.engrammic/config/models.yaml (or whichever file) to taste.

Restart the services that read it

Config is loaded once at process start, so a restart is required:

docker compose restart app dagster dagster-daemon reaction-worker

Config file reference

Use the bare filename (left column) when placing an override in ~/.engrammic/config. The in-image path is only needed for the copy-out command above.

File	In-image path	Purpose	Env shortcut
`models.yaml`	`/app/config/models.yaml`	Provider and model for SAGE synthesis (reasoning, fast, query expander, reranker) by tier. This is where the generation LLM is chosen. Default tier uses Google Vertex.	`MODELS__TIER` selects `economy`, `balanced`, or `premium`. Changing the provider requires editing this file.
`embeddings.yaml`	`/app/config/embeddings.yaml`	Embedding model and provider, vector dimensions, Qdrant collection name, batching and rate limits	`EMBEDDING_MODEL`, `EMBEDDING_DIMENSIONS`
`tags.yaml`	`/app/src/context_service/config/tags.yaml`	Auto-tagging thresholds: min/max tags, similarity thresholds, cache TTL	None
`identities.yaml`	`/app/src/context_service/config/identities.yaml`	Models, timeouts, and cron schedules for the four background workers (custodian, synthesizer, groundskeeper, validator)	None
`mcp_tools.yaml`	`/app/src/context_service/config/mcp_tools.yaml`	Names and descriptions of the MCP tools shown to connecting agents, plus the top-level MCP instructions. The most likely file to edit intentionally, for example to reword tool descriptions.	None
`mcp_presets.yaml`	`/app/src/context_service/config/mcp_presets.yaml`	ICP skill presets: tool namespaces and per-preset parameter overrides. Only relevant when adding custom skill presets.	None

reasoning_chain.yaml exists in the image but is not read at runtime. Its thresholds are controlled entirely by the REASONING_CHAIN_MATCHING__* and CHAIN_FEEDBACK__* environment variables (nested double-underscore form). Placing it in the override directory has no effect.

Configuration -- the full list of environment variables.
Running Models Locally -- a worked example that overrides models.yaml to run the LLM on Ollama.
Self-hosting guide -- compose setup, upgrade, and backup.

YAML Config Files

On this page