tomtan/memory-gateway
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

兼容新版 EverOS memory API

Browse Source
This commit is contained in:
tomtan
2026-06-10 10:47:36 +08:00
parent 64e3ea9631
commit 000415404b
5 changed files with 177 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
README.md
View File

@ -66,7 +66,7 @@ Memory Gateway 需要先连上两个后端服务。默认本地端口约定：
| 服务 | 默认地址 | 作用 |
|---|---|---|
| OpenViking | `http://127.0.0.1:1933` | session、archive、long-term memory、resources、semantic search |
| EverOS EverCore | `http://127.0.0.1:1995` | profile、episodic memory、recall |
| EverOS | `http://127.0.0.1:1995` | profile、episodic memory、recall |
| Memory Gateway | `http://127.0.0.1:1934` | 对业务方暴露统一 `/memory-system` API |
### 安装 OpenViking
@ -82,23 +82,28 @@ pip install openviking --upgrade --force-reinstall
如果本机已经有 OpenViking 源码或已安装的 `openviking-server`，可以跳过安装，直接确认 `openviking-server --help` 可用。
### 安装 EverOS / EverCore
### 安装 EverOS
Memory Gateway 使用 EverOS 里的 EverCore HTTP 服务。按 [EverOS / EverCore Quick Start](https://github.com/EverMind-AI/EverOS#evercore)：
Memory Gateway 使用当前 EverOS HTTP 服务：
```bash
git clone https://github.com/EverMind-AI/EverOS.git /Users/tom/projects/EverOS
cd /Users/tom/projects/EverOS/methods/EverCore
cd /Users/tom/projects/EverOS
# 需要 Docker 和 Python 3.12。
cp /Users/tom/projects/memory-gateway/everos.env.example .env
# 编辑 .env，至少填入实际可用的 LLM_API_KEY 和 VECTORIZE_API_KEY。
docker compose up -d
uv sync
# 编辑 .env，至少配置 LLM、multimodal、embedding、rerank 的 model/api_key/base_url。
uv sync --extra dev
```
如果 EverOS 已经在本机存在，只需要进入 `methods/EverCore` 并补齐 `.env`。
如果 EverOS 已经在本机存在，只需要进入 EverOS 根目录并补齐 `.env`。
当前 Memory Gateway 兼容的 EverOS v1 记忆接口是：
```text
POST /api/v1/memory/add
POST /api/v1/memory/flush
POST /api/v1/memory/search
POST /api/v1/memory/get
```
### 安装 Memory Gateway
@ -149,16 +154,25 @@ openviking-server doctor
`root_api_key` 只放在 OpenViking 和 Memory Gateway 的服务端配置里。业务调用方不要传 root key。
### EverOS / EverCore 配置
### EverOS 配置
Memory Gateway 仓库内也提供 EverOS / EverCore 的 `.env` 模板。复制到 EverCore 目录：
在 EverOS 根目录创建或编辑 `.env`：
```bash
cd /Users/tom/projects/EverOS/methods/EverCore
cp /Users/tom/projects/memory-gateway/everos.env.example .env
cd /Users/tom/projects/EverOS
$EDITOR .env
```
然后编辑 `.env`，至少填入 `LLM_API_KEY`、`LLM_MODEL`、`VECTORIZE_API_KEY`、`EMBEDDING_MODEL` 和 `RERANK_MODEL`。Docker 依赖地址默认使用模板里的本地 compose 端口；如果改过 EverCore 的 compose 配置，需要同步修改 `.env`。
至少需要配置：
```text
EVEROS_LLM__MODEL / EVEROS_LLM__API_KEY / EVEROS_LLM__BASE_URL
EVEROS_MULTIMODAL__MODEL / EVEROS_MULTIMODAL__API_KEY / EVEROS_MULTIMODAL__BASE_URL
EVEROS_EMBEDDING__MODEL / EVEROS_EMBEDDING__API_KEY / EVEROS_EMBEDDING__BASE_URL
EVEROS_RERANK__MODEL / EVEROS_RERANK__API_KEY / EVEROS_RERANK__BASE_URL
```
大模型较慢时，建议同时设置 `EVEROS_LLM__TIMEOUT_SECONDS` 和 `EVEROS_MULTIMODAL__TIMEOUT_SECONDS`。
### Memory Gateway 配置
@ -220,12 +234,11 @@ openviking-server --config ~/.openviking/ov.conf
如果使用 Docker 方式运行 OpenViking，确认对 Memory Gateway 暴露的是 `1933` 端口，避免和 Memory Gateway 的 `1934` 端口冲突。
终端 2：启动 EverOS / EverCore。
终端 2：启动 EverOS。
```bash
cd /Users/tom/projects/EverOS/methods/EverCore
docker compose up -d
uv run python src/run.py --port 1995
cd /Users/tom/projects/EverOS
uv run everos server start
```
终端 3：启动 Memory Gateway。
@ -335,7 +348,7 @@ curl -sS -X POST "$API/users" \
### `POST /messages`
写入用户消息和/或助手消息。至少要传 `user_message` 或 `assistant_message` 其中一个。网关会先确保 OpenViking user/session 存在，再把消息写入 OpenViking session，同时写入 EverOS。
写入用户消息和/或助手消息。至少要传 `user_message` 或 `assistant_message` 其中一个。网关会先确保 OpenViking user/session 存在，再把消息写入 OpenViking session，同时调用 EverOS `POST /api/v1/memory/add`。
请求体：
@ -367,7 +380,7 @@ curl -sS -X POST "$API/messages" \
### `POST /sessions/{session_id}/commit`
提交会话。OpenViking 会归档 session 并异步抽取长期记忆，通常会返回 `task_id`；EverOS 会 flush 当前 session。
提交会话。OpenViking 会归档 session 并异步抽取长期记忆，通常会返回 `task_id`；EverOS 会调用 `POST /api/v1/memory/flush` flush 当前 session。
路径参数：
@ -419,7 +432,7 @@ GET /api/v1/sessions/{session_id}/context
X-API-Key: <user_key>
```
同时用同一个 `query` 调用 EverOS `/api/v1/memories/search`，返回相关 episodic/profile/raw message 记忆。适合在回答用户问题前，把“当前 session 工作记忆”和“EverOS 相关记忆”一起取回。
同时用同一个 `query` 调用 EverOS `POST /api/v1/memory/search`，请求体使用顶层 `user_id`，并把 `session_id` 放在 `filters.session_id` 中。适合在回答用户问题前，把“当前 session 工作记忆”和“EverOS 相关记忆”一起取回。
路径参数：
@ -455,7 +468,7 @@ curl -sS -X POST "$API/sessions/sessionA1/context" \
|---|---|
| `context` | OpenViking `result`，包含 `latest_archive_overview`、`pre_archive_abstracts`、`messages`、`stats` |
| `items` | EverOS 搜索命中的精简记忆结果，含 `source_backend: "everos"` |
| `backends` | 两个后端的精简诊断信息，不重复返回完整 OpenViking context 或 EverOS `original_data` |
| `backends` | 两个后端的精简诊断信息，不重复返回完整 OpenViking context 或 EverOS 原始大 payload |
### `GET/POST /openviking/tasks/{task_id}`
@ -667,7 +680,7 @@ curl -sS -X DELETE -G "$API/resources" \
### `POST /search`
同时查询 OpenViking 和 EverOS，并合并结果。
同时查询 OpenViking 和 EverOS，并合并结果。EverOS 分支调用 `POST /api/v1/memory/search`，请求体形如 `{"user_id": "...", "query": "...", "method": "hybrid|agentic", "top_k": 10, "include_profile": true, "filters": {"session_id": "..."}}`。
请求体：
@ -675,7 +688,7 @@ curl -sS -X DELETE -G "$API/resources" \
|---|---|---:|---|
| `user_id` | string | 是 | 用户 ID |
| `user_key` | string | 是 | `/users` 返回的 user key |
| `session_id` | string/null | 否 | 会话 ID；用于 EverOS 过滤和鉴权身份 |
| `session_id` | string/null | 否 | 会话 ID；用于 EverOS `filters.session_id` 和 OpenViking agent identity |
| `query` | string | 是 | 查询文本 |
| `use_llm` | bool | 否 | 只影响 EverOS 检索方式：`false` 使用 hybrid，`true` 使用 agentic |
| `limit` | int | 否 | 返回条数，默认 10，范围 1 到 100 |
@ -707,11 +720,11 @@ curl -sS -X POST "$API/search" \
|---|---|
| `status` | 总体状态 |
| `items` | 合并后的记忆结果，含 `source_backend` |
| `backends` | 两个后端的精简诊断信息，例如命中数量、query plan 或查询过滤条件；不再回传完整原始命中和 `original_data` |
| `backends` | 两个后端的精简诊断信息，例如命中数量、query plan 或查询过滤条件；不再回传完整原始命中 |
### `GET/POST /users/{user_id}/profile`
读取用户画像。该接口需要 `user_key`，用于确认调用方属于该 user。网关会读取 EverOS profile，并用同一个 `query` 调 OpenViking `/api/v1/search/search`，固定传 `target_uri: viking://user/memories` 和 `level`。
读取用户画像。该接口需要 `user_key`，用于确认调用方属于该 user。网关会调用 EverOS `POST /api/v1/memory/get`，请求体为 `{"user_id": "...", "memory_type": "profile", "page": 1, "page_size": 20}`；同时用同一个 `query` 调 OpenViking `/api/v1/search/search`，固定传 `target_uri: viking://user/memories` 和 `level`。
请求体：