개요

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로 한 번 등록하면 모든 디렉터리에서 쓸 수 있다.

도구역할
searchQMD 의미+키워드 검색(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에서 검토했다.