BHGBrain: AI 에이전트를 위한 영구 메모리

모든 AI 에이전트는 각 세션을 건망증으로 시작합니다. 어제의 아키텍처 결정, 지난주의 디버깅 돌파, 세 스프린트 전에 팀이 합의한 명명 규칙 — 모두 사라집니다. 당신이 다시 설명하거나, 에이전트가 잘못 알게 됩니다.

BHGBrain이 이를 해결합니다. 세션, 도구, 팀 전반에 걸쳐 유지되는 영구적이고 검색 가능하며 공유되는 메모리를 AI 에이전트에 제공하는 오픈소스 MCP 서버입니다.

작동 방식

BHGBrain은 AI 에이전트와 지속성 저장소 계층 사이에 위치합니다. 모든 MCP 호환 클라이언트 — Claude Code, Codex, OpenClaw, Gemini — 가 BHGBrain에 연결되어 공유 지식 베이스에 접근할 수 있습니다.

AI Agents (Claude / Codex / OpenClaw / Gemini)
  → MCP transport (stdio or HTTP)
    → BHGBrain server
      → Qdrant (semantic vector search)
      → SQLite (metadata, fulltext index, audit log, archive)

에이전트가 메모리를 저장하면 BHGBrain은 지능적인 파이프라인을 통해 처리합니다:

1. 정규화 — 해싱 전에 입력을 정리하고 표준화하여, 바꾸어 표현하거나 재포맷된 콘텐츠 전반의 중복 제거 정확도를 향상시킵니다
2. 중복 제거 — SHA-256 콘텐츠 해싱과 코사인 유사도(임계값: 0.92)를 사용해 기존 메모리와 비교하며, 정밀도 제어를 위해 계층별 조정 임계값을 적용합니다
3. 결정 — 새 지식을 추가할지, 기존 항목을 업데이트할지, 중복을 폐기할지 결정합니다
4. 보존 할당 — 유형, 중요도, 호출자 지정 선호도에 따라 적절한 보존 계층(T0–T3)에 메모리를 할당합니다
5. 저장 — 수락된 메모리를 임베딩, 인덱싱, 영구화하며, 향후 검색 순위에 영향을 주는 중요도 점수를 함께 저장합니다

에이전트가 컨텍스트가 필요할 때, BHGBrain은 하이브리드 RRF 검색을 통해 전달합니다 — 구성 가능한 가중치로 Reciprocal Rank Fusion을 통해 시맨틱 유사도(70%)와 전문 매칭(30%)을 결합합니다. 에이전트는 전체 지식 베이스가 아닌 관련 메모리를 받습니다.

핵심 기능

• 계층형 보존(T0–T3) — 메모리는 의미가 있는 만큼 유지됩니다. T0(기반)는 만료되지 않습니다. T1(제도적)은 1년간 지속됩니다. T2(운영)는 90일간 지속됩니다. T3(일시적)은 30일간 지속됩니다. 각 계층은 구성 가능한 용량 예산을 가집니다(T1: 100K, T2: 200K, T3: 200K 항목).
• 슬라이딩 윈도우 TTL —每次 접근마다 만료 시계가 재설정됩니다. 계속 사용되는 메모리는 자동으로 살아남습니다.
• 자동 승격 — 5회 이상 접근된 메모리는 자동으로 다음으로 높은 보존 계층으로 승격됩니다. 고가치 지식이 스스로 영구성을 선택합니다.
• 만료 전 경고 — 메모리는 만료 7일 전에 플래그되어, 에이전트와 운영자가 지식이 손실되기 전에 행동할 시간을 갖습니다.
• 삭제 전 아카이브 — 만료된 메모리는 제거 전에 아카이브 테이블에 기록됩니다. 복구 가능한 기록 없이 영구 삭제되는 일은 없습니다.
• 하이브리드 RRF 검색 — Reciprocal Rank Fusion이 시맨틱(70%)과 전문(30%) 결과를 단일 순위 목록으로 결합합니다. 가중치는 쿼리별로 구성 가능합니다.
• 시맨틱 중복 제거 — 0.92 임계값의 코사인 유사도가 거의 중복된 항목을 잡아냅니다. SHA-256 체크섬이 정확한 중복을 잡아냅니다. 콘텐츠 정규화가 해싱 전에 실행되어 바꾸어 표현된 입력이 올바르게 중복 제거됩니다.
• 중요도 점수 — 각 메모리는 0–1 중요도 점수를 가지며, 검색 결과 순위에 직접 영향을 줍니다. 중요도가 높은 메모리가 먼저 표시됩니다.
• 카테고리 / 지속적 정책 슬롯 — 명명된 정책 카테고리(예: architecture-decisions, coding-standards, security-policies)는 TTL과 무관하게 항상 사용 가능해야 하는 제도적 지식을 위한 지속적 슬롯을 제공합니다.
• 에이전트 간 공유 메모리 — Claude Code가 당신의 API 규약을 학습하면, Codex가 다음 세션에서 자동으로 이어받습니다. 하나의 메모리, 모든 에이전트, 드리프트 제로.
• 메모리 분류 — 메모리는 자동으로 에피소드형(이벤트), 시맨틱형(사실), 절차형(워크플로)으로 분류됩니다.
• 네임스페이스 격리 — 프로젝트, 팀, 클라이언트를 교차 오염 없이 분리합니다. 횡단 표준을 위한 글로벌 네임스페이스.
• 컬렉션 — 네임스페이스 내에서 관련 메모리를 그룹화합니다(예: api-design, infrastructure, security).
• 컨텍스트 주입 — 특수 MCP 리소스가 세션 시작 시 예산화된 컨텍스트 블록을 전달하여, 에이전트가 수동 프롬프트 없이 관련 지식과 함께 시작합니다.
• 전체 CLI — 목록, 검색, 카테고리 관리, 가비지 컬렉션 실행, 백업 생성 — 모두 명령줄에서.

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

BHGBrain은 프로토타입이 아닙니다. 첫날부터 프로덕션 사용을 위해 구축되었습니다.

대상 독자

• 다중 에이전트 워크플로를 운영하는 팀 — Claude Code, Codex, OpenClaw가 모두 드리프트 없이 같은 프로젝트 지식을 공유해야 할 때.
• 엔터프라이즈 IT 부서 — AI 메모리를 위해 감사 추적, 인증, 자체 호스팅 인프라가 필요한 조직.
• 컨설턴트 및 에이전시 — 네임스페이스 격리가 클라이언트 지식을 분리하면서도 참여 전반에 걸쳐 내부 표준을 공유합니다.
• 솔로 개발자 — AI 메모리 요구가 MEMORY.md 파일을 넘어선 모든 사람.

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. API 키 설정 및 실행

export OPENAI_API_KEY=sk-...
node dist/index.js

4. 에이전트 연결

BHGBrain을 MCP 클라이언트 설정에 추가하세요 — Claude Desktop, OpenClaw, 또는 MCP 호환 도구. 이제 에이전트가 세션 전반에 걸쳐 remember와 recall을 할 수 있습니다.

상세 설정, 구성 옵션, 부트스트랩 인터뷰 프롬프트는 GitHub의 전체 문서를 참조하세요.

다국어 문서

BHGBrain은 5개 언어로 된 전체 문서와 함께 제공됩니다:

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

📖 심층 분석: BHGBrain: AI 에이전트에 공유되고 영구적인 메모리 부여하기