SamurAIGPT/llm-wiki-agent

A personal knowledge base that builds and maintains itself. Drop in sources — Claude (or Codex/Gemini) reads them, extracts knowledge, and maintains a persistent interlinked wiki. Works with Claude Code, Codex, OpenCode, Gemini CLI. No API key needed.

LLM Wiki Agent – LLM 에이전트로 구축된 자가 유지 지식 위키

무엇인가요 – 로컬 파일 기반 지식 기반 시스템입니다. PDF, DOCX, PPTX, 마크다운 등 어떤 형식의 문서든 raw/ 폴더에 넣고, LLM 기반의 에이전트에게 인제스트하도록 요청할 수 있습니다. 에이전트는 엔티티, 개념, 요약을 추출하고, 상호 연결된 마크다운 페이지를 생성하며, 모순을 탐지하고 지속적인 지식 그래프를 업데이트합니다. 모든 출력은 일반 마크다운과 정적 graph.html 시각화로 저장되므로, 어떤 에디터(예: Obsidian)나 웹 브라우저로도 탐색할 수 있습니다.

왜 중요한가요 – 일반적인 검색 증강 생성(RAG) 파이프라인은 매번 쿼리마다 원시 청크를 재처리하지만, 이 도구는 지식을 한 번만 컴파일하고 최신 상태를 유지합니다. 크로스리퍼런스, 엔티티 페이지, 모순 플래그는 인제스트 시점에 생성되므로, 채팅 전용 어시스턴트의 '세션 후 기억 상실' 문제를 피하고, 성장하는 쿼리 준비된 위키를 제공합니다.

빠른 시작 (Python 코드 필요 없음)

# 리포지토리 클론
git clone https://github.com/SamurAIGPT/llm-wiki-agent.git
cd llm-wiki-agent

# 지원되는 LLM 에이전트 중 하나로 리포지토리 열기 (Claude, Codex, Gemini 등)
# 에이전트는 설정 파일 (CLAUDE.md, AGENTS.md, GEMINI.md)을 읽습니다.
claude      # 또는 `codex`, `gemini`, `opencode`

에이전트는 ingest …, query: …, lint, build graph와 같은 자연어 명령을 이해합니다.

핵심 워크플로우

단계	명령 (자연어)	수행 내용
인제스트	`ingest raw/papers/attention-is-all-you-need.md`	파일은 필요 시 마크다운으로 변환되고, 파싱되며 위키가 업데이트됩니다. 새로운 엔티티 페이지(사람, 회사)와 개념 페이지(아이디어, 방법)가 자동 생성됩니다.
쿼리	`query: what are the main themes?`	LLM이 구조화된 위키를 읽고 답변을 합성하고, `wiki/syntheses/` 아래에 합성 페이지로 저장할 것을 제안합니다.
Lint	`lint`	일관성 검사를 수행합니다: 고립된 페이지, 손상된 링크, 누락된 엔티티 페이지, 감지된 모순이 `wiki/log.md`에 보고됩니다.
그래프	`build graph`	`graph.json` (노드/엣지 캐시)와 vis.js 기반의 자가 포함형 `graph.html` 시각화를 생성합니다.

디스크에 생성되는 항목

wiki/
├─ index.md          # 모든 페이지의 자동 생성 카탈로그
├─ log.md            # 마지막에 추가되는 작업 로그
├─ overview.md       # 모든 소스의 실시간 합성
├─ sources/          # 원본 문서당 하나의 요약 페이지
├─ entities/         # 사람, 조직, 프로젝트용 자동 생성 페이지
├─ concepts/         # 아이디어, 프레임워크, 방법용 자동 생성 페이지
└─ syntheses/        # 에이전트가 보관하도록 요청한 답변

graph/
├─ graph.json        # 캐시된 노드/엣지 데이터 (SHA-256 키 기반)
└─ graph.html        # 지식 그래프의 인터랙티브 브라우저 뷰

모든 파일은 일반 마크다운이므로, 어떤 에디터, 버전 관리 시스템, 또는 Obsidian 백업과도 호환됩니다.

주요 기능

다양한 형식 인제스트 – PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, EPUB 등은 Microsoft의 markitdown (또는 복잡한 PDF용 옵션 도구인 Marker)을 통해 자동 변환됩니다.
엔티티 및 개념 자동 생성 – 에이전트는 고유명사와 기술 용어를 추출하고, 전용 페이지를 생성하며, 등장하는 모든 곳에 링크합니다.
모순 탐지 – 새로운 소스가 기존 주장과 다를 경우, 인제스트 시점에 플래그가 추가됩니다.
지속적인 지식 그래프 – 2단계 구축: 결정론적 위키 링크 + LLM 추론된 의미적 엣지(신뢰도 점수 포함). Louvain 커뮤니티 탐지로 주제를 클러스터링합니다.
Lint 리포트 – 고립된 페이지, 손상된 링크, 데이터 공백, 제안된 누락된 소스.
Obsidian 호환 – 위키는 표준 [[wikilink]] 구문을 사용하며, wiki/를 임의의 Obsidian 백업에 심볼릭 링크로 연결하면 실시간 그래프 뷰가 가능합니다.
서버 없음, 데이터베이스 없음 – 모든 것이 파일 시스템에 저장되며, 실행 시 유일한 의존성은 설정 파일을 읽는 LLM 에이전트입니다.

예시 사용 사례

도메인	사용 방법
연구	논문 인제스트 (`/wiki-ingest raw/papers/*.md`), 다음에 "홀루시네이션을 줄이는 주요 접근법은 무엇인가요?"과 같은 합성을 요청 – 답변은 향후 참조를 위해 위키 페이지로 저장됩니다.
책 읽기	각 장을 마크다운으로 넣고, 에이전트가 등장인물 및 주제 페이지를 생성하게 한 후, 서사 구조나 모순을 쿼리합니다.
개인 지식 기반	일기, 기사 요약, 팟캐스트 노트를 저장; 패턴을 쿼리(예: "에너지에 도움이 되는 습관은 무엇인가요?")하고 위키가 진화하는 모습을 관찰합니다.
팀 인텔리전스	미팅 기록, 로드맵, 고객 통화 기록을 인제스트; "가장 자주 등장하는 기능 요청은 무엇인가요?"을 묻고, 구조화된 답변과 로드맵이 고객 피드백과 모순되는지 플래그를 얻습니다.
경쟁 분석	경쟁사 발표 및 시장 보고서를 지속적으로 공급; 비교 표를 쿼리하거나 "경쟁 환경" 합성 페이지를 생성합니다.

기술 스택 (README에 기재됨)

LLM 에이전트 – Claude Code, OpenAI Codex, Gemini CLI (제공된 스키마 파일을 읽을 수 있는 모든 에이전트).
그래프 처리 – NetworkX + Louvain 커뮤니티 탐지.
시각화 – vis.js (정적 graph.html).
파일 변환 – markitdown (기본), 옵션 Marker, arxiv2md, PyMuPDF4LLM (PDF용).
스크립팅 – tools/에 소규모 Python 유틸리티. 위의 Python 패키지와 Anthropic API 키(직접 변환 스크립트 실행 시)만 필요합니다.

도움 받기 / 확장하기

리포지토리는 각 에이전트의 정확한 명령 세트를 정의하는 스키마 파일(CLAUDE.md, AGENTS.md, GEMINI.md)을 포함합니다. 이 파일을 편집하면 이름 규칙, 프론트마터 필드, 또는 새로운 트리거를 추가할 수 있습니다.
위키가 단순한 git 리포지토리이므로, 변경 사항을 버전 추적하고, 실험용 브랜치를 만들거나, 협업자의 기여를 병합할 수 있습니다.

TL;DR – LLM Wiki Agent는 로컬에서 실행되며, LLM 에이전트 기반의 파이프라인으로, 어떤 문서 컬렉션도 자동 엔티티 추출, 모순 플래그, 시각적 지식 그래프를 갖춘 살아있는 상호 연결된 마크다운 위키로 변환합니다. Claude/Codex/Gemini 스타일의 모든 LLM 에이전트와 호환되며, 서버가 필요 없고 Obsidian 등 도구와 원활하게 통합됩니다.