gieok

GIEOK

Memory for Claude Code

_{GIEOK(기억)은 한국어로 "memory"를 뜻합니다}

Claude Code는 세션이 끝나면 과거의 지식을 잊어버립니다. gieok은 대화를 자동으로 Wiki에 축적하고 다음 세션에서 이를 기억합니다.

같은 설명을 반복할 필요가 없습니다. 매번 사용할 때마다 성장하는 "세컨드 브레인" — 당신의 Claude를 위해.

주요 기능

Claude Code 세션을 자동으로 기록하고, Obsidian Vault 위에 구조화된 지식 베이스를 구축합니다. Andrej Karpathy의 LLM Wiki 패턴과 자동 로깅 및 여러 머신 간 Git 동기화를 결합했습니다.

🗣️  평소처럼 Claude Code와 대화합니다
         ↓  （모든 것이 자동으로 기록됩니다 — 아무것도 할 필요 없습니다）
📝  세션 로그가 로컬에 저장됩니다
         ↓  （스케줄된 작업이 AI에게 로그를 읽고 지식을 추출하게 합니다）
📚  Wiki가 매 세션마다 성장합니다 — 개념, 결정, 패턴
         ↓  （Git으로 동기화）
☁️  GitHub이 Wiki를 백업하고 여러 머신 간에 공유합니다

1. 자동 캡처 (L0): Claude Code Hook 이벤트(UserPromptSubmit / Stop / PostToolUse / SessionEnd)를 포착하여 session-logs/에 Markdown으로 기록
2. 구조화 (L1): 예약 실행(macOS LaunchAgent / Linux cron)을 통해 LLM이 미처리 로그를 읽고 wiki/에 개념 페이지, 프로젝트 페이지, 설계 결정을 작성. 세션 인사이트는 wiki/analyses/에도 저장
3. 무결성 검사 (L2): 월간 Wiki 상태 점검으로 wiki/lint-report.md를 생성. 비밀 정보 유출 자동 탐지 포함
4. 동기화 (L3): Vault 자체가 Git 리포지토리. SessionStart에서 git pull, SessionEnd에서 git commit && git push를 실행하여 GitHub Private 리포지토리를 통해 머신 간 동기화
5. Wiki 컨텍스트 주입: SessionStart 시 wiki/index.md를 시스템 프롬프트에 주입하여 Claude가 과거 지식을 활용할 수 있도록 지원
6. qmd 전문 검색: MCP를 통해 BM25 + 시맨틱 검색으로 Wiki 검색
7. 외부 소스 Ingest (PDF / URL): gieok_ingest_pdf / gieok_ingest_url MCP 도구로 로컬 PDF나 웹 아티클을 한 번의 대화로 Vault에 축적. 긴 PDF는 백그라운드 요약(Option B detached 모드)으로 Claude Desktop 60초 타임아웃 회피
8. Wiki Ingest 스킬: /wiki-ingest-all 및 /wiki-ingest 슬래시 커맨드로 기존 프로젝트 지식을 Wiki에 가져오기
9. 비밀 정보 격리: session-logs/는 머신별 로컬 유지(.gitignore). wiki/ / raw-sources/ / templates/ / CLAUDE.md만 Git으로 관리

주의사항

[!CAUTION] gieok 의 본체 가치(자동 세션 캡처 L0 + Wiki 컨텍스트 주입 + 자동 ingest 파이프라인)는 현재 Claude Code (Max 플랜) 가 필요합니다. Hook 시스템과 SessionStart 컨텍스트 주입은 Claude Code 전용 메커니즘입니다.

v0.6 부터 Codex CLI / OpenCode / Gemini CLI 에서도 skills (슬래시 커맨드) 만은 사용 가능합니다 (scripts/setup-multi-agent.sh). 단, 자동 캡처는 동작하지 않으므로 다른 에이전트는 이미 Claude Code 로 축적된 Vault 의 후속 조작 (검색 / ingest / lint) 용으로 활용하는 것이 현실적입니다. 자세한 매트릭스는 아래 멀티 에이전트 지원 섹션을 참조.

Ingest/Lint 파이프라인(L1/L2)은 claude -p 호출을 교체하면 다른 LLM API 와 함께 사용할 수 있습니다 -- 이는 향후 개선으로 계획되어 있습니다.

[!IMPORTANT] 이 소프트웨어는 어떠한 종류의 보증도 없이 "있는 그대로" 제공됩니다. 저자는 이 도구의 사용으로 인해 발생하는 데이터 손실, 보안 사고 또는 손해에 대해 어떠한 책임도 지지 않습니다. 사용에 따른 위험은 본인이 부담합니다. 전체 약관은 LICENSE를 참조하세요.

사전 요구 사항

	버전 / 요구 사항
macOS	13+ 권장
Node.js	18+ (Hook 스크립트는 .mjs ES Module, 외부 의존성 없음)
Bash	3.2+ (macOS 기본)
Git	2.x+. git pull --rebase / git push 지원 필수
GitHub CLI	선택 사항 (gh로 Private 리포 생성 간소화)
Claude Code	Max 플랜 필수 (claude CLI와 ~/.claude/settings.json의 Hook 시스템 사용)
Codex CLI	선택 (멀티 에이전트 사용 시. ~/.codex/skills/ 인식)
OpenCode	선택 (멀티 에이전트 사용 시. ~/.config/opencode/skills/ 인식)
Gemini CLI	선택 (멀티 에이전트 사용 시. ~/.gemini/skills/ 인식)
Obsidian	임의 폴더에 Vault 하나 생성 (iCloud Drive 불필요)
jq	1.6+ (install-hooks.sh --apply에서 사용)
환경 변수	OBSIDIAN_VAULT가 Vault 루트를 가리키도록 설정

빠른 시작

[!WARNING] 설치 전에 이해하세요: gieok은 모든 Claude Code 세션 I/O에 hook됩니다. 이는 다음을 의미합니다:

• 세션 로그에는 프롬프트와 도구 출력의 API 키, 토큰 또는 개인 정보가 포함될 수 있습니다. 마스킹은 주요 패턴을 커버하지만 완전하지는 않습니다 -- SECURITY.md를 참조하세요
• .gitignore가 잘못 설정되면 세션 로그가 실수로 GitHub에 푸시될 수 있습니다
• 자동 Ingest 파이프라인은 Wiki 추출을 위해 claude -p를 통해 세션 로그 내용을 Claude에 전송합니다

전체 운영을 활성화하기 전에 GIEOK_DRY_RUN=1로 파이프라인을 먼저 확인하는 것을 권장합니다.

⚡ 원라이너 설치 (가장 빠름)

# npm (npx) — Node 18+ 있으면 이 한 줄로 충분 (내부에서 install.sh를 그대로 호출)
npx gieok

# 또는 curl
curl -fsSL https://raw.githubusercontent.com/gaebalai/gieok/main/install.sh | bash

저장소를 ~/.local/share/gieok/repo에 clone하고, Vault(~/gieok/main-gieok)를 초기화하고, Hook · LaunchAgent · 스킬 · qmd 검색까지 순서대로 설치합니다. npx gieok 과 curl | bash는 동일한 install.sh를 실행하며 플래그도 그대로 전달됩니다.

# 완전 비대화형 (기본값으로 모두 설치)
npx gieok --yes
# = curl -fsSL https://raw.githubusercontent.com/gaebalai/gieok/main/install.sh | bash -s -- --yes

# 코어만 (스케줄 · qmd · skills 제외)
npx gieok --minimal

# Vault 경로 지정
npx gieok --vault ~/my-vault

# 업데이트 (이미 설치된 경우 다시 실행하면 clone 대신 pull)
npx gieok

# 제거 (LaunchAgent / hook 항목 / 스킬 심볼릭 링크 되돌림)
bash ~/.local/share/gieok/repo/install.sh --uninstall

설치 후 Claude Code를 재시작하면 Hook이 적용됩니다. 옵션 전체는 npx gieok --help로 확인할 수 있습니다.

🖥️ Claude Desktop MCP 연결 (선택)

Claude Desktop에서 Vault를 직접 읽고 쓰려면 .mcpb 번들을 드래그 앤 드롭하세요.

bash scripts/build-mcpb.sh          # gieok-wiki-0.6.0.mcpb 생성
# → Claude Desktop 으로 drag & drop → Vault 디렉터리 지정 → ⌘Q 로 완전 재시작

또는 Claude Code / CLI 클라이언트에는 직접 등록:

bash scripts/install-mcp-client.sh   # ~/.claude.json에 gieok-wiki 항목 자동 주입

📦 Claude Code 플러그인 마켓플레이스 (v0.6 신규)