JYP Garden Internal

garrytan/gbrain README

Properties1
tagsagentic-ai, knowledge, jyp-labs, devops-automation

12 min read

garrytan/gbrain — 공식 README 한글 정리

Key Insight

GBrain은 “검색 결과 목록”이 아니라 출처가 붙은 종합 답변, 지식 그래프 순회, 빈틈 분석까지 한 상자에서 제공하는 에이전트용 브레인 레이어다. 개인 메모리뿐 아니라 팀 단위 회사 브레인으로 확장하며, Claude Code·Codex·Hermes 같은 에이전트에 MCP/CLI로 연결하는 것을 전제로 설계되어 있다.

출처: GitHub garrytan/gbrain README
원문: https://github.com/garrytan/gbrain
원문 캡처: 2026-06-19-garrytan-gbrain-readme.md
유효일: 2026-06-19
GitHub API 확인값: stars 23,368 / forks 3,345 / open issues 949 / default branch master / pushed_at 2026-06-18T18:14:24Z

README의 한 줄 주장

“Search gives you raw pages. GBrain gives you the answer.”
검색은 원자료 페이지를 돌려주지만, GBrain은 여러 자료를 읽고 종합해 답을 작성하며, 무엇을 아직 모르는지도 알려준다.

핵심 Takeaway

  • 브레인 레이어: AI 에이전트가 코드 밖의 회의·이메일·메모·트윗·통화·아이디어를 잊지 않도록 하는 영속 지식 계층.
  • 종합 답변: gbrain search는 원자료 검색, gbrain think는 검색 결과를 바탕으로 인용·빈틈 분석이 붙은 답변을 생성.
  • 자가 배선 지식 그래프: 페이지 작성 시 엔티티 참조와 typed edge(attended, works_at, invested_in, founded, advises 등)를 LLM 호출 없이 생성.
  • 회사 브레인: 로그인 기반 스코프를 두어 개인·팀별 접근 권한을 분리하고, 검색·목록·조회·멀티소스 읽기 경로를 fuzz test해 누출을 막는 구조를 지향.
  • 에이전트 설치 우선: 사람 CLI보다 AI 에이전트가 INSTALL_FOR_AGENTS.md를 읽고 설치·검증까지 수행하는 경로를 권장.
  • MCP 연결: Claude Code, Codex, Cursor/Windsurf, Claude Desktop/Cowork, Perplexity, ChatGPT 등 주요 MCP 클라이언트 연결 문서를 제공.
  • 스키마 팩: 고정 노트 구조가 아니라 gbrain-base-v2, legacy gbrain-base, gbrain-recommended, 사용자 정의 pack으로 브레인의 형태를 해석.
  • 운영 루프: signal → search → respond → write → auto-link → sync. 에이전트의 모든 메시지에서 신호를 감지하고, 브레인 우선 검색 후 결과를 다시 기록·연결.

무엇이 기존 PKM/RAG와 다른가

README가 강조하는 차이는 두 가지다.

  1. 답변 합성 계층
    보통의 개인 지식 도구는 “쿼리에 맞는 10개 청크”를 돌려준다. GBrain은 사람·회사·딜·아이디어를 가로질러 출처가 붙은 문장형 답변을 작성하고, 페이지가 오래됐거나 근거가 부족하거나 모순이 있으면 gap analysis로 표시한다.

  2. 자가 배선 지식 그래프
    페이지에 쓰인 사람·회사·관계 표현을 typed edge로 연결한다. “Acme AI에서 누가 일하지?”, “Bob이 이번 분기에 투자한 것은?” 같은 질문은 vector search만으로는 약하고, 그래프가 있어야 강해진다는 주장이다. README에는 240-page Opus-generated rich-prose corpus 기준 P@5 49.1%, R@5 97.9%, graph-disabled variant 대비 P@5 +31.4pt 수치가 제시되어 있다.

README 예시: 회의 준비 질의

질문: “내일 Alice와 회의 전에 무엇을 알아야 하지?”

  • 일반 검색형 PKM: Alice 관련 페이지 5개를 나열하고 사용자가 직접 읽어야 함.
  • GBrain: Alice의 역할, 마지막 대화 시점, 열려 있는 액션 3개, 최근 6주간 업데이트가 없어 이메일·Slack DM에 누락 정보가 있을 수 있다는 주의까지 답변.

핵심은 검색이 자료를 찾는 단계에서 끝나지 않고, 회의 준비를 실제로 수행한다는 점이다.

설치 경로

1) 에이전트에게 설치시키기 — 권장

AI 에이전트 플랫폼이 없다면 README는 다음을 먼저 제안한다.

  • OpenClaw: Render에 AlphaClaw 배포
  • Hermes: Railway 템플릿으로 배포

그다음 에이전트에게 아래 지시를 붙여 넣는다.

Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL_FOR_AGENTS.md

에이전트가 GBrain 설치, 브레인 생성, API 키 질문, 43개 스킬 로딩, dream cycle 구성, E2E 검증을 수행한다. README 기준 약 30분.

2) Claude Code 또는 Codex에 빠르게 연결

로컬 브레인을 만들고 coding agent에 MCP로 붙이는 최소 경로:

gbrain init --pglite
claude mcp add gbrain -- gbrain serve
# 또는
codex mcp add gbrain -- gbrain serve

이미 원격 브레인이 있다면:

gbrain connect https://your-host/mcp --token gbrain_xxx --install
gbrain connect https://your-host/mcp --token gbrain_xxx --agent codex --install

3) CLI standalone

bun install -g github:garrytan/gbrain
gbrain init --pglite
gbrain doctor
gbrain import ~/notes/
gbrain query "what themes show up across my notes?"

MCP 연결 대상

README가 명시한 클라이언트:

  • Claude Code
  • Codex
  • Cursor / Windsurf / stdio MCP 클라이언트
  • Claude Desktop
  • Claude Cowork
  • Perplexity Computer
  • ChatGPT

서버 형태:

gbrain serve        # stdio MCP
gbrain serve --http # OAuth 2.1 + admin dashboard 포함 HTTP MCP

HTTP 서버는 client registration, scope-gated access(read/write/admin), rate limiting을 포함한다.

두 가지 질의 방식

gbrain search "who's working on AI agents at portfolio companies?"
gbrain think "who's working on AI agents at portfolio companies?"
  • gbrain search: hybrid retrieval 결과를 빠르게 반환. 에이전트 컨텍스트, 인용 확인, 특정 문장 찾기에 적합.
  • gbrain think: 같은 검색 결과를 바탕으로 출처와 빈틈 분석이 붙은 종합 답변 작성. 페이지가 오래됐는지, 인용이 부족한지, 모순이 있는지 알려주는 gap analysis가 핵심.

데이터 입력 방식

gbrain capture "the thought I want to remember"
gbrain capture --file ./notes/today.md
echo "from a pipe" | gbrain capture --stdin
SLUG=$(gbrain capture "..." --quiet)
  • 페이지는 DB와 디스크에 동시에 저장.
  • 기본 slug는 inbox/YYYY-MM-DD-<hash8>.
  • thin-client 설치에서는 MCP를 통해 서버로 라우팅되며 UX는 동일.
  • Webhook/Zapier/IFTTT/Apple Shortcuts/mobile inbox 경로도 제안.

브레인의 형태: schema packs

README는 “고정된 notes/people/tags 구조”를 강요하지 않는다는 점을 강조한다.

  • gbrain-base-v2: v0.41.22 기준 기본. 15-type DRY/MECE canonical taxonomy.
  • gbrain-base: v0.41 이전 legacy 24-type layout.
  • gbrain-recommended: 추가 디렉터리/타입을 제공하는 확장 pack.
  • 사용자 정의 pack: gbrain schema detect, suggest, review-candidates --apply로 실제 파일 구조에 맞는 타입 후보를 만들고 승격.

관련 명령:

gbrain schema active
gbrain schema list
gbrain schema detect
gbrain schema suggest
gbrain schema review-candidates
gbrain schema use my-pack

시스템 루프

README의 운영 루프:

signal → search → respond → write → auto-link → sync
  • Signal detector: 모든 메시지에서 아이디어, 엔티티, 시간 민감 todo, 이름, 링크를 감지.
  • Brain-first lookup: 외부 API보다 먼저 개인/조직 브레인에서 조회.
  • Auto-link: 페이지 작성 시 wikilink/엔티티 기반 그래프를 자동 연결.
  • Cron enrichment: 잠자는 동안 중복 사람 페이지 병합, 인용 수정, 중요도 점수, 모순 탐지, 다음 날 업무 준비.

주요 기능

Vector(HNSW/pgvector) + BM25 keyword + reciprocal-rank fusion + source-tier boost + intent-aware query rewriting. conservative, balanced, tokenmax 같은 search mode를 제공하고, gbrain search --explain으로 점수 근거를 볼 수 있다.

Self-wiring knowledge graph

put_page가 markdown/wikilink/typed-link syntax에서 엔티티 참조를 추출하고 typed edge를 생성. gbrain graph-query로 multi-hop traversal 가능.

Job queue: Minions

BullMQ형 Postgres-native job queue. crash-safe two-phase persistence를 가진 durable subagent, shell jobs with audit, child jobs, rate leases, S3/Supabase attachments 등을 제공.

43 curated skills

skills/RESOLVER.md에 라우팅이 있고, signal capture, ingest, enrichment, querying, brain ops, citation fixing, daily task management, cron scheduling, reports, voice, soul audit, skill creation, eval, migration 등을 포괄.

Eval framework

LongMemEval, replay/eval export, cross-modal judge, retrieval-quality NamedThingBench 등을 통해 검색 품질과 named-thing retrieval regression을 gate.

Brain consistency

suspected-contradictions 평가로 충돌 가능성이 있는 페이지 쌍을 찾고 dream cycle에 연결.

Agent-authored schema

에이전트가 브레인의 page type, link type, facts extraction 범위를 진화시킬 수 있게 하는 schema CLI/MCP 기능을 제공.

통합

  • Voice: Twilio + OpenAI Realtime 등
  • Email + Calendar: webhook handlers
  • Embedding providers: OpenAI, OpenRouter, Voyage, ZeroEntropy, Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama, llama.cpp, LiteLLM proxy 등
  • Rerankers: ZeroEntropy zerank-2, llama.cpp reranker recipe
  • Credential gateway
  • MCP clients

아키텍처 요약

  • Two engines, one contract: PGLite(Postgres 17 via WASM)와 Postgres+pgvector를 BrainEngine 인터페이스로 통일.
  • Brain repo as system of record: 지식은 일반 git repo의 Markdown 파일로 저장되고, GBrain이 Postgres에 동기화.
  • Brain ⟂ Source: brain은 DB, source는 그 안의 repo. .gbrain-source dotfile과 6-tier precedence로 라우팅.
  • Graph + Vector: vector search는 의미적으로 가까운 chunk, graph는 사실적으로 연결된 chunk를 반환. hybrid search가 둘을 결합.

JYP Labs 관점 적용 메모

  • 현재 대표님의 OMW/Hermes 운영 방향과 매우 가깝다. 특히 “brain-first lookup → 응답 → 기록 → auto-link → cron enrichment”는 Sophie의 매일 브리핑·업무 실행 루프와 직접 연결 가능하다.
  • 회사 브레인 관점에서는 접근권한 스코프, 로그/출처, gap analysis가 핵심이다. 단순 RAG보다 “모르는 것을 모른다고 표시하는 운영 메모리”가 더 중요하다.
  • Codex/Hermes 연결 문서가 있으므로, 향후 jyp-garden을 GBrain과 병렬 평가할 때는 gbrain search와 OMW query를 같은 질의 세트로 비교하는 방식이 적합하다.
  • 단, README는 프로젝트 홍보 문서 성격이 강하므로 benchmark 수치와 보안 누출 테스트 결과는 원 저장소의 eval 문서/코드로 추가 검증 필요.

연결되는 노트

그래프 뷰

백링크