agent-brain

저장소 인덱싱 및 그래프 구축

agent-brain은 저장소의 소스 파일을 안전하게 읽고, .env, 키, 시크릿, vendor, node_modules과 같은 금지된 경로를 건너뛰며 코드 구조와 계약을 추출합니다. 이를 통해 SQLite에 메타데이터를 쓰고 Neo4j에 저장소, 파일, 함수, 메서드, 구조체, 인터페이스, 테스트, 계약, 레이어 등의 그래프 노드를 작성합니다.

컴팩트한 컨텍스트 팩 생성

생성된 컨텍스트 팩에는 컨텍스트 효율성 신호가 포함되어 있으며, indexed_files, returned_files, files_avoided, estimated_tokens_saved, recommended_agent_action 등을 제공하여 에이전트가 처음에 어떤 파일을 열어볼지 판단하도록 돕습니다. 기본 예산은 ‘cavernicola’로, 최소한의 토큰과 상위 파일만 포함하며, 필요 시 ‘standard’ 또는 ‘deep’ 예산을 사용할 수 있습니다.

MCP 서버 통합

agent-brain은 로컬 stdio MCP 서버로 실행되어 AI 코딩 에이전트가 저장소를 탐색하는 데 토큰을 낭비하지 않고 직접 컴팩트한 프로젝트 컨텍스트를 요청할 수 있도록 합니다. Codex, Cursor, Claude, Copilot 등과 같은 에이전트에 대한 설치 스크립트를 제공하며, 각 에이전트의 구성 파일에 MCP 서버를 등록합니다.

다운로드·설치 방법

소스 코드로부터 설치하려면 다음 명령을 사용합니다:

go install github.com/NanoCycles/agent-brain/cmd/agent-brain@latest

또는 Makefile을 통해 빌드할 수 있습니다:

make build

GitHub 릴리즈로부터 설치하려면 다음 스크립트를 실행합니다:

curl -fsSL https://raw.githubusercontent.com/NanoCycles/agent-brain/main/scripts/install.sh | sh

Windows PowerShell에서는 다음 명령을 사용합니다:

iwr https://raw.githubusercontent.com/NanoCycles/agent-brain/main/scripts/install.ps1 -UseB | iex

Windows에서 Chocolatey 커뮤니티 패키지를 사용할 경우 (승인 후):

choco install agent-brain -y

npm을 통해 전역 설치도 가능합니다:

npm install -g @nanocycles/agent-brain

기본 사용법/명령어

저장소에서 처음 실행하는 일반적인 흐름은 다음과 같습니다:

agent-brain init
agent-brain up
agent-brain index --repo .
agent-brain status

작업 태스크를 준비하려면:

mkdir -p .ai/tasks
echo "# TICKET-123nnDescribe the bug or feature here." > .ai/tasks/TICKET-123.md
agent-brain prepare --task .ai/tasks/TICKET-123.md --budget cavernicola

Jira 연동을 사용할 경우:

agent-brain jira import https://your-site.atlassian.net/browse/AK-123
agent-brain prepare --task .ai/tasks/AK-123.md

에이전트 컨텍스트를 생성하고 사용하려면:

agent-brain agent-start --task .ai/tasks/TICKET.md
# 에이전트는 .ai/context/.agent.md를 읽거나 agent-brain agent-start가 출력한 프롬프트를 사용
# 코드 변경 후
agent-brain review-diff
agent-brain memory-proposal --task .ai/tasks/TICKET.md

이런 경우에 유용합니다

대규모 저장소에서 작업하는 개발자가 AI 코딩 에이전트(Codex, Cursor, Claude, Copilot 등)를 사용할 때, agent-brain은 에이전트가 관련 없는 파일을 탐색하는 데 토큰을 낭비하지 않도록 도와줍니다. 저장소의 구조와 의존성을 사전에 분석하여 에이전트가 먼저 보아야 할 파일을 정확히 제시함으로써, 버그 수정 또는 기능 구현 작업에서 더 정확하고 빠른 코드 변경을 가능하게 합니다. 특히 Neo4j 그래프를 통해 변경 영향도를 분석하거나, 과거의 설계 결정을 기억하여 유사한 실수를 방지하는 데 유용합니다.

지원 환경·시스템 요구사항

Windows, macOS, Linux에서 실행 가능하며, 각 프로젝트마다 독립된 환경을 유지합니다. Docker가 로컬에서 실행 중이어야 하며, Neo4j 컨테이너는 프로젝트별로 별도의 포트에서 실행되어 서로 간섭이 발생하지 않습니다. Go 1.22+는 개발 환경에서만 필요하며, 배포된 바이너리는 단일 실행 파일로 제공됩니다.

최신 버전·업데이트

현재 버전은 0.1.3이며, 릴리스 노트는 제공된 증거에 명시되지 않았습니다. 업데이트 정보는 GitHub 저장소의 릴리스 페이지를 참조하십시오.

제한 사항·확인 사항

에이전트가 MCP 서버를 사용할 경우, IDE가 올바른 프로젝트 폴더에서 MCP 서버를 launch하지 않으면 Docker 연결 오류가 발생할 수 있습니다. 이 경우 해당 저장소 내에서 다시 설치 스크립트를 실행하고 IDE를 재시작해야 합니다. 또한, 기본 Neo4j 비밀번호는 로컬 개발용이며, 외부 네트워크에 포트를 노출해서는 안 됩니다.