Pratiyush/llm-wiki

Claude Code, Codex CLI, Cursor, Gemini CLI, 그리고 Obsidian 세션으로부터 생성되는 LLM 기반 지식 베이스(knowledge base). Andrej Karpathy의 LLM Wiki 패턴을 기반으로 구축되었습니다.

examples/demo-sessions/에 있는 합성 세션(synthetic sessions)으로부터 매 master 푸시(push)마다 재구축됩니다. 개인 데이터는 포함되지 않습니다. 안전한 참조 데이터를 대상으로 실행되는 실제 도구의 모든 기능(활동 히트맵(activity heatmap), 도구 차트(tool charts), 토큰 사용량(token usage), 모델 정보 카드(model info cards), 비교 분석(vs-comparisons), 프로젝트 주제(project topics))을 보여줍니다.

모든 Claude Code, Codex CLI, Copilot, Cursor, Gemini CLI 세션은 전체 트랜스크립트(transcript)를 디스크에 기록합니다. 여러분은 이미 수백 개의 기록을 가지고 있지만, 다시는 그것을 보지 않습니다.

llmwiki는 그 잠자고 있는 기록을 단 두 개의 명령어로 로컬에서 아름답고 검색 가능하며 상호 연결된 지식 베이스로 변환합니다. 또한, 다른 AI 에이전트가 여러분의 위키를 직접 쿼리할 수 있도록 AI가 소비 가능한 내보내기 파일(llms.txt, llms-full.txt, JSON-LD 그래프, 페이지별 .txt + .json 형제 파일)을 생성합니다.

./setup.sh # 1회성 설치
./build.sh && ./serve.sh # 빌드 및 http://127.0.0.1:8765 에서 서비스 실행

한 줄로 요약하는 기여(Contributing) 방법: CONTRIBUTING.md를 읽고, PR(Pull Request)은 집중된 주제(한 번에 하나의 관심사)를 유지하며, feat:, fix:, docs:, chore:, test: 커밋 접두사(commit prefixes)를 사용하세요. 실제 세션 데이터는 절대 커밋하지 마세요 (raw/는 gitignored 처리됨). 새로운 런타임 의존성(runtime deps)을 추가하지 마세요. 머지(merge)를 위해서는 CI가 통과(green)되어야 합니다.

아래의 모든 스크린샷은 더미 예제 세션으로부터 매 master 푸시마다 구축되는 공개 데모 사이트의 것입니다. 여러분의 위키도 실제 작업 내용만 다를 뿐 동일하게 보일 것입니다.

모든 세션을 .jsonl에서 정제되고 비식별화된 마크다운(markdown)으로 변환
Karpathy 스타일의 위키—[[wikilinks]]로 연결된 sources/, entities/, concepts/, syntheses/, comparisons/, questions/
아름다운 정적 사이트(static site)—로컬에서 브라우징하거나 GitHub Pages에 배포 가능

• 글로벌 검색 (사전 구축된 인덱스에 대한 퍼지 매치(fuzzy match)를 지원하는 Cmd+K 명령 팔레트)
• highlight.js 클라이언트 사이드 구문 강조(syntax highlighting) (라이트 + 다크 테마)
• 다크 모드 (시스템 인식 + data-theme를 통한 수동 토글)
• 키보드 단축키: /

검색 · g h/p/s

탐색 · j/k

행 · ?

도움말 - 접이식 도구 결과 섹션 (500자 초과 시 자동 확장)

• 마크다운으로 복사 (Copy-as-markdown) + 코드 복사 버튼
• 브레드크럼 (Breadcrumbs) + 읽기 진행률 표시줄
• 세션 테이블의 필터 바 (프로젝트/모델/날짜/텍스트)
• 예상 읽기 시간 (X분 소요)
• 모든 세션 하단의 관련 페이지 패널
• 홈 페이지의 활동 히트맵 (Activity heatmap)
• 구조화된 스키마를 포함한 모델 정보 카드 (제공업체, 가격, 벤치마크)
• AI 모델 간의 자동 생성된 비교 (vs-comparison) 페이지
• 가격 스파크라인 (pricing sparkline)이 포함된 추가 전용 (Append-only) 변경 로그 타임라인
• 프로젝트 토픽 칩 (프로젝트 카드 내 GitHub 스타일 태그)
• 에이전트 라벨 (색상 배지: Claude/Codex/Copilot/Cursor/Gemini)
• 홈 페이지의 최근 업데이트 카드
• 커맨드 팔레트 내 Dataview 스타일의 구조화된 쿼리
• 호버 시 위키링크 (wikilinks) 미리보기
• 모든 헤딩 옆의 딥링크 (Deep-link) 아이콘
• 모바일 대응 + 인쇄 최적화

모든 HTML 페이지는 동일한 URL에 형제 관계인 기계 판독 가능 (machine-readable) 파일을 가집니다:

<page>.html
— schema.org 마이크로데이터가 포함된 인간용 HTML

<page>.txt
— 일반 텍스트 버전 (HTML 태그 없음)

<page>.json
— 구조화된 메타데이터 + 본문

사이트 수준의 AI 에이전트 진입점:

파일	내용
/llms.txt	llmstxt.org 사양에 따른 짧은 인덱스
/llms-full.txt	평탄화된 일반 텍스트 덤프 (~5 MB 제한) — 모든 LLM의 컨텍스트에 붙여넣기 가능
/graph.jsonld	Schema.org JSON-LD 엔티티/개념/소스 그래프
/sitemap.xml	lastmod가 포함된 표준 사이트맵
/rss.xml	최신 세션의 RSS 2.0 피드
/robots.txt	llms.txt 참조가 포함된 AI 친화적 robots.txt
/ai-readme.md	AI 전용 탐색 지침
/manifest.json	SHA-256 해시 + 성능 예산(perf budget)이 포함된 빌드 매니페스트

모든 페이지에는 AI 에이전트가 별도의 .json 형제 파일을 가져오지 않고도 파싱할 수 있는 <!-- llmwiki:metadata --> HTML 주석이 포함되어 있습니다.

JSON-LD 그래프는 크롤러만을 위한 것이 아닙니다 — 셸(shell)을 떠나지 않고도 위키에 대해 간단한 질문을 할 수 있습니다. 예시: 모든 세션을 프로젝트별로 그룹화하여 트리 형태로 출력하기:

python3 examples/scripts/tree_from_graph.py

출력:

📚 3개의 프로젝트에 걸친 8개 세션
(site/graph.jsonld v1.3.0)
llmwiki/
...

전체 스크립트는 examples/scripts/tree_from_graph.py에 있으며 **표준 라이브러리(stdlib-only)**만 사용합니다.

동일한 레시피 패턴은 모든 집계 질문에 적용할 수 있습니다. 모델별 세션 수 계산, 토큰 사용량 기준 가장 큰 프로젝트 찾기, 3개 이상의 세션에 등장하는 모든 엔티티(entity) 목록화 등 원하는 대로 그래프를 잘라 활용할 수 있습니다.

4요소 신뢰도 점수 산정(4-factor confidence scoring)— 소스 개수, 소스 품질, 최신성, 상호 참조를 기준으로 하며, 콘텐츠 유형별로 에빙하우스(Ebbinghaus)에서 영감을 받은 감쇠(decay) 모델을 적용합니다.

5단계 라이프사이클 머신(5-state lifecycle machine)— 초안(draft) → 검토됨(reviewed) → 검증됨(verified) → 오래됨(stale) → 보관됨(archived) 단계로 구성되며, 90일이 지나면 자동으로 '오래됨' 상태로 전환됩니다.

16가지 린트 규칙(16 lint rules)— 8가지 구조적 규칙(프론트매터(frontmatter), 링크 무결성, 고아 페이지(orphans), 신선도, 중복, 인덱스 동기화 등) + 3가지 LLM 기반 규칙(모순, 주장 검증, 요약 정확도) + stale_candidates (#51) + tags_topics_convention (#302) + stale_reference_detection (#303) + frontmatter_count_consistency (#378) + tools_consistency (#378)

자동 드림(Auto Dream)— 24시간 경과 및 5개 세션 생성 후 MEMORY.md 통합 수행: 상대적 날짜 해결, 오래된 정보 제거, 200행 제한 적용

9개의 내비게이션 파일(9 navigation files)— CLAUDE.md, AGENTS.md, MEMORY.md, SOUL.md, CRITICAL_FACTS.md, hints.md, hot.md + 프로젝트별 핫 캐시(hot caches)

— 프로젝트 전체를 Obsidian 보관함(vault)으로 심볼릭 링크(symlinks) 연결; 그래프 뷰 + 백링크(backlinks) + 전체 텍스트 검색이 즉시 작동합니다 link-obsidian CLI

Dataview 대시보드(Dataview dashboard)— 10개의 즉시 사용 가능한 쿼리(최근 업데이트됨, 신뢰도별, 라이프사이클별, 프로젝트별, 엔티티 유형별, 미결 질문, 오래된 페이지)

Templater 템플릿(Templater templates)— 소스/엔티티/개념/합성 페이지를 위한 4개의 템플릿, 신뢰도 + 라이프사이클 + 오늘 날짜가 포함되어 생성됨

카테고리 페이지(Category pages)— Dataview (Obsidian) 모드와 정적 마크다운 (HTML) 모드 모두에서 지원되는 태그 기반 인덱스 페이지

통합 가이드(Integration guide)— docs/obsidian-integration.md에서 플러그인별 설정이 포함된 6개의 권장 플러그인을 다룹니다.

SessionStart 훅(SessionStart hook)— Claude Code를 실행할 때마다 백그라운드에서 새로운 세션을 자동으로 동기화합니다.

동기화 시 자동 빌드(Auto-build on sync)— /wiki-sync

triggers /wiki-build (설정 가능; 기본값 On)

원샷 파이프라인 (One-shot pipeline)—llmwiki all

단일 명령어로 빌드(build) → 그래프(graph) → 내보내기(export) → 린트(lint)를 실행합니다 (--strict 옵션은 CI용).

MCP 서버 (MCP server)— 12개의 프로덕션 도구(query, search, list, read, lint, sync, export, + confidence, lifecycle, dashboard, entity search, category browse)를 제공하며, 모든 MCP 클라이언트(Claude Desktop, Cline, Cursor, ChatGPT desktop)에서 쿼리할 수 있습니다.

대기 중인 인제스트 큐 (Pending ingest queue)— SessionStart 훅(hook)이 변환 및 큐에 추가하며, /wiki-sync가 큐를 처리합니다.

서버 없음, 데이터베이스 없음, npm 없음— Python 표준 라이브러리(stdlib)와 markdown을 사용합니다. 구문 강조(Syntax highlighting)는 보기(view) 시점에 highlight.js CDN에서 로드됩니다.

가이드 투어입니다. 다음 명령들을 순서대로 실행하면 마지막에는 http://127.0.0.1:8765/에서 완전히 작동하는 위키를 갖게 됩니다. 각 명령은 멱등성(idempotent)을 가지며 수행한 작업을 출력합니다.

동일한 흐름을 스크립트로 기록한 영상이 docs/videos/cli-tutorial.gif에 포함되어 있습니다 (8개 세션 샌드박스 기준 31초). 재현 가능한 소스는 docs/videos/cli-tutorial.tape이며, vhs docs/videos/cli-tutorial.tape 명령으로 언제든 다시 렌더링할 수 있습니다.

# 1. 일회성 스캐폴딩 (약 1초). raw/, wiki/, site/, seed nav 파일들을 생성합니다.
llmwiki init
# 2. 세션 가져오기 (약 1초 / 100개 세션 기준). 모든 어댑터를 순회합니다.
...

이것이 전체 해피 패스(happy path)입니다. 가끔 사용하게 될 두 가지 명령어가 더 있습니다:

# 설치 및 설정된 내용을 검사합니다. 어댑터별 테이블을 출력합니다:
# (available: yes/no, configured: yes/no, session-store path).
llmwiki adapters
...

나중에 발견하게 될 세 가지 선택적 플래그(optional flags)입니다:

--adapter <name>
— sync를 하나의 어댑터로 제한합니다 (예: --adapter claude_code).

--vault PATH
— wiki/ 대신 Obsidian / Logseq 볼트(vault) 오버레이에 기록합니다 (#54).

--synthesize
— build 중에 로컬 Claude / Ollama 백엔드를 호출하여 LLM이 생성한 개요 페이지를 만듭니다.

각 서브커맨드(subcommand)는 다른 명령들과 함께 자체적인 --help를 제공합니다. 아래의 CLI 참조 테이블은 전체 목록입니다.

┌─────────────────────────────────────┐
│ ~/.claude/projects/*/*.jsonl │ ← Claude Code 세션
│ ~/.codex/sessions/**/*.jsonl │ ← Codex CLI 세션
...

Karpathy의 3계층(3-layer) + 8계층 빌드 세부 분석에 대한 전체 내용은 docs/architecture.md를 참조하세요.

전체 프로덕션 문서(production documentation)는 docs/ 아래에 있습니다.

편집 허브(editorial hub)는 docs/index.md이며 — 튜토리얼, 에이전트별 가이드, 참조 및 배포가 모두 한곳에 모여 있습니다.

여기서 시작하세요:

목표	읽기
10분 만에 첫 사이트 설치 및 빌드하기	Tutorial 01 → 02
...

문서 기여(Contributing)를 원하시나요? **스타일 가이드(style guide)**를 확인하세요.

git clone https://github.com/Pratiyush/llm-wiki.git
cd llm-wiki
./setup.sh

git clone https://github.com/Pratiyush/llm-wiki.git
cd llm-wiki
setup.bat

pip install -e . # 기본 — 필요한 모든 것
pip install -e '.[graph]' # + graphifyy AI 기반 그래프 엔진
pip install -e '.[dev]' # + pytest + ruff
...

구문 강조(Syntax highlighting)는 이제 highlight.js를 통해 지원되며, 뷰 타임(view time)에 CDN에서 로드됩니다 — 별도의 선택적 의존성(optional deps)이 필요하지 않습니다.

• raw/, wiki/, site/ 데이터 디렉토리를 생성합니다.
• llmwiki Python 패키지를 제자리(in-place)에 설치합니다.
• 코딩 에이전트(coding agents)를 감지하고 일치하는 어댑터(adapters)를 활성화합니다.
• 자동 동기화를 위해 ~/.claude/settings.json에 SessionStart 훅(hook)을 설치할지 선택적으로 제안합니다.
• 즉시 출력을 확인할 수 있도록 첫 번째 동기화를 실행합니다.

프로젝트를 실행 중이신가요? 거버넌스 스캐폴드(governance scaffold)는 docs/maintainers/ 아래에 있으며 전용 스킬(skill)에 의해 로드됩니다:

파일	용도
CONTRIBUTING.md	기여자(contributors)를 위한 짧은 규칙 — 이것을 먼저 읽으세요
CODE_OF_CONDUCT.md	Contributor Covenant 2.1
SECURITY.md	레드액션(redaction) 버그, XSS, 데이터 유출에 대한 공개 프로세스
docs/maintainers/ARCHITECTURE.md	한 페이지 분량의 시스템 다이어그램 + 레이어 경계 + 추가하지 말아야 할 것
docs/maintainers/REVIEW_CHECKLIST.md	표준 코드 리뷰(code-review) 기준
docs/maintainers/RELEASE_PROCESS.md	버전 업(Version bump) → CHANGELOG → 태그(tag) → 빌드(build) → 게시(publish)
docs/maintainers/TRIAGE.md	라벨 분류 체계(Label taxonomy) + 오래된 이슈(stale-issue) 정책
docs/maintainers/ROADMAP.md	단기 계획 + 릴리스 테마
docs/maintainers/DECLINED.md	사유와 함께 기록된 거절된 아이디어들의 저장소

네 가지 Claude Code 슬래시 명령어가 일반적인 운영(ops)을 자동화합니다:

/review-pr <N>

— PR에 REVIEW_CHECKLIST를 적용하고 결과 게시

/triage-issue <N>

— 새 이슈에 라벨(label) + 마일스톤(milestone) + 우선순위(priority) 지정

/release <version>

— 릴리스 프로세스를 단계별로 수행

/maintainer

— 모든 거버넌스(governance) 문서를 컨텍스트(context)로 로드하는 메타 스킬(meta-skill)

유닛 테스트 스위트(pytest tests/ — 2,651개 테스트)는 몇 초 내에 실행되며 모든 모듈을 커버합니다. tests/e2e/ 아래에 있는 엔드 투 엔드(end-to-end, E2E) 스위트는 별도로 존재합니다. 이는 최소한의 데모 사이트를 구축하고, 임의의 포트에서 이를 서빙하며, Playwright를 통해 실제 브라우저를 구동하고, pytest-bdd를 통해 Gherkin으로 작성된 시나리오를 실행합니다.

왜 둘 다 필요한가요? 유닛 테스트는 모듈 경계에서 계약(contract)을 고정하고, E2E는 사용자의 브라우저에서 계약을 고정합니다. 유닛 테스트는 통과하지만 Cmd+K 팔레트를 깨뜨리는 변경 사항(diff)은 E2E에서 실패하게 됩니다.

추가 패키지를 설치하세요 (일회성, Chromium 바이너리를 위해 수백 MB 필요):

pip install -e '.[e2e]'
python -m playwright install chromium

스위트 실행:

pytest tests/e2e/ --browser=chromium

단일 기능 실행:

pytest tests/e2e/test_command_palette.py --browser=chromium -v

E2E 스위트는 기본 pytest tests/ 실행에서 제외됩니다 (pyproject.toml에 있는 --ignore=tests/e2e 옵션 참조)

) 따라서 브라우저 설치를 기다리지 않고도 유닛 테스트 스위트 (unit suite)를 반복해서 실행할 수 있습니다.

CI는 E2E 작업을 별도의 워크플로우 (.github/workflows/e2e.yml)로 실행하며, 이는 build.py, 시각화 모듈 (viz modules), 또는 tests/e2e/**를 수정하는 PR (Pull Request)이 발생할 때만 트리거됩니다.

피처 파일 (Feature files)은 tests/e2e/features/ 아래에 위치하며, 각 UI 영역별로 하나씩 존재합니다 (홈페이지, 세션 페이지, 커맨드 팔레트 (command palette), 키보드 네비게이션, 모바일 네비게이션, 테마 토글, 마크다운으로 복사 (copy-as-markdown), 반응형 중단점 (responsive breakpoints), 엣지 케이스 (edge cases), 접근성 (accessibility), 시각적 회귀 (visual regression)).

스텝 정의 (Step definitions)는 모두 tests/e2e/steps/ui_steps.py에 있습니다. 새로운 시나리오를 추가하는 것은 보통 .feature 파일에 2줄 정도를 추가하고, 아마도 하나의 새로운 스텝을 추가하는 것으로 충분합니다.

HTML 리포트와 함께 로컬에서 실행하기:

pytest tests/e2e/ --browser=chromium \
--html=e2e-report/index.html --self-contained-html
open e2e-report/index.html # macOS — 브라우저로 확인 가능한 리포트를 엽니다

테스트 리포트 확인 위치:

항목	위치
유닛 테스트 결과	GitHub Actions → ci.yml → 최신 실행 (latest run) → lint-and-test 작업 로그
...

로컬에서 HTML 리포트는 하나의 파일 (e2e-report/index.html)로 생성되며, 모든 브라우저에서 열 수 있습니다. 시나리오별 통과/실패 여부, 소요 시간, stdout/stderr, 실패 시 스크린샷을 확인할 수 있습니다.

일간/주간 cron 스타일의 동기화를 위해서는 llmwiki sync를 스케줄링하세요.