oh-my-wiki

지난 가이드에서는 헤르메스에 기본 탑재된 LLM Wiki로 위키를 만들고·묻고·점검했습니다. 한 가지 한계도 짚었죠. 넣고·묻고·점검을 전부 LLM이 직접 처리하다 보니, 위키가 커질수록 토큰 비용이 함께 늘어난다는 점이었습니다.

이번 가이드에서는 그 무거운 일을 정해진 코드(CLI) 로 내려, 검색·인덱싱·연결 그래프·점검을 토큰 없이 처리하는 오픈소스 oh-my-wiki 를 다룹니다. 한 회사의 일로 따라가 보겠습니다. 3040 남성 패션 브랜드 MAGMA의 전략기획실에서, 두 직원이 위키 한 채를 이어 씁니다.

• Oliver(전략기획실장·리서처): 웹에서 자료를 모아 회사 위키를 짓고, 그래프로 주제를 뽑아 시장 분석 초안까지 만듭니다.
• Mia(디자이너): 시장 조사를 새로 하지 않습니다. Oliver가 지어둔 위키를 그대로 열어, 자신의 디자인 정본 DESIGN.md 로 브랜드 보고서를 발행합니다.

핵심은 영속성입니다. Oliver의 세션이 끝나도 위키는 사라지지 않습니다. 위키는 디스크에 파일로 남기 때문에, Mia가 완전히 다른 세션·다른 프로필에서 같은 위키를 그대로 이어받습니다. 회사 지식이 한 사람의 머릿속이 아니라 회사 자산으로 남아, 직원이 바뀌어도 쌓이고 재사용됩니다.

💡 사전 요구사항: 헤르메스 기본 LLM Wiki 가이드로 위키의 기본 개념(원본·구조화·검색·유지의 4단계, 페이지 타입, 지식의 복리화)을 먼저 익히고 오시면 이번 실습이 훨씬 잘 이해됩니다. 이번 가이드는 그 개념을 반복하지 않고 실습·효율·멀티에이전트·영속성에 집중합니다.

두 표면 — 정해진 코드(CLI)와 AI 판단(스킬)

oh-my-wiki는 인터페이스가 두 겹입니다. 이 둘을 실습 내내 한 화면에서 번갈아 보게 됩니다.

• omw CLI: 검색·인덱싱·연결 그래프·점검처럼 무거운 일을 정해진 코드로 처리합니다. AI 추론이 들어가지 않아 빠르고, 같은 입력이면 늘 같은 결과가 나오며, 토큰이 들지 않습니다.
• omw 스킬: 헤르메스·Codex·Claude Code 같은 세션 안에서 판단이 필요한 일을 자연어로 맡습니다.

결정론적인 일은 CLI가, 판단이 필요한 일은 스킬이, 그리고 에이전트가 이 둘을 지휘합니다.

> 💡 CLI 명령어를 외울 필요는 없습니다. 실습에서 명령을 직접 쳐 보는 이유는 "이런 CLI가 준비돼 있고, 스킬이 그걸 대신 호출한다"를 이해하기 위해서입니다. 실제 작업은 대부분 자연어 한 줄로 진행합니다.

1단계 · 설치

설치 경로는 세 가지입니다. 가장 간단한 방법은 pipx입니다.

pipx install oh-my-wiki

소스로 받거나, 스킬 마켓플레이스로 받을 수도 있습니다.

git clone https://github.com/dandacompany/oh-my-wiki
skills add dandacompany/oh-my-wiki@oh-my-wiki -g -y --copy -a claude-code

⚠️ WSL(리눅스 환경)에 pipx가 아직 없다면, oh-my-wiki를 설치하기 전에 pipx부터 설치합니다.

sudo apt update
sudo apt install pipx
pipx ensurepath

설치가 끝나면 진단 명령으로 확인합니다.

omw doctor

✅ 진단 결과가 출력되면 설치는 성공입니다. 아직 볼트를 설정하기 전이라 "레지스트리가 없다"는 안내가 보이는데, 다음 단계의 omw setup 으로 바로 잡습니다.

오픈소스 저장소와 소개 페이지도 함께 참고하세요. 기능별 상세 튜토리얼이 정리돼 있어, 필요할 때 찾아보거나 그대로 에이전트에게 던져 구성해 볼 수 있습니다.

• 저장소: github.com/dandacompany/oh-my-wiki (MIT 라이선스, 무료)
• 소개·튜토리얼: oh-my-wiki.com

2단계 · 볼트 셋업 (setup 위저드)

omw setup 은 볼트 생성부터 검색·페르소나·recall 설정까지 한 번에 안내하는 설정 마법사입니다.

omw setup

위저드가 차례로 묻는 항목과 이번 실습의 선택은 다음과 같습니다.

• 볼트 이름: 위키 데이터가 저장되는 단위입니다. oh-my-wiki는 멀티 볼트를 지원해, 주제별로 위키를 여러 개로 나눌 수 있습니다. 이번에는 mens-fashion-kr 로 짓습니다.
• 모드: 일반 노트는 메모 모드, 구조화된 위키는 위키 모드입니다. 위키 모드를 선택합니다.
• 저장 형식: 마크다운 또는 옵시디언. 옵시디언으로 위키 문서를 보려면 옵시디언을 선택합니다.
• 검색 프로바이더: 자료를 모을 검색 도구입니다. 무료로 시작할 수 있는 Brave Search를 쓰려면 API 키를 입력합니다(Bright Data·Exa 도 선택 가능).
• fetch 프로바이더: 검색된 웹 페이지를 실제로 가져오는 도구입니다. 차단·로그인 페이지까지 가져오려면 Bright Data를 지정하고, 기본 도구로 충분하면 건너뜁니다.
• 검색 전략: 키워드 기반 FTS 가 기본입니다. 비용이 거의 없고 빠릅니다. 의미 기반이 필요하면 embedding·hybrid·llm 을 선택합니다.
• 한국어 노멀라이저: oh-my-wiki는 한국어에 특화돼 있습니다. 조사·어미가 위키 링크를 방해하지 않도록 형태소를 분리합니다. 규칙 기반 휴리스틱 으로 기본 동작하고, 더 정확한 분석이 필요하면 형태소 분석기 Kiwi 를 선택해 설치합니다.
• 페르소나: 위키를 전문적으로 관리하는 역할들입니다. 전체를 선택하고, 메인 페르소나는 사서(wiki-librarian)로 둡니다.
• 호스트 에이전트: 규칙(SKILL.md)을 어느 에이전트에 등록할지입니다. 헤르메스를 선택합니다. oh-my-wiki는 범용이라 Claude Code·Codex를 함께 쓰면 같이 선택하면 됩니다.
• recall: 질문할 때 관련 위키 페이지가 자동으로 근거에 따라오게 하는 기능입니다. auto 로 켜 둡니다.

> ⚠️ WSL 사용자는 볼트 경로에 주의하세요. oh-my-wiki는 WSL을 자동 감지합니다. 리눅스 경로에 만든 볼트는 윈도우 옵시디언 앱에서 열 수 없습니다. 윈도우 옵시디언으로 보려면 볼트를 윈도우 드라이브 경로에 만듭니다.

/mnt/c/Users/사용자명/omw-vaults/mens-fashion-kr

옵시디언을 쓰지 않거나 WSL 안의 리눅스 옵시디언을 쓸 계획이면 리눅스 파일 시스템 경로를 그대로 써도 됩니다. 맥·리눅스는 글로벌 경로가 기본입니다.

5.1과 같은 3계층, 달라진 것은 셋

위키의 기본 구조는 5.1과 같습니다. 원본 그대로의 raw, 정리된 위키 페이지(entities·concepts), 전체를 잇는 index. 원본은 건드리지 않고 정리본만 점진적으로 발전합니다. oh-my-wiki는 여기에 세 가지를 얹습니다.

• 멀티 볼트: 주제별로 위키를 여러 개로 나눕니다.
• 레지스트리: 볼트 위치를 ~/.omw 가 공통 관리합니다. 볼트가 어디 있는지 직접 찾을 필요가 없습니다.
• 호스트 보편: 규칙을 SKILL.md 로 끌어올려, 헤르메스·Codex·Claude Code 어느 세션에서든 같은 위키를 동일하게 씁니다.

지금부터 Oliver 프로필로 전환해, 회사 위키를 처음부터 지어 나갑니다.

3단계 · 자료 수집 (Oliver)

빈 볼트를 자료로 채웁니다. 손이 가장 많이 가는 구간입니다. 아직 보고서 주제를 정하지 않았다고 가정하고, 브랜드·유통 채널·소비 키워드·인구 통계·트렌드까지 넓게 모읍니다. 주제는 나중에 쌓인 위키가 그래프로 알려줄 것입니다.

수집 방식은 세 가지입니다.

한 건 수집 (fetch). 페이지 한 장을 가져옵니다. CLI를 직접 쓰면 다음과 같습니다.

omw fetch https://www.joongangenews.com/news/articleView.html?idxno=481642

여러 건 묶음 수집 (inbox). 여러 URL을 한꺼번에 모읍니다. 명령을 직접 입력하기보다, 스킬에 자연어로 맡기면 에이전트가 알아서 CLI를 제어합니다.

/omw 아래 기사들을 omw inbox에 추가하고, inbox list로 확인한 다음, inbox run으로 한꺼번에 수집해줘. (URL 목록 붙여넣기)

💡 이렇게 단계까지 적지 않아도 스킬이 알아서 수집합니다. 위 프롬프트는 어떤 방식으로 데이터를 모으는지 보여주기 위해 풀어 쓴 것입니다. 실제로는 의도만 전해도 됩니다.

폭넓은 자동 수집 (autoresearch). 가장 강력한 수집 방식입니다. 토픽을 던지면 여러 라운드로 검색하고, 쓸 만한 자료를 자동으로 원문에 넣습니다. 이번에는 순서를 보여주기 위해, 종합(synthesis)은 미루고 데이터 수집(ingest)까지만 진행합니다.

/omw 3040 남성 패션 시장을 autoresearch로 넓게 조사해서 raw로 모아줘. 브랜드·유통 채널·소비 키워드·트렌드까지 폭넓게. 종합(synthesis)은 아직 하지 말고 수집까지만.

자료가 더 필요하면 같은 방식으로 추가합니다. autoresearch는 중복 자료를 제거하며 모읍니다.

/omw 같은 주제로 20건 정도 더 autoresearch 해줘. (종합은 아직)

✅ 품질 좋은 위키를 만들려면 원문이 40건 안팎은 모여야 합니다. 옵시디언의 raw 폴더에 수집된 원문이 쌓이는 것을 확인하면 됩니다. 이 원문은 사람이 읽기 위한 것이 아니라, 다음 단계에서 LLM이 구조화할 재료입니다.

4단계 · 구조화 (사서 페르소나)

모은 원문을 엔티티(브랜드·인물 같은 대상)와 콘셉트(개념)로 쪼개 정리하고, 서로 링크로 엮습니다. 이 일은 사서(wiki-librarian) 페르소나에게 맡깁니다. 페르소나는 작업을 전문 영역별로 묶어, 프롬프트를 자세히 쓰지 않아도 빠진 곳까지 챙겨 줍니다.

먼저 준비된 페르소나 목록을 확인합니다.

/omw 준비된 페르소나를 출력해줘

이어서 사서에게 구조화를 맡깁니다.

/omw 사서 페르소나에게 맡겨줘. raw의 브랜드와 소비 개념을 엔티티와 콘셉트 페이지로 정리하고, 링크 제안까지 해줘.

스킬이 omw persona-run 으로 사서를 격리된 서브에이전트로 띄워 작업합니다. 헤르메스의 delegate_task로 백그라운드에서 처리되므로, 그동안 현재 세션에서는 다른 일을 할 수 있습니다.

✅ 작업이 끝나면 "엔티티 N건, 콘셉트 N건을 만들었다"고 보고합니다. 옵시디언의 entities·concepts 폴더에 페이지가 쌓이고, 각 페이지는 정해진 스키마(요약·관련·출처·노트)로 일관되게 작성됩니다.

한국어 조사까지 처리하는 자동 링크

본문에 등장하지만 링크가 걸리지 않은 언급을 찾아 위키 링크를 제안합니다. 한국어는 조사가 붙어 링크를 방해하는데, oh-my-wiki는 형태소 분석기를 내장해 이를 결정론적으로 처리합니다.

/omw 본문에서 링크 안 걸린 언급을 찾아 위키 링크를 제안해줘. 한국어 조사도 정확히 처리하고, 확인되면 고정으로 반영해줘.

💡 예를 들어 "애슬러의"에서 조사 "의"를 떼어 [[athleisure|애슬러]] 로 링크하고, 조사는 링크 밖에 남깁니다. 이 작업은 omw links suggest CLI로 토큰 없이 처리됩니다.

페이지 규약 (스키마)

페이지 타입마다 갖출 항목이 스키마로 정해져 있어, 위키가 한결같이 정돈됩니다. 어떤 스키마가 있는지는 CLI로 조회합니다.

omw schema list
omw schema show entity

5단계 · 주제 발견 (connections)

오늘의 핵심입니다. 쌓인 위키에서 보고서 주제를 그래프로 뽑습니다. 명령 한 번이면 위키 링크 그래프를 LLM 없이 순수 계산으로 분석합니다.

omw connections

결과의 핵심 지표는 넷입니다.

• 모듈러리티(modularity): 군집이 얼마나 잘 묶였는지를 나타내는 점수입니다. 높을수록 관련 주제끼리 잘 모였다는 뜻으로, 위키 품질의 척도가 됩니다.
• 군집(communities): 주제별로 모인 덩어리입니다. 보고서의 섹션이 됩니다.
• 허브(hubs): 여러 군집을 잇는 중심 페이지입니다. 섹션을 가르는 중심축이 됩니다.
• 브릿지(bridges): 관계없어 보이던 군집 사이의 의외의 연결입니다. 인사이트가 되는 자리입니다.

통계를 자연어로 정리해 달라고 요청하고, 옵시디언 그래프로도 함께 엽니다.

/omw omw connections로 위키 링크 그래프를 분석해줘. 모듈러리티 점수와 군집·허브·브릿지를 정리해서 보여주고, 옵시디언 그래프 뷰로도 열어줘.

> 💡 옵시디언에서 Ctrl+G 를 누르면 그래프 뷰를 바로 볼 수 있습니다. 다만 시각화 자체보다 중요한 것은 그래프가 알려 주는 해석입니다. 미리 목차를 짜지 않아도, 쌓인 위키가 주제 구조를 알려 줍니다.

핵심 아이디어는 이것입니다. 그래프에서 나온 셋이 그대로 보고서가 됩니다. 군집은 섹션, 허브는 중심축, 브릿지는 주목할 발견이 됩니다. 예를 들어 가성비 소비 군집과 프리미엄 그루밍 군집을 잇는 브릿지가 잡히면, "옷은 가성비로 가지만 그루밍은 프리미엄을 쓴다"는 의외의 인사이트가 나옵니다.

## 6단계 · 종합 (synthesis 초안)

리서처의 진짜 결과물은 분석입니다. 수집할 때 종합을 일부러 미뤄 둔 이유가 여기 있습니다. 주제를 미리 정해 결론을 쓴 것이 아니라, 넓게 모은 뒤 그래프가 정리한 구조 위에서 마지막에 종합합니다. Oliver가 그래프 군집을 섹션으로 잡아 시장 분석 보고서 초안을 만듭니다.

/omw 이 군집들을 섹션으로 잡아 3040 남성 패션 시장 인사이트 보고서 초안을 만들어줘. 각 섹션 근거는 omw context와 recall로 끌어오고, 출처 URL과 신뢰도를 함께 달아줘. 완성되면 위키 synthesis 폴더에 페이지로 저장해줘.

스킬은 곧바로 omw recall 로 주제를 검색하고, omw connections 와 omw context 로 근거를 끌어옵니다. 그래프와 연결이 미리 계산돼 있어, 종합 단계에서 추가로 드는 추론 비용이 작습니다.

omw context "가성비 소비"

✅ synthesis 폴더에 보고서 초안이 마크다운으로 저장됩니다. 각 주장에 출처 URL과 신뢰도가 또박또박 붙는데, 이는 setup에서 auto 로 켜 둔 recall 덕입니다. 질문하는 순간 관련 위키 페이지가 답변 근거로 따라옵니다. 여기까지가 Oliver의 일입니다.

💡 즉석에서 수집한 자료로 한 번에 만드는 보고서와 달리, 위키로 구조화한 근거 위에서 종합하면 신뢰도와 논리 구성이 크게 올라갑니다. 모든 주장이 위키 페이지를 거쳐 원문 출처까지 이어집니다.

위키를 지키는 여섯 페르소나

지금까지는 수집·구조화·그래프·종합을 단계마다 직접 시켰습니다. 매번 일일이 시킬 필요는 없습니다. 위키 일을 나눠 맡는 전문 페르소나 여섯이 있어, 의도만 말하면 알아서 처리합니다.

• 사서: 구조 손질·크로스링크·외톨이 페이지 정리
• 감사관: 위키 전체 건강 진단, 우선순위를 매겨 어느 페르소나에 맡길지 안내
• 큐레이터: index 동기화·정렬·서사 흐름
• 일관성 검사: 문서 안팎의 모순 탐지
• 팩트체커: 주장을 원자 단위로 쪼개 외부 검증, 신뢰도·출처 표기
• 용어 관리자: 용어집·별칭·표준 표기 통일

명령어를 외울 필요 없이 의도만 말하면, 스킬이 요청에 맞는 페르소나를 띄웁니다. "위키 점검해줘", "구조 정리해줘", "외톨이 정리해줘", "용어집 만들어줘" 같은 말이면 됩니다. 예를 들어 종합 초안의 주장을 검증하려면 팩트체커를 부릅니다.

/omw 팩트체커 페르소나로 관련 페이지를 팩트체크해줘. 주장을 쪼개 외부로 검증하고, 신뢰도와 출처를 달아줘.

💡 변경을 만드는 작업은 제안(.proposed)을 만든 뒤 확인을 거쳐 적용합니다. 읽기·리포트형 작업은 바로 결과를 냅니다. 위키는 한 번에 완성되는 것이 아니라, 반복하며 점진적으로 길러 가는 과정입니다.

7단계 · 발행 (Oliver에서 Mia로)

Oliver가 만든 위키는 전부 디스크에 파일로 저장됩니다. 세션 컨텍스트에 종속되지 않으므로, 세션이나 프로필이 바뀌어도 Mia가 그대로 이어받습니다. Mia는 리서치도 종합도 하지 않습니다. Oliver가 만든 synthesis 초안을 받아 제작에 들어갑니다. 회사 지식이 한 사람에게 묶이지 않고 회사에 남는 구조입니다.

Mia 프로필로 전환한 뒤, 먼저 같은 볼트가 그대로 인식되는지 확인합니다.

/omw 활성 볼트 확인해줘

이어서 Oliver의 초안을 Mia의 디자인 정본 DESIGN.md 로 입혀 HTML 보고서로 발행합니다.

/omw 올리버가 synthesis 폴더에 남긴 보고서 초안을 레퍼런스로, 내 DESIGN.md 정본을 그대로 적용해 HTML 보고서로 만들어줘. 위키 근거 링크는 본문에 그대로 박아줘.

✅ 디자인 정본의 색·타이포가 적용된 단일 HTML 보고서가 만들어집니다. 모든 주장에 위키 근거 링크가 박히고, 신뢰도와 출처가 메타데이터로 정리됩니다. 회사 톤이 한결같은, 그대로 보고해도 손색없는 자료가 나옵니다.

💡 위키가 디스크에 남아 영속되기에 가능한 협업입니다. Oliver가 짓고, Mia가 이어 씁니다. 같은 회사 지식을 두 직원이 나눠 쓰는 것은, 세션 안 여섯 페르소나가 일을 나눠 맡는 것과 같은 원리입니다.

유지보수 — 위키를 살아있게

위키는 한 번 만들고 끝이 아닙니다. 자료가 늘면 빠진 필드, 끊긴 링크, 어디에도 연결되지 않은 외톨이 페이지, 낡은 글이 생깁니다. 감사관 페르소나가 이를 훑어 심각도 순으로 진단하고, 어느 페르소나에 맡길지까지 안내합니다.

/omw 위키 검사관(감사관) 페르소나로 위키를 점검해줘

유지보수 명령은 자연어로도, CLI로도 쓸 수 있습니다.

omw lint
omw supersede old-page --by new-page
omw review due

신선도는 코드가 먼저 잡습니다. 신뢰도에 따라 다시 볼 주기가 자동으로 갈립니다(high 90일·medium 30일·low 7일). 코드가 fresh에서 stale, expired 로 자동 강등하고, 다시 승격하는 판단은 사람과 LLM이 함께 확인합니다. 점검과 강등은 코드가, 판단은 페르소나가 맡습니다.

> 💡 일반 메모는 쌓아 두면 관리가 안 돼 방치되기 쉽습니다. 유지보수 루프가 그 방치를 대신 맡아, 큰 비용 없이 지식을 계속 자산으로 키웁니다.

oh-my-wiki가 더 강력한 세 가지 이유

• 두 레이어로 싸게: 검색·인덱싱·연결 그래프·점검 같은 무거운 일을 결정론 CLI가 토큰 없이 처리합니다. 판단이 필요한 단계에서만 LLM 비용이 듭니다.
• 여섯 페르소나로 전문 분담: 혼자 하던 지식 관리를 리서치·구조화·팩트체크·감사로 나눠 맡습니다. 의도만 말하면 격리된 서브에이전트가 처리합니다.
• 그래프로 스스로 분석: 위키가 커져도 omw connections 가 군집·허브·브릿지를 LLM 없이 계산합니다. 같은 위키면 같은 결과가 나오고, 의도하지 않은 의외의 연결까지 찾아냅니다. 저장하는 위키가 아니라 분석하는 위키입니다.

복붙용 명령과 프롬프트

CLI 명령은 터미널에, 자연어 프롬프트는 세션에 /omw 로 시작해 입력합니다.

omw doctor          # 설치 확인
omw setup           # 볼트·검색·recall 한 번에
omw fetch 기사주소   # 한 건 수집
omw connections     # 군집·허브·브릿지
omw lint            # 빠진 필드·끊긴 링크·고아 점검
omw review due      # 다시 볼 페이지

자주 만나는 문제

⚠️ omw 명령을 못 찾습니다: pipx 설치 후 경로가 등록되지 않은 경우입니다. pipx ensurepath 를 실행하고 터미널을 새로 엽니다.

⚠️ 윈도우 옵시디언에서 볼트가 안 열립니다: WSL 리눅스 경로에 만든 볼트는 윈도우 옵시디언이 읽지 못합니다. 볼트를 /mnt/c/Users/사용자명/omw-vaults/ 같은 윈도우 드라이브 경로에 만들거나, WSL 안의 리눅스 옵시디언을 씁니다.

⚠️ autoresearch가 일부 페이지 수집에 실패합니다: 차단·로그인·자바스크립트 페이지는 기본 fetch로 가져오지 못할 수 있습니다(빨간 줄은 정상). 넉넉히 던져 필요한 양을 확보하거나, setup에서 fetch 프로바이더를 Bright Data로 지정합니다.

⚠️ 자연어로 시켰는데 위키를 안 보고 답합니다: 위키 작업 맥락이 옅어진 경우입니다. 프롬프트 앞에 /omw 를 붙여 스킬을 명시적으로 호출하면 위키를 근거로 답합니다.

마무리 — 본인 주제로 한 바퀴

이번에는 하나의 주제로 수집·구조화·그래프·종합·발행까지 한 흐름을 함께 돌아봤습니다. 개인 위키 시스템은 직접 써 봐야 내재화됩니다. 본인 업계나 관심 시장을 주제로, 위 여섯 단계를 한 바퀴 돌려 보세요. 끝나면 출처가 박힌 보고서 한 편과, 다시 쓸 수 있는 위키 한 채가 남습니다.

• 1단계부터 6단계까지: Oliver 역할(수집·구조화·그래프·종합)
• 마지막 발행: Mia 역할(DESIGN.md로 브랜드 보고서)

이렇게 만든 위키는 여기서 끝나지 않습니다. 다음 본부인 콘텐츠 사업부와 데이터 분석 사업부에서 지식 백본으로 다시 쓰입니다. 검색한 답을 버리지 않고 위키로 쌓아 다음 분석의 근거로 쓴다, 이것이 오늘의 한 줄입니다.