Config System

Package matrix/neo/internal/config holds Neo's runtime configuration. The locked operational contract -- context-budget thresholds, loop discipline, and the execution surface -- comes from the frozen design spec at neo/neo.frozen.kvx and is encoded as Default() values. Deployment wiring (models, cortex location, the daemon URL used for core_execute delegation) is overlaid from an optional runtime .kvx file and then from environment variables, so a fresh checkout runs with zero config.

Source files: neo/internal/config/config.go, neo/internal/config/kvx.go.

---

Design decisions

Precedence: Default < runtime .kvx < environment. A fresh checkout runs with zero config. Deployment-specific values (models, cortex location, daemon URL) are overlaid without touching source.

Frozen spec defaults. The Default() function encodes the locked operational contract from neo.frozen.kvx. Changing these values changes the spec; they are not merely "sensible defaults."

Missing .kvx is non-fatal. Load("/nonexistent/neo.kvx") returns defaults with no error. This lets dev/CLI runs work unchanged.

---

Config struct

type Config struct {
    // --- identity / runtime wiring ---
    AgentName      string // human label, "Morpheus" (the market identity)
    CortexRoot     string // root dir of the cortex brain
    CortexActor    string // actor scope for Neo's memory store
    DaemonURL      string // base URL of the MCL daemon
    ManifestPath   string // agent manifest declaring MCP servers
    SkillsRoot     string // skills corpus root
    SelfModelGraph string // self-model graph path

    // --- models (provider-qualified ids) ---
    MainModel           string // the conversational tool-calling loop
    CheapModel          string // compaction + summary validation + cheap relation-classify
    ConsolidationModel  string // durable-learning extraction (stronger than CheapModel)
    EmbedModel          string // semantic page-fault embeddings
    CassandraModel      string // cheap/fast Cassandra completeness auditor
    CassandraEscalateModel string // stronger second-opinion for low-certainty audits

    // --- memory budget (context window = RAM; cortex = disk) ---
    ContextWindowTokens    int  // total model context window
    SoftPct                int  // cooperative compaction threshold (default 80)
    HardPct                int  // forced compaction threshold (default 92)
    RetrievalTopK          int  // page-fault: top-K cortex records (default 8)
    RetrievalBudgetTokens  int  // token ceiling for retrieved records (default 6000)
    PinnedBudgetTokens     int  // pinned block ceiling (default 2000)
    AmbientRetrievalTopK   int  // ambient memory seed per turn (0 = fully tool-driven)
    FirstTurnRelevancePush bool // push relevance-matched memory on turn 1
    WarmOnOpen             bool // warm embedder + HNSW on first HTTP request

    // --- loop discipline ---
    StepBudget               int  // max tool-call iterations per turn (default 50)
    StepBudgetMin             int  // adaptive floor (0 = adaptation disabled)
    StepBudgetMax             int  // adaptive ceiling (defaults to StepBudget)
    NoProgressStall           int  // identical-failing-call count that trips stall (default 4)
    SemanticStallSimilarityPct int // word-overlap % for semantic stall detection (0 = disabled)
    MaxRetriesPerTool         int  // recovery ladder rung 1 (default 3)
    MaxAdaptAttempts          int  // recovery ladder rung 2 (default 2)
    MaxGuidanceNudges         int  // consecutive system-guidance nudge cap (0 = unbounded)

    // --- sub-agent swarm ---
    MaxSubagents           int  // hard cap per spawn_subagents call
    MaxConcurrentSubagents int  // semaphore: how many run at once
    SubagentStepBudget     int  // per-sub-agent step budget

    // --- browser filmstrip ---
    BrowserAutoshot     bool // auto-capture after view-changing actions
    BrowserAutoshotMax  int  // max captures per run
    MediaRetentionHours int  // media GC sweep age (0 = disabled)

    // --- task supervisor ---
    SuperviseTasks     bool          // master switch: wrap turns in persistent supervisor
    TaskMaxWall        time.Duration // hard wall-clock ceiling for one supervised task
    TaskAttemptTimeout time.Duration // ceiling for a single supervised attempt
    TaskMaxRespawns    int           // max fresh-agent respawns before honest partial

    // --- self-model death consolidation ---
    DeathConsolidateEvery int // cadence for self-authoring failure-pattern pass

    // --- procedural memory guards ---
    MinPatternSuccesses int // successes before a pattern is injected (default 3)

    // --- cassandra 2.0 (silent-voice controller) ---
    CassandraEnabled          bool
    CassandraMinStep          int  // first step a mod may fire (default 2)
    CassandraMaxModsPerTurn   int  // total modifications per turn (default 3)
    CassandraLoopThreshold    int  // repeat count that arms doubt side
    CassandraCooldownSteps    int  // min steps between same-trigger mods (default 2)

    // --- epistemic core ---
    EpistemicPremises           bool // premise ledger + check-before-act gate
    EpistemicPredictions        bool // prediction-carrying dispatch
    EpistemicMismatchLimit      int  // consecutive mismatch count for revision (default 3)
    EpistemicConvergenceWindow  int  // actions without evidence growth (default 4)

    // --- heartbeat ---
    HeartbeatInterval int // recurring-alarm interval in minutes (0 = disabled)

    // --- MCP tool result cache + parallel dispatch ---
    MCPCacheTTL            time.Duration // TTL for idempotent-read cache (0 = disabled)
    ToolDispatchConcurrency int          // concurrent independent tool calls (0 = serial)

    // --- automatrix (proactive surprise tasks) ---
    AutomatrixEnabled             bool
    AutomatrixBaseIntervalMinutes int
    AutomatrixJitterMinutes       int
    AutomatrixMaxTasksPerDay      int
    AutomatrixMinConfidence       float32
    NtfyServer                    string
    NtfyTopic                     string
    AppriseURL                    string

    // --- execution surface ---
    NaturalAllow    []string // reversible actions
    EscalateActions []string // money-moving actions

    // --- LLM transport ---
    GatewayURL string // optional metered gateway
    ActorDID   string // actor DID for gateway headers
}

---

Loading

cfg, err := config.Load(path) // path may be "" or missing

Precedence

1. Default() - frozen spec values
2. Runtime .kvx file, overlays defaults
3. Environment variables, highest precedence

Environment variables

---

.kvx format

The Matrix .kvx convention (mirrors tachyon/internal/config/kvx.go):

# comment
[section]
key = "string"            # double-quoted strings
num = 50                  # bare ints
list = ["shell", "git"]   # bracketed, comma-separated, quoted

[section.sub]
ref = "${ENV_VAR}"        # ${ENV} interpolated from process env

Features:

• Comments stripped (respecting quoted strings)
• Later duplicate keys win
• ${ENV} interpolation
• String values are ALWAYS double-quoted (Matrix .mtx lexer convention)

---

Execution surface helpers

func (c Config) IsEscalateAction(action string) bool

Checks whether the named action crosses the wall into MCL (requires a user wallet signature).

func (c Config) SoftBudgetTokens() int // ContextWindowTokens * SoftPct / 100
func (c Config) HardBudgetTokens() int // ContextWindowTokens * HardPct / 100

---

Modifying config