obsidian-agent

obsidian-agent는 로컬 Obsidian 볼트 위에서 AI 에이전트 역할을 하는 셀프 호스팅 텔레그램 봇이다. 답변을 채팅 스레드나 클라우드 인덱스에 보관하는 대신, 볼트 내부의 마크다운, JSON, SQLite 파일을 기반으로 응답을 생성하며 이 파일들은 언제든 Obsidian에서 편집할 수 있다. 핵심 구성 요소는 텔레그램 봇, 볼트, OpenAI 호환 LLM이다(DeepSeek, OpenRouter, Groq, 로컬 vLLM 등의 호스트를 LLM_API_KEY / LLM_BASE_URL / LLM_MODEL로 지원). 나머지는 모두 선택 사항이다. 기능 - 캡처: 텔레그램으로 보낸 텍스트, 음성(ASR), 사진, PDF, 링크가 구조화된 볼트 파일로 변환된다. 금액 항목은 원장에 반영되기 전 채팅 내 확인이 필요하다. - 플래닝: 마크다운으로 저장되는 칸반 보드(컬럼, id, 로그), 목표, 루틴, 주간 회고, 선택적 캘린더 오버레이, 완료 항목의 월간 아카이빙. - 지식: 기존 코퍼스에 대한 수집, 태그, 위키링크, RAG 검색, 선택적 예약 리서페이싱과 유지 관리 작업. - 재정: 자연어 지출, 수입, 이체, 부채, 계획 지원. 대시보드는 Obsidian 페이지로 렌더링되며 데이터는 로컬 데이터베이스에 보관된다. - 크로스 도메인 쿼리: 한 문장이 여러 도구를 거쳐 라우팅될 수 있다. 예를 들어 같은 기간에 출시된 것과 지출된 것을 비교하는 식이다. 모듈 설계 세 도메인(플래닝, 지식, 재정)이 하나의 프로세스에서 실행된다. 기능 매니페스트가 활성 상태를 결정하며, 모듈을 비활성화하면 단순히 숨기는 것이 아니라 UI, 도구, 프롬프트, 동기화에서 제거된다. 브로커 API, 건강 데이터 파이프, 데스크톱 동기화 스크립트 같은 커넥터는 기본적으로 꺼져 있으며 사용자별로 구성된다. 호스팅 봇과 장기 실행 작업은 VPS나 노트북에서 24시간 캡처를 위해 실행할 수 있으며, 볼트는 사용자가 편집하는 곳에 위치한다. 동기화 옵션으로는 Obsidian Sync, Syncthing 또는 선택적 데스크톱 스크립트가 있다. 문서에는 Mac이 필요 없으며, 건강 지표는 Apple 전용 API 대신 텍스트 스냅샷으로 처리된다고 명시되어 있다. 설정 온보딩은 AI 코딩 챗으로 진행하도록 설계되었다. 저장소 루트를 Cursor에서 열고 /setup을 실행하거나, Claude Code나 유사 도구에서 같은 스킬 파일을 따르면 된다. CLI 경로는 scripts/onboarding_wizard.sh로 제공되며, 플레이북 선택(플래닝, 재정, 지식, 전체) 후 볼트 레이아웃 초기화와 스모크 테스트가 이어진다. 요구 사항은 Python 3.10–3.12, Obsidian 볼트 경로, 텔레그램 봇 토큰, LLM API 키다. Docker는 설정을 대체하는 것이 아니라 부트스트랩 이후의 런타임 옵션으로 설명된다. 저장소 구조 unified_bot/에는 프로덕션 텔레그램 호스트가 들어 있고, shared/에는 에이전트 플랫폼, LLM, 기능 로직이 있으며 planning_bot/, knowledge_bot/, finance_bot/이 도메인 모듈이다. 설정과 사용자 대면 문구는 YAML 파일에 있어 Python을 로캘 독립적으로 유지하며, 기본 로캘은 영어이고 러시아어도 사용할 수 있다. 평가와 테스트 eval/ 아래에 정제된 합성 검색 쿼리 공개 골드 세트가 포함되어 있으며, 관리자는 비공개 라벨링 실행에서 대략 0.76의 in-window Recall@1 / MRR을 보고했다. 테스트는 scripts/run_tests.sh로 실행되며 CI는 GitHub Actions로 구성되어 있다. 라이선스는 MIT다.