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

```bash
uv sync --extra dev
```

If `uv` is not installed on a fresh server:

```bash
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:

```bash
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:

```bash
cp config.example.yaml config.yaml
```

Start OpenViking and EverOS first, then run:

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

The default Memory System base URL is:

```text
http://127.0.0.1:1934/memory-system
```

## Validation

Run focused tests for touched areas whenever possible:

```bash
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:

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

If dependencies cannot be installed, at minimum run:

```bash
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.