LLM Wiki 실전 구현

• LLM Wiki 실전 구현은 LLM Wiki 개념을, 이미 쓰던 Obsidian vault 위에 LLM 관리 계층을 얹어 실제로 굴리는 방법
• 손으로 쓴 노트는 불변 원본으로 보호하고, 관계·색인·종합은 LLM이 별도 파생 계층으로 만드는 하이브리드 (이 문서가 택한 Model A)
• 위키 자체는 정적 마크다운 — 질의·유지보수는 폴더를 읽는 LLM 도구를 연결해 수행 (개발이 아니라 도구 선택)
• 벡터 DB 없이 키워드·태그·grep로 도는 경량 파일 기반 구조

이미 Obsidian으로 정리 중인데, LLM Wiki가 왜 필요한가

LLM Wiki는 Obsidian을 대체하지 않는다. 같은 마크다운 vault 위에 “LLM 관리자”를 얹는 것이고, 파일도 뷰어도 그대로다. 바뀌는 건 하나 — 정리 노동을 누가 하느냐다.

관점	수동 Obsidian (지금)	LLM 계층 추가
정리 노동 (읽기·요약·링크·모순 발견·최신화)	전부 내가 함	LLM이 대신 함, 나는 “무엇을 넣을지” 큐레이션만
학습이 목적 (쓰며 이해·기억)	우위 — 직접 쓰는 행위가 이해를 만듦	약함 — 쓰기를 위임하면 덜 남음
참조·질의가 목적 (쌓아서 나중에 활용)	양이 늘면 손으로 유지 버거움	우위 — 질문에 답·감사·색인

그래서 판단은 “도구를 또 쓰나?”가 아니라 **“이 정리 노동을 계속 감당할지, 위임할지”**다. 결론은 둘 중 택일이 아니라 하이브리드 — 학습 정리는 손으로 계속하고, 양이 늘어 질문·링크·감사가 번거로워지는 지점에서 LLM 계층의 이득이 커진다.

하이브리드 배치 — 내 원본은 불변, LLM은 파생 계층만 (Model A)

먼저 오해 하나: “불변”은 LLM 기준이다. LLM이 내 노트를 안 건드린다는 뜻이지, 주인인 내가 직접 고치는 건 당연히 정상이다.

배치는 “raw냐 vs 이미 종합된 것이냐”로 나뉜다. 손으로 쓴 학습 노트는 이미 종합된 지식이므로, 이걸 그대로 불변 원본으로 두고 LLM에는 읽기만 허용한다. 관계·색인·종합은 LLM이 별도 겹으로 만든다.

my-wiki/
├── sources/            # 내 학습 노트 + 원자료 (LLM 읽기만, 절대 수정 안 함)
└── wiki/               # LLM이 생성하는 파생 계층 (언제든 재생성 가능)
    ├── entities/       # 개체·개념 관계 페이지 (MOC)
    ├── index.md        # 전체 노트 한 줄 요약 카탈로그
    ├── audit.md        # 모순·공백·stale 리포트
    └── log.md          # 작업 기록

flowchart LR
    U["나<br/>(저자·큐레이터)"]
    subgraph SRC["sources/ — 불변 (LLM 읽기만)"]
        N["내 학습 노트"]
        RAW["원자료"]
    end
    subgraph W["wiki/ — LLM 파생 (재생성 가능)"]
        MOC["관계·색인"]
        AUD["모순·공백 감사"]
    end
    U -->|"작성·수정"| N
    SRC ==>|"ingest (LLM이 읽어 생성)"| W
    MOC -.->|"위키링크 → 백링크로 그래프 연결"| N
    U -->|"질의"| W
    W -->|"인용 종합 답변"| U

내 노트는 100% 보호되고, 관계·색인·종합은 LLM이 별도 겹으로 만든다. (대안으로 LLM이 내 노트 안에 직접 링크를 박는 Model B도 있지만, 노트를 수정하므로 이 문서는 원본 보호를 위해 Model A를 택한다.)

”중복”이 아니라 “생성된 색인”

wiki/는 두 번째 원본이 아니라 내 노트로부터 언제든 다시 생성할 수 있는 index/answer 계층이다. 진실은 내 노트 하나뿐이고, wiki/는 버리고 재생성해도 되는 캐시 같은 겹이다. 그래서 이중 관리 부담은 작다.

Obsidian 단독 대비 실제 이점

Model A에서 LLM이 내 노트를 못 고쳐도, 파생 계층과 질의만으로 다음을 얻는다.

• 질의 → 답변 (find가 아니라 answer) — Obsidian 검색은 단어가 든 파일 목록을 주지만, LLM은 여러 노트를 걸쳐 인용까지 붙여 답을 종합한다. (“그 파일 어디” 같은 단순 찾기는 Obsidian이 이미 빠르니 이점이 없다 — 이득은 “질문에 답하기”에 있다)
• 노트를 안 건드리고 그래프가 연결됨 — LLM이 wiki/에 만든 MOC가 내 노트로 위키링크를 걸면, Obsidian 백링크 덕에 내 불변 노트에도 연결이 뜨고 graph view에 나타난다. 파일은 한 글자도 안 바뀌는데 관계망이 생긴다
• 모순·공백·stale 감사 — “A와 C 노트가 상충”, “RAG·임베딩을 참조하는데 임베딩 노트 없음”, “이 노트는 오래돼 옛 정보 참조” 같은 리포트를 만든다. 고칠지는 내가 판단
• 자동 색인·조감도 — 전체 노트를 한 줄 요약으로 카탈로그, “내가 X에 대해 배운 것” 종합 — 태그·검색 위의 조감도
• 다음 학습거리 제안 — 공백 분석으로 이어서 배울 것을 제안

LLM이 내 노트를 수정하지 못하는 것은 손해가 아니라 의도한 보장이다 — 원본 보호가 Model A의 핵심이다. 그 결과 LLM이 만든 [[링크]]는 내 노트 파일 안이 아니라 wiki/ 파생 계층에 생긴다. 하지만 Obsidian 백링크가 이어주므로 내 노트도 graph에서 연결되어 보이고, 탐색에서 잃는 것은 없다.

(단 하나 예외 — 상충·중복 정리는 LLM이 고친 원본을 제안할 수 있다. 자동 적용이 아니라 git으로 내 승인을 거치므로 원본 보호 원칙은 유지된다. 아래 [목적별 LLM 개입 수위와 승인 흐름] 참조.)

목적별 LLM 개입 수위와 승인 흐름

이 지식베이스로 얻으려는 것은 네 가지이고, 각각 LLM이 어디까지 하고 내가 어떻게 승인하는지가 다르다. 원본은 내 것이므로, LLM이 원본을 고칠 때는 자동 적용이 아니라 항상 내 승인(git commit)을 거친다.

목적	LLM이 하는 것	나의 역할	원본 수정?
1. 상충 확인	고친 원본(diff)을 제안	확인 → 수용 or 직접 수정	O (내 승인 시)
3. 중복 확인	정리본(병합/링크, diff)을 제안	확인 → 수용 or 직접 수정	O (내 승인 시)
2. 부족 확인	”이 개념이 빠졌다”고 지적만	내가 공부해서 직접 작성	X (내가 새로)
4. 자연어 검색	질의에 인용과 함께 답변	—	X

Model A의 정제 — “안 씀”이 아니라 “내 승인 없이는 확정 안 됨”

앞의 Model A는 “LLM은 원본을 절대 안 쓴다”였다. 1·3에서 **“LLM이 고친 원본을 제안해주면 좋다”**는 요구가 생기면서, 불변식이 한 단계 정제된다.

• 이전: LLM은 원본을 건드리지 않는다
• 지금: LLM은 원본 수정을 제안하되, 내 commit 없이는 확정되지 않는다

이 “승인 게이트”의 정답이 git이다. 원본(sources/)을 git 저장소로 두면, 작업트리가 제안 샌드박스가 되고 commit이 승인 게이트가 된다.

git 승인 흐름 (1·3에 적용)

flowchart TD
    A["감사: 상충/중복 발견"] --> B["LLM이 고친 원본을<br/>git 작업트리에 씀 (미커밋)"]
    B --> C{"git diff 로 검토"}
    C -->|"맞다"| D["git commit → 수용"]
    C -->|"내가 더 고침"| E["직접 편집 후 commit"]
    C -->|"아니다"| F["git checkout → 폐기 (원상복구)"]

내 commit 없이는 아무것도 확정되지 않으므로 “원본은 내 것”이 지켜지고, 수용·직접수정·거부 세 경로가 git으로 자연스럽게 처리된다. 2(부족)는 지적만 하고 내가 직접 쓰며, 4(검색)는 읽기 전용이다.

현재 CLI: propose-edit 구현됨

llm-wiki CLI는 감사의 prose 제안에 더해, 상충·중복 findings에 대해 고친 원본 후보를 git worktree에 기록하는 propose 명령으로 1·3을 구현했다. 원본은 HEAD에서 뜬 격리 worktree에 쓰이므로 메인 작업트리는 안 건드리고, 나는 git diff로 검토 후 merge하거나 propose --cleanup으로 폐기한다. 2·4는 감사·질의로 충족된다.

위키는 정적 md — 쓰려면 LLM을 폴더에 “연결”

핵심은 위키가 **수동적 저장소(md 파일)**일 뿐이고 행위 주체는 LLM이라는 점이다. 위키만으론 아무것도 못 하고, 질의하려면 LLM이 그 폴더를 읽어야 한다. 그런데 이 “연결”은 개발이 아니다 — 파일 접근이 되는 LLM 도구를 폴더에 향하게 하고 물으면 끝이다. 위키를 유지하는 LLM과 질의하는 LLM은 같은 주체다.

도구	질의 방법	내가 할 일
Claude Code	vault 폴더에서 열고 질문 → 파일 읽고 답변	그 폴더에서 실행 (개발 0)
OMC wiki 스킬	wiki_query → 매칭 페이지 + LLM 종합	내장
Obsidian 플러그인 (Auto LLM Wiki / Copilot / Smart Connections)	vault 안 채팅창에 질문	플러그인 설치만
데스크톱 앱 (nashsu 등)	앱 내장 채팅	앱 설치만

어디에도 “질의 기능을 코딩”하는 단계가 없다. 내 “몫”은 세 가지뿐이고 전부 코딩이 아니다 — ① 도구 선택 ② 폴더 접근 허용 ③ 실행 비용(클라우드면 토큰, 로컬 모델이면 없음).

빠른 질의 인터페이스 — 코딩 중 즉석 질문 (Alfred + 로컬 LLM + Quicklook)

개발(예: Codex) 중에 “어제 정리한 게 뭐였지?”가 떠오를 때, Obsidian을 열지 않고 그 자리에서 묻고 답을 받는 흐름이다. 두 제약이 설계를 정한다.

• 코딩 터미널에 그냥 물으면 안 된다 — 진행 중 작업과 컨텍스트가 섞인다. 그래서 코딩 세션과 완전히 분리된 별도 프로세스로 물어야 한다
• 던져두고 병렬로 계속 일하고 싶다 — 답이 준비되면 그때 확인

엔진과 트리거를 분리한다

• 엔진 = 노트 폴더를 읽어 답하는 헤드리스 로컬 LLM 호출 (한 번 만들면 재사용)
• 트리거 = 엔진을 부르는 방법 — 여기선 Alfred Powerpack 워크플로우(전역 핫키)

이렇게 나누면 코딩 세션과 격리되고, 트리거는 나중에 뭐든 바꿀 수 있다.

엔진: 로컬 LLM (Ollama)

ollama run <model>로 로컬 실행 → 클라우드 인증 불필요, 사설·오프라인. 이 작업은 “내 노트를 근거로 요약·종합”이라 제공된 텍스트에 grounded되므로 중형 로컬 모델(8~14B)로도 충분하다. 핵심 제약은 컨텍스트 한계 — vault 전체를 넣으면 안 되고, 관련 페이지만 추려 넣는다. Ollama 데몬은 상시 실행해 둔다. (이 엔진은 이후 자체 CLI llm-wiki query로 구현했다 — 아래 “실제 구현” 참조)

흐름 (기대한 3단계)

1. Alfred 핫키 + 질문 → 워크플로우가 백그라운드 스크립트를 발사하고 Alfred 창은 즉시 닫힘
2. 나는 곧바로 다른 터미널에서 병렬 작업 (질의는 독립 프로세스라 코딩과 안 섞임)
3. 완료 시 스크립트가 답을 저장하고 Quicklook을 띄워 화면에 자동 팝업 → 읽고 닫음

sequenceDiagram
    autonumber
    actor Me as 나
    participant AL as Alfred
    participant Q as 질의 스크립트<br/>(백그라운드)
    participant LLM as 로컬 LLM<br/>(Ollama)
    participant N as 노트 폴더
    participant QL as Quicklook
    Me->>AL: 핫키 + 질문
    AL->>Q: 백그라운드 발사 (Alfred 창 닫힘)
    Note over Me: 곧바로 다른 터미널에서 병렬 작업
    Q->>N: index.md 먼저 → 관련 페이지 선별
    Q->>LLM: 선별 노트 + 질문
    LLM-->>Q: 종합 답변 (markdown)
    Q->>QL: /tmp/wiki-answer.md 저장 후 qlmanage -p
    QL-->>Me: 자동 팝업 (Space/Esc로 닫기)

표시: Quicklook (확정)

• 완료된 스크립트가 qlmanage -p /tmp/wiki-answer.md를 호출 → Quicklook 패널이 자동으로 앞으로 떠오른다(별도 클릭·알림 불필요)
• 단일 파일 재사용 — 매 질의가 같은 /tmp/wiki-answer.md를 덮어쓰므로 파일은 항상 1개, 누적 없음
• 닫기는 Space/Esc — Quicklook은 Cmd+W가 안 먹는다. 이 점을 감안하고 Quicklook을 택함
• 마크다운을 렌더링하려면 QLMarkdown 플러그인(brew install --cask qlmarkdown) 설치, 없으면 평문으로 표시
• 트레이드오프: 자동 팝업이라 완료 순간 포커스를 가져올 수 있음(타이핑 중 끊길 수 있음) — 알림 대기 대신 즉시 노출을 택한 결과

주의 (Alfred 스크립트 환경)

Alfred Run Script는 최소 환경에서 돌므로 ollama·qlmanage는 절대경로로 부르고, 답변 파일 경로는 /tmp/wiki-answer.md로 고정해 재사용한다.

수집(ingest): 수동이 기본, 자동화는 옵션

Karpathy의 기본은 “수동 + 사람 검토”(한 번에 하나, 요약 읽고 강조점 지시)다. 그 위에서 마찰만 자동화한다.

방식	트리거	성격
폴더 auto-watch	sources/에 파일 추가/수정 감지(수 초 폴링) → 자동 ingest	반자동 (넣는 건 사람)
Web Clipper 원클릭	방문 페이지를 단축키로 클립 → markdown 저장 → 자동 ingest	반자동 (페이지당 1클릭)
Save to Wiki	좋은 챗 답변 저장 → 엔티티/개념 자동 추출	반자동
스케줄 에이전트	야간 유지보수·주간 재조정·자동 lint	자동 (수집이 아닌 정리)

“접속한 사이트 자동 ingest”는 지양한다. 브라우징 히스토리 무인 수집은 (1) 대부분 지식 가치 없는 페이지로 위키를 오염시키고(노이즈), (2) history-sniffing 영역의 프라이버시 이슈를 낳으며, (3) “사람이 큐레이션” 전제와 충돌한다. 실무 정답은 “자동 감지 + 의도적 선별” — 넣는 마찰은 자동화하되 무엇을 넣을지는 사람이 1클릭으로 결정한다.

원본을 고치면 어떻게 되나 — 재-ingest와 관계 갱신

내가 sources/의 노트를 고치면, wiki/ 파생 계층은 그 노트에 대해 stale(낡음) 상태가 된다. 그래서 재-ingest가 필요하다: LLM이 바뀐 노트를 다시 읽어 파생 페이지(관계·요약·감사)를 갱신한다. 개념을 추가했으면 MOC에 링크가 붙고, 이전 감사에서 잡힌 모순이 해소됐으면 플래그가 사라진다. 내 노트 쪽은 그대로, 파생 계층만 바뀐다.

재-ingest는 바뀐 노트 + 그걸 참조하는 파생 페이지만 증분 갱신하며(log.md에 기록), 트리거는 폴더 auto-watch(자동)나 수동 요청이다. 파일명을 바꾸면(rename) 파생 링크가 깨질 수 있어 lint가 감지·수정한다. 노트 A의 변경이 “A와 C의 관계”에 주는 2차 파급까지 맞추려면 주기적 lint/재조정을 걸어둔다.

여기서 실효성의 핵심이 나온다 — 파생 계층을 append-only(새 페이지만 계속 추가)로 두면 낡은 관계가 쌓여 무너진다. 재-ingest로 기존 페이지를 갱신(write-back)하고, 스케줄 재조정으로 최신성을 유지해야 한다.

AS-IS — 순진한 append-only: 쌓일수록 무너짐

flowchart TB
    S1["소스 1"] --> P["새 페이지만 계속 추가 (append-only)"]
    S2["소스 2"] --> P
    S3["소스 N"] --> P
    P --> C["모순·낡은 정보가 함께 축적 (둘 다 살아있음)"]
    C --> X["수백 소스 후 붕괴 ✗"]

TO-BE — write-back + 스케줄 유지보수

flowchart TB
    S["새 소스"] --> ING["Ingest: 기존 페이지를 갱신 (write-back)"]
    ING --> W[("위키")]
    W --> RECON["스케줄 재조정: 최신성·권위·신뢰도로 모순 해소"]
    RECON -->|"낡은 주장은 날짜 이력으로 보관"| W
    LINT["스케줄 Lint: 고아·stale·깨진 링크"] --> W

auto-watch는 직접 개발하나 — 아니오

재-ingest 자동화(auto-watch)는 대개 직접 개발할 필요가 없다. 세 수준으로 갈린다.

• 내장 (코드 0) — Obsidian Auto LLM Wiki 플러그인, nashsu 데스크톱 앱 등은 폴더 변경 감지·재-ingest가 내장. 설치·설정만
• 기존 유틸 글루 (한 줄) — 순수 Claude Code면 fswatch sources/ | xargs … 한 줄, 또는 launchd/cron으로 야간 재-ingest 스케줄. 소프트웨어를 만드는 게 아니라 도구 연결
• 수동 (설정 0) — 노트 고친 뒤 “바뀐 노트 재-ingest 해줘” 한마디

개인 학습 vault는 편집이 잦지 않아 실시간 감시 자체가 과하다. 실시간 watch는 소스가 계속 쏟아지는 대량 파이프라인용이다. 권고: Obsidian 유저라면 Auto LLM Wiki 플러그인(설치만), 아니면 수동 재-ingest나 야간 스케줄로 충분하다.

스키마 문서 (실효성의 90%)

LLM을 “일반 챗봇”이 아니라 “규율 있는 위키 관리자”로 만드는 설정 문서(SCHEMA.md 또는 CLAUDE.md). 최소한 아래를 명시한다.

• 불변 규칙 — sources/는 LLM 읽기 전용, 생성·수정은 wiki/에만
• 페이지 포맷 — YAML frontmatter: title / tags / category / updated / sources
• 명명·링크 규칙 — 파일명 표기, [[wiki-link]] 규칙
• 모순 처리 — 상충 시 최신성·권위·신뢰도 우선순위, 진 주장은 날짜 이력으로 보관
• 명령 정의 — ingest / query / lint 절차

검색은 무-벡터로 시작

개인/프로젝트 규모에선 키워드 + 태그 + grep로 충분하다(Karpathy 권장). 벡터 임베딩은 위키가 수천 페이지로 커진 뒤 옵션으로 얹으면 된다. 처음부터 벡터 DB를 세우는 것은 과설계다.

실제 구현에서는 여기서 한 단계 나아가 SQLite FTS5(bm25) 키워드 검색 + 임베딩(bge-m3) 하이브리드를 택했다 — 단 별도 벡터 DB 없이, Node 내장 node:sqlite 파일 하나를 재생성 가능한 캐시로 쓰는 선이라 “벡터 DB 과설계” 경계는 넘지 않는다.

시작 절차 (Model A 기준, 단계별)

1. 이미 있는 Obsidian vault를 sources/로 삼거나 sources/·wiki/ 폴더와 SCHEMA.md 생성
2. SCHEMA.md에 “sources/는 불변, wiki/에만 파생 생성” 규칙과 페이지 포맷·명명·모순 처리·명령 정의
3. LLM 도구를 그 폴더에 연결 (Claude Code 실행 / Obsidian 플러그인 설치)
4. 노트 몇 개로 ingest → wiki/에 생긴 관계·색인·감사를 사람이 검토, 스키마를 다듬음
5. 질의로 사용 — “내 노트 기준 X 요약” 등 인용 답변 확인
6. 편집이 잦아지면 auto-watch(플러그인)나 야간 재-ingest·lint 스케줄로 최신화 자동화 (변경은 diff/버전 히스토리로 되돌림 가능하게)

실제 구현 — local-llm-wiki CLI

이 문서의 설계를 실제 코드로 옮긴 결과물이 heepie-repo/llm-wiki(TypeScript CLI, 런타임 의존성 0)다. Model A 원칙 그대로 — source_root(내 노트)는 읽기 전용을 다층으로 강제(symlink 탈출 차단·경로 격리 검증)하고, 인덱스·리포트·프로필은 전부 vault 밖(~/Library/Application Support/local-llm-wiki/, review_output/)에 둔다. 파생 계층은 md 위키 페이지 대신 검색 인덱스 + 날짜별 감사 리포트로 구현했다: 질의는 매번 재합성하되, ‘복리 축적’은 리포트의 TODO를 보고 사람이 원본을 고치는 human write-back 루프로 일어난다.

레이어 구조

flowchart TB
    subgraph L1["CLI 계층 (cli.ts)"]
        CMD["ingest · audit · batch · search · query · status · launchd"]
    end
    subgraph L2["엔진 계층"]
        IDX["WikiIndexer<br/>오케스트레이션 + batch lock"]
        QE["QueryEngine<br/>하이브리드 검색 + 인용 검증"]
        AE["AuditEngine<br/>중복·부족·상충 감사"]
        RPT["Report Writer<br/>날짜별 검토 리포트"]
    end
    subgraph L3["Provider 인터페이스 (providers.ts) — 교체 지점"]
        CP["ChatProvider"]
        EP["EmbeddingProvider"]
        SP["SemanticConflictProvider"]
    end
    subgraph L4["구현체"]
        OL["Ollama (ollama.ts)<br/>qwen3:14b · bge-m3"]
        LM["LM Studio 등 OpenAI 호환<br/>(인터페이스만 구현하면 교체)"]
    end
    subgraph L5["저장 계층 — 전부 source_root 밖"]
        PF["ProfileStore (JSON 프로필)"]
        IS[("state.sqlite<br/>FTS5 bm25 · 임베딩 캐시 · 감사 lifecycle")]
        OUT["review_output/*.md 리포트"]
    end
    SRC[("source_root — 내 노트<br/>읽기 전용, 불변 강제")]
    QLV["QuickLook 팝업"]

    CMD --> IDX
    IDX --> QE
    IDX --> AE
    IDX --> RPT
    IDX --> PF
    SRC -->|"읽기만"| IDX
    QE --> CP
    QE --> EP
    AE --> SP
    CP --> OL
    EP --> OL
    SP --> OL
    CP -.-> LM
    EP -.-> LM
    IDX --> IS
    QE --> IS
    AE --> IS
    RPT --> OUT
    QE --> QLV

저장 계층의 state.sqlite는 파생 캐시다(ingest --full로 언제든 재생성) — 유일한 예외는 감사 이슈의 new/persistent/resolved 이력(lifecycle)으로, 이것만은 지우면 해결 추적이 리셋된다.

질의 시퀀스 (Alfred → 답변)

sequenceDiagram
    autonumber
    actor Me as 나 (Alfred)
    participant CLI as llm-wiki query
    participant QE as QueryEngine
    participant DB as state.sqlite
    participant EP as EmbeddingProvider<br/>(bge-m3)
    participant CP as ChatProvider<br/>(qwen3:14b)
    participant QL as QuickLook
    Me->>CLI: 질문 (--quicklook)
    CLI->>QE: query(질문)
    QE->>DB: FTS5 bm25 키워드 검색
    QE->>EP: 질문 임베딩 (+미계산 청크 백필)
    EP-->>QE: 벡터
    QE->>DB: 코사인 유사도 상위 청크
    Note over QE: RRF로 키워드·벡터 순위 결합 → 상위 8청크
    QE->>CP: 근거 청크 + 질문 (근거만 사용, 인용 필수)
    CP-->>QE: 답변 + [C#] 인용 마커
    QE->>QE: 인용 마커 검증 (무인용·미지 마커 → 실패 처리)
    CLI->>QL: answer.md(0600) 저장 → qlmanage -p
    QL-->>Me: 자동 팝업 (인용·경고 포함)

인용 검증이 fail-closed라는 점이 핵심이다 — 답변에 알려진 [C#] 마커가 없거나 모르는 마커가 있으면 성공으로 위장하지 않고 실패로 처리한다(프롬프트 인젝션 가드도 근거 텍스트 앞에 명시).

배치 쪽은 launchd가 매일 아침 실행한다: batch lock 획득 → 변경 파일만 ingest(sha256 비교) → 구조 감사(중복·부족 개념) + semantic 상충 감사 → review_output/에 날짜 리포트 생성 → 내가 리포트의 TODO를 보고 원본을 수정 → 다음 batch가 “이전 실행 이후 해결된 항목”으로 감지. 이 루프가 위 TO-BE 다이어그램의 “스케줄 재조정”의 실제 모습이다.

엔진 교체 — LM Studio 지원 구현됨

QueryEngine·AuditEngine은 ChatProvider·EmbeddingProvider·SemanticConflictProvider 인터페이스에만 의존한다. 이제 LM Studio(및 OpenAI 호환 서버)를 위한 openai.ts 구현체가 추가되었고, cli.ts가 profile.provider(ollama|lmstudio)와 baseUrl로 백엔드를 고르는 팩토리를 갖는다. 즉 Ollama는 선택이고 LM Studio만으로 완결된다. 다만 운영상 launchd 새벽 배치까지 쓰려면 LM Studio는 headless 서버(lms server start)를 상시로 둬야 해서, 데몬 운영은 Ollama가 더 단순하다.

설계 대비 달라진 점

• 검색: grep 대신 SQLite FTS5 + 임베딩 하이브리드 (위 “검색은 무-벡터로 시작” 참조)
• ingest 대상: 전체 .md 스캔 대신 git 추적 파일(git ls-files)만 — node_modules/.gitignore 자동 제외, 파일타입 설정(기본 md)
• Quicklook 파일: 단일 파일 재사용 대신 질의마다 임시 폴더(0600 권한) 생성 — 합의했던 단일 재사용 방식으로 정리 예정
• 파생 계층: MOC md 페이지가 아니라 인덱스+리포트 — Obsidian 백링크 그래프 연결 이점은 아직 미구현

ingest란 무엇인가 — mock 예시로 한 번에 이해

ingest = 내 Markdown을 “검색·감사할 수 있는 조각(chunk)들”로 분해해, 원본 밖의 색인 DB에 적재하는 것. 원본은 한 글자도 안 바뀐다(읽기만). 아래 mock 파일 하나가 어떻게 변형·저장되는지 따라가면 개념이 잡힌다.

입력 — sources/RAG.md

---
tags: [ai, rag]
aliases: [검색증강생성]
---
 
# RAG
 
RAG는 질의마다 원문을 검색한다. [[LLM Wiki]]와 대비된다.
 
## 한계
 
매번 재검색하므로 [[LLM Wiki]] 대비 축적이 없다.

1단계: 파싱 (parseMarkdown) — 무엇을 뽑아내나

• title = 본문 첫 H1 → "RAG"
• tags = frontmatter → ["ai","rag"]
• aliases = frontmatter → ["검색증강생성"]
• wikilinks / 참조 수 = 본문의 [[...]] 집계 → [[LLM Wiki]] 2회 (감사의 “부족한 개념” 판정 근거)
• chunks = heading 단위로 쪼갠 조각 — 이게 핵심. 파일이 아니라 heading 블록이 검색·인용의 최소 단위가 된다

2단계: 저장 (state.sqlite) — 어떤 구조로 어디에

저장 위치: ~/Library/Application Support/local-llm-wiki/projects/<project-id>/state.sqlite (vault 밖, 지워도 ingest --full로 재생성되는 캐시)

flowchart LR
    MD["sources/RAG.md<br/>(내 원본, 불변)"]
    P["parseMarkdown()<br/>frontmatter · H1 · [[링크]] · heading별 chunk"]
    subgraph DB["state.sqlite (vault 밖)"]
        SR["sources 1행<br/>title·tags·aliases·wikilinks"]
        CH["chunks 2행<br/>heading·line범위·본문"]
        FT["chunks_fts 2행<br/>bm25 검색용 미러"]
    end
    MD -->|"읽기만"| P
    P --> SR
    P --> CH
    CH --> FT

sources (1행) — 문서 1개의 메타데이터

path	title	tags_json	aliases_json	wikilink_refs_json	sha256
RAG.md	RAG	["ai","rag"]	["검색증강생성"]	[{"target":"LLM Wiki","count":2}]	(파일 해시)

chunks (2행) — heading 단위 조각. line_start~line_end가 나중에 인용의 위치가 됨

ordinal	heading	level	line	text(요약)
0	RAG	1	2–5	# RAG … [[LLM Wiki]]와 대비된다.
1	RAG > 한계	2	6–9	## 한계 … 축적이 없다.

(각 chunk엔 chunk_id = sha256(path, 파일해시, ordinal, heading)[:24]가 붙어 파일이 바뀌면 자동으로 다른 id가 된다)

chunks_fts (2행) — 위 chunk의 text를 FTS5로 미러링한 검색 인덱스. search/query는 여기에 bm25로 키워드 매칭한 뒤 chunks·sources와 join해 “어느 파일 어느 heading 몇 번째 줄”까지 짚어 인용한다. (임베딩은 이 단계에서 계산하지 않고, query 중 필요할 때 chunk_embeddings에 채워진다)

3단계: 증분 동작 — 다시 ingest하면

• 파일의 sha256을 비교 → 안 바뀐 파일은 건너뜀(unchanged), 바뀐 파일만 지우고 다시 넣음, 사라진 파일은 인덱스에서 삭제
• 그래서 재-ingest는 바뀐 것만 처리해 빠르다
• query는 실행 직전에 이 증분 ingest를 자동으로 1회 돌린다(임베딩 제외) → 방금 추가·수정한 노트도 그 질의에서 바로 잡힘. 끄려면 --no-refresh

왜 파일이 아니라 chunk로 쪼개나

질문에 답할 때 “이 파일 어딘가에 있음”이 아니라 **“RAG.md의 한계 섹션 6–9번째 줄”**처럼 근거를 정확히 짚고 인용([C1])하기 위해서다. heading 단위 chunk가 있어야 긴 문서에서 관련 조각만 골라 LLM에 넣고(컨텍스트 절약), 답변의 각 주장에 정확한 출처를 붙일 수 있다.

참고 문서

• karpathy/llm-wiki (원본 Gist)
• I rebuilt Karpathy’s LLM Wiki: what’s missing (theaioperator) — write-back·스케줄 자동화 권고
• nashsu/llm_wiki (GitHub) — 폴더 auto-watch·클리퍼 auto-ingest 구현
• How to Build an LLM Wiki with Obsidian and Claude Code (MindStudio)
• How I Built a Self-Maintaining KB for 6 Projects with Claude Code (HackerNoon)
• Auto LLM Wiki — Obsidian Plugin
• Astro-Han/karpathy-llm-wiki (Agent Skills 호환)