gbrain — AI 에이전트에게
"기억하는 뇌"를 달아주기

먼저, "에이전트의 외장 해마"가 뭔가?

왜 지금 이런 두뇌가 필요한가.

2024~2026년 사이 Claude·ChatGPT 같은 에이전트가 빠르게 똑똑해졌지만, 한 가지 약점이 남았다 — 잘 잊어버린다는 것. 세션이 끝나면 어제 얘기한 내용도, 1시간 전 받은 이메일도 사라진다. 그래서 사용자는 매번 같은 컨텍스트를 다시 붙여넣고 있다.

해결책은 보통 두 갈래다 — (1) 모델의 컨텍스트 윈도를 더 키우거나, (2) 외부 DB에 사실을 적어두고 그때그때 검색해서 끼워넣는 RAG. gbrain은 두 번째 길을 택하되, 거기에 "자기 배선 지식 그래프"를 더해 벡터 검색만으로는 닿지 못하는 답까지 끌어낸다.

이 프로젝트의 핵심 메시지

한 문장으로 줄이면.

2026년 5월, 트렌딩에 오른 이유

시대적 배경 + 경쟁 우위.

① 유명인이 직접 만들어서 직접 쓴다

이 레포의 가장 큰 신뢰 포인트는 Garry Tan(현 Y Combinator 사장)이 본인 업무용으로 만들고 매일 돌리고 있다는 점이다. README에 적힌 운영 규모 (작성 시점 2026-05-20 기준):

• 17,888페이지가 두뇌 안에 정리되어 있고
• 4,383명의 인물 · 723개의 회사가 자동 색인됨
• 21개 cron 잡이 밤사이 자율적으로 돈다
• 12일 만에 만들어진 시스템

② RAG 단점을 "그래프"로 보완

일반적인 RAG는 "의미가 비슷한 문장"만 잘 찾아온다. 그래서 "Bob이 이번 분기에 어디에 투자했어?" 같은 사실 관계 질문엔 약하다. gbrain은 모든 페이지에 위키링크([[wiki/people/bob]])를 자동 추출해 그래프 엣지를 LLM 호출 없이 자라게 한다. tree-sitter로 마크다운을 파싱해 엔티티 참조를 패턴 매칭으로 뽑는 게 비밀.

③ "30분이면 끝나는 셋업" — 진입장벽이 낮다

"Postgres 같은 서버 깔아라"부터 막힐 게 뻔하니까 PGLite(WASM으로 도는 임베디드 Postgres)를 기본으로 쓴다. 도커도, 서버도 필요 없이 2초 만에 DB가 뜨고, 그다음은 "API 키 묻는 질문에 답만 하면" 끝.

④ MCP · Claude Code · Cursor 등 어디든 꽂힌다

MCP 서버로 동작하므로 Claude Desktop, Claude Code, Cursor, Windsurf, ChatGPT, Perplexity, Cowork에서 그대로 사용할 수 있다. gbrain serve 한 줄.

경쟁 비교 — 일반 RAG vs gbrain

전체 기술 지도

런타임 · DB · 검색 · MCP · 잡 큐.

런타임 · 언어

데이터베이스 · 검색

임베딩 · 리랭커

LLM SDK

MCP · 서버 · 인증

유틸리티 · 파일 처리

잡 큐 — "Minions"

관리자 UI

시스템 구조와 핵심 설계 패턴

전체 루프 → 두 엔진 → 자기 배선 그래프 → 하이브리드 검색 → 잡 큐 → 보안.

전체 루프 — "신호 → 검색 → 응답 → 쓰기 → 자동 연결 → 동기화"

  signal   →   search   →   respond   →   write   →   auto-link   →   sync
  (every    (brain-first  (informed     (page +    (typed edges     (cron
  message)  retrieval)    by context)   timeline)  + backlinks)     keeps fresh)

두 개의 엔진, 하나의 계약

┌─────────────────────────────────────────────────────────────┐
│              src/core/engine.ts (BrainEngine 인터페이스)     │
│   put_page · get_page · search · query · graph-query 등     │
│                  약 47개 오퍼레이션                          │
└──────────┬──────────────────────────────────┬───────────────┘
           │                                  │
   PGLite 엔진(default)                  Postgres+pgvector 엔진
   - WASM 임베디드                       - Supabase / 셀프호스팅
   - 서버/도커 불필요                    - 다중 머신 공유
   - ~50K페이지까지 권장                 - 대규모 / 팀용

CLI와 MCP 서버는 단일 소스에서 생성된다. 같은 47개 오퍼레이션을 두 가지 방식(셸 명령 vs MCP 도구)으로 노출하므로 사람과 에이전트가 같은 기능을 공유한다.

두 가지 조직 축 — Brain ⊥ Source

모든 페이지는 source_id 컬럼으로 태깅된다. .gbrain-source 닷파일이 라우팅을 결정하고, 6단계 우선순위 체인이 어디로 쓸지/읽을지 결정한다.

자기 배선 그래프 — LLM 호출 없이 엣지가 자란다

핵심 트릭 — 페이지를 쓸 때마다 마크다운에서 패턴 매칭만으로 엔티티 참조를 뽑아낸다.

# 페이지 본문 예시
오늘 [[wiki/people/bob]] 가 [[companies/acme-ai]] 에 100K USD를 invested_in.

# 자동으로 만들어지는 그래프 엣지
people/bob  --invested_in-->  companies/acme-ai

LLM API 호출 = 0. 단순히 tree-sitter로 마크다운을 파싱해 위키링크 + typed link(attended/works_at/invested_in/founded/advises 등)를 추출한다. 이게 "Bob이 어디 투자했어?" 같은 다중 홉 질문에 답할 수 있는 비밀이다.

하이브리드 검색의 내부

  query
    │
    ▼
  query expansion / 의도 인식 재작성
    │
    ├─→ Vector (HNSW on pgvector)    ┐
    ├─→ BM25 keyword (pg_trgm)       │── RRF (Reciprocal Rank Fusion)
    └─→ Graph traversal (multi-hop)  ┘
                                       │
                                       ▼
                              Source-tier 가중치
                                       │
                                       ▼
                           ZeroEntropy zerank-2 리랭커
                                       │
                                       ▼
                                  Top-K 결과

세 가지 모드(conservative / balanced / tokenmax)가 비용·품질의 다이얼을 미리 묶어둔다. 기본은 balanced.

잡 큐 — Minions

durable subagent가 핵심 개념. LLM 도구 루프가 도중에 크래시가 나도 pending → done 2단계 상태로 회복한다. 셸 잡(쉘 명령 실행)에는 감사 로그가 붙고, 자식 잡엔 캐스케이딩 타임아웃이, 외부 호출엔 rate lease가 걸린다.

밤사이 도는 "꿈 사이클(dream cycle)"

cron이 매시간/매일 돌리는 자율 정비 페이즈들:

• synthesize — 흩어진 정보 통합
• patterns — 반복되는 신호 추출
• consolidate — 중복 사람·회사 페이지 dedupe, valid_until 시간 마감
• citation-fixer — 인용 깨진 곳 자동 수리
• soul-audit — 모순되는 사실 찾기
• daily-task-prep — 내일 할 일 미리 정리

보안 경계 — 신뢰된 로컬 vs 원격 에이전트

아주 중요한 설계 포인트. OperationContext.remote 플래그로 두 부류를 구분한다.

레포 구조 해부

어디에 뭐가 있는지.

gbrain/
├── src/
│   ├── cli.ts                 # gbrain 명령어 엔트리포인트 (신뢰된 호출자)
│   ├── schema.sql             # Postgres 스키마 (pages/sources/edges/etc.)
│   ├── core/
│   │   ├── engine.ts          # BrainEngine 인터페이스 (47개 op 계약)
│   │   ├── engine-factory.ts  # PGLite vs Postgres 선택
│   │   ├── pglite-engine.ts   # WASM Postgres 구현체
│   │   ├── operations.ts      # remote=true/false별 권한 정책
│   │   ├── embedding.ts       # 14개 임베딩 공급자 추상화
│   │   ├── search/hybrid.ts   # 벡터+BM25+그래프 RRF
│   │   ├── link-extraction.ts # 위키링크 + typed link 파서
│   │   ├── ai/gateway.ts      # LLM 호출 게이트 (비용/속도/리트라이)
│   │   ├── minions/           # 잡 큐 (BullMQ-shaped, Postgres-native)
│   │   ├── cycle/             # synthesize/patterns/consolidate 페이즈
│   │   ├── calibration/       # voice gate, SVG 차트 렌더러
│   │   └── ...                # 50+ 모듈
│   ├── commands/              # gbrain init / doctor / sync / serve 등
│   ├── mcp/                   # MCP 서버 (stdio + HTTP/OAuth)
│   └── eval/                  # LongMemEval, BrainBench, replay
│
├── skills/                    # 총 43개 스킬
│   ├── RESOLVER.md            # 스킬 디스패처 (에이전트가 먼저 읽음)
│   ├── _AGENT_README.md
│   ├── _brain-filing-rules.md
│   ├── ingest/                # 회의/미디어/아이디어 ingest
│   ├── enrich/                # 사람·회사 자동 보강
│   ├── citation-fixer/        # 깨진 인용 수리
│   ├── daily-task-manager/    # 매일 할일 사이클
│   ├── cron-scheduler/        # 21개 cron 정의
│   └── soul-audit/            # 모순 감지
│
├── admin/                     # React SPA 관리자 대시보드
├── docs/
│   ├── architecture/          # topologies, brains-and-sources, RETRIEVAL
│   ├── mcp/                   # 각 MCP 클라이언트별 셋업
│   ├── integrations/          # 음성/이메일/임베딩 공급자별 레시피
│   └── ethos/                 # "thin harness, fat skills" 철학
├── recipes/                   # twilio-voice-brain 등 통합 레시피
├── evals/                     # LongMemEval 실행/덤프
├── examples/                  # 샘플 브레인 레포
├── templates/                 # 사람/회사/딜 마크다운 템플릿
├── test/                      # 단위 + E2E
├── scripts/                   # CI/검증/빌드 스크립트
│
├── package.json               # Bun + ai SDK + MCP SDK + pgvector
├── gbrain.yml                 # storage 정책 (db_tracked / db_only)
├── openclaw.plugin.json       # OpenClaw 플러그인 매니페스트
├── docker-compose.ci.yml      # 로컬 CI Docker 스택 (pgvector)
├── llms.txt / llms-full.txt   # LLM이 한 번에 빨아가는 문서 맵
├── AGENTS.md                  # 비-Claude 에이전트용 진입점
├── CLAUDE.md                  # Claude Code 전용 진입점
└── README.md

기술별 배울 것

8개 영역에서 무엇을 가져갈지 + 실습 아이디어.

① TypeScript + Bun 단일 바이너리

② PGLite — 서버 없는 Postgres

③ pgvector + HNSW + BM25 하이브리드 검색

④ MCP 서버 — stdio + HTTP/OAuth

⑤ Postgres-native 잡 큐 (Minions)

⑥ 마크다운 = 시스템 오브 레코드

⑦ Eval 파이프라인 — LongMemEval + replay

⑧ "Thin harness, fat skills" 철학

하드웨어·시스템 요구사항

규모별 최소 / 권장 사양.

직접 해볼 수 있는 6단계

난이도별 실습 — Easy → Hard.

실습 1 — 30분 셋업하기Easy

실습 2 — Claude Desktop에 MCP로 연결Easy

실습 3 — Obsidian 보관함 마이그레이션Medium

실습 4 — 자체 스킬 만들기Medium

실습 5 — 검색 모드별 비용/정확도 측정Hard

실습 6 — 잡 큐(Minions) 패턴 이식Hard

8주 심화 학습 로드맵

주차별로 따라가면 전체 스택 마스터.

핵심 용어 한눈에

자주 마주칠 단어들.

더 깊이 파고들 자료

공식 · 관련 표준 · 학습 리소스.

공식 자료

• garrytan/gbrain (GitHub)
• garrytan/gbrain-evals — 벤치마크 별도 레포
• openclaw · hermes (관련 에이전트 프레임워크)
• TrendShift 페이지
• https://raw.githubusercontent.com/garrytan/gbrain/main/llms.txt (LLMs documentation map)

핵심 인프라 · 표준

• PGLite (electric-sql/pglite)
• pgvector/pgvector
• MCP 스펙 (modelcontextprotocol.io)
• LongMemEval 데이터셋
• ZeroEntropy (임베딩/리랭커)