PRODUCTS

볼트를 검색하고 노트를 고치는 옵시디언 AI 사이드바 ‘Agent LLMs’

teinam 2026-11-14updated 11-14 7 MIN

옵시디언(Obsidian) 사이드바에서 AI와 대화하면서 볼트(vault, 옵시디언이 노트를 보관하는 폴더)를 검색하고 노트를 만들고 고치는 플러그인 ‘Agent LLMs’를 소개합니다. 모델은 AWS Bedrock, Google Gemini, OpenAI, Ollama 네 백엔드 가운데 골라 쓰고 PC와 휴대폰·태블릿에서 모두 동작합니다. 옵시디언 커뮤니티 플러그인 목록에 올라 있고 코드는 GitHub에 MIT 라이선스로 공개했습니다. 이 글은 0.8.0 기준입니다.

무엇을 하는 플러그인인가요

영역	하는 일
채팅	스트리밍 응답, 파일 첨부, 대화 저장·검색·내보내기
볼트 검색	임베딩 검색에 노트 링크 순회와 키워드 검색을 합친 Graph RAG
노트 작업	AI가 노트를 읽고 만들고 고치고 옮기고 지움, 변경 되돌리기
Second Brain	기존 노트를 바탕으로 위키 노트를 쓰고 관리하는 선택 기능
정리 도구	일일 할 일, P.A.R.A 폴더 정리, 웹 클리퍼, 템플릿, 태그 생성
MCP	외부 MCP 서버의 도구를 채팅에서 사용 (PC 전용)

모델은 답만 하지 않고 도구(모델이 호출하는 기능 단위)를 호출해 일을 합니다. 내장 도구는 21개입니다. 볼트 검색, 노트 읽기·생성·편집·이어 쓰기, 파일 목록·이동·삭제, 템플릿 같은 기본 도구가 13개이고 Second Brain 도구가 8개입니다. 요청 하나에서 모델이 도구를 부르고 결과를 받는 과정은 최대 10번까지 되풀이됩니다.

설치와 백엔드 설정

옵시디언 1.13.2 이상이 필요합니다. 옵시디언 설정의 커뮤니티 플러그인 탐색 화면에서 ‘Agent LLMs’를 찾아 설치하고 활성화합니다. 릴리스에서 main.js, manifest.json, styles.css를 받아 볼트의 .obsidian/plugins/agent-llms/ 폴더에 넣어도 됩니다.

설정 → Agent LLMs → AI 백엔드에서 백엔드를 고릅니다.
그 백엔드의 자격 증명을 넣습니다.
리본 아이콘을 누르거나 명령 팔레트에서 어시스턴트 열기를 실행해 오른쪽 사이드바를 엽니다.
볼트 검색을 쓰려면 볼트 인덱싱 명령을 실행합니다.

백엔드	필요한 것
Bedrock	AWS 리전, `~/.aws/config` 프로필 이름 또는 Bedrock API 키
Gemini	Google AI Studio에서 발급한 API 키
OpenAI	API 키. 호환 엔드포인트는 `/v1`까지 포함한 base URL
Ollama	서버 주소. 비워 두면 `http://localhost:11434`

볼트 검색에 임베딩(embedding, 글을 의미가 담긴 숫자 벡터로 바꾼 것)을 쓰기 때문에 임베딩 API를 제공하는 곳만 백엔드로 지원합니다. Anthropic 직접 API에는 임베딩 엔드포인트가 없어서 Claude 모델은 Bedrock 백엔드로 씁니다.

Bedrock 인증은 PC에서 Roles Anywhere 프로필, SSO 프로필, Bedrock API 키 순서로 시도하고 모바일에서는 API 키만 씁니다. 설정에 적은 프로필과 키만 쓰고 [default] 프로필이나 환경 변수 같은 AWS SDK의 기본 자격 증명 체인으로는 넘어가지 않습니다.

API 키는 옵시디언 키체인에 보관합니다. 볼트의 data.json에는 키를 담은 비밀(secret)의 이름만 남습니다. 비밀은 볼트와 기기마다 따로 저장되므로 쓰는 기기마다 같은 이름으로 만들어 줍니다.

채팅: 첨부와 인용 검증

PC에서는 Enter로 보내고 모바일에서는 Enter가 줄바꿈이라 전송 버튼으로 보냅니다. 답은 스트리밍으로 나옵니다. 현재 노트와 볼트의 다른 노트를 대화에 첨부할 수 있고 파일 선택기나 드래그앤드롭, 붙여넣기로 기기의 파일도 첨부합니다. 형식에 따라 받을 수 있는 백엔드가 다릅니다.

첨부	지원 백엔드
텍스트 파일(`.md`·`.txt` 등)	네 백엔드 모두, 파일마다 앞 8,000자
이미지	네 백엔드 모두
PDF	Bedrock, Gemini
Office 문서(doc·docx·xls·xlsx)	Bedrock

지원하지 않는 조합은 조용히 버리지 않고, 그 형식을 처리할 수 있는 백엔드 목록과 함께 거절합니다.

답변이 노트를 인용하면 그 노트 경로와 #헤딩 앵커가 볼트에 실제로 있는지 확인하고, 찾지 못한 인용을 답변 아래에 표시합니다. 모델이 그럴듯한 경로를 지어내는 경우를 잡기 위한 장치입니다.

추론 강도는 채팅에서 /effort high처럼 바꾸고 현재 값은 채팅창 아래 모델 이름 옆에 표시됩니다. 받을 수 있는 값은 모델마다 다릅니다.

Graph RAG: 링크를 따라가는 볼트 검색

RAG(retrieval-augmented generation, 검색 증강 생성)는 질문과 관련된 문서를 먼저 찾아 모델에게 함께 건네는 방식입니다. 이 플러그인의 Graph RAG는 임베딩으로 찾은 노트에서 링크를 따라가 이웃 노트까지 후보에 넣습니다.

색인이 만든 인덱스를 검색이 읽고, 링크 순회와 키워드 융합으로 순위를 정합니다

색인. 노트를 최대 2,000자 청크(chunk, 조각)로 나누고 이웃한 청크끼리 200자씩 겹치게 합니다. 청크마다 임베딩을 만들어 볼트 루트의 .agent-llms-index.json에 저장합니다. 볼트의 .txt·.csv·.json·.html 파일도 함께 색인합니다.
벡터 검색. 질문의 임베딩과 가까운 노트를 시드(seed, 출발점)로 뽑습니다.
그래프 순회. 시드 노트의 아웃링크와 백링크를 따라 이웃 노트를 후보에 더합니다. 깊이는 0~3이고 기본값은 1입니다.
점수 계산. 관련성에 거리 감쇠를 곱합니다. 관련성은 벡터 유사도를 0~1 범위로 정규화한 값이고 감쇠는 링크 한 단계마다 0.5배입니다. 이웃 노트의 관련성은 이웃 자신의 유사도 60%와 시드 유사도 40%를 더한 값입니다. 감쇠를 곱하기 전의 관련성이 0.55 미만이면 후보에서 뺍니다.
키워드 융합. 4단계 점수로 매긴 순위를 키워드 검색 순위와 합쳐 최종 순서를 정합니다.

4단계를 숫자로 보겠습니다. 정규화한 유사도가 시드 노트는 0.9이고, 거기서 링크 하나로 이어진 이웃 노트 자신은 0.7이라고 하겠습니다. 이웃의 관련성은 0.6 × 0.7 + 0.4 × 0.9 = 0.78입니다. 0.55를 넘으므로 후보에 남고 한 단계 떨어져 있으니 0.5를 곱한 0.39가 이 단계의 점수가 됩니다.

5단계는 RRF(reciprocal rank fusion, 상호 순위 융합)를 씁니다. 점수 대신 순위로 두 목록을 합치는 방법으로, 각 목록에서 r위인 노트에 1/(60 + r)을 주고 더합니다. 4단계 점수로 매긴 벡터 쪽 목록의 1위는 1/61 ≈ 0.0164, 10위는 1/70 ≈ 0.0143입니다. 키워드 목록에는 가중치 0.5를 곱하므로 키워드 1위는 0.5/61 ≈ 0.0082로 벡터 쪽 10위보다 낮습니다. 그래서 키워드 검색에만 걸린 후보에게 결과 자리 2개를 따로 예약합니다. 오류 코드나 함수 이름, 버전 문자열처럼 글자가 정확히 맞아야 하는 질문이 임베딩 유사도에 밀리지 않게 하려는 것입니다.

검색은 폴더, 태그, 수정일 범위, 프론트매터(front matter, 노트 맨 위의 속성 영역) 속성으로 좁힐 수 있습니다. 속성 조건에는 =, !=, >, >=, <, <=, ~(부분 포함)를 쓰고 project.status = active처럼 점으로 중첩 키를 가리킵니다. 잘못된 조건은 조용히 버리지 않고 알려 줍니다. 노트를 고치면 그 파일은 자동으로 다시 색인됩니다.

색인할 때 노트 청크는 설정한 임베딩 API로 전송됩니다. 외부 엔드포인트를 쓰면 본문이 기기 밖으로 나가고 같은 기기의 Ollama를 지정하면 임베딩도 로컬에서 처리합니다.

Second Brain: 위키 노트를 쓰는 선택 기능

Second Brain은 기존 노트를 바탕으로 위키 노트를 만들고 유지하는 계층입니다. 기본값은 꺼짐이고 설정에서 켜기 전에는 이 계층이 노트를 만들거나 고치지 않습니다.

볼트를 읽고 결과를 채팅에 보여 주기만 하는 도구가 넷입니다.

challenge: 과거 노트를 근거로 지금 주장의 허점과 반례를 검토합니다.
connect: 두 주제를 각각 검색해 연결점을 찾습니다.
emerge: 최근 노트에서 아직 이름 붙지 않은 패턴을 찾습니다.
reconcile_topic: 노트끼리 어긋나는 진술을 점검해 보고합니다.

노트를 쓰는 도구도 넷이고, 설정한 위키 폴더(기본 Second Brain) 안에만 씁니다.

synthesize_topic: 주제와 관련된 노트를 모아 종합 노트를 만들거나 갱신합니다.
architect: 코드베이스 구조를 훑어 Architecture.md를 작성합니다.
create_wiki_note: 정해진 규격의 위키 노트를 만듭니다.
update_index: 위키 폴더의 노트를 모아 index.md 목록을 갱신합니다.

synthesize_topic, architect, update_index는 자기가 쓴 영역을 마커로 감쌉니다. 다시 실행하면 마커 안쪽만 바꾸므로 같은 노트에 직접 적은 글은 남습니다. create_wiki_note는 같은 경로에 파일이 이미 있으면 덮어쓰지 않고 실패로 알립니다.

<!-- @generated:synthesis -->
(AI가 생성한 내용)
<!-- @end:synthesis -->

여기에 직접 적은 메모는 재생성해도 그대로 남습니다.

종합 노트는 출처 청크마다 내용 해시를 기록합니다. 출처 노트가 바뀌면 종합 노트에 오래됨 표시가 붙고, 다시 생성할 때 무엇이 달라졌는지 diff로 보여 줍니다.

볼트 정리를 돕는 명령도 있습니다. 지식 공백 리포트, 링크 제안, 중복 후보, 복습 큐는 LLM을 호출하지 않고 계산합니다. 모순 반영, 링크 제안, 중복 후보, 결정 원장, Inbox 검토는 변경안을 목록으로 보여 주고 승인한 항목만 노트에 반영합니다.

AI가 바꾼 노트는 되돌릴 수 있습니다

채팅에서 AI가 도구로 노트를 바꾸거나 승인형 정리를 반영하면, 변경 전과 후의 스냅샷을 AI 변경 원장(되돌리기용 변경 기록)에 기록하고 최근 20건을 보관합니다. 마지막 AI 변경 되돌리기 명령은 가장 최근 작업 한 건을 되돌립니다. 그 작업 뒤에 해당 파일이 다시 바뀌었으면 되돌리기를 중단하고 아무것도 덮어쓰지 않습니다. 바뀌었는지는 수정 시각이 아니라 현재 내용을 스냅샷과 비교해 판단합니다. P.A.R.A 분류나 태그 생성처럼 채팅 도구를 거치지 않는 변경은 원장에 남지 않아 이 명령으로 되돌릴 수 없습니다.

미리 확인하고 싶다면 설정의 노트 변경·MCP 도구 실행 확인을 켭니다. 노트를 만들고 고치고 옮기고 지우는 도구와 모든 MCP 도구를 실행하기 전에 승인을 받습니다. 기본값은 꺼짐입니다.

할 일, P.A.R.A, 웹 클리퍼

할 일: 템플릿으로 일일 할 일 노트를 만들고 가장 최근 할 일 노트에서 끝내지 못한 항목을 하위 항목과 함께 이월합니다. 오래된 할 일 파일은 아카이브 폴더로 옮깁니다.
P.A.R.A 정리: 01. Projects, 02. Areas, 03. Resources, 04. Archives 네 폴더를 만들고 기존 노트를 AI가 알맞은 폴더로 분류합니다.
웹 클리퍼: 주소를 넣으면 페이지를 가져와 필요하면 번역하고 마크다운 노트로 요약합니다. 프론트매터에는 source, created, type: web-clip, tags: [web-clip]이 들어갑니다.

MCP 서버 연동 (PC 전용)

MCP(Model Context Protocol)는 모델이 외부 도구를 쓰도록 연결하는 규약입니다. 설정의 MCP 서버 편집기에 서버를 적으면 그 서버의 도구를 채팅에서 쓸 수 있습니다.

{
  "mcpServers": {
    "fetch": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp/fetch"]
    }
  }
}

지정한 명령은 셸을 거치지 않고(shell: false) 실행합니다. 서버 프로세스에는 PATH, HOME 같은 환경 변수 15개만 기본으로 넘기고 API 키나 프록시 설정은 서버별 env에 적은 것만 전달합니다. 모바일에서는 MCP 서버를 실행하지 않습니다.

PC와 모바일

채팅, 볼트 검색, 노트 편집, Graph RAG, Second Brain, 할 일 관리는 PC와 모바일이 같은 코드를 씁니다. 로컬 MCP 서버 실행과 ~/.aws/config 프로필 인증은 PC에서만 됩니다. 모바일에서 Ollama를 쓰려면 휴대폰이 접근할 수 있는 서버 주소를 넣어야 합니다. 휴대폰에서 localhost는 그 휴대폰 자신을 가리키기 때문입니다.

플러그인의 네트워크 요청은 고른 백엔드의 API, 웹 클리퍼가 가져오는 대상 주소, 설정 화면의 후원 버튼 이미지(cdn.buymeacoffee.com)로 갑니다. MCP 서버를 연결하면 그 서버가 따로 요청을 보낼 수 있습니다. 분석이나 추적 서비스로는 데이터를 보내지 않습니다.

한눈에 보기

항목	값
버전	0.8.0
옵시디언	1.13.2 이상, PC·휴대폰·태블릿
백엔드	AWS Bedrock, Google Gemini, OpenAI, Ollama
내장 도구	21개 (기본 13, Second Brain 8)
UI 언어	English, 한국어, 日本語
청크	최대 2,000자, 겹침 200자
그래프 순회 깊이	기본 1 (0~3)
AI 변경 원장	최근 20건
MCP	PC 전용
라이선스	MIT

테스트와 릴리스 검증

테스트는 1,632개입니다. 풀 리퀘스트와 main 브랜치 푸시마다 GitHub Actions가 린트·테스트·빌드를 돌립니다. 0.7.6 이후의 릴리스 파일에는 빌드 출처 증명(artifact attestation)이 붙어 있어, 받은 파일이 이 저장소의 소스에서 빌드됐는지 확인할 수 있습니다.

gh attestation verify main.js --repo TeiNam/obsidian-agent-llms

생각: AI 채팅에 볼트를 연결하고 싶다는 데서 시작했습니다

여기서부터는 플러그인을 만든 사람으로서 하는 개인적인 이야기입니다.

Agent LLMs는 AI 채팅에 옵시디언 볼트를 연결해서 사용하고 싶다는 데서 시작했습니다. 거기에 할 일 관리, 웹 요약처럼 이것저것 필요한 걸 붙이다 보니, 세컨드 브레인이나 지식 기반까지 하나의 플러그인에서 다 사용할 수 있도록 만들게 되었습니다.

Comments