garrytan/gbrain

요약

GBrain은 Y Combinator의 Garry Tan이 자신의 에이전트를 운영하려고 만들어 MIT 라이선스로 공개한 에이전트 메모리 시스템이다. 지식의 원본은 사용자가 git으로 소유하는 markdown 저장소에 두고, GBrain은 그 저장소를 Postgres로 sync해 retrieval에 쓰는 파생 인덱스를 만든다.

README가 다른 개인 지식 도구와 구별점으로 내세우는 것은 두 가지다. 하나는 상위 페이지 목록 대신 인용과 gap analysis가 붙은 답을 합성해 돌려주는 brain layer이고, 다른 하나는 페이지를 쓸 때마다 LLM 호출 없이 typed edge를 만드는 self-wiring knowledge graph다. 240페이지 코퍼스로 만든 자체 벤치마크에서 P@5 49.1%, R@5 97.9%를 기록했으며, graph를 끈 변형과 비교하면 P@5가 31.4%p 높다.

시스템은 개인용으로 시작해 company brain까지 범위를 넓혔다. 팀원마다 login으로 범위가 정해진 brain 조각을 갖고, 질의 결과에는 허용된 것만 나온다. 구현은 TypeScript와 Bun이며 기본 엔진은 서버가 필요 없는 PGLite다.

배경

검색 결과와 답의 차이

README는 문제를 사용 장면 하나로 설명한다. 내일 Alice와 회의가 있고, 그가 무슨 일을 하는지, 마지막으로 언제 이야기했는지, 둘 사이에 무엇이 열려 있는지 알고 싶은 상황이다.

대부분의 개인 지식 도구는 여기서 페이지 목록을 돌려준다. Alice의 인물 페이지, 지난 분기 제품 리뷰 회의록, 킥오프 회의록, 고객사 페이지, 4월 22일 가격 논의 메모 다섯 건이 나오는 식이다. 자료를 제대로 찾아 주기는 했지만 읽고 정리하는 일은 사용자에게 그대로 남는다.

GBrain이 같은 질문에 돌려주는 것은 문장으로 쓰인 답이다. Alice가 어느 회사에서 엔지니어링을 맡고 있고, 마지막 대화가 언제였으며, 그 대화에서 아직 닫히지 않은 항목이 무엇인지가 근거 페이지와 함께 나온다. 예시에서는 보안 검토 회신 지연, 500석 요금제 견적에 대한 무응답, CISO 채용 관련 소개 약속 세 가지가 열린 항목으로 제시된다.

답의 마지막에 붙는 문장이 이 시스템의 성격을 잘 보여준다. 6주 전인 4월 22일 이후로 Alice와 그 회사에 대해 brain에 추가된 것이 없으니, 이메일이나 Slack DM처럼 brain이 보지 못하는 경로로 답이 왔을 수 있다는 경고다. 무엇을 아는지뿐 아니라 무엇을 모르는지를 함께 말하는 부분이 gap analysis다.

상시 실행 데몬이라는 선택

README는 설계 근거를 운영 관점에서 밝힌다. 대화창 안의 에이전트가 계속 열심히 일하게 만드는 것보다, ingest와 enrichment와 통합을 24시간 수행하는 데몬을 만드는 편이 쉽다는 것이다. GBrain은 그 데몬을 일반화한 결과물로 소개된다.

같은 문단이 목표도 밝힌다. 10만 페이지 규모의 brain을 만드는 목적은 그것을 전략적 해자로 쓰기 위해서다. 컨텍스트를 잃지 않기 위해, 그리고 자기 머릿속에 있는 것을 다시 읽지 않고도 질의하기 위해서다. brain layer가 그 해자를 실제로 쓸 수 있게 만들고, 야간에 실행되는 dream cycle이 날을 유지한다. brain layer와 dream cycle 모두 사용자의 하드웨어, 데이터베이스, API 키 위에서 수행된다.

저자 본인의 운영 규모

README 첫 단락은 저자 자신의 production brain 수치를 공개한다. 문서 전체에서 실제 운영 규모를 알려주는 유일한 수치다.

이 brain은 사용자가 자는 동안 회의, 이메일, 트윗, 음성 통화, 직접 적은 아이디어를 ingest한다. 마주친 모든 사람과 회사를 보강하고, 자기 인용을 고치며, 밤사이 메모리를 통합한다.

핵심 개념

brain repo는 사용자가 git으로 소유하는 평문 markdown 디렉토리다. README는 이것을 system of record로 부른다. GBrain은 이 저장소를 데이터베이스로 sync하며, git에서 파일을 지우면 데이터베이스에서는 soft delete가 된다. 인덱스가 손상되어도 저장소가 남아 있으면 다시 만들 수 있는 구조다.

brain은 데이터베이스 자체를 가리킨다. 개인 brain일 수도 있고 참여한 팀 mount일 수도 있다. source는 그 brain 안에 든 저장소 하나를 가리키며 wiki, gstack, 에세이, 지식 베이스 같은 단위다. 두 개념이 서로 직교하기 때문에 하나의 brain이 여러 source를 담고, 하나의 source가 여러 brain에 mount될 수 있다.

typed edge는 페이지 사이의 관계에 이름을 붙인 것이다. works_at, invested_in, attended, founded, advises, mentions 같은 값을 쓴다. 이 edge는 페이지를 쓸 때마다 LLM 호출 없이 문법 매칭만으로 만들어진다.

schema pack은 brain의 형태를 선언한 묶음이다. 어떤 페이지 타입이 존재하는지, 그 타입들이 어떤 관계로 연결되는지, 어떤 fact를 자동으로 추출할지를 정한다. 기본값은 gbrain-base-v2이며 사용자가 직접 만들어 쓸 수도 있다.

brain layer는 retrieval 결과 위에서 답을 합성하는 층이다. gbrain think가 진입점이고, 인용과 gap analysis를 함께 낸다. raw retrieval을 담당하는 gbrain search와 역할이 나뉜다.

Minion은 Postgres 네이티브 job queue의 작업 단위다. durable subagent, shell job, child job이 모두 여기에 실린다. dream cycle은 야간 cron으로 수행되는 enrichment, 인용 수정, salience 채점, 모순 탐지, 다음 날 준비 묶음을 부르는 이름이다.

방법

에이전트 루프

시스템 전체의 동작은 여섯 단계 루프 하나로 서술된다.

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

auto-link 단계가 graph를 자라게 하는 지점이다. 참조된 entity에 해당하는 페이지가 없으면 stub 페이지가 새로 생기고, 그 stub이 다음 enrichment의 대상이 된다. 사용자가 별도로 관계를 입력하지 않아도 graph가 커지는 구조다.

sync 단계에 붙은 cron 작업이 dream cycle이다. 사람 페이지 중복 제거, 인용 수정, salience 점수 매기기, 모순 찾기, 다음 날 할 일 준비를 사용자가 자는 동안 수행한다.

두 엔진과 하나의 계약

GBrain은 규모에 따라 두 가지 저장소를 쓰지만 상위 코드는 하나의 interface만 본다.

두 엔진은 src/core/engine.ts에 선언된 contract-first BrainEngine interface를 함께 구현한다. 이 interface가 약 47개 연산을 정의하고, CLI와 MCP 서버가 모두 이 한 곳에서 생성된다. 어느 표면으로 호출하든 같은 연산이 같게 동작한다는 뜻이며, 엔진 교체가 상위 기능에 영향을 주지 않는 근거이기도 하다.

PGLite는 서버가 없으므로 초기화가 2초 만에 끝난다. README가 설치 소요를 30분으로 잡으면서 "데이터베이스는 2초, 사용자는 API 키에 대한 질문에만 답하면 된다"고 적는 근거가 여기에 있다.

brain과 source의 분리

brain이 데이터베이스이고 source가 그 안의 저장소라는 구분은 라우팅 규칙으로 구현된다. 어떤 파일이 어느 source에 속하는지는 .gbrain-source dotfile이 정하며, 해석은 문서화된 6단계 precedence chain을 따른다.

이 분리 덕분에 하나의 배치가 여러 형태를 가질 수 있다. 개인 brain에 개인 wiki와 에세이 저장소를 함께 두는 형태, 팀 mount에 참여해 공용 지식 베이스를 함께 읽는 형태, 동료의 brain 서버를 가리키는 thin client 형태가 모두 같은 구조에서 나온다. 저장소 공개 범위를 부분집합으로 나누어 publish하는 것도 가능하다.

schema pack

README는 대부분의 개인 지식 도구가 자기 방식의 고정 레이아웃을 강요한다고 지적한다. Notion export나 오래된 Obsidian vault를 그 위에 올리면 에이전트가 Projects/ 폴더가 무엇을 뜻하는지, Reading/이 사람인지 출처인지 알지 못한다는 것이다. GBrain의 답은 레이아웃을 교체 가능한 pack으로 만드는 것이다.

기본값인 gbrain-base-v2의 15종은 person, company, media, tweet, social-digest, analysis, atom, concept, source, deal, email, slack, writing, project, note다. 서로 겹치지 않으면서 빠짐이 없도록 정리한 분류라고 README는 설명한다.

자체 pack을 만드는 절차는 세 명령이다. gbrain schema detect가 실제 파일 구조를 타입 후보로 클러스터링하고, gbrain schema suggest가 그 후보에 LLM 패스를 적용하며, gbrain schema review-candidates --apply가 사람이 고른 것만 승격한다. 이 밖에 gbrain schema active는 지금 어느 pack이 어느 단계에서 설정됐는지 보여주고, gbrain schema list는 번들된 pack과 설치된 pack을 나열한다.

활성 pack은 읽기와 쓰기 경로 전체를 관통한다.

pack을 바꾸면 brain이 스스로를 다시 해석하고, 되돌리면 잃는 것이 없다. 어느 pack을 쓸지는 7단계 순서로 결정된다. per-call 플래그, 환경 변수, source별 데이터베이스 키, brain 전역 데이터베이스 키, gbrain.yml, ~/.gbrain/config.json, 그리고 gbrain-base 기본값 순이다.

v0.40.7.0부터는 사람이 아니라 에이전트가 이 스키마를 바꿀 수 있다. gbrain schema CLI 동사 14개와 배치 MCP op schema_apply_mutations가 제공되며, 이 op는 admin scope를 요구하되 localOnly가 아니라서 원격 에이전트도 HTTPS로 접근한다. 안전 장치로는 atomic file lock, 에이전트 신원이 남는 audit log, 동시 writer를 막지 않는 1,000행 단위 chunked UPDATE backfill이 붙는다.

retrieval 구성

retrieval은 여러 층을 겹쳐 점수를 매긴다. 기본 층은 pgvector의 HNSW vector 검색, BM25 keyword 검색, 두 결과를 합치는 reciprocal-rank fusion, source-tier boost, 그리고 의도를 반영해 질의를 다시 쓰는 intent-aware query rewriting이다.

비용과 품질의 조절값은 개별 설정이 아니라 세 가지 이름 있는 mode로 묶여 있다. README는 각 mode의 세부 값을 본문에 적지 않고 docs/eval/SEARCH_MODE_METHODOLOGY.md의 비용과 recall 비교로 넘긴다.

reranker에 대한 두 서술은 서로 어긋난다. 기본값 balanced가 이미 ZeroEntropy reranker를 켠 상태라고 적으면서, 통합 목록에서는 zerank-2를 tokenmax mode의 기본값으로 소개한다. 실제 적용 범위는 README만으로 확정되지 않는다.

여기에 질의마다 발동하는 graph signal 세 가지가 더해진다.

점수 산출은 관측 가능하게 만들어져 있다. gbrain search "<query>" --explain은 단계별 기여를 보여준다. 기본 점수가 얼마였는지, 어떤 boost가 발동했는지, 그 boost가 무엇을 곱했는지가 나온다. gbrain doctor에는 graph_signals_coverage 검사가 있고, gbrain search stats는 신호별 발동 횟수와 실패 분해를 보여준다. 특정 페이지가 왜 나오지 않는지 추적할 때는 gbrain search diagnose "<query>" --target <slug>가 어느 retrieval 층이 그 페이지를 표면화하거나 놓치는지 알려준다.

세부 규칙 세 가지가 실무에서 자주 문제가 되는 지점을 겨냥한다.

• 페이지 단위 pooling: vector retrieval이 페이지마다 가장 좋은 chunk를 모아 점수를 낸다. 한 chunk가 약하다는 이유로 이웃 페이지에 밀리는 대신, 페이지가 가장 강한 근거로 표면화된다.
• 이름을 부르는 질의: 페이지 제목 문구나 선언된 free-text alias에 맞는 질의는 그 페이지로 boost된다. 기존 페이지의 alias는 gbrain reindex --aliases로 backfill한다.
• 에이전트가 쓰는 힌트: 모든 결과에 왜 매치됐는지 알리는 evidence 태그와 exists, probable, unknown 중 하나인 create_safety 힌트가 붙는다. 에이전트가 raw score를 보고 추측하는 대신 페이지가 이미 있는지 판단하라는 설계다.

self-wiring knowledge graph

graph는 별도의 추출 단계가 아니라 쓰기 경로 안에 들어 있다. 모든 put_page가 markdown, wikilink, typed-link 문법에서 entity 참조를 뽑아 edge를 기록하며, 이 과정에 LLM 호출이 하나도 없다. 대용량 ingest에서도 graph 유지 비용이 토큰 비용으로 번지지 않는 이유다.

README는 vector 검색과 graph의 역할을 한 문장으로 구분한다. vector 검색은 의미적으로 가까운 chunk를 돌려주고, graph는 사실로 연결된 chunk를 돌려준다는 것이다. hybrid retrieval은 양쪽에서 함께 끌어오고, 모든 write에서 실행되는 auto-link가 graph를 최신으로 유지한다.

여러 단계를 건너가는 질의는 gbrain graph-query로 처리한다. "Acme AI에서 일하는 사람이 누구인가", "Bob이 이번 분기에 어디에 투자했는가" 같은 질문이 vector 검색만으로는 닿기 어려운 예로 제시된다.

Obsidian에서 옮겨온 vault에는 별도 설정이 필요하다. [[struktura]]처럼 폴더를 명시하지 않은 wikilink가 실제로는 projects/struktura.md를 가리키는 경우인데, 이 basename 해석은 gbrain config set link_resolution.global_basename true로 켜야 동작한다. 기본값은 꺼짐이고, 켜기 전에 gbrain doctor가 몇 개의 edge를 새로 얻게 되는지 알려준다.

brain layer와 gap analysis

질의 경로는 세 가지로 나뉜다. 무엇이 필요한지에 따라 고르는 구조다.

gap analysis가 이 층의 차별점으로 지목된다. 답변이 사용자에게 알리는 것은 네 가지다. 페이지가 오래됐을 때, claim에 인용이 없을 때, 두 페이지가 서로 모순될 때, 그리고 아직 채워지지 않은 구멍이 있을 때다.

README는 brain layer를 find_trajectory와 함께 쓰는 조합을 compounding 효과의 예로 든다. 회사 지표가 어떻게 변했는지, 팀이 지금 어떤 모습인지, 무엇을 약속하고 공유했는지, 마지막으로 언제 만났는지, 여기서 줄 수 있는 value-add가 무엇인지를 한 번에 점수와 인용이 붙은 형태로 답한다는 것이다.

Minions 작업 큐

Minions는 BullMQ 모양을 따르되 Postgres 네이티브로 만든 job queue다. BullMQ 계열이 보통 별도 Redis를 두는 것과 달리 작업 상태가 brain과 같은 데이터베이스에 남는다. README는 이 큐가 "서브에이전트를 fire-and-forget Promise로 띄우는" 방식을 대체한다고 설명한다.

43개 스킬

지능을 실행기가 아니라 markdown 파일에 두는 태도가 docs/ethos/의 "thin harness, fat skills"다. 스킬 라우팅은 skills/RESOLVER.md에 있고, 커버하는 영역은 signal capture, ingest(아이디어, 미디어, 회의), enrichment, querying, brain ops, 인용 수정, 일일 작업 관리, cron 스케줄링, 리포트, voice, soul audit, 스킬 작성, eval 프레임워크, 마이그레이션이다.

스킬이 평문 markdown이고 특정 도구에 묶여 있지 않다는 점이 중요하다. 설치기가 43개를 하나의 skillpack으로 묶어 에이전트 workspace에 넣으며, 운영자는 필요한 스킬을 고쳐 쓸 수 있다.

데이터 유입 경로

ingest는 명령 하나로 통일돼 있고, 어느 형태로 부르든 페이지가 데이터베이스와 디스크에 한 번에 안착한다.

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)

기본 slug는 inbox/YYYY-MM-DD-<hash8>다. 캡처가 예측 가능한 triage 위치에 모이게 하려는 규칙이다. thin client 설치에서는 같은 동사가 MCP를 거쳐 서버로 라우팅되며 명령과 사용 경험은 동일하다.

설치 경로

설치는 사람이 아니라 에이전트가 수행하는 것을 기본으로 설계됐다. README가 제시하는 네 경로는 목적이 다르다.

에이전트 설치 경로는 HTTPS로 파일을 읽고 shell 명령을 실행할 수 있는 에이전트면 동작한다. README는 Codex, Claude Code, Claude Cowork, Cursor, AlphaClaw에서 검증했다고 적는다. 에이전트 플랫폼을 써 본 적이 없는 사용자를 위해 personal-brain 튜토리얼이 플랫폼 선택부터 첫 질의 검증까지를 따로 안내한다.

CLI 단독 경로의 bun install -g github:garrytan/gbrain은 README 버전에 따라 권장 여부가 다르다. GBrain Review: An Honest Assessment (Vectorize)는 v0.30 시점 README가 이 명령을 postinstall hook 차단 때문에 피해야 할 설치 함정으로 적었다고 보고하는 반면, 이 페이지가 근거로 삼은 v0.41 시점 README는 같은 명령을 표준 경로로 제시한다.

MCP 서버와 클라이언트

GBrain은 MCP로 30개가 넘는 도구를 노출한다. 서버는 두 가지 모습으로 실행된다.

HTTP 서버에는 DCR 방식 client registration, read와 write와 admin으로 나뉜 scope 게이트, rate limit이 포함된다. ngrok, Railway, Fly.io 배포 가이드는 docs/mcp/에 있다.

클라이언트별 설정은 인증 방식에 따라 갈린다.

통합 카탈로그

외부 데이터를 brain으로 넣는 경로는 recipe로 관리된다. recipe는 markdown과 설정 힌트로 이루어져 recipes/에 실리며 gbrain integrations list로 찾는다.

스킬 자동 개선

스킬이 markdown 파일이라는 점은 그 파일을 학습 대상으로 다룰 수 있다는 뜻이기도 하다. gbrain skillopt는 SKILL.md를 학습 가능한 파라미터로 놓고 다음 순서로 개선한다.

1. --bootstrap-from-skill로 그 스킬에서 곧바로 시작용 벤치마크를 만든다. 직접 작성한 벤치마크를 써도 된다.
2. 채점을 담당하는 judge를 강화한다.
3. optimizer가 편집안을 제안하면 점수가 실제로 오른 것만 남긴다.

README는 이 절차를 약 20분에 API 호출 약 $1로 잡는다. 플래그와 비용, 안전 장치 기준은 docs/guides/skillopt.md에 있다. 사람이 문체를 다듬는 대신 측정 가능한 점수로 스킬을 고른다는 점에서, 지능을 markdown에 두는 설계가 어디까지 이어지는지를 보여주는 사례다.

문서 지도와 에이전트 진입점

설치와 운영을 에이전트가 맡는 설계이므로 문서 구조도 사람과 에이전트를 나누어 놓았다.

에이전트에게 URL 하나를 붙여넣는 것만으로 설치가 진행되는 구조는 이 문서 배치에 기대고 있다. 사람이 읽는 튜토리얼과 에이전트가 실행하는 규약이 같은 저장소 안에서 분리돼 있기 때문이다.

company brain

개인 brain과 같은 구조를 팀 단위로 확장한 것이 company brain이다. 팀원마다 login으로 범위가 정해진 brain 조각을 갖고, 질의하면 허용된 것만 보인다. 다른 사람의 노트나 다른 팀의 데이터는 결과에 포함되지 않는다.

권한 격리는 개별 API가 아니라 읽기 경로 전체를 대상으로 검증했다고 README가 밝힌다. search, list, lookup, multi-source read를 포함해 brain을 읽는 모든 방식에 fuzz test를 적용했고 누출은 0건이었다는 서술이다. 저자는 이 형태를 YC가 Request for Startups에 올린 company-brain 항목에 대응시키며, 그 영역에서 창업할 계획이라면 GBrain 위에 지으라고 권한다. 설정 절차는 10명에서 50명 규모 팀을 대상으로 한 90분짜리 튜토리얼로 따로 문서화돼 있다.

계보와 크레딧

README 마지막 절은 이 시스템이 혼자 만들어진 것이 아님을 밝힌다. 라이선스는 MIT이고, 저자는 GBrain을 자신의 OpenClaw와 Hermes 배치를 운영하기 위해 만든 production brain으로 다시 한번 규정한다. 기원에 대한 서술은 docs/ethos/ORIGIN.md에 있다.

개발 쪽 검증 절차도 세 단계로 나뉜다. bun run test가 빠른 반복용이고, bun run verify가 push 전 게이트이며, bun run ci:local이 Docker 기반 CI 스택 전체를 로컬에서 실행한다.

결과

BrainBench

자체 벤치마크인 BrainBench는 Opus로 생성한 240페이지 rich-prose 코퍼스를 쓴다. 개인 brain이 실제로 담는 종류의 서술형 문서를 모사한 코퍼스다.

P@5는 상위 5건 중 관련 문서의 비율이고 R@5는 관련 문서를 상위 5건 안에서 얼마나 회수했는지를 나타낸다. 두 수치를 함께 보면 이 시스템의 성격이 드러난다. R@5 97.9%는 필요한 문서가 거의 언제나 상위 5건 안에 들어온다는 뜻이고, P@5 49.1%는 그 5건의 절반가량이 관련 문서라는 뜻이다. 답을 합성하는 층이 위에 놓인 구조에서는 회수율이 먼저 확보되어야 한다.

31.4%p라는 차이가 이 저장소가 내세우는 핵심 근거다. hybrid retrieval에 graph를 더한 것이 vector 단독 대비 성능을 끌어올린 최대 요인이며, 같은 폭이 ripgrep 기반 BM25 조합에 대해서도 유지된다. scorecard 전문은 자매 저장소 gbrain-evals에 공개돼 있다.

평가 프레임워크

벤치마크 하나가 아니라 목적이 다른 여러 eval이 CLI 하위 명령으로 붙어 있다.

gbrain eval replay가 흥미로운 이유는 평가 대상이 합성 코퍼스가 아니라 실제 사용 기록이라는 점이다. 코드가 바뀔 때마다 과거의 실제 질의를 다시 실행해 회귀를 확인하는 구조이며, NamedThingBench의 hard gate와 함께 retrieval 품질을 CI에서 붙잡아 두는 역할을 한다.

운영 관련 수치

한계

문서가 스스로 남긴 유보

README는 릴리스 노트를 인용하며 미완인 부분을 함께 밝힌다.

• cron sync의 부분 완료: v0.41.13.0의 --timeout이 import 도중 발동하면 gbrain sync가 status partial로 exit 0을 내고 last_commit은 그대로 둔다. 다음 실행이 같은 diff를 다시 걷고 content_hash가 이미 처리된 파일을 단축한다. 이 설계에서 extract와 embed 단계는 끝까지 실행되며, full sync 트리거는 v0.42 이후로 미뤄져 있다. --max-age는 마이그레이션 v98 이후 30분의 rollout window를 갖는다.
• 태그 제거가 반영되지 않는 트레이드오프: v0.41.37.0이 태그 조정을 추가 전용으로 바꾼 결과, frontmatter에서 태그를 지워도 다음 sync에서 데이터베이스의 태그가 사라지지 않는다. 이를 구분하려면 provenance 컬럼이 필요해 미뤘다고 적혀 있다.
• Obsidian basename 해석은 기본 꺼짐: 폴더를 가로지르는 bare wikilink 해석은 사용자가 명시적으로 켜야 동작한다. 기본값에서는 그런 링크가 edge로 잡히지 않는다.

운영에서 드러난 실패 유형

troubleshooting 절은 분량이 가장 큰 절이며, 실제 운영에서 나온 실패를 증상 단위로 기록한다. 이 목록 자체가 시스템의 난이도를 보여주는 자료다.

개별 버그보다 반복되는 유형이 중요하다. 대형 brain에서 sync가 멈추는 문제, 원격 Postgres pooler의 불안정이 조용한 데이터 손실로 이어지는 문제, PGLite의 단일 writer 제약이 서버와 경합하는 문제가 각각 여러 릴리스에 걸쳐 등장한다. 이 시스템을 실제로 운영하려면 gbrain doctor의 검사 항목과 ~/.gbrain/audit/ 아래 감사 로그를 읽을 줄 알아야 한다.

기여 절차상의 제약

외부 기여는 즉시 반영되지 않는다. community PR은 하나씩 merge하지 않고 release wave 단위로 묶이며, 기여자 표기는 Co-Authored-By: trailer로 유지되고 릴리스별로 CHANGELOG.md에 기록된다.

변경 범위에 따라 절차도 갈린다. 오타, 문서 버그, 명백한 회귀 같은 빠른 수정만 바로 PR로 갈 수 있고, schema와 retrieval ranking과 MCP 프로토콜과 보안 경계를 건드리는 변경은 PR 전에 이슈에서 설계 논의를 거쳐야 한다.

자료 자체의 한계

README 안에서 기본 페이지 타입 개수가 서로 다르게 적혀 있다. schema pack 절은 v0.41.22부터 기본값이 15종 gbrain-base-v2이고 legacy가 24종이라고 밝히는데, v0.40.7.0을 소개하는 문단은 "기본값은 22종 universal type을 제공한다"고 적는다. 릴리스가 달라 생긴 서술로 보이지만 README만으로는 확정되지 않는다.

이 페이지의 근거는 README 전문 하나다. 저장소 코드를 직접 읽고 검증한 결과가 아니므로, 성능 수치와 fuzz test 결과는 저자의 자기 보고다. BrainBench 코퍼스와 평가 코드가 gbrain-evals에 공개돼 있다는 점은 재현 가능성 측면에서 근거를 보태지만, 그 저장소 자체는 본 wiki에 수집돼 있지 않다.

핵심 용어

관련 페이지

• garrytan/gbrain: docs/tutorials: 같은 저장소의 docs/tutorials/를 정리한 페이지. 이 페이지가 구조와 동작을 다룬다면 튜토리얼 페이지는 개인 brain, company brain, skillopt, 코딩 에이전트 연결을 시간과 비용 예산과 함께 절차로 다룬다.
• GBrain 저장소 핵심 정리: 아키텍처, 기능, 보안, 운영 흐름: 저장소를 계약 우선 설계와 thin harness, fat skills 두 관점으로 읽은 한국어 정리. 버전이 자라온 순서를 하나의 흐름으로 보여준다.
• GBrain: 오픈소스 개인 지식 베이스: GeekNews에 올라온 한국어 소개글. 이 저장소를 처음 접할 때 읽을 짧은 개괄이다.
• Garry Tan's GBrain Explained (TechWealth Hub): 5분 45초짜리 소개 영상을 정리한 페이지. 3계층 멘탈 모델과 데이터베이스 primitive, sync 검증 절차를 다룬다.
• GBrain Review: An Honest Assessment (Vectorize): 외부 평가. 10개 항목 scorecard와 강점, 약점, 대안 비교가 여기에 있다. 이 페이지가 다루지 않는 판단은 그 페이지가 담당한다.
• Hermes + GBrain: A Complete Setup Guide: Hermes와 GBrain을 VPS에 올리는 실전 셋업 기록.
• Computer Memory vs GBrain (DevRev): 개인 메모리와 엔터프라이즈 메모리를 비교한 에세이. 공유 범위와 권한 모델의 차이를 다룬다.
• RAG, LLM Wiki, or GBrain? 에이전트 메모리 결정 프레임워크 (Liu): RAG, LLM Wiki, GBrain 중 무엇을 고를지 판단하는 결정 프레임워크.
• Karpathy LLM Wiki 패턴: 한국어 종합 정리 (kmyu99 Notion): Karpathy의 LLM Wiki 패턴을 합성한 페이지. GBrain이 확장한 원형에 해당한다.