Docker Compose

Docker Compose is the supported way to run Remem 0.5. The Community release builds one Go service containing the HTTP API, MCP endpoint, Pebble storage, local embeddings, search indexes, lifecycle, and background jobs.

Start the Community release

git clone https://github.com/remem-org/remem-community.git
cd remem-community
cp .env.example .env
mkdir -p ./remem-data
sudo chown 10001:10001 ./remem-data
docker compose up --build -d

Set REMEM_SERVER_API_KEY in .env before starting. The default Compose file bind-mounts REMEM_DATA_DIR to /var/lib/remem, so the corpus remains visible on the host and is not removed by docker compose down -v.

The embedding model

The server image does not include the embedding model, which keeps the image small (about 100 MB to download). The model lives in its own host directory, REMEM_MODEL_DIR (./remem-model by default), mounted read-only into the server.

On the first start, a one-shot remem-model service installs the model there before the server starts. It downloads about 2.4 GB and checks every file against a pinned SHA-256, so allow a few minutes. Every later start finds the model already verified and continues in a fraction of a second. If the model directory is empty, the server refuses to start and names the install command.

docker compose logs -f remem-model   # watch the first install

The model comes from Hugging Face by default. It is public and MIT-licensed, so no Hugging Face account is needed. To install it from Docker Hub instead, with no dependency on Hugging Face, set this in .env:

REMEM_MODEL_IMAGE=rememorg/remem-model:pplx-embed-context-v1-0.6b-b42df969

Both sources install the same files, checked against the same hashes. Keep REMEM_MODEL_DIR outside the data directory, so a corpus backup does not carry a copy of the model.

Without network access

The model directory is an ordinary directory, so it can be filled anywhere and copied in. On a machine with access:

docker run --rm -v "$PWD/remem-model":/var/lib/remem-model \
  rememorg/remem-model:pplx-embed-context-v1-0.6b-b42df969

Copy remem-model/ to the server’s REMEM_MODEL_DIR. The first start verifies every file and then continues.

Verify the service

docker compose ps
curl http://localhost:4545/api/v1/ready

Authenticated endpoints use the key from .env:

curl http://localhost:4545/api/v1/memories \
  -H "Authorization: Bearer $REMEM_SERVER_API_KEY"

The HTTP API and Streamable HTTP MCP endpoint are served on port 4545.

Configuration

Remem runs with built-in defaults. To override them, copy config/remem.toml, edit it, and pass it to the server with the --config option or the corresponding environment variables. See Configuration for storage, search, lifecycle, job, tenant, and metrics settings.

Updating

git pull
docker compose up --build -d

An update does not download the model again unless the release changes it. Pebble keeps the corpus durable across container restarts. Back up the host data directory before upgrades and use remem-admin for portable export, import, verification, and index maintenance.

MCP over stdio

The remem-mcp companion binary connects local clients such as Claude Desktop to the running /mcp endpoint. For clients that support Streamable HTTP, use http://localhost:4545/mcp directly.