Communitygithub.com

nmdra/notebrain-cli

NoteBrain은 Obsidian 볼트를 로컬 ChromaDB 벡터 데이터베이스에 인덱싱하여 AI 에이전트가 개인 지식 기반을 지능적으로 탐색할 수 있도록 지원하는 고성능 Go CLI 도구입니다. 의미론적 검색, 역링크 탐색, 태그 기반 발견 기능을 통해 에이전트가 메모를 컨텍스트와 함께 검색하고 추론할 수 있도록 합니다.

notebrain-cli란 무엇인가요?

NoteBrain CLI Skill은 Obsidian 볼트를 로컬 ChromaDB 벡터 데이터베이스에 인덱싱하는 고성능 Go CLI 도구인 NoteBrain을 AI 에이전트가 효과적으로 활용할 수 있도록 설계된 스킬입니다. 이 스킬은 의미론적 검색, 그래프 탐색, 역링크 발견, 숨겨진 관계 찾기, 전체 노트 검색, 태그 분석 등 다양한 명령어를 제공합니다. 에이전트는 `search`, `get`, `backlinks`, `connections`, `hidden`, `tags` 등의 명령어를 사용하여 볼트 내 정보를 정밀하게 검색하고, `--format json`과 `--jsonpath` 플래그를 통해 구조화된 데이터를 추출할 수 있습니다. 또한, 다중 신호 검색 체인(`search → backlinks → connections → hidden`)을 통해 단순 검색 이상의 깊이 있는 답변을 생성할 수 있습니다. Obsidian 볼트를 사용하는 모든 AI 에이전트(Claude Code, Cursor, Codex 등)에서 사용할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add nmdra/notebrain-cli

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

AI 에이전트를 위한 NoteBrain CLI 스킬

NoteBrain은 Obsidian 볼트를 로컬 ChromaDB 벡터 데이터베이스에 인덱싱하는 고성능 Go CLI 도구입니다. 마크다운 노트에 대해 의미론적 검색, 그래프 탐색, 역링크 발견, 숨겨진 관계 찾기, 전체 노트 검색, 태그 분석 기능을 제공합니다.

핵심 실행 원칙 및 근거

효율적으로 작동하고 토큰 낭비나 세션 중단을 방지하기 위해 다음 기본 원칙을 따르세요:

  1. NoteBrain만 사용 — 일반 파일 검색 금지: 사용자의 질문에 답변하기 위해 볼트의 마크down 파일에 대해 grep, find, ls 또는 임시 셸 스크립팅을 절대 사용하지 마십시오. NoteBrain의 명령어는 인덱싱된 벡터 및 그래프 데이터베이스를 기반으로 특별히 제작되었으며, 파일 시스템 수준의 텍스트 검색보다 항상 더 높은 품질과 관련성 높은 결과를 생성합니다. notebrain을 볼트 콘텐츠에 대한 유일한 인터페이스로 취급하십시오. notebrain 명령어가 유용한 결과를 반환하지 않는 것처럼 보이면, 일반 파일 검색으로 대체하기보다 notebrain 쿼리를 개선(다른 표현, 더 넓은 --limit, 다른 명령어)하십시오.
  2. 비대화형 실행 (--format json): 기본적으로 NoteBrain은 사람이 탐색하도록 설계된 대화형 터미널 TUI(Bubble Tea)를 실행합니다. 이 대화형 인터페이스는 자동화된 에이전트 세션을 중단시킵니다. 쿼리 명령어에는 항상 --format json(또는 --format ndjson / --format tsv)을 지정하여 구조화되고 파싱 가능한 데이터를 즉시 수신하십시오. 모든 JSON 봉투 필드는 깔끔한 snake_case 키(note_slug, title, file_path, score, tags, text)를 사용합니다.
  3. AI 에이전트 명령어 체이닝 (--jsonpath): 후속 명령어로 전달하기 위해 노트 슬러그나 텍스트 추출과 같은 특정 필드만 필요한 경우 --jsonpath를 사용하십시오(예: --jsonpath="$.results[0].note_slug" 또는 --jsonpath="$.results[*].note_slug"). --jsonpath를 사용하면 스칼라 값은 원시 따옴표 없는 문자열로 출력되고 배열은 각 항목을 새 줄에 출력하여 jq 없이도 셸 변수 추출이 가능합니다.
  4. 전체 노트 검색 (notebrain get): search가 관련 노트 청크를 반환하면 notebrain get <note-slug-or-path>를 사용하여 청크 인덱스를 추측하는 대신 인덱싱된 모든 청크에 걸쳐 함께 연결된 완전히 재구성된 마크다운 노트 텍스트를 검색하십시오. 기본 볼트 파일에 대해 cat을 사용하지 마십시오. get은 청크된 노트를 올바르게 재구성하고 볼트의 인덱싱된 상태를 존중합니다.
  5. 합성 콘텐츠 검색 (--include-text): 기본적으로 search 및 탐색 명령어는 가벼운 메타데이터 봉투(제목, 파일 경로, 태그, 유사도 점수)를 반환합니다. 작업에 검색 결과에서 개별 청크에 대한 요약이나 추론이 필요한 경우 --include-text를 추가하십시오. 반환된 text 필드에는 코드 블록이 보존된 풍부한 마크다운이 포함되어 있어 코드 조각을 복사하여 붙여넣을 수 있습니다.
  6. 바이너리 확인 및 따옴표 처리: 개발 환경에서 notebrain이 시스템 PATH에 없으면 ./notebrain을 실행하십시오. 노트 제목에는 공백이나 대괄호("Q3 Planning [Draft]")가 포함되는 경우가 많으므로 노트 제목, 태그 및 검색 쿼리는 항상 큰따옴표로 묶으십시오.
  7. 임베디드 영구 저장소: NoteBrain은 임베디드 데이터베이스(~/.notebrain/chroma)로만 실행됩니다. 독립 실행형 ChromaDB Docker 컨테이너나 HTTP 서버는 필요하지 않으며 지원되지 않습니다.
  8. 자동 수집: 수집은 OS 스케줄러(cron/systemd 타이머, 3시간마다)를 통해 처리됩니다. 사용자가 노트 편집 후 즉시 재인덱싱을 명시적으로 요청하지 않는 한 쿼리 전에 수동으로 ingest를 실행할 필요가 없습니다.

명령어 선택 가이드

사용자의 분석 목표에 맞는 특화된 명령어를 선택하십시오:

사용자 의도명령어사용 이유 및 방법
"내 노트에 X에 대해 뭐라고 써있지?"search모든 노트 청크에 대해 벡터 유사도 검색을 수행합니다. 태그별 필터링은 --tag="TagName"을 사용하십시오.
"Y 노트의 전체 내용을 읽어줘"get슬러그 또는 파일 경로로 전체 노트 텍스트와 메타데이터를 검색하고 재구성합니다.
"이 노트에 직접 링크된 것은 무엇인가요?"backlinks대상 노트를 가리키는 명시적 [[wikilink]] 참조를 찾습니다.
"그래프에서 구조적으로 가까운 것은 무엇인가요?"connections--hops N까지 위키링크에 대한 너비 우선 탐색(BFS)을 실행합니다. 기하급수적 증가를 피하기 위해 --hops 1 또는 --hops 2로 유지하십시오.
"링크되지는 않았지만 의미상 관련된 것은?"hidden링크되지 않았지만 의미상 유사한 노트를 표면화합니다. 개념적 다리를 발견하는 데 매우 유용합니다.
"X와 관련된 개념을 Y 노트 중심으로 찾아줘"boosted--seed 노트에 대한 그래프 근접성과 벡터 유사성을 결합합니다.
"X와 태그를 공유하는 노트는 무엇인가요?"tags태그 중복을 분석합니다. tags 배열에 깔끔한 태그 문자열을 반환합니다.
"데이터베이스가 최신인가요?"stats컬렉션 개수(chunks, links)를 출력합니다. --format=json 및 --jsonpath를 지원합니다.
"볼트 인덱싱 또는 재인덱싱"ingest마크다운 노트를 ChromaDB에 동기화합니다. 재수집은 멱등적입니다.

명령어 구문

의미론적 검색 및 태그 필터링 (search)

notebrain search "kubernetes reconciliation" --tag="Kubernetes" --limit 5 --format json --include-text

주요 검색 플래그

플래그목적기본값
--top-k N노트당 유지할 최대 청크 수. 하나의 긴 노트가 결과를 지배하는 것을 방지하면서 깊이를 보존합니다.3
--context-window N각 일치 항목 주변의 ±N개의 인접 청크를 가져와 context 배열을 채웁니다. 대부분의 작업에 1 또는 2를 사용하십시오.0
--has-tasks작업 목록(체크박스)이 포함된 청크만 반환합니다.off
--has-code펜스 코드 블록이 포함된 청크만 반환합니다.off
--section특정 제목 경로(예: "Architecture > Components") 아래 청크로 결과를 필터링합니다.—
--limit N반환할 최대 총 결과 수.10
--tag "TagName"태그 이름으로 필터링하거나 검색합니다.—
--min-score F이 유사도 점수(0–1) 미만의 결과를 숨깁니다.0

--context-window vs notebrain get 사용 시기

  • --context-window 1 사용: 여러 검색 결과에 대해 가벼운 주변 컨텍스트가 한 번에 필요할 때 사용합니다. 하나의 검색 호출로 일치하는 청크와 그 이웃을 모두 얻을 수 있어 전체 노트를 가져오지 않고도 로컬 컨텍스트를 이해하기에 충분합니다.
  • notebrain get 사용: 완전한 재구성된 노트 텍스트가 필요할 때 사용합니다. 예를 들어, 사용자가 특정 노트를 읽거나 요약해달라고 요청하거나, 전체 문서 구조를 확인해야 할 때 사용합니다.

윈도우 접근 방식은 많은 검색 결과를 처리할 때 특히 유용합니다. 모든 결과에 대해 전체 노트를 가져오는 것은 낭비이기 때문입니다. 먼저 윈도우를 가져온 다음, 전체 컨텍스트가 실제로 필요한 노트만 선택적으로 get하십시오.

전체 노트 검색 (get)

notebrain get "02areaskubernetesckadkubernetes-native-applications" --format json

그래프 연결 및 숨겨진 링크 (connections, hidden)

notebrain connections "Distributed Systems" --hops 2 --format json
notebrain hidden "Microservices" --limit 5 --format json --include-text

JSON 출력 스키마

결과 구조를 이해하는 것은 안정적인 필드 추출에 필수적입니다. 모든 쿼리 명령어는 이 봉투에 결과를 래핑합니다:

{
  "command": "search",
  "query": "Semantic Search: \"kubernetes\"",
  "total": 3,
  "results": [
    {
      "note_slug": "02areaskubernetes-architecture",
      "title": "Kubernetes Architecture",
      "file_path": "02.Areas/Kubernetes/Architecture.md",
      "score": 0.82,
      "chunk_index": 2,
      "tags": ["Kubernetes", "DevOps"],
      "heading_path": "Components > Control Plane",
      "text": "The API server validates and configures...",
      "context": [
        "Previous chunk text about etcd storage...",
        "The API server validates and configures...",
        "The scheduler watches for newly created Pods..."
      ]
    }
  ]
}
필드존재 시점설명
note_slug항상파일 경로에서 파생된 URL 안전 식별자.
title항상프론트매터 또는 파일 이름에서 가져온 노트 제목.
file_path항상볼트 내 상대 경로.
score항상검색의 유사도 점수(0–1); 연결의 홉 수.
chunk_index검색, hidden, boosted일치하는 노트의 청크 인덱스(0부터 시작).
tags노트에 태그가 있는 경우태그 문자열 배열.
heading_path청크가 제목 아래에 있는 경우"Section > Subsection" 형태의 이동 경로.
text--include-text가 전달된 경우일치하는 청크의 전체 마크다운 텍스트. 코드 블록이 보존됩니다.
context--context-window N > 0인 경우±N개의 인접 청크 텍스트 배열. 청크 인덱스로 정렬됩니다.
extraConnections, tags, boosted명령어별 정보(예: "2 hop(s)", "graph-boosted").

답변 품질 향상: 다중 신호 검색

"X에 대해 내가 아는 것은?" 또는 "X에 대한 내 노트를 요약해줘"와 같은 질문에 답변하기 전에 단일 search 호출에 그치지 마십시오. 검색 결과는 쿼리와 의미상 가까운 청크만 표면화할 뿐, 사용자가 그래프에 의도적으로 구축한 주변 컨텍스트를 놓칩니다. 항상 그림을 확장하십시오:

  1. 컨텍스트와 함께 검색 — --context-window 1 --include-text --top-k 2와 함께 search를 실행하여 가장 관련성 높은 청크와 주변 문단을 한 번에 가져옵니다. 이는 단일 호출로 정밀도(일치하는 청크)와 컨텍스트(앞뒤 내용)를 모두 제공합니다.
  2. 각 시드에 대한 역링크 가져오기 — notebrain backlinks <seed-slug> --format json --include-text를 실행하여 시드에 명시적으로 링크된 모든 노트를 추출합니다. 이는 사용자가 수동으로 관련성을 정리한 노트이므로 그 내용은 거의 항상 신호가 강하며 합성 시 가중치를 많이 두어야 합니다.
  3. 연결을 바깥으로 확장 — notebrain connections <seed-slug> --hops 2 --format json을 실행하여 시드 주변의 로컬 그래프 이웃을 매핑합니다. 이는 순수 벡터 검색에는 나타나지 않을 수 있지만 동일한 지식 클러스터의 일부인 구조적으로 인접한 노트(예: 두 링크 떨어진 노트)를 드러냅니다.
  4. 숨겨진 링크 확인 — notebrain hidden <seed-slug> --include-text --context-window 1을 실행하여 사용자가 아직 링크하지 않은 개념적으로 관련된 노트를 찾습니다. 이를 사용자에게 볼트의 잠재적 누락 링크로 명시적으로 언급하십시오. 이것이 일반 검색보다 NoteBrain의 가장 가치 있는 차별점 중 하나이기 때문입니다.
  5. 단순히 나열하지 말고 합성 — 시드 노트, 역링크, connections 이웃, 그리고 hidden 결과를 단일 일관된 답변으로 결합하여 명시적으로 링크된 것(높은 신뢰도)과 의미상만 유사한 것(재확인 필요)을 구분하십시오.

이 search → backlinks → connections → hidden 체인은 단순한 search 호출이 아닌, 사소하지 않은 탐색적 질문에 대한 기본 워크플로여야 합니다. 이는 사용자가 구축한 명시적 구조와 NoteBrain이 감지할 수 있는 암시적 구조를 모두 표면화하기 때문입니다.

AI 에이전트 체이닝 파이프라인

# 1. 주변 컨텍스트와 함께 검색 — top-k는 여러 노트에 걸쳐 결과를 다양하게 유지합니다.
SLUG=$(notebrain search "message broker backpressure" --limit 3 --top-k 2 \
  --context-window 1 --include-text --format json \
  --jsonpath="$.results[0].note_slug")

# 2. 상위 적중 노트의 완전히 재구성된 노트 텍스트 가져오기
notebrain get "$SLUG" --jsonpath="$.text"

# 3. 이 노트를 가리키는 모든 역링크 노트 슬러그와 그 내용을 찾아
#    사용자가 명시적으로 링크한 내용을 기반으로 답변을 grounding
notebrain backlinks "$SLUG" --format json --include-text

# 4. 그래프 이웃을 탐색하여 벡터 검색만으로는 놓칠 수 있는
#    구조적으로 인접한 노트를 표면화
notebrain connections "$SLUG" --hops

…

[번역 잘림]

관련 스킬