# 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
```