Memorix supports Docker as a VPS/hosted HTTP service deployment path.
Local development and verification should run the Node service directly. Do not start Docker Desktop or build a local image just to use Memorix.
This Docker flow is for:
- a long-lived
serve-httpservice - the dashboard on port
3211 - IDEs and agents that connect over
http://host:3211/mcp
It is not a containerized form of memorix serve (stdio MCP).
From the repository root:
docker compose up --build -dThen open:
- dashboard:
http://localhost:3211 - MCP endpoint:
http://localhost:3211/mcp - health:
http://localhost:3211/health
The compose port is bound to 127.0.0.1 by default. Do not expose this
unauthenticated control plane directly to the public internet. For a hosted
deployment, put it behind an authenticated reverse proxy or a private network
boundary before allowing remote clients to connect.
Set MEMORIX_HTTP_AUTH_TOKEN in the service environment when the control plane
must accept remote clients. Send it as Authorization: Bearer <token>; the
/health endpoint remains unauthenticated for readiness checks. The supplied
compose file uses an explicit unauthenticated-bind opt-in because its published
host port is loopback-only.
HTTP JSON bodies are limited to 10 MiB by default (dashboard maintenance
requests use a 1 MiB sub-limit). Operators can set
MEMORIX_HTTP_MAX_BODY_BYTES, up to 64 MiB, when a trusted local client needs
larger media or tool payloads.
Stop it with:
docker compose downThe provided compose file:
- persists Memorix state in a named volume
- mounts the current repository at
/workspace - sets
MEMORIX_PROJECT_ROOT=/workspace - sets
MEMORIX_SESSION_TIMEOUT_MS=86400000so long IDE HTTP sessions can remain idle for up to 24 hours
If you prefer docker run:
docker build -t memorix:local .
docker run --rm -p 127.0.0.1:3211:3211 \
-e MEMORIX_HTTP_ALLOW_UNAUTHENTICATED_BIND=1 \
-v memorix-data:/data memorix:localmemorix serve-http accepts a --host flag:
- Local (default): binds to
127.0.0.1— only accessible from the host machine - Docker: the Dockerfile sets
--host 0.0.0.0— accessible from outside the container, which is required for port mapping (-p 3211:3211) to work. SetMEMORIX_HTTP_AUTH_TOKEN, or explicitly opt into an unauthenticated private-network bind withMEMORIX_HTTP_ALLOW_UNAUTHENTICATED_BIND=1.
If you run serve-http manually inside a container, make sure to pass
--host 0.0.0.0 plus one of those explicit security settings, or the server
will refuse to start.
The official Docker artifacts in this repo provide:
- a multi-stage production image
- an example
compose.yaml - a healthchecked HTTP deployment
Docker support is for the HTTP service:
memorix serve-http- dashboard access
- HTTP MCP clients pointing at
http://localhost:3211/mcp
It is not a promise that stdio MCP magically becomes container-friendly.
VPS Docker works best when Memorix can see the repositories it is asked to bind.
Project-scoped features such as:
- Git-root detection
- project binding
- project
memorix.toml - project
.env - Git Memory inspection
depend on the HTTP service being able to access the repository path.
- a VPS or hosted machine that can see the repositories it is asked to bind
- a compose setup that mounts the repo you are working on into the container
memorix_session_start(projectRoot=...)using a path visible inside the container
If an IDE on machine A sends projectRoot=/Users/alice/code/app, but the Docker container running on machine B cannot see that path, Memorix cannot perform project-scoped detection there.
In that case:
- HTTP connectivity still works
- global/shared memory still works
- but project-scoped Git/config semantics will not be fully available until the repo is mounted into the container at a visible path
This is a real runtime limitation, not just a documentation preference.
Useful checks:
curl http://localhost:3211/health
curl http://localhost:3211/api/stats
docker compose logs -f memorix
docker compose psThe HTTP MCP transport defaults to a 12-hour idle timeout. The example
compose.yaml raises this to 24 hours for IDEs that keep one HTTP MCP session
open while the user reads diffs, runs tests, or switches focus. When a session
does expire, the service returns a fast 404 so the client can initialize a
fresh MCP session.
To change it:
environment:
MEMORIX_SESSION_TIMEOUT_MS: 86400000