BRAIN.md

BRAIN.md provides a persistent memory layer for software projects, designed to address the challenge of AI agents forgetting prior context, decisions, and rationale in ongoing development workflows. It operates by storing structured decision-grade knowledge in a dedicated local Markdown folder, which is intended to be version-controlled alongside the project repository. This enables both human developers and AI coding agents to recall past trade-offs, conclusions, and project history without repeatedly re-explaining context in new sessions or chats. The system is organized around a brain/ directory containing several fixed root pages—such as background, architecture, flow, mindmap, stack, and roadmap—that capture project-wide perspectives. These pages are updated as the project evolves, with their version history managed through git. More granular knowledge is stored in pages within brain/pages/, each representing a unit of understanding in categories like decision, concept, project, person, or reference. Each page maintains a compiled_truth section, reflecting the current authoritative answer, and a timeline section that records a chronological chain of evidence, decisions, reversals, and notes. Updates to the compiled_truth and timeline are performed atomically to preserve the integrity of the historical record. BRAIN.md is accessed and maintained through a zero-dependency command-line interface that runs on plain Node.js, requiring no installation from npm, no background services, and no additional runtime components. The CLI enforces structural conventions, ensuring that all knowledge entries are correctly formatted and traceable. Cross-references between pages use a wiki-link syntax, and a dedicated lint-links command verifies the validity of these links. The protocol entry point is a single BRAIN.md file at the project root, which signals to any compatible coding agent how to interact with the brain directory. The tool is designed for both AI reasoning agents and human collaborators who need authoritative, reviewable project memory that persists across machines, agents, and time. All data remains local and is managed as plain files, emphasizing transparency and portability. Pricing and licensing details are not specified in the available information.