Blueprints

A Minimal Cognitive OS File Structure

A practical starter file structure for making memory, workflows, agents, projects, and reviews legible.

— 1 min read

Most people begin their AI system with prompts. A better starting point is a file structure.

Files give agents something durable to inspect, update, reference, and improve. They also give humans a way to keep judgment visible.

The minimal structure

/cognitive-os
  /memory
    profile.md
    preferences.md
    decisions.md
    lessons.md
  /workflows
    research-loop.md
    writing-loop.md
    review-loop.md
  /agents
    researcher.md
    editor.md
    operator.md
  /projects
    project-name/
      brief.md
      sources.md
      drafts.md
      decisions.md
  /reviews
    weekly-review.md
    monthly-system-review.md

What each layer does

Memory stores context that should survive individual conversations. Workflows define repeatable procedures. Agents describe roles, constraints, and evaluation standards. Projects keep execution grounded. Reviews create feedback loops.

The operating principle

If an agent will need the same context twice, make it a file. If a human will need to audit the agent’s behavior, make the process legible. If a workflow should improve over time, give it a place to accumulate evidence.

This is not the final structure. It is the minimum viable filesystem for compounding cognition.

Read more