Add memory management APIs for OpenViking: list, read, write, and delete memories

2026-05-29 16:38:57 +08:00
parent 0ab2a35e16
commit 68b2513043
9 changed files with 578 additions and 3 deletions
--- a/README.md
+++ b/README.md
@ -152,6 +152,10 @@ API=http://127.0.0.1:1934/memory-system
 | `POST` | `/sessions/{session_id}/extract` | 立即触发 OpenViking extract | 需要 |
 | `GET/POST` | `/sessions/{session_id}/context` | 查询 OpenViking 会话上下文，并用同一 query 搜索 EverOS 记忆 | 需要 |
 | `GET/POST` | `/openviking/tasks/{task_id}` | 查询 OpenViking 后台任务状态 | 需要 |
+| `GET` | `/memories` | 列出 OpenViking memory URI | 需要 |
+| `GET` | `/memories/content` | 读取某条 memory 内容 | 需要 |
+| `POST` | `/memories` | 创建、覆盖或追加写入 memory | 需要 |
+| `DELETE` | `/memories` | 删除某条 memory URI | 需要 |
 | `POST` | `/resources` | 上传本地文件或远程 URL 到 OpenViking resources | 需要 |
 | `DELETE` | `/resources` | 删除 OpenViking resource URI | 需要 |
 | `POST` | `/search` | 同时搜索 OpenViking 和 EverOS 记忆 | 需要 |
@ -357,6 +361,91 @@ curl -sS -X POST "$API/openviking/tasks/${TASK_ID}" \
  }'
 ```

+### `GET /memories`
+
+列出 OpenViking memory URI。网关会调用 OpenViking：
+
+```http
+GET /api/v1/fs/ls?uri=viking://user/memories&recursive=true
+X-API-Key: <user_key>
+```
+
+Query 参数：
+
+| 参数 | 类型 | 必需 | 说明 |
+|---|---|---:|---|
+| `user_id` | string | 是 | 用户 ID |
+| `user_key` | string | 是 | `/users` 返回的 user key |
+| `uri` | string | 否 | 要列出的 memory 根 URI，默认 `viking://user/memories` |
+| `recursive` | bool | 否 | 是否递归列出，默认 `true` |
+
+示例：
+
+```bash
+curl -sS -G "$API/memories" \
+  --data-urlencode "user_id=userA" \
+  --data-urlencode "user_key=$USER_KEY" \
+  --data-urlencode "uri=viking://user/memories" \
+  --data-urlencode "recursive=true"
+```
+
+### `GET /memories/content`
+
+读取某条 memory 内容。先用 `/memories` 或 `/search` 找到 `viking://user/memories/...` URI，再读取：
+
+```bash
+curl -sS -G "$API/memories/content" \
+  --data-urlencode "user_id=userA" \
+  --data-urlencode "user_key=$USER_KEY" \
+  --data-urlencode "uri=viking://user/memories/preferences/python.md"
+```
+
+### `POST /memories`
+
+创建、覆盖或追加写入 memory。网关会调用 OpenViking `/api/v1/content/write`，写入后由 OpenViking 刷新语义和向量索引。
+
+请求体：
+
+| 参数 | 类型 | 必需 | 说明 |
+|---|---|---:|---|
+| `user_id` | string | 是 | 用户 ID |
+| `user_key` | string | 是 | `/users` 返回的 user key |
+| `uri` | string | 是 | 目标 memory URI，例如 `viking://user/memories/profile.md` |
+| `content` | string | 是 | 要写入的 Markdown/text 内容 |
+| `mode` | `create`/`replace`/`append` | 否 | 写入模式，默认 `create` |
+| `wait` | bool | 否 | 是否等待索引刷新，默认 `true` |
+
+覆盖修改：
+
+```bash
+curl -sS -X POST "$API/memories" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "user_id": "userA",
+    "user_key": "'"$USER_KEY"'",
+    "uri": "viking://user/memories/preferences/python.md",
+    "content": "# Python 偏好\n\n用户偏好使用 Python 做数据分析，常用 pandas。",
+    "mode": "replace",
+    "wait": true
+  }'
+```
+
+追加补充时把 `mode` 改为 `append`；新增 memory 时可用默认的 `create`。
+
+### `DELETE /memories`
+
+删除某条 memory。默认非递归删除；如果 OpenViking 提示目标是目录或复合资源，再把 `recursive` 设为 `true`。
+
+```bash
+curl -sS -X DELETE -G "$API/memories" \
+  --data-urlencode "user_id=userA" \
+  --data-urlencode "user_key=$USER_KEY" \
+  --data-urlencode "uri=viking://user/memories/preferences/python.md" \
+  --data-urlencode "recursive=false"
+```
+
+返回中的 `memory` 是 OpenViking 对应接口的原始响应。
+
 ### `POST /resources`

 上传文件资源到 OpenViking。网关只调用 OpenViking，不写 EverOS。