projectbrain.md 공식 오픈 소스 공개 - 프로젝트를 위한 지속 가능한 메모리 레이어

당신은 코딩 에이전트(coding agent)와 함께 실질적인 문제를 해결하며 오후 시간을 보냅니다. 왜 SQLite 대신 Markdown을 사용하는지, 왜 옵션 B가 제외되었는지, 이번 버전에서 "완료"가 무엇을 의미하는지 등에 대해 논의합니다. 논리적 근거는 타당하고, 트레이드오프(trade-offs)는 검토되었으며, 결정이 내려집니다.

그러고 나서 세션이 종료됩니다.

내일 새로운 세션을 열거나, 기기를 바꾸거나, Claude Code에서 Codex로 전환하면, 에이전트는 다시 똑같은 질문을 던집니다. 이 프로젝트는 무엇을 하는 것인가? 왜 B가 아닌가? 우리 이미 이걸 결정하지 않았나? 모델이 약한 것이 아닙니다. 단지 결론을 저장할 내구성이 있는 장소가 없었을 뿐입니다. 작업 결과는 코드로 살아남지만, 그 이면의 "이유(why)"는 아무도 다시 열어보지 않는 채팅 로그 속으로 증발해 버립니다.

그래서 우리는 이 빠진 조각을 위한 작은 표준을 만들었고, 이를 오픈 소스로 공개합니다: brain.md.

그것이 무엇인가

brain.md는 프로젝트에 **두뇌(brain)**를 부여합니다. 즉, 프로젝트 저장소(repo)에 존재하며 모든 세션보다 오래 지속되는 일반 Markdown 형식으로 작성된 내구성이 있는 결정 사항, 요구 사항 및 제약 조건입니다.

패키지에는 두 가지가 포함되어 있습니다:

• 계약 (A contract) — 프로젝트 루트에 있는 단일 BRAIN.md 파일로, 어떤 코딩 에이전트에게도 두뇌가 어떻게 작동하는지 알려줍니다. 에이전트는 해당 파일을 읽는 것만으로 사용법을 학습합니다.
• 툴킷 (A toolkit) — 두뇌를 구성하고 유지 관리하는 작은 brain CLI와 한 번 설치하면 되는 몇 가지 스킬(skills)입니다.

두뇌 자체는 저장소에 있는 단순한 Markdown 파일일 뿐입니다. 시작하기 전에 별도로 구축해야 할 것은 없습니다. 이는 MCP 등을 통해 두뇌를 구동하는 우리의 프로젝트 두뇌 워크벤치인 MindMux에서 발전되었습니다. brain.md는 그 아래에 있는 오픈 레이어(open layer)입니다. 즉, 파일을 읽을 수 있는 어떤 에이전트라도 MindMux를 사용하든, 에디터와 터미널만 사용하든 상관없이 사용할 수 있는 형식과 계약입니다.

두뇌가 실제로 어떻게 생겼는가

Markdown으로 구성된 brain/ 디렉토리이며, 두 가지 종류의 파일을 가집니다.

루트 페이지 (Root pages) — 프로젝트를 한눈에 파악할 수 있는 고정된 6개의 세트: background, architecture, flow, mindmap, stack, roadmap. 이것들은 오직 업데이트만 수행하게 됩니다.

Pages — 각각 하나의 지속 가능한 지식 단위입니다: 결정, 개념, 인물, 참조 사항 등입니다. 진행하면서 자유롭게 생성하면 됩니다. 제한도, 복잡한 절차도 없습니다.

페이지를 단순한 노트 이상으로 만드는 요소는 그 형태입니다. 모든 페이지는 두 가지 레이어(layer)를 가집니다:

• compiled_truth — 현재의 최선인 이해 상태이며, 전체를 다시 쓸 수 있습니다.
• timeline — 해당 이해에 도달하기까지의 과정을 기록한 추가 전용(append-only) 흔적입니다.

한 레이어는 당신이 계속 나아갈 수 있게 해줍니다. 다른 레이어는 당신이 지나온 길을 추적할 수 있게 해줍니다. 과거의 결정을 뒤집을 때, 역사를 조용히 수정하는 것이 아니라 타임라인(timeline)에 reversal을 추가합니다. 그러면 마음이 바뀐 기록이 그대로 남게 됩니다.

설계 전략: 파일과 CLI의 결합

이것들 중 어느 것도 그 자체로 완전히 새로운 아이디어는 아닙니다. AGENTS.md와 CLAUDE.md는 이미 에이전트에게 표준 지침(standing instructions)을 전달할 수 있게 해줍니다. brain.md의 전략은 더 좁고, 제 생각에는 더 유용합니다: 메모리를 구조화하고, 구조적으로 올바르게(correct by construction) 만드는 것입니다.

그 메커니즘은 다음과 같습니다. 읽기와 쓰기 모두 brain CLI를 통해 이루어집니다. 사용자가 직접 브레인(brain) 파일을 편집하는 일은 절대 없습니다. 이것이 제약처럼 들릴 수도 있겠지만, 바로 그것이 핵심입니다. CLI가 유일한 쓰기 도구이기 때문에 다음과 같은 이점이 있습니다:

• 프론트매터(Frontmatter)가 항상 생성되므로, 유효하지 않은 형태로 어긋날 일이 없습니다.
• compiled_truth를 다시 쓰고 그에 따른 timeline 항목을 추가하는 작업이 **하나의 원자적 쓰기(one atomic write)**로 수행됩니다. 따라서 이해 상태가 흔적을 남기지 않고 변경되는 일은 결코 발생할 수 없습니다.

두 번째 속성이 가장 중요합니다. 지식 베이스(knowledge base)가 부패하는 가장 흔한 방식은 조용한 편집입니다. 누군가 결론을 바꾸면 그 뒤에 숨겨진 추론 과정은 사라져 버립니다. 모든 쓰기 작업을 하나의 명령어로 통제하면, 그러한 실패 모드는 구조적으로 불가능해집니다. brain.md에는 검증기(validator)가 따로 없습니다. 검증기가 잡아낼 수 있는 오류 자체가 남지 않기 때문입니다.

실제로 무엇이 다른가

만약 유사한 도구들을 사용해 보셨다면, 다음과 같은 솔직한 차이점이 있습니다.

• 평면적인 CLAUDE.md / rules 파일과 비교 시 — 이러한 파일들은 지침(instructions)을 전달하기에는 훌륭하지만, 수동으로 관리해야 하는 하나의 거대하고 커지는 덩어리(blob)일 뿐입니다. 반면 브레인(brain)은 구조화되어 있고, 주소 지정이 가능하며(addressable), 내장된 감사 추적(audit trail) 기능을 갖춘 지식입니다. 역할 자체가 다릅니다.
• 도구 내부에 존재하는 메모리와 비교 시 — 벡터 저장소(vector store), 모델 자체의 메모리, 호스팅된 서비스 등은 당신의 지식 '위에서' 동작하는 런타임(runtime)입니다. 브레인은 그 자체인 기질(substrate)입니다. 즉, git에 저장되는 일반 파일이며, PR(Pull Request)에서 차이점(diff)을 비교할 수 있고, 사람이나 에이전트, 또는 grep으로 읽을 수 있습니다. 그 위에 런타임을 얹더라도(MindMux는 MCP를 통해 이를 수행하며, 더 많은 도구가 가능할 것입니다), 지식은 도구가 아닌 저장소(repo)에 귀속됩니다.
• 채팅 기록(chat history) 저장과 비교 시 — 채팅 기록은 '과정(process)'입니다. 브레인은 '결론(conclusion)'입니다. 모든 가공되지 않은 문장을 다시 돌려받고 싶은 것이 아니라, 나중에 다시 필요하게 될 몇 가지 판단(judgments)들을 원하는 것입니다.

또한 특정 모델이나 특정 도구에 종속되지 않습니다. 계약(contract)은 파일 형태이므로, 동일한 브레인이 Claude Code, Codex, 그리고 다음에 당신이 사용할 그 어떤 도구에서도 작동합니다.

작동 방식 확인하기

도구를 한 번 설치하세요:

./setup        # 선택한 모든 에이전트에 기술(skills)을 연결합니다 (~/.claude, ~/.codex, …)

그 후, 어떤 프로젝트에서든 에이전트가 브레인을 구성하고 초기화하며(brain-setup 실행 후 brain-bootstrap), 그 이후부터는 그냥 작동합니다. 그 결실은 세션 '전반에 걸쳐' 나타납니다:

사용자: 설정을 SQLite가 아닌 Markdown으로 저장하자 — diff를 비교하고 마이그레이션하기 더 쉬워.

에이전트: 이 세션 이후에도 유지될 수 있도록 이를 결정 사항(decision)으로 캡처하겠습니다.
...

다시 설명할 필요가 없습니다. 다음 대화는 당신이 이미 결정한 사항으로부터 시작됩니다.

직접 시도해보세요

브레인은 모델을 위한 것이 아니라 '프로젝트'를 위한 메모리입니다. 다음 달에 다른 에이전트를 연결하더라도, 남는 것은 바로 브레인입니다.

만약 이것이 당신이 겪고 있는 문제라면, 5분 정도면 그 효용을 느낄 수 있습니다:

• Repo: github.com/mindmuxai/brain.md
• Standard: projectbrain.md
• 현재 Claude Code 및 Codex와 함께 작동합니다. Apache-2.0 라이선스입니다. 이슈(Issues)와 PR(Pull Requests)을 환영합니다.

만약 가장 먼저 눈에 띄는 점이 _"이 모든 것을 다시 설명할 필요가 없었다"_라는 점이라면, 제대로 작동하고 있는 것입니다. 그것이 바로 우리가 이것을 만든 이유입니다.

원문은 MindMux Blog에 게시되었습니다.