docs/superpowers/specs/2026-06-15-memory-gateway-package-migration-design.md

@@ -0,0 +1,104 @@
+# 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.