DEV Community

Patrick
Patrick

Posted on

Why Your AI Agent Is Inconsistent (It's a Loading Order Problem)

#aiagents #devops #productivity #programming

Every time your AI agent starts a session, it loads context — SOUL.md, memory files, task state. The order matters more than you think.

If your agent loads user preferences before loading current task state, user data might override task constraints. If it loads yesterday's memory before today's, stale patterns win.

Why Agents Seem "Inconsistent"

Most agent inconsistency isn't the model hallucinating — it's nondeterministic context loading. Same query, different load order, different answer.

Common causes:

  • Glob patterns that don't guarantee file order
  • Memory files loaded in filesystem order (which varies by OS)
  • Race conditions when multiple files update simultaneously
  • Missing boot sequence definition in SOUL.md

The Fix: Explicit Boot Sequence

In your SOUL.md, define the exact load order:

## Boot Sequence
1. Load SOUL.md (identity, constraints)
2. Load USER.md (user preferences)
3. Load memory/YYYY-MM-DD.md (today's context, then yesterday's)
4. Load MEMORY.md (long-term distilled memory)
5. Load current-task.json (active task state)
6. Load outbox.json (pending outputs)
Enter fullscreen mode Exit fullscreen mode

Each file has a priority. Later loads can reference earlier ones but shouldn't override core constraints.

The Constraint Hierarchy Rule

Think of context loading like CSS specificity:

  • SOUL.md = base styles (lowest specificity, never overridden)
  • USER.md = component styles
  • Daily memory = page styles
  • current-task.json = inline styles (highest specificity for task scope)

A user preference should never override a SOUL.md safety rule. A task instruction should never override your identity constraints.

Explicit hierarchy prevents accidental overrides.

Implementation 

// current-task.json
{
  "task": "analyze market data",
  "constraints_from_soul": ["never modify production data", "escalate if uncertain"],
  "user_preferences": {"output_format": "bullet_list"},
  "session_budget": {"max_steps": 20, "max_runtime_seconds": 300}
}
Enter fullscreen mode Exit fullscreen mode

The constraints field is copied from SOUL.md during task initialization. Even if USER.md says "be brief," the agent knows its hard limits aren't negotiable.

The Consistency Test

Want to verify your agent is consistent? Run the same task prompt 5 times with a fresh context load each time. If you get materially different results, your context loading is nondeterministic.

Fix the boot sequence. Add explicit ordering. Test again.

Consistency is a loading problem before it's a model problem.

The full boot sequence template and context hierarchy patterns are in the Ask Patrick Library — updated nightly with real configs from running agents.

Top comments (0)