# Memory Gateway Package Migration Design

## Goal

Move Beaver's Memory Gateway source code and typed configuration into the
existing `beaver.memory` domain package without changing runtime behavior.

This migration affects Python source organization only. It does not move or
modify runtime data under `app-instance/backend/memory/`, the standalone
`/home/tom/memory-gateway` service, or Beaver instance configuration files.

## Target Structure

```text
app-instance/backend/beaver/memory/gateway/
├── __init__.py
├── config.py
├── client.py
└── service.py
```

- `config.py` owns `MemoryConfig` and `MemoryGatewayConfig`.
- `client.py` owns `MemoryGatewayClient` and
  `MemoryGatewayClientError`.
- `service.py` owns `MemoryGatewayService`, `GatewayRecallOutcome`, and
  `GatewayPersistOutcome`.
- `__init__.py` exposes the public Gateway API used by the loader and tests.

## Source Changes

- Remove `beaver/integrations/memory_gateway/`.
- Remove `beaver/services/memory_gateway_service.py`.
- Remove the lazy `MemoryGatewayService` export from `beaver.services`.
- Move the Gateway configuration dataclasses out of
  `beaver.foundation.config.schema`.
- Keep `beaver.foundation.config.loader` responsible for parsing the top-level
  `memory` JSON section, importing the typed models from
  `beaver.memory.gateway`.
- Update `EngineLoader`, tests, README references, and implementation-plan
  source paths to use the new package.
- Do not retain compatibility import modules. After migration,
  `beaver.memory.gateway` is the only supported source entry point.

## Configuration Location

Memory remains configured in each Beaver instance's `config.json`, not inside
the Python package or runtime memory data directory.

Configuration lookup order remains:

1. `BEAVER_CONFIG_PATH`
2. `$BEAVER_HOME/config.json`
3. `<workspace>/.beaver/config.json`
4. `./.beaver/config.json`

For the Docker app instance, the container reads:

```text
/root/.beaver/config.json
```

The corresponding host file is:

```text
app-instance/runtime/instances/<instance-slug>/beaver-home/config.json
```

The `memory` section remains unchanged:

```json
{
  "memory": {
    "mode": "hybrid",
    "gateway": {
      "baseUrl": "http://172.19.0.1:8010",
      "userId": "gateway_test_user",
      "userKey": "uk_xxx",
      "appId": "default",
      "projectId": "default",
      "scope": ["current_chat", "resources"],
      "topK": 8,
      "timeoutSeconds": 10
    }
  }
}
```

`userKey` remains a secret and must not be committed or logged.

## Behavioral Guarantees

- Curated memory behavior is unchanged.
- Hybrid search/add/flush request payloads and ordering are unchanged.
- Gateway audit events and best-effort failure semantics are unchanged.
- The standalone Memory Gateway deployment remains outside Beaver.
- `app-instance/backend/memory/` continues to contain runtime memory data only.

## Verification

- Update all imports and assert no references remain to the removed modules.
- Run Gateway configuration, client/service, loader, context, and AgentLoop
  tests.
- Run the complete backend test suite and Python compile check.
- Scan tracked diffs for credential values.