Last week, someone leaked the Claude Code source. I spent a couple hours reading it, and one detail clicked in a way I wasn’t expecting: Claude Code loads CLAUDE.md and the current git state at session start.

That’s the trick. Before Claude Code writes a single line of code, it already knows the project conventions, recent commits, and current branch state. The LLM starts warm. It doesn’t have to rediscover context — it arrives with it.

I immediately thought: we should do this for robots.

But as I started building it, I realized the right question wasn’t “how do we give robots a CLAUDE.md?” It was: why isn’t AGENTS.md — or any of the other AI context file proposals out there — enough?

What AGENTS.md actually is

AGENTS.md, CLAUDE.md, and similar proposals are static configuration files. You write them. They tell an AI system how to behave: conventions to follow, tools available, rules to respect. They’re authored once and updated when you change your mind about something.

They’re excellent at what they do. For a coding agent, knowing the project’s style guide and test conventions before writing code is genuinely valuable. This is what the CLAUDE.md lesson really is — not magic, just good engineering: give the model relevant context before it starts work.

But here’s the thing about physical robots: the most important context isn’t configuration. It’s operational history.

A robot that has been running for weeks has accumulated something no config file can capture: experience. Which hallway has an unmapped 4cm threshold. Which wheel encoder starts dropping ticks after sustained load. Which time of day the WiFi in the kitchen gets congested. None of this is in your RCAN config. None of it is in a static instructions file. It exists, if anywhere, scattered across hundreds of log lines that no one is reading.

The gap: configuration vs. operational memory

If you ask an AI assistant “what conventions does this project follow?”, AGENTS.md answers that well. But if you ask a robot brain “what should you know before you start navigating today?”, AGENTS.md has nothing useful to say.

The existing landscape doesn’t cover this gap:

ROS parameter server — current parameter state, volatile, resets on restart. No history, no distillation.

URDF/SDF — hardware description: joints, links, sensors. What the robot is, not what it’s experienced.

Event logs / black boxes — raw data. An LLM context window can’t usefully process 48 hours of raw motor telemetry. The distillation step is the entire point.

Human-maintained runbooks — someone has to write them. Goes stale. Doesn’t scale.

IEEE P2873, ISO 8373, emerging AI agent standards — focused on capability description and interoperability, not on operational memory or session-start context injection.

None of these define the loop that actually matters: raw operational history → distilled knowledge → injected context at session start → informs agent behavior → generates new operational history.

That closed feedback loop between a robot’s experience and its future decision-making is what we’re calling the ROBOT.md pattern.

What ROBOT.md contains

We implemented this in OpenCastor as a <robot-context> block injected into the dynamic section of the system prompt at the start of every brain session:

<robot-context generated="2026-04-01T09:14:22Z">
  <identity rrn="RRN-000000000001" host="bob.local"
            profile="pqc-v1" version="2026.4.1.0"/>
  <status uptime="4d 11h" loa="2"/>
  <recent-errors>
    path_planner: obstacle avoidance timeout (attempt 3/3)
    motor_controller: left_wheel encoder no-update timeout (0 ticks, 800ms)
  </recent-errors>
  <recent-commands>
    robot_navigate {"waypoint":"kitchen_a","speed":0.4}
    robot_telemetry {}
  </recent-commands>
  <memory>
    Left wheel encoder intermittent under sustained load — prefer speeds ≤0.3m/s.
    Kitchen hallway has 4cm threshold not on map — flagged for geometry update.
    autoDream distilled these from 14 navigation events (last updated 2026-04-01).
  </memory>
</robot-context>

The brain session opens with this already loaded. “Go to the kitchen” lands in a context that knows about the encoder issue and the threshold. “Why did you stop last night?” lands in a context that already has the relevant error history.

This is the CLAUDE.md lesson applied to robots — but the content is entirely different in kind. Not instructions. Not configuration. Accumulated operational knowledge.

Architecture: what gets cached, what doesn’t

One thing that took some iteration: prompt caching changes the tradeoffs here significantly.

The static section — robot identity, RCAN capabilities, tool definitions — is cache-anchored. It’s ~3,000–5,000 tokens and doesn’t change between sessions. With Anthropic’s cache_control: ephemeral, the first call writes the cache at 125% cost; every subsequent call reads it at ~10%. The breakeven is the second tool call in a session.

The <robot-context> block goes in the dynamic section — explicitly not cached. Recent errors change. Command history changes. robot-memory.md changes nightly. If we cached this, we’d be feeding the brain stale context. The context block is ~400–700 tokens. We pay full price for it on every session. That’s the right tradeoff: small, fresh, accurate is worth more than large, cheap, stale.

autoDream: the distillation loop

The memory section of the context block isn’t written by hand. It’s maintained by autoDream — a nightly distillation process that runs at 02:00 Pacific and updates ~/.opencastor/robot-memory.md.

autoDream feeds the last 24 hours of gateway event logs into a Haiku-class LLM with a distillation prompt: find durable learnings, flag degrading hardware patterns, note environmental observations, prune entries no longer supported by recent data. The result is written atomically. Typically 30–60K input tokens, $0.04–$0.07 per night at current pricing.

What ends up in the file isn’t raw logs — it’s compressed, actionable knowledge. The brain session the next morning arrives already knowing what autoDream learned while the robot was idle.

One design decision worth being explicit about: autoDream is operator tooling, not a runtime default. The AutoDreamBrain class ships in the castor package as a primitive. The nightly orchestration — when to run, which logs to read, whether to file GitHub issues — is operator configuration. We ship a reference script you adapt to your deployment. Issue filing requires CASTOR_AUTODREAM_FILE_ISSUES=1 and an explicit CASTOR_GITHUB_REPO. No defaults. The primitives are universal; the opinionated orchestration is yours to configure.

Why this matters beyond convenience

There’s a deeper point here. An AI robot that starts every session cold isn’t operating like a coherent agent — it’s operating with amnesia. It can execute individual commands correctly while missing patterns that span sessions. It will rediscover the left-wheel encoder issue on Tuesday that it encountered on Monday. It will navigate the kitchen threshold the same way it did yesterday, without knowing that yesterday didn’t go well.

The CLAUDE.md insight was: context at session start is what makes coherent behavior possible for coding agents. The same applies here, but the type of context that matters for a physical robot is fundamentally different from what matters for a software project. Configuration can’t substitute for operational history.

ROBOT.md is the pattern for that history. The RCAN spec is a natural home for formalizing it — defining a standard schema for robot-memory.md (field structure, confidence decay, versioning) so the pattern becomes interoperable across deployments, not just an OpenCastor-specific file.

What’s next

• Structured tagging for memory entries: hardware observations, environment notes, behavior patterns
• Confidence decay: entries that haven’t appeared in logs for 30 days get deprioritized
• Multi-robot context: optional peer-context block when Bob and Alex operate together
• RCAN spec proposal for robot-memory.md schema

The core pattern is in production. Every OpenCastor brain session starts warm.

---

OpenCastor is an open-source robot runtime. RCAN is the Robot Communication and Autonomy Network protocol. Source on GitHub.