Open Reasoning Format

Open Reasoning Format (ORF) is a file-based specification that gives AI coding agents persistent memory of past problem-solving experience. Lessons are stored as plain Markdown files under an experiences/ directory — no vector databases, no embedding pipelines, no server infrastructure required.

Why ORF Exists

The Problem

Most agent sessions start cold. Every time the context window resets, the agent re-learns the same:

• Framework gotchas
• Parser edge cases
• Command failures
• Deployment traps
• Debugging paths

This repetition wastes tokens, time, and reliability.

Existing Approaches Fall Short

The ORF Solution

ORF treats hard-won agent experience as source-controlled project knowledge. Each lesson is a small, structured playbook that records:

1. The objective that triggered the lesson
2. The trap or failure mode encountered
3. An abstracted, reusable insight
4. The validated path that worked
5. A verification checklist

Think of it as a compact technical wiki for agents — not a search system or a monolithic prompt file.

Core Architecture

All experiences live under a single project-local directory:

<project-root>/
└── experiences/
    ├── INDEX.md
    └── <domain>/
        └── EXP-<YYYYMMDD>-<sequence>.md

Key design decisions:

• No database or daemon — files are plain Markdown, readable by humans and cheap for agents to inspect.
• Git-native — every file can be diffed, reviewed, and reverted like any other source artifact.
• INDEX.md as router — lists categories with short descriptions so an agent can determine whether relevant memory exists before loading any details.

Experience File Structure

Each experience file is a Markdown document with YAML frontmatter and five mandatory sections.

Step 1 — Frontmatter (Metadata)

---
id: "EXP-<YYYYMMDD>-<sequence>"
title: "<Short, imperative title>"
description: "<When to load this experience>"
domain: "<domain-id>"
keywords: [keyword1, keyword2]
complexity: "low" | "medium" | "high"
created_at: "YYYY-MM-DD"
---

Step 2 — Body Sections

## 1. Objective
<What task triggered the experience>

## 2. The Trap
<The naive path, failure mode, error, or edge case>

## 3. Abstracted Insight
> **Core Principle:** <Reusable heuristic>

## 4. Validated Path
<The commands, edits, or steps that worked>

## 5. Verification Checklist
- [ ] <How to confirm the path still works>

Why these two sections matter most:

• The Trap makes failure modes first-class, so a future agent can match on symptoms before it even knows the fix.
• Abstracted Insight forces the lesson above a one-off execution log into a reusable rule of thumb.

How Agents Retrieve Memory (Progressive Disclosure)

ORF never loads every memory file into context. Instead, it uses a three-step retrieval pattern that is intentionally token-budgeted:

How it works in practice:

1. Inspect low-cost category metadata (cheap).
2. Scan frontmatter for one domain (cheap).
3. Load the full body only after a match is found (expensive, done once).

This mirrors the discovery pattern used by agent skills: show cheap summaries first, reveal expensive detail only after a match is confirmed.

Reference CLI

A lightweight Python CLI handles both retrieval and recording.

Retrieving Experiences

# Step 1 — See which domains have recorded experience
python3 manage-experience/scripts/experiences.py list-categories

# Step 2 — Read frontmatter for a specific category
python3 manage-experience/scripts/experiences.py get-frontmatter --category python-scripting

# Step 3 — Read a specific experience in full
python3 manage-experience/scripts/experiences.py read-experience --id EXP-20260720-0001

Recording a New Experience

python3 manage-experience/scripts/experiences.py create-experience --domain cloud-run ...

Important: create-experience writes the new file and updates INDEX.md, but does not commit anything. This is a deliberate trust boundary — new memory appears as a normal working-tree change for human review before it becomes part of the project’s knowledge base.

Packaging as an Agent Skill

ORF also packages the experience workflow as an agentskills.io-style skill named manage-experience. A compliant host can:

1. Discover the skill automatically.
2. Run retrieval at the start of a complex task.
3. Record a new experience after resolving something non-trivial.

The Two-Phase Lifecycle

Task Start                              Task End
    │                                       │
    ▼                                       ▼
Consult prior experience        Record the lesson for
via progressive disclosure      future agents to use

This feedback loop is ORF’s core goal: agent work should improve the next agent run instead of disappearing with the session.

Adoption: Step-by-Step Checklist

Follow these steps to add ORF to a project:

• Step 1 — Create experiences/INDEX.md with your initial domain categories.
• Step 2 — Add the manage-experience skill and reference CLI to the project.
• Step 3 — Configure the agent to consult ORF at the start of complex tasks.
• Step 4 — Configure the agent to record a new experience after resolving a non-obvious trap.
• Step 5 — Review experiences/ changes like source code so stale or low-quality memory does not accumulate.

Where ORF Fits: Lineage

ORF combines ideas from three adjacent formats and research directions:

ORF is a narrow format for episodic problem-solving memory — not general organizational knowledge, not a tool skill registry, and not a semantic search corpus.

Evaluation Model

ORF uses a cold-versus-warm evaluation flow to measure effectiveness:

1. Cold run — an agent attempts a task without any prior experience files.
2. Spec validation — generated experience files are checked for required frontmatter and sections.
3. Warm run — a fresh agent repeats the same task with the recorded experience available.

Early results show fewer repeated debugging steps in warm runs. Sample sizes are small, so treat findings as directional: ORF demonstrates that structured experience files can help a later agent avoid a known trap.

Compared With Alternatives

ORF is strongest when the memory unit is a reusable operational lesson: a trap, fix, command sequence, framework gotcha, or validated debugging path.

Strengths

Limitations

Bottom Line

ORF is a practical pattern for agent memory: structured, local, auditable, and cheap to query.

Its most useful idea is not the file extension or CLI, but the discipline of turning agent trial-and-error into small reusable playbooks that future agents can discover before repeating the same mistake.