🔥 04. OpenViking: 에이전트용 컨텍스트 DB

OpenViking은 메모리, 리소스, 스킬을 한꺼번에 관리하는 에이전트용 컨텍스트 DB다. 벡터DB 하나 더 붙이는 느낌보다, 에이전트가 읽는 재료를 파일시스템처럼 계층적으로 관리하자는 제안에 가깝다.

이 레포는 4위 · ⭐ +10.2K로 회자된 프로젝트다. 별 숫자만 보면 유행처럼 보일 수 있지만, 실제로는 개발자들이 지금 어디에 시간을 쓰고 있는지를 꽤 솔직하게 드러낸다. 에이전트 프로젝트가 커질수록 제일 먼저 터지는 문제가 컨텍스트다. 메모리는 한쪽, 문서는 한쪽, 스킬은 또 다른 곳에 흩어져 있으면 디버깅이 어렵다. OpenViking은 이 흩어진 재료를 파일시스템 패러다임으로 묶어 보여주기 때문에, “에이전트의 뇌를 관리한다”는 감각을 직관적으로 준다.

flowchart LR
A[문제] --> B[openviking]
B --> C[설치]
C --> D[최소 실험]
D --> E[업무 적용 판단]

칠판 판서형 치트시트

• 이 레포의 한 줄 키워드는 openviking다.
• 이번 보강에서는 설치와 사용 순서를 공식 README 기준으로 더 촘촘하게 정리했다.
• 읽을 때는 전제 조건 → 설치 → 첫 실행 → 검증 순서로 보면 된다.
• “대단해 보인다”보다 “내 업무에서 반복 비용을 줄이는가”를 먼저 본다.

이 레포를 한 줄로 보면

OpenViking은 메모리, 리소스, 스킬을 한꺼번에 관리하는 에이전트용 컨텍스트 DB다. 벡터DB 하나 더 붙이는 느낌보다, 에이전트가 읽는 재료를 파일시스템처럼 계층적으로 관리하자는 제안에 가깝다.

왜 지금 이 레포가 뜨는가

에이전트 프로젝트가 커질수록 제일 먼저 터지는 문제가 컨텍스트다. 메모리는 한쪽, 문서는 한쪽, 스킬은 또 다른 곳에 흩어져 있으면 디버깅이 어렵다. OpenViking은 이 흩어진 재료를 파일시스템 패러다임으로 묶어 보여주기 때문에, “에이전트의 뇌를 관리한다”는 감각을 직관적으로 준다.

레포 안에서 먼저 볼 것

• L0/L1/L2 계층 로딩 구조로 필요한 문맥만 단계적으로 불러오는 방식
• 메모리·리소스·스킬을 통합 관리하는 파일시스템형 인터페이스
• 검색 경로를 시각화해 왜 이 문맥이 선택됐는지 추적하는 관찰성 기능

설치 전에 확인할 것

• Python 3.10+
• Go 1.22+ (AGFS 빌드용)
• GCC 9+ 또는 Clang 11+
• Embedding 모델과 VLM 모델에 쓸 API 키

설치 방법

공식 확인 링크

• GitHub README: https://github.com/volcengine/OpenViking
• 공식 문서: https://www.openviking.ai/docs
• 서버/배포 가이드 링크는 README의 quickstart server 섹션에 연결돼 있다.

패키지와 CLI 설치

서버/라이브러리 본체는 Python 패키지로 설치한다.

pip install openviking --upgrade --force-reinstall

CLI는 Rust 버전이 별도로 있다.

curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/crates/ov_cli/install.sh | bash

또는 소스에서 직접 설치할 수 있다.

cargo install --git https://github.com/volcengine/OpenViking ov_cli

설정 파일 만들기

OpenViking은 서버 설정(ov.conf)과 CLI 설정(ovcli.conf)을 먼저 잡아야 한다. 서버 설정 파일 예시 경로는 ~/.openviking/ov.conf다.

{
  "storage": { "workspace": "/home/your-name/openviking_workspace" },
  "embedding": {
    "dense": {
      "api_base": "<api-endpoint>",
      "api_key": "<your-api-key>",
      "provider": "<provider-type>",
      "dimension": 1024,
      "model": "<embedding-model>"
    }
  },
  "vlm": {
    "api_base": "<api-endpoint>",
    "api_key": "<your-api-key>",
    "provider": "<provider-type>",
    "model": "<vlm-model>"
  }
}

그다음 환경변수를 연결한다.

export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf

CLI는 보통 아래처럼 ~/.openviking/ovcli.conf를 쓴다.

{
  "url": "http://localhost:1933",
  "timeout": 60.0,
  "output": "table"
}

export OPENVIKING_CLI_CONFIG_FILE=~/.openviking/ovcli.conf

첫 실행

README의 첫 예제는 아래 순서다.

openviking-server

다른 터미널에서 CLI를 붙인다.

ov status
ov add-resource https://github.com/volcengine/OpenViking
ov ls viking://resources/
ov tree viking://resources/volcengine -L 2
ov find "what is openviking"
ov grep "openviking" --uri viking://resources/volcengine/OpenViking/docs/zh

Bot 기능까지 보려면 아래처럼 확장 설치 후 실행할 수 있다.

pip install "openviking[bot]"
openviking-server --with-bot
ov chat

사용 방법

1. 먼저 workspace를 비워진 테스트 폴더로 정하고, 리소스 1개만 ov add-resource로 넣는다.
2. 그다음 ov ls, ov tree, ov find, ov grep 순으로 파일시스템형 탐색 흐름을 체험한다.
3. 여기서 중요한 건 검색 결과만이 아니라 경로 구조가 이해되는지다. OpenViking의 장점은 이 트랙을 눈에 보이게 만든다는 점이다.
4. 리소스 탐색이 안정되면 그다음에야 실제 에이전트나 bot 기능과 연결한다.

README 기준 가장 안전한 첫 실험은 서버 한 대 + 리소스 한 개 + 검색 4종이다. 한 번에 메모리, bot, 대규모 문서셋까지 올리기보다 ov add-resource → ov ls → ov find → ov grep만 먼저 해보는 편이 구조를 이해하기 쉽다.

어디에 바로 써먹을 수 있나

사례 A. 장기 실행 에이전트

하루 종일 문서를 읽고 작업하는 에이전트는 세션이 길어질수록 문맥이 비대해진다. OpenViking 같은 계층형 컨텍스트 저장소를 쓰면 필요 없는 정보를 덜 올리고, 자주 쓰는 재료를 구조화해 재활용할 수 있다.

사례 B. 팀 지식베이스 운영

팀 규칙, 제품 설명, 운영 기록, 스킬 파일이 제각각 놀고 있다면 파일시스템처럼 묶어두는 방식이 디버깅에 유리하다. “왜 이런 답을 했지?”를 추적할 때 경로를 보는 것이 큰 도움이 된다.

처음 해볼 최소 실험

1. Python 패키지와 CLI를 설치한다.
2. ov.conf와 ovcli.conf를 최소 설정으로 만든다.
3. openviking-server를 띄우고 ov status가 응답하는지 본다.
4. GitHub 레포 하나를 리소스로 추가해 검색/트리/grep 흐름을 검증한다.

검증 포인트는 간단하다. 적용 전후를 비교할 때는 모델 체감보다 불필요한 문맥 로드 감소, 검색 실패 감소, 디버깅 속도를 봐야 한다.

볼 때 주의할 점

• 설정 항목이 제법 많아 처음부터 풀세팅하면 피곤하다.
• 좋은 구조가 있어도 넣는 문서 품질이 낮으면 결과는 나빠진다.
• 모델·임베딩·스토리지 설정이 동시에 얽혀 있어 PoC 범위를 작게 잡는 편이 좋다.

다음 읽기

• 🔥 08. Context Hub
• 🔥 09. Deep Agents
• 64. 멀티에이전트보다 컨텍스트 엔지니어링

이 글은 AI를 활용해 초안을 정리했고, GitHub README와 공식 링크를 다시 확인해 실무 적용 관점으로 풀어썼다.