# OpenViking: bộ nhớ và ngữ cảnh cho AI agent — hướng dẫn cài đặt và dùng

> OpenViking là cơ sở dữ liệu ngữ cảnh mã nguồn mở cho AI agent, giúp lưu và truy xuất kiến thức, bộ nhớ người dùng và kỹ năng trong filesystem ảo. Bạn có thể chạy bằng Python và uv, dùng CLI, SDK hoặc kết nối với nhiều coding agent. Cài đặt không quá khó nếu đã có Python 3.10+, uv và model provider phù hợp.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-11-07 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/openviking-bo-nho-ngu-canh-ai-agent

OpenViking là cơ sở dữ liệu ngữ cảnh mã nguồn mở cho AI agent. Repo này gom kiến thức, bộ nhớ dài hạn và kỹ năng vào một filesystem ảo có URI dạng `viking://`, để agent có thể duyệt, đọc, ghi và tìm kiếm giống như làm việc với thư mục.

Điểm đáng giá nhất là dữ liệu của agent không còn nằm trong một kho vector khó quan sát. Bạn có thể xem cấu trúc đã lưu, đọc phần tóm tắt trước khi mở nội dung đầy đủ, chỉnh sửa bộ nhớ và kết nối OpenViking với các công cụ như Claude Code, Codex, Cursor, OpenCode hoặc LangChain.

Repo phù hợp với lập trình viên xây agent nhiều phiên làm việc, đội ngũ muốn quản lý kho tài liệu cho RAG, hoặc người cần agent nhớ sở thích và kinh nghiệm của mình. Repo hiện có khoảng 42.169 sao và 3.476 fork, dùng giấy phép AGPL-3.0.

```repo
- repo | volcengine/OpenViking
- kind | Thư viện
- desc | Cơ sở dữ liệu ngữ cảnh cho AI agent, hợp nhất knowledge, memory và skills trong filesystem ảo viking://.
- stars | 42k
- lang | Python
- license | AGPL-3.0
```

## OpenViking làm được gì

### Gom kiến thức, bộ nhớ và kỹ năng vào một nơi

OpenViking coi tài liệu dự án, bộ nhớ người dùng và hướng dẫn thực hiện công việc đều là các loại ngữ cảnh. Mỗi tài nguyên có URI `viking://` riêng, nên agent có thể truy cập có cấu trúc thay vì chỉ nhận một đoạn văn bản đã nhúng vector.

Với người làm kinh doanh, bạn có thể lưu tài liệu sản phẩm, quy trình chăm sóc khách hàng và ghi chú về từng người dùng. Với lập trình viên, bạn có thể lưu tài liệu API, mã nguồn, thói quen coding và các kỹ năng dùng lại cho nhiều phiên làm việc.

### Duyệt dữ liệu như filesystem

Agent có thể dùng các thao tác như `ls`, `tree`, `read`, `write` và `grep`. Bạn cũng có thể mở thư mục để kiểm tra hoặc chỉnh sửa những gì agent đang biết.

Cách này giúp việc kiểm tra dữ liệu dễ hơn so với một kho nhớ chỉ trả về các vector hoặc đoạn kết quả khó giải thích. Khi agent trả lời sai, bạn có thêm cơ hội tìm đúng thư mục và nội dung gây ra vấn đề.

### Tìm kiếm trong phạm vi thư mục

`find` có thể tìm ngữ cảnh phù hợp theo câu hỏi. OpenViking cũng hỗ trợ giới hạn tìm kiếm trong một dự án hoặc một nhánh bộ nhớ, thay vì quét toàn bộ kho vector.

Điều này hữu ích khi bạn có nhiều dự án, nhiều nhóm tài liệu hoặc nhiều người dùng. Agent có thể tìm trong `viking://resources/my_project/` mà không lẫn dữ liệu từ dự án khác.

### Đọc tóm tắt trước khi đọc tài liệu gốc

OpenViking chia ngữ cảnh thành ba tầng. L0 là bản tóm tắt một câu để kiểm tra nhanh mức liên quan. L1 là phần tổng quan dùng cho lập kế hoạch. L2 là nội dung đầy đủ, chỉ mở khi thật sự cần.

Các thư mục đã được xử lý ngữ nghĩa có `.abstract.md` và `.overview.md`. Nhờ vậy agent có thể xem cấu trúc và ý chính trước, giúp giảm lượng nội dung phải nạp vào phiên làm việc.

### Lưu phiên trò chuyện thành file có thể kiểm tra

Khi commit một session, OpenViking lưu lại cuộc trò chuyện và trích xuất memory thành Markdown. Bạn có thể đọc, sửa và hợp nhất các file này.

Nếu bật VikingBot, lệnh `ov compile` còn có thể tổ chức tài liệu nguồn thành wiki, knowledge graph hoặc báo cáo. Đây là hướng dùng phù hợp khi bạn muốn biến các cuộc trao đổi rời rạc thành tài liệu làm việc có thể tái sử dụng.

### Kết nối với nhiều agent và framework

Repo có bộ cài memory plugin cho Claude Code, Codex, Cursor, TRAE, OpenCode và một số công cụ khác. Ngoài ra còn có tích hợp cho OpenClaw, Hermes, pi, DeerFlow, DSH, Doubao Work và LangChain.

Bạn cũng có thể tự xây tích hợp bằng SDK Python, Go, TypeScript hoặc HTTP API. OpenViking vì vậy phù hợp cả với người dùng cuối lẫn đội ngũ phát triển sản phẩm agent.

## Cần chuẩn bị gì

Nếu tự triển khai server, bạn cần `uv`, Python 3.10 trở lên và một model provider có embedding model cùng VLM. Trình cài đặt hỗ trợ Volcengine, OpenAI, Codex OAuth, Kimi, GLM và Ollama cục bộ.

Bạn cần API key tương ứng nếu model provider yêu cầu. README không khẳng định mọi provider đều có cùng cách cấp key, nên hãy chuẩn bị key của provider đã chọn và nhập khi trình hướng dẫn hỏi.

Nếu chỉ muốn thử nhanh, OpenViking có Studio chạy trên trình duyệt, không cần cài đặt. README cũng nêu dịch vụ OpenViking do Volcengine vận hành có 50 file đầu tiên miễn phí; để kết nối, bạn cần server address và API key tạo trong console.

Để cài memory plugin bằng installer, máy cần macOS hoặc Linux, Node.js 18 trở lên và `curl`, không cần sudo. Trên Windows, README hướng dẫn dùng desktop app. Desktop app beta hỗ trợ macOS và Windows x64.

```note
API key có quyền khác nhau. Khi server bật xác thực, plugin cần user key để đọc và ghi memory; root key không dùng được cho tác vụ này. Không dán key vào nội dung công khai và không ghi key vào rule hoặc file khác ngoài nơi công cụ hướng dẫn.
```

## Cài đặt từng bước

```steps
- Chọn cách chạy | Dùng Studio, dịch vụ hosted hoặc tự chạy server
- Chuẩn bị môi trường | Cài uv, Python 3.10+ và model provider nếu tự host
- Cài OpenViking | Cài package rồi chạy trình hướng dẫn init
- Kiểm tra server | Xem trạng thái bằng ov status
- Nạp và tìm tài liệu | Import repo, theo dõi task rồi dùng ls, tree, find hoặc grep
- Kết nối agent | Cài memory plugin hoặc dùng SDK, HTTP API
```

### Chọn cách chạy phù hợp

Nếu chỉ cần xem thử, dùng OpenViking Studio trong trình duyệt. Cách này không yêu cầu cài đặt trên máy.

Nếu muốn dùng dịch vụ hosted, kích hoạt OpenViking Service của Volcengine, tạo API key trong mục User Management → API Key, rồi dùng server address do README cung cấp:

```text
https://api.vikingdb.cn-beijing.volces.com/openviking
```

Nếu muốn tự quản lý dữ liệu, chuyển sang bước cài server bên dưới. README cho biết bản mã nguồn mở có thể chạy trong môi trường riêng và không cần activation key.

### Cài package và khởi tạo server

Mở terminal tại máy bạn muốn chạy server. Lệnh chính thức trong README là:

```bash
uv tool install openviking --upgrade && openviking-server init
```

Lệnh này cài hoặc nâng cấp package `openviking`, sau đó mở trình hướng dẫn cấu hình. `init` ghi cấu hình vào `~/.openviking/ov.conf` và thiết lập model.

Khi được hỏi, hãy chọn model provider, embedding model, VLM và cung cấp API key nếu cần. Không nên tự đoán provider hoặc model vì README chỉ nêu các nhóm provider được hỗ trợ, không đưa một cấu hình chung cho mọi tài khoản.

Server chạy ở foreground. Vì vậy bạn cần giữ terminal này mở trong lúc dùng CLI hoặc kết nối agent. Nếu đóng terminal, server sẽ dừng.

### Kiểm tra server bằng CLI

Mở một terminal khác, sau đó chạy:

```bash
ov status
```

Nếu server đã chạy và CLI kết nối được, lệnh sẽ trả về trạng thái của OpenViking. Nếu chưa kết nối được, kiểm tra lại terminal server và cấu hình đã tạo trong `~/.openviking/ov.conf`.

### Nạp một repository vào OpenViking

Dùng lệnh sau để import repo mẫu:

```bash
ov add-resource https://github.com/volcengine/OpenViking
```

Lệnh trả về `task_id`. Hãy thay `TASK_ID` bằng giá trị thật và kiểm tra cho đến khi trạng thái là `completed`:

```bash
ov task status TASK_ID
```

Đừng gõ nguyên chữ `TASK_ID`; đó chỉ là chỗ giữ chỗ trong hướng dẫn. Việc import có thể cần thời gian vì OpenViking phải xử lý tài nguyên và tạo ngữ cảnh.

### Duyệt và tìm nội dung

Sau khi task hoàn tất, thử các lệnh CLI trong README:

```bash
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/en
```

`ov ls` liệt kê tài nguyên. `ov tree` xem cây thư mục với độ sâu được chỉ định. `ov find` trả về ngữ cảnh phù hợp cùng các URI để bạn kiểm tra tiếp. `ov grep` tìm chuỗi trong một URI cụ thể.

Nếu cần xem cấu hình CLI, README có nhắc tới `ov config` và hướng dẫn CLI setup. README được cung cấp chưa ghi đầy đủ các tùy chọn của `ov config`, nên không nên tự thêm cờ hoặc biến môi trường ngoài tài liệu đó.

### Cài memory plugin cho agent

README cung cấp installer chính thức sau:

```bash
curl -fsSL https://openviking.ai/install | bash
```

Khi installer hỏi, chọn công cụ agent và server. Với server trên máy hiện tại, chọn self-hosted/local. Với dịch vụ Volcengine, chọn Volcengine OpenViking Cloud. Nếu dùng địa chỉ khác, chọn Custom URL.

Nếu server bật xác thực, nhập user key, không nhập root key. Sau khi cài, khởi động lại agent. README cũng nêu Codex có thể dừng ở màn hình `Hooks need review`; khi đó chọn `Trust all and continue`.

Có thể dùng prompt để nhờ agent cài theo hướng dẫn chính thức:

```text
Install the OpenViking memory plugin and help me start using it.
```

Installer yêu cầu network access và ghi vào thư mục home. Trên Windows, dùng desktop app thay cho installer shell này.

### Chạy VikingBot nếu cần agent tích hợp sẵn

README cung cấp extra package và các lệnh sau:

```bash
pip install "openviking[bot]"
openviking-server --with-bot
ov chat   # in another terminal
```

Giữ server ở một terminal, sau đó chạy `ov chat` trong terminal khác. Đây là cách thử VikingBot dựa trên OpenViking.

## Kiểm tra đã chạy được chưa

Có bốn dấu hiệu rõ ràng:

- `ov status` trả về trạng thái server thay vì lỗi kết nối.
- `ov add-resource` trả về `task_id`, rồi `ov task status TASK_ID` chuyển sang `completed`.
- `ov ls viking://resources/` hiển thị tài nguyên đã nhập.
- `ov find` trả về các context kèm URI để tiếp tục kiểm tra.

Bạn cũng có thể chạy `ov tree` để thấy thư mục và các tầng ngữ cảnh. Khi tài liệu được xử lý, cấu trúc có thể xuất hiện `.abstract.md` và `.overview.md` bên cạnh nội dung gốc.

Với memory plugin, hãy yêu cầu agent nhớ một sở thích, sau đó hỏi lại trong một session mới. README lưu ý memory được xử lý ở background, nên việc chưa tìm thấy ngay sau khi ghi là bình thường.

## Dùng vào việc thật

### Chủ shop muốn agent nhớ cách trả lời khách

Chủ shop có thể kết nối memory plugin, rồi nói với agent một quy tắc như:

```text
Hãy nhớ rằng tôi muốn trả lời khách bằng tiếng Việt, ngắn gọn và lịch sự.
```

Ở session sau, hỏi lại:

```text
Tôi thường muốn trả lời khách theo phong cách nào?
```

OpenViking lưu preference trong nhánh memory và agent có thể lấy lại khi cần. Nếu cần kiểm tra, bạn duyệt các URI thuộc `viking://user/{user_id}/memories/`.

### Nhân viên văn phòng tìm quy trình trong kho tài liệu

Một nhân viên có thể import tài liệu dự án hoặc tài liệu nội bộ được phép sử dụng, sau đó tìm theo câu hỏi:

```bash
ov find "quy trình xử lý yêu cầu hoàn tiền"
```

Nếu kết quả trả về URI phù hợp, dùng `ov tree` hoặc `ov grep` để xem phạm vi liên quan. Cách tìm theo thư mục giúp tránh trộn tài liệu của nhiều dự án.

### Dev muốn agent hiểu một repository

Dev có thể import repository bằng `ov add-resource`, theo dõi task đến `completed`, rồi hỏi:

```bash
ov find "how does this project handle authentication"
```

Bạn có thể kiểm tra tiếp thư mục tài liệu bằng `ov tree`, hoặc tìm từ khóa trong một nhánh bằng `ov grep`. Agent có thể xem summary trước rồi mới mở nội dung chi tiết, phù hợp với repository lớn.

### Đội ngũ muốn biến session thành tài liệu

Sau một chuỗi trao đổi về sản phẩm, đội ngũ có thể commit session để lưu cuộc trò chuyện và memory dưới dạng Markdown. Sau đó có thể đọc, chỉnh sửa hoặc hợp nhất nội dung.

Nếu dùng VikingBot, chạy:

```bash
ov compile
```

README mô tả lệnh này có thể tổ chức tài liệu nguồn thành wiki, knowledge graph hoặc report. Đây là cách biến kinh nghiệm tích lũy từ agent thành tài liệu dùng chung.

> Một agent tốt không chỉ nhớ nhiều, mà còn phải cho bạn xem nó đang nhớ gì.
>
> — Ông T

## Lỗi hay gặp và cách xử lý

### Terminal server bị đóng

Server chạy ở foreground. Nếu đóng terminal hoặc dừng tiến trình, CLI và agent sẽ không kết nối được. Hãy chạy lại server và giữ terminal đó mở, sau đó thử `ov status` ở terminal khác.

### Dùng sai loại API key

Khi xác thực bật, plugin cần user key. Root key không có quyền đọc hoặc ghi memories theo hướng dẫn README. Hãy tạo hoặc lấy user key đúng server, rồi nhập vào installer hoặc cấu hình được yêu cầu.

### Tìm memory ngay sau khi vừa ghi

Memory được xử lý ở background. Vì vậy session mới có thể chưa thấy nội dung ngay lập tức. Hãy chờ quá trình xử lý hoàn tất rồi hỏi lại, thay vì ghi lại nhiều bản sao.

### Import chưa hoàn tất nhưng đã tìm kiếm

`ov add-resource` trả về task bất đồng bộ. Nếu chưa kiểm tra `ov task status TASK_ID` đến khi có trạng thái `completed`, kết quả tìm kiếm có thể chưa đầy đủ. Hãy dùng đúng task ID được trả về.

### Chạy installer trên Windows

Installer shell trong README yêu cầu macOS hoặc Linux, Node.js 18+ và curl. Trên Windows, hãy dùng desktop app beta hỗ trợ Windows x64 thay vì cố chạy nguyên lệnh shell.

## Có nên dùng không

OpenViking đáng thử nếu bạn đang xây agent cần memory qua nhiều session, muốn quản lý knowledge base có cấu trúc, hoặc cần kiểm tra trực tiếp dữ liệu mà agent đã lưu. Mô hình filesystem `viking://`, ba tầng L0/L1/L2 và tìm kiếm theo thư mục là những điểm khác biệt rõ so với cách lưu memory dạng hộp đen.

CLI có các thao tác dễ hiểu, repo có SDK cho Python, Go, TypeScript, HTTP API và nhiều integration. Repo cũng có lựa chọn self-host, Docker và dịch vụ hosted. Với dữ liệu cần kiểm soát, bản self-host dưới AGPLv3 cho phép bạn triển khai trong môi trường riêng, nhưng cần tự lo vận hành, model provider, key và bảo mật.

Giới hạn lớn là việc tự chạy không chỉ dừng ở `pip install`. Bạn cần Python 3.10+, uv, embedding model, VLM và cấu hình provider. Nếu expose server ra ngoài localhost, README yêu cầu cấu hình authentication; nếu nhiều người dùng, bạn cần quan tâm accounts, user isolation và ACL.

Nếu chỉ cần hỏi đáp tài liệu đơn giản, một công cụ RAG có sẵn có thể dễ bắt đầu hơn. Nếu muốn memory tích hợp sâu với coding agent và cần nhìn thấy, chỉnh sửa, tổ chức lại ngữ cảnh, OpenViking là lựa chọn đáng cân nhắc. Hãy đọc kỹ điều khoản AGPL-3.0 và giới hạn dịch vụ trước khi dùng trong sản phẩm thương mại.

## Câu hỏi thường gặp

### OpenViking có miễn phí không?

Bản mã nguồn mở được phát hành dưới giấy phép AGPL-3.0 và server open-source không cần activation key. Dịch vụ OpenViking do Volcengine vận hành có 50 file đầu tiên miễn phí theo README; các gói thương mại và giới hạn cụ thể cần xem tài liệu dịch vụ.

### Có cần GPU để chạy OpenViking không?

README được cung cấp không nói OpenViking bắt buộc phải có GPU. Tài liệu yêu cầu model provider có embedding model và VLM khi tự triển khai, hoặc có thể dùng Ollama cục bộ. Vì vậy chưa có đủ thông tin để khẳng định cấu hình phần cứng cụ thể.

### OpenViking có chạy trên Windows không?

Có desktop app beta cho Windows x64. Tuy nhiên installer shell yêu cầu macOS hoặc Linux, Node.js 18+ và curl; README hướng dẫn người dùng Windows dùng desktop app.

### Dữ liệu có an toàn không?

Bạn có thể tự triển khai server trong môi trường riêng và cấu hình accounts, user isolation, ACL cùng authentication. README yêu cầu bật authentication trước khi expose server ngoài localhost. Mức an toàn thực tế còn phụ thuộc cấu hình, quyền truy cập và cách bạn bảo vệ API key.

### Có cần API key không?

Nếu tự chạy với model provider hoặc dùng dịch vụ hosted, bạn thường cần API key theo cấu hình đã chọn. Khi server bật xác thực, integration cần user key để đọc và ghi memory; root key không dùng cho tác vụ này.

### OpenViking khác gì một kho vector thông thường?

OpenViking tổ chức ngữ cảnh thành filesystem ảo `viking://`, có thể duyệt, đọc, ghi và tìm trong phạm vi thư mục. Nó cũng tạo abstract và overview để agent xem tóm tắt trước khi đọc nội dung đầy đủ, thay vì chỉ trả về các đoạn vector từ một index phẳng.

### Có thể dùng OpenViking với coding agent nào?

README nêu các integration cho Claude Code, Codex, Cursor, TRAE, OpenCode và nhiều công cụ khác. Ngoài ra còn có tích hợp cho OpenClaw, Hermes, pi, DeerFlow, DSH, Doubao Work và LangChain.
