WUPHF - Karpathy 스타일 LLM 위키를 에이전트들이 직접 유지하는 시스템

Andrej Karpathy가 2026년 4월 공개한 GitHub Gist는 개발자 커뮤니티에서 폭발적 관심을 받고 있다. 바로 'LLM Wiki' 패턴 — AI 에이전트가 자체적으로 유지하는 마크다운 기반 지식 베이스다. 이번 글에서는 WUPHF라는 실제 구현체를 통해 이 패턴의 핵심 구조와 활용법을详细介绍한다.

왜 기존 RAG은 부족한가?

현재 많은 AI 프로젝트가 RAG(Retrieval-Augmented Generation)을 활용해 문서 기반 질의응답을 구현한다. 그러나 RAG은 근본적 한계가 있다. 매번 쿼리마다 벡터 데이터베이스에서 유사 문서를 찾아 다시 생성해야 하므로, 에이전트가 이전 세션에서 '배운 것'을 기억하지 못한다.

Karpathy의 핵심 통찰은 단순하다. 에이전트는 문서를 검색하는 것이 아니라, 지식을 컴파일해야 한다. Wiki layer를 두어 LLM이 지속적으로 지식을 축적하고, 다른 에이전트 세션에서도 그 지식을 활용할 수 있게 하는 것이다.

WUPHF 아키텍처 — Markdown + Git을 소스 오브 트루스로 사용

WUPHF: 첫 번째 실용적 구현

WUPHF는 Karpathy 패턴을 실제로 구현한 첫 번째 프로젝트다. HN(Hacker News)의 Show HN에서 23포인트로 화제를 모으며, 기존 위크엔드 프로젝트와는 차원이 다른 완성도를 보여주고 있다.

핵심 기술 스택

• Markdown + Git: 소스 오브 트루스로 버전 관리와 협업 가능
• Bleve (BM25): 벡터 데이터베이스 대신 전통적 키워드 검색 사용
• SQLite: 메타데이터 저장소로 가볍고 빠른 쿼리
• Lint: Wiki 품질 자동 검증

특히 주목할 점은 벡터 데이터베이스나 그래프 DB를 사용하지 않는다는 것이다. 이는 설정과 운영의 복잡성을 대폭 줄이면서도, 검색 품질 저하는 최소화한다.

디렉토리 구조

~/.wuphf/wiki/
├── raw/           # 불변의 원본 소스
├── wiki/          # LLM이 생성한 위키 페이지
├── index/         # Bleve + SQLite 인덱스
└── .git/          # 모든 변경 이력 관리

3단계 아키텍처

Karpathy의 LLM Wiki는 명확한 3층 구조로 설계된다.

1. Raw Layer (raw/)

읽기 전용 원본 문서 저장소다. PDFs, 웹 스크랩, 노트 등 에이전트가 참조하는 모든 소스가 여기에 보관된다. 한 번 추가되면 절대 수정되지 않아 데이터 무결성이 보장된다.

2. Wiki Layer (wiki/)

LLM이 원본 소스를 기반으로 생성한 위키 페이지 모음이다. Markdown 형태로 저장되며, 페이지 간 내부 링크로 연결되어 있어 탐색이 용이하다.

3. Schema Layer (CLAUDE.md)

에이전트 세션 시작 시 로드되는 스키마 정의 파일이다. Wiki 구조, 페이지 형식, 쿼리 방법 등 에이전트가 따라야 할 규칙을 명시한다.

LLM Wiki 워크플로우 — Ingest, Query, Lint 3단계

실제 활용 사례

멀티 에이전트 컨텍스트 공유

여러 Claude Code 세션이同一 코드베이스를 작업할 때 발생하는 컨텍스트 초기화 문제를 해결한다. AGENTS.md + DESIGN-WIKI.md 패턴을 활용하면, 레포지토리 루트를 에이전트용 지식 문서로 지정하고 세션 시작 시 system prompt에 포함시킬 수 있다.

코드베이스 아키텍처 문서화

에이전트가 코드를 변경할 때마다 Wiki가 자동 업데이트된다. '이 모듈은 무엇을 하는가?', '왜 이렇게 설계되었는가?' 같은 질문에 즉시 답할 수 있는 Living 문서가 탄생한다.

커뮤니티 구현체

Karpathy의 패턴에서 영감을 받은 다양한 구현체가 쏟아지고 있다.

• Pratiyush/llm-wiki: Claude Code, Codex CLI, Cursor, Gemini CLI, Obsidian 연동
• bashiraziz/llm-wiki-template: 바로 사용할 수 있는 프로젝트 템플릿
• WUPHF: 가장 완성도 높은 구현체로 HN에서 화제

RAG과의 비교

기준	RAG	LLM Wiki
지식 유지	세션마다 재검색	지속적 컴파일
설정 난이도	벡터DB + 임베딩 파이프라인	Markdown + Git만 필요
버전 관리	외부 도구 필요	Git 내장
컨텍스트 활용	부분적	에이전트 간 완전 공유

앞으로의 전망

LLM Wiki 패턴은 AI 에이전트의 장기 기억 문제에 대한 새로운 패러다임을 제시한다. 벡터 데이터베이스 없이도 구조화된 지식을 구축하고 공유할 수 있다는 것은, 소규모 팀부터 기업 환경까지 폭넓은 적용 가능성을 의미한다.

특히 주목할 점은 이 패턴이 '제품'이 아니라 '방법론'이라는 것이다. Karpathy가 제시한 아키텍처를 각자의 필요에 맞게 커스터마이징할 수 있어, 다양한 구현체가 빠르게 등장하고 있다.

핵심 요약

• LLM Wiki는 AI 에이전트가 자체적으로 유지하는 Markdown 기반 지식 베이스
• WUPHF가 첫 번째 실용적 구현체로 HN에서 화제
• 3층 구조(raw/, wiki/, CLAUDE.md)로 명확한 아키텍처
• RAG 대비 설정 간소화, 에이전트 간 지식 공유 용이
• 커뮤니티에서 다양한 구현체 빠르게 증가 중

AI 에이전트의 기억력 문제를 겪고 있다면, LLM Wiki 패턴을 한 번 시도해볼 만하다. 복잡한 벡터 파이프라인 없이도 더 intelligent한 지식 관리가 가능하다.