BHGBrain이란 무엇인가요?

BHGBrain은 AI 에이전트에게 영구적이고 벡터 기반의 메모리를 제공하는 오픈 소스 MCP 서버입니다. SQLite와 Qdrant에 메모리를 저장하며, 세션과 도구를 가로질러 의미, 전문, 또는 하이브리드 검색으로 검색할 수 있게 합니다.

어떤 AI 에이전트가 BHGBrain과 작동하나요?

MCP 호환 클라이언트라면 모두 됩니다 — Claude Code, Claude Desktop, OpenAI Codex, OpenClaw, Gemini 등. BHGBrain은 stdio와 HTTP 전송을 모두 지원하여 로컬 프로세스 또는 네트워크 서비스로 작동할 수 있습니다.

BHGBrain은 MEMORY.md나 세션 컨텍스트와 어떻게 다르나요?

MEMORY.md는 매 세션마다 컨텍스트에 로드되는 평면 파일로, 토큰을 소비하고 규모가 커지면 뉘앙스를 잃습니다. BHGBrain은 메모리를 메타데이터가 있는 벡터로 저장하고, 의미 검색을 통해 관련 있는 것만 검색하며, 자동으로 중복을 제거합니다 — 컨텍스트 창을 부풀리지 않고 수십만 개의 메모리로 확장됩니다.

BHGBrain을 실행하려면 GPU나 클라우드 서비스가 필요한가요?

아니요. BHGBrain은 Node.js 20+와 Qdrant 인스턴스(Docker로 쉽게 실행)가 있는 어떤 머신에서도 실행됩니다. 임베딩은 기본적으로 OpenAI의 API를 사용하거나, Ollama를 통해 nomic-embed-text 같은 로컬 모델을 사용해 완전히 오프라인으로 운영할 수 있습니다.

BHGBrain은 엔터프라이즈 사용에 안전한가요?

네. BHGBrain은 기본적으로 localhost에 바인딩되고, 루프백이 아닌 연결에는 베어러 토큰 인증을 요구하며, 로그의 비밀 정보를 마스킹하고, 메모리 저장 전 자격 증명 패턴을 스캔하며, 모든 쓰기 및 삭제 작업의 전체 감사 로그를 유지합니다.

여러 에이전트가 같은 BHGBrain 인스턴스를 공유할 수 있나요?

물론입니다. 그것이 핵심 설계입니다. 여러 MCP 클라이언트가 HTTP를 통해 같은 BHGBrain 서버에 연결하여 하나의 지식 베이스를 공유합니다. 네임스페이스 격리는 프로젝트 간 누출을 방지하면서도 네임스페이스 내에서 에이전트 간 지식 공유를 허용합니다.

BHGBrain: AI 에이전트에게 공유되는 영구 메모리를 부여하라

당신이 사용하는 모든 AI 코딩 에이전트 — Claude Code, Codex, Copilot, Gemini — 는 각 세션을 건망증으로 시작한다. 어제의 디버깅 돌파구, 지난주의 아키텍처 결정, 세 스프린트 전에 팀이 합의한 코딩 표준 — 전부 사라진다. 모든 것을 다시 설명하거나, 우연히 열려 있는 파일에서 에이전트가 추론해 주기를 바라는 수밖에 없다.

이것이 오늘날 에이전트 워크플로에서 가장 큰 마찰 지점이다. 모델 품질이 아니다. 도구 통합이 아니다. 메모리다.

BHGBrain은 우리의 답이다: AI 에이전트에게 영구적이고, 검색 가능하며, 공유되는 세컨드 브레인을 제공하는 오픈 소스 MCP 서버.

문제: 모든 에이전트는 금붕어다

실제 프로젝트에 AI 코딩 에이전트를 사용해 본 적이 있다면 이 패턴을 알 것이다:

아침 세션: 당신은 아키텍처, 제약, 관례를 설명한다. 에이전트는 훌륭한 작업을 한다.
오후 세션: 새 컨텍스트 창. 에이전트는 네 시간 전에 피하라고 했던 바로 그 패턴을 제안한다.
다음 날: 다른 에이전트(아마 백그라운드 작업을 위한 Codex)는 어제 Claude Code가 배운 것에 대해 전혀 모른다.

해결책은 취약하다:

MEMORY.md 파일은 500줄에 도달하여 매 메시지마다 컨텍스트 창의 15%를 소비할 때까지 작동한다.
시스템 프롬프트는 정적이며 진화하는 지식을 담을 수 없다.
세션 기록은 에이전트별로 다르고 검색할 수 없다.
수동 재설명은 애초에 에이전트를 사용하려고 피하려 했던 바로 그것이다.

근본적 문제: 각 에이전트는 자신만의 일시적 컨텍스트를 가지며, 어느 것도 서로 대화하지 않는다.

BHGBrain이 하는 일

BHGBrain은 MCP 서버다 — 즉, MCP 호환 AI 클라이언트라면 도구로서 연결할 수 있다. 간단한 연산 집합을 노출한다:

도구	하는 일
`remember`	자동 타입 분류, 중복 제거, 태깅과 함께 메모리 저장
`recall`	의미 검색 — 키워드가 아닌 의미로 관련 메모리 찾기
`search`	벡터 유사도와 전문 일치를 결합한 하이브리드 검색
`forget`	메모리 삭제 (감사 추적 포함)
`tag`	메모리에 태그 추가 또는 제거
`category`	영구 정책 카테고리 관리 (아키텍처, 코딩 표준 등)
`collections`	메모리를 이름이 지정된 컬렉션으로 정리
`backup`	전체 백업 생성 및 복원

내부적으로, 모든 메모리는 다음을 얻는다:

벡터 임베딩은 의미 검색을 위해 Qdrant에 저장
메타데이터와 전문 인덱스는 빠른 필터링과 키워드 검색을 위해 SQLite에 저장
자동 중복 제거 — 같은 것을 두 번 말하면 복제 대신 병합
타입 분류 — 메모리는 에피소드형(사건), 의미형(사실), 절차형(워크플로)으로 분류

쓰기 파이프라인

에이전트가 remember를 호출하면, BHGBrain은 텍스트를 데이터베이스에 그냥 쏟아붓지 않는다. 다단계 파이프라인을 실행한다:

추출 — LLM이 원시 입력을 추론된 타입, 태그, 중요도 점수가 있는 원자 메모리 후보로 분해.
결정 — 각 후보는 같은 네임스페이스의 기존 메모리와 비교된다. 시스템은 ADD(새 지식), UPDATE(기존 정제), DELETE(오래된 정보 무효화), 또는 NOOP(이미 알고 있음)로 결정.
저장 — 수용된 메모리는 임베딩되고, 인덱싱되고, 영속화.

추출 모델이 사용 불가면, BHGBrain은 콘텐츠 해시와 코사인 유사도 임계값을 사용한 결정적 중복 제거로 폴백한다. 메모리를 조용히 버리는 일은 결코 없다.

읽기 경로

에이전트가 컨텍스트가 필요하면, recall 또는 search를 호출한다:

의미 검색은 의미로 메모리를 찾는다 (“이 프로젝트에서 인증은 어떻게 작동하나?”)
전문 검색은 정확한 용어를 찾는다 (“OIDC federated credentials”)
하이브리드 검색은 Reciprocal Rank Fusion을 사용해 둘을 결합 (기본 70% 의미, 30% 전문)

또한 memory://inject가 있다 — 세션 시작 시 예산이 정해진 컨텍스트 블록을 전달하는 특수 MCP 리소스로, 에이전트가 수동 프롬프팅 없이 관련 지식으로 시작할 수 있다.

공유 브레인이 모든 것을 바꾸는 이유

진정한 힘은 한 에이전트가 무언가를 기억할 수 있다는 것이 아니다. 당신의 모든 에이전트가 같은 메모리를 공유한다는 것이다.

시나리오: 다중 에이전트 개발

한 프로젝트에 세 개의 에이전트를 운영 중이다:

Claude Code는 IDE에서 대화형 개발용
Codex는 백그라운드 작업(테스트 생성, 리팩토링)용
OpenClaw는 운영 및 배포 자동화용

공유 메모리가 없으면 각 에이전트는 고립되어 작동한다. Claude Code는 당신의 명명 관례를 배운다; Codex는 그것을 위반하는 테스트를 생성한다. OpenClaw는 Claude Code가 어제 포착한 아키텍처 결정과 모순되는 설정을 배포한다.

BHGBrain을 사용하면, Claude Code가 "모든 API 라우트는 kebab-case를 사용하고 RFC 7807 problem details를 반환한다"고 저장할 때, Codex는 다음 recall에서 이를 picked up하고 규정을 준수하는 테스트를 생성한다. OpenClaw의 배포 스크립트도 같은 관례에 정렬된다. 하나의 메모리, 세 개의 에이전트, 드리프트 제로.

시나리오: 온보딩과 지식 이전

새 팀원이 합류한다. 40페이지의 위키 문서(절반은 구식)를 읽는 대신, 자신의 AI 에이전트를 팀의 BHGBrain 인스턴스에 연결한다. 에이전트는 즉시 다음에 접근한다:

아키텍처 결정과 그 근거
구체적인 예시가 있는 코딩 표준
알려진 함정과 해결책
프로젝트별 용어

BHGBrain에 포함된 부트스트랩 프롬프트는 정체성, 책임, 목표, 도구, 엔티티 맵, 운영 규칙을 다루는 구조화된 10섹션 인터뷰를 안내한다 — 약 30분 만에 포괄적인 작업 프로필을 구축한다.

시나리오: 교차 저장소 연속성

여러 저장소에서 작업 중인가 (마이크로서비스, 모노레포 분할, 다중 조직 컨설팅에서 흔함)? BHGBrain의 네임스페이스와 컬렉션 시스템이 지식을 정리한다:

project-alpha 네임스페이스는 그 프로젝트에 특정한 메모리를 보관
global 네임스페이스는 교차적 표준을 보관
네임스페이스 내의 컬렉션은 관련 메모리를 그룹화 (예: api-design, infrastructure, security)

에이전트는 올바른 범위를 자동으로 쿼리한다. 교차 오염 없음, 손실된 컨텍스트 없음.

아키텍처: 단순하고 자체 호스팅

BHGBrain은 당신의 머신 또는 인프라에서 실행된다. 임베딩 API를 넘어선 클라우드 의존성은 없다 (그리고 그것조차 로컬 모델로 선택적이다).

MCP Clients (Claude / Codex / OpenClaw / etc.)
  → MCP transport (HTTP or stdio)
  → BHGBrain server
      → Write pipeline (extraction + dedup + decision)
      → Qdrant (vector search)
      → SQLite (metadata, fulltext, categories, audit log)

요구 사항:

Node.js 20+
Qdrant (Docker 한 줄: docker run -d --name qdrant -p 6333:6333 qdrant/qdrant)
OpenAI API 키 (임베딩용) — 또는 완전한 로컬 운영을 위해 nomic-embed-text와 함께 Ollama 사용

설치 및 실행:

git clone https://github.com/Big-Hat-Group-Inc/BHGBrain.git
cd BHGBrain
npm install && npm run build
export OPENAI_API_KEY=sk-...
export BHGBRAIN_TOKEN=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")
node dist/index.js

끝이다. 이제 에이전트가 stdio(로컬) 또는 HTTP(네트워크)로 연결할 수 있다.

기본적으로 엔터프라이즈 준비 완료

BHGBrain은 장난감이 아니다. 첫날부터 프로덕션 고려사항을 담아 구축되었다:

인증: 루프백이 아닌 HTTP 연결에는 베어러 토큰이 필요. Fail-closed — 토큰 환경 변수가 설정되지 않고 루프백이 아닌 주소에 바인딩하면 서버가 시작을 거부.
속도 제한: 기본 클라이언트당 분당 100 요청.
감사 로깅: 모든 쓰기와 삭제는 타임스탬프, 네임스페이스, 클라이언트 ID, 연산 타입과 함께 로깅.
비밀 스캐닝: 메모리는 저장 전 자격 증명 패턴을 검사. 가능성 있는 비밀은 거부.
백업 및 복원: 무결성 검증을 포함한 전체 SQLite + Qdrant 스냅샷.
우아한 저하: Qdrant가 다운되면 읽기는 SQLite 전문으로 폴백. 임베딩 API를 사용할 수 없으면 서버는 충돌 대신 저하 모드로 진입.
구조화된 로깅: 자동 토큰 및 콘텐츠 마스킹이 포함된 JSON 로그.

5분 안에 시작하기

1. Qdrant 시작

docker run -d --name qdrant -p 6333:6333 qdrant/qdrant

2. BHGBrain 설치

git clone https://github.com/Big-Hat-Group-Inc/BHGBrain.git
cd BHGBrain && npm install && npm run build

3. 에이전트 설정

Claude Desktop의 경우, claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "bhgbrain": {
      "command": "node",
      "args": ["/path/to/BHGBrain/dist/index.js"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

HTTP 클라이언트(OpenClaw, mcporter, 원격 에이전트)의 경우:

{
  "mcpServers": {
    "bhgbrain": {
      "transport": "http",
      "url": "http://127.0.0.1:3721",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

4. 기억하기 시작

에이전트에게 무언가를 기억하라고 하라:

“기억해: 우리 API는 kebab-case 라우트를 사용하고, RFC 7807 problem details를 반환하며, 모든 엔드포인트는 Bearer token 인증이 필요하다.”

BHGBrain이 이를 저장하고, semantic으로 분류하고, 적절히 태그를 붙이고, recall을 통해 연결된 모든 에이전트가 사용할 수 있게 만든다.

5. 브레인 부트스트랩

포함된 부트스트랩 인터뷰를 실행하여 포괄적인 작업 프로필을 구축하라:

# BootstrapPrompt.txt의 내용을 새로운 AI 대화에 붙여넣으세요
# 에이전트가 10개 섹션에 걸쳐 당신을 인터뷰하고 구조화된 프로필을 생성합니다

파워 유저를 위한 CLI

BHGBrain은 직접 관리를 위한 전체 CLI를 포함한다:

bhgbrain search "authentication patterns" --mode hybrid
bhgbrain list --limit 20
bhgbrain category set "Coding Standards" --file ./standards.md
bhgbrain stats
bhgbrain gc --consolidate    # Merge similar memories, flag stale ones
bhgbrain backup create

BHGBrain과 MEMORY.md 중 언제 무엇을 쓸까

	MEMORY.md	BHGBrain
규모	컨텍스트 부피 전 ~100개 메모리	500,000개 이상 메모리
검색	매 세션마다 전체 파일 로드	관련 부분집합의 의미 검색
다중 에이전트	에이전트별, 워크스페이스별	모든 MCP 클라이언트에 공유
중복 제거	수동	자동 (해시 + 코사인 유사도)
타입	평면 텍스트	에피소드형, 의미형, 절차형
감사	없음	전체 감사 로그
백업	Git	무결성 검사를 포함한 전용 백업/복원

MEMORY.md는 단일 프로젝트에 단일 에이전트, 몇 개의 메모가 있는 경우에 적합하다. BHGBrain은 팀, 다중 에이전트 워크플로, 그리고 AI 메모리 필요가 텍스트 파일을 넘어선 모든 이를 위한 것이다.

다음은 무엇인가

BHGBrain v1은 코어를 올바르게 잡는 데 집중한다: 신뢰할 수 있는 저장, 스마트 중복 제거, 하이브리드 검색, 다중 클라이언트 접근. 로드맵은 다음을 포함한다:

다중 사용자 RBAC — 팀 수준 접근 제어
저장 시 암호화 — 규제 환경용
클라우드 동기화 — 기기 간 선택적 동기화
작업 메모리 TTL — 자동 만료되는 단기 스크래치 메모리

사용해 보라

BHGBrain은 MIT 라이선스로 오픈 소스다.

GitHub: github.com/Big-Hat-Group-Inc/BHGBrain

당신의 AI 에이전트가 어제 말한 것을 계속 잊는다면, 지속되는 브레인을 주라.

Kevin Kaminski는 Big Hat Group의 설립자로, 엔터프라이즈 AI, Windows 365, 클라우드 인프라를 중심으로 도구와 컨설팅 실무를 구축한다. BHGBrain은 우리가 매일 운영하는 다중 에이전트 워크플로에서 에이전트 건망증에 대한 우리 자신의 좌절에서 나왔다.