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:

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

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:

cp config.example.yaml config.yaml

Important fields:

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:

python -m memory_system_api.server --config config.yaml --host 127.0.0.1 --port 1934

Real Test Flow

Health:

curl -s http://127.0.0.1:1934/memory-system/health

Write user and assistant messages:

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:

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:

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:

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:

curl -s http://127.0.0.1:1934/memory-system/users/real_user_001/profile

Development Checks

python -m pytest -q
python -m compileall -q memory_system_api tests

3.0 KiB Raw Blame History