Skip to content

README.md

Latest commit

 

History

History
163 lines (108 loc) · 4.55 KB

README.md

File metadata and controls

163 lines (108 loc) · 4.55 KB
Raw

foxmemory-deploy

Deployment recipes for the FoxMemory stack.

If you’re new to infra: this repo is the "how to run it" layer. It does not contain core API code; it contains Docker Compose topologies and runbooks.

What this repo is for

  • Start FoxMemory services with sane defaults
  • Choose a topology based on your environment
  • Provide smoke tests and operations runbooks

Topologies

  1. compose.one.yml — one-node stack (infer + store)
  2. compose.split.yml — split deployment across environments
  3. compose.external.yml — only store; inference from an external OpenAI-compatible provider

Quick start (10-minute external path)

Use this path when you already have an OpenAI-compatible provider and want a quick smoke pass.

cp .env.example .env
# set OPENAI_BASE_URL and OPENAI_API_KEY in .env
bash scripts/smoke-memory.sh

Expected success line:

smoke-memory: PASS

Quick start (one-node)

cp .env.example .env
docker compose -f compose.one.yml up -d

Health checks:

curl -s http://localhost:8081/health
curl -s http://localhost:8082/health

Stop:

docker compose -f compose.one.yml down -v

Smoke tests

One-node smoke

bash scripts/smoke-one.sh

External-provider smoke

cp .env.example .env
# set OPENAI_BASE_URL and OPENAI_API_KEY for your provider
bash scripts/validate-env.sh
bash scripts/smoke-external.sh

Env file basics

The .env file configures image tags, model names, and provider keys.

Required environment variables

Variable Purpose Consumed by Example
FOXMEMORY_INFER_IMAGE Infer container image tag Docker Compose (infer) docker.io/foxlightfoundation/foxmemory-infer:latest
FOXMEMORY_STORE_IMAGE Store container image tag Docker Compose (store) docker.io/foxlightfoundation/foxmemory-store:latest
OLLAMA_BASE_URL Local model runtime URL for infer infer service http://host.docker.internal:11434
OLLAMA_EMBED_MODEL Embedding model name for infer infer service nomic-embed-text
OLLAMA_CHAT_MODEL Chat model name for infer infer service llama3.1:8b
INFER_API_KEY API key accepted by infer and forwarded to store in one-node compose infer service; one-node store auth wiring change-me
OPENAI_BASE_URL OpenAI-compatible base URL for store calls store service http://infer:8081/v1
OPENAI_API_KEY Provider API key used by store store service change-me
MEM0_LLM_MODEL LLM model used for memory reasoning store service gpt-4.1-nano
MEM0_EMBED_MODEL Embedding model used by store store service text-embedding-3-small
QDRANT_URL Canonical Qdrant endpoint URL store runtime (where supported) http://qdrant:6333
QDRANT_API_KEY Qdrant auth key (optional) store runtime ``
QDRANT_COLLECTION Collection name for memory vectors store service foxmemory

Backward-compatible variables still present in some scripts/builds:

  • QDRANT_HOST
  • QDRANT_PORT

Troubleshooting (Qdrant / auth / baseURL)

Qdrant connection refused (ECONNREFUSED 127.0.0.1:6333)

Common cause: store container is trying to reach localhost instead of the Docker service name.

Checks:

docker compose -f compose.external.yml ps
curl -s http://localhost:6333/health

Fix:

  • In compose/runtime env, set QDRANT_HOST=qdrant and QDRANT_PORT=6333 for container-to-container calls.
  • Keep localhost:6333 only for host-side diagnostics.

Auth/baseURL mismatch (ENOTFOUND infer, provider auth failures)

Common cause: OPENAI_BASE_URL points to a service that does not exist in the chosen topology.

Checks:

grep -n "OPENAI_BASE_URL" .env

Expected:

  • compose.one.yml: OPENAI_BASE_URL=http://infer:8081/v1
  • compose.external.yml: OPENAI_BASE_URL must point to your external provider (for example https://api.openai.com/v1)

Quick verification commands (expected PASS path)

bash scripts/validate-env.sh
bash scripts/smoke-memory.sh

Expected final line:

smoke-memory: PASS

Docs to read next

  • docs/RUNBOOK.md — step-by-step operations guide

License

MIT (see LICENSE in service repos)

Client backpressure contract (429)

If foxmemory-store (or an upstream dependency) responds with HTTP 429 Too Many Requests, clients should treat Retry-After as authoritative wait time before retrying. This keeps autonomous loops from amplifying overload during partial outages.