mindmuxai/brain.md

What it solves

Coding agents often lose critical context—such as the reasoning behind a specific architectural decision, project constraints, or rejected alternatives—once a chat session ends. This project provides a durable, persistent memory layer that lives directly in the project repository, ensuring that knowledge is preserved across different agents, machines, and sessions.

How it works

It establishes an agent-agnostic standard for capturing project knowledge as plain Markdown files. The system consists of a zero-dependency Node CLI that acts as the sole writer to ensure data integrity.

Key mechanisms include:

• BRAIN.md: A protocol file that tells any agent how to use the brain.
• Compiled Truth & Timeline: Each knowledge page contains a current "compiled truth" (the best current understanding) and an append-only timeline that records every change and the evidence behind it.
• CLI-Driven Updates: To prevent malformed edits, all reads and writes are performed through the brain CLI rather than manual editing.

Who it’s for

Developers using AI coding agents (such as Claude Code, Cursor, or Codex) who want to maintain a long-term, version-controlled knowledge base for their software projects.

Highlights

• Repo-native: Knowledge is stored as Markdown and tracked via Git, making it portable and independent of any specific tool.
• Agent-agnostic: Any agent capable of reading files can follow the BRAIN.md protocol.
• Tamper-evident: The combination of atomic writes and append-only timelines ensures that understanding can never change without a trace.
• Automated Seeding: Includes a bootstrap skill to seed the brain by analyzing existing code, documentation, and git logs.