Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

Doc: suggest use ~/.openviking/ov.conf as a default configure path (#119)

MaojiaShengc24c091de1be
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index baf685bb3..1d5a363ef 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -42,7 +42,7 @@ source .venv/bin/activate # Linux/macOS
### 3. Configure Environment
-Create a configuration file `ov.conf`:
+Create a configuration file `~/.openviking/ov.conf`:
```json
{
@@ -67,7 +67,7 @@ Create a configuration file `ov.conf`:
Set the environment variable:
```bash
-export OPENVIKING_CONFIG_FILE=ov.conf
+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
```
### 4. Verify Installation
diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md
index e122fab2e..9875050b0 100644
--- a/CONTRIBUTING_CN.md
+++ b/CONTRIBUTING_CN.md
@@ -41,7 +41,7 @@ source .venv/bin/activate # Linux/macOS
### 3. 配置环境
-创建配置文件 `ov.conf`:
+创建配置文件 `~/.openviking/ov.conf`:
```json
{
@@ -66,7 +66,7 @@ source .venv/bin/activate # Linux/macOS
设置环境变量:
```bash
-export OPENVIKING_CONFIG_FILE=ov.conf
+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
```
### 4. 验证安装
diff --git a/README.md b/README.md
index 5a2f2d49d..e51a38fd0 100644
--- a/README.md
+++ b/README.md
@@ -84,7 +84,7 @@ OpenViking supports various model services:
#### Configuration Template
-Create a configuration file `ov.conf`:
+Create a configuration file `~/.openviking/ov.conf`:
```json
{
@@ -165,7 +165,7 @@ Create a configuration file `ov.conf`:
After creating the configuration file, set the environment variable to point to it (Linux/macOS):
```bash
-export OPENVIKING_CONFIG_FILE=ov.conf
+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
```
On Windows, use one of the following:
@@ -173,13 +173,13 @@ On Windows, use one of the following:
PowerShell:
```powershell
-$env:OPENVIKING_CONFIG_FILE = "ov.conf"
+$env:OPENVIKING_CONFIG_FILE = "~/.openviking/ov.conf"
```
Command Prompt (cmd.exe):
```bat
-set OPENVIKING_CONFIG_FILE=ov.conf
+set OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
```
> 💡 **Tip**: You can also place the configuration file in other locations, just specify the correct path in the environment variable.
diff --git a/README_CN.md b/README_CN.md
index a1da5bf64..fd1ec47e5 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -83,7 +83,7 @@ OpenViking 支持多种模型服务:
#### 配置文件模版
-创建配置文件 `ov.conf`:
+创建配置文件 `~/.openviking/ov.conf`:
```json
{
@@ -164,7 +164,7 @@ OpenViking 支持多种模型服务:
创建好配置文件后,设置环境变量指向配置文件(Linux/macOS):
```bash
-export OPENVIKING_CONFIG_FILE=ov.conf
+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
```
Windows 下可使用以下方式之一:
@@ -172,13 +172,13 @@ Windows 下可使用以下方式之一:
PowerShell:
```powershell
-$env:OPENVIKING_CONFIG_FILE = "ov.conf"
+$env:OPENVIKING_CONFIG_FILE = "~/.openviking/ov.conf"
```
命令提示符(cmd.exe):
```bat
-set OPENVIKING_CONFIG_FILE=ov.conf
+set OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
```
> 💡 **提示**:你也可以将配置文件放在其他位置,只需在环境变量中指定正确的路径即可。
diff --git a/docs/en/faq/faq.md b/docs/en/faq/faq.md
index 412e344e1..d62d032ed 100644
--- a/docs/en/faq/faq.md
+++ b/docs/en/faq/faq.md
@@ -69,7 +69,7 @@ pip install openviking
### How do I configure OpenViking?
-Create an `ov.conf` configuration file in your project directory:
+Create an `~/.openviking/ov.conf` configuration file in your project directory:
```json
{
@@ -281,7 +281,7 @@ This strategy finds semantically matching fragments while understanding the comp
```
2. **Embedding model configuration error**
- - Check if `api_key` in `ov.conf` is correct
+ - Check if `api_key` in `~/.openviking/ov.conf` is correct
- Confirm model name and endpoint are configured correctly
3. **Unsupported file format**
diff --git a/docs/en/getting-started/02-quickstart.md b/docs/en/getting-started/02-quickstart.md
index 9dcfc70f2..1fa0bfa45 100644
--- a/docs/en/getting-started/02-quickstart.md
+++ b/docs/en/getting-started/02-quickstart.md
@@ -31,7 +31,7 @@ OpenViking supports multiple model services:
### Configuration File Template
-Create a configuration file `ov.conf`:
+Create a configuration file `~/.openviking/ov.conf`:
```json
{
@@ -110,7 +110,7 @@ Create a configuration file `ov.conf`:
After creating the configuration file, set the environment variable to point to it:
```bash
-export OPENVIKING_CONFIG_FILE=ov.conf
+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
```
## Run Your First Example
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 598250c12..ca9686776 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -1,10 +1,10 @@
# Configuration
-OpenViking uses a JSON configuration file (`ov.conf`) for settings.
+OpenViking uses a JSON configuration file (`~/.openviking/ov.conf`) for settings.
## Configuration File
-Create `ov.conf` in your project directory:
+Create `~/.openviking/ov.conf` in your project directory:
```json
{
@@ -168,7 +168,7 @@ export OPENVIKING_DATA_PATH="./data"
1. Constructor parameters (highest)
2. Config object
-3. Configuration file (`ov.conf`)
+3. Configuration file (`~/.openviking/ov.conf`)
4. Environment variables
5. Default values (lowest)
diff --git a/docs/en/guides/02-volcengine-purchase-guide.md b/docs/en/guides/02-volcengine-purchase-guide.md
index efa289170..04ac4a26a 100644
--- a/docs/en/guides/02-volcengine-purchase-guide.md
+++ b/docs/en/guides/02-volcengine-purchase-guide.md
@@ -88,7 +88,7 @@ After activation, use the model ID: `doubao-embedding-vision-250615`
### Configuration Template
-Create an `ov.conf` file using the following template:
+Create an `~/.openviking/ov.conf` file using the following template:
```json
{
@@ -139,7 +139,7 @@ Create an `ov.conf` file using the following template:
### Configuration Example
-Save the following content as `ov.conf`:
+Save the following content as `~/.openviking/ov.conf`:
```json
{
diff --git a/docs/en/guides/03-deployment.md b/docs/en/guides/03-deployment.md
index 740b5644e..f21a279cd 100644
--- a/docs/en/guides/03-deployment.md
+++ b/docs/en/guides/03-deployment.md
@@ -47,9 +47,9 @@ python -m openviking serve \
Server configuration is read from the JSON config file specified by `--config` or the `OPENVIKING_CONFIG_FILE` environment variable (the same file used for `OpenVikingConfig`):
```bash
-python -m openviking serve --config ./ov.conf
+python -m openviking serve --config ~/.openviking/ov.conf
# or
-export OPENVIKING_CONFIG_FILE=./ov.conf
+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
python -m openviking serve
```
diff --git a/docs/zh/faq/faq.md b/docs/zh/faq/faq.md
index f3c19fd9d..a4331a07c 100644
--- a/docs/zh/faq/faq.md
+++ b/docs/zh/faq/faq.md
@@ -69,7 +69,7 @@ pip install openviking
### 如何配置 OpenViking?
-在项目目录创建 `ov.conf` 配置文件:
+在项目目录创建 `~/.openviking/ov.conf` 配置文件:
```json
{
@@ -281,7 +281,7 @@ OpenViking 使用分数传播机制:
```
2. **Embedding 模型配置错误**
- - 检查 `ov.conf` 中的 `api_key` 是否正确
+ - 检查 `~/.openviking/ov.conf` 中的 `api_key` 是否正确
- 确认模型名称和 endpoint 配置正确
3. **文件格式不支持**
diff --git a/docs/zh/getting-started/02-quickstart.md b/docs/zh/getting-started/02-quickstart.md
index bf8e2ea40..2f18c493f 100644
--- a/docs/zh/getting-started/02-quickstart.md
+++ b/docs/zh/getting-started/02-quickstart.md
@@ -31,7 +31,7 @@ OpenViking 支持多种模型服务:
### 配置文件模版
-创建配置文件 `ov.conf`:
+创建配置文件 `~/.openviking/ov.conf`:
```json
{
@@ -110,7 +110,7 @@ OpenViking 支持多种模型服务:
创建好配置文件后,设置环境变量指向配置文件:
```bash
-export OPENVIKING_CONFIG_FILE=ov.conf
+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
```
## 运行第一个示例
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 747ca320e..9a375202b 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -4,7 +4,7 @@ OpenViking 使用 JSON 配置文件(`ov.conf`)进行设置。配置文件支
## 快速开始
-在项目目录创建 `ov.conf`:
+在项目目录创建 `~/.openviking/ov.conf`:
```json
{
@@ -251,7 +251,7 @@ export OPENVIKING_DATA_PATH="./data"
1. 构造函数参数(最高)
2. Config 对象
-3. 配置文件(`ov.conf`)
+3. 配置文件(`~/.openviking/ov.conf`)
4. 环境变量
5. 默认值(最低)
diff --git a/docs/zh/guides/02-volcengine-purchase-guide.md b/docs/zh/guides/02-volcengine-purchase-guide.md
index 1197a8536..f8a69264c 100644
--- a/docs/zh/guides/02-volcengine-purchase-guide.md
+++ b/docs/zh/guides/02-volcengine-purchase-guide.md
@@ -90,7 +90,7 @@ OpenViking 需要以下模型服务:
### 配置模板
-创建 `ov.conf` 文件,使用以下模板:
+创建 `~/.openviking/ov.conf` 文件,使用以下模板:
```json
{
@@ -141,7 +141,7 @@ OpenViking 需要以下模型服务:
### 配置示例
-将以下内容保存为 `ov.conf`:
+将以下内容保存为 `~/.openviking/ov.conf`:
```json
{
diff --git a/docs/zh/guides/03-deployment.md b/docs/zh/guides/03-deployment.md
index 8071bd510..41fd062c3 100644
--- a/docs/zh/guides/03-deployment.md
+++ b/docs/zh/guides/03-deployment.md
@@ -47,9 +47,9 @@ python -m openviking serve \
服务端配置从 `--config` 或 `OPENVIKING_CONFIG_FILE` 环境变量指定的 JSON 配置文件中读取(与 `OpenVikingConfig` 共用同一个文件):
```bash
-python -m openviking serve --config ./ov.conf
+python -m openviking serve --config ~/.openviking/ov.conf
# 或
-export OPENVIKING_CONFIG_FILE=./ov.conf
+export OPENVIKING_CONFIG_FILE=~/.openviking/ov.conf
python -m openviking serve
```
diff --git a/examples/chatmem/README.md b/examples/chatmem/README.md
index a6432bd95..ec3128b67 100644
--- a/examples/chatmem/README.md
+++ b/examples/chatmem/README.md
@@ -170,7 +170,7 @@ OV_DEBUG=1 uv run chatmem.py
## Configuration
-Edit `ov.conf`:
+Edit `./ov.conf`:
```json
{
@@ -218,7 +218,7 @@ Memories Extracted & Persisted
## Troubleshooting
**"Error initializing"**
-- Check `ov.conf` has valid API keys
+- Check `./ov.conf` has valid API keys
- Ensure `data/` directory is writable
**"No relevant sources found"**
diff --git a/examples/chatmem/docs/2026-02-03-chatmem-implementation.md b/examples/chatmem/docs/2026-02-03-chatmem-implementation.md
index a6b237725..91610490f 100644
--- a/examples/chatmem/docs/2026-02-03-chatmem-implementation.md
+++ b/examples/chatmem/docs/2026-02-03-chatmem-implementation.md
@@ -423,7 +423,7 @@ from openviking.utils.config.open_viking_config import OpenVikingConfig
import json
# Load config
-with open('ov.conf', 'r') as f:
+with open('./ov.conf', 'r') as f:
config_dict = json.load(f)
config = OpenVikingConfig.from_dict(config_dict)
@@ -834,7 +834,7 @@ OV_DEBUG=1 uv run chat.py
## Configuration
-Edit `ov.conf`:
+Edit `./ov.conf`:
```json
{
diff --git a/examples/memex/README.md b/examples/memex/README.md
index 6814752cb..6664d8bf6 100644
--- a/examples/memex/README.md
+++ b/examples/memex/README.md
@@ -167,7 +167,7 @@ Memex uses a modular RAG (Retrieval-Augmented Generation) architecture:
| Variable | Description |
|----------|-------------|
-| `OPENVIKING_CONFIG_FILE` | Path to OpenViking config file |
+| `OPENVIKING_CONFIG_FILE` | Path to OpenViking config file, default to `~/.openviking/ov.conf` |
| `FEISHU_APP_ID` | Feishu app ID (optional) |
| `FEISHU_APP_SECRET` | Feishu app secret (optional) |
diff --git a/examples/server_client/README.md b/examples/server_client/README.md
index 6cb6c1bdb..c9ceddc7b 100644
--- a/examples/server_client/README.md
+++ b/examples/server_client/README.md
@@ -60,7 +60,7 @@ main()
### 方式三:环境变量
```bash
-export OPENVIKING_CONFIG_FILE=./ov.conf
+export OPENVIKING_CONFIG_FILE=./ov.conf # or ~/.openviking/ov.conf
export OPENVIKING_PATH=./data
export OPENVIKING_PORT=1933
export OPENVIKING_API_KEY=your-secret-key
diff --git a/examples/server_client/server.py b/examples/server_client/server.py
index 5e496d206..a3f4f3a9c 100644
--- a/examples/server_client/server.py
+++ b/examples/server_client/server.py
@@ -12,7 +12,6 @@ import argparse
import os
import sys
-from rich import box
from rich.console import Console
from rich.panel import Panel
from rich.table import Table
@@ -44,6 +43,8 @@ Examples:
os.environ["OPENVIKING_CONFIG_FILE"] = args.config
elif os.path.exists("./ov.conf"):
os.environ.setdefault("OPENVIKING_CONFIG_FILE", "./ov.conf")
+ elif os.path.exists("~/.openviking/ov.conf"):
+ os.environ.setdefault("OPENVIKING_CONFIG_FILE", "~/.openviking/ov.conf")
# Display server info
info = Table(show_header=False, box=None, padding=(0, 2))