An open standard · v0.2

reality.md — a memory file for your life, not just your repo

Every AI harness already reads an instruction file before touching a codebase — CLAUDE.md, AGENTS.md, .cursorrules. Codebases got a memory layer. People didn't. So every session starts with you re-explaining yourself to a brilliant amnesiac.

reality.md is one file in your home directory that tells any agent who you are and what you're building — so every agent on your machine works for your life, not just your repo.

~/reality.md — the contract. You write it, agents read it.

~/soul.md — the inner contract. Why, and who you are being.

~/.reality/ — the state. Agents maintain it, you review it. (Or reality/ inside your notes vault.)

No SaaS. No account. No lock-in. A markdown file, readable by every harness that exists.

reality.md Standard Specification Blueprint

Eight sections, eight levers

Each section is an intervention point in a working model of how outcomes happen: attention → belief → action → environment → feedback → outcome. An empty section isn't a failure — it's your gap, found. (The assessment tells you which one.)

## Identity

Who is acting — the roles every action votes for.

## Aims

What's being built. Specific, written, with if-then triggers.

## Attention

What signal agents surface to you, and what they mute.

## State

The conditions you act from — sleep, deep-work windows, non-negotiables.

## Systems

What is already systemized: agents, supervised automations, and review loops.

## Environment

The defaults you've engineered. What's been removed.

## Feedback

Review cadence and the metrics that count.

## Guardrails

What agents must never do on your behalf.

The agent protocol — five verbs

What makes this a standard rather than a note: any agent that finds your reality.md knows exactly how to behave.

1
READ — Load reality.md before acting on the human's behalf.
2
SURFACE — Filter inputs against Aims and Attention — signal forward, noise muted.
3
PROPOSE — Recommend the smallest next action that votes for the Identity.
4
LOG — Append outcomes to .reality/ — wins, reviews, never silently.
5
GUARD — Refuse anything that violates the Guardrails.

New in v0.2

soul.md
The inner contract beside reality.md: purpose, values, the “I am” lines, the scene, gifts, vows, gratitude, and the voice your agents use with you. Meaning, kept separate from mechanism.
Vault mode
Keep everything in a visible reality/ folder inside Obsidian or any notes app, so it syncs to your phone. Agents find it through REALITY_HOME.
Witness, snapshots, decisions
A ledger kept as fact, meaning and action; snapshots sealed only with your approval; decisions with review dates. Every field labeled desired, reported, planned, done or meaning.
The Agent Charter
Twelve articles for any AI that supports a person's life: propose, never impose; never certify causation; never blame; consent before memory or sharing.

Reality Studio writes all of it for you, on your device, and exports an Obsidian-ready folder.

Adopt it in two minutes

1. Copy the template from the repo into ~/reality.md and fill what you know. Leave the rest empty — empty is a map.
2. Add one line to your harness's instruction file (CLAUDE.md, .cursorrules, GEMINI.md):
Read ~/reality.md before acting on my goals; follow its agent protocol.
3. Ask your agent: "Read my reality.md. What's the smallest next action?" — and watch it answer like it knows you. Because now it does.

Get the spec + template →

The spec is MIT — extend it, fork it, build tools on it. The name stays generic on purpose: standards survive their authors. The method that fills the file is the Architect's Loop, and it's free too.

Get the reality.md field guide

The full walkthrough for filling all eight sections — with the agent prompts that maintain it for you.

Run the assessment Implementation options