개요
breferrari/obsidian-mind는 AI 코딩 에이전트의 기억 저장소로 쓰는 Obsidian 볼트 템플릿이다(MIT, TypeScript, ⭐4.9k, 포크 560). 2026-10-09 기준 최신 버전은 v9.1.0(2026-10-06)이다. 일본 큐레이션 계정 @trendtech33566이 “매번 AI에게 ‘지난번 이어서’를 설명하는 사람에게”라며 소개했다. 세션을 열면 목표·진행 중 프로젝트·열린 할 일을 에이전트가 먼저 읽고, 대화 내용은 알아서 노트·링크·인덱스로 정리된다. Claude Code는 완전 지원, Codex CLI와 Gemini CLI는 같은 훅과 명령으로 동작한다.
설계 원칙
- 절차는 코드가, 내용은 에이전트가. 분류·검증·인덱싱·세션 수명주기는
.claude/scripts/의 결정적 훅이 맡는다. 노트 작성·배치·링크 판단은 에이전트 몫이다. - 폴더는 용도, 링크는 의미. 노트는 한 폴더에 살고 여러 노트에 링크된다. 링크 없는 노트는 버그로 본다.
- 볼트 우선 기억. 오래 남길 지식은
brain/노트에 두고, Claude Code의MEMORY.md는 볼트 위치를 가리키는 색인으로만 쓴다. 그래서 기기를 바꿔도 기억이 남는다.
훅 5종
| 훅 | 시점 | 하는 일 |
|---|---|---|
| SessionStart | 시작·재개 | QMD 재색인, North Star 목표·진행 작업·최근 변경·할 일·파일 목록 주입(바이트 예산 안에서) |
| UserPromptSubmit | 매 메시지 | 결정·장애·성과·1:1·사람 등으로 분류해 저장 위치 힌트 주입 |
| PostToolUse | .md 작성 후 | frontmatter·위키링크 검증, 너무 큰 노트 경고 |
| PreCompact | 컨텍스트 압축 전 | 세션 기록을 thinking/session-logs/에 백업 |
| Stop | 매 응답 후 | 볼트 위생 점검 결과를 다음 메시지에 전달 |
Claude Code 2.1.287 이상에서는 같은 훅을 mod(Claude Code 안에서 도는 플러그인)로도 실행한다. 세션 컨텍스트를 훅 출력 대신 지침 파일로 넣어 10,000자 훅 출력 한도와 압축 후 손실을 피한다.
om MCP 서버 — 다른 저장소에서 볼트 쓰기
볼트 밖의 코딩 세션에서도 볼트를 쓰게 해 주는 MCP 서버다. claude mcp add --scope user om node <볼트>/.claude/scripts/om-mcp.mjs로 한 번 등록하면 모든 디렉터리에서 쓸 수 있다.
| 도구 | 역할 |
|---|---|
search | QMD 의미+키워드 검색(QMD가 없으면 키워드 매칭으로 대체) |
expand | 노트의 링크·백링크 |
recall / remember | 저장소별로 범위를 정한 짧은 교훈 읽기·쓰기. confidence: verified·inferred·unverified를 반드시 붙인다 |
record_work | 그 저장소에서 한 작업·결정·검증을 볼트에 기록 |
reason | 두 번째 Claude 세션이 여러 노트를 읽고 판단이 필요한 질문에 답함 |
health | 연결 상태 점검 |
remember는 볼트 안에서 호출하면 거부된다. 그래서 기억은 항상 바깥 저장소에서만 들어온다. 저장소는 폴더 이름으로 구분하며, 이름이 겹치면 .om-project 파일로 나눈다. 기억은 memory_root(기본 memories/)에, 작업 기록은 주로 projects/<이름>/나 inbox/에, 읽기 감사 로그는 .claude/om-mcp-audit.jsonl에 쌓인다.
README가 강조하는 것은 서버 등록만으로는 부족하다는 점이다. 작성자가 측정해 보니 서버만 연결하고 해당 저장소의 CLAUDE.md에 지시를 넣지 않았을 때, 세션은 볼트를 한 번도 호출하지 않았고 볼트에 “명시적으로 기각”이라고 기록된 설계를 그대로 구현했다. 지시를 넣자 구현을 거부하고 해당 노트를 인용했다. 작성자의 결론은 두 가지다.
- MCP
instructions의 금지는 호출 세션에 잘 전달되지만, “볼트를 참고하라”는 권유는 더 가까운 정보원이 있으면 건너뛰어진다. - 참고 시점은 작업 시작이 아니라 산출물에 묶어야 한다. 구현 전에 쓰는 계획·설계 메모에 “기록된 결정 / 반대 근거 / 기록 없음”을 적게 하라는 것이다. 트리거는 “저장 형식·ID 의미·CLI 표면”처럼 구체적인 명사 3~5개로 쓴다.
토큰 예산과 검색
- 볼트 전체를 컨텍스트에 넣지 않는다. 세션 시작 때는 North Star 발췌·git 요약·할 일·파일 목록만 넣고, 바이트 예산(
vault-manifest.json의eager_layer_budget_bytes, 기본 9,100)과 크기 측정값을 함께 붙인다. 재개·압축 시에는 바뀌는 부분만 다시 넣는다. - QMD는 로컬 모델 3개(
embeddinggemma-300M, 쿼리 확장 1.7B,Qwen3-Reranker-0.6B)를 쓴다..mcp.json에 MCP 서버로 등록되어 있어 서브에이전트도 같은 검색 도구를 쓴다. - v9.0(2026-10-03)부터는 Claude Code mod가 Stop 점검 결과를 답변 아래 한 줄로 보여 주고, 전체 보고는 다음 메시지에 에이전트에게 전달한다.
명령과 서브에이전트
- 명령 20개 안팎:
/om-standup(아침 컨텍스트 로드),/om-dump(생각나는 대로 말하면 알맞은 노트로 분배),/om-wrap-up(세션 정리),/om-weekly,/om-incident-capture(Slack 장애 스레드 재구성),/om-review-brief·/om-self-review(성과 평가 준비),/om-tidy,/om-vault-audit등. - 서브에이전트 9개:
brag-spotter,cross-linker,slack-archaeologist,people-profiler,review-fact-checker,vault-librarian등. - 볼트 구조는
work/(프로젝트·장애·1:1),org/(사람·팀),perf/(성과 기록·역량),brain/(목표·결정·패턴·주의점)로 나뉜다. 직장인의 업무 기록과 성과 평가 준비에 맞춘 구성이다.
설치
npm install -g shardmind
mkdir my-vault && cd my-vault
shardmind install github:breferrari/obsidian-mind그냥 git clone해도 된다. 이미 clone한 볼트는 shardmind adopt github:breferrari/obsidian-mind로 수정 내용을 지키면서 ShardMind 관리(3-way merge 업그레이드)로 바꿀 수 있고, 다른 볼트의 내용은 /om-vault-upgrade <옛 볼트>로 옮긴다(원본은 건드리지 않음). Obsidian 1.12 이상(CLI 활성화), Node 22 이상이 필요하고 QMD는 선택이다.
이 위키와 비교
이 볼트처럼 “에이전트가 관리하는 마크다운 지식 저장소”라는 점은 같다. 다만 obsidian-mind는 개인 업무 기억(사람·회의·성과)에, LLM Wiki는 출처 기반 지식 정리에 초점이 있다. 배경은 2026-07-11-llm-wikis-and-how-to-give-your-agents-memory, 비슷한 에이전트 기억 도구는 2026-04-13-claude-mem 참고. 이 볼트에 적용할 수 있는지는 2026-10-09-obsidian-mind-vault-applicability에서 검토했다.