brain.md의 개요
brain.md는 코딩 에이전트가 프로젝트에 대해 잊으면 안 되는 것을 적어 두기 위한 규약이자 도구입니다. brain init을 실행하면 프로토콜 파일 BRAIN.md, brain/ 폴더, 그리고 CLAUDE.md와 AGENTS.md에 표시된 블록이 추가되어 어떤 에이전트에게든 사용법을 알려 줍니다. 각 페이지는 decision, concept, reference 등 여섯 가지 범주 중 하나에 속하고, 다시 쓸 수 있는 현재 요약과 추가만 가능한 근거 타임라인을 가지며, 모든 쓰기는 brain CLI를 거치므로 형식이 깨지지 않습니다.
네 가지 스킬이 이를 움직입니다. brain-setup은 프로젝트를 준비하고 연결하며, brain-bootstrap은 코드, 문서, git log 또는 사용자 인터뷰로 첫 페이지 초안을 쓰고, brain-page는 읽기와 쓰기 안내서이며, brain-ingest는 대화나 문서를 brain에 반영합니다. Claude Code와 Codex용 선택형 SessionStart 훅은 세션이 시작될 때마다 페이지 색인을 에이전트에 건넵니다.
CLI는 의존성 없는 Node.js 스크립트로, MindMux가 npm에 @mindmux/brain-md라는 이름으로 Apache 2.0 라이선스로 배포합니다. 저장소는 2026년 6월에 만들어졌고 v0.4.2는 2026년 11월 13일에 나왔습니다.
brain.md, 쓸 만한 가치가 있습니까?
발상은 타당하고 범위는 정직합니다. brain.md는 에이전트가 하는 일을 모두 기록하려 하지 않습니다. 6개월 뒤에도 중요하고 코드에서 읽어 낼 수 없는 것만 남기고, 그 이해가 바뀔 때는 흔적을 남기라고 요구합니다. update-truth는 페이지 요약을 다시 쓰면서 같은 한 번의 쓰기로 타임라인 항목을 추가하므로, 뒤집힌 결정도 사라지지 않고 기록이 남습니다.
뒤에 있는 코드는 많지 않으며, 이것이 매력이자 한계입니다. CLI와 설치 도구를 합쳐 의존성 없는 JavaScript 약 1,750줄이고, 여기에 스킬 파일 네 개와 테스트가 있습니다. 검색 명령은 없습니다. 에이전트는 페이지를 ID, 제목, 범주로 나열하고 관련 있어 보이는 것을 읽는데, 수십 페이지까지는 되지만 수백 페이지가 되면 어려워집니다. 기록은 에이전트가 BRAIN.md를 따르는지에 달려 있습니다. claude-mem이나 ai-memory와 달리 세션을 자동으로 기록하는 장치가 없어서, 바쁜 에이전트는 그냥 잊을 수 있습니다.
훅은 절제되어 있습니다. Codex SessionStart 훅은 페이지 색인만 보내며 상한은 8 KiB, 실행 시간은 5초이고, CLI가 실패하면 조용히 끝납니다. Node 18과 POSIX 셸이 필요하므로 네이티브 Windows는 제외됩니다. 훅에는 절대 경로가 들어 있어 프로젝트를 옮기면 다시 설치해야 합니다. brain은 저장소 안에 있으므로 저장소에 접근할 수 있는 사람은 누구나 읽을 수 있는데, 그것이 바로 목적이면서 비밀 정보를 넣지 말아야 할 이유이기도 합니다.
채택은 아직 적습니다. 별 722개, 기여자 9명, 11월 19일까지 30일간 npm 다운로드 814건입니다. 이미 아키텍처 결정 기록을 쓰는 팀에게 brain.md는 에이전트가 관리하도록 지시받는 형식을 하나 더하는 것이고, 아무것도 기록하지 않는 팀에게는 부담 없는 첫걸음입니다.
제 역할을 하는 곳
에이전트가 이미 정한 설계 선택을 자꾸 다시 꺼내는 3인 팀
새 방식을 제안하기 전에 에이전트가 과거 결정을 읽게 하고 싶음
brain init을 실행한 뒤 brain-bootstrap 스킬로 git log에서 결정 페이지 초안을 만듭니다. CLAUDE.md 블록이 작업을 시작할 때마다 관련 페이지를 불러오라고 에이전트에 지시합니다. 무료이며 페이지는 코드 리뷰에도 나타납니다.
한 저장소에서 Claude Code와 Codex를 번갈아 쓰는 개발자
세션 시작 시 두 에이전트에 같은 프로젝트 지식을 주고 싶음
brain install-hooks와 brain install-hooks --agent codex로 두 에이전트의 SessionStart 훅을 설치합니다. 각 세션은 최대 8 KiB의 페이지 색인을 받고, 필요할 때 전체 페이지를 읽습니다.
도입 전 확인할 점
- 설정
- npm install -g @mindmux/brain-md를 실행하고, brain setup -y로 감지된 각 에이전트에 스킬을 복사한 뒤, 프로젝트에서 brain init을 실행합니다. Node 18 이상이 필요합니다.
- 연동
- Claude Code, Codex, Cursor, Pi용 에이전트 스킬, Claude Code와 Codex용 SessionStart 훅이 있으며, AGENTS.md나 CLAUDE.md를 읽는 에이전트라면 프로토콜을 따를 수 있습니다. MCP 서버는 없습니다.
- 데이터와 개인정보
- 페이지는 저장소의 brain/ 폴더나 brainRoot로 지정한 경로에 Markdown으로 있으며, CLI는 아무 데도 아무것도 보내지 않습니다. 에이전트가 쓴 내용은 저장소에 접근할 수 있는 모든 사람에게 보입니다.
- 제한
- 검색과 임베딩이 없습니다. Codex 훅 스냅샷은 8 KiB와 5초가 상한입니다. 훅은 절대 경로를 담고 있어 이동 후 다시 설치해야 합니다. 네이티브 Windows 셸은 지원하지 않습니다.
좋은 점
- 저장소 안의 평범한 Markdown으로 코드와 함께 버전 관리
- 추가 전용 타임라인이 결정을 바꾼 이유를 보존
- 의존성 없는 CLI, 호스팅할 것이 없음
- 부트스트랩 스킬이 코드와 git log로 첫 페이지 초안 작성
아쉬운 점
- 검색이 없어 에이전트가 페이지 목록을 훑어야 함
- 기록이 에이전트가 쓰는 것을 기억하는지에 달림
- 훅에 POSIX 셸 필요, 네이티브 Windows 미지원
- 작은 프로젝트: 기여자 9명, 월 npm 다운로드 814건
추천 대상
Claude Code나 Codex가 아키텍처 결정과 제약을 저장소에 남기고, 사람이 풀 리퀘스트에서 검토할 수 있는 형식을 원하는 소규모 팀에게 맞습니다.
brain.md 대안
brain.md: 자주 묻는 질문
- brain.md, 쓸 만한 가치가 있습니까?
- brain.md는 왜 그런 결정을 했는지 에이전트가 적어 두게 하는 깔끔한 방법이지만, 규칙이 더 엄격하고 잘 관리된 문서 폴더 이상의 일은 거의 하지 않습니다. 평점은 5점 만점에 3.4점입니다.
- brain.md의 가격은 얼마입니까?
- Apache 2.0 라이선스로 무료입니다. 서비스나 계정이 필요 없습니다.
- brain.md의 단점은 무엇 입니까?
- 검색이 없어 에이전트가 페이지 목록을 훑어야 함; 기록이 에이전트가 쓰는 것을 기억하는지에 달림; 훅에 POSIX 셸 필요, 네이티브 Windows 미지원; 작은 프로젝트: 기여자 9명, 월 npm 다운로드 814건.
- brain.md에 적합한 사람은 누구입니까?
- Claude Code나 Codex가 아키텍처 결정과 제약을 저장소에 남기고, 사람이 풀 리퀘스트에서 검토할 수 있는 형식을 원하는 소규모 팀에게 맞습니다.
- brain.md에 회사 데이터를 맡겨도 안전합니까?
- 페이지는 저장소의 brain/ 폴더나 brainRoot로 지정한 경로에 Markdown으로 있으며, CLI는 아무 데도 아무것도 보내지 않습니다. 에이전트가 쓴 내용은 저장소에 접근할 수 있는 모든 사람에게 보입니다.
- brain.md의 가장 좋은 대안은 무엇입니까?
- 저희가 리뷰한 것 중 가장 가까운 대안은 ai-memory, claude-obsidian 및 OpenWiki입니다.
답변 확인일: 2026년 11월 20일.