이 가이드북을 읽는 법

세 파트는 하나의 흐름입니다 — 쌓고 → 찾고 → 꺼내 쓰기.

왜 "LLM이 읽을 수 있는 위키"인가

Karpathy는 2025년에 이렇게 말했습니다.

앞으로 내 글·노트를 읽는 쪽은 점점 사람이 아니라 AI가 된다는 뜻입니다. 그러니 내 지식을 검색·요약·AI 비서의 연료로 쓰려면, 사람만 보기 좋은 예쁜 문서(PDF·이미지·특정 앱 전용 포맷)가 아니라 LLM이 그대로 먹을 수 있는 형식 — 즉 plain markdown(일반 텍스트 노트)으로 쌓아야 유리합니다. 이것이 "LLM wiki" 발상의 출발점이에요.

왜 하필 마크다운인가 — AI가 읽기 좋은 5가지 이유

"plain markdown으로 쌓아라"는 말은 자주 듣지만, 왜 하필 마크다운이어야 하는지는 잘 안 알려줍니다. 여기서 그 이유를 처음부터 풀어볼게요. 이 절만 이해하면 LLM wiki의 절반은 잡은 셈입니다.

마크다운(Markdown)은 그냥 글자(텍스트)입니다. 거기에 약속된 기호 몇 개만 더한 거예요. 워드처럼 버튼을 눌러 굵게·제목을 만드는 게 아니라, 기호로 직접 표시합니다.

LLM(AI 언어모델)은 글을 통째로 보는 게 아니라, 토큰(token)이라는 작은 글자 조각으로 잘라서 읽습니다. 그리고 그 입력은 결국 순수한 텍스트(글자)예요 — 그림도 표도, LLM 앞에서는 일단 글자로 바뀌어야 읽힙니다. 이 한 가지 사실이 아래 다섯 이유의 뿌리입니다.

마크다운은 처음부터 글자라, LLM이 그대로 바로 먹습니다. 반면 PDF·이미지·한글(.hwp)·워드 파일은 LLM이 읽기 전에 "글자만 뽑아내는 변환"을 먼저 거쳐야 해요. 그 변환에서 표가 뭉개지고 줄바꿈·순서가 깨지는 일이 흔합니다.

사람은 큰 글씨·굵은 글씨를 보고 "아, 이게 제목이구나" 압니다. 그런데 LLM은 글씨 크기를 못 봐요 — 글자만 봅니다. 마크다운은 그 구조를 기호로 적어두기 때문에, LLM이 #를 보고 "제목", -를 보고 "목록 항목"이라고 글자만으로 문서의 뼈대(위계)를 파악합니다.

같은 "제목" 하나도 형식에 따라 글자 수가 확 다릅니다.

LLM이 한 번에 읽을 수 있는 양(토큰)은 정해져 있고, 토큰은 곧 비용이기도 합니다. 마크다운은 군더더기 태그가 없어 같은 내용을 더 적은 토큰에 담아요 → 한 번에 더 많은 지식을, 더 싸게 읽힐 수 있습니다.

LLM은 인터넷의 방대한 글로 학습했는데, 그중 마크다운으로 쓰인 글이 아주 많습니다 — 개발자 설명서(README), 위키, 기술 문서 상당수가 마크다운이거든요. 그래서 LLM에게 마크다운은 읽기도 쓰기도 자연스러운, 손에 익은 형식입니다.

마크다운에서 노트끼리의 연결([[노트이름]])도 그냥 글자입니다. 그래서 LLM이 "이 노트가 저 노트와 이어져 있다"를 읽는 즉시 압니다 — 그리고 이 연결망이 바로 Part 2의 지식 그래프(검색의 재료)가 됩니다. 또 텍스트라서 한 줄을 고치면 딱 그 한 줄만 달라져, "무엇이 언제 바뀌었는지" 추적(버전 관리)도 쉽습니다.

근거: microsoft/markitdown · Anthropic "Use XML tags" · The Stack(BigCode)·Common Crawl · Cloudflare "Markdown for Agents"(토큰 측정 사례) — 코난 1차/권위 출처 검증(2026-06-08). 토큰 절감 구체 수치는 콘텐츠마다 편차가 커 범위로만 봅니다.

왜 하필 옵시디언인가 — AI의 모국어로 쌓기

마크다운이 "AI가 읽기 좋은 형식"이라면, 옵시디언은 그 마크다운을 가장 잘 다루는 도구입니다. 단순한 메모장이 아니에요 — 노트를 쓰는 것만으로 AI가 이해하기 좋은 구조가 자연스럽게 만들어집니다. 비결은 셋이에요: 프론트매터 · 위키링크 · 그래프.

프론트매터(front matter)는 노트 맨 위에 --- 두 줄 사이에 적는 짧은 메타데이터(머리말 정보)입니다. 제목·태그·날짜처럼 "이 노트가 무엇인지"를 정해진 칸에 적어 두는 거예요.

왜 AI에 좋을까요? AI나 검색 시스템이 본문 전체를 읽지 않고도 머리말만 훑어 분류·필터·검색할 수 있기 때문입니다. 수백 개 노트 중 "AI 태그가 달린, 올해 노트"를 골라내는 일이 한순간이 돼요.

옵시디언에선 [[노트이름]]이라고 쓰면 그 노트로 가는 링크가 됩니다(앞 절에서 본 그 기호예요). 폴더 경로를 외울 필요 없이 이름만으로 노트와 노트를 잇죠.

위키링크로 이어진 노트들을, 옵시디언은 점(노트)과 선(링크)으로 그린 그래프로 보여줍니다. 내 지식 전체가 한 장의 지도로 펼쳐지는 거예요. 그리고 결정적으로 — 이 연결망이 그대로 Part 2의 "지식 그래프(GraphRAG)" 재료가 됩니다. 내가 노트를 이어 둔 방식이, 나중에 검색이 똑똑해지는 바탕이 돼요.

근거: 프론트매터·위키링크·그래프 뷰의 기능 정의 = 옵시디언 공식 문서(help.obsidian.md) · "AI·검색에 유리"는 앞 절의 마크다운 특성에서 유도한 평가 · "X-ray" 비유는 이해를 돕기 위한 설명으로 특정 인물의 출처는 아닙니다 — 코난 공식/1차 출처 검증(2026-06-08).

Andrej Karpathy의 "LLM wiki" — 실제로 어떻게 도는가

OpenAI 창립 멤버·전 Tesla AI 디렉터. 2026년 개인 지식관리 방법 "LLM Knowledge Base / LLM wiki"를 공개해 큰 반향을 일으켰고, "LLM wiki"라는 말이 퍼진 진원지입니다.

발상은 단순합니다 — "코드를 다루는 데 쓰던 AI를, 이제 지식을 다루는 데 쓴다."

그가 공개한 설계(본인 gist llm-wiki.md)는 세 층으로 나뉩니다.

1. raw/ (원자료 · 불변) — 내가 모은 원본(논문·기사 등). "immutable — the LLM reads from them but never modifies them. This is your source of truth." 고치지 않고 추가만 하는 단일 진실 원천.
2. wiki/ (LLM이 소유) — LLM이 만든 마크다운 페이지들(요약·개념·비교). "The LLM owns this layer entirely."
3. schema (규약) = CLAUDE.md / AGENTS.md — LLM에게 "위키가 어떻게 구성되고, 규칙·작업방식이 무엇인지" 알려주는 설정 문서. 그의 표현으로 "what makes the LLM a disciplined wiki maintainer rather than a generic chatbot. You and the LLM co-evolve this over time." → LLM을 규율 있는 위키 관리자로 만드는 핵심. 사람과 LLM이 함께 다듬어 갑니다.

1. Ingest(수집·편입) — 원본 1개를 raw에 넣고 "처리해줘"라고 하면, LLM이 읽고 → 핵심을 나와 상의 → 요약 페이지 작성 → 색인(index) 갱신 → 관련 개념·인물 페이지 갱신 → 로그(log)에 기록. 그의 말로 "A single source might touch 10-15 wiki pages." (소스 하나가 10~15개 페이지를 건드림.)
2. Query(질문) — 위키에 물으면 LLM이 관련 페이지를 찾아 출처와 함께 답함. 핵심은 "good answers can be filed back into the wiki as new pages... your explorations compound." 좋은 답을 다시 위키로 보관하니, 탐색이 채팅에서 증발하지 않고 복리처럼 쌓입니다.
3. Lint(점검) — 주기적 건강검진. "contradictions between pages, stale claims, orphan pages with no inbound links, important concepts lacking their own page, missing cross-references, data gaps." (모순·낡은 주장·고아 페이지·빠진 개념·끊긴 참조·빈틈 찾기.)

출처(1차): gist · llm-wiki.md · 트윗(지식 다루기) · 트윗(context engineering). 위키 규모 "~100글·40만 단어"는 2차 보도 기준.

Karpathy 패턴 ↔ 우리 시스템 (그대로 대응)

우리 옵시디언 vault·봇 시스템은 Karpathy의 LLM wiki와 거의 1:1로 대응합니다. 이 표 하나가 Part 1 → Part 2 → Part 3 전체를 꿰어요.

노트 방법론 지도 — 따라 할 수 있는 실전 how-to

Karpathy만 그런 게 아닙니다. "내 지식을 일반 텍스트로, 내가 소유하며, 연결해서 쌓는다"는 흐름은 여러 갈래로 이미 있었어요. 각각 바로 따라 할 수 있게 정리했습니다.

1. 형식부터 개방형으로 — 노트를 .md·.txt로. 앱 전용·클라우드 종속 포맷 회피(앱이 사라져도 메모장으로 열림).
2. 로컬 소유 + 동기화는 보조 — vault를 내 컴퓨터 폴더에(예 ~/Documents/vault/).
3. 폴더는 최소·평평하게 — 깊은 계층 대신 최상위에 노트, 폴더는 소수만.
4. 경로 대신 링크로 — [[노트이름]] + 빠른 전환(Cmd/Ctrl+O).
5. 정기 재방문 — 일·월·연 리뷰로 과거 아이디어 재연결.

LYT(Linking Your Thinking)의 핵심 도구 MOC = 관련 노트로 가는 링크를 사람이 직접 큐레이션한 지도 노트.

1. "정신적 압박점" 감지 — "한 주제에 아는 건 많은데 정리가 안 돼" 느낌이 MOC 만들 신호(밀로의 용어).
2. 관련 노트 모으기 — 검색·태그로 목록화(15~30개 모이면 적기).
3. 허브 노트 신설 — 예 MOC_프로젝트관리.md, 맨 위 한 문장 설명.
4. 카테고리별 정렬 — ## 핵심 개념 / ## 도구 / ## 사례로 묶어 링크 나열.
5. 비파괴 오버레이 — 원본 노트는 그대로, MOC는 위에 얹는 지도. 새 노트 생기면 갱신.

기준은 "주제"가 아니라 "지금 얼마나 실행에 쓰이나"입니다.

결정 규칙: 마감 있나?→P / 끝없는 책임?→A / 지금은 아니지만 나중에?→R / 더 안 씀?→Archive.

이 방식의 뿌리는 독일 사회학자 Niklas Luhmann(1927–1998)의 Zettelkasten(쪽지 상자) — 평생 약 9만 장의 카드를 1장 = 1아이디어로 적고 서로 연결해 방대한 저술을 남긴 노트법입니다. Matuschak의 Evergreen은 그 현대판이에요.

그의 실제 노트 제목 그대로(verbatim):

터미널에서 LLM을 부르는 그의 도구 llm 실사용 예:

그리고 TIL(Today I Learned) — 매일 배운 작은 걸 짧게 공개 기록("미래의 내가 다시 검색 안 하도록"). 자기 위한 기록인데 부수효과로 남에게도 도움이 됩니다.

출처: stephango.com · linkingyourthinking.com · fortelabs.com · notes.andymatuschak.org · llm.datasette.io

우리 옵시디언 vault — 다섯을 합친 한국어 실천판

위 방법들을 한데 합친 게 우리 옵시디언 vault입니다. 큰 폴더는 역할로 나뉩니다(주제가 아니라 — Forte의 PARA 정신).

노트 사이는 [[위키링크]]로 잇습니다(Milo의 연결). 자주 찾는 주제는 MOC(지도 노트)로 묶고(Milo), 노트는 가능한 한 원자적으로 쪼갭니다(Matuschak). 전부 plain markdown — 우리가 소유하고(kepano), AI가 그대로 읽습니다(Karpathy).

"폴더를 어떻게 짜야 하나?"엔 정답이 없습니다. 유명한 세 방식을 비교해 보면, 뿌리는 같고 취향만 다릅니다.

우리 vault는 재경 방식(숫자 prefix로 역할 고정)에 가깝지만, 어느 쪽이든 plain markdown + 위키링크라는 뿌리는 같아요. 처음엔 아무거나 하나 골라 시작하고, 쓰면서 내 손에 맞게 바꾸면 됩니다.

knowledge-manager — 흩어진 자료를 LLM wiki로

노트를 처음부터 다 손으로 쓰는 건 무리예요. 우리 자료는 이미 여기저기 흩어져 있죠 — PDF 보고서, 워드 문서, 노션 페이지, 메신저 대화, 웹 기사. 이걸 한 번에 LLM wiki로 빨아들이는 도구가 우리 knowledge-manager(지식 관리자)입니다.

누구나 겪는 일이죠. 중요한 자료는 분명 어딘가 있는데, PDF는 다운로드 폴더에, 회의록은 노션에, 링크는 메신저에 흩어져 찾질 못합니다. AI에게 물어봐도, 그 자료가 AI가 읽을 수 있는 형태로 한곳에 모여 있지 않으면 소용없어요.

한 줄 명령(/knowledge-manager)을 주면, 안에서 다섯 단계가 차례로 돕니다.

1. 수집(Collect) — 자료를 가져옵니다(PDF·웹·노션 등).
2. 분석(Analyze) — 무슨 내용인지, 핵심이 무엇인지 파악합니다.
3. 변환(Convert) — AI가 읽기 좋은 마크다운으로 바꿉니다(앞 절의 그 형식!).
4. 저장(Store) — 프론트매터(이름표)를 달아 vault 알맞은 폴더에 저장합니다.
5. 연결(Link) — 관련 노트와 [[위키링크]]로 잇고, 필요하면 MOC(지도 노트)에 등록합니다.

자료 종류마다 꺼내는 방법이 달라요. 웹 기사는 본문만 긁어오고, PDF는 글자를 떠내는 여러 단계를 거치고, 노션·메신저는 또 각자의 방식이 있죠. knowledge-manager는 입력이 무엇인지 감지해 알맞은 추출 경로로 자동 분기합니다 — 사용자는 "이거 넣어줘"만 하면 됩니다.

회사 자료를 다룬다면 경계가 중요합니다. 기밀 문서·고객 정보를 외부 AI 서비스에 함부로 올리면 안 되죠.

오늘 바로 시작하기 — 5단계

거창할 필요 없어요. 오늘 한 폴더부터가 당신의 LLM wiki 첫걸음입니다.

1. Obsidian 설치(무료) → vault 폴더 하나 생성.
2. PARA 폴더 4개(Projects/Areas/Resources/Archives) + 임시 Inbox (Forte).
3. 영역마다 MOC 1개(예 MOC_AI학습.md) — 관련 노트를 모아 지도로 (Milo).
4. 마크다운 + [[위키링크]]로 노트 작성, 한 노트 한 개념 (kepano·Matuschak).
5. LLM 연동(LLM wiki化) — raw/에 원자료를 넣고 Claude Code/Codex에 "이 소스 읽고 요약 페이지 + 색인 갱신"(=Ingest) → "쌓인 노트 종합해줘"(=Query). 규약은 CLAUDE.md로 (Karpathy).

한국에서는 — 그리고 이 강의

이게 먼 나라 이야기 같나요? 한국에서도 이미 일어나고 있습니다(아래는 직접 확인한 출처만).

※ 검증되지 않은 한국어 URL은 일부러 싣지 않았습니다(가짜 출처 박제 방지 — 코난 리서치 원칙).

검색 한 번에 무슨 일이 벌어지나

검색이라고 하면 보통 "단어가 들어간 문서 찾기"를 떠올립니다. 하지만 좋은 검색은 그보다 훨씬 많은 일을 합니다. 같은 뜻을 다른 단어로 쓴 글도 찾아야 하고("반려견"으로 물어도 "강아지" 글), 흔한 단어에 묻힌 핵심 문서를 위로 끌어올려야 하고, 여러 방식이 추천한 결과를 하나로 합쳐야 합니다. 우리 /search는 이걸 다섯 단계로 합니다.

1. 네 갈래로 동시에 찾기. ㉠뜻으로(의미검색) ㉡단어 그대로(키워드검색) ㉢질문을 작은 질문으로 쪼개서 ㉣개념(엔티티) 매칭. 한 갈래만 쓰면 놓치는 걸 서로 메웁니다.
2. 공정하게 합치기. 네 갈래가 각자 추천한 순위표를 RRF(순위 융합)로 합칩니다. 점수 척도가 제각각이어도 "순위"만 쓰니 안전합니다.
3. 정밀 심사. 합쳐서 추린 상위 후보만 리랭커가 질문과 한 묶음으로 정독해 다시 줄세웁니다. 1차 서류전형 → 2차 면접.
4. 결과 내기. 최종 Top-5 문서 + 신뢰도 4단계(high/medium/low/very_low). 여기까지가 검색의 일입니다.
5. (선택) 답변 만들기. 원하면 그 Top-5를 근거로 LLM이 자연어 답까지 합성(기본 OFF). 이게 RAG의 'G(생성)' 부분 — 마지막 장에서.

RAG — 오픈북 시험의 원리

거대 언어모델(LLM)은 학습할 때 본 지식을 신경망 가중치 안에 욱여넣습니다. 이걸 파라메트릭 메모리(parametric memory, 모델 속 기억)라고 합니다. 문제는 셋입니다. ①내 개인 지식(내 vault 메모)은 학습에 없었으니 모름. ②지식이 옛날 것이라 최신을 모름. ③근거 출처를 못 대니 그럴듯하게 지어내기 쉬움(환각, hallucination). 모델을 다시 학습시키는 건 비싸고 느립니다.

RAG(검색증강생성, Retrieval-Augmented Generation)는 이 셋을 한 번에 푸는 아이디어입니다. 답하기 전에 외부에서 관련 문서를 검색해 와서, 그 문서를 질문과 함께 모델에 넣어 줍니다. 모델은 "기억"이 아니라 "눈앞의 자료"를 보고 답합니다.

1. R (Retrieval, 검색): 질문과 관련된 문서를 외부 저장소에서 찾는다. ← 이 가이드북의 거의 전부가 바로 이 단계 이야기입니다(우리 /search).
2. A (Augmented, 증강): 찾아온 문서를 질문에 "붙여서" 모델에게 줄 입력을 만든다. ("아래 자료를 참고해 답하라: [문서1][문서2]… 질문: …")
3. G (Generation, 생성): 모델이 그 자료를 근거로 자연어 답을 쓴다.

최신·개인 지식을 반영하고, 출처를 제시해 환각을 줄이며, 재학습 없이 지식만 갈아끼울 수 있습니다. 다만 답 품질이 검색 품질에 종속됩니다. 검색이 엉뚱한 문서를 가져오면 모델은 그 위에 그럴듯한 틀린 답을 씁니다("garbage in, garbage out"). 그래서 RAG의 핵심은 사실 '생성'보다 '검색'입니다 — 이 가이드북이 검색에 집중하는 이유입니다.

임베딩 & Dense 검색 — 의미를 좌표로

키워드 검색만으로는 "반려견 키우는 법"을 물었을 때 "강아지 기르기" 글을 못 찾습니다. 글자가 다르니까요. 사람은 두 문장이 같은 뜻인 걸 압니다. 컴퓨터도 그렇게 하려면 의미를 비교 가능한 형태로 바꿔야 합니다. 그게 임베딩입니다.

임베딩(embedding)은 문장을 고정 길이 숫자 배열(벡터)로 바꾼 결과입니다. 우리 모델은 한 문장을 384개 숫자로 만듭니다. 이 숫자들은 사람이 정한 게 아니라, 신경망이 방대한 글을 학습하며 "비슷한 맥락에 쓰이는 문장은 비슷한 숫자가 되도록" 스스로 익힌 결과입니다.

"가깝다"는 보통 코사인 유사도로 잽니다. 두 벡터가 가리키는 방향이 얼마나 비슷한지를 봅니다(크기가 아니라 방향). 같은 방향이면 1.0, 직각이면 0, 반대면 -1.

이 벡터를 Dense(밀집) 벡터라 부릅니다. 384칸이 거의 전부 0이 아닌 값으로 빽빽이 차 있기 때문입니다. 다음 장에 나올 BM25의 'Sparse(희소)' 벡터(대부분 0)와 정확히 대비됩니다 — 이 둘의 차이가 하이브리드 검색의 출발점입니다.

말바꿈·동의어·번역에 강합니다("자동차"↔"승용차"↔"car"). 다만 정확한 고유명사·코드·아주 드문 용어에는 의외로 약합니다(임베딩이 그 단어를 뭉뚱그려 비슷한 것들과 섞어버림). 긴 문서는 한 점으로 압축하며 디테일이 뭉개집니다.

Sparse & BM25 — 단어를 정직하게 세기

"이 문서가 이 질문에 얼마나 맞나"를 단어로 답하는 가장 오래된 질문입니다. Ctrl+F는 단어가 "있나/없나"만 봅니다. 하지만 우리는 얼마나 관련 있나를 점수로 줄세워야 합니다. 그 점수 공식의 사실상 표준이 BM25입니다(검색엔진·엘라스틱서치 등이 다 씁니다).

BM25는 순진한 방법이 왜 실패하는지를 짚으며 세 번 고쳐나가면 가장 잘 이해됩니다.

첫 직관: 질문 단어가 문서에 많이 나올수록 관련 높다(TF, Term Frequency). 맞습니다. 그런데 함정이 있습니다 — "강의 강의 강의 강의…"를 30번 도배한 문서가 3번 자연스럽게 쓴 문서보다 10배 관련 높을까요? 아니죠.

그래서 BM25는 TF를 포화(saturation)시킵니다. 처음 몇 번은 점수가 쑥 오르지만, 곧 천장에 수렴해 더 나와도 거의 안 오릅니다.

둘째 문제: "그리고", "방법" 같은 단어는 거의 모든 문서에 있습니다. 이런 흔한 단어가 많이 나온다고 관련 높은 게 아닙니다. 반대로 "성우하이텍" 같은 희귀한 단어가 들어있으면 그 문서는 거의 확실히 관련 있습니다.

그래서 IDF(역문서빈도)로 단어마다 가중치를 줍니다 — 전체 문서 중 그 단어가 나오는 문서가 적을수록 가치↑.

셋째 문제: 5,000단어짜리 긴 문서는 짧은 문서보다 모든 단어를 더 많이 담습니다. 그냥 두면 긴 문서가 무조건 유리해집니다. 그래서 BM25는 문서 길이를 평균 길이와 비교해 보정합니다(파라미터 b≈0.75). 평균보다 긴 문서는 TF 점수를 깎고, 짧은 문서는 살려줍니다.

BM25식 검색을 Sparse(희소) 검색이라 부릅니다. 문서를 "사전의 모든 단어 = 한 칸"인 거대한 벡터로 본다면, 한 문서엔 그중 몇 칸만 켜지고 나머지는 전부 0이라서 텅 빈(희소) 벡터가 되기 때문입니다. 앞 장 Dense(밀집, 거의 다 채워짐)와 정반대입니다.

정확한 고유명사·제품명·코드·드문 전문용어에 매우 강합니다(임베딩이 약한 바로 그 지점). 하지만 동의어·말바꿈에는 약합니다 — "반려견"으로 찾으면 "강아지"만 쓴 문서를 못 찾습니다. 그래서 다음 장의 하이브리드(Dense+Sparse)가 필요합니다.

ANN & HNSW — 수만 점에서 빨리 찾기

2장의 의미 검색을 다시 떠올리면, 질문 벡터에서 가장 가까운 문서 벡터를 찾아야 합니다. 가장 정확하게 하려면 전부 하나씩 비교(brute-force)합니다 — 우리 엔티티 7,281개면 질문마다 7,281번 비교. 이건 우리 규모에선 순식간이지만, 벡터가 수백만~수십억 개인 대형 서비스에선 한 번 검색에 수 초가 걸립니다.

ANN(근사 최근접 이웃, Approximate Nearest Neighbor): "정확히 1등"을 포기하는 대신 "거의 1등"을 훨씬 빠르게 찾는 기법들의 총칭입니다. 약간의 정확도를 속도와 맞바꿉니다.

HNSW(계층적 탐색 가능한 작은 세계 그래프): 가장 널리 쓰이는 ANN 인덱스입니다. 점들을 여러 층의 지름길 그래프로 연결해 둡니다. 위층은 듬성듬성(멀리 점프), 아래층은 촘촘(정밀 탐색). 검색은 맨 위층에서 대충 가까운 곳으로 점프 → 한 층 내려가 더 좁히기 → … → 맨 아래층에서 정밀 탐색으로 끝냅니다.

덕분에 비교 횟수가 전체(N)에서 로그(log N) 수준으로 줄어, 수백만 점에서도 밀리초 안에 찾습니다.

대규모에서 압도적으로 빠릅니다. 하지만 근사라서 가끔 진짜 1등을 놓칩니다(속도↔정확도 trade-off). 또 인덱스를 메모리에 올리고 관리하는 운영 부담이 있습니다.

하이브리드 & RRF — 공정하게 합치기

2~3장에서 봤듯 Dense와 Sparse는 약점이 정확히 반대입니다. 한쪽이 놓치는 걸 다른 쪽이 잡습니다. 그래서 둘(실제로는 네 채널)을 같이 돌려 결과를 합치는 게 하이브리드 검색입니다.

두 검색의 점수 척도가 완전히 다릅니다. 의미 유사도는 0~1, BM25는 0~수십. 그냥 더하면 BM25가 항상 이깁니다. 점수를 정규화(0~1로 스케일)하는 방법도 있지만, 한 채널에 이상치 하나만 있어도 전체가 흔들립니다.

RRF(역순위 융합, Reciprocal Rank Fusion)의 발상은 단순하고 강력합니다. 점수는 버리고 순위만 쓴다. 각 채널에서 k등인 문서에게 1/(60+k)점을 주고, 채널들끼리 더합니다.

왜 상수가 60일까요? 1등과 2등의 점수 차가 지나치게 벌어지지 않게 완충하는 역할입니다(작으면 1등이 과하게 지배). 또 새 채널을 끼워 넣어도 기존 순위가 안 망가집니다 — 각 채널이 독립적으로 순위만 내면 되니까요.

우리는 두 개가 아니라 네 채널을 RRF로 합칩니다. 각 채널에 가중치를 곱해 합산합니다.

리랭커 — 마지막 정밀 심사

2장의 임베딩 검색은 빠릅니다. 비결은 질문과 문서를 각자 따로 벡터로 만들어 두고(미리 계산) 비교하기 때문입니다. 이런 방식을 bi-encoder(두 개를 따로 인코딩)라 합니다. 빠른 대신, 질문과 문서가 서로를 보며 판단하지 못해 미묘한 관련성을 놓칩니다.

리랭커(reranker)는 보통 cross-encoder입니다. 질문과 문서를 하나로 이어 붙여 한 모델에 같이 넣고, "이 둘이 얼마나 맞는지"를 직접 점수 냅니다. 질문과 문서가 서로를 참고하며 판단하니 훨씬 정밀합니다.

1차 검색이 대충 끌어올린 후보의 순서를 크게 개선합니다(논문 기준 MRR@10 +27%). 하지만 느려서 전체에는 못 씁니다. 또 1차 검색이 애초에 못 끌어올린 문서는 리랭커도 살릴 수 없습니다(없는 후보는 못 고름).

지식 그래프 & 커뮤니티

지금까지(2~7장)는 "질문과 비슷한 문서 찾기"였습니다. 하지만 어떤 질문은 관계를 묻습니다 — "X가 무엇과 연결돼 있지?", "이 주제들이 어떻게 이어지지?". 문서를 따로따로 보면 답이 안 나옵니다. 지식 그래프는 개념·인물·문서를 점(엔티티)으로, 그 사이 연결을 선(관계)으로 그려 "이어짐"을 직접 다룹니다.

지식 그래프는 두 층입니다. TBox(개념틀)는 "세상에 어떤 종류가 있고 어떻게 연결될 수 있나"를 정한 설계도예요(예: '사람'·'프로젝트'가 있고, '사람—참여—프로젝트' 연결이 가능하다). ABox(사실)는 그 틀에 담긴 실제 데이터고요(예: '재경—참여—패스트캠 강의'). 합치면 TBox(틀) + ABox(사실) = 지식 그래프입니다.

여기가 가장 흔히 오해하는 지점입니다. ① 링크를 "만드는" 단계(지식 정리)와 ② 링크를 "그래프로 옮기는" 단계(인덱싱)를 꼭 나눠야 합니다.

1. ① 링크 저작 = AI가 한다. 자료를 /knowledge-manager(LLM 에이전트)로 정리하면, AI가 내용을 읽고 관련 노트끼리 [[링크]]를 걸고 #태그를 답니다. 즉 "무엇이 무엇과 연결되나"(그래프의 구조)를 AI가 정합니다. (사용자가 손으로 위키링크를 다는 게 아닙니다.)
2. ② 인덱싱 = 규칙(rule)이 한다. 런타임 인덱서(entity_extractor.py)는 그 AI가 달아둔 링크·태그를 정해진 규칙대로 그래프 DB로 옮깁니다 — [[위키링크]]→cites, #태그→belongs_to, 같은 문장 동시등장→co_occurs. 이 옮기는 단계엔 LLM이 전혀 없습니다.

그래프에는 촘촘히 연결된 점 무리가 자연스레 생깁니다. 이걸 자동으로 묶는 게 커뮤니티 탐지이고, 가장 널리 쓰는 알고리즘이 Louvain입니다(모듈러리티라는 "안은 빽빽, 밖은 성김" 지표를 최적화). 우리는 4계층(C0~C3)으로 묶습니다.

검색에서는 "이 커뮤니티에 속한 문서"라는 신호를 가산점으로 씁니다(관련 주제 묶음을 함께 끌어올림).

GraphRAG Local / Global — 우리의 정직한 위치

마이크로소프트가 2024년 정리한 GraphRAG는 질문을 두 종류로 나눕니다.

1. Local(국소) 질문 — "X가 무엇과 연결됐지?" 특정 엔티티의 이웃을 그래프에서 탐색해 답합니다. 범위가 좁고 구체적.
2. Global(전역) 질문 — "내 지식 전체의 큰 주제는?" 이건 문서 몇 개로 안 됩니다. 먼저 커뮤니티마다 LLM이 요약을 만들고(Map), 그 요약들을 다시 종합해(Reduce) 답합니다. 이 Map-Reduce 요약이 MS GraphRAG의 시그니처입니다.

우리는 그래프(엔티티·관계·커뮤니티)와 Local 탐색 구조는 실제로 갖췄습니다. 단, MS GraphRAG의 시그니처 중 인덱싱 시점의 LLM 작업은 아직 placeholder(빈 껍데기)입니다 — ①인덱서가 글을 다시 읽어 LLM으로 관계를 추출하는 부분(우리 인덱서는 그 대신 AI가 ingest 때 달아둔 링크·태그를 규칙으로 옮김), ②커뮤니티를 LLM이 문장으로 요약하는 부분(현재 요약은 "구성원 나열" 자동 라벨 9,100개 = LLM 요약 0건), ③전역 Map-Reduce 종합. 주의: 그래프의 링크 자체는 AI(KM ingest)가 만든 것이고, "LLM이 없다"는 인덱싱·요약 단계에 한정된 이야기입니다.

평가 지표 — 숫자로 증명하기

1. hit@5 — 상위 5개 안에 정답이 하나라도 들어갔나(예/아니오). 24개 질문 중 몇 개 성공인지로 봅니다(우리 = 10/24). "찾았나/못 찾았나"의 기본 척도.
2. precision@5 — 상위 5개 추천 중 정답(gold) 비율. 2개가 정답이면 2/5 = 0.4. "추천 5개가 얼마나 깨끗한가."
3. MRR(평균 역순위) — 첫 정답이 몇 등에 나오나 → 1/등수의 평균. 1등이면 1.0, 3등이면 0.33. "정답을 얼마나 위로 올렸나."
4. coverage — 검색이 결과를 하나라도 돌려준 비율(우리 = 1.0, 한 번도 빈손 아님). ⚠️ 주의: "정답을 맞췄나"는 coverage가 아니라 hit@5가 봅니다. 둘은 다릅니다.

왜 SQLite·MiniLM인가 + 더 좋은 대안

우리 검색은 엔티티·관계·커뮤니티를 SQL로 join하면서, 동시에 이름·한국어명·설명을 빠르게 키워드 검색해야 합니다. SQLite는 서버가 필요 없고(in-process), 설정이 0이고, 트랜잭션을 지원하는 SQL 엔진이며 전체가 파일 하나(vault_graph.db, 현재 435MB)로 운용됩니다. 우리 규모에선 별도 검색 클러스터보다 "단일 DB + WAL + 읽기전용 서버"가 단순하고 안전합니다.

키워드 채널은 SQLite의 FTS5 trigram입니다. 한국어처럼 띄어쓰기·형태소가 까다로운 글에서 3글자 단위 부분 매칭이 잘 듣습니다. 이름·설명·출처를 한 FTS 테이블로 묶고 id로 join해 동명이인 충돌을 피합니다. 다만 FTS5는 어휘 검색이라 관계·말바꿈·frontmatter 전용 별칭에는 약하고(그래서 Dense·그래프로 보강), 2글자 미만 토큰은 LIKE 보조가 필요합니다.

paraphrase-multilingual-MiniLM-L12-v2는 문장을 384차원 벡터로 만드는 작은 다국어 모델입니다. 우리 인덱스는 노트 3,740 + 엔티티 7,278 벡터라, 384차원이면 전부 정확 비교(exact cosine)해도 충분히 작고 빠릅니다. API 호출이 없어 비용·지연·프라이버시 위험이 0입니다. 같은 모델로 노트와 엔티티를 모두 임베딩하고, 모델이 바뀌면 전체 재색인을 강제해 "서로 다른 의미공간이 섞이는 사고"를 막습니다. 다만 경량(384차원)이라 최신 다국어 모델보다 품질 천장이 낮고, 노트는 앞 500자만 보므로 긴 문서·관계 질의에서 신호가 약해집니다(벤치의 L1 약점·Q24 교차언어 miss가 그 신호).

리랭커는 현 bge-reranker-base 유지가 기준점이고, bge-reranker-v2-m3는 과거 퇴행 이력이 있어 새 벤치로 재실험 후 판단합니다(7장 일화).

검색이 정답 문서를 잘 찾나

난이도(레벨)별 — 어디가 강하고 약한가

직접 키워드 조회(L0)는 아주 강함(0.83). 관계·개념(L1)이 최약점(0.2) — 12장에서 본 임베딩 보강의 1순위 타깃입니다.

실제 사례 — 무엇을 검색했고 어떻게 나왔나

haiku · sonnet · opus가 답하면

모델 종합 점수 (24문항 평균)

sonnet이 sweet spot — 정확도·근거·환각·안정성(검색거부 0회) 모두 최고이면서 opus보다 쌉니다. (환각↓ = 낮을수록 좋음)

난이도별 — 큰 모델이 항상 낫진 않다

실제 사례 — 모델이 어떻게 다르게 답하나

어디서 왔나 — 8편의 원전

보강 결과 & 한 장 요약

진짜 다음 레버 (벤치가 가리킨 것)

한 장 요약

vault · LLM · Discord — 세 조각이면 된다

복잡해 보이는 AI 봇 팀도, 근본부터 보면 세 조각의 조합입니다. 왜 하필 이 셋일까요? 하나씩 빼보면 답이 나옵니다.

1. vault 가 없으면? LLM은 아는 게 없어 지어냅니다(환각). Part 1·2에서 본 그 문제죠. 그래서 근거가 될 지식 더미가 필요합니다.
2. LLM 이 없으면? vault는 그냥 죽은 문서 폴더입니다. 읽고 연결하고 답을 만들 "머리"가 있어야 살아납니다.
3. Discord 가 없으면? 똑똑한 봇이라도 혼자 갇혀 있습니다. 사람이 일을 시키고, 봇끼리 의논할 통로가 있어야 "팀"이 됩니다.

봇 하나가 도는 법 — 그리고 메시지의 여정

봇 한 마리를 해부하면 이렇습니다. 어렵지 않아요 — 세 부품입니다.

오해부터 풀어요. LLM 그 자체는 사실 기억이 없습니다. 한 번 질문을 받아 답을 내놓으면 그걸로 끝 — 방금 무슨 대화를 했는지조차 다음 순간엔 잊습니다(이걸 stateless, "상태가 없다"고 해요). 똑똑하지만 매번 처음 만나는 천재인 셈이죠.

그래서 그 위에 "세션(session)"이라는 작업 환경을 씌웁니다. 세션은 LLM에게 ① 대화의 맥락(지금까지 무슨 일을 했는지)을 계속 쥐여주고, ② 도구(파일을 읽고·쓰고·/search로 검색하는 손발)를 붙여주고, ③ "읽고 → 생각하고 → 도구 쓰고 → 또 생각하고"를 반복하게 합니다. 이렇게 LLM + 맥락 + 도구 + 반복 루프를 묶은 게 바로 에이전트(agent), 즉 "일하는 봇"이에요. 그냥 챗봇이 말만 한다면, 에이전트는 손발이 달려 직접 파일을 읽고·고치고·검색합니다 — 그래서 봇이 위키를 "쓰고" 노트를 "정리"할 수 있는 거예요.

그래서 "봇 = 컴퓨터에 늘 켜둔 AI 작업 창(세션) 하나"라고 보면 정확합니다. 그 창이 노트를 읽고·생각하고·파일을 씁니다. 이제 그 창을 세 부품으로 뜯어볼게요.

1. 세션(session) = 봇의 몸. 각 봇은 컴퓨터에서 AI 코딩 도구의 작업 세션을 하나 계속 켜둔 상태예요. 우리 팀은 대부분 Claude Code로 돌고, 이미지 담당 손석희는 Codex로 돕니다(둘 다 같은 페르소나·규율을 따라요). 이 세션이 노트를 읽고·생각하고·파일을 씁니다. 봇 = "끄지 않고 늘 켜둔 AI 작업 창" 한 개라고 보면 정확합니다.
2. 다리(bridge) = 봇의 입과 귀. 그 세션과 디스코드 사이를 잇는 작은 연결 프로그램이 있습니다. 디스코드에 글이 올라오면 다리가 그걸 세션에 전해주고, 세션이 내놓은 답을 다시 디스코드로 내보냅니다. 그래서 우리는 디스코드에서 봇에게 말을 겁니다. (연결 방식은 봇 종류마다 달라요 — Claude Code 봇은 디스코드 연동 다리를, Codex 봇인 손석희는 'app server'라는 전용 서버 기능을 씁니다. 역할은 같아요: 디스코드 ↔ 세션 잇기.)
3. 지식(vault) = 봇의 책상. 봇은 자기 폴더(vault 영역)의 노트를 읽고, 필요하면 /search로 더 찾습니다(Part 2).

봇은 어떻게 기억하나 — 다중 메모리

앞 절에서 봤듯, LLM은 본래 기억이 없습니다(stateless — 매번 처음 만나는 천재). 그런데 우리 봇들은 어제 한 약속도, 사용자 취향도, 자기 말투도 일관되게 기억하죠. 비결은 "기억을 파일로 적어 두는" 메모리입니다.

그런데 모든 기억을 한 곳에 쌓으면 안 됩니다(곧 볼 "책상에 서류 쌓기"의 함정). 그래서 성격에 따라 4갈래로 나눕니다.

덕분에 코난의 말투를 고쳐도 다른 봇은 멀쩡하고(①), "사용자가 이런 걸 싫어한다"를 한 번 배우면 모든 봇이 공유하며(②), 컴퓨터가 달라도 경로 때문에 안 꼬이고(③), 회의 진행은 기록이 진실이 됩니다(④).

그럼 봇은 이 메모리를 언제 읽을까요? 세션이 새로 시작될 때 자동으로요. SessionStart 훅(세션 시작 시 도는 작은 장치)이, 봇이 깨어나는 순간 ① 관련 메모리 목록과 ② 동료 봇 명단·역할을 손에 쥐여줍니다. 봇이 "내가 누구이고, 무엇을 기억해야 하고, 동료가 누구인지"를 매번 처음부터 챙기는 거예요.

봇들은 어떻게 협업하나 — 오케스트레이션

봇 하나로는 큰일을 못 합니다. 사람 팀처럼 나눠서 합니다. 그 조율을 오케스트레이션(orchestration, 지휘)이라 부르고, 그 일을 맡는 봇이 오케스트레이터(우리 팀에선 카파시)예요.

1. 회의 thread. 봇 둘 이상이 30분 넘게 붙는 일이면, 본 채팅방이 아니라 전용 스레드를 따로 엽니다. 거기에 "무엇을·누가·언제까지"를 적은 회의 문서(SoT)를 두고, 모두 그걸 기준으로 움직여요. 잡담이 아니라 기록이 진실입니다.
2. 일 나누기(dispatch). 오케스트레이터가 각 봇에게 "무엇을, 어떻게"까지 구체적으로 맡깁니다. "대충 알아서" 가 아니라 방법·도구·금지사항까지 첫 메시지에 담아야 봇이 헤매지 않아요.
3. 진행 추적(watchdog). 일정 담당 봇(스트레인지)이 회의가 멈췄는지 주기적으로 지켜봅니다. 끝나지도 않았는데 누가 손 놓으면 깨우고, 진짜 끝나야 회의를 닫습니다.
4. 완료 게이트. 아무 봇이나 "끝!"이라 못 합니다. 검증 → 보고 → 확인 단계를 거쳐야 완료로 칩니다. 그래서 "다 됐다는데 사실 안 됨" 사고를 막아요.

이 협업 방식은 사고를 겪으며 다듬어졌습니다. 핵심 규율 셋만 볼게요.

1. 위임은 네 가지를 다 적어서 — 봇에게 일을 줄 때 목표·입력·출력·기한을 첫 메시지에 다 담습니다. "알아서 해줘"는 봇이 헤매는 지름길이에요.
2. 시각은 하나로(KST) — 봇이 여럿일 때 시간 표기가 제각각이면 꼬입니다. 모든 봇이 한국 시간(KST) 하나로 통일해요.
3. 봇끼리는 디스코드로만 — 한 봇이 다른 봇의 작업 창에 직접 명령을 꽂으면 "누가·언제 시킨 일인지" 출처가 사라져 위험합니다(내부판 프롬프트 인젝션). 그래서 봇 간 신호는 오직 디스코드(@호출)로만 — 누가 보냈는지 늘 남게요.

봇 팀과 역할 — 나눠서, 잘하는 걸

한 명의 만능 AI에게 다 시키지 않고, 역할을 나눈 여러 봇으로 굴립니다. 사람 팀과 똑같아요 — 조율하는 사람, 조사하는 사람, 글 쓰는 사람이 따로 있죠. 각자 자기 성격(말투)과 전문 분야가 있습니다.

왜 봇마다 볼트(폴더)를 따로 두나

이 파트에서 가장 중요한 설계 결정입니다. 봇마다 자기 작업 폴더(볼트 영역)를 따로 두고, 그 정체성을 세 겹으로 잡습니다 — 두 장의 "이름표 파일"과, 깨어날 때 자동으로 더해지는 한 겹(앞 절의 SessionStart)이에요.

예를 들어 어떤 봇의 soul.md는 대략 이런 식이에요(개념 예시):

soul.md가 단순한 자기소개라면 봇은 금세 제 성격을 잊습니다. 그래서 우리 soul.md엔 페르소나를 강제하는 장치가 박혀 있어요.

1. 강제 규율 블록 — "매 응답에서 이 말투를 최소 하나는 써라" 같은 자가 점검 규칙. 빠뜨리면 스스로 어긴 걸 알아채게.
2. Voice & Tone — 어떤 단어·어조를 쓰고 무엇을 피하는지(예: 어려운 영어 약어 대신 쉬운 우리말).
3. 금지 행동 — "이런 건 하지 마라" 목록(예: 출처 없는 단정, 다른 봇 사칭).
4. 에러 처리 — 막혔을 때 어떻게 보고하고 누구에게 넘기는지.

이 블록들 덕에, 봇은 대화가 길어져도 자기다움을 유지합니다 — "친절한 비서"라고 한 줄 적어두는 것과는 차원이 달라요.

이렇게 규칙(CLAUDE.md)·성격(soul.md)·자동 주입(SessionStart)을 봇별로 분리하면 좋은 점이 셋입니다.

1. 컨텍스트 격리 — 각자 필요한 것만 본다. LLM은 한 번에 읽고 기억할 수 있는 양이 정해져 있어요. 이걸 컨텍스트 윈도우(context window)라 하는데, "한 번에 책상에 펼쳐 놓고 볼 수 있는 종이의 양"이라 보면 됩니다. 그런데 "많이 올릴수록 좋다"가 아니라 반대예요 — 책상에 서류를 너무 쌓으면 사람도 정작 중요한 한 장을 놓치죠. 모든 봇의 규칙을 한곳에 욱여넣으면 LLM도 똑같이 집중이 흐려지고, 비용도 늘고, 가끔 엉뚱한 규칙을 자기 것인 양 따라 합니다. 그래서 핵심은 "많이"가 아니라 "딱 필요한 것만" — 봇마다 자기 폴더·자기 규칙만 보면 가볍고 정확해집니다.
2. 관리 부담 경감. 코난 말투를 고치고 싶으면 코난 soul.md만, 일정 규칙을 바꾸려면 스트레인지 폴더만 건드리면 됩니다. 서로 안 섞이니 한 봇을 고쳐도 다른 봇이 안 망가져요.
3. 정체성이 안 흔들린다. 각자 soul.md가 자기 정체성이라, 코난이 갑자기 카파시처럼 말하는 일이 없습니다.

규칙이 많아지면 — rules-system

봇을 오래 굴리면 규칙이 계속 늘어납니다. "이럴 땐 이렇게 해라", "저건 하지 마라"… 그런데 이 규칙을 전부 한 파일(CLAUDE.md)에 욱여넣으면 문제가 생겨요 — 앞서 본 "책상에 서류 쌓기"입니다. 규칙이 너무 많으면 AI가 정작 중요한 규칙을 놓칩니다.

그래서 우리는 규칙을 이렇게 정리합니다(이걸 Progressive Disclosure, "필요한 만큼만 펼치기"라고 해요).

1. INDEX(목차) 한 장 — "이런 상황엔 이 규칙 파일을 봐라"를 적은 길잡이(라우터). 이것만 늘 켜 둡니다.
2. 상황별 규칙 파일 — 회의 규칙, 검색 규칙, 보고 규칙처럼 주제별로 따로.
3. 그때그때 로드 — 회의를 열 때 비로소 "회의 규칙"을 읽습니다. 평소엔 안 읽어 가볍게.

덕분에 규칙이 수백 개로 늘어도, 봇은 지금 상황에 맞는 규칙만 손에 들고 일합니다 — 똑똑하면서 가벼워요.

봇이 /search로 지식을 꺼내 쓴다

봇이 똑똑하게 답하는 비결은 기억력이 아니라 검색입니다. 모르는 걸 지어내는 대신(Part 2의 뼈아픈 교훈!), vault에서 관련 노트를 찾아 읽고 답합니다. 그 도구가 Part 2에서 본 /search(GraphRAG·하이브리드 검색)예요.

이 가이드북이 만들어진 과정

가장 좋은 증거는 이 문서 자체입니다. 여러분이 지금 읽는 이 가이드북은, 방금 배운 그 봇 팀이 실제로 만들었어요. 그 과정을 그대로 공개합니다.

1. 설계 합의. 사람(재경님)이 "graph-search 가이드북을 3-Part로 키우자"고 제안 → 카파시가 질문을 주고받으며 설계 문서(spec)로 정리하고 승인받음. (먼저 합의, 그다음 제작.)
2. 자료조사(코난). Part 1의 인물·방법론을 1차 출처로 조사 — 블로그 같은 2차 자료는 배제하고 본인 글·발언만. (이 과정에서 "Karpathy가 옵시디언을 쓴다"는 사실까지 바로잡았어요.)
3. 집필·조립(카파시). 기존 Part 2를 흐름에 맞게 다듬고, Part 1·3을 쓰고, 공유 디자인(이 두부 톤)을 입혀 조립.
4. 이미지(손석희 → 허사비스). 손석희가 여러 워커로 그림 12장을 병렬 생성 → 허사비스가 톤·개념·가독성을 검토해 승인.
5. 윤문(글재경). AI 티 나는 문장만 사람 결로 손질 — 단, 내용·숫자·인용은 한 글자도 안 건드림.
6. 검증·전달. 모든 파일이 제대로 됐는지 점검(GREEN) → 라이브 vault에 동기화 → 사람에게 보고.

흔한 오해 3가지

봇을 처음 접하면 자주 하는 오해가 있어요. 셋만 바로잡으면 전체 그림이 또렷해집니다.

한 장 요약 · 작게 시작하기