▲

Show GN: Hypomnema - Claude Code 안에서 동작하는 LLM-네이티브 개인 위키 (오픈소스)

 (github.com/sk-lim19f)
1P by limsangkyu | ★ favorite | 댓글과 토론

Hypomnema는 Claude Code 안에서 슬래시 한 번으로 동작하는 LLM-native 개인 위키 OSS입니다.
~/hypomnema/ 폴더에 평문 마크다운 + git으로 살고, 외부 서비스 / API 키 / 벡터 DB가 없습니다.
사용자가 던진 원본은 sources/에 그대로 보존되고, Claude가 합성한 결과는 pages/에 누적됩니다.
같은 주제를 다시 만나면 새 페이지를 만들지 않고 기존 페이지를 업데이트합니다.

만들게 된 이유는 AI와 매일 일하면서 쌓인 네 가지 문제였습니다.
(1) 새 세션마다 어제 컨텍스트를 다시 설명하는 비용
(2) 결과는 빠르게 쌓이는데 왜 그렇게 짰는지가 어디에도 없어서 한 달 뒤 디버깅이 더 비싸지는 기술부채
(3) 노션·Obsidian·Confluence를 다 써봤지만 "자동화 없음 / 합성 없음 / 레거시화 / 안 본다" 네 함정에서 무너지는 수동 위키
(4) Karpathy의 짧은 Gist — "RAG는 매번 다시 읽지만 위키는 한 번 합성한 지식을 영속시킨다. 병목은 늘 북키핑이었고, LLM이 그 비용을 0으로 낮춘다" — 가 답을 제시했다는 것.

그래서 마크다운 폴더 두 개로 시작해 매일 짜증나는 부분이 생길 때마다 라이프사이클 훅을 하나씩 붙였습니다.

핵심 요약

  • 컨셉: RAG(Retrieval-Augmented Generation, 검색증강생성) 대신 위키. LLM이 한 번 합성한 페이지를 보존하고, 다음번엔 그 위에 또 쌓습니다. 평문 마크다운 + git, 외부 서비스 / API 키 / 벡터 DB 없음.
  • 설치: npm install -g hypomnema → Claude Code에서 /hypo:init.
  • 단일 원천 + 단방향 반영: 행동 교정은 pages/feedback/<slug>.md 한 곳에만 기록합니다. hypomnema feedback-sync 명령이 MEMORY.md(상한 200줄)와 <learned_behaviors>(상한 10개, 5개 필드 엄격 검사)에 자동으로 다시 계산해 반영합니다.
  • 새 SCHEMA 강제 필드: type: feedback 페이지에 9개 필수 필드를 강제합니다. upgrade --apply가 backfill 체크리스트를 자동으로 작성합니다. 자동 초안(stub)은 일부러 거부했습니다 — 잘못된 기본값을 박아 두면 두 파생 면(MEMORY와 CLAUDE.md)으로 조용히 잘못된 동작이 흘러가기 때문입니다.
  • 확장 파일 동봉 동기화: 위키 안에 extensions/{agents,commands,hooks,skills} 디렉토리를 같이 두고 ~/.claude/ 로 자동 미러링합니다. --codex 플래그를 주면 ~/.codex/ 에는 hooks + commands 서브셋(핵심 훅 포함)만 미러됩니다.
  • 자동화 강화: 현재 작업 디렉토리(cwd)에 위키 프로젝트가 없으면 자동 생성 권유, 의미 있는 세션이 끝날 때 가벼운 마무리(minimal crystallize) 자동 권유, WebFetch / WebSearch 직후 /hypo:ingest 권유 안내, 업데이트 알림 2채널(npm / plugin), W8 lint 경고로 오래된 design-history.md 발견, 다른 프로젝트로 새던 교정 차단(scope: project:* 정확 일치 강제), 코드 주석 정리 1단계(시간 지나면 의미가 흐려지는 시점-바인딩 참조 제거, 설계 앵커는 보존).

기존 LLM Wiki OSS와의 차이

Karpathy Gist에서 파생된 프로젝트가 짧은 기간에 10여 개 나왔습니다.
직접 살펴본 영역별 차이를 정리하면 다음과 같습니다.

  • Hypomnema가 메인으로 다루는 영역: 세션 라이프사이클 자동화(훅 14개로 SessionStart / PreCompact / Stop 등에 위키 운영을 묶음), AI 행동 교정의 단일 원천화 + 자동 단방향 반영, ~/.claude/{commands,agents,skills,hooks} 자동 미러링.
  • nvk/llm-wiki: --mode thesis로 명제 찬반 에이전트를 병렬 실행하는 검증 모드가 강합니다.
  • SamurAIGPT/llm-wiki-agent: PDF / Word / PPT / Excel 멀티포맷 ingest가 강합니다.
  • nashsu/llm_wiki: Electron 데스크탑 GUI(6.6k stars)가 가장 성숙합니다.

Hypomnema는 thesis 모드 · 멀티포맷 ingest · 자체 GUI를 의도적으로 만들지 않았습니다 — 그 영역은 위 프로젝트들이 더 잘하고, 필요하면 Obsidian 같은 기존 도구를 같이 씁니다.
요약하면 Claude Code 사용자가 매일 쓰는 워크플로우 안으로 위키를 끌어들이는 부분이 Hypomnema가 가장 강한 영역입니다.

구성 요소

슬래시 커맨드 8개(/hypo:ingest, /hypo:query, /hypo:crystallize, /hypo:resume, /hypo:feedback, /hypo:verify, /hypo:lint, /hypo:graph) + CLI subcommand 5개(init, upgrade [--apply] [--codex], doctor [extensions], uninstall, feedback-sync) + 라이프사이클 훅 14개 + Claude Agent Skills 호환.
각 명령과 훅의 자세한 동작은 README와 dev.to 영문 walkthrough에 정리해 두었습니다.

의도적으로 뺀 것들

벡터 DB · API 키 · GUI · 모드 매트릭스 · SCHEMA 자동 stub 없음 — 모두 "잘못된 기본값이 조용히 잘못된 동작으로 흐른다" 또는 "이미 다른 도구가 잘한다" 는 이유로 의도적으로 제외했습니다.

요구사항 + 링크

기여 안내

피드백·이슈·PR 환영합니다.

함께 보면 좋은 글 β