개인 지식 베이스 × 지식 그래프 (파일 기반, 반복 가능)
Markdown 문서 컬렉션을 '추억하고 추적 가능한' 지식 네트워크로 만듭니다. 각 문서에 frontmatter 메타데이터 레이어를 추가하고, 세 가지 관계로 그래프를 연결하며, 스크립트로 증류 레이어(결정 등록부 + 그래프 인접 리스트)를 재구성하여 에이전트가 분석 및 결정 전에 과거 아이디어와 히스토리컬 컨텍스트를 참조할 수 있도록 합니다.
핵심 원칙 (실행 전 이해하기)
- 문서 본체가 유일한 진실 공급원입니다. 그래프는 독립적인 시스템이 아닙니다. frontmatter와 이중 링크는 사용자의 md 파일 안에 존재합니다.
graph/디렉토리는 순수 생성물이며, 삭제 후 언제든지 재생성할 수 있습니다. 모든 수정은 원본 문서에서만 이루어집니다. - 쓰기 전에 반드시 확인해야 합니다. frontmatter는 당신이 초안을 작성하지만, 일괄 쓰기 전에 사용자에게 샘플을 보여주고 확인을 받아야 합니다. supersedes(누가 누구를 대체했는지)와 같은 판단적 관계는 반드시 목록으로 만들어 확인을 받은 후에만 작성하며, 묵시적으로 작성하지 않습니다.
- 강등하되 억지로 쓰지 마십시오. 결론을 읽을 수 없는 문서는
status: reference로 표시하고, conclusion을 지어내지 마십시오. 잘못된 '한 줄 결론'은 결정 시 사용자를 오도할 수 있으며, 없는 것보다 더 해롭습니다.
이 스킬 디렉토리에는 두 개의 동봉 파일이 있습니다 (이 SKILL.md 파일과 같은 디렉토리에 위치):
scripts/gen_kb_graph.py— 그래프 생성 스크립트 (순수 표준 라이브러리, 오프라인 사용 가능)references/schema.md— frontmatter 전체 사양, 세 가지 엣지 의미론, 출력 템플릿, 회상 출력 형식. 처음 지식 베이스를 구축하거나 필드가 확실하지 않을 때 먼저 읽으십시오.
실행 흐름
0단계: 범위 결정, 사용자에게 일어날 일 설명
- 사용자가 폴더를 제공한 경우 → 해당 폴더가 지식 베이스 루트 디렉토리입니다.
- 사용자가 단일 또는 몇 개의 파일을 제공한 경우 → 질문: 이 파일들이 있는 폴더를 지식 베이스 루트 디렉토리로 할지 (권장, 과거 문서들이 서로 연결되어 그래프를 형성할 수 있음), 아니면 이 파일들을 저장할 별도의 독립적인 지식 베이스 폴더를 새로 만들지 물어보십시오.
- 사용자가 파일이 전혀 없고 지식 베이스를 새로 만들고 싶어하는 경우 → 2단계 '빈 지식 베이스 스켈레톤'으로 진행합니다.
- 작업을 시작하기 전에 두세 문장으로 사용자에게 확인합니다: 루트 디렉토리가 어디인지, 어떤 파일을 수정할지 (원본 문서 frontmatter + 새
graph/디렉토리), 문서 본문은 수정하지 않을 것임을 알립니다.
1단계: 지식 베이스 상태 확인
루트 디렉토리 읽기:
<루트>/gen_kb_graph.py또는<루트>/graph/INDEX.md가 이미 존재함 → 반복 모드 (기존 지식 베이스)- 그 외의 경우 → 지식 베이스 구축 모드 (새 지식 베이스)
2단계 A: 지식 베이스 구축 모드 (빈 지식 베이스 스켈레톤 포함)
- 빈 지식 베이스 스켈레톤 (사용자에게 기존 파일이 없는 경우): 다음 파일을 생성한 후 3단계로 건너뛰어 알리면 됩니다 —
<루트>/지식베이스-스키마-요약.md: references/schema.md에서 frontmatter 템플릿과 세 가지 핵심 규칙을 발췌하여, 사용자가 일상적인 글쓰기에서 참조할 수 있도록 함 (자체status: reference포함)<루트>/템플릿-분석문서.md: 완전한 frontmatter가 포함된 빈 템플릿 (위와 동일하게 자체 frontmatter 포함)
- 스크립트 설치: 스킬 디렉토리의
scripts/gen_kb_graph.py를<루트>/gen_kb_graph.py로 복사합니다 (이미 존재하면 건너뜁니다). 지식 베이스에 포함시키는 이유는 자체 포함성을 위함입니다 — 사용자나 다른 에이전트가 이 스킬에 의존하지 않고도 그래프를 재구성할 수 있습니다. - 시험 실행:
python3 <루트>/gen_kb_graph.py <루트>를 실행합니다.<루트>/graph/report.md의 개요를 읽고 사용자에게 규모를 보고합니다 (문서 수, frontmatter가 누락된 문서 수). - 메타데이터 초안 작성 (핵심 작업량): 먼저 references/schema.md를 읽은 후, 하위 디렉토리나 도메인별로 배치 처리합니다:
- 문서를 하나씩 읽고 frontmatter 초안을 작성합니다:
date(결론이 나온 날짜),domain,status(active/superseded/reference),conclusion(한 줄 결론, '이 문서가 최종적으로 주장하는 것'만 작성하고 내용 요약은 쓰지 않음) - 먼저 샘플을 보여줍니다: 대표적인 문서 2-3개 (결정 문서 1개, 참고 자료 1개)를 골라, 사용자에게 작성할 frontmatter를 보여주고 사용자가 형식을 확인한 후에 일괄 작성합니다
- 진화 관계 식별: 파일명에 v2/새 버전/복사본/개정 등이 포함되거나, 내용상 서로를 대체하는 문서 쌍을 찾아
supersedes참조를 제안하고, 목록으로 만들어 사용자 확인을 받은 후 작성합니다 - 각 배치 완료 시 진행 상황을 보고합니다; 본문은 한 글자도 수정하지 않고 frontmatter만 추가합니다
- 문서를 하나씩 읽고 frontmatter 초안을 작성합니다:
- 재구성 및 전달: 스크립트를 다시 실행하여 (자동으로
graph/kb-graph.html시각화 페이지 생성), 사용자에게 INDEX.md의 처음 몇 줄과 report.md의 나머지 누락 사항을 보여주고, 브라우저로 kb-graph.html을 열어 대화형 그래프를 볼 수 있음을 알립니다.
2단계 B: 반복 모드 (기존 지식 베이스)
- 기존
<루트>/gen_kb_graph.py를 실행합니다 (없으면 스킬 디렉토리에서 다시 복사합니다) graph/report.md를 읽고, 증분만 처리합니다: frontmatter가 누락된 새 문서, date/conclusion이 누락된 문서, 끊어진 링크. 초안 작성 → 확인 → 쓰기- 의미적 엣지 보충: 새 문서에 대해, 전체를 읽고 기존 문서와의
related('같은 사건의 두 측면') 및supersedes('이 문서가 저 문서를 수정함') 관계를 제안하며, 한 줄 이유를 첨부하고 확인 후 작성합니다 - 재구성 (kb-graph.html 시각화 페이지 새로고침 포함) 후, 사용자에게 변경 사항을 보고합니다 (새 노드/엣지 수, 나머지 누락 사항)
3단계: 사용자에게 사용 방법 안내
지식 베이스 구축/반복이 끝날 때마다 사용자에게 다음과 같이 앞으로 사용하라고 안내합니다 (원문 참조 가능):
앞으로 분석이나 결정을 내리기 전에 저에게 직접 말씀해 주세요: "XX에 대한 제 이전 아이디어와 결론을 알려줘." 그러면 그래프를 검색하고 진화 체인을 따라 시간 순서와 유효성을 확인한 후 참조 보고서를 드리겠습니다. 그래프를 시각적으로 보고 싶으시면 브라우저로
graph/kb-graph.html을 열어 보세요 (검색, 필터링, 노드 클릭으로 세부 정보 확인 가능). 문서는 계속 평소처럼 작성하시고, 작성이 끝나면 "지식 베이스 업데이트"라고 말씀해 주세요. 새 문서는 제가 자동으로 메타데이터를 보충하고 관계를 연결하겠습니다.
회상 모드 (결정 전 검색)
사용자가 과거 아이디어를 회상해 달라고 요청하고, 대상 디렉토리에 graph/ 생성물이 있을 경우, 이 흐름을 따르며 전체가 읽기 전용입니다:
graph/INDEX.md를 읽고, 주제 키워드로 문서 제목과 결론을 매칭하여 관련 항목을 1차 선별합니다 (많은 쪽이 누락보다 나음)- 확장이 필요하면
graph/GRAPH.md를 읽습니다: 1차 선별된 문서의 supersedes 진화 체인, related 이웃을 따라 맥락을 보충합니다 - 관련 문서의 frontmatter와 결론 부분을 정독합니다 (전체를 다 읽을 필요는 없음)
- 고정 형식으로 출력합니다 (전체 예시는 references/schema.md 참조):
- 관련 아이디어 목록: 각 항목 = 날짜 | 한 줄 결론 | 상태 | 문서 링크
- 진화 체인: 해당 문제에 대한 아이디어 변화 궤적, 언제 무엇에 의해 대체/수정되었는지 명시
- 현재 문제에 대한 참조점: 어떤 결론을 직접 사용할 수 있고, 어떤 것이 구식이어서 주의해야 하는지
- 선례 없음 선언: 그래프에서 해당 문제에 대한 과거 결정을 찾을 수 없는 경우, 명확히 "이것은 완전히 새로운 결정이며, 따를 수 있는 과거 선례가 없습니다"라고 말합니다 — 이것 역시 가치 있는 출력입니다
사용자 확인 체크포인트 (반드시 멈춰야 함)
- 지식 베이스 구축 전: 루트 디렉토리 범위, 무시 규칙 (
.kbignore파일로 디렉토리 제외 가능, 줄당 하나의 와일드카드) - frontmatter 일괄 쓰기 전: 2-3개 샘플 확인
- supersedes 관계 쓰기 전: 쌍 목록 확인
- 모든 본문 내용 수정: 기본적으로 금지, 사용자가 명시적으로 요청한 경우에만 수행
스크립트 사용법
python3 gen_kb_graph.py <지식베이스_루트_디렉토리> [--output graph] [--ignore "books,old,*_old"] [--no-html]
기본 무시: 숨김 디렉토리, .venv, venv, node_modules, pycache, .git, 출력 디렉토리 자체. 멱등적이며, 언제든지 다시 실행 가능합니다. 5개의 파일을 출력합니다 (INDEX.md / GRAPH.md / kb-graph.json / report.md / kb-graph.html). 형식은 references/schema.md를 참조하십시오. kb-graph.html은 의존성이 없는 단일 파일 시각화 페이지입니다 (힘 기반 그래프 + 결정 목록 테이블, 검색/필터링/클릭 세부 정보/더블 클릭으로 원본 파일 열기 지원). 환경이 허락한다면 브라우저로 직접 열어 사용자에게 보여줄 수 있습니다.
업그레이드 경계
문서가 약 500개를 초과하거나, GRAPH.md를 한 번에 다 읽을 수 없거나, 빈번한 다중 홉 추론이 필요한 경우, 파일 기반 그래프는 한계에 도달합니다. 사용자에게 LightRAG(그래프 + 벡터 하이브리드 검색)로 마이그레이션을 권장합니다 — frontmatter와 이중 링크가 최고의 마이그레이션 코퍼스이며, 마이그레이션은 무손실입니다. 그때까지는 데이터베이스나 외부 서비스를 도입하지 마십시오.