msbaek/vis

Vault Intelligence System (vis) Skill

개요

vis는 BGE-M3 기반 시맨틱 검색 엔진으로 Obsidian vault의 지식 관리를 지원하는 CLI 도구. 사용자의 요청을 분석하여 최적의 vis 명령어와 옵션을 자동 선택하여 실행.

daemon 서버 모드 (성능 최적화)

visd가 실행 중이면 vis search가 자동으로 HTTP API를 사용한다 (ML import 없이 즉시 응답).

# 서버 관리 (시작/중지/상태/로그)
visd start     # 시작 (이미 실행 중이면 스킵)
visd status    # 상태 확인 (PID, 문서 수, 인덱스)
visd logs 20   # 최근 로그 20줄
visd restart   # 재시작
visd stop      # 중지

# 검색 (0.3초, CLI의 vis search는 import만 8초)
curl -s --get --data-urlencode "query=키워드" "http://localhost:8741/search?search_method=hybrid&top_k=10" | jq -r '.results[] | "\(.score) \(.path)"'

# rerank 포함 검색
curl -s --get --data-urlencode "query=키워드" "http://localhost:8741/search?search_method=hybrid&rerank=true&top_k=10" | jq -r '.results[] | "\(.score) \(.path)"'

서버 미실행 시: visd start로 시작 후 재시도.

사용자 의도 → vis 명령어 매핑

사용자가 아래 의도를 표현하면 해당 vis 명령어를 적극 제안하고 실행.

| 사용자 의도 | vis 명령어 | 예시 요청 | |---|---|---| | 문서 검색 | vis search | "TDD 관련 문서 찾아줘", "리팩토링에 대해 검색해줘" | | 주제별 문서 수집 | vis collect | "TDD 관련 자료 모아줘", "클린코드 문서 정리해줘" | | 관련 문서 찾기 | vis related | "이 문서와 비슷한 거 찾아줘", "연관 문서 뭐 있어?" | | MOC 생성 | vis generate-moc | "TDD MOC 만들어줘", "주제별 목차 생성해줘" | | 자동 태깅 | vis tag | "이 문서에 태그 달아줘", "폴더 전체 태깅해줘" | | 관련 문서 섹션 추가 | vis add-related-docs | "관련 문서 링크 넣어줘", "백링크 추가해줘" | | 지식 공백 분석 | vis analyze-gaps | "vault에 빈 부분 뭐야?", "부족한 주제 찾아줘" | | 중복 문서 감지 | vis duplicates | "중복 문서 있어?", "겹치는 내용 찾아줘" | | 주제 분석 | vis analyze | "vault 주제 분포 보여줘", "어떤 주제가 많아?" | | 클러스터 요약 | vis summarize | "문서 클러스터링해줘", "주제별로 묶어줘" | | 학습 리뷰 | vis review | "이번 주 학습 정리해줘", "월간 리뷰 만들어줘" | | 고립 태그 정리 | vis clean-tags | "안 쓰는 태그 정리해줘", "태그 정리" | | 인덱스 갱신 | vis reindex | "인덱스 다시 만들어줘", "새 문서 반영해줘" | | 태그 목록/통계 | vis list-tags | "태그 분포 보여줘", "어떤 태그가 많아?" | | 주제별 문서 연결 | vis connect-topic | "TDD 주제 문서 연결해줘", "그래프 연결 작업" | | 연결 진행 상황 | vis connect-status | "연결 작업 얼마나 됐어?", "진행 상황 확인" | | 시스템 상태 확인 | vis info | "vis 상태 어때?", "캐시 상태 확인" |

검색 전략 자동 선택

vis search 실행 시, 사용자의 표현을 분석하여 최적의 옵션을 자동 조합.

검색 방법 선택 기준

| 판단 기준 | 검색 방법 | 옵션 | |---|---|---| | 정확한 용어/키워드 검색 ("~라는 단어", "정확히") | keyword | --search-method keyword | | 개념/의미 기반 탐색 ("~에 대해", "~란 무엇") | semantic | --search-method semantic | | 일반적인 검색 (기본) | hybrid | --search-method hybrid | | 긴 문장, 복합 개념, 여러 주제 결합 | colbert | --search-method colbert |

품질 옵션 자동 추가 기준

| 사용자 표현 키워드 | 추가 옵션 | 효과 | |---|---|---| | "정확한", "가장 관련 높은", "best" | --rerank | 재순위화로 정확도 향상 | | "다 찾아줘", "빠짐없이", "포괄적으로" | --expand | 동의어 + HyDE 확장 | | "완전히", "깊이 있게", "철저하게" | --rerank --expand | 최고 품질 검색 | | 결과가 부족할 때 | --top-k 20 | 더 많은 결과 반환 | | 최근 문서만 | --threshold 0.5 | 높은 유사도만 |

검색 실행 기본 패턴

# 기본 검색
vis search "검색어"

# 고품질 검색 (정확도 중요)
vis search "검색어" --rerank

# 포괄적 검색 (놓치지 않기)
vis search "검색어" --expand

# 최고 품질 (정확 + 포괄)
vis search "검색어" --rerank --expand

# 결과 저장
vis search "검색어" --output results.md

주요 명령어 사용 패턴

주제별 문서 수집 (collect)

사용자가 특정 주제의 문서를 모으려 할 때 사용.

vis collect "주제" --output collection.md
vis collect "주제" --top-k 30 --expand    # 포괄적 수집

관련 문서 찾기 (related)

특정 문서와 유사한 문서를 찾을 때 사용.

vis related "문서명.md" --top-k 10

MOC 자동 생성 (generate-moc)

주제별 Map of Content를 자동으로 생성할 때 사용.

vis generate-moc "주제" --top-k 50
vis generate-moc "주제" --output "MOC-주제.md" --include-orphans

자동 태깅 (tag)

문서에 hierarchical tag를 자동으로 부여.

vis tag "문서명.md"                    # 단일 문서
vis tag "폴더명/" --recursive          # 폴더 전체
vis tag "문서명.md" --dry-run          # 미리보기
vis tag "문서명.md" --tag-force        # 기존 태그 무시하고 재생성

관련 문서 섹션 추가 (add-related-docs)

문서에 "관련 문서" 섹션을 자동으로 추가.

vis add-related-docs "문서명.md"
vis add-related-docs "문서명.md" --dry-run           # 미리보기
vis add-related-docs --batch --pattern "000-SLIPBOX/*.md"   # 배치 처리

지식 공백 분석 (analyze-gaps)

vault에서 부족한 주제나 연결이 약한 영역을 분석.

vis analyze-gaps --top-k 20

중복 문서 감지 (duplicates)

내용이 유사한 중복 문서를 찾아 정리.

vis duplicates

주제 분석 (analyze)

vault 전체의 주제 분포를 분석.

vis analyze --output analysis.md

클러스터 요약 (summarize)

문서를 클러스터링하고 주제별로 요약.

vis summarize --clusters 5
vis summarize --topic "TDD" --clusters 3 --style detailed
vis summarize --since "2024-01-01" --output recent.md

학습 리뷰 (review)

일정 기간의 학습 활동을 리뷰.

vis review --period weekly
vis review --period monthly --output monthly-review.md
vis review --from 2024-08-01 --to 2024-08-31
vis review --topic TDD --period quarterly

태그 목록 및 통계 (list-tags)

vault의 태그 목록과 사용 통계를 확인.

vis list-tags                        # 전체 태그 목록
vis list-tags --depth 1              # 최상위 태그만
vis list-tags --min-count 5          # 5개 이상 문서에 사용된 태그
vis list-tags --output tags.md       # 파일로 저장

주제별 문서 연결 (connect-topic)

주제(태그)를 기준으로 MOC 생성 + 관련 문서 링크를 한 번에 처리.

vis connect-topic "TDD"                           # MOC + 관련 문서 링크
vis connect-topic "TDD" --dry-run                  # 미리보기
vis connect-topic "TDD" --skip-moc                 # 관련 문서 링크만
vis connect-topic "TDD" --skip-related             # MOC만
vis connect-topic "TDD" --related-k 5 --backup     # 관련 링크 5개 + 백업

연결 진행 상황 (connect-status)

주제별 문서 연결 작업의 진행 상황을 확인.

vis connect-status                   # 요약
vis connect-status --detailed        # 전체 주제 상세 현황

고립 태그 정리 (clean-tags)

1개 이하 문서에서만 사용되는 고립 태그를 감지하고 정리.

vis clean-tags                  # 감지만
vis clean-tags --dry-run        # 미리보기

인덱스 관리 (reindex)

새 문서 추가 후 또는 인덱스 갱신이 필요할 때.

vis reindex                       # 기본 재인덱싱
vis reindex --with-colbert        # ColBERT 포함
vis reindex --force               # 강제 전체 재인덱싱
vis reindex --include-folders 000-SLIPBOX 003-RESOURCES   # 특정 폴더만

vis 기능 전체 안내

사용자가 "vis로 뭘 할 수 있어?", "vis 기능 알려줘" 등으로 질문하면 아래 내용을 기반으로 상세히 안내.

19개 명령어 전체 목록

1. search - 시맨틱/키워드/하이브리드/ColBERT 검색 (4가지 방법 + rerank + expand)
2. collect - 주제별 문서 수집 및 정리
3. related - 특정 문서와 유사한 관련 문서 찾기
4. generate-moc - 주제별 Map of Content 자동 생성
5. tag - 문서에 hierarchical tag 자동 부여
6. add-related-docs - 문서에 "관련 문서" 섹션 자동 추가
7. analyze-gaps - vault의 지식 공백 분석
8. duplicates - 중복/유사 문서 감지
9. analyze - vault 주제 분포 분석
10. summarize - 문서 클러스터링 및 주제별 요약
11. review - 기간별 학습 활동 리뷰 (주간/월간/분기)
12. clean-tags - 고립 태그 감지 및 정리
13. reindex - 검색 인덱스 재구축
14. init - 시스템 초기화 (최초 설정)
15. test - 시스템 테스트
16. info - 시스템 상태 및 캐시 정보 확인
17. list-tags - Vault 태그 목록 및 통계 (계층별, 문서 수)
18. connect-topic - 주제별 문서 연결 (MOC 생성 + 관련 문서 링크 삽입)
19. connect-status - 그래프 연결 진행 상황 확인

검색 엔진 특징

• BGE-M3 모델 기반 Dense + Sparse + ColBERT 3가지 임베딩
• Cross-encoder 재순위화 (BGE Reranker V2-M3)
• 쿼리 확장: 동의어 + HyDE (Hypothetical Document Embedding)
• SQLite 캐싱으로 빠른 반복 검색

관련 문서 자동 제안 (Related Notes)

vis search 또는 vis related 실행 후, 검색 대상 문서가 명확한 경우 관련 문서 링크 추가를 자동으로 제안한다.

트리거 조건

• 사용자가 특정 문서에 대해 검색하거나 (vis related "문서.md")
• 검색 결과에서 특정 문서와 관련된 문서들이 발견된 경우

프로세스

1. 후보 선별: 검색 결과에서 daily notes, 자기 자신을 제외하고 관련도 높은 문서 목록 생성
2. 사용자에게 제안: 후보 목록을 번호와 함께 표시하고, 추가할 문서를 선택하도록 요청
   • 각 후보에 한 줄 맥락 설명 포함
3. 사용자 피드백 필수: 선택된 문서만 Related Notes 섹션에 추가
   • 맥락 설명도 사용자가 수정 가능
4. 적용: 문서 하단에 ## Related Notes 섹션 추가 (Uncertainty Map 섹션이 있으면 그 앞에)

   ## Related Notes
   - [[문서명]] - 맥락 설명
   

5. 기존 Related Notes: 이미 섹션이 있으면 중복 없이 항목을 추가

주의사항

• 반드시 사용자 승인 후 적용 — 자동으로 문서를 수정하지 않음
• frontmatter의 related: 필드는 사용자가 명시적으로 요청한 경우에만 업데이트

자주 실수하는 옵션

| 잘못된 옵션 | 올바른 사용법 | |---|---| | --method | --search-method | | --k | --top-k | | --top | --top-k | | --output-file | --output | | --reranking | --rerank | | --query "TDD" | positional: vis search "TDD" | | --topic "TDD" | positional: vis collect "TDD" | | --file "문서.md" | positional: vis related "문서.md" | | --target "문서.md" | positional: vis tag "문서.md" | | --topic "TDD" (moc) | positional: vis generate-moc "TDD" | | --file "문서.md" (add) | positional: vis add-related-docs "문서.md" | | --similarity-threshold | --threshold (add-related-docs) |

상세 CLI 레퍼런스는 references/cli-reference.md 참조.