# Open Reasoning Format > A file-based memory format for AI coding agents to preserve reusable lessons, traps, and validated paths without vector databases or server infrastructure. - **Category**: - **Canonical URL**: https://designpattern.fyi/open-reasoning-format/ --- ## Description A file-based memory format for AI coding agents to preserve reusable lessons, traps, and validated paths without vector databases or server infrastructure. ## Additional Notes **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 | Approach | Problem | |---|---| | Large RAG / vector systems | Adds embedding pipelines and retrieval infrastructure | | Single giant memory file | Loads too much irrelevant context; hard to maintain | ### 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: ```text / └── experiences/ ├── INDEX.md └── / └── EXP--.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) ```yaml --- id: "EXP--" title: "" description: "" domain: "" keywords: [keyword1, keyword2] complexity: "low" | "medium" | "high" created_at: "YYYY-MM-DD" --- ``` ### Step 2 — Body Sections ```markdown ## 1. Objective ## 2. The Trap ## 3. Abstracted Insight > **Core Principle:** ## 4. Validated Path ## 5. Verification Checklist - [ ] ``` > **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: | Step | Action | What the Agent Learns | |---|---|---| | **1** | List categories | Which experience domains exist | | **2** | Read frontmatter for a category | Which specific lessons may match | | **3** | Read one full experience | The full trap, insight, path, and checklist | **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 ```bash # 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 ```bash 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: | Influence | What ORF Borrows | |---|---| | **Reasoning Bank** | Store abstracted heuristics and named traps, not raw trajectories | | **Open Knowledge Format** | Use Markdown + YAML frontmatter as a portable, Git-native representation | | **Agent Skills** | Use progressive disclosure so agents load summaries before full detail | 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 | Capability | ORF | Vector DB / RAG Memory | Monolithic Memory File | |---|---|---|---| | **Infrastructure** | Filesystem only | Embeddings + vector store | Filesystem only | | **Retrieval** | Metadata-first progressive disclosure | Semantic top-k retrieval | Everything loads | | **Human review** | Git-native Markdown | Often opaque or indirect | Git-native text | | **Write path** | Structured agent-created experiences | Usually separate ingestion | Manual edits | | **Best fit** | Small-to-medium lessons learned stores | Large unstructured corpora | Small stable context | > **ORF is strongest** when the memory unit is a reusable operational lesson: a trap, fix, command sequence, framework gotcha, or validated debugging path. --- ## Strengths | Strength | Detail | |---|---| | **No infrastructure** | Adoption can be as small as adding a folder, a skill, and a Python script | | **Git-native** | Experience records can be diffed, reviewed, blamed, reverted, and discussed in PRs | | **Token-aware** | Retrieval is staged so agents do not load every past lesson into context | | **Trap-oriented** | The format optimizes for recognizing recurring failure modes, not just matching topics | | **Agent-writable** | Memory can compound over repeated task execution instead of remaining a static document | ## Limitations | Limitation | Detail | |---|---| | **Early draft** | v0.1.0 should be treated as experimental | | **Abstraction quality not guaranteed** | Agents may still record overly specific lessons despite the schema | | **Staleness unresolved** | Validated paths can decay as dependencies, tools, and platforms change | | **Deduplication undefined** | Overlapping or conflicting experiences need human or future-tool consolidation | | **Team sharing still open** | Cross-repo experience distribution is not yet fully specified | --- ## 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**.