spec v0.1

Open Specification

Memory for
AI agents
that actually works.

A structured workspace for language models. Markdown files, frontmatter metadata, and a directory convention any LLM can read, write, and reason about.

Markdown-first Human-readable Version-controlled No vendor lock-in

Not a framework.
A convention.

Brain Protocol defines how an AI agent's memory should be organized on disk. No databases, no vector stores, no proprietary formats. Just directories and markdown.

A brain is a git repository. Everything the agent knows — about people, projects, tasks, history — lives in structured markdown files with frontmatter metadata. The agent reads them on boot, writes during sessions, commits the diff.

01 //

Plain text only

Every piece of memory is a readable markdown file. Open it in any editor, grep it, version it.

02 //

Git is the database

Memory has history. Diff two sessions, revert a bad decision, audit what the agent changed.

03 //

Structured metadata

Frontmatter provides machine-readable context: type, tags, relationships, timestamps.

04 //

LLM-agnostic

Works with Claude, Gemini, GPT, Mistral — any model that can read a directory.

The directory layout.

brain/
├── wiki/ // entities: people, companies, projects, tech
│  └── projects/client-x/index.md
├── diary/ // temporal log — what happened and when
│  └── 2026/03/02.md
├── todo/ // open tasks
├── inbox/ // incoming — to be processed
├── boot/ // system config: identity, agents, tools
└── tools/ // API wrappers and automation scripts
---
type: project
tags: [web, laravel, client]
status: active
created: 2026-01-15
relates_to: [people/mario-rossi, companies/acme]
---
 
# Project content in plain markdown...

Works with any LLM.

If it can read a file, it speaks Brain Protocol.

Claude Gemini GPT-4o Mistral Llama Any model →