feat(deploy): add one/split/external modes and smoke scripts for provider contract

Author: Thomas Tupper

.env.example

@@ -2,14 +2,17 @@
 FOXMEMORY_INFER_IMAGE=docker.io/foxlightfoundation/foxmemory-infer:latest
 FOXMEMORY_STORE_IMAGE=docker.io/foxlightfoundation/foxmemory-store:latest
 
-# Infer service
+# infer runtime
 OLLAMA_BASE_URL=http://host.docker.internal:11434
 OLLAMA_EMBED_MODEL=nomic-embed-text
+OLLAMA_CHAT_MODEL=llama3.1:8b
+INFER_API_KEY=
 
-# Store service / mem0 OSS config inputs
+# store runtime
+OPENAI_BASE_URL=http://infer:8081/v1
 OPENAI_API_KEY=
 MEM0_LLM_MODEL=gpt-4.1-nano
 MEM0_EMBED_MODEL=text-embedding-3-small
 QDRANT_COLLECTION=foxmemory
-QDRANT_HOST=qdrant
+QDRANT_HOST=127.0.0.1
 QDRANT_PORT=6333

README.md

@@ -1,12 +1,13 @@
 # foxmemory-deploy
 
-Deployment pack for FoxMemory (Node/TS services + Mem0 OSS-compatible store).
+Deployment pack for FoxMemory.
 
 ## Modes
-1. `compose.one.yml` — one-node (infer + store with embedded qdrant)
-2. `compose.split.yml` — split topology for Mini/R720 style deployments
+1. `compose.one.yml` — one-node (infer + store-with-embedded-qdrant)
+2. `compose.split.yml` — split topology (infer and store on different infrastructure)
+3. `compose.external.yml` — store only; inference via external OpenAI-compatible API
 
-## Quick start
+## Quick start (one-node)
 ```bash
 cp .env.example .env
 docker compose -f compose.one.yml up -d
@@ -29,7 +30,7 @@ curl -s -X POST http://localhost:8082/v1/memories/search \
   -d '{"user_id":"demo","query":"movie preference","top_k":5}'
 ```
 
-## Notes
-- Uses Docker Hub images by default.
-- Configure OPENAI_API_KEY if using OpenAI LLM/embedder path.
-- In one-node mode, Qdrant is embedded in store and persisted via `foxmemory_store_data`.
+## Design contract
+- `foxmemory-store` requires no external container other than optional `foxmemory-infer`.
+- Inference integration uses OpenAI-compatible API shape.
+- Embedded Qdrant is included in store container for two-container deployments.

compose.external.yml

@@ -0,0 +1,23 @@
+# External mode: no infer container; store points to any OpenAI-compatible endpoint.
+services:
+  store:
+    image: ${FOXMEMORY_STORE_IMAGE}
+    container_name: foxmemory-store
+    ports:
+      - "8082:8082"
+      - "6333:6333"
+    environment:
+      - OPENAI_BASE_URL=${OPENAI_BASE_URL}
+      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - MEM0_LLM_MODEL=${MEM0_LLM_MODEL}
+      - MEM0_EMBED_MODEL=${MEM0_EMBED_MODEL}
+      - QDRANT_HOST=127.0.0.1
+      - QDRANT_PORT=6333
+      - QDRANT_COLLECTION=${QDRANT_COLLECTION}
+      - MEM0_HISTORY_DB_PATH=/tmp/history.db
+      - QDRANT_STORAGE_PATH=/qdrant/storage
+    volumes:
+      - foxmemory_store_data:/qdrant/storage
+
+volumes:
+  foxmemory_store_data:

compose.one.yml

@@ -7,6 +7,8 @@ services:
     environment:
       - OLLAMA_BASE_URL=${OLLAMA_BASE_URL}
       - OLLAMA_EMBED_MODEL=${OLLAMA_EMBED_MODEL}
+      - OLLAMA_CHAT_MODEL=${OLLAMA_CHAT_MODEL}
+      - INFER_API_KEY=${INFER_API_KEY}
 
   store:
     image: ${FOXMEMORY_STORE_IMAGE}
@@ -15,7 +17,8 @@ services:
       - "8082:8082"
       - "6333:6333"
     environment:
-      - OPENAI_API_KEY=${OPENAI_API_KEY}
+      - OPENAI_BASE_URL=http://infer:8081/v1
+      - OPENAI_API_KEY=${INFER_API_KEY}
       - MEM0_LLM_MODEL=${MEM0_LLM_MODEL}
       - MEM0_EMBED_MODEL=${MEM0_EMBED_MODEL}
       - QDRANT_HOST=127.0.0.1

compose.split.yml

@@ -1,35 +1,32 @@
+# Split mode: deploy these services on separate hosts if desired.
 services:
-  # Deploy on host A (e.g., Mini)
   infer:
     image: ${FOXMEMORY_INFER_IMAGE}
     ports:
       - "8081:8081"
     environment:
       - OLLAMA_BASE_URL=${OLLAMA_BASE_URL}
       - OLLAMA_EMBED_MODEL=${OLLAMA_EMBED_MODEL}
-
-  # Deploy on host B (e.g., R720)
-  qdrant:
-    image: qdrant/qdrant:v1.13.2
-    ports:
-      - "6333:6333"
-    volumes:
-      - qdrant_data:/qdrant/storage
+      - OLLAMA_CHAT_MODEL=${OLLAMA_CHAT_MODEL}
+      - INFER_API_KEY=${INFER_API_KEY}
 
   store:
     image: ${FOXMEMORY_STORE_IMAGE}
     ports:
       - "8082:8082"
+      - "6333:6333"
     environment:
+      - OPENAI_BASE_URL=${OPENAI_BASE_URL}
       - OPENAI_API_KEY=${OPENAI_API_KEY}
       - MEM0_LLM_MODEL=${MEM0_LLM_MODEL}
       - MEM0_EMBED_MODEL=${MEM0_EMBED_MODEL}
-      - QDRANT_HOST=${QDRANT_HOST:-qdrant}
-      - QDRANT_PORT=${QDRANT_PORT:-6333}
+      - QDRANT_HOST=127.0.0.1
+      - QDRANT_PORT=6333
       - QDRANT_COLLECTION=${QDRANT_COLLECTION}
       - MEM0_HISTORY_DB_PATH=/tmp/history.db
-    depends_on:
-      - qdrant
+      - QDRANT_STORAGE_PATH=/qdrant/storage
+    volumes:
+      - foxmemory_store_data:/qdrant/storage
 
 volumes:
-  qdrant_data:
+  foxmemory_store_data:

scripts/smoke-external.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/.."
+if [ ! -f .env ]; then
+  echo "Create .env from .env.example and set OPENAI_BASE_URL/OPENAI_API_KEY first." >&2
+  exit 1
+fi
+cleanup(){ docker compose -f compose.external.yml down -v >/dev/null 2>&1 || true; }
+trap cleanup EXIT
+
+docker compose -f compose.external.yml up -d
+sleep 6
+curl -fsS http://localhost:8082/health >/dev/null
+
+echo "smoke-external: store healthy"

scripts/smoke-one.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+cd "$(dirname "$0")/.."
+cp -f .env.example .env
+cleanup(){ docker compose -f compose.one.yml down -v >/dev/null 2>&1 || true; rm -f .env; }
+trap cleanup EXIT
+
+docker compose -f compose.one.yml up -d
+sleep 8
+curl -fsS http://localhost:8082/health >/dev/null
+curl -fsS -X POST http://localhost:8082/v1/memories -H 'content-type: application/json' -d '{"user_id":"smoke","messages":[{"role":"user","content":"remember I like tea"}]}' >/dev/null
+curl -fsS -X POST http://localhost:8082/v1/memories/search -H 'content-type: application/json' -d '{"user_id":"smoke","query":"tea","top_k":3}' >/dev/null
+
+echo "smoke-one: OK"