OKF — Personal RAG 지식저장소

개인 지식이 자동으로 축적·정제·정본화되고, 어떤 LLM 에이전트에서든 근거 인용과 함께 검색되는 개인 RAG 시스템.

핵심 아이디어는 "질문할 때마다 원본 조각을 다시 찾는 단순 RAG"가 아니라, LLM이 지속적으로 편찬하는 persistent Markdown wiki(Karpathy LLM Wiki 패턴)를 중심에 두는 것이다. 원본은 불변의 사실 근거로 보존되고, 위키는 요약·개념·문답이 누적되는 복리(compounding) 산출물이며, Obsidian은 사람이 탐색하는 IDE, LLM은 편찬자다.

📐 v3 설계서 — 자립 스택 재설계 (2026-08, 설계 확정·구현 대기): 낭비 제거, LangGraph 편찬 파이프라인, DeepAgents 리서치, 에이전트 핸드오프, 볼트 이전. 아래 문서는 현행 v2 시스템을 서술한다.

이 리포에 담긴 것: 시스템 코드(MCP 게이트웨이 app/, 평가 하네스 eval/, 배포 compose.yaml)와 이 아키텍처 문서. 담기지 않은 것: 지식 데이터(Obsidian 볼트), 파생 인덱스·백업(backups/), 시크릿(.env), 모델 가중치(models/) — 전부 로컬 전용이며 .gitignore로 차단된다. 야간 편찬 크론 스크립트는 별도 스택(hermes agent-stack)에서 운영된다(§5).

1. 한눈에 보기

flowchart LR
    subgraph IN["지식 입력 (3+1 경로)"]
        A1["에이전트 세션 캡처<br/>okf_capture_session"]
        A2["사용자 투입<br/>00-inbox / 00.init"]
        A3["리서치 토픽 신청<br/>05-todo 체크박스"]
        A4["웹 보강<br/>딥리서치 (무료/로컬)"]
    end

    subgraph VAULT["Obsidian 볼트 (정본, git 저장소, 로컬 전용)"]
        V1["10-sources<br/>원본 사본 (불변)"]
        V2["30-reviews/staging<br/>승인 대기 카드"]
        V3["20-wiki<br/>정본 위키"]
        V4["HOME.md · index.md<br/>대시보드·카탈로그"]
    end

    subgraph PIPE["야간 편찬 파이프라인 (hermes wiki_manager, 크론 21개)"]
        P1["인박스 스캔 (10분)"]
        P2["재니터 01:30"]
        P3["정밀화→게이트→웹검증<br/>01:45→02:20→02:40"]
        P4["자동 승격 02:50<br/>(결정론 게이트 5종)"]
        P5["index/HOME 재생성 03:25"]
    end

    subgraph MCP["OKF MCP 게이트웨이 (이 리포, read-only 사서)"]
        M1["SQLite 파생 인덱스<br/>FTS5 + trigram + bge-m3 벡터"]
        M2["하이브리드 검색 (RRF)<br/>+ 거버넌스·신선도 부스트"]
        M3["evidence bundle<br/>정답 캐시 · 감사 로그"]
        M4["gap 레이더<br/>지식 공백 추적"]
    end

    subgraph OUT["소비자"]
        C1["Claude Code / Desktop"]
        C2["hermes · opencode 에이전트"]
        C3["사람 (Obsidian, WebDAV 동기화)"]
    end

    A1 & A2 & A3 --> P1 --> V1 & V2
    A4 --> V1
    V2 --> P3 --> P4 --> V3
    P2 -.정리.-> V2
    P5 -.재생성.-> V4
    VAULT -- "read-only 마운트" --> M1 --> M2 & M3 & M4
    M2 & M3 --> C1 & C2
    V4 --> C3
    M4 -. "공백 → 새 토픽" .-> A3

닫힌 루프: 축적 → 정제 → 정본화 → 검색/즉답 → 공백 발견 → 재축적. 사람은 두 지점에만 개입한다 — 정본 승격 게이트의 예외 승인, 그리고 Obsidian에서의 탐색·토픽 신청.

Related MCP server: personal-notes-assistant

2. 설계 원칙

3. 지식 볼트 (정본 저장소)

Obsidian 볼트는 로컬 git 저장소다(이 리포에는 포함되지 않음). WebDAV(wsgidav)로 사용자 기기의 Obsidian과 동기화된다.

LLM-Wiki/
├── HOME.md            ← 야간 자동 생성 대시보드 (정본 수·대기 큐·최근 승격·리뷰 우선순위)
├── index.md           ← 정본 카탈로그 (20-wiki 실물 기준 야간 재생성)
├── log.md             ← append-only 연대기 (## [날짜] action | subject)
├── AGENTS.md·SCHEMA.md ← 편찬자 규율·스키마 계약
├── 00-inbox/          ← 지식 투입구 (세션 캡처·사용자 파일). 처리 후 .processed/로 이동
├── 05-todo/           ← 개인 실행 목록 + research-topics.md (리서치 토픽 신청)
├── 10-sources/        ← 원본 사본 — 불변의 사실 근거 (raw-source)
├── 15-graph-imports/  ← Graphify 파생 참고층 (재생성 가능)
├── 20-wiki/           ← 정본: concepts/ entities/ comparisons/ queries/ maps/
├── 30-reviews/        ← staging/ (승인 대기 카드) · gap-queue.md
├── 40-assets/         ← 첨부
└── 90-system/         ← 승격 원장·게이트 판정·재니터 원장·리포트

Frontmatter 계약 (모든 문서 공통):

type:   concept | entity | comparison | query | map | source-summary | graph-import
status: draft | canonical | needs-review | archived | reference | raw-source
trust:  source | human_edit | llm_summary | llm_context | web_staging
# + title/created/updated/tags/sources/confidence/contested

status와 trust는 검색 랭킹·검색 범위·편찬 규칙이 모두 참조하는 거버넌스 축이다. human_edit 페이지는 AI가 직접 고치지 않고 staging 제안만 만든다. alpha/트레이딩 시그널은 저장 금지.

4. MCP 게이트웨이 (사서) — 이 리포의 코드

FastMCP 기반 Streamable HTTP 서버. 볼트를 read-only로 마운트해 SQLite 파생 인덱스를 만들고, 12개 도구를 제공한다. 독립 compose 스택으로 편찬 파이프라인과 완전히 분리되어 있다.

4.1 하이브리드 검색 파이프라인

질의
 ├─ lexical: FTS5 unicode61 BM25 + trigram(오타·부분일치) + 구문/AND 부스트 + 2자 한국어 폴백
 ├─ semantic: bge-m3 1024d 코사인 (후보 풀 OKF_SEM_CANDIDATES=30, 단독 매칭 하한 SIM_SOLO=0.45)
 ▼
RRF 병합 → 거버넌스 부스트(canonical·human_edit·source ↑, archived 제외)
        → 신선도 보정(updated 완만 감쇠)
        → [옵션] cross-encoder 리랭크 (bge-reranker-v2-m3 사이드카, 실패 시 무손실 폴백)
 ▼
섹션(heading) 청크 단위 결과 + anchor(path#heading) + match 근거(fts/semantic/title)

• 인덱스는 5분 주기 증분 재스캔(콘텐츠 해시 기반), 임베딩은 content-addressed 증분(변경 섹션만 재임베딩, 삭제분 GC).

• 임베딩 프로바이더(LM Studio /v1/embeddings)가 죽어도 FTS-only로 무손실 폴백 — 큐는 유지되어 복구 시 재개.

• 모델 선정 근거: nomic-embed-v1.5는 한국어 판별력 없음(관련≈무관≈0.7), bge-m3는 관련 ~0.5 vs 무관 ~0.3 (2026-07-05 실측).

4.2 도구 12종

4.3 지식 공백(gap) 레이더

0건 검색(zero_hit)과 근거 빈약 번들(bundle_weak)은 자동으로 gap에 기록된다. okf_probe가 주기적으로 "이후 편찬으로 채워졌는가"를 재생 점검하고, 안 채워진 것은 compile_next로 편찬 파이프라인에 우선순위를 준다 — 검색 실패가 곧 다음 축적 대상이 되는 자기교정 루프.

4.4 보안

• 볼트는 read-only 마운트, 쓰기는 Error Book(자체 DB)과 00-inbox 세션 캡처(draft 고정)뿐.

• Bearer 토큰 인증, 127.0.0.1 바인드 → tailscale serve로 tailnet 전용 HTTPS 노출.

• 컨테이너 하드닝: cap_drop: ALL, no-new-privileges, 비루트(uid 10000), 리소스 상한.

• 시맨틱 단독 매칭 유사도 하한(환각성 매칭 방지), 시크릿 형태 문자열은 토픽/캡처 단계에서 거부.

5. 편찬 파이프라인 (야간 자동화)

별도 스택(hermes agent-stack)의 wiki_manager 프로필 크론 21개가 볼트에 쓰는 유일한 주체다. LLM이 개입하는 단계(정밀화·게이트 판정)와 결정론 단계(승격·정리·재생성)가 분리되어 있다.

5.1 야간 타임라인

5.2 정본 승격 게이트 (결정론 5종)

LLM 판정(gatekeeper)을 그대로 믿지 않고, 승격 시점에 기계로 재검증한다:

1. ## 승격 메타 존재 (정밀화를 거쳤는가)

2. 동일 제목 정본 부재 (중복 방지)

3. 10-sources/ 원본 사본 존재 (근거 실물)

4. 본문에 살아있는 [[wikilink]] (그래프 연결 — 고아 정본 방지)

5. 인용 앵커 존재 (path#heading 또는 URL — 출처 없는 정본 방지)

전부 통과해야 정본이 되고, 같은 커밋에서 index/log가 갱신되며, 승격 원장(90-system/promotions/*.jsonl)에 기록된다.

5.3 staging 재니터 (큐 수렴 장치)

유입(~7건/일)이 승격(~0.4건/일)보다 많아 대기 큐는 방치하면 발산한다. 재니터가 결정론 규칙으로 수렴시킨다 — 파일 삭제가 아니라 status: archived 전환이라 링크·검색(옵션) 모두 보존된다:

부가로 스캐너가 해시 불일치로 영구 스킵하는 00-inbox 고착 파일을 화해한다(소스 사본 보장 후 .processed/ 이동 — 내용 소실 0 보장).

6. 사람의 자리 — Obsidian 연동

• 보기: 볼트가 WebDAV(wsgidav)로 기기의 Obsidian과 동기화된다. 진입점은 HOME.md(대시보드) → index.md(카탈로그) → log.md(연대기).

• 넣기: 아무 마크다운이나 00-inbox/에 떨어뜨리면 10분 스캔이 수록한다.

• 시키기: 05-todo/research-topics.md에 - [ ] 궁금한 주제를 적으면 매시 브리지가 큐에 넣고, 야간 딥리서치가 조사해 축적한다. 처리되면 체크박스가 [x] … ← queued로 바뀐다.

• 승인하기: 웹검증 미달 승격 건은 텔레그램으로 해시 고정 승인 요청이 온다.

7. 배포·운영

docker compose up -d --build          # 기동 (볼트 경로는 compose.yaml의 바인드 마운트 수정)
curl -s http://127.0.0.1:8787/health  # 헬스체크 (인증 불필요)
docker compose --profile rerank up -d # [옵션] 리랭커 사이드카

• 클라이언트 등록(예: Claude Code): claude mcp add --transport http okf https://<tailnet-호스트>:8443/mcp --header "Authorization: Bearer <OKF_MCP_TOKEN>" — Codex·opencode 등 Streamable HTTP 지원 클라이언트 동일.

• 인덱스 초기화: docker compose down -v 후 재기동(볼트에서 전량 재생성). 단 Error Book·감사 로그는 파생층이 아니므로 **일일 DB 스냅샷(요일 로테이션 7개, backups/)**이 보호한다.

• 임베딩 모델 교체: .env의 OKF_EMBED_MODEL 변경 → 전량 자동 재임베딩 + 임계값 2종(SIM_BOOST/SIM_SOLO) 재보정 필수(eval 하네스의 calibrate).

8. 평가 하네스 (eval/)

검색 품질을 감으로 조정하지 않기 위한 골든셋 회귀 체계:

• golden.jsonl — 질의→기대 문서 골든셋(lexical/semantic/hybrid 카테고리).

• run_eval.py run — hit@k/recall 지표를 스로어웨이 DB 복사본에서 측정, baselines/와 비교. 코퍼스 지문 게이트: 볼트 상태가 다른 베이스라인과의 비교를 거부(허위 회귀/개선 차단).

• run_eval.py calibrate — 임베딩 임계값 재보정(모델/입력 스킴 교체 시 필수).

• 진단 도구: 후보 풀 스윕(sweep_candidates), 랭킹 진단(rank_diag), 폴백 프로브, 임베딩 처리량 벤치, 프리픽스 ablation(컨텍스추얼 프리픽스가 판별력을 떨어뜨려 폐기된 실험 기록).

9. 리포 구성

app/        서버 (config / store: 인덱스·검색·그래프 / server: MCP 도구 12종)
eval/       평가 하네스 + 골든셋 + 베이스라인
tests/      단위 테스트
compose.yaml, Dockerfile, requirements.txt
backups/    [git 제외] 일일 DB 스냅샷 — 개인 데이터
models/     [git 제외] 리랭커 가중치(수동 배치)
.env        [git 제외] OKF_MCP_TOKEN 등 시크릿

10. v3 재설계

docs/design-v3.md — 자립형 스택으로의 재설계 확정본 (2026-08-14)

v2 전수 감사에서 드러난 것(Graphify 47회 전부 no-op, LLM 편찬 체인 라이브락으로 월 정본 3편, 임베딩 해시 정의 불일치로 제목 변경 시 벡터 영구 stale)과 2026년 RAG 최신 조사를 근거로, 다음을 설계했다:

• 한 지붕 스택 — 게이트웨이 + 전용 hermes(크론·텔레그램·프로바이더) + WebDAV + 리랭커를 이 저장소의 compose 하나로. 남의 스택 의존 해소

• 편찬 재작성 — LangGraph 그래프(빈 큐면 LLM 미기동, 라이브락 자동 archive, 승인은 interrupt→텔레그램→resume) + 리서치만 DeepAgents

• RAG 코어 정비 — 해시 정의 통일, 정규 RRF + 파라미터 외부화(eval 스윕), 리랭커 기본 활성, 정답 캐시 v2, 비동기 우선

• 핸드오프 레이어 — okf_worklog / okf_handoff / okf_resume: 어떤 에이전트든 새 세션에서 한 번의 호출로 이전 작업 맥락을 이어받는다

• 볼트 이전 — 호스트 계정 소유의 전용 위치로 (Obsidian 주소는 불변)

진행 상태: Phase 0(비용 차단 — LLM 편찬 크론 11개 pause) 완료, Phase 1(RAG 코어) 착수 대기.