breferrari/obsidian-mind
breferrari/obsidian-mind has 5,521 GitHub stars and 610 forks. GitHot measured +38 in 7 days. Last checked 2026-11-10 00:01 UTC. Last push 2026-10-17.
A self-organizing Obsidian vault that gives AI coding agents persistent memory.
측정된 스타 증가
- in 24h
- 업데이트 지연
- in 7 days
- +38
- in 15 days
- 업데이트 지연
- in 1 month
- 업데이트 지연
서로 겹치는 기간의 순증가량이며 일별 합계가 아닙니다. 측정값이 없으면 비워 둡니다. 스타는 관심도를 나타내며 품질을 보장하지 않습니다.
README.ko.md
Original[!NOTE] 이 번역은 AI의 도움을 받아 작성되었습니다. 부자연스러운 표현이나 오역을 발견하시면 Issue 또는 Pull Request로 알려주세요. 커뮤니티의 수정과 기여를 환영합니다.
Obsidian Mind
Claude Code가 모든 것을 기억하게 해주는 Obsidian 볼트. 세션을 시작하고 하루에 대해 이야기하면, Claude가 나머지를 처리합니다 — 노트, 링크, 인덱스, 성과 추적까지. 모든 대화가 이전 대화 위에 쌓입니다.
🔴 문제
Claude Code는 강력하지만 기억하지 못합니다. 매 세션이 제로에서 시작됩니다 — 당신의 목표, 팀, 패턴, 성과에 대한 컨텍스트가 없습니다. 같은 내용을 반복해서 설명해야 합니다. 세 번의 대화 전에 내린 결정이 사라집니다. 지식이 축적되지 않습니다.
🟢 해결책
에이전트에게 뇌를 주세요.
You: "start session"
에이전트: *reads North Star, checks active projects, scans recent memories*
에이전트: "You're working on Project Alpha, blocked on the BE contract.
Last session you decided to split the coordinator. Your 1:1
with your manager is tomorrow — review brief is ready."
shardmind install 또는 git clone으로 설치 — 어느 쪽이든 동일한 볼트입니다.
⚡ 실제 동작 예시
아침 킥오프:
/om-standup
# → loads North Star, active projects, open tasks, recent git changes
# → "You have 2 active projects. The auth refactor is blocked on API contract.
# Your 1:1 with Sarah is at 2pm — last time she flagged observability."
회의 후 브레인 덤프:
/om-dump Just had a 1:1 with Sarah. She's happy with the auth work but wants
us to add error monitoring before release. Also, Tom mentioned the cache
migration is deferred to Q2 — we decided to focus on the API contract first.
Decision: defer Redis migration. Win: Sarah praised the auth architecture.
→ Updated org/people/Sarah Chen.md with meeting context
→ Created work/1-1/Sarah 2026-03-26.md with key takeaways
→ Created Decision Record: "Defer Redis migration to Q2"
→ Added to perf/Brag Doc.md: "Auth architecture praised by manager"
→ Updated work/active/Auth Refactor.md with error monitoring task
인시던트 대응:
/om-incident-capture https://slack.com/archives/C0INCIDENT/p123456
# → slack-archaeologist reads every message, thread, and profile
# → people-profiler creates notes for new people involved
# → Full timeline, root cause analysis, brag doc entry
하루 마무리:
You: "wrap up"
# → verifies all notes have links
# → updates indexes
# → brag-spotter finds uncaptured wins
# → suggests improvements
🚀 빠른 시작
📦 ShardMind로 설치 (권장)
npm install -g shardmind
mkdir my-vault && cd my-vault
shardmind install github:breferrari/obsidian-mind
shardmind install은 현재 디렉토리에 기록하므로, 먼저 새 폴더를 만들고 그 안으로 이동하세요. 마법사가 이름, 조직, 볼트 목적, 포함할 에이전트, QMD 활성화 여부를 수집합니다. 이어서 ShardMind가 git을 초기화하고, 필요 시 QMD를 부트스트랩하며, 답변에 따라 brain/North Star.md를 개인화합니다. 그런 다음:
- 설치된 폴더를 Obsidian 볼트로 엽니다
- 설정 → 일반에서 Obsidian CLI를 활성화합니다 (Obsidian 1.12+ 필요)
- 볼트 디렉토리에서 에이전트를 실행합니다:
claude,codex, 또는gemini. Codex는 폴더가 신뢰되고 각 훅이 승인되기 전까지 볼트의 훅을 실행하지 않습니다: 다른 에이전트와 사용하기 참고. - 업무에 대해 이야기를 시작하세요
ShardMind는 Obsidian 볼트 템플릿의 패키지 매니저입니다. 설치 시 .shardmind/ 사이드카가 추가되어 마법사, 선택적 모듈 (사용하지 않는 것은 건너뛰기), 3-way 머지 업그레이드를 제공합니다. 모든 값이 기본값일 때 설치 결과는 git clone과 바이트 단위로 동일합니다 — 클론 경험이 그대로 보존됩니다. 설치된 볼트에서 .shardmind/와 shard-values.yaml을 삭제해도 계속 작동합니다: ShardMind는 추가 기능이며, 필수 요소가 아닙니다.
또는 직접 클론
git clone https://github.com/breferrari/obsidian-mind.git
또는 GitHub 템플릿으로 사용하세요. 마법사를 건너뛰고 기본 템플릿을 받습니다. 그런 다음 위의 4단계를 진행하고, 추가로 **brain/North Star.md**에 목표를 작성하세요 (ShardMind 마법사를 사용하면 자동으로 처리됩니다).
🔍 권장: QMD 시맨틱 검색
볼트 전체의 시맨틱 검색을 위해 (노트 제목이 "Redis Migration ADR"이어도 "캐싱에 대해 뭘 결정했지?"를 찾을 수 있습니다):
npm install -g @tobilu/qmd
node --experimental-strip-types .scripts/qmd-bootstrap.ts
부트스트랩은 멱등성이 있어 재실행해도 안전합니다. vault-manifest.json 의 qmd_index 와 qmd_context 필드를 읽어 명명된 인덱스를 등록하고 임베딩을 생성합니다 (인덱스 이름은 qmd_index 가 설정되어 있으면 그 값, 설정되어 있지 않으면 볼트 폴더 이름을 슬러그화한 값). SessionStart 훅, .mcp.json 래퍼, CLI 명령은 모두 동일한 매니페스트 필드를 참조하므로, 같은 머신의 다른 볼트와 QMD 데이터가 섞이지 않습니다. CLI 명령에는 항상 --index <이름> 을 전달하세요:
qmd --index obsidian-mind query "캐싱에 대해 뭘 결정했지?"
qmd --index obsidian-mind update # 일괄 편집 후
qmd --index obsidian-mind embed # 많은 신규 노트 후
MCP를 통한 네이티브 에이전트 도구. .mcp.json에 Model Context Protocol 서버로 등록되어 있습니다 — QMD가 설치되어 있으면 mcp__qmd__query, mcp__qmd__get, mcp__qmd__multi_get가 Read와 Edit 옆에 에이전트의 도구 메뉴에 나타납니다. 서브에이전트, 슬래시 명령, 메인 대화 모두 동일한 타입 지정 계약을 호출합니다. 나중에 다른 MCP 호환 도구(데이터베이스, 티켓팅 시스템, 캘린더)를 추가하면 같은 방식으로 플러그인됩니다.
내부 동작 방식
QMD는 세 개의 작은 모델을 로컬에서 실행하므로, 설정할 API 키도 없고 쿼리당 비용도 없으며 오프라인에서도 동작합니다:
| 모델 | 크기 | 역할 |
|---|---|---|
embeddinggemma-300M |
~328MB | 노트와 쿼리를 벡터로 변환 |
qmd-query-expansion-1.7B |
~1.28GB | 쿼리를 더 나은 검색어로 재작성 |
Qwen3-Reranker-0.6B |
~640MB | 후보를 실제 관련성으로 재정렬 |
첫 사용 시 다운로드되어 캐시됩니다. GPU를 찾으면 오프로드하며(외장 GPU는 CUDA, Apple Silicon은 Metal), 없으면 CPU로 폴백합니다. qmd doctor로 현재 상태를 확인할 수 있습니다.
세 가지 CLI 명령은 저렴한 순서대로 이 스택에 대응합니다: qmd search는 모델을 전혀 쓰지 않는 BM25 키워드 검색, qmd vsearch는 벡터 전용, qmd query는 완전한 하이브리드입니다. 큰 다운로드를 피하고 싶다면 search만으로도 충분히 유용합니다.
MCP 서버에 주는 의미
om 서버는 어휘 쿼리와 벡터 쿼리를 함께 보내므로, 키워드가 겹치지 않아도 질문에 답하는 노트를 찾아냅니다. 실무적으로 알아둘 점:
- 비싼 쪽은 쓰기가 아니라 읽기입니다. 쿼리는 검색 전에 로컬에서 임베딩되므로 쿼리가 있는
recall은 수 초가 걸리고, 쿼리 없는recall은 거의 즉시입니다. 노트에 대한search는 빠르며, 비용이 드는 것은 벡터 단계입니다. - 메모리 쓰기는 모델을 기다리지 않습니다. 인덱스 갱신은 동기적이라 새 메모리는 즉시 검색 가능해지고, 벡터 생성은 백그라운드에서 진행됩니다. 벡터는 순위에만 영향을 줄 뿐 발견 여부에는 영향이 없기 때문입니다.
- 인덱스가 없어도 동작합니다. QMD가 없으면 서버는 어휘 매칭으로 폴백합니다. 순위는 나빠지지만 사라지는 것은 없습니다.
📋 요구 사항
- Obsidian 1.12+ (CLI 지원)
- Claude Code
- Node 22+ LTS (훅 스크립트용 — Claude Code / Codex / Gemini CLI와 함께 이미 설치되어 있을 가능성이 큽니다)
- Git (버전 히스토리용)
- QMD (선택 사항, 시맨틱 검색용)
Node 플래그에 관한 참고. 훅 스크립트는 Node의
--experimental-strip-types플래그로 TypeScript를 직접 실행합니다. 이 플래그는 Node 22.6+ (2024년 8월)부터 안정화되었고, Node 23.6+ 에서는 기본 동작이 되었습니다. 실험적(experimental)으로 표시되어 있지만 22 LTS와 24 LTS 전반에서 동작이 변경된 적은 없습니다. 향후 Node 릴리스에서 플래그가 폐지되거나 이름이 변경되면.claude/settings.json,.codex/hooks.json,.gemini/settings.json의 훅 명령어를 한 줄만 수정하면 됩니다.
⚙️ 작동 원리
절차적 코드는 환경을 소유하고, 에이전트는 콘텐츠를 소유합니다. .claude/scripts/의 훅이 분류, 검증, 인덱싱, 라이프사이클 주입을 처리합니다 — 결정론적이고, 테스트 가능하며, 모든 에이전트에서 동일하게 실행됩니다. 노트를 작성하고, 분류하고, 링크하고, 브리프를 작성하는 것 — 이는 판단이며 에이전트의 몫으로 남겨집니다. 양쪽은 작은 핸드오프에서 만납니다(훅이 컨텍스트를 주입하고 에이전트가 볼트를 읽음) — 서로의 일을 할 필요가 없습니다.
폴더는 용도별로 그룹화하고, 링크는 의미별로 그룹화합니다. 노트는 하나의 폴더(본거지)에 있지만 여러 노트(컨텍스트)에 링크됩니다. 에이전트는 이 그래프를 유지 관리합니다 — 작업 노트를 사람, 의사결정, 역량에 자동으로 연결합니다. 리뷰 시즌이 오면 각 역량 노트의 백링크가 이미 증거 자료가 됩니다. 링크가 없는 노트는 버그입니다.
볼트 우선 메모리는 세션과 기기 간에 컨텍스트를 유지합니다. 모든 지속 지식은 brain/ 토픽 노트에 있습니다(git 추적, Obsidian 브라우저 가능, 링크됨). Claude Code의 MEMORY.md(~/.claude/)는 볼트 위치를 가리키는 자동 로드 인덱스일 뿐 — 저장소 자체가 아닙니다. 즉, 메모리가 기기 변경에도 유지되며 그래프의 일부가 됩니다.
세션은 설계된 생명주기를 따릅니다. SessionStart 훅이 North Star 목표, 활성 프로젝트, 최근 변경사항, 미완료 작업, 전체 볼트 파일 목록, 볼트 위생 플래그를 자동 주입합니다 — Claude는 빈 상태가 아니라 컨텍스트가 있는 상태로 모든 세션을 시작합니다. 마무리할 때 "wrap up"이라고 말하면 Claude가 /om-wrap-up을 실행합니다 — 노트 검증, 인덱스 업데이트, 누락된 성과 발견. CLAUDE.md가 그 사이의 모든 것을 관리합니다: 파일 배치 위치, 링크 방법, 노트를 분할해야 할 때, 의사결정과 인시던트 처리 방법.
🔗 훅
다섯 개의 생명주기 훅이 라우팅을 자동으로 처리합니다:
| 훅 | 시점 | 동작 |
|---|---|---|
| 🚀 SessionStart | 시작/재개 시 | QMD 재인덱싱＋셀프힐, North Star 포커스·활성 작업·최근 변경사항·작업·파일 목록·볼트 위생 플래그 주입 — 전체는 Claude Code의 훅 출력 상한에 맞는 바이트 예산으로 제한되고, 마지막 줄은 주입 크기 미터 |
| 💬 UserPromptSubmit | 매 메시지마다 | 콘텐츠 분류(의사결정, 인시던트, 성과, 1:1, 아키텍처, 인물, 프로젝트 업데이트) 및 라우팅 힌트 주입. 이전 턴의 Stop 보고서도 에이전트에게 전달 |
| ✍️ PostToolUse | .md 작성 후 |
프론트매터＋위키링크 검증, 잘못 배치된 메모리 파일 차단, 비대 노트(줄이지 말고 분할)와 작성 시점 토픽 클러스터 플래그 |
| 💾 PreCompact | 컨텍스트 압축 전 | 세션 트랜스크립트를 thinking/session-logs/에 백업 |
| 🏁 Stop | 각 응답 종료 시 | 체크리스트＋구체적인 드리프트 발견 (SessionStart와 동일한 위생 스캔). 세션당 한 번, 내용이 바뀔 때만 다시 표시. 사용자에게는 섹션별 한 줄 요약이, 에이전트에게는 다음 메시지와 함께 전체 보고서가 전달되며 조치 여부는 에이전트가 판단. 조치는 om-tidy로 |
[!TIP] 그냥 이야기하세요. 훅이 라우팅을 처리합니다.
🧩 Claude Code mod
Claude Code 2.1.287 이상에서는 볼트가 mod도 함께 제공합니다. .claude/skills/obsidian-mind/에 있는, Claude Code 안에서 실행되는 플러그인입니다. 볼트 자체의 훅 스크립트를 실행하고, 그 출력이 세션에 전달되는 경로만 바꿉니다.
- 세션 컨텍스트가
CLAUDE.md처럼 instruction 파일로 전달됩니다. 컴팩션과/clear후에도 전체가 다시 읽히고(훅 출력은 포인터로 줄어듭니다), 범용 서브에이전트에도 전달되며(훅 출력은 전달되지 않습니다), Claude Code 훅 출력의 10,000자 제한에 잘리지 않습니다. 예산은vault-manifest.json의eager_layer_instruction_budget_bytes이며, 열린 작업처럼 줄어들지 않는 섹션은 이를 넘을 수 있습니다./memory에는.claude/session-context.md로 표시됩니다. - Stop 보고서가 답변 아래의 한 줄이 됩니다. 발견 사항이 바뀌면 Claude의 답변 아래에 mod 이름으로 시작하는 줄
obsidian-mind: vault check: …가 표시됩니다. Claude Code는 Stop에서 응답한 플러그인의 이름을+로 이어 붙이므로, 다른 플러그인도 응답하면obsidian-mind+<플러그인>: vault check: …처럼 표시됩니다. Claude는 전체 보고서를 다음 메시지와 함께 보이지 않게 받습니다. 긴급으로 표시된 발견 사항은 대신 즉시 Claude에게 전달됩니다(보내는 메시지 하나당 한 번까지이며, 두 번째는 보고서 안에서 기다립니다). 템플릿 자체의 보고서에는 그런 항목이 없습니다.
mod는 처리하는 이벤트마다 해당 훅에 대기하라고 알립니다. mod가 로드되지 않는 곳에서는 훅이 이전과 똑같이 동작합니다. Codex와 Gemini, 이전 버전의 Claude Code, 볼트 하위 폴더에서 시작한 세션(볼트 루트에서 실행하거나, 그곳으로 /cd한 뒤 /clear), 신뢰하지 않은 폴더입니다. mod는 볼트에 대한 Claude Code의 신뢰 확인을 수락한 뒤에만 로드됩니다.
mod는 샌드박스 없이 사용자의 권한으로 실행되는 코드이므로, 폴더를 신뢰하기 전에 내용을 확인하세요. claude plugin validate .claude/skills/obsidian-mind가 훅하는 모든 이벤트와 수행하는 모든 호출을 나열합니다(볼트 자체의 스크립트를 실행하고, 컨텍스트 파일을 쓰고, 각 세션에 어떤 보고서를 보여 줬는지 자체 저장소에 기록하고, 긴급한 발견 사항이 있으면 프롬프트를 보내는 것이 전부입니다). 끄려면 .claude/settings.local.json에 "enabledPlugins": { "obsidian-mind@skills-dir": false }를 추가하세요.
이 버전의 mod에서 출력 중 확인할 두 줄은 다음과 같습니다:
❯ ./register.ts hooks: classic.SessionStart, prompt.context, classic.Stop, turn.complete, prompt.submit, turn.start
❯ ./register.ts calls: $.fs.write, $.process.run (via runScript), $.prompt.submit, $.session.root, $.state.get, $.state.set, $.store.get (via setShown, shownFor), $.store.set (via setShown), $.ui.invalidate
⚡ 토큰 효율성
obsidian-mind는 전체 볼트를 컨텍스트에 로드하지 않습니다. 계층형 로딩으로 토큰 비용을 최소화합니다:
| 계층 | 내용 | 시점 | 비용 |
|---|---|---|---|
| 항상 | CLAUDE.md + SessionStart 컨텍스트 (North Star 발췌, git 요약, 작업, 볼트 파일 목록) |
세션 시작 시 | 매니페스트 예산이 상한 (예산 자체도 Claude Code의 10,000자 훅 출력 상한 안으로 제한됨). 실제 크기는 매 세션 마지막 줄의 미터가 보고 |
| 온디맨드 | QMD 시맨틱 검색 결과 | 에이전트가 특정 컨텍스트 필요 시 | 대상만 |
| 트리거 | 분류 라우팅 힌트 | 매 메시지 | ~100 토큰 |
| 트리거 | PostToolUse 검증 | .md 작성 후 |
~200 토큰 |
| 드물게 | 전체 파일 읽기 | 명시적으로 필요한 경우만 | 가변 |
SessionStart는 가벼운 컨텍스트를 로드합니다 — 주요 파일의 짧은 발췌, 파일명, git 요약만 로드하며 전체 노트 내용은 읽지 않습니다. 에이전트는 QMD를 통해 의미 기반 검색 후 파일을 읽으므로 관련 정보만 가져옵니다. 분류 훅은 메시지당 가벼운 Node 호출 1회입니다. 검증 훅은 마크다운 쓰기 시에만 실행되며 제외된 경로는 건너뜁니다. 볼트가 커져도 주입 계층을 정직하게 유지하는 다섯 가지 메커니즘: 소스 인식 주입 (resume/compact 시 휘발성 섹션만 재주입 — 정적인 대부분은 이미 대화에 있음), 모든 주입의 마지막 줄에 붙는 주입 크기 미터, 미터가 측정한 값을 실제로 강제하는 주입 예산 (상한을 넘으면 잃어도 되는 섹션부터 포인터로 축소되고, 축소된 섹션 이름은 미터에 반드시 표시됨 — 조용한 손실이 비대화보다 나쁘기 때문), 쓰기당 훅 프로세스 1회 (QMD 리프레시가 검증 훅에 동승), 목록 접기 (노트 수 임계값을 넘는 폴더는 한 줄 카운트로 접히므로, 아무도 설정하지 않은 폴더를 통해 볼트가 상한을 넘어 자랄 수 없음). 예산과 임계값 모두 vault-manifest.json 에서 조정할 수 있으며, 예산은 설정값과 관계없이 Claude Code의 10,000자 훅 출력 상한 안으로 제한됩니다. 상한을 넘으면 세션에는 2,000자 미리보기만 전달되기 때문입니다.
🌐 다른 에이전트와 사용하기
obsidian-mind는 Claude Code, Codex CLI, Gemini CLI에서 작동합니다. CLAUDE.md의 볼트 규약, .claude/scripts/의 훅 스크립트, .claude/commands/의 커맨드는 모두 에이전트 비의존적입니다 — 순수 Markdown, TypeScript, 셸이며 SDK 의존성이 없습니다.
Claude Code — 완전 지원. 훅, 커맨드, 서브에이전트, 메모리 시스템이 모두 기본으로 작동합니다.
Codex CLI — AGENTS.md를 네이티브로 읽습니다. .codex/hooks.json의 훅 설정이 Claude Code와 동일한 훅 스크립트를 연결합니다 — 세션 컨텍스트, 메시지 분류, 쓰기 검증이 자동으로 작동합니다.
Codex가 프로젝트의 훅을 실행하려면 두 가지 신뢰가 필요합니다(Codex CLI 0.160.0으로 확인, 2026-10-13 기준, #345).
- 볼트 폴더가 신뢰되어 있어야 합니다. Codex는 이를
~/.codex/config.toml의[projects.'<path>']에 기록합니다. Windows에서는 키가\\?\접두사가 붙은 경로입니다(예:[projects.'\\?\C:\path\to\vault']). - 각 훅이 승인되어 있어야 합니다. Codex는 각 승인을
[hooks.state]아래trusted_hash로 저장합니다. 대화형codex세션에서 승인하면 이것이 기록될 것으로 예상됩니다(추정: #345의 확인에서는 한 번의 비대화형 실행용 플래그--dangerously-bypass-hook-trust로 대신했습니다).
둘 다 갖춰지기 전에는 Codex가 어떤 훅도 실행하지 않으며, 세션에 볼트 컨텍스트가 전달되지 않습니다.
Gemini CLI — GEMINI.md를 네이티브로 읽습니다. .gemini/settings.json의 훅 설정이 Gemini의 이벤트 이름을 공유 훅 스크립트에 매핑합니다.
기타 에이전트 (Cursor, Windsurf, GitHub Copilot, JetBrains AI) — AGENTS.md로 볼트 규약을 읽습니다. 훅 지원은 에이전트마다 다릅니다.
[!NOTE] 훅, 커맨드, 서브에이전트 프롬프트, 볼트 메모리(
brain/)는 모두 에이전트 비의존적입니다.~/.claude/자동 메모리 로더만 Claude Code 전용입니다. 자세한 내용은AGENTS.md를 참조하세요.
🧠 어떤 저장소에서든 볼트에 접근하기
볼트는 보통 그 안에서 작업할 때만 도움이 됩니다. om MCP 서버가 이를 바꿉니다. 다른 어떤 저장소의 코딩 세션이든 노트를 검색하고, 읽고, 그래프를 따라가고, 배운 것을 볼트에 다시 기록할 수 있습니다.
{
"mcpServers": {
"om": {
"command": "node",
"args": ["/path/to/your-vault/.claude/scripts/om-mcp.mjs"]
}
}
}
이것은 사용하는 프로젝트의 .mcp.json에 들어갑니다. 그런 다음 해당 프로젝트 자체의 CLAUDE.md에 볼트를 가리키는 짧은 섹션을 추가하세요.
[!IMPORTANT] 두 단계 모두 필수이며, 두 번째는 형식적인 절차가 아닙니다. 측정 결과: 서버가 연결되어 있어도 저장소 측 지침이 없으면 세션은 볼트를 한 번도 호출하지 않았고, 볼트가 명시적으로 거부했다고 기록한 설계를 그대로 구현했습니다. 지침이 있을 때는 구현을 거부하고 해당 노트를 인용했습니다.
MCP
instructions필드의 금지 사항은 호출하는 세션으로 확실히 전파됩니다. 반면"볼트를 참조하라"는 긍정형 지시는 권고적이며, 더 가까운 정보원이 있으면 건너뜁니다. 서버는 세션을 멈출 수는 있지만, 세션이 찾아보게 만드는 것은 그 프로젝트 자체의 규약뿐입니다.
세션이 얻는 것: search(시맨틱 + 키워드), expand(노트의 링크와 백링크), recall(해당 저장소로 스코프된 지속적 교훈), remember(교훈 기록), record_work(작업 내용 기록), reason(여러 노트에 걸친 판단), health(배선이 정상인지). 여기에 노트를 읽을 수 있는 리소스로 제공합니다.
생각하는 것은 reason 하나입니다. 나머지가 검색이라면, 이것은 두 번째 Claude 세션으로 볼트를 읽고 노트를 가로지르는 판단이 필요한 질문에 답합니다 — 지금 하려는 일이 이 여섯 개의 노트가 결정한 바와 일치하는가? 스스로 먼저 검색을 수행하므로 먼저 검색할 필요가 없습니다. 당신 본인의 CLI 기본 모델로 동작하므로, 볼트는 지금 작업 중인 수준과 같은 수준으로 답합니다. 그리고 어떤 상한도 없습니다 — 당신의 기기에서, 당신의 인증으로 돌아가는 Claude이기 때문입니다. 호출마다 비용·턴 수·모델·실제 소요 시간이 기록됩니다. 답변에는 confidence: inferred가 붙고 그 자체로 메모리에 기록되지 않습니다 — 남길 가치가 있는지는 당신의 세션이 정합니다.
저장소는 폴더 이름으로 식별됩니다. 대개는 맞지만 가끔 틀립니다: api라는 이름의 저장소가 둘이면 하나의 정체성을 공유해 서로의 메모리를 받게 됩니다. 저장소 루트에 .om-project 파일을 두고 다른 이름을 적으면 분리됩니다. health가 어느 저장소로 인식하는지, 그 이름이 어디서 왔는지 알려줍니다.
인식론적 계약이 있는 저장소 간 메모리. 한 저장소에서 배운 교훈은 스코프가 지정된 저장소에만 도달합니다. 도달 범위는 읽을 때 추측되는 것이 아니라 쓸 때 선언되므로, 형제 프로젝트가 다른 프로젝트의 제약을 물려받지 않습니다. 기록되는 모든 것에는 confidence: verified | inferred | unverified, 변동성 있는 사실의 날짜, 그리고 서버 측에서 도출된 출처가 함께 담깁니다 — 세션이 자신이 아닌 프로젝트를 사칭할 수 없습니다. 수정은 덮어쓰기가 아니라 대체로 기록되므로, 저장소는 모순을 쌓아가는 대신 커질수록 더 신뢰할 수 있게 됩니다.
무엇을 제공하는가. 당신의 볼트, 당신의 노트, 당신의 세션입니다. 기본값은 볼트가 이미 자신의 콘텐츠로 선언한 것(user_content_roots)을, 작성한 그대로의 단위로 사용합니다(work/ 전체가 아니라 work/active/). vault-manifest.json의 mcp_exposed_roots를 설정하는 것은 이 볼트가 당신이 공유할 권한이 없는 자료 — 고용주의 기밀 정보나 고객의 데이터 — 를 담고 있을 때뿐입니다. private 태그가 붙은 노트는 제공되지 않으며, 메모리는 자체 스코프를 갖기 때문에 일반 노트로 제공되지 않습니다. 둘 사이를 가로지르는 경우가 하나 있습니다. 캡처의 promoted: 마커가 앵커를 담고 있으면 recall이 brain/의 해당 블록을 제공하므로, 다른 저장소는 처음 작성된 캡처가 아니라 수정된 판을 받습니다. 이 역시 같은 정책의 제약을 받으므로 private이거나 비공개인 노트는 여기서도 거부됩니다. 모든 읽기는 호출한 저장소와 함께 기록됩니다.
[!NOTE] 볼트 자료가 공개 PR에 들어가지 않게 하는 것은 공개 목록이 아니라 계약의 일입니다. 세션은 어차피 볼트를 직접 읽을 수 있습니다. 호출하는 세션에 주입되는 금지 사항이 실측으로 효과가 있는 부분입니다.
📅 일일 워크플로우
아침: /om-standup을 실행합니다. 에이전트가 North Star, 활성 프로젝트, 미완료 작업, 최근 변경사항을 로드합니다. 구조화된 요약과 추천 우선순위를 받습니다.
하루 중: 자연스럽게 이야기하세요. 내린 결정, 발생한 인시던트, 방금 마친 1:1, 기억하고 싶은 성과를 언급하세요. 분류 훅이 에이전트가 각 항목을 올바르게 기록하도록 안내합니다. 더 큰 브레인 덤프를 하려면 /om-dump을 사용하고 한 번에 모든 것을 이야기하세요.
하루 끝: "wrap up"이라고 말하면 에이전트가 /om-wrap-up을 호출합니다 — 노트 검증, 인덱스 업데이트, 링크 확인, 누락된 성과 발견.
주간: /om-weekly를 실행하여 세션 간 종합 분석 — North Star 정렬, 패턴, 누락된 성과, 다음 주 우선순위. /om-vault-audit를 실행하여 고아 노트, 깨진 링크, 오래된 콘텐츠를 점검합니다.
리뷰 시즌: /om-review-brief manager를 실행하면 모든 증거가 이미 링크된 구조화된 리뷰 준비 문서를 받습니다.
🛠️ 명령어
.claude/commands/에 정의되어 있습니다. 모든 Claude Code 세션에서 실행할 수 있습니다.
| 명령어 | 기능 |
|---|---|
/om-standup |
아침 킥오프 — 컨텍스트 로드, 어제 리뷰, 작업 표면화, 우선순위 제안 |
/om-dump |
자유 형식 캡처 — 무엇이든 자연스럽게 이야기하면 올바른 노트로 라우팅 |
/om-wrap-up |
전체 세션 리뷰 — 노트, 인덱스, 링크 검증, 개선사항 제안 |
/om-humanize |
목소리 보정 편집 — Claude가 작성한 텍스트를 본인이 쓴 것처럼 수정 |
/om-weekly |
주간 종합 — 세션 간 패턴, North Star 정렬, 누락된 성과 |
/om-prep-1on1 |
1:1 준비 — 상대방 컨텍스트, 미해결 항목, 제안 안건 로드 |
/om-meeting |
주제별 미팅 준비 — 미해결 항목, 차단 요소, 고려사항 브리핑 |
/om-intake |
미팅 노트 수신함 처리 — work/meetings/의 파일을 분류하고 적절한 노트로 라우팅 |
/om-capture-1on1 |
1:1 미팅 트랜스크립트를 구조화된 볼트 노트로 캡처 |
/om-incident-capture |
Slack/채널의 인시던트를 구조화된 노트로 캡처 |
/om-slack-scan |
Slack 채널/DM을 깊이 스캔하여 증거 수집 |
/om-peer-scan |
동료의 GitHub PR을 깊이 스캔하여 리뷰 준비 |
/om-review-brief |
리뷰 브리프 생성 (매니저 또는 동료 버전) |
/om-self-review |
리뷰 시즌을 위한 자기 평가 작성 — 프로젝트, 역량, 원칙 |
/om-review-peer |
동료 리뷰 작성 — 프로젝트, 원칙, 성과 요약 |
/om-correct |
수정된 사실을 일괄 반영 — 단일 출처에 적용하고, 재진술은 링크로 대체하며, 날짜가 있는 기록은 보존 |
/om-vault-audit |
인덱스, 링크, 고아 노트, 오래된 컨텍스트 감사 |
/om-vault-upgrade |
기존 볼트에서 콘텐츠 가져오기 — 버전 감지, 분류, 마이그레이션 |
/om-project-archive |
완료된 프로젝트를 active/에서 archive/로 이동, 인덱스 업데이트 |
/om-tidy |
자체 유지보수 — 위생 플래그에 따라 완료 노트 아카이브, 클러스터 폴더화, 비대 노트 분할을 수행. 삭제도 커밋도 하지 않음 |
🤖 서브에이전트
격리된 컨텍스트 윈도우에서 실행되는 전문 에이전트입니다. 메인 대화를 오염시키지 않고 무거운 작업을 처리합니다.
| 에이전트 | 용도 | 호출 방법 |
|---|---|---|
brag-spotter |
누락된 성과와 역량 격차 발견 | /om-wrap-up, /om-weekly |
context-loader |
인물, 프로젝트, 개념에 대한 모든 볼트 컨텍스트 로드 | 직접 호출 |
cross-linker |
누락된 위키링크, 고아 노트, 깨진 백링크 발견 | /om-vault-audit |
people-profiler |
Slack 프로필에서 인물 노트를 일괄 생성/업데이트 | /om-incident-capture |
review-prep |
리뷰 기간의 모든 성과 증거 집계 | /om-review-brief |
slack-archaeologist |
전체 Slack 복원 — 모든 메시지, 스레드, 프로필 | /om-incident-capture |
vault-librarian |
심층 볼트 유지보수 — 고아 노트, 깨진 링크, 오래된 노트 | /om-vault-audit |
review-fact-checker |
리뷰 초안의 모든 주장을 볼트 소스와 대조 검증 | /om-self-review, /om-review-peer |
vault-migrator |
소스 볼트에서 콘텐츠 분류, 변환, 마이그레이션 | /om-vault-upgrade |
[!NOTE] 서브에이전트는
.claude/agents/에 정의되어 있습니다. 도메인별 워크플로우를 위해 직접 추가할 수 있습니다.
📊 성과 그래프
볼트는 성과 추적 시스템으로도 활용됩니다:
- 역량 노트(
perf/competencies/)가 조직의 역량 프레임워크를 정의합니다 — 역량별로 하나의 노트 - 작업 노트가
## Related섹션에서 역량에 링크하며, 어떤 역량이 발휘되었는지 주석을 답니다 - 백링크가 자동으로 축적됩니다 — 리뷰 준비는 각 역량 노트의 백링크 패널을 읽는 것으로 충분합니다
- Brag Doc가 분기별 성과를 증거 노트 링크와 함께 집계합니다
- **
/om-peer-scan**이 동료의 GitHub PR을 깊이 스캔하고 구조화된 증거를perf/evidence/에 작성합니다 - **
/om-review-brief**가 모든 것을 집계하여 전체 리뷰 브리프를 생성합니다: Brag 항목, 의사결정, 인시던트, 역량 증거, 1:1 피드백
[!TIP] 시작하려면: 템플릿에서 역량 노트를 만들고, 작업하면서 작업 노트에 역량을 링크하세요. 그래프가 나머지를 처리합니다.
📋 Bases
bases/ 폴더에는 노트의 프론트매터 속성을 쿼리하는 데이터베이스 뷰가 있습니다. 노트가 변경되면 자동으로 업데이트됩니다.
| Base | 표시 내용 |
|---|---|
| Work Dashboard | 분기별 필터링, 상태별 그룹화된 활성 프로젝트 — 14일 이상 손대지 않은 활성 노트를 보여주는 Stale Actives 뷰 포함 |
| Recently Touched | 실제 수정 시각 순의 모든 노트 — "최근 무엇을 작업했나"에 대한 정확한 답 (살아있는 노트에서 파일명 날짜는 믿을 수 없음) |
| Incidents | 심각도와 날짜순으로 정렬된 모든 인시던트 |
| People Directory | org/people/의 모든 인물과 역할, 팀 정보 |
| 1:1 History | 인물과 날짜로 정렬 가능한 모든 1:1 노트 |
| Review Evidence | 인물과 주기별로 그룹화된 PR 스캔 및 증거 |
| Competency Map | 백링크 기반 증거 수를 포함한 역량 목록 |
| Templates | 모든 템플릿에 대한 빠른 접근 |
Home.md가 이 뷰들을 임베드하여 볼트의 대시보드 역할을 합니다.
📁 볼트 구조
Home.md 볼트 진입점 — 임베드된 Base 뷰, 바로가기 링크
CLAUDE.md 운영 매뉴얼 — 에이전트가 매 세션마다 읽음
AGENTS.md 멀티에이전트 가이드 — Codex, Cursor, Windsurf 등
GEMINI.md 멀티에이전트 가이드 — Gemini CLI
vault-manifest.json 템플릿 메타데이터 — 버전, 구조, 스키마
.shardmindignore `shardmind install`에서 제외되는 파일 (CONTRIBUTING, 번역, 마케팅 미디어)
CHANGELOG.md 버전 히스토리
CONTRIBUTING.md 템플릿 개발 체크리스트
README.md 제품 문서
LICENSE MIT 라이선스
bases/ 동적 데이터베이스 뷰 (Work Dashboard, Incidents, People 등)
work/
active/ 현재 프로젝트 (한 번에 1–3개 파일)
archive/YYYY/ 완료된 작업, 연도별 정리
incidents/ 인시던트 문서 (메인 노트 + RCA + 심층 분석)
1-1/ 1:1 미팅 노트 — <Person> YYYY-MM-DD.md 형식
Index.md 모든 작업의 Map of Content
org/
people/ 인물별 노트 — 역할, 팀, 관계, 주요 순간
teams/ 팀별 노트 — 구성원, 범위, 상호작용
People & Context.md 조직 지식의 MOC
perf/
Brag Doc.md 증거에 링크된 성과 기록
brag/ 분기별 Brag 노트 (분기당 하나)
competencies/ 역량별 노트 (링크 대상)
evidence/ PR 심층 스캔, 리뷰용 데이터 추출
<cycle>/ 리뷰 주기별 브리프 및 산출물
brain/
North Star.md 목표와 집중 영역 — 매 세션마다 읽음
Memories.md 메모리 토픽 인덱스
Key Decisions.md 중요한 의사결정과 근거
Patterns.md 작업 전반에서 관찰된 반복 패턴
Gotchas.md 잘못된 것들과 그 이유
Skills.md 커스텀 워크플로우와 슬래시 명령어
reference/ 코드베이스 지식, 아키텍처 맵, 플로우 문서
thinking/ 초안을 위한 스크래치패드 — 결과 정리 후 삭제
templates/ YAML 프론트매터가 포함된 Obsidian 템플릿
.claude/
commands/ 18개 슬래시 명령어
agents/ 9개 서브에이전트
scripts/ 훅 스크립트 + charcount.ts 유틸리티
skills/ Obsidian + QMD 스킬, obsidian-mind mod
settings.json 5개 훅 설정
.scripts/ 볼트 수준 도구 — QMD 부트스트랩 (새 클론에서 한 번 실행)
.shardmind/ ShardMind 사이드카 — `shardmind install`로 설치한 경우에만 사용
shard.yaml 매니페스트 (이름, 버전, 모듈, 훅)
shard-schema.yaml 마법사 값 + 모듈 게이팅
hooks/ bootstrap (git 초기화 + QMD), personalize (North Star), post-update
[!NOTE]
.shardmind/는 추가 기능이며, 필수 요소가 아닙니다. 클론하여 열기만 하는 볼트는 이 파일을 읽지 않으며,shardmindCLI만 사용합니다. 삭제해도 볼트는 계속 작동합니다. v6 레이아웃 계약은 shardmind/docs/SHARD-LAYOUT.md를 참조하세요.
📝 템플릿
YAML 프론트매터가 포함된 템플릿으로, 각각 점진적 공개를 위한 description 필드를 포함합니다:
- Work Note — 날짜, 설명, 프로젝트, 상태, 분기, 태그
- Decision Record — 날짜, 설명, 상태 (proposed/accepted/deprecated), 담당자, 맥락
- Thinking Note — 날짜, 설명, 맥락, 태그 (스크래치패드 — 정리 후 삭제)
- Competency Note — 날짜, 설명, 현재 레벨, 목표 레벨, 숙련도 표
- 1:1 Note — 날짜, 상대방, 핵심 요점, 액션 아이템, 인용, 주시 사항
- Incident Note — 날짜, 티켓, 심각도, 역할, 타임라인, 근본 원인, 영향
🔧 포함 항목
🧩 Obsidian 스킬
kepano/obsidian-skills가 .claude/skills/에 사전 설치되어 있습니다:
- obsidian-markdown — Obsidian 특화 마크다운 (위키링크, 임베드, 콜아웃, 속성)
- obsidian-cli — 볼트 운영을 위한 CLI 명령어
- obsidian-bases — 데이터베이스 스타일
.base파일 - json-canvas — 시각적
.canvas파일 생성 - defuddle — 웹 페이지를 마크다운으로 추출
🔍 QMD 스킬
.claude/skills/qmd/에 있는 커스텀 스킬로, Claude가 QMD 시맨틱 검색을 능동적으로 사용하도록 합니다 — 파일을 읽기 전, 노트 생성 전(중복 확인), 노트 생성 후(링크할 관련 콘텐츠 탐색).
🎨 커스터마이즈
이것은 출발점입니다. 자신의 업무 방식에 맞게 조정하세요:
| 항목 | 위치 |
|---|---|
| 목표 | brain/North Star.md — 모든 세션의 기준 |
| 조직 | org/ — 매니저, 팀, 핵심 협력자 추가 |
| 역량 | perf/competencies/ — 조직의 프레임워크에 맞추기 |
| 도구 | .claude/commands/ — GitHub 조직, Slack 워크스페이스에 맞게 편집 |
| 규칙 | CLAUDE.md — 운영 매뉴얼, 진행하면서 발전시키기 |
| 도메인 | 폴더 추가, .claude/agents/에 서브에이전트 추가, .claude/scripts/에 분류 규칙 추가 |
[!IMPORTANT]
CLAUDE.md는 운영 매뉴얼입니다. 규칙을 변경하면 이 파일을 업데이트하세요 — 에이전트가 매 세션마다 읽습니다.
🔄 업그레이드
에이전트에게 요청하기
가장 간단한 방법 — 에이전트에게 말하세요:
이 볼트를 최신 obsidian-mind로 업데이트해줘 https://github.com/breferrari/obsidian-mind
에이전트가 최신 변경사항을 가져오고, 충돌을 해결하고, 인프라 파일을 업데이트합니다. Claude Code, Codex CLI, Gemini CLI 모두에서 작동합니다.
기존 클론 업데이트
리포지토리를 직접 클론한 경우:
cd your-vault
git pull origin main
새 파일(AGENTS.md, GEMINI.md, .codex/, .gemini/)이 자동으로 추가되고 훅 스크립트도 업데이트됩니다.
포크 업데이트
리포지토리를 포크한 경우:
git remote add upstream https://github.com/breferrari/obsidian-mind.git
git fetch upstream
git merge upstream/main
커스터마이징한 파일(일반적으로 CLAUDE.md, brain/ 노트)의 충돌을 해결하세요. 인프라 파일(.claude/scripts/, .codex/, .gemini/)은 깔끔하게 병합됩니다.
기존 클론을 ShardMind로 채택 (v5.x → v6)
이미 obsidian-mind를 클론했고 커스터마이징을 잃지 않고 마법사, 선택적 모듈, 3-way 머지 업그레이드를 원하시나요? shardmind adopt가 기존 볼트를 관리되는 v6 설치로 조정해줍니다 — 편집한 모든 바이트를 유지하면서 .shardmind/ 사이드카와 shard-values.yaml만 추가합니다:
npm install -g shardmind
shardmind adopt github:breferrari/obsidian-mind
2-way diff UI가 로컬 변경 사항을 안내하고, 파일별로 무엇을 유지할지 묻고, 엔진 메타데이터를 작성합니다. 결과: 기존 콘텐츠가 그대로 유지된 v6 관리 볼트, 이후로는 shardmind update를 사용할 수 있습니다. 다시 클론할 필요 없음.
이전 볼트에서 마이그레이션 (또는 다른 볼트)
v5 이전 버전의 obsidian-mind를 사용 중이거나, 완전히 다른 Obsidian 볼트에서 마이그레이션하시나요? /om-vault-upgrade 명령어가 최신 템플릿으로 콘텐츠를 마이그레이션합니다:
# 1. 최신 obsidian-mind 클론
git clone https://github.com/breferrari/obsidian-mind.git ~/new-vault
# 2. 에이전트로 열기
cd ~/new-vault && claude # 또는 codex, gemini
# 3. 이전 볼트를 지정하여 업그레이드 실행
/om-vault-upgrade ~/my-old-vault
에이전트가 수행하는 작업:
- 감지 — 볼트 버전 확인 (v1–v3.x, 또는 obsidian-mind가 아닌 볼트 식별)
- 인벤토리 — 모든 파일을 사용자 콘텐츠, 스캐폴드, 인프라, 미분류로 분류
- 마이그레이션 계획 제시 — 복사, 변환, 건너뛸 항목을 정확히 보여줌
- 승인 후 실행 — 프론트매터 변환, 위키링크 수정, 인덱스 재구축
- 검증 — 고아 노트, 깨진 링크, 누락된 프론트매터 확인
기존 볼트는 절대 수정되지 않습니다. --dry-run을 사용하면 실행 없이 계획만 미리 볼 수 있습니다.
[!NOTE] obsidian-mind뿐만 아니라 모든 Obsidian 볼트에서 작동합니다. obsidian-mind가 아닌 볼트의 경우, 에이전트가 각 노트를 읽고 의미적으로 분류합니다 — 작업 노트, 인물, 인시던트, 1:1, 의사결정을 올바른 폴더로 라우팅합니다.
🗺️ 로드맵
이슈와 버그 보고를 환영합니다. 코드 기여는 할당제로 진행됩니다. 이슈에 댓글로 작업 의사를 밝히고, 할당된 뒤에 PR을 열어 주세요. 본인에게 할당되지 않은 이슈에 대한 PR은 리뷰 없이 닫힙니다. 자세한 내용은 CONTRIBUTING.md를 참고하세요.
🙏 디자인 영향
- kepano/obsidian-skills — 공식 Obsidian 에이전트 스킬
- James Bedford — 볼트 구조 철학, AI 생성 콘텐츠 분리
- arscontexta — description 필드를 통한 점진적 공개, 세션 훅
👤 저자
Brenno Ferrari 제작 — 베를린의 시니어 iOS 엔지니어, Claude Code로 개발자 도구를 구축하고 있습니다.
📄 라이선스
MIT