添加内存管理工具和用户密钥支持，更新文档和测试用例
This commit is contained in:
@ -1,6 +1,6 @@
|
||||
---
|
||||
name: memory-system-api
|
||||
description: "Use when an AI agent needs to operate this repository's Memory System API, including creating users, writing session messages, committing or extracting memory, searching memories, reading profiles, or debugging OpenViking/EverOS backend results."
|
||||
description: "Use when an AI agent needs to operate this repository's Memory System API, including creating users, writing session messages, committing or extracting memory, managing memory URIs, searching memories, reading profiles, or debugging OpenViking/EverOS backend results."
|
||||
---
|
||||
|
||||
# Memory System API
|
||||
@ -26,13 +26,13 @@ Do not assume business APIs will auto-create users. Non-user-creation endpoints
|
||||
- `user_key`: OpenViking key returned when the user is created.
|
||||
- `session_id`: conversation ID and OpenViking session ID.
|
||||
|
||||
Internally the gateway always uses the fixed OpenViking admin workspace:
|
||||
Internally the gateway creates one isolated OpenViking account per business user:
|
||||
|
||||
```json
|
||||
{"account_id": "admin", "admin_user_id": "admin"}
|
||||
{"account_id": "<user_id>_account", "admin_user_id": "<user_id>"}
|
||||
```
|
||||
|
||||
On the first user creation, if the admin workspace is not stored in SQLite yet, the gateway creates it first and then creates the requested user. After that, later users go straight to `/api/v1/admin/accounts/admin/users`.
|
||||
The gateway does not call `/api/v1/admin/accounts/admin/users`. User creation goes through `/api/v1/admin/accounts`, stores the returned `user_key`, and later business calls use that user key directly.
|
||||
|
||||
The SQLite store is the source of truth for:
|
||||
|
||||
@ -44,8 +44,9 @@ The SQLite store is the source of truth for:
|
||||
Session memory is retrieved under OpenViking using the explicit user/session URI paths:
|
||||
|
||||
```text
|
||||
viking://user/<user_id>/memories/
|
||||
viking://user/<user_id>/<session_id>
|
||||
viking://user/memories
|
||||
viking://user/memories/...
|
||||
viking://user/<session_id>
|
||||
```
|
||||
|
||||
## Endpoints
|
||||
@ -65,6 +66,8 @@ Base path: `/memory-system`
|
||||
| `GET` | `/memories/content` | Read one OpenViking memory URI | Yes |
|
||||
| `POST` | `/memories` | Create, replace, or append an OpenViking memory via `content/write` | Yes |
|
||||
| `DELETE` | `/memories` | Delete an OpenViking memory URI via `fs` | Yes |
|
||||
| `POST` | `/resources` | Upload local file or remote URL to OpenViking resources | Yes |
|
||||
| `DELETE` | `/resources` | Delete OpenViking resource URI via `fs` | Yes |
|
||||
| `POST` | `/search` | Search OpenViking and EverOS | Yes |
|
||||
| `GET` | `/users/{user_id}/profile` | Read EverOS profile | Yes |
|
||||
|
||||
@ -195,6 +198,8 @@ curl -sS -X DELETE -G "$BASE/memory-system/memories" \
|
||||
--data-urlencode "recursive=false"
|
||||
```
|
||||
|
||||
For directory-like or composite memories, retry deletion with `recursive=true` only after OpenViking reports that recursive deletion is required.
|
||||
|
||||
## Response Handling
|
||||
|
||||
Top-level `status` is one of:
|
||||
@ -213,6 +218,8 @@ Session context responses include OpenViking context under `context`, EverOS rec
|
||||
- Omitting `user_key` on business calls.
|
||||
- Sending `account_id` to business APIs.
|
||||
- Confusing `X-API-Key` with `user_key`.
|
||||
- Assuming memory updates use a PATCH endpoint; use `POST /memory-system/memories` with `mode=replace` or `mode=append`.
|
||||
- Deleting memories recursively by default; use `recursive=false` unless the target is a directory or composite resource.
|
||||
- Expecting `backends.everos.result` to still contain full `episodes` or `original_data`.
|
||||
- Assuming the gateway stores these values only in memory; it persists them in SQLite.
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
interface:
|
||||
display_name: "Memory System API"
|
||||
short_description: "Use the configured Memory System API endpoint from AI agents."
|
||||
default_prompt: "Use the Memory System API skill with the configured endpoint to create users, write conversation memory with user_id and user_key, trigger extraction, search memory, and read user profiles."
|
||||
default_prompt: "Use the Memory System API skill with the configured endpoint to create users, write session messages with user_id and user_key, commit or extract sessions, manage memory URIs, search memory, and read user profiles."
|
||||
|
||||
@ -20,6 +20,34 @@ If an API key is configured, add:
|
||||
curl -s <MEMORY_SYSTEM_BASE_URL>/memory-system/health
|
||||
```
|
||||
|
||||
## Create User
|
||||
|
||||
Create the business user before calling any business endpoint:
|
||||
|
||||
```bash
|
||||
curl -s -X POST <MEMORY_SYSTEM_BASE_URL>/memory-system/users \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"user_id": "<USER_ID>"}'
|
||||
```
|
||||
|
||||
Save the returned `account.result.user_key` and pass it as `user_key` on later calls:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"account": {
|
||||
"status": "ok",
|
||||
"result": {
|
||||
"account_id": "<USER_ID>_account",
|
||||
"admin_user_id": "<USER_ID>",
|
||||
"user_key": "<USER_KEY>"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Do not send `account_id` to business endpoints.
|
||||
|
||||
## Write Messages
|
||||
|
||||
```bash
|
||||
@ -134,6 +162,68 @@ Response shape:
|
||||
}
|
||||
```
|
||||
|
||||
## Manage Memories
|
||||
|
||||
Memory management operates on OpenViking memory URIs, usually under `viking://user/memories`. There is no separate PATCH endpoint. Update existing memory by writing directly to its URI.
|
||||
|
||||
### List Memory URIs
|
||||
|
||||
```bash
|
||||
curl -sS --get "<MEMORY_SYSTEM_BASE_URL>/memory-system/memories" \
|
||||
--data-urlencode "user_id=<USER_ID>" \
|
||||
--data-urlencode "user_key=<USER_KEY>" \
|
||||
--data-urlencode "uri=viking://user/memories" \
|
||||
--data-urlencode "recursive=true"
|
||||
```
|
||||
|
||||
This maps to OpenViking `GET /api/v1/fs/ls`.
|
||||
|
||||
### Read Memory Content
|
||||
|
||||
```bash
|
||||
curl -sS --get "<MEMORY_SYSTEM_BASE_URL>/memory-system/memories/content" \
|
||||
--data-urlencode "user_id=<USER_ID>" \
|
||||
--data-urlencode "user_key=<USER_KEY>" \
|
||||
--data-urlencode "uri=viking://user/memories/preferences/python.md"
|
||||
```
|
||||
|
||||
This maps to OpenViking `GET /api/v1/content/read`.
|
||||
|
||||
### Create, Replace, Or Append Memory
|
||||
|
||||
```bash
|
||||
curl -sS -X POST "<MEMORY_SYSTEM_BASE_URL>/memory-system/memories" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"user_id": "<USER_ID>",
|
||||
"user_key": "<USER_KEY>",
|
||||
"uri": "viking://user/memories/preferences/python.md",
|
||||
"content": "# Python 偏好\n\n用户偏好使用 Python 做数据分析，常用 pandas。",
|
||||
"mode": "replace",
|
||||
"wait": true
|
||||
}'
|
||||
```
|
||||
|
||||
`mode` supports:
|
||||
|
||||
- `create`: create a new memory URI.
|
||||
- `replace`: fully replace an existing memory.
|
||||
- `append`: append content to an existing memory.
|
||||
|
||||
This maps to OpenViking `POST /api/v1/content/write`. OpenViking refreshes semantic and vector indexes after writing.
|
||||
|
||||
### Delete Memory
|
||||
|
||||
```bash
|
||||
curl -sS -X DELETE --get "<MEMORY_SYSTEM_BASE_URL>/memory-system/memories" \
|
||||
--data-urlencode "user_id=<USER_ID>" \
|
||||
--data-urlencode "user_key=<USER_KEY>" \
|
||||
--data-urlencode "uri=viking://user/memories/preferences/python.md" \
|
||||
--data-urlencode "recursive=false"
|
||||
```
|
||||
|
||||
Default to `recursive=false`. If OpenViking reports that the URI is a directory or composite resource, retry with `recursive=true`.
|
||||
|
||||
## Search
|
||||
|
||||
Without LLM planning:
|
||||
|
||||
Reference in New Issue
Block a user