로컬 지식 베이스

로컬 지식 베이스는 VelaTerm에서 작성하고 정리하는 Markdown 파일이 담긴 일반 폴더입니다. 노트와 첨부 파일이 이 폴더에 그대로 저장되므로, 다른 편집기에서도 계속 편집할 수 있습니다. 일부 메뉴 항목에서는 로컬 지식 베이스를 "보관함"이라고 부르며, 두 용어는 같은 폴더를 가리킵니다.

내장된 "세션 지식 베이스"는 로컬 지식 베이스와 나란히 표시됩니다. 세션 지식 베이스에는 에이전트가 세션에서 정리한 지식이 담기며, 항목, 출처, 수정 이력을 따로 관리합니다. 세션 지식 베이스를 참조하십시오.

지식 베이스 열기

오른쪽 패널의 지식 아이콘(도구 설명 "지식 베이스")을 클릭합니다. 가운데 영역에 "지식 베이스" 탭이 열리고, 다음 항목이 있는 홈 페이지가 표시됩니다.

검색 상자("세션 지식과 로컬 노트 검색…", 아래 검색 섹션 참조)
"세션 지식 베이스"
"로컬 지식 베이스"
"지식 베이스 열기" 및 "지식 베이스 만들기" 버튼

오른쪽 패널에는 "세션 지식 베이스", "보관된 세션", "로컬 지식 베이스"라는 세 개의 최상위 항목이 있는 트리가 표시됩니다. 화살표를 클릭하면 폴더가 그 자리에서 펼쳐지며, 여러 지식 베이스를 동시에 펼칠 수 있습니다. 폴더 이름을 클릭하면 폴더의 내용이 표시되고, 노트를 클릭하면 노트가 열립니다. 트리 맨 위의 "지식 베이스" 링크를 클릭하면 홈 페이지로 돌아가고, 페이지 헤더의 "상위 단계로 이동" 버튼을 클릭하면 지식 베이스를 벗어나지 않고 상위 페이지로 이동합니다.

노트는 일반 문서 탭에서 열리며, 다른 Markdown 파일과 마찬가지로 편집, 저장, 검색, PDF 내보내기를 사용할 수 있습니다(문서 및 브라우저 탭 참조). "지식 베이스" 탭은 탭 바에 남아 있으므로 보던 위치로 돌아갈 수 있습니다.

로컬 지식 베이스 열기 또는 만들기

열기: "지식 베이스 열기"를 클릭하고 폴더를 선택합니다. 데스크톱 앱에서는 시스템 폴더 선택 창이 표시되고, 브라우저 클라이언트에서는 연결된 컴퓨터의 폴더를 탐색하는 창이 표시됩니다. 기존 Obsidian 보관소도 바로 열 수 있습니다. 파일은 원래 위치에 그대로 있으며, .obsidian 같은 숨김 폴더는 인덱싱하거나 변경하지 않습니다.
만들기: "지식 베이스 만들기"를 클릭하고 "이름"을 입력한 다음, "폴더"를 지정하고(직접 입력하거나 "찾아보기"로 선택하며, 기본 제안은 ~/Notes입니다) 확인합니다. VelaTerm이 폴더를 만들고 엽니다. 상위 폴더는 이미 있어야 하고, 같은 이름의 폴더는 없어야 합니다. 그렇지 않으면 "대상이 이미 존재합니다. 다른 이름이나 폴더를 선택하세요."가 표시됩니다. 기존 폴더를 사용하려면 대신 "지식 베이스 열기"를 선택합니다.
이름 바꾸기: 트리에서 지식 베이스를 마우스 오른쪽 버튼으로 클릭하고 "이름 바꾸기"를 선택합니다. 디스크의 폴더 이름도 함께 바뀝니다.
닫기: 지식 베이스 도구 모음에서 "보관함 닫기"를 클릭하거나, 트리에서 지식 베이스를 마우스 오른쪽 버튼으로 클릭하여 같은 항목을 선택합니다. 닫으면 목록에서 폴더만 제거되고 파일은 디스크에 남습니다. 같은 폴더를 다시 열면 휴지통과 가져오기 기록도 그대로 남아 있습니다.

여기서 "로컬"은 현재 연결된 VelaTerm 백엔드가 실행되는 컴퓨터를 뜻합니다. 브라우저 클라이언트에서 "지식 베이스 열기"를 사용하면 그 컴퓨터의 폴더를 탐색하며, 가져오기를 하면 브라우저에서 선택한 파일이 그 컴퓨터로 업로드됩니다.

파일과 폴더 가져오기

대상 지식 베이스를 열고 도구 모음에서 "가져오기"를 클릭합니다.
가져올 위치("폴더")를 선택한 다음 "파일 선택"이나 "폴더 선택"을 클릭하거나, 파일과 폴더를 가져오기 영역으로 끌어다 놓습니다.
목록을 확인하고 확정합니다.

가져오기는 백그라운드에서 실행되므로, 파일이 복사되는 동안 다른 페이지로 이동하거나 노트를 열 수 있습니다. 진행 상황은 지식 베이스 도구 모음과 홈 페이지에 표시되며, 가져오기 대화 상자나 "가져오기 기록"에서 취소할 수 있습니다. 가져오기가 끝나면 가져온 파일과 건너뛴 파일의 수가 배너에 표시되고, 창에 포커스가 없으면 시스템 알림("가져오기 완료" 또는 "가져오기 실패")이 표시됩니다. 한 지식 베이스에서는 한 번에 하나의 가져오기만 실행할 수 있습니다.

가져오기는 ASCII가 아닌 파일 이름, 상대 폴더 구조, 첨부 파일을 포함하여 파일을 있는 그대로 복사하며, 원본은 수정하지 않습니다. 폴더를 가져오면 폴더 자체도 함께 가져옵니다. 파일 하나라도 기존 파일을 덮어쓰게 되면 전체 가져오기가 거부됩니다. 숨김 파일과 숨겨진 설정 폴더는 건너뜁니다. 브라우저의 파일 선택 창은 빈 폴더를 전달하지 않으므로 빈 폴더는 가져오지 않습니다.

한 번의 가져오기에는 최대 5,000개의 파일(건너뛴 숨김 파일도 이 개수에 포함)과 총 1GiB까지 포함할 수 있으며, 파일 하나의 크기는 최대 100MiB입니다. 파일은 먼저 임시 영역에 준비되고 전체가 도착한 뒤에야 대상 위치에 나타나므로, 업로드가 중단되더라도 일부만 기록된 노트가 생기지 않습니다.

"가져오기 기록"에는 각 가져오기의 시각, 대상 위치(최상위 폴더는 "지식 베이스 루트"), 상태("가져오는 중", "완료", "실패", "취소됨", "중단됨"), 가져온 파일과 건너뛴 파일의 수, 크기, 소요 시간이 표시됩니다. "파일 (N)"을 클릭하면 각 파일과 건너뛴 이유를 확인할 수 있습니다. "기록 삭제"는 기록에서 해당 항목만 삭제하며, 가져온 파일은 삭제하지 않습니다. 앱이 예기치 않게 종료되는 등의 이유로 진행이 2분 넘게 멈춘 가져오기는 "중단됨"으로 표시되며, 이 기록을 삭제하면 해당 가져오기를 위해 준비해 둔 파일도 함께 삭제됩니다.

노트 작성과 정리

지식 베이스 페이지에는 "최근 노트", "휴지통", "가져오기 기록" 보기와 "새 노트" 버튼이 있고, 도구 모음에는 "새 폴더", "가져오기", "보관함 닫기" 버튼이 있습니다. 노트 목록은 태그("모든 태그")로 필터링하고 "최근 수정순" 또는 "제목순"으로 정렬할 수 있습니다.

지식 베이스 페이지가 표시되어 있을 때 ⌘N / Ctrl+N을 누르면 "새 노트"가 만들어지고, ⌘O / Ctrl+O를 누르면 "빠른 열기"(경로로 노트 찾기)가 열리며, ⌘⇧F / Ctrl+Shift+F를 누르면 "노트 검색…" 상자로 이동합니다.
노트 이름을 바꾸려면 트리에서 노트를 마우스 오른쪽 버튼으로 클릭하고 "이름 바꾸기"를 선택합니다. 노트를 옮기려면 같은 지식 베이스의 다른 폴더로 끌어다 놓습니다. "삭제"를 선택하면 노트가 지식 베이스의 휴지통으로 이동합니다.
폴더를 열어 둔 상태에서 "이름 변경 또는 이동"을 선택하면 지식 베이스 루트를 기준으로 한 상대 경로로 폴더를 옮깁니다. 이때 상위 폴더가 이미 있어야 합니다. 노트나 폴더를 옮기면 같은 지식 베이스의 다른 노트에 있는 링크도 갱신되며, 링크 텍스트는 유지되고 코드는 변경되지 않습니다.
삭제한 항목은 지식 베이스 안의 .vkb-trash 폴더로 이동합니다. "휴지통"을 열고 "복원"을 클릭하면 항목을 되돌릴 수 있으며, 같은 이름의 기존 파일을 덮어쓰지 않습니다.
태그는 본문의 #tag와 YAML의 tags 목록 또는 배열에서 가져옵니다.
노트에 붙여 넣은 이미지는 노트 옆의 assets 폴더에 저장됩니다.

페이지가 표시되어 있는 동안 트리와 목록은 약 5초마다 새로 고쳐지며, 창이 다시 포커스를 받을 때도 새로 고쳐집니다. 열려 있는 문서 탭은 다른 프로그램이 변경한 내용을 감지하고 다시 불러오기를 제안합니다.

지식 베이스 페이지, 대화 상자, 가져오기 기록, 검색, 검색 범위, 태그, 정렬, 빠른 열기에는 모두 고유한 URL이 있으므로 페이지를 새로 고치거나 브라우저의 뒤로 및 앞으로 버튼을 사용할 수 있습니다. 저장하지 않은 텍스트와 양식 입력은 URL에 포함되지 않습니다.

검색

홈 페이지: 세션 지식 베이스와 모든 로컬 지식 베이스를 한 번에 검색하고 결과를 출처별로 묶어 표시합니다. 보관된 세션은 포함되지 않습니다.
오른쪽 패널: 트리 위의 "노트 검색…"은 모든 로컬 지식 베이스를 검색합니다.
지식 베이스 페이지: "노트 검색…"은 노트 이름, 경로, 본문을 검색합니다. "검색 범위"에서 "현재 지식 베이스"와 "모든 지식 베이스" 중 하나를 선택합니다.

여러 단어를 입력하면 모든 단어가 일치해야 합니다. 각 결과에는 해당 지식 베이스나 세션 그룹, 발췌문, 줄 번호, 일치 횟수, 노트가 링크하는 "관련 노트"가 표시되며, 이 중 어느 것을 클릭해도 해당 항목이 열립니다. 위쪽 및 아래쪽 화살표 키로 결과를 선택하고, Enter로 열고, Esc로 검색어를 지웁니다. 결과는 이름이나 경로의 일치 여부, 일치 횟수, 최근 수정 시각 순으로 정렬됩니다. 결과는 최대 100개까지 표시되며, 그보다 많으면 목록 끝에 "앞부분의 결과만 표시합니다. 검색어를 좁히면 나머지를 확인할 수 있습니다."가 표시됩니다.

VelaTerm은 먼저 정확히 일치하는 항목을 찾고, 그런 항목이 없을 때만 유사 일치로 전환하여 "정확히 일치하는 항목이 없습니다. 유사한 결과를 표시합니다."를 표시합니다. 유사 일치는 라틴 문자와 숫자로 이루어진 단어에만 적용되며, 순서대로 나오는 글자(knwl로 knowledge 검색), 머리글자(kb로 knowledge base 검색), 작은 오타(4자 이상인 단어는 1개, 8자 이상인 단어는 2개까지 허용하며, knoledge로 knowledge 검색)를 인식합니다. 중국어를 비롯한 라틴 문자 이외의 텍스트는 정확히 일치하는 항목만 찾습니다.

링크와 기존 파일 호환성

VelaTerm은 흔히 쓰이는 [[note]], [[folder/note|label]], [[note#heading]] 형식과 표준 Markdown 상대 링크, ![[image.png]]를 인식합니다. 이 링크는 노트를 옮길 때 링크를 갱신하고, 검색 결과에 "관련 노트"를 표시하며, 아래의 vkb 명령을 실행할 때 사용됩니다. 편집기에서 [[…]] 링크는 일반 텍스트로 표시됩니다. 이름이 같은 파일이 여러 개 있으면 대상이 하나로 정해질 때만 짧은 링크를 해석하므로, 그렇지 않은 경우에는 폴더 경로를 함께 적습니다.

파일은 일반 Markdown으로 유지되며, YAML 머리말도 파일에 그대로 남습니다. 편집기의 소스 모드에서는 머리말이 파일 내용 그대로 표시됩니다. UTF-8이 아니거나 5MiB보다 큰 Markdown 파일은 노트 목록에 표시되지 않고 "건너뛴 파일"로 집계됩니다. 지식 베이스에는 파일과 폴더를 최대 50,000개까지 둘 수 있으며, 이보다 큰 폴더는 열 수 없고 "파일 또는 선택한 항목이 보관함의 허용 범위를 초과합니다."가 표시됩니다. 심볼릭 링크는 따라가지 않습니다.

이 기능들은 로컬 파일, 폴더, Markdown, 링크, 검색을 다루는 일상적인 작업을 지원합니다. Obsidian 플러그인, 테마, Canvas, 블록 참조, 노트 임베드, YAML 별칭은 지원하지 않으며, 해당 파일은 변경하지 않고 그대로 둡니다. 파일 구조와 링크 문법은 Obsidian 문서의 보관소, 내부 링크, 첨부 파일 항목을 참조하십시오.

세션 지식 베이스에서 복사하기와 에이전트 조회

세션 지식 베이스에서 항목을 열고 "로컬 보관함에 복사"를 선택한 다음, 대상 지식 베이스와 파일 이름을 지정합니다. 복사본은 독립된 Markdown 노트이며, 원래 항목과 출처 스냅샷, 수정 이력은 그대로 유지됩니다.

VelaTerm 세션에서는 사용자나 에이전트가 vkb로 등록된 로컬 지식 베이스를 읽을 수 있습니다.

vkb notes "reading notes"
vkb note <knowledge-base-ID> "reading/how-to-take-notes.md"
vkb search "architecture decision"

notes는 현재 백엔드에 등록된 모든 로컬 지식 베이스를 검색합니다. 각 결과에는 vaultId, vaultName, path, absolutePath, line, matches, score, matched(실제로 일치한 텍스트), related(이 노트가 링크하는 노트), summary(일치 부분 주변의 텍스트)가 포함됩니다. 응답에는 total, hasMore, unavailable(읽을 수 없었던 지식 베이스), fuzzy(유사 일치 결과인지 여부)도 포함됩니다. 결과는 최대 100개까지 반환됩니다.
note는 노트의 본문, 개요, 링크, 백링크, 태그를 반환합니다.
search는 세션 지식 베이스와 로컬 노트에서 일치하는 항목을 반환하며, 코드 인덱스가 있으면 코드 그래프의 결과도 반환합니다(코드 그래프 및 지식 베이스 참조).

이 명령들은 읽기 전용이며 노트를 변경하지 않습니다. 또한 VelaTerm은 지식 베이스의 내용을 세션에 자동으로 추가하지 않습니다.

저장 방식과 로그

노트와 첨부 파일의 원본은 디스크에 있는 파일입니다. 애플리케이션 데이터베이스(kb_* 테이블)에는 등록된 지식 베이스 목록, 휴지통 기록, 가져오기 기록, 다시 만들 수 있는 검색 캐시만 저장됩니다. 세션 지식 베이스는 별도의 memory_* 테이블을 사용합니다.

열기, 쓰기, 이동, 삭제, 복원, 가져오기는 작업 ID, 개수, 소요 시간과 함께 런타임 로그에 기록되며, 노트 내용은 기록되지 않습니다. 이 로그 줄은 knowledge 이벤트를 사용하며, VLX_LOG_DIR이 설정되지 않은 경우 VLX_KNOWLEDGE_LOG_DIR로 로그 디렉터리를 지정합니다. 가져오기 기록은 데이터베이스에 저장되고 "가져오기 기록" 페이지에 표시됩니다. 지식 베이스를 완전히 백업하려면 지식 베이스 폴더와 애플리케이션 데이터를 모두 백업합니다. 휴지통 기록과 가져오기 기록은 애플리케이션 데이터에 들어 있습니다.