거의 일주일동안 메달려 llm wiki시스템이 어느정도 능선을 넘은것 같습니다
지나가던행인이님의 secall로 처음 접하게 되서 이런저런 시행 착오도 많이 겪고 수난도 많이 겪었지만 조금만 더 손보면 자동화 딸깍까지 갈수있는 정도까진 온것 같습니다
아래의 내용은 저와 claude가 구축한 저희 llm위키 의 요약입니다
🏗️ Vault 지식 시스템 요약
Karpathy의 LLM Wiki 패턴에서 출발했지만, 소스와 철학이 근본적으로 다르게 발전한 시스템.
LLM Wiki 패턴은 개념적 배경으로 참조하고, 이 문서는 우리 시스템 고유의 사상과 현재 상태를 기록한다.
📋 목차
핵심 사상 — 작업이 곧 지식이다
Karpathy 원본의 소스는 외부 문서 (기사, URL, 책)다.
이 시스템의 소스는 자신의 AI 세션 로그 — 작업하는 과정 자체가 raw 데이터가 된다.
Karpathy: 외부 세계의 지식 → 나를 위해 정리
이 시스템: 내가 일하는 과정 → 그 자체가 지식
자기참조적 지식 시스템
볼트는 외부 정보를 담는 그릇이 아니라, 나의 사고 과정이 쌓이는 공간이다.
세션이 끝날 때마다 지식이 자동으로 축적되고, 과거의 나와 대화할 수 있다.
Karpathy 원본과의 차이
항목 | Karpathy 원본 | 이 시스템 |
|---|
주요 소스 | 외부 문서 (URL, 기사) | AI 세션 로그 + 클리핑 |
수집 방식 | 수동 ingest | 세션 종료 시 자동 수집 |
LLM 구성 | 단일 LLM | 멀티 LLM 역할 분담 |
품질 보증 | 없음 (LLM 직접 생성) | 2계층 검증 (PR 파이프라인) |
검색 | 파일 검색 위주 | FTS5(BM25) + BGE-M3 벡터 하이브리드 |
지식 축적 | 외부 → 내부 단방향 | 내 작업 ↔ wiki 양방향 |
자기 개선 | 없음 | PR history 피드백 루프 |
파이프라인 — 사용자 → 세션 → 지식
이 시스템의 전체 데이터 흐름은 세 계층으로 구성된다.
┌─────────────────────────────────────────────────────────┐
│ 사용자 (User) │
│ Claude Code / Claude AI 로 작업 │
└────────────────────┬────────────────────────────────────┘
│ 작업 중 자동 캡처
▼
┌─────────────────────────────────────────────────────────┐
│ 세션 (Session) │
│ raw/sessions/YYYY-MM-DD/{agent}_{project}_{id8}.md │
│ secall: BGE-M3 벡터 임베딩 → SQLite + ANN 인덱스 │
└────────────────────┬────────────────────────────────────┘
│ Gemma4 크론 (09/15/21시)
│ Claude PR review
▼
┌─────────────────────────────────────────────────────────┐
│ 지식 (Wiki) │
│ wiki/projects/ · wiki/topics/ · wiki/decisions/ │
│ → recall 시 다음 세션에 컨텍스트로 환류 │
└─────────────────────────────────────────────────────────┘
계층 1 — 사용자
사용자는 Claude Code(코딩·운영)와 Claude AI(탐색·대화) 두 채널로 작업한다.
채널이 달라도 세션 파일로 동일하게 수집되어 agent 필드로 구분한다.
채널 | agent 값 | 주요 용도 |
|---|
Claude Code | claude-code
| 코딩, Vault 운영, 태스크 실행 |
Claude AI (웹) | claude-ai
| 리서치, 토론, 개념 탐색 |
프로젝트 맥락: 세션은 cwd(작업 디렉토리)에서 프로젝트 이름을 자동 추출한다.
614개 세션, 114개 프로젝트 — 작업 디렉토리가 곧 지식의 범주가 된다.
계층 2 — 세션
세션 수명주기는 secall이 자동 관리한다.
이벤트 | 동작 | 명령 |
|---|
세션 시작 (Initialize) | ingest only | secall sync --local-only --no-wiki
|
세션 종료 (SessionEnd) | ingest + push | secall sync --no-wiki
|
30분 cron | ingest only | secall sync --local-only --no-wiki
|
인덱싱 구조:
세션 파일 (Markdown)
↓ 청크 분할
BGE-M3 (1024차원 벡터)
↓
┌──────────────────┬────────────────────────────┐
│ SQLite turn_vectors 테이블 │ ANN (USearch) 인덱스 │
│ + FTS5 전문 검색 인덱스 │ 근사 최근접 이웃 검색 │
└──────────────────┴────────────────────────────┘
검색 쿼리 타입:
타입 | 엔진 | 언제 |
|---|
keyword
| FTS5 (BM25) | 함수명·파일명·날짜 등 정확한 단어 |
semantic
| BGE-M3 cosine similarity | "왜 이렇게 했지" 같은 의미 검색 |
계층 3 — 지식 (Wiki)
세션은 두 경로로 wiki가 된다.
[자동] Gemma4 크론 (09/15/21시)
세션 → wiki/pr/{id8}.md (1차 초안)
↓ A: 기존 wiki 컨텍스트 주입
↓ C: 중복 감지 (80%+ → 3초 SKIP)
Claude PR review
↓ merge / create / discard 판정
wiki/topics/ · wiki/projects/ · wiki/decisions/
[수동] Claude /wiki · /wiki-batch · /wiki-query
필요한 시점에 직접 인제스트 또는 합성
지식의 환류: wiki는 정적인 저장소가 아니다.
사용자 질문
↓ wiki_search (경량) 또는 /wiki-query (전체 탐색)
관련 wiki 페이지 + 세션 recall
↓ Claude 응답에 반영
더 나은 작업 결과 → 새 세션 → 더 나은 wiki
프로젝트 차원의 지식 격리
wiki/projects/는 프로젝트별 현재 상태를 독립적으로 유지한다.
프로젝트 A의 결정이 프로젝트 B에 섞이지 않도록 sources: frontmatter로 추적한다.
발전된 점
1. 멀티 LLM 역할 분담
속도와 정확도를 분리했다.
에이전트 | 역할 | 특성 |
|---|
Gemma4 | 세션 → wiki/pr/ 1차 초안 (하루 3회 크론) | 빠름, 대량 처리 |
Claude | 2차 review, 판정, wiki 운영 | 정확, 맥락 이해 |
Karpathy 원본은 단일 LLM이 전부 처리 → 품질과 속도를 동시에 만족할 수 없음.
2. 2계층 검증 파이프라인
Gemma4가 만든 초안을 Claude가 기존 wiki와 대조 후 판정(merge/create/discard).
소형 모델의 구조적 한계(분류 오류, 중복 생성)를 Claude가 보완.
→ Wiki PR review 2계층 검증 체계
3. PR history 피드백 루프 (2026-04-15)
판정 완료된 PR을 삭제하지 않고 wiki/pr/history/YYYY-MM-DD-{id8}.md로 보관.
frontmatter의 verdict 필드와 ^review 블록으로 판정 사유를 구조화.
목적: 판정 이력 축적
→ 통계: Gemma4 정확도, discard 사유 빈도
→ 미래 판단: "이 유형은 과거에 어떻게 판정했지?" recall 가능
→ Gemma4 튜닝: 반복되는 오판 패턴 → 프롬프트 개선 근거
이것이 단순 기록을 넘어 시스템이 스스로 개선되는 루프를 만든다.
4. 지연 정제 루프 (Lazy Refinement Loop)
wiki-execute가 놓친 세션은 사라지지 않는다.
raw/sessions/에 보존 → 필요한 시점에 /wiki-query의 recall 폴백으로 발굴 → wiki 승격.
자동 처리 (속도 우선, 맥락 부족)
↓ 놓친 세션은 raw에 잔류
수요 기반 발굴 (질문이 트리거, 맥락 명확)
↓
더 정확한 wiki 페이지 생성
"왜 필요한지가 명확할 때 wiki로 만들어야 한다" — 자동 추천보다 신호 대 소음 비율이 좋다.
5. A+C 품질 향상
단계 | 이름 | 동작 |
|---|
생성 전 | A (Augment) | 기존 wiki 컨텍스트를 Gemma4 프롬프트에 주입 |
생성 후 | C (Check) | 생성 파일명으로 유사 wiki 검색 → merge_candidate 삽입 |
기존 wiki와 80%+ 중복인 세션은 ~70분 생성 대신 3초 SKIP.
요건: secall serve (포트 8765) 실행 중.
6. 세션 연속성 — 핸드오프 (2026-04-15)
LLM의 근본적 한계: 세션이 끝나면 컨텍스트가 사라진다.
이 시스템은 세션 종료 시 핸드오프 파일을 생성해 다음 세션에 전달함으로써 이를 극복한다.
세션 종료 (/session-close)
↓
share/project/obsidian-vault/handoff/YYYY-MMDDThhmm.md 생성
↓
다음 세션 시작 시 Claude가 자동으로 읽음
↓
이전 완료 작업 + 예정 작업 + 현재 상태 파악
핸드오프 파일 구조:
섹션 | 내용 |
|---|
✅ 완료한 작업
| 세션에서 실제 처리된 항목 (PR 판정, wiki 생성 등) |
🎯 다음 세션 예정 작업
| 미완료 작업, 후속 제안 |
📋 참고 상태
| PR staging 상태, 특기 사항 |
왜 Obsidian CLI를 쓰는가:
# 볼트 상대경로로 동작 → PC가 달라져도 경로 동일
obsidian files folder="share/project/obsidian-vault/handoff"
obsidian read path="share/project/obsidian-vault/handoff/<파일명>"
ls + Read 툴(절대경로)과 달리 obsidian CLI는 볼트 루트 기준 상대경로를 사용한다.
MacBook ↔ NAS ↔ 다른 PC 간 이동해도 동일한 명령이 작동한다.
핸드오프는 LLM 기억의 외부화다
세션 사이의 공백을 메우는 것이 아니라, 볼트 자체가 지속적 메모리가 되는 것.
"과거의 나 → 미래의 나"에게 보내는 상태 요약이다.
7. 세션 생명주기 인식
--resume으로 재진입한 세션은 turns_seen < total_turns 조건으로 부분 재처리.
같은 세션의 성장을 추적하며, PR history 파일명의 날짜가 달라져 자동으로 구분.
미흡한 점 / 과제
❶ 단락 수준 소스 추적 (미구현)
현재는 페이지 단위 sources: frontmatter만 있다.
llm-wiki-compiler의 ^[session_id] 단락 마크처럼 주장 단위 출처 추적이 없다.
# 미래 목표 예시
Gemma4는 word-level timestamp를 지원한다. ^[9c979986]
페이지 수가 적을 때는 불필요. 수백 페이지 이상 + 다수 소스 혼합 시 도입 검토.
❷ 대형 세션 (100턴+) 자동화 미완
100턴 이상 세션은 wiki-execute-large.sh로 수동 실행. RTX 5080(NAS) 권장.
크론 자동화 대상에서 제외된 상태.
❸ 관리자 편향 (개선 중)
Claude가 project/topic 분류 기준으로 과도하게 discard하는 경향.
PR history 축적으로 데이터 기반 패턴 분석 가능해지면 개선 예정.
❹ exportignore 유연성 부족
특정 세션/프로젝트를 인덱싱에서 제외하는 설정이 SQLite 쿼리에 하드코딩되어 있다.
llm-wiki-template의 .exportignore 파일 방식이 더 유연하지만, secall Rust 코드 수정 필요.
❺ confidential 세션 처리 없음
건강 데이터, 개인 금융 관련 세션의 암호화 보관 메커니즘 없음.
llm-wiki-template의 sessions/confidential/ + GPG 방식 참고 가능.
❻ Dataview 통계 대시보드 (Phase 4)
wiki/pr/history의 verdict 필드, wiki 페이지 수, 소스 분포 등을 시각화하는
Dataview 대시보드가 없다. 기반 데이터(frontmatter)는 이미 갖춰지는 중.
구조 원칙
소스 계층 불변성
raw/ 하위 파일은 절대 수정하지 않는다. 관찰 대상이 바뀌면 안 된다.
wiki는 현재 상태 중심
wiki는 히스토리가 아니라 현재 상태를 담는다.
이력과 의사결정은 decisions/로 분리.
에이전트 소유권 분리
소유 | 담당 |
|---|
raw/articles/, raw/inbox/
| Gemini/사용자 (Claude 수정 금지) |
wiki/pr/ staging
| Gemma4 생성 |
wiki/pr/history/
| Claude review |
wiki/topics/, wiki/projects/, wiki/decisions/
| Claude (최종 관리) |
log.md, overview.md (루트)
| secall 자동 생성 (수정 금지) |
obsidian CLI 우선
볼트 파일 접근은 obsidian CLI로 한다. 볼트 상대경로로 동작하므로 PC가 달라져도 경로가 동일하다.
세션 연속성 — 핸드오프
→ 발전된 점 섹션의 "7. 세션 연속성 — 핸드오프" 참조.
핵심 요약:
/session-close 스킬이 share/project/obsidian-vault/handoff/ 에 파일 생성
다음 세션 첫 번째 응답 전 obsidian CLI로 최신 파일을 자동 확인
완료 작업 / 예정 작업 / 시스템 상태를 구조화해 저장
obsidian CLI 기반 → 볼트 상대경로 → PC 이식성 확보
