AI 코딩 에이전트에 영구 메모리를 제공하는 Obsidian 볼트

Obsidian 볼트로, AI 코딩 에이전트에 영구적인 기억을 부여합니다. Claude Code를 위해 구축되었으며, Codex CLI 및 Gemini CLI용 작동 중인 후크(hooks)를 갖추고 있습니다. 세션을 시작하고 하루에 대해 이야기하면, 에이전트가 나머지 모든 것—노트, 링크, 인덱스, 성능 추적—을 처리합니다. 모든 대화는 이전의 내용을 기반으로 쌓아갑니다.

AI 코딩 에이전트는 강력하지만, 기억하지 못합니다. 매 세션은 0부터 시작하며, 사용자의 목표, 팀, 패턴, 성과에 대한 맥락 정보가 없습니다. 같은 내용을 계속해서 다시 설명해야 합니다. 몇 대화 전에 내린 결정들을 잊게 됩니다. 지식은 결코 축적되지 않습니다.

당신의 에이전트에게 두뇌를 주세요.

You: "start session"
Agent: *North Star를 읽고, 활성 프로젝트를 확인하며, 최근 메모리를 스캔합니다*
Agent: "프로젝트 Alpha를 진행 중이며, BE 계약에 막혀 있습니다.
...

Claude Code(완전 지원), Codex CLI, 그리고 Gemini CLI와 함께 작동합니다. 동일한 후크, 동일한 명령어, 동일한 볼트를 사용합니다.

shardmind install를 통해 설치하거나

git clone을 사용할 수 있습니다.

어느 쪽이든 동일한 볼트가 생성됩니다.

아침 시작:

/om-standup
# → North Star, 활성 프로젝트, 열린 작업, 최근 git 변경 사항을 로드합니다
# → "활성 프로젝트가 2개 있습니다. 인증 리팩토링은 API 계약에 막혀 있습니다.
...

회의 후 브레인 덤프:

/om-dump Sarah와 1:1을 방금 했습니다. 그녀는 인증 작업에는 만족하지만, 출시 전에 오류 모니터링을 추가하기를 원합니다. 또한 Tom이 캐시 마이그레이션은 2분기로 연기되었다고 언급했습니다. 우리는 먼저 API 계약에 집중하기로 결정했습니다.
...

→ 회의 맥락으로 org/people/Sarah Chen.md 업데이트
→ 주요 시사점을 담아 work/1-1/Sarah 2026-03-26.md 생성
→ 의사결정 기록(Decision Record): "Redis 마이그레이션 2분기로 연기"
...

인시던트 대응:

/om-incident-capture https://slack.com/archives/C0INCIDENT/p123456
# → slack-archaeologist가 모든 메시지, 스레드, 프로필을 읽습니다
# → people-profiler가 관련된 새로운 사람들을 위한 메모리를 생성합니다
...

하루 마무리:

You: "wrap up"
# → 모든 노트에 링크가 있는지 확인합니다
# → 인덱스를 업데이트합니다
...

npm install -g shardmind
mkdir my-vault && cd my-vault
shardmind install github:breferrari/obsidian-mind

shardmind install은 현재 디렉터리에 내용을 작성하므로, 먼저 새 폴더를 만들고 진입해야 합니다. 마법사(wizard)가 사용자 이름, 조직, 볼트 목적, 포함할 에이전트, QMD 활성화 여부를 수집합니다. 이후 ShardMind는 git을 초기화하고, 선택적으로 QMD를 부트스트랩하며, 답변을 바탕으로 brain/North Star.md 파일을 개인화합니다. 그 다음:

• 설치된 폴더를 Obsidian 볼트로 엽니다. 설정(Settings) → 일반(General)에서 Obsidian CLI를 활성화합니다 (Obsidian 1.12 이상 필요). 볼트 디렉터리에서 에이전트를 실행합니다: claude 또는 codex, gemini
• 업무에 대해 이야기하기 시작합니다.

ShardMind는 Obsidian 볼트 템플릿을 위한 패키지 관리자입니다. 이 설치 과정은 마법사, 선택적 모듈(사용하지 않는 것은 건너뛰기), 그리고 3방향 병합 업그레이드를 구동하는 .shardmind/ 사이드카를 추가합니다. 모든 값이 기본값일 때의 설치는 git clone과 바이트가 동일하며 — 클론-UX는 정확하게 유지됩니다. 설치된 볼트에서 .shardmind/와 shard-values.yaml을 삭제해도 계속 작동합니다: ShardMind는 지지하는(load-bearing) 것이 아니라 추가적인(additive) 기능입니다.

git clone https://github.com/breferrari/obsidian-mind.git

또는 GitHub 템플릿으로 사용합니다. 마법사를 건너뛰고, 기본 템플릿을 받습니다. 그런 다음 위의 4단계를 거치면서, 목표를 담아 brain/North Star.md 파일을 채웁니다 (ShardMind 마법사가 이 작업을 대신 수행해 줍니다).

QMD는 에이전트의 검색 지능 대부분이 나오는 곳입니다. 엄밀히 말하면 선택 사항이며 — 볼트는 grep + Obsidian CLI로 폴백(fallback)합니다 — 하지만 사용 경험은 QMD를 사용할 때 의미 있게 더 좋습니다:

시맨틱 리콜(Semantic recall). 노트가

그리고 친구들은 QMD를 먼저 참고하고, 그 다음에 grep을 사용합니다.MCP를 통한 네이티브 에이전트 도구(Native agent tools via MCP). mcp.json에 모델 컨텍스트 프로토콜(Model Context Protocol) 서버로 등록됩니다.

— QMD가 설치되면, Read와 Edit 옆에 에이전트의 도구 메뉴에 mcp__qmd__query, mcp__qmd__get, 그리고 mcp__qmd__multi_get이 나타납니다. 서브에이전트(Subagents), 슬래시 명령어(/ commands), 그리고 메인 대화 모두 동일한 타입 계약(typed contract)을 호출합니다. 나중에 다른 MCP 인식 도구(데이터베이스, 티케팅 시스템, 캘린더 등)를 추가해도 같은 방식으로 플러그인됩니다.

npm install -g @tobilu/qmd
node --experimental-strip-types .scripts/qmd-bootstrap.ts

부트스트랩(bootstrap)은 반복 실행이 가능합니다(idempotent). 이 과정은 vault-manifest.json에서 qmd_index 필드가 설정되어 있으면 해당 볼트의 인덱스 이름을, 그렇지 않으면 볼트 폴더 이름에 슬러기화(slugified)된 값을 사용하여 결정합니다 — 읽어와서 qmd_context로 등록하고, 컬렉션을 첨부하며, 인덱스와 임베딩을 구축합니다. SessionStart 훅과 .mcp.json 래퍼 모두 동일한 매니페스트 필드를 읽기 때문에 CLI 쿼리, MCP 서버, 그리고 재인덱싱(re-index) 모두 동일한 이름의 SQLite 스토어 범위 내에서 작동합니다. 이는 해당 볼트를 같은 기기의 다른 QMD 사용 볼트로부터 격리시킵니다.

만약 다른 인덱스 이름을 사용하고 싶다면 (예를 들어, 공유 워크스테이션에서 엔지니어별로 볼트를 분리하는 경우), 부트스트랩을 실행하기 전에 vault-manifest.json의 qmd_index를 수정하세요. 스토어가 채워진 후에는 항상 CLI에 --index <이름>을 전달해야 합니다:

qmd --index obsidian-mind query "what did we decide about caching"
qmd --index obsidian-mind update # 대량 편집(bulk edits) 후
qmd --index obsidian-mind embed # 새로운 노트가 많이 추가된 후

QMD는 세 개의 작은 모델을 로컬에서 실행하므로 API 키를 설정할 필요도 없고, 쿼리당 비용이 들지 않으며, 오프라인에서도 작동합니다:

사용 시점에 다운로드되며 캐시됩니다. QMD는 GPU가 감지되면 해당 장치에 오프로드합니다 — 독립형 카드에서는 CUDA, Apple Silicon에서는 Metal을 사용하며, 그렇지 않으면 CPU로 폴백(fallback)합니다. qmd doctor를 사용하여 현재 시스템이 무엇을 하고 있는지 확인해 보세요.

세 가지 CLI 동사들은 이 스택에 매핑되며, 비용 효율성이 낮은 순서대로 다음과 같습니다: qmd search는 어떤 모델도 사용하지 않는 BM25 키워드 검색이며, qmd vsearch는 벡터 전용이고, qmd query는 전체 하이브리드 방식입니다. 더 큰 다운로드를 피하고 싶다면, search만으로도 실제로 유용합니다.

om 서버는 어휘적(lexical) 및 벡터 서브쿼리를 보내기 때문에, 검색은 해당 노트가 질문과 키워드를 공유하지 않더라도 답변하는 노트를 찾을 수 있습니다. 알아두면 좋은 실질적인 결과들이 있습니다:

읽기는 비용이 많이 드는 쪽이고, 쓰기는 그렇지 않습니다. 쿼리가 검색하기 전에 로컬에서 임베딩(embeds)되어야 하므로, 쿼리를 사용한 recall은 몇 초가 걸리는 반면, 쿼리 없이 recall은 거의 즉각적입니다. 노트에 대한 search는 빠릅니다 — 비용이 드는 것은 벡터 단계입니다.메모리를 작성하는 것이 모델을 기다리지 않습니다. 인덱스 업데이트는 동기식(synchronous)이므로 새로운 메모리는 즉시 검색 가능하며, 그 벡터를 생성하는 작업은 백그라운드에서 이루어집니다. 왜냐하면 그것은 해당 노트가 순위 매겨지는 것에는 영향을 주지만, 발견되는지 여부에는 영향을 미치지 않기 때문입니다.인덱스가 없어도 문제없습니다. QMD 없이도 서버는 어휘적 일치(lexical matching)로 폴백합니다. 순서가 나빠질 뿐, 아무것도 사라지지는 않습니다.

참고
QMD가 설치되어 있지 않아도 모든 것이 작동합니다 — 에이전트는 grep과 Obsidian CLI로 폴백하며, MCP 서버 항목은 무해한 경고와 함께 건너뜁니다.

• Obsidian 1.12 이상 (CLI 지원용)
• AI 코딩 에이전트: Claude Code(완벽 지원), Codex CLI 또는 Gemini CLI
• Node 22+ LTS (훅 스크립트용 — 일반적으로 Claude Code / Codex / Gemini CLI와 함께 이미 설치됨)
• Git (버전 기록용)
• QMD (선택 사항, 의미론적 검색용)

Node 플래그에 대한 참고사항. 훅 스크립트는 Node의 --experimental-strip-types를 통해 TypeScript를 직접 실행합니다.

플래그는 Node 22.6+(2024년 8월)에서 안정화되었으며 Node 23.6+의 기본 동작 방식입니다. 이 플래그는 실험적인 것으로 표시되어 있지만, 22 LTS와 24 LTS 전반에 걸쳐 변경되지 않았습니다. 만약 향후 Node 릴리스에서 이를 폐기하거나 이름을 변경한다면, .claude/settings.json, .codex/hooks.json, 그리고 .gemini/settings.json의 후크 명령어는 한 줄 업데이트가 필요합니다.

절차적 코드가 환경을 소유하고, 에이전트가 콘텐츠를 소유합니다. .claude/scripts/에 있는 후크는 분류(classification), 검증(validation), 인덱싱(indexing), 그리고 라이프사이클 주입(lifecycle injection)을 처리합니다. 이는 결정론적이고 테스트 가능하며 모든 에이전트에게 동일하게 실행됩니다. 메모 작성, 파일링, 링크 연결, 보고서 초안 작성 등은 판단(judgments)의 영역이며, 이 부분은 에이전트가 담당합니다. 두 부분이 작은 핸드오프(handoffs)에서 만납니다 (후크는 컨텍스트를 주입하고, 에이전트는 볼트를 읽습니다). 따라서 어느 쪽도 상대방의 역할을 할 필요가 없습니다.

폴더는 목적별로 그룹화되고, 링크는 의미별로 그룹화됩니다. 노트는 하나의 폴더(자신의 홈)에 존재하지만 여러 노트와 연결되어 있습니다(그것의 컨텍스트). 사용자의 에이전트는 이 그래프를 유지합니다. 작업 노트를 사람, 결정, 역량과 자동으로 연결하는 것입니다. 검토 시즌이 오면, 각 역량 노트의 백링크가 이미 증거 추적 경로(evidence trail)가 되어 있습니다. 링크가 없는 노트는 버그입니다.

**볼트 우선 메모리(Vault-first memory)**는 세션과 기기를 가로질러 컨텍스트를 유지합니다. 모든 영구적인 지식은 brain/에 존재하며, 여기에는 주제 노트(git으로 추적되고, Obsidian에서 탐색 가능하며, 연결됨)가 포함됩니다. Claude Code의 MEMORY.md (~/.claude/)는 볼트 위치를 가리키는 자동 로드 인덱스이며, 그 자체가 저장소는 아닙니다. 이는 메모리가 기기 변경을 생존하고 그래프의 일부임을 의미합니다.

세션은 설계된 라이프사이클을 갖습니다. SessionStart 후크는 사용자의 북극성 목표(North Star goals), 활성 프로젝트, 최근 변경 사항, 열려 있는 작업, 그리고 전체 볼트 파일 목록을 자동으로 주입합니다. 따라서 에이전트는 빈 상태가 아닌 컨텍스트를 가지고 모든 세션을 시작합니다. 마지막에는

운영 매뉴얼(operating manual)이 그 사이의 모든 것을 관장합니다. 즉, 무엇을 어디에 보관할지, 어떻게 연결할지, 언제 노트를 분리할지, 결정과 사건들을 어떻게 처리할지를 말입니다.

다섯 가지 생애 주기 후크(lifecycle hooks)가 라우팅을 자동으로 처리합니다:

팁

사용자는 말하기만 하면 됩니다. 후크가 라우팅을 처리합니다.

Claude Code 2.1.287 이상 버전에서는 볼트 또한 모드(mod)를 함께 제공합니다: .claude/skills/obsidian-mind/

이는 Claude Code 내부에서 실행되는 플러그인이며, 볼트 자체의 후크 스크립트를 실행하고 오직 그 출력물이 세션에 도달하는 방식만 변경합니다:

세션 컨텍스트는 지침 파일(instruction file) 형태로 도착하며, CLAUDE.md가 하는 방식과 같습니다. 이는 압축 후 전체적으로 재읽히고 /clear될 때 (후크 출력물로서 포인터로 축소됨), 일반 목적의 서브 에이전트에게 도달하며 (후크 출력물이 절대 그렇게 하지 않음), Claude Code의 10,000자 후크 제한에 의해 잘리지 않습니다. 이 예산은 vault-manifest.json의 eager_layer_instruction_budget_bytes입니다. 열려 있는 작업(open tasks)과 같이 절대 줄어들지 않는 섹션도 여전히 이를 초과할 수 있습니다. /memory는 이를 .claude/session-context.md로 목록화합니다.

Stop 보고서는 답변 아래 한 줄이 됩니다. 발견 사항이 변경되면 obsidian-mind: vault check: …가 표시됩니다.

Claude의 답변 아래에, 그리고 Claude는 다음 메시지와 함께 전체 보고서를 보게 되며, 이는 사용자에게는 보이지 않습니다. '긴급(urgent)'으로 표시된 발견 사항은 대신 즉시 Claude의 주의를 끌고, 전송하는 메시지당 한 번만 가능합니다 (두 번째 것은 보고서 안에 대기합니다). 이 템플릿 자체의 보고서는 그런 기능이 없습니다.

모드가 처리하는 각 이벤트에 대해, 해당 모드는 일치하는 후크(hook)에게 작동을 중단하라고 지시합니다. 모드가 로드되지 않는 곳에서는 후크가 이전과 정확하게 실행됩니다: Codex 및 Gemini, 구형 Claude Code, 볼트 하위 폴더에서 시작된 세션 (볼트 루트에서 실행하거나 /cd
거기서 그리고 /clear)
또는 신뢰하지 않은 폴더입니다. 이 기능은 사용자가 볼트에 대한 Claude Code의 신뢰 프롬프트를 수락한 후에만 로드됩니다.

모드는 사용자 권한으로 실행되는 격리되지 않은(unsandboxed) 코드이므로, 폴더를 신뢰하기 전에 어떤 작업을 하는지 확인하세요: claude plugin validate .claude/skills/obsidian-mind