Obsidian 에이전트 Vault 퀵스타트
Obsidian을 AI 에이전트의 장기 지식 저장소로 쓰기 위한 도구 조합, vault 구조, AGENTS.md 규칙, 최소 skill, MCP 도입 기준을 정리한 퀵스타트.
Obsidian 에이전트 Vault 퀵스타트
한 줄 요약
Obsidian을 에이전트의 장기 지식 저장소로 쓰려면 처음부터 MCP나 복잡한 프레임워크를 붙이기보다, Markdown vault, Git, AGENTS.md, 작은 Skill, 검색 중심 작업 규칙부터 잡는 편이 안전하다.
먼저 읽을 결론
가장 좋은 출발점은 단순하다.
Obsidian vault = 장기 지식 / 원본 / 프로젝트 기록
AGENTS.md = vault 운영 규칙
Skill = 반복 절차 / 검증 루프 / 작업 방식
Git = 안전장치 / 변경 추적 / 복구
MCP = 필요할 때만 붙이는 API/tool 호출 계층
Obsidian은 앱이기 전에 로컬 Markdown 폴더다. 이 특성 덕분에 에이전트가 파일시스템, Git, rg, 스크립트로 vault를 직접 읽고 쓸 수 있다. 이 장점을 살리려면 역할을 섞지 않아야 한다.
| 계층 | 역할 |
|---|---|
| Obsidian | 지식, 상태, 원본, 프로젝트 기록 |
| Skill | 반복 절차, 실행 규칙, 검증 루프 |
AGENTS.md | vault/repo 전체에 항상 적용할 운영 규칙 |
| Git | 변경 이력, rollback, review |
| MCP | Obsidian 앱 내부 상태나 외부 tool interface가 필요할 때 붙이는 호출 계층 |
추천 우선순위는 다음이다.
- Karpathy LLM Wiki + OpenAI/Codex Skills +
kepano/obsidian-skills로 원리와 표준 구조를 먼저 익힌다. Ar9av/obsidian-wiki는 패키지화된 구현 예시로 테스트 vault에서 검증한다.- Obsidian Local REST API with MCP 계열은 read-only부터 시작하고, 실제로 앱 내부 command나 metadata cache가 필요할 때 붙인다.
이전 노트와 연결
이 노트는 기존 두 문서의 실전 퀵스타트다.
- Karpathy의 LLM Wiki 패턴과 차세대 지식 운영: raw source, compiled wiki, schema, lint, tension page 같은 운영 원칙.
- Agent Skill과 MCP 관리 도구: skill/MCP가 늘어날 때의 dependency management, context tax, 보안 검토.
앞의 두 노트가 원칙과 도구 생태계를 정리했다면, 이 문서는 “내 Obsidian vault를 에이전트가 안전하게 다루게 하려면 무엇부터 만들 것인가”에 답한다.
왜 저장했나
Obsidian을 AI 에이전트의 장기 기억으로 쓰려는 시도는 매력적이지만, 쉽게 과설계된다. 처음부터 MCP server, vector DB, graph DB, 여러 plugin을 붙이면 정작 중요한 raw/source 보존, 수정 규칙, Git review, 권한 경계가 흐려진다.
이 노트는 개인이나 소규모 팀이 바로 시작할 수 있는 최소 구조를 남기기 위해 저장했다. 핵심은 “앱 자동화”보다 “파일 기반 지식 운영”이다.
정리한 질문
Obsidian을 AI 에이전트의 장기 지식 저장소로 쓰려면 어떤 도구 조합을 먼저 보고, vault 구조와 AGENTS.md, Skill, Git, MCP를 어떤 순서로 설계해야 하는가?
1순위: 원리와 표준 조합
먼저 볼 조합은 Karpathy LLM Wiki, OpenAI/Codex Skills, kepano/obsidian-skills다.
이 단계의 목표는 “Obsidian을 에이전트가 다루는 Markdown 지식베이스로 보는 사고방식”을 잡는 것이다. Obsidian vault는 로컬 Markdown 파일 폴더다. 그래서 에이전트는 파일 읽기, 검색, Git diff, 작은 스크립트로 충분히 많은 일을 할 수 있다.
Skills는 SKILL.md 중심의 재사용 가능한 workflow bundle이다. Codex 기준으로는 skill의 name, description, file path가 선택 신호가 되고, 필요할 때 전체 SKILL.md와 references를 읽는 progressive disclosure 방식이 맞다.
학습 순서는 다음처럼 잡는다.
| 순서 | 볼 것 | 이해할 것 |
|---|---|---|
| 1 | Karpathy LLM Wiki | raw source와 synthesized wiki를 분리하는 사고방식 |
| 2 | OpenAI/Codex Skills | SKILL.md, scripts/, references/, assets/ 구조 |
| 3 | kepano/obsidian-skills | Obsidian Flavored Markdown, Bases, JSON Canvas, Obsidian CLI를 agent skill로 다루는 예 |
개인용이나 소규모 팀은 여기까지만 해도 충분히 쓸 수 있다. MCP 없이도 Obsidian, 파일시스템, Git, Skill 조합은 비용 대비 효과가 좋다.
2순위: Ar9av/obsidian-wiki
Ar9av/obsidian-wiki는 Karpathy LLM Wiki 패턴을 Obsidian용 프레임워크로 패키지화한 구현 예시에 가깝다. 문서상 obsidian-wiki setup --vault /path/to/vault, doctor, query, lint 같은 명령과 여러 에이전트용 skill/rule 설치 흐름을 제공한다.
바로 쓰면 빠르지만, 먼저 raw/wiki/log/index 구조를 이해하지 않으면 도구가 만들어주는 폴더를 왜 운영해야 하는지 놓치기 쉽다. 실제 vault에 바로 적용하기보다 테스트 vault에서 구조와 명령 설계를 먼저 검증하는 편이 안전하다.
적합한 경우는 다음이다.
- LLM Wiki 구조를 빠르게 scaffold하고 싶다.
- doctor/query/lint 같은 유지보수 명령이 필요하다.
- 여러 에이전트에 공통 skill/rule을 깔고 싶다.
- 기존 vault를 agent-maintained wiki로 정리하고 싶다.
3순위: Obsidian Local REST API with MCP
MCP는 AI 애플리케이션이 외부 데이터, 도구, workflow에 연결되는 표준 프로토콜이다. Obsidian Local REST API with MCP 계열은 REST API와 built-in MCP server로 vault read, create, update, delete, search, patch 등을 노출한다.
강력하지만 보안과 운영 복잡도가 커진다. MCP 공식 보안 문서가 다루는 confused deputy, token passthrough, SSRF, local MCP compromise, scope minimization 같은 위험을 무시하면 안 된다.
MCP가 필요한 상황은 제한적으로 잡는다.
| MCP가 필요한 경우 | 아직 필요 없는 경우 |
|---|---|
| active file을 읽어야 한다. | Markdown 파일 읽기/쓰기만 하면 된다. |
| Obsidian 앱 내부 command나 metadata cache가 필요하다. | Git 백업이나 권한 설계가 없다. |
| periodic note, current note, plugin state를 활용해야 한다. | 단일 개인 vault를 로컬에서만 쓴다. |
| 여러 agent/app이 같은 vault를 tool interface로 다뤄야 한다. | delete/move/replace 권한을 줄 준비가 안 됐다. |
처음에는 read-only 또는 파일시스템 접근으로 시작하고, 실제 API/tool layer가 필요해졌을 때 MCP를 붙이는 편이 낫다.
꼭 지킬 역할 분리
Obsidian과 Skill의 역할을 섞지 않는다.
Obsidian = 지식, 상태, 원본, 프로젝트 기록
Skill = 반복 절차, 실행 규칙, 검증 루프
AGENTS.md = 항상 적용할 운영 규칙
MCP = 외부 도구와 연결하는 호출 계층
Skill description은 마케팅 문구가 아니라 routing rule이다.
나쁜 예:
description: Helps with Obsidian.
좋은 예:
description: Search, summarize, and update an Obsidian Markdown vault. Use when the user asks to save knowledge, query notes, update wiki pages, ingest sources, or maintain vault metadata. Do not use for unrelated file editing.
무엇을 할 때 쓰고, 무엇에는 쓰지 말아야 하는지 적어야 에이전트가 정확히 고른다.
Vault 퀵스타트
Step 1. 구조 만들기
mkdir -p ~/Obsidian/agent-brain/{inbox,raw,wiki,projects,journal,templates,logs}
cd ~/Obsidian/agent-brain
touch index.md AGENTS.md
추천 구조:
agent-brain/
├─ inbox/
├─ raw/
├─ wiki/
├─ projects/
├─ journal/
├─ templates/
├─ logs/
├─ index.md
└─ AGENTS.md
Step 2. Git 초기화
cd ~/Obsidian/agent-brain
cat > .gitignore <<'EOF'
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.trash/
.DS_Store
.env
*.tmp
EOF
git init
git add .
git commit -m "Initial Obsidian agent vault scaffold"
Step 3. AGENTS.md 핵심 규칙
# AGENTS.md - Obsidian Vault Operating Rules
## Directory policy
- `raw/`: source material. Treat as append-only unless explicitly asked.
- `wiki/`: synthesized knowledge. Create and update pages here.
- `projects/`: project-specific notes, decisions, tasks, and plans.
- `logs/`: agent operation logs. Append a log entry after meaningful changes.
## Write safety
- Search before editing.
- Prefer targeted edits over full-file replacement.
- Never delete or move files without explicit approval.
- After edits, summarize changed files and rationale.
- When Git is available, check `git status` before and after edits.
## Retrieval policy
- Do not read the entire vault by default.
- Search by filename, tag, frontmatter, and full-text search first.
- Open only the smallest set of relevant notes needed for the task.
Step 4. 최소 Skill 만들기
mkdir -p ~/.agents/skills/obsidian-vault
cat > ~/.agents/skills/obsidian-vault/SKILL.md <<'EOF'
---
name: obsidian-vault
description: Search, summarize, and update an Obsidian Markdown vault. Use when the user asks to save knowledge, query notes, update wiki pages, ingest sources, maintain vault metadata, or work with Obsidian notes. Do not use for unrelated file editing.
---
# Obsidian Vault Skill
1. Read the vault root AGENTS.md before making changes.
2. Search before opening files.
3. Do not read the entire vault unless explicitly requested.
4. Keep raw/ and wiki/ separate.
5. Prefer targeted edits and append-only logs.
6. Never delete, move, or mass-rewrite without explicit approval.
7. After meaningful changes, append a log entry under logs/.
8. Summarize changed files, rationale, and uncertainty.
EOF
테스트 프롬프트:
$obsidian-vault 를 사용해서 ~/Obsidian/agent-brain vault의 AGENTS.md를 읽고,
현재 vault 구조가 적절한지 점검해줘.
파일은 수정하지 말고 보고서만 작성해줘.
Step 5. obsidian-wiki는 테스트 vault에서 먼저
python -m pip install obsidian-wiki
obsidian-wiki setup --vault ~/Obsidian/agent-brain
obsidian-wiki doctor
obsidian-wiki query "MCP security"
obsidian-wiki lint
실제 vault에 적용하기 전에는 반드시 테스트 vault에서 실행 결과와 diff를 확인한다.
Step 6. MCP는 필요할 때만
MCP를 붙이는 순서는 보수적으로 잡는다.
1. Obsidian Community Plugin에서 Local REST API with MCP 설치
2. API key 생성
3. localhost binding 확인
4. read/search tool만 먼저 연결
5. create/append 허용
6. update/patch 제한 허용
7. delete/move/replace는 사용자 승인 필수
API key와 tool 권한이 보안 경계가 된다. read/search만으로 충분한지 먼저 확인한 뒤 write 권한을 단계적으로 열어야 한다.
Sync와 보안 주의점
Obsidian Sync와 iCloud, Dropbox, OneDrive, Google Drive 같은 클라우드 동기화를 같은 vault에 동시에 쓰는 것은 피한다. 충돌 위험이 커진다.
MCP는 read-only부터 시작한다. 권한이 넓어질수록 피해 범위도 커지므로 최소 권한, 짧은 토큰, 토큰 검증, credential logging 금지, localhost 개발용 HTTP 제한 같은 원칙을 적용한다.
delete, move, replace 권한은 자동화하지 않는다. 이 권한은 vault 손상이나 대량 삭제로 이어질 수 있으므로 사용자 승인 없이는 열지 않는 편이 안전하다.
Skill Artifact
이 노트는 독립 배포용 skill 저장소가 아니라, Obsidian 기반 agent vault를 만들 때 참고하는 운영 가이드다.
Agent는 이 페이지를 다음 상황에서 참고한다.
- Obsidian vault를 agent-maintained knowledge base로 설계할 때
- raw/wiki/projects/logs 구조를 정할 때
- vault root의
AGENTS.md운영 규칙을 작성할 때 - Obsidian 전용 Skill description과
SKILL.md초안을 만들 때 - MCP 도입 여부와 권한 범위를 판단할 때
범위는 개인용/소규모 팀용 vault 설계와 퀵스타트다. 조직 단위 권한 관리, 법무/컴플라이언스, 대규모 검색 인프라는 별도 설계가 필요하다.
검증이 필요한 주장
Ar9av/obsidian-wiki의 설치 명령, doctor/query/lint 기능, skill/rule 설치 흐름은 repo 버전에 따라 바뀔 수 있다.kepano/obsidian-skills의 포함 skill과 지원하는 Obsidian 기능은 업데이트될 수 있다.- OpenAI/Codex Skills, Claude Skills, MCP 보안 문서는 빠르게 바뀌므로 실제 skill을 만들기 전 최신 공식 문서를 다시 확인해야 한다.
- Obsidian Local REST API with MCP의 권한 모델과 노출 범위는 plugin 버전과 설정에 따라 다를 수 있다.
- Sync 충돌, Git conflict, Obsidian plugin metadata 변경은 개인 vault 구조에 따라 다르게 나타날 수 있다.
Source Fidelity Notes
- Preserved key numbers: 1순위/2순위/3순위 도입 순서, vault 7개 디렉터리 구조,
AGENTS.mddirectory/write/retrieval policy, 최소 Skill 8개 규칙, MCP 단계 7개,obsidian-wikisetup/doctor/query/lint 명령. - Preserved frameworks / models: Obsidian = Markdown folder, Obsidian/Skill/AGENTS.md/MCP/Git 역할 분리, Skill description as routing rule, MCP read-only first, Sync 도구 단일화.
- Preserved templates / checklists: vault scaffold command,
.gitignore,AGENTS.md핵심 규칙, 최소SKILL.md, MCP 도입 순서, 테스트 프롬프트. - Omitted or compressed: 원문의 반복 설명, 일부 도구별 홍보성 문장, 임시 sandbox attachment link는 제거했다. 원문 전체는 redaction된 형태로
sources/layer에 보존했다. - Omission risk: 이 페이지는 실행 가능한 빠른 시작 가이드지만, 각 외부 repo와 plugin의 최신 기능을 재검증한 설치 매뉴얼은 아니다. 실제 적용 전에는 테스트 vault에서 먼저 실행해야 한다.
출처 / 참고자료
- User-provided Korean AI research. Raw source preserved at
../../sources/tools/2026-07-07-obsidian-agent-vault-quickstart.raw.md. - Related note: Karpathy의 LLM Wiki 패턴과 차세대 지식 운영
- Related note: Agent Skill과 MCP 관리 도구
- Obsidian Help: How Obsidian stores data
- Karpathy: LLM Wiki gist
- Ar9av/obsidian-wiki
- Model Context Protocol: Introduction
- Model Context Protocol: Security Best Practices
- OpenAI Developers: Agent Skills
- OpenAI Developers: Custom instructions with AGENTS.md
- Claude Platform: Skill authoring best practices
- Obsidian Help: Switch to Obsidian Sync
- Model Context Protocol: Understanding Authorization
- coddingtonbear/obsidian-local-rest-api