brain-md

Persistent memory for AI agents. Open spec. Local first. Human readable.

Brain.md is an open standard and toolset that gives AI agents persistent, structured memory. Every memory is a plain markdown file on your disk — inspectable, editable, version-controllable, and portable across any AI agent.

AI agents have amnesia. Every session starts from scratch. You explain your preferences, your project context, your coding standards — and next session, it's all gone. Developers are duct-taping memory together with scattered markdown files and custom system prompts. There's no standard, no tooling, and no way to see what your agent actually knows.

A Brain is just a folder with structured markdown files and a lightweight index. Any AI agent can read and write to it. You can open any memory in VS Code, Obsidian, or a plain text editor. It works offline. You own your data.

my-brain/
├── .brain/
│   ├── config.json        # Brain configuration
│   └── index.json         # Thought index for fast queries
├── BRAIN.md               # Entry point — what this Brain is for
└── thoughts/
    ├── user/              # Who you are
    ├── context/           # What's being worked on now
    ├── decisions/         # Your preferences and choices
    ├── learnings/         # Corrections and patterns
    ├── references/        # External resources
    └── projects/          # Project knowledge

1. Copy the skill file into your Claude Code configuration:

cp skills/brain.md ~/.claude/skills/brain.md

1. Tell Claude Code to initialize a Brain:

> Initialize a Brain in this project

1. That's it. Your agent will now remember things across sessions — preferences, corrections, decisions, project context — all stored as readable markdown files.

1. Clone this repo:

git clone https://github.com/TerraByte-Dev/brain-md.git

1. Look at the [example Brain]