142 lines
3.0 KiB
Markdown
142 lines
3.0 KiB
Markdown
# Memory System API
|
|
|
|
Memory System API is a lightweight HTTP facade over two memory backends:
|
|
|
|
- OpenViking stores session conversation memory.
|
|
- EverOS stores user profile and episodic memory.
|
|
|
|
The caller only sends `user_id`, `session_id`, and optional `user_message` / `assistant_message`.
|
|
The API creates or reuses the OpenViking user key, writes messages to both backends, and exposes simple endpoints for commit, immediate extraction, search, and profile reads.
|
|
|
|
## Endpoints
|
|
|
|
Base URL:
|
|
|
|
```text
|
|
http://127.0.0.1:1934
|
|
```
|
|
|
|
Routes:
|
|
|
|
- `GET /memory-system/health`
|
|
- `POST /memory-system/messages`
|
|
- `POST /memory-system/sessions/{session_id}/commit`
|
|
- `POST /memory-system/sessions/{session_id}/extract`
|
|
- `GET /memory-system/openviking/tasks/{task_id}?user_id=...`
|
|
- `POST /memory-system/search`
|
|
- `GET /memory-system/users/{user_id}/profile`
|
|
|
|
## Install
|
|
|
|
```bash
|
|
cd /home/tom/memory-gateway
|
|
python -m venv .venv
|
|
source .venv/bin/activate
|
|
pip install -U pip
|
|
pip install -e ".[dev]"
|
|
```
|
|
|
|
## Configure
|
|
|
|
Copy the example config and edit backend URLs or keys as needed:
|
|
|
|
```bash
|
|
cp config.example.yaml config.yaml
|
|
```
|
|
|
|
Important fields:
|
|
|
|
```yaml
|
|
server:
|
|
host: "127.0.0.1"
|
|
port: 1934
|
|
api_key: ""
|
|
|
|
openviking:
|
|
url: "http://127.0.0.1:1933"
|
|
api_key: "your-secret-root-key"
|
|
|
|
everos:
|
|
url: "http://127.0.0.1:1995"
|
|
```
|
|
|
|
If `server.api_key` is set, clients must send `X-API-Key`.
|
|
|
|
## Start
|
|
|
|
Start OpenViking and EverOS first, then run:
|
|
|
|
```bash
|
|
python -m memory_system_api.server --config config.yaml --host 127.0.0.1 --port 1934
|
|
```
|
|
|
|
## Real Test Flow
|
|
|
|
Health:
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:1934/memory-system/health
|
|
```
|
|
|
|
Write user and assistant 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": "好的，我会记住你的咖啡偏好。"
|
|
}'
|
|
```
|
|
|
|
Commit OpenViking and flush EverOS:
|
|
|
|
```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"}'
|
|
```
|
|
|
|
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
|
|
}'
|
|
```
|
|
|
|
Search 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
|
|
}'
|
|
```
|
|
|
|
Read EverOS profile:
|
|
|
|
```bash
|
|
curl -s http://127.0.0.1:1934/memory-system/users/real_user_001/profile
|
|
```
|
|
|
|
## Development Checks
|
|
|
|
```bash
|
|
python -m pytest -q
|
|
python -m compileall -q memory_system_api tests
|
|
```
|