gbrain

KO | EN

gitlite — search

#go #android #rust #linux #docker #macos #nodejs #java #windows #cli #kubernetes #vue #security #openai

(★ 28,560)

Garry's Opinionated OpenClaw/Hermes Agent Brain

gbrain 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# GBrain
\*\*검색은 원본 페이지를 주지만, GBrain은 정답을 줍니다.\*\* 이것은 AI 에이전트가 지금까지 놓치고 있던 두뇌 레이어입니다. 하나의 상자 안에서 종합(synthesis), 그래프 탐색(graph traversal), 갭 분석(gap analysis)을 모두 수행하는 유일한 솔루션입니다. 이 위에 완전한 자율 에이전트를 실행하거나, 단 한 번의 명령어로 Claude Code 또는 Codex에 슈퍼차지된 검색 레이어로 연동할 수 있습니다. 어떤 방식이든 코드가 아닌 모든 것에 대해 건망증을 보이던 코딩 에이전트의 버릇을 고쳐줄 것입니다.
저는 Y Combinator의 사장 겸 CEO인 Garry Tan입니다. 저는 제 자신의 AI 에이전트를 구동하기 위해 GBrain을 만들었습니다. 이는 제 OpenClaw 및 Hermes 배포 환경을 지탱하는 프로덕션 두뇌입니다: \*\*155,795개의 페이지, 24,589명의 인물, 5,340개의 기업\*\*, 그리고 자율적으로 실행되는 66개의 크론 잡. 제 에이전트는 제가 잠든 사이에 미팅, 이메일, 트윗, 음성 통화, 그리고 독창적인 아이디어들을 흡수합니다. 만나는 모든 사람과 기업에 대한 정보를 풍부하게 만듭니다. 밤사이에 자신의 인용(citation)을 수정하고 메모를 통합합니다. 저는 잠들었을 때보다 더 똑똑한 상태로 아침에 일어납니다. 여러분도 그렇게 될 것입니다.
\*\*그리고 이제 GBrain은 기업의 두뇌로도 작동합니다.\*\* 팀의 각 구성원은 로그인 권한에 따라 분할된 자신만의 두뇌 영역을 갖게 됩니다. 쿼리를 실행할 때, 오직 허용된 권한 내의 내용만 볼 수 있으며 다른 사람의 메모나 다른 팀의 데이터는 절대 볼 수 없습니다. 우리는 두뇌를 읽을 수 있는 모든 방식(검색, 목록, 조회, 다중 소스 읽기)에 걸쳐 퍼즈 테스트(fuzz-tested)를 진행했으며 유출(leak)이 0건임을 확인했습니다. YC가 최근 Startup Request for Startups에 등재한 [company-brain](https://www.ycombinator.com/rfs#company-brain) 형태의 공유 조직 기억 장치로 GBrain을 도입해 보세요. 해당 분야에서 제품을 만들고 있다면, 이 위에 구축하는 것이 유리할 것입니다. \*\*[튜토리얼: GBrain을 기업의 두뇌로 설정하기 →](docs/tutorials/company-brain.md)\*\*
많은 개인 지식 시스템들은 키워드 매칭과 grep 기능을 제공합니다. GBrain은 그 기능들을 제공할 뿐만 아니라, 다른 곳에서는 함께 제공하지 않는 두 가지 기능을 추가했습니다.
- \*\*실제 정답을 제공하는 종합(synthesis) 레이어.\*\* 사람, 기업, 거래, 아이디어에 걸쳐 잘 인용된 종합적인 산출물. 단순히 "귀하의 쿼리를 언급하는 10개의 청크가 여기에 있습니다"가 아니라, 인용구와 함께 두뇌가 아직 알지 못하는 내용에 대한 명시적인 주석이 포함된 실제 정답을 제공합니다. 갭 분석(gap analysis)은 두뇌를 사용하는 방식을 근본적으로 바꾸어 놓는 부분입니다.
- \*\*스스로 연결되는 지식 그래프.\*\* 모든 페이지 작성 시 LLM 호출 없이 엔티티 참조를 추출하고 타입이 지정된 에지(`attended`, `works\_at`, `invested\_in`, `founded`, `advises`)를 생성합니다. "Acme AI에서 일하는 사람이 누구야?" 또는 "Bob이 이번 분기에 어디에 투자했지?"라고 질문하면 벡터 검색만으로는 도달할 수 없는 답변을 얻을 수 있습니다. 벤치마크 결과: 240페이지 분량의 Opus가 생성한 풍부한 산출물 코퍼스에서 \*\*P@5 49.1%, R@5 97.9%\*\*를 기록했으며, 그래프 비활성화 버전 및 ripgrep-BM25 + 벡터 전용 RAG 대비 \*\*P@5 기준 31.4포인트 향상된\*\* 수치를 보였습니다. 전체 BrainBench 성적표는 관련 [gbrain-evals](https://github.com/garrytan/gbrain-evals) 저장소에서 확인할 수 있습니다.
15만 페이지에 달하는 두뇌를 구축하는 이유는 이를 전략적 해자(moat)로 활용하기 위함입니다. 컨텍스트를 절대 잃지 않기 위함입니다. 내 머릿속에 있는 내용을 다시 읽지 않고도 쿼리하기 위함입니다. 두뇌 레이어는 이 해자를 유용하게 만드는 요인입니다. 24시간 내내 작동하는 드림 사이클(dream cycle)은 그 해자를 날카롭게 유지해 줍니다. 이 모든 것은 여러분의 하드웨어, 여러분의 DB, 여러분의 키 위에서 실행됩니다.
채팅창에서 열심히 일하는 에이전트를 유지하는 것보다, 24시간 내내 실행되며 수집, 보강, 통합을 수행하는 데몬(daemon)을 배포하는 것이 더 쉽습니다. GBrain은 바로 그러한 데몬의 일반화된 형태입니다. 30분 만에 설치하세요. 에이전트가 작업을 수행합니다. 제 개인 에이전트가 더 똑똑해지는 만큼, 여러분의 에이전트도 똑똑해집니다.
> 추천하는 Codex / Claude Code 경로를 따를 경우 (주로 간단한 인터뷰 포함) \*\*동작하는 개인 에이전트를 만드는 데 ~15분\*\*; 상시 가동되는 OpenClaw / Hermes 설정의 경우 약 30분이 소요됩니다. 어느 쪽이든 데이터베이스는 2초 만에 준비됩니다 (PGLite, 서버 불필요).
> \*\*LLM:\*\* 문서 맵을 보려면 [`llms.txt`](llms.txt)를 가져오거나, 하나의 요청으로 핵심 문서가 인라인된 동일한 맵을 보려면 [`llms-full.txt`](llms-full.txt)를 가져오세요. \*\*에이전트:\*\* [`AGENTS.md`](AGENTS.md)(Claude Code를 사용하는 경우 [`CLAUDE.md`](CLAUDE.md))로 시작하세요.
## 이것이 어떻게 보이는지
내일 Alice와 미팅이 있다고 가정해 봅시다. 그녀가 어떤 업무를 하고 있는지, 마지막으로 대화한 때는 언제인지, 그리고 두 사람 사이에 아직 해결되지 않은 사안은 무엇인지 기억하면서 미팅에 들어가고 싶습니다. 이때 나타나는 모습은 다음과 같습니다.

type, and what you'd get back.
\*\*질문:\*\*
> "내일 Alice와의 미팅 전에 알아야 할 게 뭐가 있지?"
\*\*대부분의 개인 지식 관리 툴은 페이지 목록을 반환합니다.\*\* 다음과 같은 식입니다:
```
1. people/alice — Alice는 Acme에서 엔지니어링을 총괄합니다...
2. meetings/2026-03-15-alice-q1 — Alice와의 Q1 제품 리뷰...
3. meetings/2026-01-08-acme-kickoff — Acme 팀과의 킥오프 미팅...
4. customers/acme — Acme는 우리가 함께 일하는 시리즈 B 핀테크 기업입니다...
5. notes/2026-04-22 — 가격 책정에 대한 Alice와의 간단한 대화...
```
준비를 위해 직접 열어서 읽어봐야 하는 페이지가 다섯 개나 됩니다. 툴은 올바른 자료를 찾아냈지만, 일은 대신해주지 않았습니다.
\*\*GBrain은 출처와 함께 답변을 제공합니다:\*\*
```
Alice는 Acme(시리즈 B 핀테크)의 엔지니어링을 총괄합니다. 마지막 대화는 
4월 22일 가격 관련 간단한 채팅이었습니다. 해당 대화에서 아직 해결되지 
않은 세 가지 사안이 있습니다:
1. 새 티어에 대한 보안 검토를 그녀가 보내야 합니다
(마감일은 5월 1일이었으며, 이후 업데이트가 없습니다).
2. 귀하는 500석 티어의 가격을 제안하겠다고 약속했습니다
(4월 25일에 발송했으나, 아직 응답이 없습니다).
3. 그녀가 CISO를 채용 중이라고 언급했으며, 귀하는 네트워크에서
누군가를 소개해주겠다고 말했습니다.
참고: 6주 전인 4월 22일 이후로 Alice나 Acme에 관해 브레인에 추가된 
내용이 없습니다. 브레인이 볼 수 없는 채널인 이메일이나 Slack DM을 
통해 답변했을 수 있습니다. 이 내용들이 여전히 유효하다고 가정하기 전에 
Alice에게 직접 확인해보는 것이 좋습니다.
```
모든 주장에는 그 이면에 출처 페이지가 존재합니다. 마지막의 "참고(heads up)"는 브레인이 아직 파악하지 못한 내용을 알려주므로, 당황하는 대신 Alice에게 직접 물어볼 수 있습니다. 브레인이 미팅 준비를 대신 해준 것입니다.
이것이 검색 엔진과 브레인의 차이점입니다. 검색은 페이지를 찾아줍니다. 브레인은 페이지를 읽고 답변을 작성해 줍니다.
## Install
> [!WARNING]
> \*\*GBrain은 npm을 통해 배포되지 않습니다.\*\* `gbrain`이라는 이름의 npm 패키지는 이 프로젝트와 아무런 관련이 없는 무관한 패키지입니다. `npm install -g gbrain`이나 `bun add -g gbrain`을 실행하지 마세요. 엉뚱한 것이 설치되며 PATH에 있는 실제 바이너리와 충돌(shadowing)을 일으킬 수 있습니다. 아래에 문서화된 공식 경로를 통해서만 설치 및 업그레이드하세요
> (`bun install -g github:garrytan/gbrain` 또는 `git clone` + `bun install && bun link`).
> 실수로 npm 설치를 이미 실행한 경우: `npm uninstall -g gbrain` /
> `bun remove -g gbrain`을 실행한 후 GitHub에서 다시 설치하세요. `gbrain doctor`는 잘못 설치된 npm 패키지를 감지하고 해결 방법을 출력합니다.
GBrain은 AI 에이전트가 설치하고 운영하도록 설계되었습니다. \*\*GBrain이 처음이신가요? Codex로 시작하세요\*\* — 이미 구독 중인 ChatGPT를 기반으로 실행되며, 약 15분이 소요되고 별도의 배포가 필요 없습니다. 이미 Claude Code를 사용 중이신가요? 방법은 정확히 동일합니다. 설계된 목적 그대로 GBrain이 상시 실행되며 24시간 내내 브레인을 풍부하게 만들기를 원하시나요? 그렇다면 실제 서버 및 API 비용이 발생하는 OpenClaw 또는 Hermes를 사용하시면 됩니다. 아래의 각 경로는 독립적으로 완벽하게 작동합니다. (수동으로 직접 연동하고 싶으신가요? [CLI 독립 실행형](#cli-standalone-no-agent) 또는 [MCP 표](#connect-gbrain-to-your-ai-client-mcp)로 이동하세요.)
### Codex 사용 시 — 권장하는 첫 번째 단계
Codex를 상시 작동하는 개인 에이전트로 전환하세요. (전체 에이전트 없이 브레인과 스킬만 원하시나요? `codex plugin marketplace add garrytan/gbrain@codex-plugin` 후 `codex plugin add gbrain@gbrain`을 실행하세요 — [docs/mcp/CODEX.md](docs/mcp/CODEX.md) 참고). 아래의 붙여넣기 블록은 전체 에이전트를 구축합니다.) \*\*ChatGPT 데스크톱 앱\*\* (폴더에서 Codex 열기) 및 \*\*Codex CLI\*\* (터미널에서 `codex` 실행) 모두에서 작동합니다 — 동일한 설치, 동일한 결과. \*\*기존 코드 프로젝트가 아닌 새 빈 폴더\*\*에서 Codex를 엽니다. 해당 폴더는 부트스트랩이 생성하고 개인 보호를 검증해 주는 에이전트 전용 \*\*비공개 GitHub 저장소\*\*가 됩니다. 그런 다음 아래 내용을 붙여넣으세요:
```
Read and follow every step of:
https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/BOOTSTRAP\_FOR\_AGENTS.md
Goal: set yourself up as my persistent personal agent in this folder, with gbrain
as your memory. Interview me before writing any identity file — never invent
answers. Ask before anything destructive.
```

You are not done until
`gbrain bootstrap verify` exits 0.
```
Codex will ask for command approvals during the install — approving them is the sandbox working as intended. What you get, in about 15 minutes: a short interview (6 required questions) → your agent's identity (SOUL.md, USER.md, MEMORY.md) rendered from your own answers, never invented → a local PGLite brain (2 seconds, no server, no Docker) → MCP wired so every session can search and write memory → a \*\*private\*\* GitHub repo, created and privacy-verified, as your agent's durable body. Works with \*\*zero API keys\*\* — keyword search plus memory your agent writes itself; one optional key upgrades capabilities (OpenAI: semantic search + automatic fact extraction; Voyage: semantic search; Anthropic: fact extraction). Codex reads brain context through its tools each turn (pull-based). The click moment: tell it one small thing to remember, restart Codex, then ask for it back — the answer comes from the brain, not from this chat's context (which the restart cleared). That cross-session round-trip is the whole product; "what's my name / my top jobs?" is answered from your identity files, which is nice but not the same trick.
Two things worth understanding once it's running: \*\*you own the brain\*\* — every memory is a markdown file in that private repo (read it, clone it to a second machine, delete it and the brain is gone) — and \*\*the first skill to run is `cold-start`\*\*: say "fill my brain" and your agent imports your Gmail, calendar, and contacts (via [ClawVisor](https://clawvisor.com), an OAuth vault so the agent never holds raw tokens) or offline archives like Google Takeout, one consented step at a time. An empty brain is a database; a filled one is a memory.
> \*\*Prefer to make the repo yourself?\*\* Create a new \*\*empty\*\* private repo \*\*under your own GitHub account\*\* (no README/.gitignore/license), clone it, open the clone in Codex, and paste the same block — bootstrap detects your empty repo and adopts it instead of creating one. The repo must be empty and personal-account-owned; org-owned repos are refused (create one under your account, or let bootstrap make it).
### For Claude Code — turn it into your persistent personal agent
Works in the \*\*desktop app\*\* and in the \*\*CLI\*\* (`claude` in a terminal) — identical harness, identical result. Open Claude Code in a \*\*new, empty folder\*\* (not an existing code project) — that folder becomes your agent's own \*\*private GitHub repo\*\*, created and privacy-verified for you. Then paste the same block:
```
Read and follow every step of:
https://raw.githubusercontent.com/garrytan/gbrain/latest-stable/BOOTSTRAP\_FOR\_AGENTS.md
Goal: set yourself up as my persistent personal agent in this folder, with gbrain
as your memory. Interview me before writing any identity file — never invent
answers. Ask before anything destructive. You are not done until
`gbrain bootstrap verify` exits 0.
```
Codex 경로의 모든 내용이 Claude Code에도 적용됩니다 — 인터뷰, 본인의 답변으로 생성되는 정체성, 로컬 브레인, 프라이빗 레포, 키리스(keyless) 모드 — 여기에 추가로 Claude Code는 \*\*턴당 컨텍스트 훅\*\* (기본 활성화, 선택 해제 가능)을 지원합니다. 브레인이 모든 프롬프트에 자동으로 로드되며, 작업 내용은 턴마다 프라이빗 레포에 지속적으로 저장됩니다(로컬에서는 약 5분 간격 디바운스, 클라우드 샌드박스에서는 매 턴마다 저장되며, 하네스가 세션 종료 훅을 실행하지 않는 `/exit` 상황도 커버합니다). 푸시가 실패할 경우 다음 턴에 알림이 표시됩니다. 이는 노트북뿐만 아니라 \*\*Claude Code 클라우드 세션\*\*에서도 작동합니다. 샌드박스가 GitHub API를 차단할 경우 순수 git 프로토콜로 폴백하며, `gbrain bootstrap cloud-setup-script`가 환경 설정 레시피를 출력합니다. 핵심적인 순간: 기억해야 할 사소한 것을 하나 알려주고, 세션을 재시작한 뒤, 다시 물어보세요. 새로 시작된 세션에는 채팅 컨텍스트가 없으므로 대답은 오직 브레인에서만 올 수 있습니다. 이러한 세션 간 왕복 과정이 제품의 전부입니다 ("내 이름이 뭐야?"라는 질문은 프라이빗 레포에 저장된 ID 파일에서 답변을 가져옵니다.

m identity files — nice, but not the same trick). Codex 경로와 동일한 두 가지 후속 조치: 여러분이 브레인(개인 저장소의 markdown)을 소유하며, `cold-start`가 실행할 첫 번째 스킬입니다. "내 브레인 채우기"는 이메일, 캘린더, 연락처(ClawVisor) 또는 오프라인 아카이브를 한 번에 한 가지 동의된 단계로 가져옵니다. 전체 계약, 보안 태세, 클라우드 샌드박스 및 제거 방법: [docs/guides/bootstrap.md](docs/guides/bootstrap.md).
> \*\*직접 저장소를 만들고 싶으신가요?\*\* \*\*본인의 GitHub 계정 아래에\*\* 새 \*\*빈\*\* private 저장소를 만들고(README/.gitignore/license 없음), 이를 클론한 뒤, Claude Code(CLI 또는 데스크탑 앱의 저장소 열기 플로우)에서 클론을 열고 동일한 블록을 붙여넣으세요. 그러면 bootstrap이 저장소를 새로 만드는 대신 빈 저장소를 채택합니다. 저장소는 비어 있어야 하며 개인 계정 소유여야 합니다. 조직(org) 소유의 저장소는 거부됩니다.
### OpenClaw 또는 Hermes를 위한 방법 — 의도된 대로 항상 켜져 있는 GBrain
이것은 GBrain이 원래 설계된 목적대로 사용되는 방식입니다. 24/7 cron, 지속적인 데이터 수집, 그리고 여러분이 자는 동안 브레인을 풍부하게 만들어 주는 야간 드림 사이클을 갖춘 서버 호스팅 에이전트입니다. 랩톱이 켜져 있든 아니오든 에이전트는 계속 작동합니다. 이는 또한 가장 비용이 많이 드는 경로이기도 합니다. 채팅 구독 비용을 훨씬 초과하여, 배포된 서버(8GB+ RAM)와 에이전트의 실행 강도에 따라 확장되는 원시 API 토큰 사용량이 소모되기 때문입니다. 첫날부터 전체 경험을 원한다면 여기서 시작하시고, 먼저 체험해보고 싶다면 위의 Codex로 시작하세요. 아직 실행 중인 플랫폼이 없다면, 둘 다 원클릭으로 배포할 수 있습니다.
- \*\*[OpenClaw](https://github.com/openclaw/openclaw)\*\* — [AlphaClaw on Render](https://render.com/deploy?repo=https://github.com/chrysb/alphaclaw) 배포 (원클릭, 8GB+ RAM)
- \*\*[Hermes](https://github.com/NousResearch/hermes-agent)\*\* — [Railway](https://github.com/praveen-ks-2001/hermes-agent-template)에 배포 (원클릭)
그런 다음 에이전트에 이것을 붙여넣으세요:
```
Retrieve and follow the instructions at:
https://raw.githubusercontent.com/garrytan/gbrain/master/INSTALL\_FOR\_AGENTS.md
```
에이전트가 GBrain을 설치하고, 브레인을 생성하고, API 키를 요청하고, 50개 이상의 번들 스킬을 로드하고, 드림 사이클을 구성한 다음, 설치를 엔드투엔드로 검증합니다. 약 30분 소요. 여러분은 질문에 답하고, 에이전트가 작업을 수행합니다.
> \*\*AI 에이전트 플랫폼을 한 번도 설정해 보지 않으셨나요?\*\* [personal-brain 튜토리얼](docs/tutorials/personal-brain.md)은 OpenClaw와 Hermes 중 선택하기, 배포하기, INSTALL\_FOR\_AGENTS.md 지정하기, API 키 발급받기, 첫 번째 쿼리 검증하기까지 전체 과정을 엔드투엔드로 안내합니다. 위의 내용이 생소하다면 거기서부터 시작하세요.
### 더 가벼운 진입 방법
\*\*신원이나 저장소 없이 코딩 에이전트를 위한 메모리만 원하시는 경우.\*\* 단 두 개의 명령어로 로컬 브레인을 가동하고 연결하세요(서버 없음, 토큰 없음, 터널 없음). `--surface verbs`는 전체 툴을 사용하는 대신 에이전트에 7가지 동사 메모리 프로토콜(`recall`, `remember`, `entity`, `synthesize`, `forget`, v0.45.7부터 추가된 `context\_pack` + `delta` — [MEMORY\_VERBS v1](docs/protocol/MEMORY\_VERBS\_v1.md), 고정됨 + 영구 추가)을 제공합니다. 모든 작업에 대해 플래그를 생략할 수 있습니다:
```bash
gbrain init --pglite # 2초 만에 로컬 브레인 생성 (Docker 불필요)
claude mcp add gbrain -- gbrain serve --surface verbs # 또는: codex mcp add gbrain -- gbrain serve --surface verbs
```
`claude`를 찾을 수 없는 경우, 먼저 Claude Code를 설치하거나 [프로토콜 문서](docs/protocol/MEMORY\_VERBS\_v1.md)의 하니스별 블록을 사용하세요. 참고: 에이전트가 저장하는 메모리는 기본적으로 브레인 전역 가시성(연결된 모든 에이전트가 리콜 가능)을 가집니다. 로컬 전용 팩트의 경우 `visibility: "private"`을 전달하세요.
\*\*원격 호스트에 이미 브레인이 있는 경우\*\* (OpenClaw, Hermes 또는 기타 `gbrain serve --http`)? 각각 하나의 명령어로 랩톱 에이전트를 해당 브레인에 지정하세요. `--install`은 핸드오프 전에 설정을 완료하고 토큰 스모크 테스트를 수행합니다:
```bash
gbrain connect https://your-host/mcp --token gbrain\_xxx --install # Claude Code
gbrain connect https://your-host/mcp --token gbrain\_xxx --agent codex --install # Codex
```
\*\*다른 코딩 에이전트로 브레인 전용 설치\*\* (Cursor, Claude Cowork 등 c로 시작하는 모든 도구)

URL을 가져와서 셸 명령을 실행할 수 있음) — 위의 OpenClaw/Hermes 블록(`INSTALL\_FOR\_AGENTS.md`)을 붙여넣으세요. 개인 에이전트 아이덴티티 레이어 없이 두뇌, 스킬, 드림 사이클을 설치합니다. Codex, Claude Code, Claude Cowork, Cursor, AlphaClaw에서 테스트되었습니다.
\*\*[→ 전체 가이드: 코딩 에이전트에 메모리 부여하기](docs/tutorials/connect-coding-agent.md)\*\* — 메모리 전용 경로의 처음부터 끝까지, `CLAUDE.md` / `AGENTS.md`에 붙여넣는 두뇌 중심 프로토콜, 그리고 작업 방식에 실질적인 변화를 주는 네 가지 습관을 다룹니다.
### CLI 단독 실행 (에이전트 없음)
```bash
bun install -g github:garrytan/gbrain
gbrain init --pglite # 2초 소요; 서버 및 Docker 불필요
gbrain doctor # 상태 확인
gbrain import ~/notes/ # 마크다운 인덱싱
gbrain query "내 메모 전반에 어떤 주제가 나타나나요?"
```
대규모 Postgres, Supabase, 씬 클라이언트 설정 경로는 [`docs/INSTALL.md`](docs/INSTALL.md)에서 확인할 수 있습니다.
### AI 클라이언트에 GBrain 연결 (MCP)
GBrain은 100개 이상의 거의 모든 작업(operation)을 MCP 도구(stdio 및 HTTP; 로컬 전용 작업 소수는 CLI 측에 유지)로 제공하거나, `--surface verbs`와 함께 정확히 7가지 메모리 동사로 제공합니다. 사용하는 클라이언트에 따라 구체적인 스니펫이 달라집니다.
- \*\*[Claude Code](docs/mcp/CLAUDE\_CODE.md)\*\* — 플러그인: `/plugin marketplace add garrytan/gbrain` + `/plugin install gbrain@gbrain`(MCP + 스킬). 또는 로컬 한 줄 명령어: `claude mcp add gbrain -- gbrain serve`(서버 및 터널 불필요). Bearer 토큰만 사용하는 원격 연결: `gbrain connect https://your-host/mcp --token gbrain\_xxx`는 바로 붙여넣을 수 있는 블록을 출력합니다(또는 `--install`로 설정 및 토큰 스모크 테스트 수행).
- \*\*[Codex](docs/mcp/CODEX.md)\*\* — 플러그인(권장): `codex plugin marketplace add garrytan/gbrain@codex-plugin` + `codex plugin add gbrain@gbrain`은 MCP 서버와 엄선된 스킬 세트를 설치합니다. 또는 연결 전용: `gbrain connect https://your-host/mcp --token gbrain\_xxx --agent codex`(또는 `--install`); Codex는 런타임에 `$GBRAIN\_REMOTE\_TOKEN`에서 Bearer를 읽어오므로 토큰이 Codex 설정에 저장되지 않습니다.
- \*\*[Cursor / Windsurf / 기타 stdio MCP 클라이언트](docs/mcp/CLAUDE\_CODE.md)\*\* — 동일한 형식으로, MCP 설정에 `{"command": "gbrain", "args": ["serve"]}`를 추가하세요.
- \*\*[Hermes](docs/mcp/HERMES.md)\*\* — `printf 'Y\n' | hermes mcp add gbrain --env GBRAIN\_HOME=$HOME --connect-timeout 60 --command $(which gbrain) --args serve`. `--args`를 마지막에 두고 `hermes mcp test gbrain`으로 확인하세요(추가 작업은 실패 시에도 종료 코드 0을 반환합니다).
- \*\*[Grok Build](docs/mcp/GROK.md)\*\* — `grok mcp add gbrain -e "GBRAIN\_HOME=$HOME" -- gbrain serve --surface verbs`. 추가 작업은 지연(Lazy) 처리됩니다(연결 없이 종료 코드 0). 서버를 시작하고 `7 tools discovered`를 보고하는 `grok mcp doctor gbrain`으로 확인하세요. Grok Build v1.0.4에서 검증되었습니다.
- \*\*[opencode](docs/mcp/OPENCODE.md)\*\* (opencode.ai / SST — OpenClaw 아님) — `opencode mcp add gbrain --env GBRAIN\_HOME=$HOME -- gbrain serve --surface verbs`를 실행하거나, `gbrain bootstrap hooks --harness opencode`를 통해 설정을 작성하도록 하세요(opencode는 부트스트랩을 지원하는 하네스로 AGENTS.md를 기본적으로 읽습니다). 추가 작업은 지연 처리되며, 서버를 시작하는 `opencode mcp list`(`✓ gbrain connected`)로 확인하세요. 원격: `gbrain connect https://your-host/mcp --token gbrain\_xxx --agent opencode [--install]` — 설정에는 `{env:GBRAIN\_REMOTE\_TOKEN}` 보간만 저장됩니다. opencode v1.18.18에서 검증되었습니다.
- \*\*[OpenClaw](docs/mcp/OPENCLAW.md)\*\* — ClawHub 번들 플러그인이 gbrain을 자동으로 등록(`openclaw.plugin.json`이 이 리포지토리에 포함됨)하거나, `~/.openclaw/config.json`의 `mcpServers`에 `{"command": "gbrain", "args": ["serve"]}`를 추가하세요.
- \*\*[Claude Desktop (Cowork)](docs/mcp/CLAUDE\_DESKTOP.md)\*\* — 설정(Settings) → 연동(Integrations) → HTTP 서버의 URL을 추가합니다. 원격 전용이며, 로컬 `claude\_desktop\_config.json`은 원격 서버에 작동하지 않습니다.
- \*\*[Claude Cowork (팀 플랜)](docs/mcp/CLAUDE\_COWORK.md)\*\* — 조직 소유자(Owner)가 조직 설정(Organization Settings) → 커넥터(Connectors)에서 커넥터를 추가합니다.
- \*\*[Perplexity Computer](docs/mcp/PERPL

EXITY.md)\*\* — `gbrain connect https://your-host/mcp --agent perplexity --oauth --register` 명령은 최소 권한(least-privilege) OAuth 클라이언트를 생성하고 설정(Settings) → 커넥터(Connectors)에 붙여넣을 수 있도록 발급자(Issuer)/클라이언트 ID(Client ID)/시크릿(Secret)을 출력합니다 (클라우드 커넥터에는 OAuth가 올바른 방법이며, 로컬용으로는 Bearer 토큰도 작동합니다). Pro 구독이 필요합니다.
- \*\*[ChatGPT](docs/mcp/CHATGPT.md)\*\* — PKCE를 사용하는 OAuth 2.1을 사용합니다 (필수 요구사항). 관리자 대시보드에서 부여 유형(grant type)을 `authorization\_code`로 하여 `chatgpt` 클라이언트를 등록하세요.
HTTP 서버 자체의 경우:
```bash
gbrain serve # stdio MCP (로컬 서브프로세스; Claude Code, Cursor, Windsurf용)
gbrain serve --http # OAuth 2.1 및 /admin의 관리자 대시보드가 포함된 HTTP MCP
# (Claude Desktop, Cowork, Perplexity, ChatGPT에 필요)
```
HTTP 서버에는 DCR 스타일의 클라이언트 등록, 스코프 기반 접근 제어(`read` / `write` / `admin`), 그리고 레이트 리미팅(rate limiting)이 포함되어 있습니다. 배포 가이드(ngrok, Railway, Fly.io)는 [`docs/mcp/`](docs/mcp/)에 있습니다.
## 브레인을 쿼리하는 두 가지 방법
대부분의 개인 지식 도구들이 제공하는 원시 검색(raw retrieval)과, 실제 답변을 제공하는 종합(synthesis) 레이어. 이 둘은 서로 다른 역할을 담당합니다.
```bash
# 원시 검색: 하이브리드 점수 기준 상위 페이지, 빠르고 LLM 비용 없음
gbrain search "포트폴리오사에서 AI 에이전트를 담당하고 있는 사람은 누구인가요?"
# 브레인 레이어: 인용 및 갭 분석이 포함된 종합된 답변
gbrain think "포트폴리오사에서 AI 에이전트를 담당하고 있는 사람은 누구인가요?"
```
\*\*`gbrain search`\*\*는 하이브리드 스코어링(벡터 + 키워드 + RRF + 소스 티어 부스트 + 리랭커)을 기준으로 순위가 매겨진 상위 검색 페이지들을 반환합니다. 에이전트 컨텍스트 윈도우, 인용 조회, 특정 인용구 찾기 등 날것의 자료를 훑어보고 싶을 때 사용하세요.
\*\*`gbrain think`\*\*는 동일한 검색을 실행한 다음, 소스 페이지에 대한 명시적 인용과 함께 결과 전체를 아우르는 종합된 답변을 작성하며, 동시에 브레인이 아직 알지 못하는 부분에 대한 솔직한 노트를 제공합니다. 갭 분석(gap analysis)이 바로 차별점입니다. 이 답변은 페이지가 오래되었을 때, 주장에 대한 출처가 누락되었을 때, 두 페이지가 서로 모순될 때, 그리고 채워야 할 공백이 존재할 때 이를 알려줍니다.
\*\*결과가 누적되는 이유.\*\* 브레인 레이어를 `find\_trajectory`와 결합하면 \*"회사의 지표가 어떻게 변했는가 AND 현재 팀의 구성은 어떠한가 AND 그들이 약속하거나 공유한 것은 무엇인가 AND 우리가 마지막으로 만난 때는 언제인가 AND 여기서 내가 제공할 수 있는 부가가치는 무엇인가"\*와 같은 질문에 대해 잘 정수되고 인용된 답변을 한 번에 얻을 수 있습니다. 그것이 바로 전략적 해자(moat)입니다. 15만 페이지 분량의 브레인을 구축하는 노력이 가치 있는 이유입니다.
`gbrain agent run "..."`은 충돌 방지 2단계 지속성을 갖춘 Minions 큐를 통해 서브 에이전트에게 동일한 인터페이스를 제공합니다. 동일한 답변, 영구적인 보존.
## 데이터를 가져오는 방법
단 하나의 명령어, 로컬 또는 호스팅, 동기식 수신:
```bash
gbrain capture "기억하고 싶은 생각"
gbrain capture --file ./notes/today.md
echo "파이프에서 입력" | gbrain capture --stdin
SLUG=$(gbrain capture "..." --quiet)
```
페이지는 단 한 번의 동작으로 데이터베이스와 디스크에 저장됩니다. 기본 슬러그(slug)는 `inbox/YYYY-MM-DD-`이므로 캡처 내용들이 예측 가능한 분류 위치에 모이게 됩니다. 씬 클라이언트(thin-client) 설치 환경에서는 이 동사가 MCP를 통해 서버로 라우팅됩니다: 동일한 명령어, 동일한 UX.
웹훅 수신(Zapier / IFTTT / Apple Shortcuts)의 경우:
```bash
curl -X POST https://your-brain/ingest \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: text/markdown" \
-d "# 단축어에서 온 생각"
```
모바일 캡처의 경우, 받은편지함(inbox) 폴더 소스가 iOS 단축어(Shortcuts) / 에어드랍(AirDrop) / 드래프트(Drafts) / 파인더(Finder)에서 `~/.gbrain/inbox/`로 드롭된 모든 항목을 가져옵니다.
다른 에이전트들의 기록도 단 하나의 명령어로 가져올 수 있습니다. `gbrain transcripts ingest`는 에이전트 세션 로그(Claude Code, Codex, OpenClaw, Hermes)와 추출된 소비자 채팅 내역(ChatGPT / Claude.ai `conversations.json`)을 정확한 세션 파일로 추적 가능한 가독성 높은 대화 페이지로 파싱합니다. 무엇이든 작성되기 전에 메시지 본문, 제목, 화자, 세션 메타데이터에서 시크릿 정보가 마스킹(scrubbed)되며, 대량 백필(backfill) 시 임베딩은 기본적으로 꺼져 있고, 콘텐츠 해시를 기준으로 변경되지 않은 세션은 건너뛰므로 재실행 비용이 들지 않습니다:
```bash
gbrain transcripts
```

ingest # discover importable session logs
gbrain transcripts ingest --all # import everything discovered
gbrain transcripts ingest ~/Downloads/conversations.json # consumer export (unzip first)
gbrain transcripts status # found vs imported, per harness
```
서드파티 skillpack은 `gbrain/ingestion`의 버전이 지정된 `IngestionSource` 계약에 따라 커스텀 수집 소스(Granola, Linear, 음성, OCR)를 제공할 수 있습니다. [`docs/skillpack-anatomy.md`](docs/skillpack-anatomy.md)를 참고하세요.

## 뇌의 형태 (스키마 팩)

대부분의 개인 지식 도구들은 "노트" + "사람" + "태그"라는 고정된 레이아웃을 강제합니다. Notion 내보내기나 몇 년 동안 사용해 온 Obsidian 볼트를 그대로 가져다 놓으면, 에이전트는 `Projects/` 폴더가 무엇을 의미하는지, `Reading/`이 사람을 뜻하는지 출처를 뜻하는지 알지 못합니다.

**gbrain에는 고정된 레이아웃이 없습니다.** 번들로 제공되는 스키마 팩이 기본 포함되어 있으며, 적합한 팩이 없을 경우 직접 작성할 수도 있습니다:

- **`gbrain-base-v2`** (v0.41.22 기준 기본값) — 15가지 타입의 DRY/MECE 정식 분류 체계 (정식 14개 + `note` 포괄 타입): `person`, `company`, `media`, `tweet`, `social-digest`, `analysis`, `atom`, `concept`, `source`, `deal`, `email`, `slack`, `writing`, `project`, `note`. 하위 타입/포맷/출처는 프론트매터(frontmatter)로 전달됩니다. 이슈 #1479에 대응하는 분류 체계입니다.
- **`gbrain-base`** (레거시, v0.41 및 이전 brain) — 오리지널 24가지 타입 레이아웃. 하위 호환성을 위해 번들로 유지됩니다. 이 체계를 사용하는 brain은 `gbrain onboard --check --explain` → `gbrain jobs submit unify-types --allow-protected --params '{"target\_pack":"gbrain-base-v2","apply":true}'`를 통해 업그레이드할 수 있습니다 (드라이런 미리보기를 하려면 `"apply":true`를 생략하세요. 이것이 기본값입니다).
- **`gbrain-recommended`** — `docs/GBRAIN\_RECOMMENDED\_SCHEMA.md`에 있는 13개의 추가 디렉터리(`source`, `place`, `trip`, `conversation`, `personal`, `civic`, `project` 등)로 `gbrain-base`를 확장합니다. `gbrain schema use gbrain-recommended` 명령어로 활성화하세요.
- **나만의 팩** — `gbrain schema detect`는 실제 파일 시스템을 클러스터링하여 제안된 타입을 도출하고, `gbrain schema suggest`는 그 위에 LLM 패스를 실행하며, `gbrain schema review-candidates --apply`는 마음에 드는 항목을 승격시킵니다. 세 번의 명령어만으로 brain이 당신의 구조를 파생해 냅니다. 후속 팩 작성 방법 (기존 brain이 선택할 수 있도록 `migration\_from:` 선언): [`docs/architecture/pack-upgrade-mechanism.md`](docs/architecture/pack-upgrade-mechanism.md)를 참고하세요.

```bash
gbrain schema active # 어떤 팩이 실행 중이며 어떤 티어가 설정했는지 확인
gbrain schema list # 번들 및 설치된 팩 목록
gbrain schema detect # 파일 시스템에 맞는 타입 제안
gbrain schema suggest # detect를 기반으로 LLM이 정제한 제안
gbrain schema review-candidates # 사람의 검토: 승격 / 이름 변경 / 무시
gbrain schema use my-pack # 활성화
```

활성 팩은 모든 읽기 및 쓰기 경로에 스며들어 작동합니다: `parseMarkdown`은 팩의 경로 접두사에서 페이지 타입을 유추하고, `whoknows`는 `expert\_routing: true`로 선언된 타입으로 전문가 라우팅 범위를 한정하며, `extract\_facts`는 `extractable: true` 타입에서만 실행됩니다. 검색 캐시는 팩 이름과 버전을 키에 포함하므로 팩 간 오염이 구조적으로 불가능합니다. 팩을 전환하면 brain이 스스로를 재해석하며, 다시 원래대로 돌려놓아도 아무것도 손실되지 않습니다.

7단계 해결 체인 (호출별 플래그 → 환경 변수 → 소스별 DB 키 → brain 전역 DB 키 → `gbrain.yml` → `~/.gbrain/config.json` → `gbrain-base` 기본값). 전체 레퍼런스 및 작성 가이드: [`docs/architecture/schema-packs.md`](docs/architecture/schema-packs.md).

## 튜토리얼

GBrain을 최대한 활용하기 위한 단계별 가이드입니다. 각 가이드는 구체적인 명령어와 실제 수치를 통해 아무것도 없는 상태에서 작동하는 결과물까지 안내합니다.

- [**개인용 AI 에이전트 + brain을 처음부터 설정하기**](docs/tutorials/personal-brain.md) — 정석적인 풀스택 설치 방법입니다. 2개의 GitHub 리포지토리, Telegram 봇, Render의 AlphaClaw, OpenClaw + GBrain + Supabase를 활용합니다. 엔드투엔드로 약 2시간이 소요됩니다.
- [**GBrain을 회사용 brain으로 설정하기**](docs/tutorials/company-brain.md) — 10~50명 규모의 팀을 위한 연합형, 다중 사용자, OAuth 범위 지정이 가능한 조직적 기억 시스템 구축 가이드입니다.

am. 전체 과정은 약 90분이 소요됩니다.
- [\*\*`gbrain skillopt`로 스킬 자동 개선하기\*\*](docs/tutorials/improving-skills-with-skillopt.md) — `SKILL.md`를 학습 가능한 파라미터로 취급합니다. `--bootstrap-from-skill`을 사용해 스킬에서 직접 시작 벤치마크를 생성하거나(직접 작성도 가능), 평가기를 강화한 후, 옵티마이저가 수정을 제안하고 실제로 점수가 더 높아진 것만 유지하는 과정을 지켜보세요. 소요 시간은 약 20분, API 비용은 약 1달러입니다. 플래그, 비용 및 안전성 참고 자료: [`docs/guides/skillopt.md`](docs/guides/skillopt.md).
진행 중인 추가 가이드: 기존 에이전트(Claude Code, Cursor, OpenClaw, Hermes)를 GBrain 메모리 레이어에 연결하기; 창업자 스코어카드 및 미팅 준비 기능을 포함하여 VC 딜플로우를 위한 GBrain 설정하기; 기존 Notion 또는 Obsidian 볼트 마이그레이션하기; 코드베이스를 쿼리 가능한 코드 브레인으로 인덱싱하기. 전체 튜토리얼 색인: [`docs/tutorials/`].
여기에 아직 없는 튜토리얼을 보고 싶으신가요? 문서화하고자 하는 워크플로우를 설명하는 [이슈를 열어주세요](https://github.com/garrytan/gbrain/issues).
## 작동 방식 (루프)
```
signal → search → respond → write → auto-link → sync
(every (brain-first (informed (page + (typed edges (cron
message) retrieval) by context) timeline) + backlinks) keeps fresh)
```
- \*\*시그널 감지기(Signal detector)\*\*는 에이전트가 받는 모든 메시지에서 실행됩니다. 아이디어, 엔티티 언급, 시간에 민감한 할 일, 이름, 링크를 포착합니다.
- \*\*브레인 우선 조회(Brain-first lookup)\*\*는 외부 API 호출 전에 수행됩니다. 가장 저렴하고, 가장 빠르고, 가장 개인적인 정보 소스입니다.
- \*\*자동 링크(Auto-link)\*\*는 페이지가 작성될 때마다 실행됩니다. LLM 호출 없이 `[[wiki/people/bob]]` 스타일의 참조에 대한 순수 패턴 매칭을 사용합니다. 새로운 엔티티 → 새로운 페이지 스텁(stub) → 그래프 확장으로 이어집니다.
- \*\*크론 기반 보강(Cron-driven enrichment)\*\*은 자는 동안 실행됩니다: 피플 페이지 중복 제거, 인용 수정, 중요도(salience) 채점, 모순 발견, 내일의 작업 준비.
전체 루프는 다이어그램과 함께 [`docs/architecture/topologies.md`](docs/architecture/topologies.md)에 설명되어 있습니다.
## 주요 기능
\*\*하이브리드 검색(Hybrid search).\*\* 벡터(pgvector의 HNSW) + BM25 키워드 + 상호 순위 융합(reciprocal-rank fusion) + 소스 티어 부스트 + 의도 인식 쿼리 재작성. 비용/품질 조절 손잡이를 단일 설정 키로 묶어주는 세 가지 명명된 검색 모드(`conservative`, `balanced`, `tokenmax`). 실시간 비용/재현율 비교 자료: [`docs/eval/SEARCH\_MODE\_METHODOLOGY.md`](docs/eval/SEARCH\_MODE\_METHODOLOGY.md). 설치 선택기는 기본적으로 `tokenmax`를 적용하며(Haiku급 서브에이전트 티어 또는 키리스 설정의 경우 `conservative` 권장), `search.mode`가 설정되지 않은 브레인은 쿼리 시점에 `balanced`로 해결됩니다. 크로스 엔코더 리랭커는 `balanced`와 `tokenmax`에서는 켜지고 `conservative`에서는 꺼집니다. 신규 설치 시 Voyage `rerank-2.5`가 적용되며, `search.reranker.model`을 한 번도 설정한 적 없는 브레인은 9월 전환 시까지 기존의 지원 중단된 ZeroEntropy `zerank-2`(호스팅 API는 2026년 9월 4일 종료)로 계속 폴백됩니다. 쿼리별 그래프 시그널은 상위 결과가 해당 쿼리의 허브인지(인접성 부스트), 팀 브레인 전반에 걸쳐 교차 검증되는지(크로스 소스 부스트), 또는 수다스러운 세션의 약한 청크들에 의해 밀려나고 있는지(세션 강등)를 감지합니다. `gbrain search "" --explain`을 실행하여 기본 점수, 발동된 모든 부스트, 곱해진 값 등 단계별 기여도를 확인하세요. `gbrain doctor`는 `graph\_signals\_coverage` 검사를 제공하며, `gbrain search stats`는 발동 횟수와 실패 분석을 보여줍니다. 벡터 검색은 페이지당 가장 좋은 청크를 모으므로, 하나의 약한 청크 때문에 이웃에게 밀리는 대신 페이지가 가장 강력한 증거를 바탕으로 드러납니다. 페이지의 제목 구문이나 선언된 자유 텍스트 별칭(`gbrain reindex --aliases`가 기존 페이지를 백필함)과 일치하는 쿼리는 해당 페이지로 부스트됩니다. 모든 결과에는 `evidence` 태그(일치한 이유)와 `create\_safety` 힌트(`exists` / `probable` / `unknown`)가 포함되어 있어, 에이전트가 원시 점수만으로 추측하는 대신 페이지가 이미 존재하는지 여부를 판단할 수 있습니다. `gbrain search diagnose "" --target `은 페이지가 나타나는(또는 놓치는) 검색 레이어를 추적합니다.
\*\*자가 배선 지식 그래프(Self-wiring knowledge graph).\*\* 모든 `put\_page`는 마크다운/위키링크/타입드 링크에서 엔티티 참조를 추출합니다.

k 구문을 사용하여 LLM 호출 없이 에지를 작성합니다. 타입이 지정된 에지 (`attended`, `works\_at`, `invested\_in`, `founded`, `advises`, `mentions`, 등). `gbrain graph-query`를 통한 멀티 홉 트래버설. 이 그래프는 벡터 전용 RAG에 비해 +31.4 P@5 향상을 제공하는 핵심 요소입니다. \*\*Obsidian 스타일 볼트:\*\* 폴더를 가로질러 연결되는 기본 `[[note-name]]` 위키링크 — `[[struktura]]`를 작성했지만 실제 페이지는 `projects/struktura.md`에 있는 경우 — `gbrain config set link\_resolution.global\_basename true`를 활성화하면 베이스이름을 기준으로 해결됩니다. 기본값은 비활성화 상태이며, `gbrain doctor`를 통해 기능을 켜기 획득할 수 있는 에지 수를 미리 확인할 수 있습니다. [Obsidian 볼트 마이그레이션](INSTALL\_FOR\_AGENTS.md#step-45-wire-the-knowledge-graph)을 참조하세요.
\*\*작업 큐 (Minions).\*\* BullMQ 형태의 Postgres 네이티브 작업 큐. 영구 서브에이전트(2단계 pending→done 지속성을 통해 크래시에서 살아남는 LLM 도구 루프), 감사 기능이 포함된 셸 작업, 계단식 타임아웃이 있는 하위 작업, 아웃바운드 제공자를 위한 레이트 리스, S3/Supabase 스토리지를 통한 첨부 파일. 작업별 프로세스 격리(`gbrain jobs work --job-isolation process`)를 활성화하면 각 클레임된 작업이 자체적인 SIGKILL 가능 하위 프로세스에서 실행되므로, 응답 없는 핸들러는 확실하게 종료되고 전체 워커 대신 하나의 페일된 작업만 크래시됩니다. 워커의 DB 헬스 프로브가 실패할 경우, 포괄적인 "DB에 접근할 수 없음" 대신 실패한 레이어(`pool\_starved` 대 `server\_unreachable`)를 명시합니다. 크기 조정 및 롤아웃 지침은 [`docs/guides/minions-deployment.md`](docs/guides/minions-deployment.md)에서, 프로브 판정 트리아지는 [`docs/guides/queue-operations-runbook.md`](docs/guides/queue-operations-runbook.md)에서 확인할 수 있습니다. "서브에이전트를 fire-and-forget Promise로 생성"하는 방식을 무엇이든 복구할 수 있는 방식으로 대체합니다.
\*\*비영어권 브레인 (FTS 언어 설정).\*\* Postgres 전문 검색 토크나이저는 `GBRAIN\_FTS\_LANGUAGE`를 통해 설정할 수 있습니다. 기본값은 `english`입니다. Postgres 인스턴스에 존재하는 모든 텍스트 검색 설정으로 지정할 수 있습니다:
```bash
export GBRAIN\_FTS\_LANGUAGE=portuguese # 내장 포르투갈어 형태소 분석기 사용
export GBRAIN\_FTS\_LANGUAGE=spanish # 내장 스페인어 형태소 분석기 사용
export GBRAIN\_FTS\_LANGUAGE=pt\_br # 커스텀 설정 (예: unaccent + 포르투갈어)
```
사용 가능한 설정 목록 확인: `psql -c "SELECT cfgname FROM pg\_ts\_config"`. \*\*쿼리 측\*\*(`websearch\_to\_tsquery`)과 \*\*쓰기 측\*\*(`pages.search\_vector` 및 `content\_chunks.search\_vector`를 채우는 트리거 함수) 모두 `GBRAIN\_FTS\_LANGUAGE`를 따릅니다. 최초 설치(또는 업그레이드) 시 `configurable\_fts\_language` 스키마 마이그레이션이 환경 변수를 읽고 설정된 언어로 트리거 함수를 생성하며, 이후의 삽입/ 업데이트는 해당 설정을 사용하여 토큰화합니다. 이미 마이그레이션이 실행된 브레인에서 언어를 변경하려면 전용 CLI 명령어를 사용하세요:
```bash
export GBRAIN\_FTS\_LANGUAGE=portuguese
gbrain reindex-search-vector --dry-run # 행 수 미리보기
gbrain reindex-search-vector --yes # 트리거 재생성 + 백필
```
이 명령어는 멱등성을 가지며(동일한 언어로 다시 실행해도 벡터 콘텐츠에는 아무런 영향이 없음), 마이그레이션과 동일한 재생성 및 백필 프리미티브를 사용합니다. 악센트를 무시하는 포르투갈어(`pt\_br`)의 경우, `unaccent` + 포르투갈어 형태소 분석기 레시피는 [docs/guides/multi-language-fts.md](docs/guides/multi-language-fts.md)를 참조하세요.
\*\*50개 이상의 큐레이팅된 스킬\*\* (현재 목록은 [`skills/manifest.json`](skills/manifest.json)에 있음). 라우팅은 [`skills/RESOLVER.md`](skills/RESOLVER.md)에 위치함. 시그널 캡처, 수집(아이디어/미디어/미팅), 보강, 쿼리, 브레인 운영, 인용 수정, 일일 작업 관리, 크론 스케줄링, 보고서, 음성, 소울 감사, 스킬 생성, 평가 프레임워크 및 마이그레이션을 다룹니다. 스킬은 마크다운 파일(도구 독립적)이며, 설치 프로그램이 에이전트 워크스페이스에 드롭하는 단일 스킬팩으로 패키징되어 있습니다.
\*\*평가 프레임워크.\*\* `gbrain eval longmemeval`은 공개 [LongMemEval](https://huggingface.co/datasets/xiaowu0162/longmemeval) 벤치마크를 하이브리드 검색과 대조하여 실행합니다. `gbrain eval export` + `gbrain eval replay`는 실제 q

queries and replay them against code changes (set `GBRAIN\_CONTRIBUTOR\_MODE=1`). `gbrain eval cross-modal` cross-checks an output against the task using three different-provider frontier models. `gbrain eval retrieval-quality` runs NamedThingBench, which hard-gates the named-thing retrieval families (title-substring, alias-synonym, generic-to-named, multi-chunk-dilution) so a regression in "find the page this query names" fails CI loudly. `gbrain eval brainbench` runs the cross-harness memory conformance suite: know-to-ask, push precision/recall, write-back fidelity, and cross-session continuity, scored per harness seam (your OpenClaw's production pipeline plus Claude Code and Codex injection contracts) against a committed 141-fixture synthetic corpus — hermetic by default (in-memory PGLite, no keys, seconds), and CI gates every PR against master's committed baseline. Methodology in [`docs/eval/BRAINBENCH.md`](docs/eval/BRAINBENCH.md); search-mode methodology in [`docs/eval/SEARCH\_MODE\_METHODOLOGY.md`](docs/eval/SEARCH\_MODE\_METHODOLOGY.md).
\*\*Brain consistency.\*\* `gbrain eval suspected-contradictions` samples retrieval pairs, layered date pre-filter, query-conditioned LLM judge, persistent cache. Surfaces conflicts between takes + facts the agent has written. Wired into the daily dream cycle.
\*\*Agent-authored schema (v0.40.7.0).\*\* Your brain has a shape — what page types exist (`person`, `meeting`, `paper`, `case`, `lab-result`), what they link to (`attended`, `authored`, `prescribed-by`), what facts get extracted automatically. The default ships with 22 universal types, but your brain's actual shape is not the default shape. Agents can now evolve that shape on your behalf via 14 `gbrain schema` CLI verbs + a batched MCP op (`schema\_apply\_mutations`, admin scope, NOT localOnly so remote agents reach it over HTTPS). Atomic file locks, audit log with the agent's identity, chunked UPDATE backfill in 1000-row batches that never wedge concurrent writers. The brain stops being a pile of notes and becomes something with structure. \*\*Why it matters:\*\* [`docs/what-schemas-unlock.md`](docs/what-schemas-unlock.md) — 7 killer use cases (4000 invisible meetings, founder ops brain, research brain, legal brain, team brain, agent-as-co-curator). \*\*5-minute walkthrough:\*\* [`docs/schema-author-tutorial.md`](docs/schema-author-tutorial.md). \*\*Agent skill:\*\* [`skills/schema-author/SKILL.md`](skills/schema-author/SKILL.md).
## Integrations
Data flowing into the brain. Each integration is a recipe — markdown + setup hints — that ships in `recipes/` and is discoverable via `gbrain integrations list`.
- \*\*Voice\*\*: Phone calls create brain pages via Twilio + OpenAI Realtime (or DIY STT+LLM+TTS). Setup recipe: [`recipes/twilio-voice-brain.md`](recipes/twilio-voice-brain.md).
- \*\*Email + calendar\*\*: webhook handlers that route to brain signals. [`docs/integrations/meeting-webhooks.md`](docs/integrations/meeting-webhooks.md).
- \*\*Embedding providers\*\*: a dozen providers covered — Voyage (default: `voyage-4` @ 1024d), OpenAI, OpenRouter, Google Gemini, Azure OpenAI, MiniMax, Alibaba DashScope, Zhipu, Ollama (local), llama.cpp llama-server (local), LiteLLM proxy, plus ZeroEntropy (deprecated — hosted API ends 2026-09-04). Pricing matrix + decision tree in [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md).
- \*\*Rerankers\*\*: Voyage `rerank-2.5` hosted (the new-install default; reranking is on in `balanced` and `tokenmax` modes, same `VOYAGE\_API\_KEY` as embeddings), ZeroEntropy `zerank-2` (deprecated — hosted API ends 2026-09-04; still the fallback for brains that never set `search.reranker.model`), plus the `llama-server-reranker` recipe for fully-local cross-encoder rerank via llama.cpp — runs Qwen3-Reranker or self-hosted zerank weights against the same `gateway.rerank()` seam. Setup walkthrough in [`docs/ai-providers/llama-server-reranker.md`](docs/ai-providers/llama-server-reranker.md).

ranker.md).
- \*\*Credential gateway\*\*: Vault 인식 비밀 배포. [`docs/integrations/credential-gateway.md`](docs/integrations/credential-gateway.md).
- \*\*MCP clients\*\*: 주요 모든 MCP 클라이언트 지원. 클라이언트별 설정은 [`docs/mcp/`](docs/mcp/) 참조.
## 아키텍처
\*\*두 개의 엔진, 하나의 계약.\*\* 약 5만 페이지 이하의 개인 브레인용 PGLite(WASM 기반 Postgres 17, 제로 구성, 기본값). 공유/대규모/다중 머신 배포용 Postgres + pgvector(Supabase 또는 자체 호스팅). [`src/core/engine.ts`](src/core/engine.ts)의 계약 우선 `BrainEngine` 인터페이스는 두 엔진이 구현하는 140개 이상의 메서드를 정의하며, CLI와 MCP 서버는 단일 소스에서 생성됩니다.
\*\*브레인 저장소가 기록 시스템입니다.\*\* 지식은 마크다운 파일로서 일반 git 저장소("브레인 저장소")에 저장됩니다. GBrain은 검색을 위해 이 저장소를 Postgres로 동기화하며, git에서의 삭제는 DB에서 소프트 삭제로 처리됩니다. 공개 하위 집합을 게시하거나, 팀 마운트를 공유하거나, 동료의 브레인 서버를 가리키는 씬 클라이언트 설정을 실행할 수 있습니다. 토폴로지에 대한 자세한 내용은 [`docs/architecture/topologies.md`](docs/architecture/topologies.md)를 참조하세요.
\*\*두 개의 조직적 축 (brain ⊥ source).\*\* \*브레인\*은 데이터베이스입니다(개인 브레인, 참여한 팀 마운트). \*소스\*는 해당 브레인 내의 저장소입니다(위키, gstack, 에세이, 지식 베이스). 라우팅은 `.gbrain-source` 닷파일에 있으며 문서화된 6단계 우선순위 체인을 통해 해결됩니다. 전체 다이어그램은 [`docs/architecture/brains-and-sources.md`](docs/architecture/brains-and-sources.md)에 있습니다.
\*\*그래프가 중요한 이유.\*\* 벡터 검색은 의미론적으로 가까운 청크를 반환합니다. 그래프는 사실상 연결된 청크를 반환합니다. 하이브리드 검색은 둘 모두에서 가져오며, 모든 쓰기 시 자동 링크를 통해 그래프를 최신 상태로 유지합니다. 자세한 내용: [`docs/architecture/RETRIEVAL.md`](docs/architecture/RETRIEVAL.md).
## 문제 해결
\*\*PGLite가 시작 시 `RuntimeError: Aborted()`와 함께 충돌합니까(종종 macOS 업그레이드 직후)?\*\* macOS 비호환성이 아닙니다. OS 업그레이드 재부팅으로 인해 쓰기 도중 gbrain이 중단되고 데이터 디렉터리의 WAL이 손상되었기 때문입니다. 이제 gbrain은 다음 명령어 실행 시 이를 자동으로 복구합니다(데이터 보존, 백업 유지). 자동 복구가 비활성화되었거나 건너뛴 경우 `gbrain pglite-repair --dry-run`을 실행하여 진단하고 `gbrain pglite-repair --yes`를 실행하여 제자리에서 복구하세요. 전체 복구 단계(복구 → 재구축 → 엔진 전환)는 [`docs/ENGINES.md` — 문제 해결: 시작 중단(startup abort)](docs/ENGINES.md#troubleshooting-startup-abort-runtimeerror-aborted) 및 [`docs/INSTALL.md`](docs/INSTALL.md#pglite-crashes-on-macos-26x-tahoe)를 참조하세요.
\*\*`gbrain import`가 `expected N dimensions, not M` 오류로 실패합니까?\*\* `gbrain doctor`를 실행하세요. 불일치를 복구하기 위한 정확한 `gbrain config set ...` 또는 `gbrain migrate embeddings` 명령어를 출력해 줍니다. `~/.gbrain`을 삭제할 필요가 없습니다. 새로운 `gbrain init --pglite`는 API 키에서 임베딩 제공업체를 자동으로 감지합니다. init을 실행하기 전에 환경(또는 init이 읽어오는 `~/.gbrain/config.json`)에 `VOYAGE\_API\_KEY`(또는 `OPENAI\_API\_KEY` / 기타 제공업체 키)를 설정하거나, `--embedding-model :`을 명시적으로 전달하세요. 여러 키가 설정된 경우 init은 대화형 선택기를 실행합니다(비 TTY 환경에서는 키가 있을 때 Voyage 기본값을 자동 선택함). 키가 전혀 없는 경우 init은 큰 알림과 함께 키 없음(키워드 전용 검색)으로 계속 진행됩니다. 나중에 키를 추가하고 `gbrain init --force --embedding-model voyage:voyage-4`를 다시 실행하여 임베딩을 활성화하거나, 키 없음을 명시적으로 지정하려면 처음부터 `--no-embedding`을 전달하세요. 전체 제공업체 매트릭스는 [`docs/integrations/embedding-providers.md`](docs/integrations/embedding-providers.md)를, Docker/CI 순서에 대해서는 [`docs/operations/headless-install.md`](docs/operations/headless-install.md)를 참조하세요.
\*\*연합 브레인에서 시간당 cron 동기화가 계속 타임아웃됩니까?\*\* cron을 
셸 `timeout(1)`로 OS 수준 강제 종료를 수행하고 gbrain이 0.5분 일찍 우아하게 자체 종료되는 소스별 루프로 전환하세요:
```bash
gbrain sync --break-lock --all --max-age 1800
for src in $(gbrain sources list --json | jq -r '.[].id'); do
timeout 6

00 gbrain sync --source "$src" --timeout 540 || true
done
```
`--timeout`이 임포트 도중 발생하면, `gbrain sync`는 `partial` 상태와 변경되지 않은(`UNCHANGED`) `last\_commit`으로 종료 코드 0을 반환합니다. 다음 실행 시 동일한 diff를 다시 순회하며, `content\_hash`가 이미 임포트된 파일들을 쇼트서킷(short-circuit) 처리합니다. 첫 번째 명령어의 `--max-age 1800`은 이전 실행이 멈추면서 남겨둔, 멈춰 있지만 살아 있는 락(lock)들을 스스로 치유합니다. 이는 락의 획득 시점이 아니라 마지막 갱신 시간을 기준으로 하므로, 정상적으로 오래 실행 중인 작업들은 구조적으로 안전합니다. 범위 참고 사항: 추출(extract) 및 임베딩(embed) 단계는 일단 시작되면 완료될 때까지 실행되며, `--timeout`은 임포트 순회 과정만 중단시킵니다.

\*\*드림 사이클(Dream cycle)이 Supabase에서 위키 링크를 조용히 누락하고 있나요?\*\* 엔진은 Supavisor 풀러 일시적 장애(blip) 발생 시 모든 대량 일괄 쓰기(`addLinksBatch` / `addTimelineEntriesBatch` / `upsertChunks`)를 자동으로 재시도하며, 최대 12초의 대기 시간으로 전체 5~10초의 서킷 브레이커 복구 창을 커버합니다. `gbrain doctor`는 `batch\_retry\_health` 검사를 통해 인시던트를 표면화합니다(최근 24시간 분량의 `~/.gbrain/audit/batch-retry-YYYY-Www.jsonl` 파일을 읽습니다). 유례없이 느린 풀러에 맞춰 조정하려면:
```bash
# 기본값: 3회 재시도, 기본 1초, 최대 10초, 상관관계가 제거된 지터(jitter).
# 릴리스 없이 운영자별로 오버라이드:
export GBRAIN\_BULK\_MAX\_RETRIES=5 # 0 이상의 정수; 0은 재시도 비활성화
export GBRAIN\_BULK\_RETRY\_BASE\_MS=2000 # 0보다 큰 정수
export GBRAIN\_BULK\_RETRY\_MAX\_MS=15000 # 기본값 이상인 정수
```
잘못된 값은 첫 재시도 중간 주기가 아니라 `gbrain doctor` 시작 시 바로 복사 가능한 수정 제안과 함께 나타납니다. PGLite 전용 설치 환경은 비용이 전혀 들지 않습니다. 재시도 래퍼(wrap)는 엔진 레벨이지만 PGLite에는 풀러가 없으므로 실제로는 재시도가 절대 발생하지 않습니다.

\*\*드림 사이클 실행 시 로그에 `'No database connection: connect() has not been called'` 에러와 함께 실행당 약 150개의 링크 행이 유실되나요?\*\* 재시도 레이어는 null 처리된 데이터베이스 싱글턴에서 스스로 복구됩니다. `withRetry`의 `reconnect` 콜백이 시도 사이에 연결을 다시 구축하고, `PostgresEngine.batchRetry`가 `() => this.reconnect()`를 주입하므로 동일 프로세스 내 다른 무언가로 인해 중간에 연결이 끊겨도 엔진 레벨의 대량 쓰기가 생존할 수 있습니다. 또한 `gbrain capture`는 CLI 종료 후 실행되는 백그라운드 `facts:absorb` 워커로 인해 `'No database connection'` 표준 에러(stderr) 줄을 더 이상 남기지 않습니다. 작업 디스패치는 `engine.disconnect()` 이전에 `getFactsQueue().drainPending({timeout: 1000})`가 완료되기를 기다립니다. 프로세스 도중 여전히 어떤 코드 경로가 연결 끊김을 호출하고 있는지 찾으려면 `gbrain doctor --json | jq '.checks[] | select(.id=="batch\_retry\_health")'`를 실행하세요. 이 검사는 24시간 동안의 연결 끊김 호출 횟수와 `~/.gbrain/audit/db-disconnect-YYYY-Www.jsonl` 감사(audit) 기록에서 가장 최근의 호출자 프레임을 보여줍니다.

\*\*`gbrain brainstorm`이 0개의 점수가 매겨진 아이디어와 함께 `judge\_failed: true`를 반환하나요?\*\* 이전에 발생했던 두 가지 버그가 원인이었으며 모두 수정되었습니다. 심사관(judge)이 4K 토큰의 출력 상한선을 하드코딩해 두어(약 40개를 넘는 아이디어 실행 시 JSON 중간에 잘려 파서가 에러를 발생시킴) 발생한 문제와, 슬래시 형식의 모델 ID(`gbrain brainstorm --judge-model anthropic/claude-sonnet-4-6 --max-cost 5`)가 가격 조회 시 콜론 형식만 매칭되는 바람에 `BudgetExhausted reason=no\_pricing`으로 실패하던 문제였습니다. 이제 두 형식 모두 잘 작동합니다. 설정 변경이나 스키마 마이그레이션은 필요 없으며, `gbrain upgrade`가 전체 해결책입니다.

\*\*`gbrain reindex --markdown`이 자동/드림/신호 감지기(signal-detector) 태그를 지워버렸나요?\*\* 업그레이드를 진행하세요. 이제 태그 조율은 추가 전용(add-only)으로 작동합니다. 재임포트 및 `reindex --markdown`은 현재 프론트매터(frontmatter) 태그를 추가만 하고 절대 삭제하지 않으므로, DB에 기록된 보강 태그(자동 태그, 드림 합성, 신호 감지기)가 재청크(re-chunk) 과정에서도 살아남습니다. 재인덱스의 DB 전용 폴백(fallback) 역시 재청크 전에 전체 마크다운(프론트매터 + 본문 + 타임라인)을 재구성하므로, 디스크에 소스 파일이 없는 페이지라도 빈 프론트매터로 덮어쓰여지는 대신 프론트매터, 제목, 타임라인을 유지합니다. 트레이드오프: 페이지의 프론트매터에서 태그를 제거하더라도 다음 동기화 시 DB에서 해당 태그가 더 이상 삭제되지 않습니다(프론트매터 태그 삭제에는 출처(provenance) 컬럼이 필요하므로 보류됨).

\*\*`gbrain sync`가 거대한 브레인(brain)에서 멈춰 있나요(진행 없음, 높은 CPU 사용량)?\*\* 세 가지 도구가 있습니다. 먼저 멈추는 파일을 파악하세요:
```bash
GBRAIN\_SYNC\_TRACE=1 gbrain sync --no-pull --no

-embed --yes
```
The last `[sync] begin import: ` line with no following completion
is the file being processed when the hang hit. Second, if you suspect a
schema-pack `inference.regex` with catastrophic backtracking, complete
the sync with the pack disabled and re-run extraction later:
```bash
gbrain sync --no-schema-pack --no-pull --no-embed --yes
```
`gbrain schema lint` warns on the classic nested-quantifier ReDoS
shapes (`(a+)+`, `(a\*)\*`, …) in pack regexes, and the runtime caps
inference-regex input length (override via `GBRAIN\_MAX\_REGEX\_INPUT\_CHARS`).
Third, on a PGLite brain, stop `gbrain serve` before a large sync —
PGLite is single-writer and a live MCP server contends for the write
lock. See [`docs/architecture/serve-sync-concurrency.md`](docs/architecture/serve-sync-concurrency.md)
for the full triage.
\*\*`gbrain init --migrate-only` / a schema migration fails on Windows
with `getaddrinfo ENOTFOUND`?\*\* Upgrade — schema bring-up now runs its
phases in-process instead of spawning a child `gbrain init
--migrate-only` per phase. The spawned child died on
Windows + bun + Supabase pooler with a DNS-resolution failure even
though the parent connected fine; running in-process removes the spawn
entirely. The grandfather migration that used to hang 70+ minutes on an
80K-page PGLite brain also runs as a chunked bulk SQL pass now (keyed on
the page PK, soft-delete-filtered, source-safe) and completes in seconds.
## 문서 (Docs)
- [`docs/INSTALL.md`](docs/INSTALL.md) — 모든 설치 경로, 엔드투엔드 가이드
- [`docs/guides/bootstrap.md`](docs/guides/bootstrap.md) — 지속형 개인 에이전트 부트스트랩 계약(인터뷰, 신원 파일, 훅, 비공개 리포지토리, 보안 태세, 제거), 그리고 실행 중인 serve에 프레임워크가 생성한 Claude Code/Codex 세션을 연결하기 위한 로컬 하니스 모드(`gbrain bootstrap harness`)
- [`docs/what-schemas-unlock.md`](docs/what-schemas-unlock.md) — 스키마가 중요한 이유: 7가지 킬러 유스케이스, 타입이 지정된 페이지 종류에 대한 구조적 논증, 에이전트 공동 큐레이션 패턴(v0.40.7.0)
- [`docs/schema-author-tutorial.md`](docs/schema-author-tutorial.md) — 5분 만에 끝내는 가이드: 번들된 팩 포크, 커스텀 타입 추가, 기존 페이지 백필, `gbrain whoknows`를 통한 연동 확인
- [`docs/architecture/`](docs/architecture/) — 시스템 설계, 토폴로지, 검색 이론
- [`docs/guides/`](docs/guides/) — 방법론 런북(서브 에이전트 라우팅, 미니언 배포, 스킬 개발, 브레인 우선 조회, 아이디어 캡처, 듀딜리전스 인제스션)
- [`docs/integrations/`](docs/integrations/) — 외부 데이터 소스 연결(음성, 이메일, 캘린더, 임베딩 제공자)
- [`docs/mcp/`](docs/mcp/) — 클라이언트별 MCP 설정(Claude Desktop, Code, Cursor, ChatGPT, Perplexity, Cowork)
- [`docs/eval/`](docs/eval/) — 평가 프레임워크, 메트릭 용어집, 방법론
- [`docs/ethos/`](docs/ethos/) — 철학(가벼운 하니스, 무거운 스킬, 레시피 형태의 마크다운, 탄생 비화)
- [`AGENTS.md`](AGENTS.md) — Claude가 아닌 에이전트를 위한 진입점
- [`CLAUDE.md`](CLAUDE.md) — Claude Code를 위한 진입점(심층 운영 컨텍스트)
- [`CONTRIBUTING.md`](CONTRIBUTING.md) — 기여자 가이드, 테스트 원칙, 평가 캡처 모드
- [`SECURITY.md`](SECURITY.md) — OAuth 위협 모델, 하드닝 기본값
## 기여하기 (Contributing)
빠른 반복을 위해 `bun run test`를 실행하고, 푸시 전 검증을 위해 `bun run verify`를 실행하며, 전체 Docker 기반 CI 스택을 로컬에서 실행하려면 `bun run ci:local`을 실행하세요. 상세한 테스트 원칙은 [`CONTRIBUTING.md`](CONTRIBUTING.md)에 있습니다.
커뮤니티 PR은 하나씩 병합되는 대신 릴리스 웨이브 단위로 묶여 처리됩니다. [`CLAUDE.md`](CLAUDE.md)의 "PR wave workflow" 섹션을참조하세요. 기여자 귀속은 `Co-Authored-By:` 트레일러를 통해 유지됩니다. 수락된 모든 기여는 [`CHANGELOG.md`](CHANGELOG.md)에 명시됩니다.
버그를 발견하거나 기능이 필요한 경우: 먼저 이슈를 열어주세요. 간단한 수정(오타, 문서 버그, 명백한 회귀)은 바로 PR로 진행해도 됩니다. 스키마, 검색 순위, MCP 프로토콜, 또는 보안 경계를 건드리는 모든 작업은 먼저 이슈에서 디자인 논의가 필요합니다.
## 라이선스 (License)

+ credit
MIT. I built GBrain to run my OpenClaw and Hermes deployments — the production brain behind my AI agents.
Origin story: [`docs/ethos/ORIGIN.md`](docs/ethos/ORIGIN.md).
Community PR contributors are credited in `CHANGELOG.md` per release. ZeroEntropy ([@zeroentropy](https://zeroentropy.dev)) for the embedding + reranker stack that shipped as the default from v0.36 through v0.46. Voyage AI for the asymmetric-encoding recipe template. Ramp Labs for the search quality improvements lineage.

gbrain

gbrain 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

gbrain

gbrain 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README