Many software repositories today include an AGENTS.md. It is a small, deliberate file that explains how an agent should behave inside a codebase. It captures constraints, priorities, and non-negotiables. Agents are fast, capable, and useful, but they are also unreliable. Without something written down, they drift.
A HUMANS.md applies the same idea to a person.
It is not a diary. It is not a list of goals, affirmations, or aspirations. It is a technical specification for our character. A document to consult when a decision feels ambiguous, to see whether it violates the invariants defined when thinking clearly. Not to search for motivation, but to recover intent.
Often, this work falls to memory. Values, principles, and past lessons are expected to surface at the right moment, without prompting. But biological memory is a lossy storage system. It is optimized for survival, not consistency. Under fatigue, stress, or fear, what tends to persist is what helps in the moment, not what reflects longer-term intent. Memory has no version history. It cannot easily show how a present decision diverges from conclusions reached years earlier under very different conditions.
A HUMANS.md captures what memory tends to compress away: a small set of principles meant to survive convenience, the mental models that help interpret situations consistently, and the lessons that only became clear after consequences arrived. It exists to preserve clarity across different versions of the same person.
As life unfolds, the document changes. New experiences introduce new constraints. Old rules are refined or removed. The value is not in fixing an identity in place, but in leaving a trail of reasoning that does not disappear as circumstances change.
The deeper effect of writing something like this is not discipline or rigidity. It is a reduction in cognitive friction. Many difficult moments are hard not because the options are unclear, but because values are being renegotiated under pressure. A HUMANS.md shifts that negotiation to a quieter moment, when there is space to think without urgency.
Over time, this creates continuity. Fewer internal debates about what matters. Less energy spent justifying choices after the fact. Decisions feel steadier, not because they are easy, but because the frame they sit in was already considered.
AGENTS.md exists to keep systems aligned as they evolve. HUMANS.md borrows the same idea, for moments when we drift.