| 💾 Saved. d722711 k33g 8h ago | 1 | # Reference: configuration file |
| 2 | |
| 3 | > Neutral, exhaustive description of the YAML file read by `mm`. Every key is optional; a key left out keeps its built-in default. The file is decoded on top of the defaults, so unknown keys are ignored. |
| 4 | |
| 5 | ## Top-level keys |
| 6 | |
| 7 | | Key | Type | Default | Description | |
| 8 | |-----|------|---------|-------------| |
| 9 | | `provider` | string | `dmr` | Registry key of the LLM server: `dmr` or `llamacpp`. Overridden by `AGENT_PROVIDER`. | |
| 10 | | `model` | string | `huggingface.co/jetbrains/mellum2-12b-a2.5b-instruct-gguf-q4_k_m:Q4_K_M` | Model identifier in the provider's naming. Overridden by `AGENT_MODEL`. | |
| 11 | | `baseUrl` | string | `""` (provider default) | OpenAI-compatible endpoint tried first. Overridden by `AGENT_BASE_URL`. | |
| 12 | | `fallback` | string or absent | absent (provider default) | Endpoint used when `baseUrl` does not answer `/models` within 2 s. Absent = provider default; `""` = no fallback. | |
| 13 | | `apiKeyEnv` | string | `""` (provider default) | Name of the environment variable holding the API key. | |
| 14 | | `contextWindow` | int | `0` | Tokens the server serves. `0` = ask the server, else unknown. Must be ≥ 0. | |
| 15 | | `maxOutput` | int | `16000` | Maximum characters a tool returns to the model; longer output keeps its head and up to 2000 characters of tail. Must be > 0. | |
| 16 | | `maxTurns` | int | `10` | Maximum model ↔ tools round trips per question. Must be > 0. | |
| 17 | | `previewLines` | int | `20` | Lines of a command's output echoed to the terminal. `0` disables the echo. Must be ≥ 0. | |
| 18 | | `displayCommands` | bool | `false` | Print the numbered list of commands and file operations after each answer. | |
| 19 | | `system` | string | built-in prompt | The system prompt, first message of every history. | |
| 20 | | `skillsDir` | string | `skills` | Directory holding the skills, as `<name>.md` files or `<name>/SKILL.md` directories. A relative path is resolved from the directory `mm` is started in (terminal mode, or ACP mode without a config file), or next to the config file (ACP mode with one); the banner warns with the absolute path when nothing is found there. | |
| 21 | | `editTools` | bool | `true` | Declare `read_file`, `write_file`, `edit_file`. `false` leaves `bash` and `read_skill` only. | |
| 22 | | `sampling` | map | `temperature: 0.0`, `top_p: 0.9`, `max_tokens: 4096` | Generation settings, OpenAI API key names, passed to the server. The shipped `agent.yaml` adds `parallel_tool_calls: false`. | |
| 23 | | `watchdogTimeout` | duration | `20s` | Silence tolerated between two streamed tokens before the connection is declared hung. Doubled for summary requests. | |
| 24 | | `context` | map | see below | Automatic history compression. | |
| 25 | |
| 26 | ## `context` keys |
| 27 | |
| 28 | | Key | Type | Default | Description | |
| 29 | |-----|------|---------|-------------| |
| 30 | | `enabled` | bool | `false` | Turn the automatic compression on. `/compact` works regardless. | |
| 31 | | `threshold` | int | `75` | Percentage of the context window beyond which the history is compressed before the next question. Between 1 and 100. | |
| 32 | | `maxMessages` | int | `80` | Message count that triggers a compression when the window is unknown or the estimate is low. `0` disables. Must be ≥ 0. | |
| 33 | | `keepLastTurns` | int | `3` | Question turns kept raw at the end of the history. Must be ≥ 1. | |
| 34 | | `summaryMaxTokens` | int | `1200` | `max_tokens` of the summary request. Must be > 0. | |
| 35 | | `prompt` | string | `""` | Replaces the built-in summary prompt when not empty. | |
| 36 | | `showStats` | bool | `true` | Print the one-line `🗜️` report after each compression. | |
| 37 | |
| 38 | ## Provider defaults |
| 39 | |
| 40 | | Provider | `baseUrl` | `fallback` | `apiKeyEnv` | Key required | |
| 41 | |----------|-----------|------------|-------------|--------------| |
| 42 | | `dmr` | `http://localhost:12434/engines/v1` | `http://host.docker.internal:12434/engines/v1` | none | no | |
| 43 | | `llamacpp` | `http://127.0.0.1:8080/v1` | none | `LLAMA_API_KEY` | no | |
| 44 | |
| 45 | ## Validation errors |
| 46 | |
| 47 | Reported as `[config error: <path>: <message>]`, exit code 1. |
| 48 | |
| 49 | | Message | Cause | |
| 50 | |---------|-------| |
| 51 | | `provider must not be empty` | `provider: ""` | |
| 52 | | `model must not be empty` | `model: ""` | |
| 53 | | `contextWindow must be >= 0` | negative value | |
| 54 | | `maxOutput must be > 0` | zero or negative | |
| 55 | | `maxTurns must be > 0` | zero or negative | |
| 56 | | `previewLines must be >= 0` | negative value | |
| 57 | | `context.threshold must be between 1 and 100` | out of range | |
| 58 | | `context.keepLastTurns must be >= 1` | zero or negative | |
| 59 | | `context.summaryMaxTokens must be > 0` | zero or negative | |
| 60 | | `context.maxMessages must be >= 0` | negative value | |
| 61 | | `unknown provider "x" (known: dmr, llamacpp)` | Reported by the engine, as `[engine error: …]`. | |
| 62 | |
| 63 | A start-up warning, not an error, is printed when `context.enabled` is `true`, the window is unknown and `context.maxMessages` is `0`. |
| 64 | |
| 65 | ## Shipped files |
| 66 | |
| 67 | | File | Purpose | |
| 68 | |------|---------| |
| 69 | | `agent.yaml` | Docker Model Runner set-up: `provider: dmr`, `maxTurns: 40`, `displayCommands: true`, compression off, a system prompt named "Bob" that describes the skills and file-editing rules. | |
| 70 | | `agent.llamacpp.yaml` | llama.cpp set-up: `provider: llamacpp`, `baseUrl: http://127.0.0.1:8080/v1`, `fallback: ""`, compression on. | |
| 71 | |
| 72 | ### Example |
| 73 | |
| 74 | ```yaml |
| 75 | provider: llamacpp |
| 76 | model: my-alias |
| 77 | baseUrl: http://127.0.0.1:8080/v1 |
| 78 | fallback: "" |
| 79 | maxTurns: 40 |
| 80 | context: |
| 81 | enabled: true |
| 82 | ``` |