OKF — Personal RAG 지식저장소

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

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

📐 설계 문서: v3 — 자립 스택 재설계(구현 완료, 2026-08-20 컷오버) · v4 — RAG × LLM 위키 하이브리드(진행 중) · ADR 0001~0005.

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

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/&lt;섹터&gt;/&lt;유형&gt;<br/>정본 위키 (분야별)"]
        V4["HOME.md · index.md · 섹터 허브<br/>대시보드·카탈로그·목차"]
    end

    subgraph PIPE["편찬 파이프라인 (okf-hermes 크론, setup/jobs.yaml)"]
        P1["인박스 스캔 (10분)"]
        P2["재니터 01:30"]
        P3["편찬 그래프 01:45<br/>정제→심판→인용검증 (LLM)"]
        P4["사람 승인 → 승격<br/>(결정론 게이트 5종) 09/21시"]
        P5["index/HOME/허브 재생성 03:25"]
        P6["큐레이터 (주기 점검)<br/>섹터·중복·노후 제안"]
    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
    V3 -.점검.-> P6 -. "이동 제안 → 사람 승인" .-> V3
    VAULT -- "read-only 마운트" --> M1 --> M2 & M3 & M4
    M2 & M3 --> C1 & C2
    M2 & M3 -.읽기 도구.-> P6
    V4 --> C3
    M4 -. "공백 → 새 토픽" .-> A3

닫힌 루프: 축적 → 정제 → 정본화 → 검색/즉답 → 공백 발견 → 재축적. 사람은 승인 지점에만 개입한다 — 정본 승격과 섹터 이동은 볼트의 체크박스 하나로 결정되고, 그 밖에는 Obsidian에서 읽고 토픽을 신청한다. 에이전트가 쓰기 도구를 가진 적이 없다는 것이 이 그림의 핵심이다: LLM은 초안·판정·제안까지만 만들고, 볼트를 바꾸는 것은 승인 뒤의 결정론 코드다.

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/           ← 정본. **섹터(분야) 폴더 → 타입 폴더** 2단
│   └── <섹터>/        ← AI-지식시스템 · 금융-퀀트 · 인프라-운영 · 일반 (+ 자동 추가)
│       ├── <섹터>.md  ← 섹터 허브(야간 자동 생성 목차. description만 사람이 고침)
│       └── concepts/ entities/ comparisons/ queries/ maps/
├── 30-reviews/        ← staging/ (승인 대기 카드) · approvals/ (승인 제안서) · gap-queue.md
├── 40-assets/         ← 첨부
└── 90-system/         ← 승격 원장·게이트 판정·재니터 원장·리포트

섹터(분야) — lane이 '수명주기'라면 섹터는 '분야'다. 정본의 섹터는 경로가 정본이고 (sector_of()), frontmatter의 sector:는 사본이다. 사람이 옵시디언에서 폴더를 옮기면 그게 곧 진실이 되고, FM과 어긋나면 okf_validate가 알린다. 등록부는 폴더 자체이며 별도 목록 파일은 없다. 새 섹터는 정제기가 제안하고 승격 승인과 함께 폴더가 생긴다 (ADR 0005).

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 파생 인덱스를 만들고, 15개 도구를 제공한다. 독립 compose 스택으로 편찬 파이프라인과 완전히 분리되어 있다.

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

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

• 인덱스는 5분 주기 증분 재스캔(콘텐츠 해시 기반), 임베딩은 content-addressed 증분(변경 섹션만 재임베딩, 삭제분 GC). 재임베딩 트리거인 embed_hash는 실제로 프로바이더에 보내는 문자열의 해시라 입력이 같으면 재계산이 없고 다르면 반드시 갱신된다(v24).

• 스캔은 문서 단위 쓰기 트랜잭션, 검색은 스레드별 read-only 커넥션(WAL) — 전체 스캔 중에도 검색이 막히지 않는다.

• 임베딩 사이드카(okf-embed, llama.cpp /v1/embeddings)가 죽어도 FTS-only로 무손실 폴백 — 큐는 유지되어 복구 시 재개.

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

4.2 도구 15종

4.3 지식 공백(gap) 레이더

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

4.4 보안

• 볼트는 read-only 마운트. 쓰기는 Error Book(자체 DB)·00-inbox 세션 캡처(draft 고정)·50-ops 작업 기억(worklog/handoff)뿐 — 정본(20-wiki)은 승인 뒤 파이프라인만 쓴다.

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

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

• 시맨틱 단독 매칭 유사도 하한(환각성 매칭 방지), 시크릿 형태 문자열·저장형 인젝션 패턴은 토픽·캡처·작업 기억 단계에서 거부.

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

okf-hermes 컨테이너의 크론이 볼트에 쓰는 유일한 주체다(2026-08-20 컷오버). 스케줄의 정본은 **setup/jobs.yaml**이고 setup/provision.sh가 크론에 등록한다 — 잡은 전부 --no-agent 스크립트이고, LLM이 필요한 잡도 프롬프트 주입이 아니라 잡 코드가 직접 부른다 (모델 핀은 코드·설정에, 기동 시 preflight로 검증).

5.1 야간 타임라인

수동 실행 전용(스케줄 없음): sector_migrate(레거시 정본 → 섹터 분류 제안, 일회성), curate(큐레이터 점검), agent_smoke(에이전트 경로 점검). curate는 섹터 이전 승인 뒤 시각을 정해 setup/jobs.yaml의 주석을 풀어 등록한다.

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(:8090)로 기기의 Obsidian과 동기화된다. 진입점은 HOME.md(대시보드) → index.md(카탈로그) → 분야별 20-wiki/<섹터>/<섹터>.md(섹터 허브) → log.md(연대기).

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

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

• 승인하기: 사람이 결정하는 모든 것이 30-reviews/approvals/의 체크박스 하나다 — 정본 승격도, 섹터 이동도. 켜 두면 다음 틱(09/21시)이 반영하고, 텔레그램은 "지금 볼 차례"일 때만 알린다. 제안 내용을 고치면 지문이 어긋나 자동 거부되므로, 고치고 싶으면 승인하지 말고 원본을 편집한다(단 섹터 이동 제안의 to는 예외 — 고쳐도 된다).

• 분류 고치기: 옵시디언에서 정본을 다른 섹터 폴더로 직접 옮겨도 된다. 경로가 정본이라 그게 곧 반영이고, frontmatter의 sector:가 남아 어긋나면 다음 okf_validate가 알려 준다.

7. 배포·운영

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

7.1 클라이언트 연결 키트 (어느 기기·어느 에이전트든 같은 지식)

서버 하나 · 인덱스 하나 · 볼트 하나다. 모든 클라이언트가 같은 URL을 보므로 기기마다 동기화할 것이 없다.

# Claude Code
claude mcp add --transport http okf https://<tailnet-호스트>:8443/mcp \
  --header "Authorization: Bearer $OKF_MCP_TOKEN"

# Codex CLI — ~/.codex/config.toml
[mcp_servers.okf]
url = "https://<tailnet-호스트>:8443/mcp"   # 같은 호스트면 http://127.0.0.1:8787/mcp
bearer_token_env_var = "OKF_MCP_TOKEN"      # 토큰 값은 셸 env에 두고 파일에 쓰지 않는다

컨테이너 안의 에이전트는 tailscale을 거치지 않고 http://okf-mcp:8787/mcp(agentnet).

작업 이어받기 의식 — 어느 에이전트든 같다: 시작할 때 okf_resume('<프로젝트>') 한 번(이전 핸드오프 + 최근 작업 로그 + 참조 정본 + 열린 공백), 일한 뒤 okf_worklog, 넘길 때 okf_handoff. 재사용 가치가 있는 답은 okf_capture_session(kind='qa').

• 인덱스 초기화: 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_ranking.py — 랭킹 파라미터(RRF 상수·플랜 가중치·거버넌스 배수)를 재기동 없이 골든셋 위에서 스윕. v3에서 상수를 데이터클래스로 뺐기 때문에 가능해졌다.

• 진단 도구: 후보 풀 스윕(sweep_candidates), 랭킹 진단(rank_diag), 폴백 프로브, 임베딩 처리량 벤치.

9. 리포 구성

app/            MCP 게이트웨이 (읽기 전용 사서)
  config.py   설정 단일 정의처 (Config.from_env — 주입 가능)
  core/       I/O 없는 순수 모듈: chunking(청킹·임베딩 입력 해시) / ranking(RankingParams,
              정규 RRF) / governance(lane·status·trust 어휘) / frontmatter / safety(시크릿·인젝션)
  infra/      db(읽기/쓰기 커넥션 분리) / embedder / reranker
  services/   answer_cache(정답 캐시 v2) / workspace(worklog·handoff·resume)
  store.py    파사드 — 조립·트랜잭션·검색 조율
  server.py   MCP 도구 15종
eval/       평가 하네스 + 골든셋 + 베이스라인 + 랭킹 파라미터 스윕
tests/      단위·계약 테스트
docs/       설계서(design-v3.md) + ADR
pipeline/       편찬 파이프라인 (okf-hermes 크론이 실행 — 볼트에 쓰는 유일한 주체)
  run.py        잡 엔트리포인트 · settings.py · budget.py · llm.py · notify.py
  jobs/         preflight / janitor / inbox_scan / index_home / topic_bridge /
                compile(그래프) / approvals / research
  nodes/        그래프 노드: select · refine · gate · web_verify · promote · approval
  graphs/       LangGraph 편찬 그래프(SqliteSaver 체크포인트)
  research/     DeepAgents 러너 + 게이트웨이 MCP 클라이언트
  vaultio/      볼트 파일 I/O · git(1실행 = 커밋 1개)
setup/          jobs.yaml(스케줄 정본) · provision.sh(멱등 등록) · env.example
compose.yaml, Dockerfile, Dockerfile.hermes, 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 스윕), 리랭커 사이드카(옵션 — 실측 후 기본 off), 정답 캐시 v2, 비동기 우선

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

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

진행 상태 (2026-08-23)

결정 근거: ADR 0001 · ADR 0002 · 실행 절차: 런북