> ## Documentation Index
> Fetch the complete documentation index at: https://docs.automagik.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> .rlmx/ directory layout, rlmx.yaml format, config commands, and settings priority.

# Configuration

RLMX uses a layered configuration system. Configuration lives in the `.rlmx/` directory at your project root.

<Warning>
  **Breaking change (v0.260331+):** RLMX now requires the `.rlmx/` directory layout. Projects using the old flat-file `rlmx.yaml` in the project root must re-run `rlmx init` to migrate.
</Warning>

## `.rlmx/` directory

Run `rlmx init` to scaffold the config directory. Choose a template with `--template default` (general-purpose) or `--template code` (code analysis).

```text theme={"dark"}
.rlmx/
├── rlmx.yaml       # Main configuration (model, budget, context, storage)
├── SYSTEM.md        # System prompt used by the RLM loop
├── CRITERIA.md      # Output criteria for quality checks
└── TOOLS.md         # Custom Python tools exposed to the RLM
```

| File          | Purpose                                                                                 |
| ------------- | --------------------------------------------------------------------------------------- |
| `rlmx.yaml`   | Model provider, budget limits, context loading, storage, and session settings           |
| `SYSTEM.md`   | Override the default RLM paper system prompt — edit only if you know what you are doing |
| `CRITERIA.md` | Output criteria appended to the system prompt (e.g., "Be concise", "Cite file paths")   |
| `TOOLS.md`    | Custom Python functions injected into the REPL namespace                                |

## `rlmx.yaml`

The primary config file inside `.rlmx/`. Run `rlmx init` to scaffold one with inline comments.

```yaml theme={"dark"}
# Model configuration
model:
  provider: google                            # pi/ai provider: google, anthropic, openai, etc.
  model: gemini-3.1-flash-lite-preview        # Model ID
  sub-call-model: gemini-3.1-flash-lite-preview  # Model for llm_query() sub-calls (optional)

# System prompt — the RLM paper prompt is used by default.
# Override only if you know what you're doing.
# system: |
#   Custom system prompt here...

# Custom Python tools injected into the REPL namespace
tools:
  search_docs: |
    def search_docs(keyword):
        """Search context for files matching keyword."""
        matches = [item for item in context if keyword.lower() in item['content'].lower()]
        return [m['path'] for m in matches]

  summarize_chunk: |
    def summarize_chunk(text, max_words=100):
        """Summarize a chunk using an LLM sub-call."""
        return llm_query(f"Summarize in {max_words} words:\n{text}")

# Output criteria appended to the system prompt
criteria: |
  - Be concise and direct
  - Cite specific file paths when referencing code
  - Use code blocks for code snippets

# Context loading configuration
context:
  extensions:
    - .md
    - .ts
    - .js
  exclude:
    - node_modules
    - .git
    - dist

# Budget limits (null = unlimited)
budget:
  max-cost: null         # Maximum USD per run
  max-tokens: null       # Maximum total tokens per run
  max-depth: null        # Maximum recursive rlm_query depth

# Tool level: core, standard, or full
tools-level: core

# Cache/CAG configuration
cache:
  enabled: false          # Enable provider-level prompt caching
  retention: long         # short | long — maps to provider TTL strategy
  ttl: 3600              # seconds (optional, provider-specific)
  expire-time: ""        # ISO 8601 (optional, for Google explicit caching)
  session-prefix: ""     # Prepended to content hash for cache key

# Gemini 3 native features (silently ignored on non-Google providers)
gemini:
  thinking-level: null         # minimal | low | medium | high
  google-search: false         # Enable web_search() battery in REPL
  url-context: false           # Enable fetch_url() battery in REPL
  code-execution: false        # Enable server-side Python execution
  media-resolution:
    images: auto               # low | medium | high | auto
    pdfs: auto
    video: auto

# Structured output (Gemini only — other providers use FINAL() fallback)
output:
  schema:
    type: object
    properties:
      answer:
        type: string
      confidence:
        type: number
```

## Config sections explained

### model

Controls which LLM provider and model RLMX uses. Supports any provider available in [pi/ai](https://github.com/nickarora/pi-ai).

| Field            | Description                                                                 |
| ---------------- | --------------------------------------------------------------------------- |
| `provider`       | Provider name: `google`, `anthropic`, `openai`, etc.                        |
| `model`          | Model ID (provider-specific)                                                |
| `sub-call-model` | Optional model for `llm_query()` sub-calls. Defaults to `model` if omitted. |

### system

The system prompt sent to the LLM. Defaults to the exact RLM paper prompt, which includes research-backed guidance on decomposition, tool use, and iterative reasoning. Override only if you have a specific need.

The system prompt supports a `{custom_tools_section}` placeholder that RLMX replaces with your custom tool definitions.

### tools

Custom Python functions injected into the REPL namespace. Each key is the function name, and the value is the Python source code.

Custom tools have access to:

* `context` — the loaded context variable
* `llm_query()` — make LLM sub-calls
* All standard Python builtins

### criteria

Quality and format criteria appended to the system prompt. Use this to control output style without touching the core system prompt.

### context

Controls how files are loaded when `--context` points to a directory.

| Field        | Description                                                                   |
| ------------ | ----------------------------------------------------------------------------- |
| `extensions` | File extensions to include (default: `[".md"]`)                               |
| `exclude`    | Directory/file patterns to skip (default: `["node_modules", ".git", "dist"]`) |

### budget

Safety limits to prevent runaway costs.

| Field        | Description                                                      |
| ------------ | ---------------------------------------------------------------- |
| `max-cost`   | Maximum USD spend per run. `null` = unlimited.                   |
| `max-tokens` | Maximum total tokens per run. `null` = unlimited.                |
| `max-depth`  | Maximum recursive `rlm_query` nesting depth. `null` = unlimited. |

<Warning>
  Without budget limits, a complex query with recursive sub-calls can get expensive. Set `max-cost` for production use.
</Warning>

### cache

Controls provider-level context caching (CAG mode). See [Cache Mode](/rlmx/cache) for the end-to-end flow and [Batch Mode](/rlmx/batch) for bulk usage patterns.

| Field            | Description                                                 |
| ---------------- | ----------------------------------------------------------- |
| `enabled`        | Enable caching. Can also use `--cache` flag per-invocation. |
| `retention`      | `short` or `long` — maps to provider-specific TTL behavior. |
| `ttl`            | TTL in seconds (optional, provider-specific).               |
| `expire-time`    | ISO 8601 timestamp for Google explicit caching (optional).  |
| `session-prefix` | Prepended to the content hash for the cache session ID.     |

### gemini

Gemini 3 native features. All are opt-in and silently ignored on non-Google providers.

| Field              | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| `thinking-level`   | Controls reasoning depth: `minimal`, `low`, `medium`, `high` |
| `google-search`    | Enable `web_search()` battery in REPL                        |
| `url-context`      | Enable `fetch_url()` battery in REPL                         |
| `code-execution`   | Enable server-side Python execution alongside local REPL     |
| `media-resolution` | Per-type token cost control for images, PDFs, and video      |

### output.schema

JSON Schema for structured output. On Google providers, this is enforced via the API. On other providers, RLMX falls back to `FINAL()` text parsing.

***

## Global settings

Global settings are stored at `~/.rlmx/settings.json` and managed with `rlmx config` commands.

```bash theme={"dark"}
# Set an API key
rlmx config set GEMINI_API_KEY your-key

# Set a default provider
rlmx config set model.provider google

# View all settings
rlmx config list

# Show settings file path
rlmx config path
```

See the [CLI Reference](/rlmx/cli/reference#rlmx-config) for the full list of config commands and keys.

## Priority order

Settings are resolved highest-priority first:

| Priority    | Source              | Example                 |
| ----------- | ------------------- | ----------------------- |
| 1 (highest) | CLI flags           | `--max-cost 0.10`       |
| 2           | Project `rlmx.yaml` | `budget.max-cost: 0.50` |
| 3           | Global settings     | `~/.rlmx/settings.json` |
| 4 (lowest)  | Hardcoded defaults  | `max-iterations: 30`    |

***

## `.rlmx/` companion files

The `.rlmx/` directory includes companion Markdown files alongside `rlmx.yaml`. These files let you keep long-form content (prompts, tools, criteria) out of the YAML file.

| File          | Purpose                        | Overrides `rlmx.yaml` section |
| ------------- | ------------------------------ | ----------------------------- |
| `SYSTEM.md`   | System prompt for the RLM loop | `system:`                     |
| `TOOLS.md`    | Custom Python tools            | `tools:`                      |
| `CRITERIA.md` | Output criteria                | `criteria:`                   |

If both the Markdown file and the corresponding `rlmx.yaml` section are present, the Markdown file takes precedence.

### TOOLS.md format

Custom tools defined as `## heading` + Python code block:

```markdown theme={"dark"}
## search_docs

` ``python
def search_docs(keyword):
    """Search context for files matching keyword."""
    matches = [item for item in context if keyword.lower() in item['content'].lower()]
    return [m['path'] for m in matches]
` ``
```

<Tip>
  You can inline tools directly in `rlmx.yaml` under the `tools:` section, or keep them in `TOOLS.md` for readability. Same applies to `system:` / `SYSTEM.md` and `criteria:` / `CRITERIA.md`.
</Tip>

***

## Environment variables

API keys can also be set as environment variables instead of using `rlmx config set`:

| Variable             | Provider      |
| -------------------- | ------------- |
| `GEMINI_API_KEY`     | Google Gemini |
| `ANTHROPIC_API_KEY`  | Anthropic     |
| `OPENAI_API_KEY`     | OpenAI        |
| `GROQ_API_KEY`       | Groq          |
| `XAI_API_KEY`        | xAI           |
| `OPENROUTER_API_KEY` | OpenRouter    |

Keys set via `rlmx config set` are injected into `process.env` before any command runs, so they behave identically to environment variables.