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

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:

BEAVER_CONFIG_PATH
$BEAVER_HOME/config.json
<workspace>/.beaver/config.json
./.beaver/config.json

For the Docker app instance, the container reads:

/root/.beaver/config.json

The corresponding host file is:

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

The memory section remains unchanged:

{
  "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.

3.1 KiB Raw Blame History