> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 OpenViking 存储

`openviking` 长期记忆后端把会话消息提交给 OpenViking，由 OpenViking 为每个用户提取并保存实体、事件和偏好。检索时，VeADK 按用户隔离记忆，并把命中内容返回给智能体。

## 前置条件

准备可访问的 OpenViking 服务和服务所有者 API Key。`openviking-sdk>=0.1.3` 已包含在 VeADK 1.0.3 的基础依赖中。

```bash lines theme={null}
export DATABASE_OPENVIKING_URL="https://openviking.example.com"
export DATABASE_OPENVIKING_API_KEY="${OPENVIKING_API_KEY}"
```

## 使用示例

```python lines theme={null}
import asyncio

from veadk import Agent, Runner
from veadk.memory.long_term_memory import LongTermMemory

memory = LongTermMemory(
    backend="openviking",
    app_name="support_assistant",
    top_k=5,
)

agent = Agent(
    name="support_assistant",
    instruction="回答问题前，先检索用户的长期记忆。",
    long_term_memory=memory,
    auto_save_session=True,
)

runner = Runner(
    agent=agent,
    app_name="support_assistant",
    user_id="user_123",
)

print(asyncio.run(runner.run("记住：我偏好简短的回答。")))
```

保存会话时，OpenViking 后端会同时接收用户和智能体的文本消息，并在提交会话后形成长期记忆。检索范围固定为当前用户的 `viking://user/peers/{peer_id}/memories`，避免不同用户之间混用记忆。

## 参数

`LongTermMemory` 的通用参数见[长期记忆概述](/productions/veadk/archives/1.0.3/zh/components/memory)。通过 `backend_config` 可覆盖 OpenViking 后端参数：

| 参数 | 环境变量 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- | :- |
| `index` | 无 | `str` | `app_name` 或 `default_app` | 记忆所属应用的索引名。 |
| `openviking_config` | `DATABASE_OPENVIKING_*` | `OpenVikingConfig` | 从环境变量构造 | 包含 `url` 与 `api_key` 的连接配置。 |
| `url` | `DATABASE_OPENVIKING_URL` | `str` | `""` | OpenViking 服务地址；必须配置。显式传入时覆盖 `openviking_config.url`。 |
| `api_key` | `DATABASE_OPENVIKING_API_KEY` | `str` | `""` | OpenViking 服务所有者 API Key；必须配置。显式传入时覆盖 `openviking_config.api_key`。 |
| `peer_id_resolver` | 无 | `Callable[[str, str], str] \| None` | 使用 `user_id` | 根据 `app_name` 和 `user_id` 生成 OpenViking peer 标识的函数。 |
| `timeout` | 无 | `float` | `30` | OpenViking SDK 请求超时时间，单位为秒。 |

默认 `peer_id` 等于 `Runner.user_id`。自定义函数返回的标识不能为空，只能包含字母、数字、点、下划线、`@` 和连字符，且不能为 `.` 或 `..`。

```python lines theme={null}
from veadk.memory.long_term_memory import LongTermMemory

memory = LongTermMemory(
    backend="openviking",
    app_name="support_assistant",
    backend_config={
        "peer_id_resolver": lambda app_name, user_id: f"{app_name}-{user_id}",
        "timeout": 60,
    },
)
```

<Warning>
  `peer_id_resolver` 决定 OpenViking 中的用户隔离边界。上线后修改映射规则会使既有记忆落在旧的 peer 路径下，新的检索可能无法命中这些数据。
</Warning>