memory-gateway/AGENTS.md

AGENTS.md

Guidance for coding agents working in this repository.

Project Overview

Memory Gateway is a lightweight Python HTTP gateway that exposes one business-facing Memory System API over two memory backends:

• OpenViking handles sessions, session archives, extracted long-term memories, resources, and semantic search.
• EverOS handles profile and episodic-memory style recall.

The main package is memory_system_api. Treat it as a narrow gateway, not a replacement for either backend. Callers should interact with users, sessions, messages, resources, memories, search, and profile endpoints under /memory-system.

Key Contract

Business endpoints are gated by user_id + user_key.

• Create a user first with POST /memory-system/users.
• Save account.result.user_key from the response.
• Pass user_id and user_key on later business calls.
• Do not ask callers to pass account_id.
• Do not ask callers to pass OpenViking root keys.
• X-API-Key is only for protecting the Memory Gateway server itself when server.api_key is configured.

OpenViking user calls use the OpenViking user key as X-API-Key. Admin calls, such as account creation, use the configured OpenViking root key internally.

Important Paths

• memory_system_api/api.py: FastAPI routes under /memory-system.
• memory_system_api/service.py: orchestration across OpenViking and EverOS.
• memory_system_api/clients.py: async HTTP clients for backend APIs.
• memory_system_api/schemas.py: Pydantic request and response models.
• memory_system_api/store.py: SQLite persistence for user keys, sessions, tasks, and archive metadata.
• memory_system_api/config.py: YAML and environment-based configuration.
• plugins/memory/memory_system/: Hermes memory provider plugin that talks to this API.
• skills/memory-system-api/: local agent skill and reference docs for using this API.
• eval/hermes_memory_eval/: LoCoMo-style evaluation runner for Hermes memory behavior.
• tests/: unit tests for clients, service orchestration, server routes, store behavior, and plugin behavior.

API Surface

Current Memory System endpoints include:

• GET /memory-system/health
• POST /memory-system/users
• POST /memory-system/messages
• POST /memory-system/sessions/{session_id}/commit
• POST /memory-system/sessions/{session_id}/extract
• GET|POST /memory-system/sessions/{session_id}/context
• GET|POST /memory-system/openviking/tasks/{task_id}
• GET /memory-system/memories
• GET /memory-system/memories/content
• POST /memory-system/memories
• DELETE /memory-system/memories
• POST /memory-system/resources
• DELETE /memory-system/resources
• POST /memory-system/search
• GET|POST /memory-system/users/{user_id}/profile

Memory writes are implemented through OpenViking POST /api/v1/content/write with mode set to create, replace, or append. Memory reads and deletes use content/read, fs/ls, and fs.

Development Setup

The project uses Python 3.10+.

Common setup:

uv sync --extra dev

If uv is not installed on a fresh server:

curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
uv sync --extra dev

In sandboxed environments, uv may need a writable cache directory:

uv --cache-dir /private/tmp/uv-cache sync --extra dev
uv --cache-dir /private/tmp/uv-cache run pytest -q

Running The Server

Copy the example config before local runs:

cp config.example.yaml config.yaml

Start OpenViking and EverOS first, then run:

uv run memory-gateway --config config.yaml --host 0.0.0.0 --port 1934

The default Memory System base URL is:

http://127.0.0.1:1934/memory-system

Validation

Run focused tests for touched areas whenever possible:

uv run pytest -q tests/test_memory_system_clients.py
uv run pytest -q tests/test_memory_system_service.py
uv run pytest -q tests/test_memory_system_server.py
uv run pytest -q tests/test_memory_system_store.py
uv run pytest -q tests/test_hermes_memory_system_plugin.py

Run the full suite before handing off broad changes:

uv run pytest -q
uv run python -m compileall -q memory_system_api plugins eval tests

If dependencies cannot be installed, at minimum run:

python3 -m compileall -q memory_system_api plugins eval tests

Then report the missing uv or test dependency clearly.

Coding Guidelines

• Keep changes scoped to the relevant API, service, client, schema, plugin, or docs surface.
• Prefer existing patterns in api.py, service.py, clients.py, and tests.
• Add or update tests before changing behavior.
• Preserve the BackendStatus response pattern: top-level status plus per-backend status, result, and error.
• Keep OpenViking-only operations from accidentally touching EverOS.
• Keep search responses compact. Do not return embedding vectors or large raw EverOS original_data blobs.
• Do not introduce in-memory identity caches; SQLite is the source of truth for user keys, sessions, tasks, and archive URIs.
• Do not commit local config.yaml, SQLite databases, real user keys, root keys, or API secrets.
• Use rg for searches and prefer small, targeted patches.

Testing Patterns

The tests use lightweight fake clients and stores. When adding backend client behavior:

• Add client tests that assert exact HTTP path, headers, params, and JSON body.
• Add service tests that assert credential_for_user is called and the correct backend receives the operation.
• Add server route tests when new endpoints are exposed.
• For plugin changes, update tests/test_hermes_memory_system_plugin.py.

Documentation Updates

When changing public behavior, update the relevant docs:

• README.md for user-facing setup and API details.
• skills/memory-system-api/SKILL.md for agent-facing usage.
• skills/memory-system-api/references/api.md when the longer API reference needs to match.
• plugins/memory/memory_system/README.md when Hermes plugin behavior changes.

Safety Notes

• Never include real OpenViking root keys, user keys, Memory System API keys, or EverOS keys in examples.
• Prefer placeholders such as <USER_KEY>, <MEMORY_SYSTEM_API_KEY>, and <OPENVIKING_ROOT_KEY>.
• Keep destructive operations explicit. Deleting memories or resources maps to OpenViking DELETE /api/v1/fs; check recursive defaults and tests carefully.