TAU-HOME.COM
LOADING

옵시디언과 클로드 코드를 묶은 AI 세컨드 브레인 'claude-obsidian'

자료를 inbox 폴더에 넣으면 클로드가 읽고 상호 연결해 로컬 마크다운 지식 그래프로 정리하는 오픈소스 도구 claude-obsidian의 핵심 아키텍처와 설치 방법을 살펴봅니다.

tau · 2026년 11월 15일

#claude-code #obsidian #second-brain #pkm #open-source

옵시디언과 클로드 코드를 묶은 AI 세컨드 브레인 'claude-obsidian'

자료를 모으는 일은 쉽지만, 이를 체계적인 지식 체계로 정리하는 일은 늘 번거로운 숙제로 남습니다. 웹 기사, 논문 요약, 회의록을 저장 폴더에 쌓아두기만 하다가 결국 다시 열어보지 못하는 경험은 개인 지식 관리(PKM, Personal Knowledge Management)를 시도하는 사람이라면 누구나 겪는 문제입니다. 오픈소스 프로젝트 'claude-obsidian'은 앤스로픽의 터미널 기반 코딩 에이전트 도구인 클로드 코드(Claude Code)와 로컬 메모 도구인 옵시디언(Obsidian)을 결합해 이 문제를 자동화합니다.

옵시디언 그래프 뷰와 클로드 코드를 연동한 claude-obsidian 지식 관리 화면

이미지 출처: https://x.com/dopamine_crypto/status/2121872077619667225

개발자 AgriciDaniel이 공개한 claude-obsidian은 MIT 라이선스를 채택한 오픈소스 프로젝트입니다. 사용자가 inbox/ 폴더에 문서나 텍스트 자료를 넣어두면, 클로드가 원본을 읽고 핵심 개념을 추출한 뒤 상호 연결된 마크다운 문서로 변환해 옵시디언 지식 그래프(Knowledge Graph)를 생성합니다. 2026년 10월 21일 배포된 v3.0.1 릴리즈를 통해 플러그인 명령 체계가 안정화되었으며, 깃허브 스타 1만 6,000개 이상을 기록하며 주목받고 있습니다.

카파시의 'LLM 위키 패턴'과 3개 에이전트 구조

claude-obsidian의 핵심 설계는 인공지능 연구자 안드레이 카파시(Andrej Karpathy)가 제시한 'LLM 위키 패턴(LLM Wiki pattern)'에 뿌리를 두고 있습니다. 자료를 단순히 대화형 AI 검색창에 질문하고 답을 받는 데서 끝내지 않고, 마치 사람이 위키백과를 구축하듯 새로운 정보가 들어올 때마다 색인 문서와 주제별 문서를 갱신하고 문서 사이의 연결 고리를 만드는 방식입니다.

시스템 내부에서는 역할을 엄격하게 분리한 3개의 읽기 전용 에이전트와 트랜잭션 코어가 협업합니다.

  • wiki-ingest 에이전트: inbox/에 들어온 원본 소스를 읽고 분석해 새 마크다운 페이지 초안을 생성합니다. 원본 파일은 손상 없이 그대로 보존되어 모든 요약본이 원래 출처를 추적할 수 있습니다.
  • wiki-lint 에이전트: 지식 저장소 내부의 연결 끊김, 어디에도 이어지지 않은 고립 페이지(orphan page), 누락된 메타데이터나 빈 섹션을 검사해 지식 품질을 점검합니다.
  • verifier 에이전트: 새롭게 제안된 문서 변경 사항이 기존 저장소의 일관성을 해치지 않는지 사전에 테스트합니다.

이들 3개 에이전트는 읽기 전용으로만 동작하며, 실제 파일 작성과 수정은 안전성 검증을 거친 트랜잭션 코어만이 담당합니다.

단일 트랜잭션과 저널 롤백을 통한 데이터 안전성

개인 지식 관리에서 가장 우려되는 지점은 AI가 로컬 파일을 임의로 덮어쓰거나 오염시키는 상황입니다. claude-obsidian은 파일 쓰기 과정에서 데이터 무결성을 유지하기 위해 SHA-256 해시 기반의 단일 트랜잭션(Transaction) 구조와 저널 롤백(Journal rollback) 방식을 채택했습니다.

문서를 변경할 때 부분 적용으로 인한 데이터 깨짐을 방지하고, 모든 수정 단계가 완벽히 검증되었을 때만 디스크에 최종 반영합니다. 만약 처리 도중 오류가 발생하거나 링크 정합성이 어긋나면 저널 기록을 토대로 이전 상태로 즉각 롤백합니다.

결과물은 외부 클라우드 데이터베이스에 종속되지 않는 순수 마크다운(Plain Markdown) 파일로 사용자 PC에 저장됩니다. 특정 상용 서비스에 묶이지 않고, 옵시디언의 그래프 뷰(Graph view)나 캔버스(Canvas) 기능으로 언제든지 지식 연결 상태를 시각적으로 탐색할 수 있습니다.

15개 스킬 구성과 작업 모드 지원

claude-obsidian은 5개의 핵심 워크플로 스킬, 7개의 확장 스킬, 3개의 레퍼런스 스킬로 구성된 총 15개의 전용 스킬셋을 제공합니다. 클로드 코드 프롬프트 창에서 명령어를 직접 입력하거나 일반 자연어로 작업을 지시할 수 있습니다.

  • 핵심 워크플로: 저장소를 초기화하거나 기존 옵시디언 볼트를 연결하는 /claude-obsidian:wiki, 수집 자료를 정리하는 /claude-obsidian:wiki-ingest, 기존 노트 내용을 검색해 출처와 함께 답변하는 /claude-obsidian:wiki-query, 유용한 답변을 새 노트로 저장하는 /claude-obsidian:save, 결함 검사를 수행하는 /claude-obsidian:wiki-lint가 포함됩니다.
  • 다양한 정리 프레임워크 지원: wiki-mode 스킬을 통해 사용자가 선호하는 메모 방법론을 선택할 수 있습니다. 일반(Generic) 모드 외에도 제텔카스텐(Zettelkasten), PARA, LYT(Linking Your Thinking) 방식을 지원하여 노트가 분류되는 규칙을 변경할 수 있습니다.
  • 검색 및 시각화 확장: 로컬 BM25 키워드 검색 엔진(wiki-retrieve)과 옵시디언 캔버스 보드 생성(canvas) 기능을 연계해 복잡한 연구 주제를 체계적으로 시각화합니다.

요구 사양과 설치 절차

claude-obsidian을 사용하기 위해서는 컴퓨터에 클로드 코드 실행 환경, Python 3.11 이상, 그리고 메모 확인을 위한 옵시디언 데스크톱 애플리케이션이 설치되어 있어야 합니다.

설치는 클로드 코드가 실행 가능한 터미널 환경에서 두 줄의 플러그인 명령어로 끝납니다.

claude plugin marketplace add AgriciDaniel/claude-obsidian
claude plugin install claude-obsidian@agricidaniel-claude-obsidian

설치를 마친 뒤 지식 저장소로 사용할 폴더로 이동하여 클로드 코드를 실행합니다.

claude
/claude-obsidian:wiki

명령어를 실행하면 설정 마법사가 미리보기를 먼저 보여준 뒤 사용자의 승인을 거쳐 볼트(Vault) 구조를 구성합니다. 기존에 사용하던 옵시디언 볼트가 있다면 파일을 다른 곳으로 옮기지 않고도 그대로 연동할 수 있습니다.

단, 윈도우(Windows) 환경 사용자는 볼트에 파일을 작성하고 수정하는 작업을 안전하게 수행하기 위해 WSL(Windows Subsystem for Linux) 환경에서 실행하는 것이 권장됩니다. 기본 윈도우 환경에서는 파일 검사와 미리보기는 가능하지만 직접 쓰기 단계에서 제한이 발생할 수 있습니다.

출처

Impact-Site-Verification: 9b3ebd10-6c45-44cf-a014-5b8c19b7b285