claudekit / tools / openviking
[ Tool · Claude Code Utilities ]

OpenViking

에이전트의 메모리, 참고 자료, 스킬을 하나의 가상 파일시스템에 모아 두는 오픈소스 컨텍스트 데이터베이스. Claude Code에 플러그인으로 연결하면 세션이 끝나도 남는 장기 기억과 자료 검색이 생깁니다.

volcengine/OpenViking ·updated
$ pip install openviking --upgrade copy

ByteDance 볼케이노 엔진(Volcengine)이 공개한 오픈소스 프로젝트(volcengine/OpenViking).

왜 필요한가?

Claude Code는 세션이 끝나면 대화 내용을 잊습니다. 프로젝트 문서나 사내 규칙은 매번 다시 붙여 넣어야 하고, 지난주에 정한 코딩 규칙을 이번 세션에서 다시 설명하게 됩니다. 기억은 설정 파일에, 자료는 벡터 데이터베이스(문장을 숫자 배열로 바꿔 의미가 비슷한 것끼리 찾는 저장소)에, 스킬은 또 다른 곳에 흩어져 있어 한꺼번에 관리하기 어렵습니다. 공식 문서는 이 상태를 “Context Fragmentation: Memory in code, resources in vector databases, skills scattered everywhere”라고 정리합니다.

OpenViking은 이 세 가지를 viking://로 시작하는 하나의 가상 파일시스템에 담습니다. 에이전트는 결과만 돌려주는 검색 엔진에 질의하는 대신, ls, tree, find 같은 익숙한 명령으로 자기 컨텍스트를 직접 훑습니다.

무엇을 할 수 있나

공식 문서와 README가 안내하는 대표 작업입니다.

  • 저장소, 문서를 통째로 자료로 등록 — ov add-resource https://github.com/volcengine/OpenViking처럼 GitHub 저장소나 웹 페이지를 넣어 두면 의미 기반 검색 대상이 됩니다
  • 자료를 파일처럼 탐색 — ov ls, ov tree로 디렉터리를 훑고, ov find "what is openviking"으로 자연어 질문을 던지고, ov grep으로 특정 경로만 뒤집니다
  • 세션이 끝나면 취향과 경험이 남음 — 세션이 커밋된 뒤 사용자 선호와 에이전트 경험을 장기 메모리로 추출합니다. viking://user/{user_id}/memories/preferences/coding_habits 같은 경로에 쌓입니다
  • 여러 에이전트가 같은 기억을 공유 — Claude Code, Codex, Cursor, OpenCode, TRAE가 같은 서버에 붙어 하나의 컨텍스트를 씁니다
  • 검색 경로 확인 — 결과가 이상할 때 어떤 디렉터리를 거쳐 나온 답인지 경로가 남아 원인을 짚을 수 있습니다

근거: docs.openviking.ai, volcengine/OpenViking README.

핵심 기능

  • viking:// 가상 파일시스템

    메모리, 자료, 스킬에 각각 URI를 부여해 viking://resources/my_project/docs/api처럼 위치를 지정합니다. 무엇이 어디에 있는지가 경로로 드러나므로, 검색 결과를 짐작하지 않고 확인할 수 있습니다.

  • L0, L1, L2 계층 로딩

    등록 시점에 항목마다 L0(약 256자 요약), L1(약 4,000자 개요), L2(원본 전체)를 만들어 두고 필요한 깊이까지만 읽습니다. 관련 여부를 판단하는 데 원본 전체를 넣지 않으므로 입력 분량이 줄어듭니다.

  • 디렉터리 단위 재귀 검색

    의미 검색으로 점수가 가장 높은 디렉터리를 먼저 찾고, 그 안으로 한 단계씩 내려갑니다. 조각난 문장이 아니라 주변 맥락이 붙은 채로 결과가 나옵니다.

  • Claude Code 플러그인

    openviking-memory 플러그인은 네 지점에 붙습니다. 프롬프트 전에 관련 기억 주입, 응답 후 대화 턴 수집, 세션 시작 시 프로필과 메모리 목록 주입, 압축(compaction) 직전과 세션 종료 시 커밋. 서브에이전트에는 각각 독립된 메모리 세션이 할당됩니다.

  • 자동 회수, 자동 수집 스위치

    OPENVIKING_AUTO_RECALL과 OPENVIKING_AUTO_CAPTURE가 기본으로 켜져 있고, OPENVIKING_BYPASS_SESSION_PATTERNS로 특정 세션만 제외할 수 있습니다. /openviking-memory:ov로 서버 상태, 회수 횟수, 스위치 상태를 확인합니다.

  • 프로바이더 선택

    openviking-server init이 Volcengine, OpenAI, Codex OAuth, Kimi, GLM, 로컬 Ollama 중에서 고르도록 안내합니다. Ollama를 고르면 런타임 설치와 하드웨어에 맞는 모델 내려받기까지 처리합니다.

사용 방법

먼저 서버를 설치하고 초기 설정을 마칩니다. Python 3.10 이상이 필요합니다.

pip install openviking --upgrade
openviking-server init      # 프로바이더, 모델, ov.conf 설정 마법사
openviking-server doctor    # 설정 점검
openviking-server           # 서버 시작

Claude Code 플러그인은 설치 스크립트 한 줄로 붙일 수 있습니다.

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh)

직접 설치하려면 마켓플레이스를 추가합니다. 플러그인 방식은 Claude Code 2.0 이상에서 동작하며, 그 이전 버전은 Hook 방식으로 넘어갑니다.

claude plugin marketplace add https://raw.githubusercontent.com/volcengine/OpenViking/main/.claude-plugin/marketplace.json
claude plugin install openviking-memory@openviking

연결 정보는 ~/.openviking/ovcli.conf에 url과 api_key로 적습니다. 설정 파일이 없으면 플러그인이 http://127.0.0.1:1933을 기본값으로 씁니다. Claude Code에서 /plugins 목록에 openviking-memory가 보이고 /mcp에 OpenViking 항목이 뜨면 연결된 것입니다.

터미널에서 자료를 다루는 명령입니다.

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

설치 전에 먼저 보고 싶다면 OpenViking Studio 데모를 브라우저에서 열 수 있습니다.

알아두면 좋은 점

  • 설치 부담이 있습니다 — 플러그인만 깔아서는 동작하지 않습니다. Python 3.10 이상, 상시 구동되는 서버, LLM과 임베딩(문장을 숫자 배열로 바꾸는 처리) 프로바이더 설정이 먼저입니다. 명령 한 줄로 끝나는 도구는 아닙니다
  • OpenViking Helper (베타) — macOS와 Windows x64용 데스크톱 콘솔로, Claude Code, Codex, Cursor, Trae, OpenCode를 찾아 플러그인, MCP, Hook 설정을 대신 잡아 줍니다. 세션 기록에서 회수와 주입이 언제 일어났는지 확인하는 용도로도 씁니다
  • 벤치마크는 조건과 함께 봐야 합니다 — 공개된 LoCoMo 결과는 Claude Code 기본 메모리 57.21%에서 OpenViking 연결 시 80.32%입니다. 다만 이 측정은 Doubao 2.0 Pro를 모델로, Doubao-embedding-vision-251215를 임베딩으로 쓴 조건이라 다른 조합에서 같은 수치가 나온다고 보기는 어렵습니다
  • 데이터가 나가는 지점 — 서버는 내 환경에서 돌지만, 등록한 자료의 요약과 임베딩 생성은 설정한 프로바이더 API를 거칩니다. 외부로 내보내고 싶지 않으면 Ollama 같은 로컬 프로바이더를 고릅니다
  • 상용판은 별개입니다 — 볼케이노 엔진이 운영하는 SaaS와 자체 배포 상용판이 있지만, README는 오픈소스판에 기능 제한, 계정 요구, 활성화 키가 없다(“no feature gates, no account required, no activation key”)고 밝히고 있습니다
  • 라이선스 — AGPL-3.0. VLDB 2026에 채택된 VikingMem 논문(arXiv:2605.29640)에서 설명한 핵심 기능의 일부를 공개한 것입니다
§ 6

See also

same category · curated
[01]
[Plugin] fluent-korean · Claude Code가 조사와 어미를 생략한 축약형 한국어 대신 의미가 분명한 문장을 출력하도록 지시하는 output-style 플러그인. 결과를 고치는 것이 아니라 시스템 프롬프트 층위에서 미리 규율합니다. 코딩 지침을 유지하는 판과 제거한 판 두 가지를 제공합니다.
tool · claudekit.io / tools / fluent-korean
[02]
[Tool] Herdr · Rust로 작성된 단일 바이너리의 터미널 네이티브 에이전트 멀티플렉서. tmux식 세션 유지와 패널 분할에 에이전트 상태 추적(idle, working, blocked, done)을 더해, Claude Code를 포함한 여러 CLI 에이전트를 한 화면에서 관리합니다. Herdr는 Claude Code를 자동 감지해 직접 통합(direct integration) 설치 프롬프트를 띄우고, 승인하면 풀 상태 감지, 로컬 소켓 API를 통한 시맨틱 상태 전달, 재시작 후 에이전트 세션 복원이 동작합니다.
tool · claudekit.io / tools / herdr
[03]
[Tool] CC Workflow Studio · 캔버스 위에서 AI 에이전트 워크플로를 시각적으로 설계해, Claude Code·Cursor·Copilot 등 에이전트가 바로 실행할 수 있는 Markdown(skills·commands·agents)으로 내보내는 VS Code 익스텐션. MCP 서버가 내장돼 'Edit with AI'로 자연어 수정도 가능.
tool · claudekit.io / tools / cc-wf-studio
§ 7

자주 묻는 질문

자주 묻는 질문
§ 7.1
OpenViking은 무엇인가요?
에이전트의 메모리, 참고 자료, 스킬을 `viking://`로 시작하는 하나의 가상 파일시스템에 담는 오픈소스 컨텍스트 데이터베이스입니다. 에이전트가 벡터 데이터베이스에 질의하는 대신 `ls`, `tree`, `find` 같은 명령으로 자기 컨텍스트를 직접 훑습니다.
§ 7.2
Claude Code에 어떻게 연결하나요?
서버를 띄운 뒤 `openviking-memory` 플러그인을 설치합니다. 설치 스크립트 한 줄로 붙이거나, `claude plugin marketplace add`로 마켓플레이스를 추가한 다음 `claude plugin install openviking-memory@openviking`을 실행합니다. Claude Code 2.0 이상은 플러그인 방식, 그 이전 버전은 Hook 방식으로 동작합니다.
§ 7.3
설치에 무엇이 필요한가요?
Python 3.10 이상과 상시 구동되는 OpenViking 서버가 필요합니다. `openviking-server init`에서 Volcengine, OpenAI, Codex OAuth, Kimi, GLM, 로컬 Ollama 중 하나를 LLM과 임베딩 프로바이더로 설정해야 동작합니다.
§ 7.4
무료인가요? 라이선스는?
AGPL-3.0 오픈소스이며 README는 오픈소스판에 기능 제한, 계정 요구, 활성화 키가 없다고 밝히고 있습니다. 별도로 볼케이노 엔진이 운영하는 SaaS와 자체 배포 상용판이 있지만, 직접 배포해 쓰는 데는 필요하지 않습니다.
§ 7.5
내 데이터는 어디에 저장되나요?
서버가 내 환경에서 돌기 때문에 저장은 로컬에 이뤄집니다. 다만 등록한 자료의 요약과 임베딩 생성은 설정한 프로바이더 API를 거치므로, 외부로 내보내고 싶지 않다면 Ollama 같은 로컬 프로바이더를 고릅니다.
§ 7.6
Claude Code 말고 어떤 에이전트를 지원하나요?
공식 문서는 Codex, Cursor, OpenCode, TRAE, OpenClaw, Hermes, pi, LangChain/LangGraph, 일반 MCP 클라이언트용 연동 문서를 제공합니다. 같은 서버에 붙으면 여러 에이전트가 하나의 컨텍스트를 공유합니다.