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