Configuration

Engine configuration

cortex.Config holds global defaults that apply to all agents unless overridden at the agent level:

type Config struct {
    DefaultModel         string        // LLM model (default: "smart")
    DefaultMaxSteps      int           // max reasoning steps per run (default: 25)
    DefaultMaxTokens     int           // max output tokens per LLM call (default: 4096)
    DefaultTemperature   float64       // LLM sampling temperature (default: 0.7)
    DefaultReasoningLoop string        // reasoning strategy (default: "react")
    ShutdownTimeout      time.Duration // graceful shutdown timeout (default: 30s)
    RunConcurrency       int           // max concurrent runs (default: 4)
}

Defaults

cortex.DefaultConfig() // returns:
// Config{
//     DefaultModel:         "smart",
//     DefaultMaxSteps:      25,
//     DefaultMaxTokens:     4096,
//     DefaultTemperature:   0.7,
//     DefaultReasoningLoop: "react",
//     ShutdownTimeout:      30 * time.Second,
//     RunConcurrency:       4,
// }

Overriding defaults

Pass a custom config via engine options:

eng, err := engine.New(
    engine.WithConfig(cortex.Config{
        DefaultModel:    "gpt-4o",
        DefaultMaxSteps: 50,
        RunConcurrency:  8,
    }),
    engine.WithStore(pgStore),
)

Engine options

Option	Description
`engine.WithStore(s)`	Sets the composite store (required)
`engine.WithConfig(cfg)`	Sets the engine configuration
`engine.WithExtension(ext)`	Registers a plugin extension
`engine.WithLogger(l)`	Sets the structured logger

Agent-level overrides

Each agent.Config can override engine-level defaults:

agentCfg := &agent.Config{
    Model:       "claude-3-opus",  // overrides DefaultModel
    MaxSteps:    50,               // overrides DefaultMaxSteps
    MaxTokens:   8192,             // overrides DefaultMaxTokens
    Temperature: 0.3,              // overrides DefaultTemperature
}

If an agent field is zero-valued, the engine default applies.

Extension configuration

The Forge extension wrapper has its own Config that can be set programmatically or via YAML:

type Config struct {
    DisableRoutes        bool          // prevents HTTP route registration
    DisableMigrate       bool          // prevents auto-migration on start
    BasePath             string        // URL prefix for all cortex routes
    DefaultModel         string        // LLM model (default: "smart")
    DefaultMaxSteps      int           // max reasoning steps per run (default: 25)
    DefaultMaxTokens     int           // max output tokens per LLM call (default: 4096)
    DefaultTemperature   float64       // LLM sampling temperature (default: 0.7)
    DefaultReasoningLoop string        // reasoning loop strategy (default: "react")
    ShutdownTimeout      time.Duration // graceful shutdown timeout (default: 30s)
    RunConcurrency       int           // max concurrent runs (default: 4)
    GroveDatabase        string        // grove.DB name for DI resolution
}

Extension options

Option	Description
`extension.WithStore(s)`	Sets the composite store
`extension.WithExtension(x)`	Registers a Cortex plugin extension
`extension.WithEngineOption(opt)`	Passes an engine option directly
`extension.WithConfig(cfg)`	Sets the extension configuration
`extension.WithDisableRoutes()`	Disables HTTP route registration
`extension.WithDisableMigrate()`	Disables auto-migration
`extension.WithBasePath(path)`	Sets the URL prefix
`extension.WithGroveDatabase(name)`	Sets the grove.DB to resolve from DI
`extension.WithRequireConfig(bool)`	Requires YAML config to be present

YAML configuration

Cortex supports YAML-based configuration under the extensions.cortex or cortex key in your Forge config file:

# config.yaml
extensions:
  cortex:
    disable_routes: false
    disable_migrate: false
    base_path: "/cortex"
    default_model: "gpt-4o"
    default_max_steps: 50
    default_max_tokens: 8192
    default_temperature: 0.7
    default_reasoning_loop: "react"
    shutdown_timeout: "30s"
    run_concurrency: 8
    grove_database: "cortex"

Merge behaviour

YAML values take precedence for most fields. Programmatic options fill in any gaps. Remaining zero-valued fields are filled with DefaultConfig() defaults.

Source	Priority
YAML config file	Highest
Programmatic options (`WithConfig`, etc.)	Fills zero-valued fields
`DefaultConfig()`	Fills remaining zero-valued fields

Configuration

On this page