Skip to main content

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
FilePurpose
rlmx.yamlModel provider, budget limits, context loading, storage, and session settings
SYSTEM.mdOverride the default RLM paper system prompt — edit only if you know what you are doing
CRITERIA.mdOutput criteria appended to the system prompt (e.g., “Be concise”, “Cite file paths”)
TOOLS.mdCustom 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.
FieldDescription
providerProvider name: google, anthropic, openai, etc.
modelModel ID (provider-specific)
sub-call-modelOptional 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.
FieldDescription
extensionsFile extensions to include (default: [".md"])
excludeDirectory/file patterns to skip (default: ["node_modules", ".git", "dist"])

budget

Safety limits to prevent runaway costs.
FieldDescription
max-costMaximum USD spend per run. null = unlimited.
max-tokensMaximum total tokens per run. null = unlimited.
max-depthMaximum 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.
FieldDescription
enabledEnable caching. Can also use --cache flag per-invocation.
retentionshort or long — maps to provider-specific TTL behavior.
ttlTTL in seconds (optional, provider-specific).
expire-timeISO 8601 timestamp for Google explicit caching (optional).
session-prefixPrepended 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.
FieldDescription
thinking-levelControls reasoning depth: minimal, low, medium, high
google-searchEnable web_search() battery in REPL
url-contextEnable fetch_url() battery in REPL
code-executionEnable server-side Python execution alongside local REPL
media-resolutionPer-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:
PrioritySourceExample
1 (highest)CLI flags--max-cost 0.10
2Project rlmx.yamlbudget.max-cost: 0.50
3Global settings~/.rlmx/settings.json
4 (lowest)Hardcoded defaultsmax-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.
FilePurposeOverrides rlmx.yaml section
SYSTEM.mdSystem prompt for the RLM loopsystem:
TOOLS.mdCustom Python toolstools:
CRITERIA.mdOutput criteriacriteria:
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:
VariableProvider
GEMINI_API_KEYGoogle Gemini
ANTHROPIC_API_KEYAnthropic
OPENAI_API_KEYOpenAI
GROQ_API_KEYGroq
XAI_API_KEYxAI
OPENROUTER_API_KEYOpenRouter
Keys set via rlmx config set are injected into process.env before any command runs, so they behave identically to environment variables.