세션 지식 베이스

이 장에서는 "세션 지식 베이스", "정리 기록", "보관된 세션"을 설명합니다. 로컬 Markdown 파일의 관리, 편집, 가져오기는 로컬 지식 베이스에서 설명합니다.

세션 지식 베이스는 지식, 결정 사항, 제약 조건, 교훈을 프로젝트 → 세션 → 항목 구조로 정리하여 저장합니다. 생성된 항목은 별도로 저장되므로 출처 세션이 바뀌어도 변경되지 않으며, 직접 편집할 수 있습니다. 세션 지식 베이스는 현재 연결된 VelaTerm 백엔드에 속하며, 그 백엔드의 모든 프로젝트와 세션이 함께 사용합니다. 다른 서버에 연결하면 그 서버의 지식 베이스가 표시됩니다.

세션 지식 베이스는 세션 내용 검색과 별개입니다. 세션 검색은 원래 대화에서 텍스트를 찾고, 지식 베이스는 저장된 항목만 검색합니다. VelaTerm은 사용자가 요청할 때 항목을 정리하고 저장하고 표시할 뿐이며, 새 세션에 항목을 자동으로 추가하지 않습니다.

세션 정리하기

사이드바의 세션이나 세션 탭을 마우스 오른쪽 버튼으로 클릭하고 "세션 지식 베이스로 정리"를 선택합니다. 보관된 세션에서도 같은 작업을 사용할 수 있습니다.
"에이전트"를 선택합니다. Claude, Codex, Grok Build, OpenCode, Pi, OMP 중에서 선택할 수 있습니다. VelaTerm은 설정 ▸ 에이전트에 지정된 실행 파일 경로를 사용하거나 PATH에서 프로그램을 찾습니다. 찾을 수 없는 에이전트는 "설치 또는 설정되지 않음"으로 표시되며 선택할 수 없습니다.
필요하면 "모델(선택 사항)"과 "사고 강도"를 선택합니다. "기본 모델"과 "에이전트 기본값"을 선택하면 에이전트 자체 설정을 따릅니다. 모델 목록은 세션을 만들 때 사용하는 목록과 같으며, 사고 강도는 이를 지원하는 모델에서만 표시됩니다. VelaTerm은 마지막으로 사용한 에이전트, 모델, 사고 강도를 기억합니다. 에이전트는 로그인되어 있어야 하며, 선택한 모델에 접근할 수 있어야 합니다.
"정리 후 저장"을 클릭합니다. 선택한 에이전트가 세션의 텍스트를 받아 자체 모델 설정으로 처리합니다.
"정리 기록"에서 작업 진행 상황을 확인합니다. 대화 상자를 닫아도 작업은 중지되지 않습니다.

VelaTerm은 에이전트의 대화 기록이 있으면 그 기록을 읽습니다. 대화 기록이 없으면 세션의 터미널 녹화(터미널 사용법 참조)에서 터미널 제어 코드를 제거하여 사용합니다. 둘 다 읽을 수 없으면 "이 세션에는 읽을 수 있는 대화가 없습니다."라고 알립니다. 터미널 녹화에는 화면에 보였던 텍스트가 담기며 다시 그려진 내용이 포함될 수 있으므로, 정리하는 에이전트는 이러한 출력을 검증된 사실로 취급해서는 안 됩니다.

출처 스냅샷에는 정리를 위해 읽은 텍스트가 저장됩니다. 프로젝트 이름과 세션 이름은 세션이 처음 추가될 때 저장되며, 이후 다른 곳에서 프로젝트나 세션의 이름을 바꾸거나 옮기거나 보관하거나 삭제해도 갱신되지 않습니다.

세션을 다시 정리하면 세션을 다시 읽고, 이전에 그 세션에서 생성한 항목을 직접 편집한 내용까지 포함하여 교체합니다. 텍스트와 모델 설정이 바뀌지 않았더라도 마찬가지입니다. 세션에 아직 끝나지 않은 작업이 있으면 새 작업이 그 작업을 대체합니다. 이전 작업이 이미 실행 중이면 이전 프로세스가 중지된 뒤 새 작업이 자동으로 시작되며("이 세션의 이전 작업이 중지되면 자동으로 시작됩니다."), 이전 작업은 기록에 남습니다.

정리 과정

정리는 세 단계로 진행되며, 각 단계가 작업의 진행 상황으로 표시됩니다.

주제 추출 중: 세션을 여러 구간으로 나누어 읽고 재사용할 수 있는 지식을 추출합니다. 주제는 이 작업 안에서만 병합하며, 다른 세션의 항목이나 이전에 직접 편집한 내용은 사용하지 않습니다.
지식 통합 중: 주제별로 추출된 내용을 합치면서 지식, 제약 조건, 불확실한 부분을 유지합니다. 에이전트는 나중에 나온 수정과 모순을 반영하고 결론을 지어내지 않도록 지시를 받습니다.
항목 저장 중: VelaTerm이 필드, 출처, 링크, 버전을 검사한 뒤 하나의 데이터베이스 트랜잭션으로 세션의 생성된 항목을 교체합니다. 제목이 같은 항목은 기존 항목으로 유지되며 새 수정본이 추가됩니다. 더 이상 생성되지 않은 항목은 수정 이력과 함께 삭제되며, 이 항목을 가리키던 링크도 제거됩니다. 정리에 성공했지만 재사용할 수 있는 내용을 찾지 못하면 세션에서 이전에 생성한 항목이 삭제됩니다("재사용할 수 있는 지식이 추출되지 않았습니다. 이 세션에서 이전에 생성한 항목이 삭제되었습니다."). 검사에 실패하거나, 작업이 취소되거나, 버전 충돌이 발생하면 이전 항목이 그대로 유지되며, 일부 결과만 저장되는 일은 없습니다.

에이전트는 구조화된 내용을 반환하고, 데이터베이스 변경은 모두 VelaTerm이 수행합니다. 항목은 서로 링크되며, "이 항목을 참조하는 항목" 목록은 자동으로 계산됩니다. 원래 세션을 삭제해도 출처 스냅샷과 수정 이력은 계속 사용할 수 있습니다.

정리된 지식의 품질은 여전히 사용자가 판단해야 합니다. 잘못된 내용이 있으면 항목을 편집하거나 이전 수정본을 복원합니다. 복원하면 새 수정본이 만들어지며, 교체된 버전도 그대로 보존됩니다.

정리 기록

"정리 기록"에는 정리 작업이 페이지당 40개씩 나열됩니다. 각 작업에는 에이전트, 모델(선택하지 않았으면 "기본 모델"), 사고 강도, 시각이 표시되며, 실행 중인 작업에는 현재 단계("주제 추출 중", "지식 통합 중", "항목 저장 중")도 표시됩니다. 작업 상태는 "시작 대기 중", "진행 중", "취소 중", "완료", "실패", "취소됨" 중 하나이며, 목록에서 작업의 "출처 스냅샷"과 생성된 항목을 열 수 있습니다.

"취소"는 대기 중이거나 실행 중인 작업을 중지합니다. 실행 중인 작업은 에이전트 프로세스가 중지될 때까지 "취소 중"으로 표시됩니다. 작업을 취소해도 출처 스냅샷은 삭제되지 않습니다.
"다시 시도"는 실패하거나 취소된 작업을 같은 출처 스냅샷, 모델, 사고 강도로 다시 시작합니다. 기록에는 작업을 만들 때의 설정이 표시됩니다. 기본값이 표시되어 있으면 에이전트가 직접 결정했다는 뜻이며, VelaTerm이 특정 모델로 확정했다는 뜻은 아닙니다.

서로 다른 세션은 동시에 정리할 수 있습니다. 세션마다 한 번에 하나의 작업만 실행되며, 같은 세션을 다시 제출하면 대기열을 만들지 않고 가장 최근에 제출한 대기 작업만 남깁니다. 대기 중인 작업은 데이터베이스에 저장되어 앱을 다시 시작한 뒤에도 이어서 진행됩니다. 실행 중인 작업이 2분 동안 진행 상황을 보고하지 않으면 중단된 것으로 표시됩니다("정리 작업이 중단되었습니다. 저장된 출처 스냅샷으로 재시도할 수 있습니다."). 대기한 시간은 작업의 제한 시간에 포함되지 않습니다.

정리가 진행되는 동안에도 항목을 편집할 수 있습니다. 작업 중에 누군가 세션의 생성된 항목을 편집하거나 삭제하면 작업은 버전 충돌을 보고하고, 사용자가 변경한 내용은 유지되며, 이후 다시 시도할 수 있습니다. 서로 다른 세션에서는 같은 항목 제목을 사용할 수 있지만, 한 세션 안에서는 제목이 고유해야 합니다.

항목 탐색과 관리

오른쪽 패널에서 지식 베이스를 열고(로컬 지식 베이스 참조) "세션 지식 베이스"를 프로젝트, 세션, 항목 순으로 펼칩니다. 프로젝트나 세션을 클릭하면 해당 항목 목록이 표시되고, 항목을 클릭하면 내용을 읽을 수 있습니다. "상위 단계로 이동" 버튼을 클릭하면 상위 페이지로 돌아갑니다.

목록 페이지에서는 검색("항목 제목과 본문 검색…"), 태그 필터("모든 태그"), "최근 수정순" 또는 "제목순" 정렬, 새로 고침을 사용할 수 있습니다. 검색 대상은 제목, 요약, 본문, 태그입니다. 여러 단어를 입력하면 모든 단어가 일치해야 하며, 제목이 일치하는 결과가 먼저 표시되고, 각 결과에는 직접 관련된 항목도 함께 표시됩니다. 정확히 일치하는 항목이 없으면 로컬 지식 베이스 검색과 마찬가지로 유사 일치 결과가 표시됩니다.
세션의 항목은 페이지당 40개씩 표시됩니다. 프로젝트 목록과 세션 목록에는 이 제한이 적용되지 않으며, 트리의 긴 목록에는 "더 불러오기"가 표시됩니다.
항목 페이지에는 Markdown 본문, "관련 항목", "이 항목을 참조하는 항목", "출처", "수정 이력"이 표시됩니다. 본문을 그 자리에서 편집하고 ⌘S / Ctrl+S로 저장할 수 있으며, "편집"으로 제목, 요약, 태그를 수정하거나 "Markdown 내보내기", "로컬 보관함에 복사", "삭제"를 사용할 수 있습니다. 항목을 삭제하면 수정 이력도 함께 삭제되지만, 출처 세션과 스냅샷은 유지됩니다.
"새 항목"으로 항목을 직접 만들 수 있으며, 이렇게 만든 항목은 "직접 만든 항목" 그룹에 표시됩니다.

트리에서는 다음과 같은 관리 작업도 할 수 있습니다.

항목을 마우스 오른쪽 버튼으로 클릭하여 이름을 바꾸거나 삭제합니다. 항목을 다른 세션으로 끌어다 놓으면 소속 세션이 바뀝니다.
프로젝트 그룹이나 세션 그룹을 마우스 오른쪽 버튼으로 클릭하여 이름을 바꾸거나 그룹의 항목을 삭제합니다. 그룹 이름을 바꾸면 실제 프로젝트나 세션의 이름도 바뀝니다. 그룹을 삭제하면 그룹의 지식 항목만 삭제되며, "이 그룹의 지식 항목 N개를 모두 삭제하시겠습니까? 프로젝트나 세션 자체는 유지됩니다."라는 확인 메시지가 표시됩니다.
세션을 다른 프로젝트로 끌어다 놓으면 실제 세션이 그 프로젝트로 이동합니다.
"직접 만든 항목", "이전에 병합된 항목", "원본 프로젝트를 알 수 없음" 그룹은 이름을 바꿀 수 없습니다.

항목 페이지, 편집 양식, 출처 스냅샷, 수정본, 정리 대화 상자, 정리 기록에는 모두 고유한 URL이 있으며, 선택한 프로젝트, 세션, 검색어, 필터, 정렬, 페이지도 URL에 포함됩니다.

보관된 세션

보관된 세션은 지식 베이스에서 관리합니다. 지식 베이스 트리에는 "세션 지식 베이스" 옆에 "보관된 세션"이 표시되며, 보관된 세션이 원래 속했던 프로젝트별로 묶여 있습니다. 사이드바 상단의 "보관된 세션" 버튼을 클릭해도 같은 위치가 열립니다.

주 영역에는 모든 보관된 세션이 프로젝트별로 나열됩니다. 세션을 열면 두 개의 탭이 표시됩니다. "대화" 탭에는 전체 대화가, "지식 항목" 탭에는 이 세션에서 생성된 항목이 표시됩니다.
"보관 내용 검색…"은 보관된 세션의 전체 텍스트만 검색하며, 일치 항목을 세션별로 묶어 표시합니다.
보관된 세션을 열면 "일반 세션으로 복원", "세션 지식 베이스로 정리", "전체 컨텍스트를 Markdown으로 내보내기"(Claude 및 Codex 세션), "영구 삭제 (녹화 포함)"를 사용할 수 있습니다. 영구 삭제는 확인 절차 없이 즉시 적용됩니다.
항목과 출처 스냅샷은 별도로 저장되므로, 세션을 보관하거나 복원하거나 삭제해도 기존 지식 항목은 변경되지 않습니다. 복원한 세션에서는 대화를 이어서 진행할 수 있습니다.

이전 버전의 데이터

VelaTerm이 이전 데이터를 업그레이드할 때, 출처 세션이 하나뿐인 항목은 해당 세션에 배정되었습니다. 이미 여러 세션의 내용을 합친 항목은 "이전에 병합된 항목" 그룹에 그대로 보존되었으며, 이러한 항목은 분할되지 않고 해당 세션 중 하나를 다시 정리해도 교체되지 않습니다. 출처가 없는 항목은 "직접 만든 항목"으로 옮겨졌습니다. 아직 남아 있던 프로젝트 정보는 업그레이드할 때 한 번 채워졌으며, 프로젝트를 확인할 수 없는 출처는 원래 세션 이름 및 스냅샷과 함께 "원본 프로젝트를 알 수 없음" 아래에 표시됩니다.

데이터와 제한 사항

세션 지식 베이스는 세션 검색 인덱스와 별도로 애플리케이션의 SQLite 데이터베이스(memory_* 테이블)에 저장됩니다. 인터페이스는 화면에 표시하는 내용과 저장하지 않은 양식 입력만 보유하며, 유효성 검사, 버전 확인, 중복 감지, 모든 쓰기 작업은 백엔드에서 처리합니다.

출처 하나는 최대 2,000,000자, 추출 구간 하나는 최대 24,000자, 모델 입력 한 번은 최대 350,000자, 항목 본문 하나는 최대 200,000자까지 허용됩니다.
에이전트 호출 한 번은 최대 10분 동안 실행될 수 있으며, 각 출력 스트림은 최대 8MiB까지 출력할 수 있습니다.
OpenCode, Pi, OMP의 경우 한 번의 호출로 전달하는 텍스트는 128KiB로 제한됩니다.
에이전트가 예상한 구조와 맞지 않는 출력을 반환하면 VelaTerm은 최대 세 번까지 다시 요청합니다.

이 제한을 넘으면 작업이 명확하게 실패하며("출처, 컨텍스트 또는 출력이 지원 크기를 초과했습니다. 내용을 잘라내거나 항목을 저장하지 않았습니다."), 내용을 잘라서 저장하는 일은 없습니다.

정리 작업은 애플리케이션 데이터 디렉터리의 logs/runtime-*.log에 기록됩니다. VLX_LOG_DIR이 설정되지 않은 경우 VLX_MEMORY_LOG_DIR로 로그 디렉터리를 지정합니다. VLX_MEMORY_LOG_LEVEL=error로 설정하면 오류만 기록하고, off로 설정하면 이 모듈의 로그를 끕니다. 로그에는 작업과 단계, 입력 및 출력 개수, 소요 시간, 문자 수, SHA-256 다이제스트, 토큰 사용량이 기록됩니다. 전체 프롬프트, 출처 텍스트, 모델 응답, 자격 증명, 오류 출력은 기록하지 않으며, 원본 자료는 출처 스냅샷에 보관됩니다.

코드 그래프 연결

지식 항목은 코드 심볼에 연결할 수 있으며, 항목 페이지의 "코드 참조"를 클릭하면 코드 그래프로 이동합니다. 연결된 파일이 변경되면 항목에 검토가 필요하다는 표시가 나타나며, 검토를 확인해도 항목의 텍스트는 변경되지 않습니다. 세션의 에이전트는 vkb로 코드와 항목을 조회할 수 있습니다. 코드 그래프 및 지식 베이스를 참조하십시오.