LLM Wiki — Obsidian 볼트를 LLM이 유지보수하는 지식 베이스로 운영하기

LLM Wiki — Obsidian 볼트를 LLM이 유지보수하는 지식 베이스로 운영하기

Image: CI Image: Platform Image: Python Image: License: MIT Image: Obsidian Image: Claude Code Image: PRs Welcome

Obsidian을 IDE로, LLM을 프로그래머로, 위키를 코드베이스로. 사용자는 소스를 큐레이션하고 질문하고, LLM이 요약·교차참조·정리·부기(bookkeeping)를 전부 한다.

👉 처음이라면 INTRO.md 부터 — 이게 뭐고 왜 쓰는지 3분 소개.

이 문서 하나만 따라 하면 빈 Obsidian 볼트에서 시작해 자기 유지보수(self-maintaining) LLM 위키 하네스를 그대로 재현할 수 있다.

• 대상 도구: Claude Code (CLI/데스크톱/IDE)

• 언어: 노트 본문 한국어 / 파일명 영문 kebab-case

• 버전: v2.1 (통합 계층 기억 + lazy 인제스트·모델 라우팅) — v1(평평 구조) → v2(4계층·신뢰도·망각) → v2.1(비용 최적화)

목차

1. 핵심 아이디어

2. 아키텍처 — 3계층 저장 + 4계층 기억

3. 디렉토리 구조 전체

4. 처음부터 재현하기 (Setup)

5. 하네스 구성요소 — 에이전트·스킬·스크립트

6. 사용법 — 5가지 오퍼레이션 6.5. 일상 응용 시나리오

7. v2 메커니즘 상세 7.5. 질의 리트리벌 최적화 (v0.8.4~v0.9.0)

8. Frontmatter 스키마 레퍼런스

9. 스크립트 레퍼런스

10. Obsidian 설정 팁

11. 하네스 진화·확장

12. 트러블슈팅

13. 설계 결정 요약

1. 핵심 아이디어

대부분의 "LLM + 문서" 경험은 RAG다: 파일을 올리면 LLM이 질문마다 관련 조각을 검색해 답을 만든다. 문제는 누적이 없다는 것 — 매 질문마다 지식을 처음부터 재발견한다.

LLM Wiki는 다르다. LLM이 원본 소스와 당신 사이에 영속적인 위키(구조화·상호링크된 마크다운 파일 모음)를 점진적으로 만들고 유지한다. 새 소스를 넣으면 LLM은:

1. 소스를 읽고 핵심 정보를 추출

2. 기존 위키에 통합 — 엔티티 페이지 갱신, 요약 수정, 새 데이터가 옛 주장과 충돌하면 표시

3. 교차참조·모순 표시·종합을 한 번 컴파일해두고 계속 최신화

즉 위키는 복리로 쌓이는 산출물이다. 교차참조는 이미 걸려 있고, 모순은 이미 표시돼 있고, 종합은 이미 읽은 모든 것을 반영한다.

역할 분담:

• 사람: 소스 큐레이션, 탐색 방향 결정, 좋은 질문

• LLM: 요약·교차참조·정리·부기 — 위키를 지치지 않고 유지 (한 번에 15개 파일 갱신)

관련 정신: Vannevar Bush의 Memex(1945) — 개인이 큐레이션하는 지식 저장소, 문서 간 연상 경로. 그가 못 푼 것 = "누가 유지보수하나?". LLM이 그 답이다.

2. 아키텍처

2-1. 3계층 저장 (Storage)

2-2. 4계층 기억 (Memory Tiers) — v2 핵심

v1의 한계(모든 정보가 영원히 동등·평평한 구조·품질 통제 없음)를 풀기 위해, 인간 기억 구조를 본떠 정보에 등급·시간·신뢰도를 부여한다. 정보는 아래층(휘발·구체)에서 위층(영속·추상)으로 반복·시간·신뢰도에 따라 승격한다.

raw/  ──▶  L1-working  ──▶  L2-episodic  ──▶  L3-semantic  ──▶  L4-procedural
소스        작업기억         일화기억           의미기억            절차기억
(불변)      세션 스크래치     세션·소스 증거      사실·엔티티(신뢰도)   방법 steps
            세션종료시 비움    "언제 무엇을"       증류된 지식          반복된 절차

승격 규칙:

• L1 → L2 (세션 종료 시): L1 관찰을 3–5줄로 압축 → session-*.md 저장 → L1 비움

• L2 → L3 (lint 시): 같은 주장이 3회 이상 등장 → fact-*.md로 승격 (모순 있으면 보류)

• L3 → L4 (lint 시): 같은 절차가 2회 이상 관찰 → procedure-*.md로 추출

2-3. 특수 파일 두 개

• index.md — 내용 지향. 위키 전체 카탈로그(페이지 + 한 줄 요약). 인제스트마다 자동 갱신. 질의 시 여기부터 읽어 관련 페이지를 찾는다.

• log.md — 시간 지향. append-only 기록. 각 항목 ## [YYYY-MM-DD] <op> | <제목> 프리픽스 고정 → grep "^## \[" log.md | tail -5로 최근 이력 조회.

index.md vs MoC 차이: index는 "빠짐없이"(전수·기계적·평면), MoC는 "이해되게"(선별·큐레이션·계층). 둘 다 유지하되 역할을 섞지 않는다.

3. 디렉토리 구조 전체

llmwiki.obsidian/
├── CLAUDE.md                  # ★ 스키마 — 매 세션 로딩되는 정본 (규약·신뢰도·망각·관계 규칙)
├── CLAUDE.local.md            # 개인 프로필 (gitignore — 공유 안 됨)
├── README.md                  # 이 문서
├── index.md                   # 전수 카탈로그 (자동 갱신)
├── log.md                     # 시간순 append-only 로그
│
├── raw/                       # 원본 소스 (본문 immutable, 인제스트 스탬프만 예외)
│   ├── assets/                # 다운로드한 이미지
│   ├── meetings/              # 회의록 (verbal 소스)
│   ├── notes/                 # 데일리 노트 (스크래치 — pending 스캔 제외)
│   └── ...                    # 자유 분류 (lecture/·article/·books/ 등)
│
├── wiki/                      # LLM 소유 — 4계층 기억
│   ├── L1-working/            # 세션 스크래치 (종료 시 비움)
│   ├── L2-episodic/           # session-*.md, source-*.md
│   ├── L3-semantic/           # fact-*.md, entity-*.md, concept-*.md (신뢰도)
│   ├── L4-procedural/         # procedure-*.md (steps)
│   └── moc/                   # 네비게이션 지도 (home-moc.md 현관 + {topic}-moc.md)
│
├── templates/                 # Obsidian 템플릿
│   ├── meeting.md             # 회의록 (→ raw/meetings/)
│   ├── daily.md               # 오늘의 노트 (→ raw/notes/)
│   └── seeds/                 # 빈 시드 (index·log·home-moc — 배포본 초기화용)
│
├── metrics/                   # 비용대비효과 측정
│   ├── ingest-cost.csv        # 문서당 토큰·페이지·모델 원장 (gitignore)
│   └── cost-report.py         # 모델가중 비용 리포트
│
└── .claude/                   # 하네스
    ├── settings.json          # 훅 (SessionStart 자동 점검 + PostToolUse updated 스탬프)
    ├── agents/                # 전문가 정의 (누가) — 6개
    │   ├── wiki-ingestor.md        (model: sonnet)
    │   ├── wiki-synthesizer.md
    │   ├── wiki-linter.md
    │   ├── wiki-cartographer.md
    │   ├── wiki-consolidator.md
    │   └── meeting-scribe.md       (model: sonnet)
    └── skills/                # 워크플로우 정의 (어떻게)
        ├── wiki-ops/          # ★ 오케스트레이터 (진입점)
        ├── wiki-ingest/       # 인제스트 절차 (lazy)
        │   └── scripts/       # concept-index.py
        ├── wiki-query/        # 질의 절차
        ├── wiki-lint/         # 점검 절차
        │   └── scripts/       # link-audit.py, decay.py, lint-due.py, search.py,
        │                      # ingest-status.py, wiki-status-check.py
        ├── wiki-moc/          # MoC 절차
        ├── wiki-consolidate/  # 통합·배치병합 절차
        │   └── scripts/       # confidence.py, list-claims.py
        ├── weekly-review/     # 주간 리뷰 자동화
        └── meeting-minutes/   # 녹음 → 전사 → 회의록 (로컬/OpenAI 이중 백엔드)
            ├── scripts/       # transcribe.py, apikey.py
            └── references/    # backend-setup.md

4. 처음부터 재현하기 (Setup)

세 갈래가 있다. 하네스 repo를 받았다면 방법 C가 가장 빠르다.

방법 C — git clone로 하네스 배포본 받기 (가장 빠름)

누군가 공유한 하네스 repo(구조·스킬만, 콘텐츠 제외)를 받아 바로 운영을 시작한다.

git clone <하네스-repo-URL> my-wiki && cd my-wiki

1. 개인 프로필 작성 — CLAUDE.local.md를 만들어 자기 소개를 적는다(gitignore라 공유 안 됨). Claude가 세션마다 로딩해 설명 톤을 맞춘다:

   Copy

   # CLAUDE.local.md
   ## 목적 / 사용자 프로필
   - 역할: (백엔드 개발자 / 데이터 사이언티스트 / …)
   - 스택: (언어·프레임워크·인프라)
   - 관심/학습: (현재 파고드는 주제)

2. 시드 복사 — 빈 색인·로그·현관 MoC를 제자리로:

   Copy

   cp templates/seeds/index.md templates/seeds/log.md .
   cp templates/seeds/home-moc.md wiki/moc/

3. Claude Code 실행 → /hooks 한 번 열기(훅 로드) → Obsidian에서 볼트 열기.

4. raw/에 첫 소스를 넣고 "인제스트해줘" → 위키가 자란다.

업데이트 받기: git pull. 하네스(스킬·에이전트·스크립트)만 갱신되고 내 콘텐츠는 그대로다. 내가 하네스를 고쳐 재배포: git add .claude/ CLAUDE.md README.md templates/ && git commit && git push — 콘텐츠·프로필은 .gitignore라 안 올라간다. 볼트 밖(다른 프로젝트·Codex·Cursor 등)에서도 위키를 쓰려면: MCP 서버를 등록한다 — 설치·사용 가이드. 볼트에는 아무것도 설치하지 않는다(5-5 참고).

방법 A — myharness 팩토리로 자동 생성 (권장)

이 하네스는 myharness 플러그인(에이전트 팀 + 스킬 자동 구성 메타 스킬)으로 만들어졌다.

1. Obsidian 볼트 생성 — Obsidian에서 새 볼트를 만든다 (예: llmwiki.obsidian).

2. Claude Code를 볼트 디렉토리에서 실행 — cd <볼트경로> && claude.

3. /init 실행 (선택) — 기본 CLAUDE.md·규약 스캐폴딩.

4. myharness 실행 — LLM Wiki 아이디어 문서를 인자로 넘겨 하네스 구성 요청:

   Copy

   /myharness:myharness <LLM Wiki 패턴 설명 + "MoC 네비게이션 포함" 요청>

5. myharness가 Phase 0~7로 에이전트·스킬·스크립트·CLAUDE.md·훅을 생성한다.

6. v2 업그레이드 — 개선안(신뢰도·덮어쓰기·망각·4계층·엔티티·자동화)을 다시 myharness에 넘겨 아키텍처 변경을 요청하면 이 문서의 v2 구조로 확장된다.

방법 B — 수동 재현 (구조를 직접 만들기)

myharness 없이 파일을 직접 만들 때. 볼트 루트에서:

1) 디렉토리 스캐폴딩

mkdir -p raw/assets
mkdir -p wiki/L1-working wiki/L2-episodic wiki/L3-semantic wiki/L4-procedural wiki/moc
mkdir -p .claude/agents
mkdir -p .claude/skills/wiki-ops
mkdir -p .claude/skills/wiki-ingest
mkdir -p .claude/skills/wiki-query
mkdir -p .claude/skills/wiki-lint/scripts
mkdir -p .claude/skills/wiki-moc
mkdir -p .claude/skills/wiki-consolidate/scripts
# 빈 폴더가 git/OneDrive에서 유지되도록
find raw wiki -type d -exec touch {}/.gitkeep \;

2) 파일 작성 — 아래 5장·8장·9장의 내용을 각 경로에 만든다:

• CLAUDE.md (스키마 — 8장 frontmatter + 7장 규칙)

• .claude/agents/*.md (5개 전문가 — 5-1장)

• .claude/skills/*/SKILL.md (6개 스킬 — 5-2장)

• 스크립트 10개 (9장) — 작성 후 chmod +x

• .claude/settings.json (훅 — 7-6장)

• index.md, log.md, wiki/moc/home-moc.md (시드)

3) 활성화

# 스크립트 실행권한
chmod +x .claude/skills/wiki-lint/scripts/*.sh .claude/skills/wiki-lint/scripts/*.py
chmod +x .claude/skills/wiki-consolidate/scripts/*.sh .claude/skills/wiki-consolidate/scripts/*.py
chmod +x .claude/skills/wiki-ingest/scripts/*.sh metrics/cost-report.py

• Claude Code에서 /hooks를 한 번 열어 새 훅을 로드한다 (세션 중 추가된 훅은 설정 watcher가 즉시 못 잡는다 — /hooks 열기 또는 재시작 필요).

사전 요구사항

• Claude Code 설치

• python3 (모든 결정적 스크립트 + 훅 — 표준 라이브러리만 사용)

• (선택) Obsidian — 위키를 사람이 브라우징. 그래프 뷰로 위키 형태를 본다.

크로스플랫폼: 모든 스크립트·훅이 python3 전용이다(bash·grep·awk·jq·rg 불필요). 따라서:

• macOS·Linux — 그대로 작동 (python3 기본/쉬운 설치).

• Windows — 네이티브로 작동 (python3만 PATH에 있으면 됨; WSL·Git Bash 불필요). 단 훅 명령이 python3를 부르므로 Windows에서 python만 있으면 python3 별칭을 잡아주거나 PATH에 python3 확보.

• 줄바꿈은 .gitattributes가 LF로 정규화(Windows CRLF 손상 방지).

5. 하네스 구성요소

핵심 설계: 에이전트(누가) + 스킬(어떻게) 분리. 에이전트는 역할·원칙·프로토콜을, 스킬은 절차·템플릿을 담는다.

실행 모드: 전문가 풀 (서브 에이전트 디스패치). 오퍼레이션마다 전문가 1명을 호출한다 — 동시 협업 팀이 아니다. 한 소스 인제스트는 교차참조·신뢰도 일관성을 위해 단일 에이전트가 통째로 처리한다(분할하면 페이지 충돌).

5-1. 에이전트 (6명)

모델 라우팅(v2.1): 인제스트는 추출·파일쓰기 위주라 sonnet(빈번한 경로를 싸게). 병합 판단·종합·감사 같은 고추론은 나머지 4개 에이전트가 opus로. 측정상 인제스트 페이지당 실질비용 ~4.6×↓·지연 ~3×↓.

각 에이전트 정의 파일(.claude/agents/{name}.md)의 frontmatter는 연결 계약을 담는다:

---
name: wiki-ingestor
description: <언제 이 에이전트를 쓰나 — pushy하게>
tools: Read, Write, Edit, Glob, Grep, Bash, WebFetch
model: sonnet   # 인제스트=sonnet, 나머지 에이전트=opus (모델 라우팅)
skills: [wiki-ingest, wiki-moc]   # 이 에이전트가 쓰는 스킬 (구성 자기평가용)
---

본문 섹션: 핵심 역할 · 작업 원칙 · 입력/출력 프로토콜 · 이전 산출물이 있을 때 · 에러 핸들링 · 협업.

5-2. 스킬 (8개)

오케스트레이터 frontmatter는 orchestrates: 배열로 조율하는 에이전트를 선언:

---
name: wiki-ops
description: <pushy — 인제스트·질의·린트·MoC·통합 + 후속 키워드>
orchestrates: [wiki-ingestor, wiki-synthesizer, wiki-linter, wiki-cartographer, wiki-consolidator]
---

5-3. 스크립트 (10개, 결정적 — LLM 토큰 0)

계산은 스크립트가, 의미 판단만 LLM이. 상세는 9장.

5-4. 회의록 파이프라인 — 외부 전송을 코드로 막는다

meeting-minutes는 다른 스킬과 성격이 하나 다르다. 오디오를 외부로 보낼지 말지라는 되돌릴 수 없는 결정을 포함한다.

판정은 회의 성격으로 한다 — 인사·평가·심사·계약·개인정보·보안·고객사 기밀은 로컬 온디바이스(mlx-whisper), 일반 업무회의·기술 논의·일정 조율만 OpenAI API. 애매하면 로컬이다. 오분류 비용이 비대칭이기 때문이다: 로컬 오분류는 시간만 더 들지만, OpenAI 오분류는 되돌릴 수 없다(삭제해도 캐시·색인이 남을 수 있다).

이 규칙을 SKILL.md에만 적으면 잊힌다. 그래서 스크립트가 --confirm-upload 없이는 openai 백엔드를 실행 자체를 거부한다. 플래그를 붙이는 행위가 곧 판정을 마쳤다는 기록이 된다.

$ transcribe.py --backend openai --input 회의.m4a
openai 백엔드는 오디오를 외부 서버로 전송한다.
민감 회의(인사·평가·심사·계약·개인정보)라면 --backend local 을 쓰라.
exit=1     # 네트워크 호출 0회

산출물은 둘로 나뉜다. 전사 원문은 raw/meetings/transcripts/에 근거로 보존하고, 회의록만 raw/meetings/에 남겨 위키로 인제스트한다. 63분 녹음은 2만 자를 넘어 회의록의 가독성을 파괴하고 인제스트 토큰을 낭비한다. 회의록 작성은 meeting-scribe에 위임해 메인 컨텍스트가 전사문으로 오염되지 않게 한다.

화자 분리는 지원하지 않는다. Whisper 계열은 "누가 말했는지"를 출력하지 않는다. meeting-scribe는 근거(호명·자기소개·역할 명시)가 있을 때만 발언을 귀속하고, 나머지는 화자 없이 기록한다. 심사·평가 회의에서 잘못된 발언 귀속은 내용 누락보다 해롭기 때문이다.

5-5. MCP 서버 (tools/llmwiki-mcp/) — 볼트 밖에서 위키 쓰기

지금까지의 구성요소는 모두 볼트 안에서 도는 Claude Code를 전제한다. 그런데 위키가 가장 아쉬운 순간은 대개 볼트 밖이다 — 다른 저장소에서 코드를 고치는 중, Codex CLI로 작업하는 중, Cursor에서 문서를 쓰는 중. 그때 위키를 열어 읽는 대신 에이전트가 위키에서 답을 찾게 하는 것이 이 서버다.

설치·사용법은 별도 문서에 있다 → tools/llmwiki-mcp/docs/install-and-usage.ko.md (준비물, 3분 빠른 시작, 클라이언트 8종 등록, 사용법, 환경변수, 문제 해결, 업데이트·제거)

obsidian-llmwiki-mcp는 볼트를 읽기 전용으로 여는 MCP 서버다(Node ≥20, 사전 설치물은 Node 하나). 7.5장의 리트리벌(렉시컬 seed → 관계 1홉 확장 → MoC 멤버 → 옵션 BM25 rerank → claims 팩)을 도구 4개로 노출한다 — wiki_expand(진입점) · wiki_pack(주장·신뢰도 팩) · wiki_read_page(전문) · wiki_search(fallback). Claude Code(다른 프로젝트)·Codex·Gemini·agy·Cursor·Windsurf·Claude Desktop·VS Code 8종이 같은 서버를 등록해 쓴다. 등록은 클라이언트마다 한 줄이고, 스니펫은 서버의 print-config 가 만들어 준다.

볼트 안에서는 아무것도 바뀌지 않는다. wiki-query·wiki-ops는 지금처럼 search.py·scope-expand.py를 직접 부른다. 서버는 같은 규칙을 옮긴 것이고, 두 경로가 같은 결과를 낸다는 것을 패리티 테스트가 지킨다 — 볼트 안이든 밖이든 같은 답을 받는다.

위키는 읽기만 한다. 이 서버에는 파일을 쓰는 코드가 없고, 네트워크 연결도 LLM 호출도 하지 않는다. 인제스트·파일링·린트는 계속 볼트 하네스의 일이다. 그래서 설치·제거가 볼트에 아무 흔적을 남기지 않는다.

영문 상세 레퍼런스(도구 계약·상한·보안 경계)는 tools/llmwiki-mcp/README.md, 서버를 고칠 때 지켜야 할 규칙과 설계·검토 기록은 CLAUDE.md의 동기 규칙과 develop_docs/v0.8.6/에 있다.

6. 사용법 — 5가지 오퍼레이션

모든 작업의 진입점은 wiki-ops 오케스트레이터다. 위키 관련 요청을 하면 자동 트리거되고, 알맞은 전문가로 라우팅한다. 자연어로 요청하면 된다.

6-1. Ingest (소스 인제스트)

언제: 새 소스를 위키에 넣을 때.

1. raw/ 에 소스 파일을 넣는다 (예: raw/attention-is-all-you-need.md)
   — Obsidian Web Clipper로 웹 기사를 markdown으로 저장하면 편하다.
2. Claude Code에서: "raw/attention-is-all-you-need.md 인제스트해줘"

LLM이 하는 일 (v2.1 lazy — 싸고 빠르게):

1. 소스 읽기 (본문 immutable) + 유형 판별 (공식/코드/일반/구두) + 중복 스탬프 체크

2. 기존 개념은 concept-index.py 카탈로그로만 파악 (페이지 본문 Read 안 함 — 위키가 커도 O(1))

3. wiki/L2-episodic/source-*.md 증거 페이지 — 핵심 사실 전부 claim::로 (재등장 신호)

4. 신규 개념만 wiki/L3-semantic/ 초안 생성 (confidence 0.6 고정). 기존과 겹치면 손대지 않음

5. 신규 L3만 MoC에 가볍게 편입 + index.md·log.md + raw 맨 위 스탬프

6. 신규 페이지·claim 수 보고 + "병합·신뢰도·관계·승격은 다음 lint 배치" 명시

왜 lazy? v2는 인제스트마다 기존 페이지를 전수 Read하고 병합·관계까지 해서 위키가 클수록 토큰이 O(n)로 폭증했다. v2.1은 인제스트를 증거 남기기로 가볍게 하고, 병합은 본질적으로 효율적인 누적 후 lint 배치로 옮겼다(→ §6-5, §7).

6-2. Query (질의)

언제: 위키에 질문하거나 비교·분석이 필요할 때.

"우리 스택에서 PostgreSQL을 왜 쓰지? 근거랑 신뢰도까지"
"transformer와 RNN 비교표 만들어줘"

LLM이 하는 일:

1. index.md → 관련 MoC → L3 페이지 탐색 (없으면 search.py)

2. confidence·status·last_confirmed 확인

3. stale 페이지는 주근거로 안 씀 (superseded_by 따라 현재 페이지로)

4. 각 주장에 신뢰도 + 출처 인용 병기

5. 재사용 가치 있는 답은 위키에 환류 제안 → 승인 시 L3에 저장 (탐색이 복리로 쌓임)

6-3. Lint (건강 검진)

언제: 주기적으로, 또는 SessionStart 훅이 "3일+ 경과" 알릴 때.

"위키 점검해줘"  /  "위키 린트"

LLM이 하는 일 (6단계):

1. 스크립트: link-audit.py(끊긴 링크·고아) + decay.py(망각 보존율)

2. 망각 처리: faded(R<0.3) 페이지 → 재확인 또는 아카이브 후보 (자동 삭제 금지)

3. 신뢰도·supersession 감사: confidence 정합, stale 짝 링크 확인

4. 통합 승격: L2→L3, L3→L4 후보 제안

5. 추론 검사: 모순, 낡은 주장, 누락 개념, 빠진 관계

6. 보고: 심각도 정렬 수리 목록 + 새 질문·소스 제안

lint 후 반드시 ## [날짜] lint | ...를 log에 남긴다 — 자동화 훅이 경과일을 이 항목으로 계산한다.

6-4. MoC (네비게이션 정리)

언제: 주제 지도를 만들거나 갱신할 때.

"llmops 관련 MoC 만들어줘"  /  "네비게이션 정리해줘"

LLM이 하는 일: wiki/moc/{topic}-moc.md 허브 생성/갱신, home-moc 계층 유지, 새 L3/L4 페이지 편입, 모든 L3/L4 페이지가 ≥1 MoC에서 도달 가능한지 점검(고아 방지).

6-5. Consolidate (기억 통합)

언제: 세션 마무리 시(L1→L2), 또는 lint 중(L2→L3→L4).

"세션 마무리하자"  /  "L1 압축해줘"  /  "통합해줘"

LLM이 하는 일:

• L1→L2: L1 관찰 3–5줄 압축 → session-YYYY-MM-DD.md → L1 비움

• L2→L3: 같은 주장 3회+ → fact-*.md 승격 (모순 시 보류)

• L3→L4: 같은 절차 2회+ → procedure-*.md 추출

• 배치 병합 (lazy 인제스트 후속, v2.1): lazy가 미룬 일을 lint에서 일괄 — 신규 개념 ↔ 기존 페이지 병합, sources: 추가·신뢰도 재계산(claim 재등장 카운트), ## 관계 구조화, 중복 초안 정리. 병합은 여러 소스가 쌓인 뒤 한 번에 보는 게 효율적(소스마다 전수 스캔 회피).

6.5 일상 응용 시나리오 (단순 Q&A를 넘어)

단순 질문은 이 위키의 일부만 쓴다. 핵심 가치는 인제스트→축적→복리. 하루 업무 3블록 + 주간 리뷰에 매핑한 응용방안(외부 PKM/LLM-wiki 사례 리서치 기반).

① 회의 → 회의록 파이프라인

• 회의 직후 인제스트 → action item·결정사항을 claim으로 자동 추출.

• 회의 전 3분 브리핑 — "이 안건 지난 논의 뭐였지?" → 질의유형 라우팅으로 즉답(빠른 사실브리핑).

• 결정 로그(ADR) — 결정 번복 시 supersession(status: stale + superseded_by)으로 "왜 바꿨나" 이력 보존.

② 학습 → 지식 복리 + 자동 복습

• 아티클/강의 인제스트 → concept 페이지 축적(흩어진 북마크 대신 연결된 지식).

• 신뢰도(confidence)로 이해도 추적 — 1소스 0.6="얕게 봄", 3소스 0.95="여러 각도 확인".

• 망각(forgetting)이 복습 엔진 — 보존율 하락 시 lint가 "복습 대상" 표시(Ebbinghaus). 일반 PKM엔 없는 기능.

③ 개발 → 운영지식·트러블슈팅 축적

• 트러블슈팅 로그 — 장애·해결 인제스트 → 같은 절차 2회+ 시 L4 procedure 자동 승격(런북화).

• 기술결정 기록 — "왜 X 대신 Y" concept + supersession.

• 운영지식(llmops·모니터링) — entity/procedure로 축적.

④ 주간 리뷰 (최고 ROI)

완료·미결(open loops)·stale·다음주 우선순위를 한 장으로 종합 → "몇 시간→몇 분". weekly-review 스킬로 자동화(/weekly-review, 금요일). 회고·계획·상급자 보고 초안을 한 번에.

이 위키만의 차별점 (일반 Notion+AI 대비)

참고: Karpathy LLM Wiki(지식=컴파일된 코드) · AI Second Brain(회의노트→action item·주간리뷰 자동화) · living knowledge base. 상세 매핑은 위키 페이지 concept-wiki-daily-usage.

7. v2 메커니즘 상세

v2.1 타이밍 주의: 아래 신뢰도·덮어쓰기·관계는 개념이고, v2.1에서는 인제스트가 아니라 lint 배치 시점에 계산·구조화된다(lazy). 인제스트는 신규 개념에 confidence 0.6만 고정으로 붙이고, 재계산·병합·관계는 미룬다.

7-1. 신뢰도 점수 (Confidence)

주장의 확실성을 0.0~1.0으로. 소스 수·유형에서 결정적으로 계산 (confidence.py).

최종값은 [0.0, 1.0]로 클램프. L3/L4 페이지 frontmatter confidence:에 기록하고, 질의 답변에 병기한다.

python3 .claude/skills/wiki-consolidate/scripts/confidence.py --count 3 --official   # → 1.0
python3 .claude/skills/wiki-consolidate/scripts/confidence.py --kinds official,normal,verbal   # → 0.95

7-2. 덮어쓰기 (Supersession)

새 정보가 옛 정보와 다르면 삭제하지 않고 명시 대체:

• 옛 페이지: status: stale + superseded_by: [[새-페이지]]

• 새 페이지: supersedes: [[옛-페이지]]

• 서로 링크, 타임스탬프 기록 → 이력 보존

어느 쪽이 맞는지 불명한 단순 상충은 대체가 아니라 > [!warning] 상충 콜아웃으로 두 출처를 병기한다.

7-3. 망각 (Forgetting) — Ebbinghaus 곡선

시간이 지나면 정보의 보존율이 지수적으로 감쇠한다. 재확인하면 리셋.

보존율 R = exp(−Δt / S) — Δt = 마지막 확인 후 경과일, S = 안정성(decay_class가 결정).

보존율 밴드: R≥0.5 fresh / 0.3≤R<0.5 aging(재확인 권장) / R<0.3 faded(아카이브 후보 — 자동 삭제 금지).

리셋: 재확인 시 last_confirmed: 오늘 → Δt=0 → R=1.0.

lint가 decay.py --scan으로 faded 페이지를 표시한다.

7-4. 통합 계층 (Consolidation Tiers)

2-2장 참조. 요지: 반복·시간·신뢰도로 정보를 차등. 자주 확인되는 것은 위로 올라가 오래 살고(L4 절차), 한 번 스친 것은 아래에서 망각된다(L1/transient). 사람 기억이 그렇게 작동한다.

7-5. 엔티티 관계 (Entity Relations)

엔티티 페이지 ## 관계 섹션에 구조화된 관계를 기록 (Obsidian 인라인 필드 :: — Dataview 질의 가능):

## 관계
- caused :: [[incident-x]] (sources: 3, confidence: 0.9)
- depends_on :: [[postgres]] (sources: 1, confidence: 0.6)
- fixed :: [[bug-123]] (sources: 2, confidence: 0.85)

관계 유형: uses · depends_on · contradicts · caused · fixed · supersedes. 각 관계에 소스 수·신뢰도 병기.

7-6. 자동화 (Automation)

정직한 한계: Claude Code 훅은 셸만 실행 — LLM lint를 스스로 못 돌린다. 그래서 훅은 조건 검사 + 알림까지만 한다.

두 개의 훅 (.claude/settings.json):

1. SessionStart 훅 — wiki-status-check.py

   • 세션 시작 시 1회 실행 (Stop 훅은 매 턴 발화 = 스팸이라 회피)

   • lint-due.py로 마지막 lint 3일+ 경과 또는 L1 미압축 감지

   • 해당 시 모델 컨텍스트에 알림 주입 → Claude가 능동으로 lint/consolidate 제안

   • 아무것도 안 걸리면 {} (조용)

2. PostToolUse 훅 — updated: 스탬프

   • Write|Edit로 .md 파일을 건드리면 frontmatter updated:를 오늘로 자동 갱신

진짜 자율 백그라운드 lint를 원하면 → Claude Code /schedule (클라우드 크론 에이전트)로 별도 배선. 예: "매주 월요일 위키 lint 돌려줘".

7.5 질의 리트리벌 최적화 (v0.8.4~v0.9.0)

질의 응답이 질의당 52~62k 토큰을 쓰던 문제(index 통독 + 광역 MoC 스윕)를 결정적 그래프 스코프 + 질의유형 라우팅으로 최적화했다. A/B 9라운드 실측·매 릴리즈 외부감사(agy). 상세: develop_docs/v0.8.3/TECH-SUMMARY.md, develop_docs/v0.8.5/COMBO.md, 실측 원장 metrics/ab-results.csv.

핵심 이동

[구식]  질의 → index(218줄) 통독 → MoC 다수 → 페이지 12~19 full-read → 종합
[신식]  질의 → scope-expand.py(0토큰): lexical seed → 관계 1홉 확장 → (rerank) → claims 팩
       → synthesizer: 팩 1-read → 부족분만 full-read → 종합

적용 기술과 근거자료

요약: 우리 claims 팩 = parent-retriever의 small-side였고, rerank·라우팅이 빠진 조각이었다. Adaptive-RAG로 질의유형을 나누고, Contextual Retrieval의 reranking을 BM25로 얹어 완성.

질의유형별 라우팅 (파라미터)

실측 결과 (동일조건 A/B)

교훈 (실측 검증)

• 관계 도달은 lexical로 안 됨 → 그래프 1홉 확장 필수.

• 팩은 사실질의에만 이득 → 절차질의는 full-read 라우팅.

• rerank는 최대 레버지만 다이얼 → 조이면 싸지고 recall 준다(11이 균형).

• recall의 진짜 레버는 --max가 아니라 키워드 품질(엔티티 포함).

• 절차질의 비용은 근본적 → 스코핑으로 못 줄임. 반복비용은 환류 캐시(query 페이지)로만.

• 관계질의는 새 유형 아님 → 팩에 관계 실으면 사실브리핑 라우트로 커버.

전체 근거자료·구현 상세·A/B 원장: develop_docs/v0.8.3/TECH-SUMMARY.md. 관련 리서치 — GraphRAG · Parent-Document Retriever · Adaptive-RAG · Anthropic Contextual Retrieval · Contextual Compression · Self-RAG · Stop-RAG · AB-RAG.

8. Frontmatter 스키마 레퍼런스

모든 위키 페이지 상단에 YAML frontmatter. 파일이 type:을 가져야 위키 페이지로 인식된다(스크립트가 CLAUDE.md 같은 비-페이지를 걸러냄).

---
type: working | episodic | session | source | fact | entity | concept | procedure | moc | index | log | query
title: <한국어 제목>
aliases: []                  # 영문 파일명의 한국어 라벨/별칭
tags: []                     # 소문자, 예: [llm, training]
created: YYYY-MM-DD
updated: 2026-09-09

# --- L3/L4 전용 (신뢰도·망각) ---
confidence: 0.0~1.0          # confidence.py로 계산
sources: [소스-슬러그, …]     # 근거 소스 (개수가 신뢰도 결정)
last_confirmed: YYYY-MM-DD    # 재확인마다 갱신 → 망각 리셋
decay_class: architecture | procedure | concept | entity | episodic | transient
status: active | stale        # 대체된 정보는 stale (삭제 안 함)
superseded_by: [[새-페이지]]   # (옛 페이지에) 대체됨
supersedes: [[옛-페이지]]      # (새 페이지에) 대체함

# --- source 페이지 전용 ---
source_url: <URL 또는 raw 경로>
source_kind: official | code | normal | verbal
---

raw 파일 인제스트 스탬프 (raw/ 원본 맨 위에만 추가 — 본문 무변경, 완료 표시·중복 방지):

---
ingested: YYYY-MM-DD
wiki_source: [[source-<slug>]]   # 생성된 L2 증거 페이지
ingest_status: done
---

raw 본문은 immutable이지만 이 상태 스탬프는 예외. ingest-status.py가 이 표시로 done/pending을 판별한다.

규약 요약:

• 본문 한국어, 파일명 영문 kebab-case ([[wikilinks]] 깔끔)

• [[wikilinks]] 양방향, 없는 페이지 링크는 스텁으로 남김

• 모든 L3/L4 페이지는 ≥1 MoC 도달 가능 (고아 방지)

• 소스 immutable, 충돌은 병기 또는 supersession

• 파일 이동·이름변경은 승인 후 (wikilink 깨짐)

9. 스크립트 레퍼런스

confidence.py

# 소스 수 + 유형으로 신뢰도 계산
python3 .claude/skills/wiki-consolidate/scripts/confidence.py --count 2                    # 0.85
python3 .claude/skills/wiki-consolidate/scripts/confidence.py --count 1 --official         # 0.7
python3 .claude/skills/wiki-consolidate/scripts/confidence.py --kinds official,normal      # count=2, +official → 0.95
python3 .claude/skills/wiki-consolidate/scripts/confidence.py --count 3 --json             # {"score":0.95,...}

소스 유형: official|code(+0.1) · verbal(−0.1) · normal.

decay.py

# 단일 페이지 보존율
python3 .claude/skills/wiki-lint/scripts/decay.py --class architecture --last 2026-01-01   # "0.57 fresh"
python3 .claude/skills/wiki-lint/scripts/decay.py --class transient --last 2026-07-01       # "0.04 faded"
# 위키 전체 스캔 — faded/aging 페이지 나열
python3 .claude/skills/wiki-lint/scripts/decay.py --scan . --json

--today YYYY-MM-DD로 기준일 지정 가능(기본 오늘). last_confirmed 없으면 updated: 사용.

link-audit.py

python3 .claude/skills/wiki-lint/scripts/link-audit.py .           # 사람이 읽는 리포트
python3 .claude/skills/wiki-lint/scripts/link-audit.py . --json    # {broken, orphans, ...}

• broken: 대상 페이지가 없는 [[wikilink]] ((page,target) 중복 제거)

• orphans: inbound 링크 0인 페이지 (단, index/log/working/episodic/session/source 유형은 제외 — 정상적으로 inbound 0)

• stub_targets: 없는 페이지를 가리키는 링크를 참조 페이지 수(inbound)순으로 집계 → 여러 페이지가 가리키는 스텁 = 누락 개념 최우선 작성 후보. (의도된 스텁과 오타 broken을 구분하는 신호)

• HTML 주석·코드펜스 안의 링크는 무시. type: 있는 파일만 페이지로 취급.

lint-due.py

python3 .claude/skills/wiki-lint/scripts/lint-due.py . 3      # 임계 3일
# 출력: "DUE 5" | "OK 2" | "NEVER"  +  "L1:<미압축 페이지 수>"

log.md의 마지막 ## [날짜] lint 항목으로 경과일 계산.

wiki-status-check.py

SessionStart 훅이 호출. lint-due.py 결과로 알림 JSON을 만든다. DUE거나 L1>0이면 {"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"..."}}, 아니면 {}.

search.py

python3 .claude/skills/wiki-lint/scripts/search.py "transformer"      # wiki/ 전체 grep (rg 미의존)

list-claims.py

python3 .claude/skills/wiki-consolidate/scripts/list-claims.py .      # L2-episodic의 claim:: 라인 수집

같은 주장이 3회+ 등장하는지 LLM이 클러스터링하는 입력(배치 병합·승격).

concept-index.py

python3 .claude/skills/wiki-ingest/scripts/concept-index.py .         # 기존 L3/L4 카탈로그
# 출력: slug | title | aliases | confidence  (frontmatter만, 한 줄씩)

lazy 인제스트의 핵심 — 45개 페이지 본문을 Read하는 대신 이 한 출력만 보고 개념이 기존인지 신규인지 판별한다(토큰 O(1) 유지).

cost-report.py

python3 metrics/cost-report.py                # 문서당 토큰·페이지 효율 표
python3 metrics/cost-report.py --by-model     # opus vs sonnet 비교 (모델가중 wcost)

metrics/ingest-cost.csv(오케스트레이터가 인제스트마다 append)를 읽어 tok/page·모델가중 비용을 낸다. v2/v2.1 비용대비효과 추적용. MODEL_PRICE 상대단가 opus 5·sonnet 1·haiku 0.25.

ingest-status.py

python3 .claude/skills/wiki-lint/scripts/ingest-status.py .           # raw/ 인제스트 상태
# 출력: DONE <date> <file> | PENDING <file>  +  "ingested: N   pending: M"

raw 파일 맨 위 스탬프(ingest_status: done)를 읽어 인제스트 완료/대기를 판별. raw 본문은 immutable — 스탬프는 맨 위 메타 블록만 추가(본문 무변경). Obsidian에서 각 소스에 완료 표시가 보이고, 중복 인제스트를 막는다. wiki_source 필드는 생성된 L2 증거 페이지로 클릭 이동. 미인제스트 소스는 SessionStart 훅도 알린다.

환경 주의: 스크립트는 grep·python3만 의존한다. rg(ripgrep)는 비로그인 셸 PATH에 없는 경우가 많아 쓰지 않는다.

10. Obsidian 설정 팁

• Web Clipper — 브라우저 확장. 웹 기사를 markdown으로 변환해 raw/에 빠르게 저장.

• 이미지 로컬 다운로드 — Settings → Files and links → Attachment folder path를 raw/assets/로. Settings → Hotkeys에서 "Download attachments for current file"을 단축키(예: Ctrl+Shift+D)로 바인딩. 클리핑 후 눌러 이미지 로컬 저장 → LLM이 이미지를 직접 참조 가능(끊기는 URL 대신).

  • 단, LLM은 인라인 이미지가 섞인 md를 한 번에 못 읽는다 — 텍스트 먼저 읽고, 필요한 이미지만 별도로 본다.

• 그래프 뷰 — 위키 형태(허브·고아)를 보는 최고의 도구.

• Dataview 플러그인 — frontmatter(confidence·tags·sources·관계 ::)로 동적 테이블·리스트 생성.

• Marp 플러그인 — 위키 내용에서 슬라이드 덱 직접 생성.

• git — 위키는 결국 markdown git 레포. 버전 이력·브랜치·협업 무료.

템플릿 (회의록·오늘의 노트)

templates/에 두 템플릿이 있다. Obsidian 코어 플러그인으로 연결한다.

회의록 — templates/meeting.md → raw/meetings/

• 성격: 회의는 구두 소스(source_kind: verbal) — 인제스트 시 신뢰도 −0.1.

• 섹션: 안건 / 논의·결정 / 액션. frontmatter=메타(date·attendees), 본문=내용, 파일명=제목(중복 없음).

• 연결: 설정 → 코어 플러그인 Templates 켜기 → 템플릿 폴더 templates → 새 노트에서 Cmd+P → "Insert template" → meeting.

• 흐름: 회의 중 기록 → raw/meetings/에 저장 → "인제스트해줘" → 결정·액션이 위키에 통합(ingest-status가 자동으로 pending 감지).

오늘의 노트 — templates/daily.md → raw/notes/

• 성격: 개인 스크래치(할 일·배운 것). 지식이 아니라 타임라인 → 인제스트해도 L2-episodic 기록만, L3 개념 생성 안 함.

• 섹션: 할 일 / 한 일·배운 것 / 메모. 파일명=날짜.

• 연결: 설정 → 코어 플러그인 Daily notes 켜기 → New file location raw/notes · Template file location templates/daily · Date format YYYY-MM-DD → 달력 아이콘/"Open today".

• 주의: raw/notes/는 인제스트 pending 스캔에서 제외돼 있다(매일 노트가 알림을 시끄럽게 안 만들게). 특정 날 노트를 위키에 넣고 싶으면 수동 인제스트.

동적 템플릿: 날짜 자동·참석자 입력이 필요하면 Templater 커뮤니티 플러그인. {{date}} → <% tp.date.now("YYYY-MM-DD") %>, 입력받기 <% tp.system.prompt("제목") %>. 폴더 템플릿으로 raw/meetings/·raw/notes/에 새 노트 만들 때 자동 적용도 가능.

11. 하네스 진화·확장

하네스는 정적 산출물이 아니라 진화하는 시스템이다.

• 피드백 반영 경로:

  피드백 유형	수정 대상
  결과물 품질	해당 에이전트의 스킬 (.claude/skills/*/SKILL.md)
  에이전트 역할	에이전트 정의 (.claude/agents/*.md)
  워크플로우 순서	오케스트레이터 (wiki-ops/SKILL.md)
  트리거 누락	스킬 description
  신뢰도 규칙	confidence.py (base_for·모디파이어)
  망각 속도	decay.py STABILITY 딕셔너리
  승격 임계	wiki-consolidate/SKILL.md (3회/2회)

• 모든 변경은 CHANGELOG.md(하네스 변경 이력)에 기록 — 하네스가 어떻게 진화했는지 추적, 퇴행 방지. (2026-09-11 에 CLAUDE.md 에서 분리 — CLAUDE.md 는 현재 규칙만 둔다)

• 재-myharness: 큰 아키텍처 변경은 /myharness:myharness에 개선안을 넘겨 자동 확장. update 인자로 팩토리 정본 변경을 빌드된 하네스에 재전파(사용자 수정 보존).

튜닝 예시 — 망각을 더 느리게:

# .claude/skills/wiki-lint/scripts/decay.py 의 STABILITY 수정
STABILITY = { "architecture": 730, ... }   # 365 → 730일

12. 트러블슈팅

검증 명령 모음:

# 링크 정합
python3 .claude/skills/wiki-lint/scripts/link-audit.py .
# 스크립트 문법
for s in $(find .claude/skills -name '*.sh'); do bash -n "$s"; done
for p in $(find .claude/skills -name '*.py'); do python3 -m py_compile "$p"; done
# 훅 JSON 유효성
jq -e '.hooks' .claude/settings.json

13. 설계 결정 요약

부록 — 빠른 시작 (TL;DR)

1. Obsidian 볼트 생성, Claude Code를 볼트에서 실행
2. /hooks 한 번 열어 훅 로드
3. raw/ 에 첫 소스 넣기 (Web Clipper 추천)
4. "이 소스 인제스트해줘"  → L2 증거 + L3 사실(신뢰도) 생성
5. "llmops MoC 만들어줘"   → 네비게이션 지도
6. "위키에 ~ 질문"         → 신뢰도 포함 인용 답변
7. "위키 린트"             → 망각·모순·승격 점검
8. "세션 마무리"           → L1→L2 압축
9. Obsidian 그래프 뷰로 위키 형태 브라우징

현재 상태는 CLAUDE.md(스키마), 하네스 변경 이력은 CHANGELOG.md, 위키 타임라인은 log.md 가 정본이다.