OpenViking: AI Agent의 기억, 리소스, 스킬을 파일시스템처럼 다루는 컨텍스트 데이터베이스

AI Agent를 만들다 보면 어느 순간 이런 벽에 부딪힙니다.

대화 기록은 메모리 시스템에 들어가 있고, 문서는 벡터 DB에 들어가 있고, 툴 설명은 프롬프트 어딘가에 붙어 있고, 세션 상태는 또 별도 저장소에 흩어져 있습니다.
Agent가 똑똑해질수록 정작 개발자는 “이 Agent가 지금 무엇을 알고 있고, 왜 그걸 꺼냈는지”를 설명하기 어려워집니다.

OpenViking은 바로 이 지점을 정면으로 겨냥한 프로젝트입니다.
이 프로젝트는 단순한 벡터 검색 라이브러리가 아닙니다. OpenViking은 AI Agent가 사용하는 모든 컨텍스트를 파일시스템처럼 구조화해서 관리하자는 관점에서 출발한, 꽤 야심찬 Agent-native context database입니다. ByteDance의 Volcengine Viking 팀이 시작했고, 저장소 설명과 문서에서 메모리, 리소스, 스킬을 하나의 계층형 컨텍스트 시스템으로 통합하는 것이 핵심 목표라고 밝히고 있습니다. 저장소는 2026년 3월 14일 기준 약 9.1k stars를 기록하고 있습니다. (GitHub)

프로젝트 소개

OpenViking을 한 줄로 요약하면 이렇습니다.

“AI Agent를 위한 컨텍스트 파일시스템”

프로젝트 설명에서 OpenViking은 전통적인 RAG의 파편화된 벡터 저장 모델을 버리고, 파일 시스템 패러다임으로 메모리, 리소스, 스킬을 통합 관리한다고 말합니다. 즉, Agent가 알아야 할 정보를 “벡터 몇 개”가 아니라 디렉터리와 파일 구조로 이해하게 만듭니다. 이 구조 위에 의미 검색, 계층적 로딩, 세션 커밋, 메모리 추출 같은 기능이 붙습니다. (GitHub)

OpenViking이 다루는 컨텍스트는 크게 세 가지입니다.

• Resource: 문서, 메뉴얼, 코드 저장소 같은 외부 지식
• Memory: 사용자 선호, 사건, 패턴, 케이스 같은 장기 기억
• Skill: Agent가 호출할 수 있는 기능 정의와 실행 자산

이 세 가지를 viking://resources/..., viking://user/memories/..., viking://agent/skills/... 같은 URI로 다룹니다. 이 점이 굉장히 중요합니다. OpenViking은 “메모리 시스템”, “문서 검색기”, “툴 레지스트리”를 각각 따로 두지 않고, 전부 같은 인터페이스와 계층 구조로 통합합니다. (GitHub)

기술 스택 측면에서는 Python 3.10+ 기반 패키지로 제공되고, pdfplumber, readabilipy, markdownify, python-docx, python-pptx, openpyxl, openai, httpx 같은 의존성을 통해 문서 파싱, 의미 처리, API 통신을 수행합니다. 빌드에는 pybind11, cmake도 포함되어 있어 일부 성능 민감한 영역은 네이티브 확장과 연결될 가능성을 보여줍니다. 문서에서는 HTTP 서버와 CLI 재사용을 염두에 둔 서비스 계층 구조도 설명합니다. (GitHub)

왜 이 프로젝트가 등장했을까

OpenViking이 흥미로운 이유는 “벡터 DB 하나 더 만들자”가 아니라, Agent 시대의 컨텍스트 문제를 재정의하려 했기 때문입니다.

전통적인 RAG는 보통 이런 흐름입니다.

1. 문서를 chunk로 나눈다
2. 임베딩한다
3. 벡터 검색한다
4. 몇 개를 프롬프트에 붙인다

이 방식은 문서 검색에는 꽤 잘 맞습니다. 하지만 Agent 관점에서는 한계가 뚜렷합니다.

첫째, 컨텍스트가 파편화됩니다.
사용자 선호는 메모리 저장소에, 문서는 벡터 DB에, 스킬 설명은 시스템 프롬프트에, 세션 기록은 로그 DB에 흩어집니다.

둘째, 검색 과정이 블랙박스가 됩니다.
왜 이 문단이 선택됐는지, 어떤 디렉터리 맥락에서 올라왔는지, 더 상위 요약은 무엇인지 추적이 어렵습니다.

셋째, 토큰 비용이 비효율적입니다.
항상 L2 원문까지 끌어오면 비용이 커지고, 반대로 너무 잘게 쪼개면 문맥 손실이 커집니다.

넷째, 메모리와 리소스와 스킬이 같은 문제인데도 다른 방식으로 관리됩니다.
개발자 입장에서는 이게 가장 피곤합니다. 결국 Agent의 “뇌”를 여러 시스템 조합으로 억지로 흉내 내고 있는 셈이기 때문입니다.

OpenViking은 이 문제를 “Agent의 컨텍스트를 파일처럼 저장하고, 디렉터리처럼 탐색하자”는 방식으로 풉니다. 그리고 여기에 L0/L1/L2 계층, 디렉터리 재귀 검색, 세션 커밋 기반 메모리 추출, 스킬 파일 구조화를 붙여서 Agent 개발 전체를 하나의 컨텍스트 엔진으로 묶으려 합니다. (GitHub)

핵심 기능

1) 메모리, 리소스, 스킬을 하나의 파일시스템으로 통합

OpenViking의 가장 큰 특징은 컨텍스트 타입을 따로따로 보지 않는다는 점입니다.
문서도 파일, 메모리도 파일, 스킬도 파일입니다.

예를 들어 스킬은 이런 구조를 가집니다.

viking://agent/skills/{skill-name}/
├── .abstract.md
├── SKILL.md
└── scripts/

리소스는 문서 디렉터리로, 메모리는 사용자/에이전트 메모리 디렉터리로 저장됩니다. 개발자 입장에서는 매우 직관적입니다. “Agent가 뭘 알고 있나?”라는 질문에 대한 답이 추상적인 벡터 집합이 아니라, 실제 경로와 구조로 드러나기 때문입니다. (GitHub)

2) L0/L1/L2 계층형 컨텍스트 로딩

OpenViking은 컨텍스트를 3단계로 나눕니다.

• L0 Abstract: 약 100 토큰 수준의 매우 짧은 요약
• L1 Overview: 약 1k~2k 토큰 수준의 개요와 내비게이션
• L2 Detail: 원문 전체

이 설계는 Agent 개발에서 아주 실용적입니다.
모든 문서를 한 번에 읽는 대신,

• 먼저 L0로 빠르게 후보를 찾고
• L1으로 맥락을 파악하고
• 정말 필요할 때만 L2를 읽습니다

즉, 검색 정확도와 토큰 비용을 동시에 잡으려는 구조입니다. 특히 “이 문서가 맞는가?”와 “어디를 더 읽어야 하는가?”를 분리한다는 점이 좋습니다. 단순 chunk retrieval보다 탐색 가능한 컨텍스트 계층에 가깝습니다. (GitHub)

3) 계층형 검색과 재귀적 디렉터리 탐색

문서에 따르면 검색 흐름은 Intent Analysis → Hierarchical Retrieval → Rerank → Results입니다.
여기서 핵심은 단순 벡터 Top-K가 아니라, 디렉터리 수준의 재귀 검색을 한다는 점입니다.

즉 OpenViking은 “이 문서 조각이 유사하다”에서 끝나지 않고,
“어느 디렉터리 아래 어떤 구조 속에 있는가”까지 탐색 대상으로 봅니다.

이 방식은 특히 다음 시나리오에 강합니다.

• 대형 코드베이스 문서 검색
• 제품 문서 세트 탐색
• 프로젝트별 메모리 분리
• 도메인별 스킬 조직화

단편적인 유사 문단 몇 개보다, 구조화된 상위 맥락을 함께 가져오는 데 유리합니다. (GitHub)

4) 세션 커밋 기반 장기 메모리 추출

OpenViking은 단순히 문서를 저장하는 시스템이 아닙니다.
세션을 기록하고, 압축하고, 그 대화에서 메모리를 추출합니다.

문서에서는 세션 커밋 흐름을 다음처럼 설명합니다.

Messages → Compress → Archive → Memory Extraction → Storage

또한 메모리는 profile, preferences, entities, events, cases, patterns의 6개 범주로 나뉩니다.
이건 그냥 “대화 로그 저장”과는 다릅니다. OpenViking은 대화에서 지속 가치가 있는 정보만 장기 기억으로 구조화하려고 합니다. Agent를 실제 서비스로 만들 때 매우 필요한 기능입니다. 로그가 많은 것과 기억이 좋은 것은 다르니까요. (GitHub)

5) 관측 가능성과 디버깅 친화성

README와 문서에서 OpenViking은 전통적인 RAG가 블랙박스라는 문제를 지적합니다.
반면 이 프로젝트는 URI, 디렉터리, 계층 요약, observer CLI 같은 요소를 통해 검색과 컨텍스트 공급 과정을 더 관찰 가능하게 만들려 합니다. quickstart 문서에도 openviking observer system 명령이 등장합니다. (GitHub)

Agent 시스템에서 디버깅은 거의 전부입니다.
LLM 품질만큼 중요한 것이 왜 그런 응답이 나왔는지 추적 가능한가인데, OpenViking은 바로 그 추적성을 아키텍처 차원에서 확보하려는 모습입니다.

프로젝트 아키텍처 분석

문서의 구조를 바탕으로 OpenViking의 아키텍처를 개발자 관점에서 다시 그려보면 아래와 같습니다.

이 구조에서 핵심은 세 가지입니다.

Service Layer 중심 설계

문서에 따르면 서비스 계층에는 FSService, SearchService, SessionService, ResourceService, RelationService, PackService, DebugService 등이 있습니다.
이 설계는 전송 계층과 비즈니스 로직을 분리합니다. 그래서 같은 기능을 CLI와 HTTP 서버가 함께 재사용할 수 있습니다. Agent 플랫폼을 붙이기에도 좋고, 추후 SaaS화하기도 편한 구조입니다. (GitHub)

Dual-layer storage

OpenViking은 저장소를 두 층으로 나눕니다.

• AGFS: 실제 컨텐츠 저장
• Vector Index: URI, 벡터, 메타데이터 저장

즉 벡터 인덱스는 원문 전체를 저장하지 않고, 검색용 참조 계층 역할만 합니다.
이렇게 하면 저장 책임과 검색 책임이 분리됩니다. 문서에서도 메모리 최적화, 단일 데이터 소스, 독립적 확장성을 장점으로 설명합니다. (GitHub)

이건 꽤 좋은 선택입니다. 많은 RAG 시스템이 벡터 DB를 사실상 “원문 저장소”처럼 쓰다가 일관성 문제가 생기는데, OpenViking은 애초에 그 경계를 분명히 둡니다.

Parse와 Session이 모두 같은 저장 모델로 귀결

문서를 보면 컨텍스트 추가 흐름은

Input → Parser → TreeBuilder → AGFS → SemanticQueue → Vector Index

세션 커밋 흐름은

Messages → Compress → Archive → Memory Extraction → Storage

입니다.
즉 외부 문서를 넣든, 대화에서 메모리를 뽑든, 결국 동일한 파일시스템 기반 컨텍스트 모델로 수렴합니다. 이것이 OpenViking의 가장 강한 일관성입니다. “문서는 문서대로, 메모리는 메모리대로”가 아니라 둘 다 Agent가 읽는 컨텍스트 파일이 됩니다. (GitHub)

개발자가 이해해야 할 진짜 포인트

OpenViking을 제대로 이해하려면 이 프로젝트를 벡터 DB 대체재로 보면 안 됩니다.

이 프로젝트의 본질은 다음에 더 가깝습니다.

Agent의 컨텍스트 운영체제에 가까운 계층

왜냐하면 OpenViking은 단순 검색이 아니라,

• 컨텍스트의 저장 형식
• 컨텍스트의 계층 구조
• 컨텍스트의 탐색 경로
• 세션에서 기억으로 변환되는 과정
• 스킬이 저장되고 검색되는 방식

까지 포함하기 때문입니다.

그래서 이 프로젝트는 “RAG 라이브러리”보다 Agent infra에 더 가깝습니다.
특히 LangGraph, OpenAI Agents, MCP 기반 툴링, 사내 업무 Agent, 코딩 Agent 같은 시스템에서 “기억/문서/스킬”을 한 번에 정리하고 싶을 때 가치가 큽니다. (GitHub)

코드로 보면 어떤 느낌일까

공식 문서의 사용 예제를 바탕으로 흐름을 정리하면 대략 이런 식입니다.

리소스 추가

from openviking import OpenViking

client = OpenViking()

client.add_resource(
    "https://docs.example.com/api.pdf",
    reason="API documentation"
)

문서를 그냥 임베딩해서 넣는 것이 아니라, OpenViking은 이를 파싱하고 디렉터리 구조와 계층 요약으로 정리한 뒤 인덱싱합니다. (GitHub)

메모리 검색

results = await client.find(
    "UI preferences",
    target_uri="viking://user/memories/"
)

이때 검색 대상이 단순 vector namespace가 아니라 의미 있는 URI 스코프라는 점이 좋습니다.
개발자가 “어디서 찾는지”를 명시할 수 있습니다. (GitHub)

세션 커밋으로 메모리 축적

session = client.session()
await session.add_message(
    "user",
    [{"type": "text", "text": "I prefer dark mode"}]
)
await session.commit()

이 커밋 과정에서 선호 정보가 장기 메모리로 추출될 수 있습니다.
즉 로그가 기억으로 승격되는 지점이 프레임워크 레벨에 존재합니다. (GitHub)

계층별 읽기

abstract = client.abstract("viking://resources/docs/auth")
overview = client.overview("viking://resources/docs/auth")
content = client.read("viking://resources/docs/auth/oauth.md")

이 API만 봐도 OpenViking이 단순 조회가 아니라 LOD(Level of Detail) 기반 컨텍스트 공급을 중심에 둔 시스템이라는 게 드러납니다. (GitHub)

실제로 언제 쓰면 좋을까

1) 장기 기억이 필요한 Agent

예를 들어 개인 비서 Agent나 고객 지원 Agent는 사용자 선호, 과거 결정, 프로젝트 이력 같은 정보를 점진적으로 축적해야 합니다.
이때 OpenViking의 세션 커밋과 6가지 메모리 범주는 꽤 잘 맞습니다. 단순 대화 로그보다 구조화된 장기 기억이 중요할 때 적합합니다. (GitHub)

2) 문서와 툴을 함께 다루는 업무 Agent

사내 Agent는 보통 다음을 동시에 알아야 합니다.

• 제품 문서
• 업무 규정
• 사내 위키
• 툴 사용법
• 호출 가능한 스킬

OpenViking은 이런 자산을 한 저장 모델로 다룰 수 있습니다. “문서 검색”과 “툴 선택”이 서로 다른 서브시스템이 아니라 같은 컨텍스트 공간 안에 있으므로, Agent 설계가 더 단순해집니다. (GitHub)

3) 코딩 Agent / 개발자 도구

코딩 Agent는 저장소 구조, 문서, 규칙, 과거 해결 사례, 실행 스킬을 함께 알아야 합니다.
OpenViking은 최근 릴리스에서 OpenClaw 통합 강화와 OpenCode 지원 추가를 언급하고 있습니다. 이 흐름을 보면 개발 도구형 Agent 생태계와의 결합을 강하게 의식하고 있습니다. (GitHub)

4) 컨텍스트 디버깅이 중요한 프로덕션 환경

Agent가 이상한 답을 했을 때 “어떤 chunk가 선택됐는지”만 보는 건 부족합니다.
“어느 디렉터리 아래에서, 어떤 계층 요약을 거쳐, 어떤 메모리/스킬/리소스를 참조했는지”까지 봐야 합니다. OpenViking은 이 요구에 훨씬 잘 맞습니다. observer 인터페이스도 이런 운영 요구와 연결됩니다. (GitHub)

이 프로젝트의 장점

OpenViking의 장점은 꽤 분명합니다.

첫째, 모델보다 컨텍스트 운영을 더 잘하게 해준다는 점입니다.
Agent 성능 문제의 절반은 모델이 아니라 컨텍스트 설계에서 옵니다.

둘째, 개발자 정신모델과 잘 맞습니다.
파일, 디렉터리, URI, 계층 로딩은 익숙합니다.
학습 비용이 벡터 DB 내부 추상화보다 낮습니다.

셋째, 메모리/리소스/스킬이 같은 인터페이스로 통합됩니다.
이건 실제 서비스에서 유지보수 비용을 크게 줄일 수 있습니다.

넷째, 토큰 비용 관리에 유리합니다.
L0/L1/L2는 단순한 요약이 아니라, Agent의 읽기 전략 자체를 구조화합니다. (GitHub)

아쉬운 점과 현실적인 고려사항

물론 이 프로젝트가 모든 팀에 바로 정답은 아닙니다.

문서와 패키지 메타데이터를 보면 아직 Alpha 성격이 강합니다.
또한 이 시스템의 진짜 가치는 단순 FAQ 검색보다 복합적인 Agent 시스템에서 더 크게 드러납니다. 반대로 “PDF 몇 개 올려서 챗봇 만들기” 정도라면 OpenViking은 다소 무거울 수 있습니다. (GitHub)

또 하나는 운영 복잡도입니다.
파일시스템 패러다임은 직관적이지만, 실제로는 파싱, 요약 생성, 벡터 인덱싱, 세션 압축, 메모리 추출이 함께 굴러가야 합니다. 작은 팀이라면 이 통합 아키텍처가 오히려 과할 수도 있습니다.

즉 OpenViking은 “간단한 RAG 데모용 도구”라기보다,
장기적으로 Agent의 컨텍스트 계층을 표준화하고 싶은 팀에게 더 잘 맞습니다.

한 문장으로 정리하면

OpenViking은 AI Agent의 메모리, 리소스, 스킬을 벡터 몇 개가 아니라 탐색 가능한 파일시스템으로 바꾸려는 프로젝트입니다.

이 프로젝트가 재미있는 이유는 성능 최적화보다 먼저 컨텍스트를 어떻게 모델링할 것인가라는 질문을 던진다는 데 있습니다.
Agent 시대에는 모델 오케스트레이션만큼이나 컨텍스트 운영이 중요해지고 있는데, OpenViking은 바로 그 레이어를 정면으로 제품화한 오픈소스라고 볼 수 있습니다. (GitHub)