127 lines
3.1 KiB
Markdown
127 lines
3.1 KiB
Markdown
# Memory System API Reference
|
|
|
|
Base URL defaults to:
|
|
|
|
```text
|
|
http://127.0.0.1:1934
|
|
```
|
|
|
|
If `server.api_key` is configured, add:
|
|
|
|
```bash
|
|
-H "X-API-Key: <gateway-api-key>"
|
|
```
|
|
|
|
## Health
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:1934/memory-system/health
|
|
```
|
|
|
|
## Write Messages
|
|
|
|
```bash
|
|
curl -s -X POST http://127.0.0.1:1934/memory-system/messages \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"user_id": "real_user_001",
|
|
"session_id": "real_sess_001",
|
|
"user_message": "我喜欢喝拿铁，不喜欢美式。",
|
|
"assistant_message": "好的，我会记住你的咖啡偏好。"
|
|
}'
|
|
```
|
|
|
|
`user_message` and `assistant_message` are optional independently, but at least one must be present.
|
|
|
|
## Commit Session
|
|
|
|
```bash
|
|
curl -s -X POST http://127.0.0.1:1934/memory-system/sessions/real_sess_001/commit \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"user_id": "real_user_001"}'
|
|
```
|
|
|
|
Use the returned OpenViking task ID, if present:
|
|
|
|
```bash
|
|
curl -s "http://127.0.0.1:1934/memory-system/openviking/tasks/<TASK_ID>?user_id=real_user_001"
|
|
```
|
|
|
|
`commit` can return `partial_success` if OpenViking accepted the archive but EverOS flush failed or timed out. This is retryable:
|
|
|
|
```json
|
|
{
|
|
"status": "partial_success",
|
|
"backends": {
|
|
"openviking": {"status": "success", "result": {"status": "ok"}},
|
|
"everos": {"status": "failed", "error": "ReadTimeout"}
|
|
}
|
|
}
|
|
```
|
|
|
|
Wait for EverOS or its upstream LLM/rerank service to recover, then call the same commit endpoint again.
|
|
|
|
## Immediate Extract
|
|
|
|
```bash
|
|
curl -s -X POST http://127.0.0.1:1934/memory-system/sessions/real_sess_001/extract \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"user_id": "real_user_001"}'
|
|
```
|
|
|
|
## Search
|
|
|
|
Without LLM planning:
|
|
|
|
```bash
|
|
curl -s -X POST http://127.0.0.1:1934/memory-system/search \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"user_id": "real_user_001",
|
|
"session_id": "real_sess_001",
|
|
"query": "我喜欢喝什么咖啡？",
|
|
"use_llm": false,
|
|
"limit": 10
|
|
}'
|
|
```
|
|
|
|
With LLM planning:
|
|
|
|
```bash
|
|
curl -s -X POST http://127.0.0.1:1934/memory-system/search \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"user_id": "real_user_001",
|
|
"session_id": "real_sess_001",
|
|
"query": "我的偏好是什么？",
|
|
"use_llm": true,
|
|
"limit": 10
|
|
}'
|
|
```
|
|
|
|
Search responses include merged `items` plus backend debug data. Fields named `vector` are stripped recursively before the API returns JSON, so responses stay small even when EverOS includes `original_data`. Metadata keys such as `vector_model` may still be present.
|
|
|
|
## Profile
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:1934/memory-system/users/real_user_001/profile
|
|
```
|
|
|
|
## Response Interpretation
|
|
|
|
Inspect backend status:
|
|
|
|
```json
|
|
{
|
|
"status": "partial_success",
|
|
"backends": {
|
|
"openviking": {"status": "success", "result": {}},
|
|
"everos": {"status": "failed", "error": "..."}
|
|
}
|
|
}
|
|
```
|
|
|
|
Use backend-specific errors for debugging.
|
|
|
|
OpenViking user keys are intentionally hidden from callers. If OpenViking already has an account but the local API has no stored key, Memory System API falls back to the configured OpenViking root key plus identity headers internally.
|