AI 에이전트에게 "정리해줘" 라고 하면, 흩어진 자료(웹 링크·PDF·대화 로그·텍스트)를 내 옵시디언 볼트에 노트로 정리하고, 원하면 노션에 색인해주는 Claude Code 플러그인. (Codex엔 "플러그인 설치(/plugin)"가 없어요 — 대신 저장소를 받아 codex mcp add로 MCP 서버로 등록해 연동합니다: adapters/codex/SETUP.md.)
📘 처음이세요? 그대로 따라 하는 왕초보 가이드 (PDF)를 보세요 — 용어 사전·설치·사용·문제해결·라이선스까지 전부 쉽게 설명해요.
상태: v0.7.2 — 정리·검색·볼트 건강검진·작업 로그·보관함 자동탐지(MCP 도구 5개) 동작·검증 완료. 노션 색인은 노션 도구가 연결된 환경에서 동작(아래 "현재 상태" 참고).
📱 기기 안내: Wikimate는 윈도우 PC(데스크톱·노트북) 전용이에요. 스마트폰·태블릿에는 설치되지 않습니다.
- 🧹 자연어로 정리 — "이 링크 정리해줘" 한마디면 노트가 만들어져요. (가끔 자동발동이 안 되면
/wikimate <링크>슬래시 명령으로 100% 실행.) - 🧭 보관함 자동탐지(v0.7.1) — 옵시디언에 등록된 보관함(볼트)을 자동으로 찾아 "여기에 정리할까요?" 하고 제안해줘요(이름 안 말해도 됨, 도구
wikimate_vaults). - 📒 내 진짜 옵시디언 볼트에 — 설치된 옵시디언 도구(MCP/CLI)를 자동 감지해 사용하고, 없으면 파일로 폴백.
- 🗂️ 노션 색인(선택) — 노션 도구가 연결돼 있으면 색인 행을 추가(옵시디언=원본, 노션=단방향 색인).
- ✋ 항상 계획 먼저 → 승인 후 실행 — 멋대로 쓰지 않아요.
- 🔁 중복 차단 — 같은 자료는
source_hash로 한 번만. - 🛡️ 안전 설계 — 볼트 밖 경로 차단, 외부 글은 명령이 아니라 데이터로 취급(프롬프트 인젝션 방어).
- 🔎 물어보기 — "내 볼트에서 ~ 찾아줘" 하면 정리해 둔 노트에서 출처와 함께 답해요(없는 건 없다고 정직히).
- 🩺 볼트 건강검진 — 중복·깨진
[[링크]]·고아 노트·머리말 누락을 찾아 보고하고, 승인하면 삭제 없이(보관함 이동·백업) 고쳐요. - 🧾 작업 로그 — AI가 내 볼트에서 한 일을 자동 기록("최근 작업 보여줘").
| 낱말 | 쉬운 뜻 |
|---|---|
| 플러그인 | 프로그램에 끼워 넣는 새 기능 부품 (앱 추가 설치 같은 것) |
| 마켓플레이스 | 플러그인을 받아오는 앱 장터 |
| MCP / MCP 도구 | AI와 도구를 잇는 통로 / 그 통로로 누르는 기능 버튼 |
| 볼트(Vault) | 옵시디언에서 노트를 모아 두는 보관 폴더(이름이 있어요) |
| dry-run | 실제로 하기 전에 "계획만" 미리보기 |
더 많은 용어는 왕초보 가이드 1번에 있어요.
⚠️ 아래 두 명령을 한 줄씩 따로 입력하세요. (한꺼번에 붙여넣으면 URL이 깨져 실패해요.)
1) 마켓플레이스 추가 — 입력 후 Enter, "added" 확인:
/plugin marketplace add https://github.com/sodam-ai/SoDam-WikiMate.git
2) 플러그인 설치 — 1)이 끝난 뒤:
/plugin install wikimate@wikimate-marketplace
설치 후 Claude Code를 재시작하면 끝. (확인하고 싶으면 /mcp에 wikimate_collect·wikimate_lint·wikimate_fix·wikimate_runlog·wikimate_vaults 5개가 보이면 성공)
따로 "실행(켜기)"할 게 없어요. 설치만 하면 Claude Code를 켤 때마다 자동으로 함께 켜져요. "실행"은 곧 Claude Code를 켜고 대화창에 말로 시키는 것이 전부예요. (개발자가 서버를 직접 돌리려면 받은 폴더에서 npm install 후 npm start.)
Codex엔 /plugin 마켓플레이스가 없어요. 대신 저장소를 받아 MCP 서버로 등록합니다.
1) 저장소 받기
git clone https://github.com/sodam-ai/SoDam-WikiMate.git
2) MCP 서버 등록 (볼트·저장소 경로는 본인 것으로 바꾸세요):
codex mcp add wikimate --env OBSIDIAN_VAULT_PATH=D:/내/볼트/경로 -- node D:/받은/경로/SoDam-WikiMate/mcp/server.mjs
→ codex mcp list 에 wikimate가 보이면 성공.
3) (선택) 자연어 규칙 — Codex 작업 폴더에 저장소의 AGENTS.md를 두면 "정리해줘" 같은 말도 따릅니다.
업데이트: 받은 폴더에서 git pull 하면 끝(Claude Code 같은 캐시 함정 없음).
⚠️ Codex는 "축소판"이에요. 정리(쓰기) MCP 도구까지 동작하지만, 자동 발동·물어보기·여러 노트 종합 같은 스킬은 Claude Code 전용이고, 노션 색인은 Codex에 별도 노션 MCP가 연결돼 있어야 해요. (자세히:adapters/codex/SETUP.md)
GitHub에 새 버전이 올라가도, 내 PC의 마켓플레이스 캐시는 자동으로 안 바뀌어요. 그래서 재설치만으론 옛날 버전이 그대로일 수 있어요. 최신으로 갱신하려면:
/plugin marketplace update wikimate-marketplace
/plugin install wikimate@wikimate-marketplace
그래도 안 되면 /plugin 메뉴에서 마켓플레이스를 remove → 다시 add → 설치 (캐시를 통째로 새로 받아요).
💡 "GitHub에 푸시해야 하나요?" → 아니요. 설치·업데이트는 GitHub에서 받아오는 것이라, 내가 따로 올릴(push) 필요가 없어요. (푸시는 개발자가 코드를 바꿀 때만)
⚠️ 설치 중EBUSY: resource busy or locked가 뜨면 → Windows 백신(Defender)이 갓 쓰인 파일을 잠깐 잠근 거예요. Claude Code를 완전히 종료했다 다시 켠 뒤 위 명령을 다시 실행하면 대개 풀립니다.
대화로 시키면 됩니다:
"이 내용을 내 'Vault' 볼트에 정리해줘"
⭐ 확실한 방법(권장) — 자연어 "정리해줘"는 AI 판단이라 가끔 자동발동을 안 하고 그냥 요약만 할 때가 있어요. 그럴 땐 슬래시 명령
/wikimate <링크/텍스트>를 쓰면 100% 발동합니다(직접 명령이라). 예:/wikimate https://example.com
- 📎 정리할 "자료"는 무엇이든 돼요 — 한 문장 텍스트, 웹 링크(
이 링크 정리해줘: https://...), 파일 경로(이 파일 정리해줘: D:\메모\오늘.md) 모두 OK. 따로 준비할 게 없어요. - 🧭 보관함 이름은 안 말해도 돼요(v0.7.1) — Wikimate가 등록된 보관함을 찾아 "여기에 할까요?"라고 제안해줘요. 콕 집어 "내 'Vault' 볼트에" 처럼 말해도 됩니다(이름은 옵시디언 좌하단 볼트 전환 메뉴에서 확인).
- 먼저 계획(어디에·어떤 도구로·노션 색인 여부)을 보여주고, 승인하면 노트를 만듭니다.
찾을 때도 대화로 (읽기 — 정리해 둔 노트에서):
"내 볼트에서 RAG 찾아서 요약해줘"
- 색인(노션)과 원본(옵시디언)에서 찾아 출처와 함께 답해요. 답하기 전에 원본이 실제로 있는지 확인하고, 지워진 노트(끊긴 색인)면 "원본 없음"이라고 솔직히 알려줍니다(없는 걸 있다고 안 함).
- 🔗 여러 노트를 묶어서도 물어볼 수 있어요: "내 노트들로 RAG·임베딩·벡터DB 관계 정리해줘" → 관련 노트를 모아 노트별 출처와 함께 종합해 답합니다(어떤 노트로 답할지 먼저 보여줘요).
정리 상태가 궁금할 때도 대화로 (건강검진 — 읽기):
"내 'Vault' 볼트 건강검진해줘"
- 🩺 시간이 지나며 쌓인 고아 노트(아무 데도 안 이어진 노트)·깨진
[[링크]]·중복·frontmatter 누락, 그리고 노션을 쓰면 끊긴 색인(원본은 지워졌는데 노션 행만 남은 것)을 찾아 보고해요. 멋대로 고치지 않아요 — 고칠 항목을 골라 승인하면 그때만 손봅니다: 중복은 삭제가 아니라 보관함(99_Archive)으로 이동(되돌리기 쉬움), 링크 수정은 고치기 전 자동 백업(비가역은 한 번 더 확인).
| 변수 | 용도 |
|---|---|
OBSIDIAN_VAULT_PATH |
볼트 폴더 절대경로 (파일 폴백·중복검사용) |
OBSIDIAN_VAULT_NAME |
옵시디언에 등록된 볼트 이름 (CLI용) |
NOTION_RESEARCH_DB_ID |
노션 색인 DB 지정 (없으면 검색하거나 물어봐요) |
.env.example를 복사해 .env로 쓰세요. 실제 값(토큰 등)은 절대 git에 올리지 마세요.
.claude-plugin/ 플러그인·마켓플레이스 매니페스트
mcp/server.mjs 무의존 MCP 서버 (stdio) — 도구 5개(collect·lint·fix·runlog·vaults)
mcp/lib/collect.mjs 수집(이름 안전화·중복 차단)
mcp/lib/lint.mjs 건강검진(읽기전용)
mcp/lib/fix.mjs 안전 수정(삭제 없음·백업)
mcp/lib/runlog.mjs 작업 로그
skills/ 자연어 자동 발동 스킬(organize·query·lint)
commands/ /wikimate · /wikimate-lint 명령
adapters/codex/ Codex용 설정 안내
templates/ 노트 템플릿
scripts/ 검증 스크립트(verify-*·smoke-*)
(내 볼트의) .wikimate/runlog.jsonl 작업 로그(숨김)
- ✅ 쓰기는 사람 승인 후 실행 (
dry_run이 기본 — 계획만 먼저 보여줌). 매번 "승인"이 번거로우면 "묻지 말고 바로 정리해줘" 라고 하세요 → 신규 노트 생성은 자동(단 덮어쓰기·삭제는 항상 한 번 더 확인). 그리고 승인은 선택지(숫자/클릭) 로 떠서, "진행해줘"를 타자치지 않고 골라도 돼요. - 🧾 원문 보존 알림 — 정리할 자료에 웹주소는 있는데 내용이 너무 짧으면("요약만 넣은 거 아니에요?") 또는 너무 크면, 저장 전 계획(dry-run) 화면에 알려드려요. 차단이 아니라 알림이에요 — 확인 후 그대로 진행해도 되고, 원문을 다시 준비해 다시 정리해도 돼요.
- ✅ 노트 제목·폴더의 경로 구분자·금지문자·제어문자를 정리하고 볼트 밖 경로를 차단(경로 이탈 방지).
- ✅ 외부 자료 속 지시문은 명령이 아니라 데이터로만 취급(프롬프트 인젝션 방어).
- ✅ 옵시디언 CLI는 셸 없이 실행(명령 주입 방지). 키·토큰은 노트·배포물에 저장하지 않음.
- ✅
.obsidian/폴더는 건드리지 않음. 기존 노트는 승인 없이 수정·삭제하지 않음. - ℹ️ 노션 색인은 노션 도구가 연결돼 있을 때만. 안 되면 옵시디언만 정리하고 솔직히 보고해요.
- 🧾 작업 기록(Run Log) — 실제로 만들거나·옮기거나·고친 노트는 자동으로
.wikimate/runlog.jsonl(숨김)에 한 줄씩 남아요. "최근 작업 보여줘" 라고 하면 무엇을 했는지 되짚어 드립니다(읽기 전용 안전 로그).
- ✅ 옵시디언 정리: 실제 볼트에 노트 생성 확인(자연어 자동 발동 포함).
- ✅ 건강검진·안전수정·작업로그: 단위테스트 + 서버 프로토콜 e2e로 검증(중복·깨진링크·고아 탐지, 삭제 없는 수정, 자동 기록).
- 🟡 노션 색인: 노션 도구(MCP/CLI)가 연결·인증된 환경에서 동작. 환경에 따라 미연결이면 자동으로 건너뜁니다.
- 🟡 Codex: 같은 MCP 코어를 쓰도록 어댑터 제공(설정은
adapters/codex/SETUP.md). ⚠️ 라이브 세션 미검증: 실제 Claude Code/mcp세션·실볼트 검증은 사용자 환경에서 권장(2분, 위 설치 참고).
- "정리해줘" 했는데 노트는 안 만들고 요약만 해요 → 자연어 자동 발동이 들쭉날쭉이에요.
/wikimate <링크>슬래시 명령으로 콕 찍으면 100% 됩니다(가장 확실). marketplace ... not found(마켓플레이스 못 찾음) → 등록이 안 된 거예요.update가 아니라/plugin marketplace add https://github.com/sodam-ai/SoDam-WikiMate.git부터 한 뒤/plugin install wikimate@wikimate-marketplace./mcp에 안 보여요 → Claude Code 재시작. 그래도 없으면 위 "업데이트" 방식으로 캐시 갱신.- 노트가 옵시디언에 안 보여요 → 볼트 이름을 정확히 말했는지 확인(파일 폴백은
OBSIDIAN_VAULT_PATH폴더에 생성됨). - 노션에 색인이 안 돼요 → 노션 MCP/CLI가 연결·인증돼 있는지 확인. 안 되면 옵시디언 노트만 생성됩니다(정상 폴백).
- 제목의 일부 기호가 사라졌어요 →
/ \ : * ? " < > |같은 파일명 금지문자는 안전을 위해 공백으로 정리돼요(의도된 동작). - 설치가
EBUSY ... locked로 실패해요 → 백신 파일 잠금이에요. Claude Code를 껐다 켠 뒤 다시 설치(위 "업데이트" 참고). 반복되면 잠시 뒤 재시도. - 옛날 버전(예: 0.1.0)이 깔려요 → 마켓플레이스 캐시가 옛것이에요. 위 "업데이트"의
marketplace update(또는 remove → 다시 add)로 갱신하세요.
더 많은 증상·해결은 왕초보 가이드 15번에 표로 정리돼 있어요.
notesmd-cli · mcp-obsidian · notion-mcp-server · ntn CLI
⚖️ 아래는 일반 안내이며 법률 자문이 아니에요. 정확한 고지는
LICENSE·NOTICE파일이 정본입니다.
- Wikimate 본체: Apache License 2.0 © 2026 SoDam AI Studio. 상업적 이용·수정·배포 허용, 단 저작권 고지+라이선스 사본 포함·변경 표시·NOTICE 유지 필요. 무보증(AS-IS), 상표 권리 미부여("Wikimate"·"SoDam AI Studio" 이름 임의 사용 금지).
- 외부 도구는 번들 아님 — Node.js·@modelcontextprotocol/sdk·notesmd-cli·mcp-obsidian·notion-mcp-server는 MIT, Notion API/
ntn은 Notion 약관, Obsidian은 개인 무료·상업용 별도 라이선스. 각자 원문 약관을 직접 확인하세요. - 콘텐츠 저작권은 원저작자에게 있어요. 수집·재배포 시 원저작물의 라이선스·약관을 지키세요. 노트는 내 컴퓨터(로컬) 에만 저장되고 외부로 보내지 않아요(노션 색인은 내가 켤 때만).
- Wikimate가 정리해 준 내 노트의 저작권은 100% 사용자 것이에요. Wikimate(SoDam AI Studio)는 정리 결과물(노트)에 대해 어떤 권리도 주장하지 않아요 — Wikimate는 소프트웨어일 뿐, 그 결과로 만들어진 노트의 저작자가 아닙니다.
전체 라이선스 표·면책은 왕초보 가이드 17번 또는
NOTICE참고. 개발·테스트·배포 방법은 DEVELOPMENT.md.