Configuration

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

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.

`.rlmx/` directory

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

.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.

# 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.

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.

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

cache

Controls provider-level context caching (CAG mode). See Cache Mode for the end-to-end flow and Batch Mode 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.

# 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 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:

## 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]
` ``

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.

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.

​Configuration

​.rlmx/ directory

​rlmx.yaml

​Config sections explained

​model

​system

​tools

​criteria

​context

​budget

​cache

​gemini

​output.schema

​Global settings

​Priority order

​.rlmx/ companion files

​TOOLS.md format

​Environment variables

Configuration

`.rlmx/` directory

`rlmx.yaml`

Config sections explained

model

system

tools

criteria

context

budget

cache

gemini

output.schema

Global settings

Priority order

`.rlmx/` companion files

TOOLS.md format

Environment variables