Deploy MemDBEnterprise

Operator guide for self-hosted MemDB: Docker, Docker Compose, Helm on Kubernetes, Azure and Google Cloud, plus how engineers connect local memtrace clients.

MemDB is the shared graph database behind Memtrace on the Teams plan. You run one MemDB cluster per org on infrastructure you control. Every engineer's local memtrace connects as a pure gRPC client — graph data, embeddings, and episode history live on your cluster, not on laptops. This page is the operator guide; engineer onboarding is Self-hosted MemDB (connect).

Overview#

Choose a deployment path#

Your provisioning bundle's cluster/INSTALL.md is rendered with your org's database name, vector dimensions, and image tag — follow that file first when it disagrees with generic examples here.

Provisioning bundle#

Teams customers receive a tarball with two halves. The cluster/ half is for platform engineers (secrets). The engineer/ half is distributed to developers.

bundle/
├── cluster/                    # platform team — treat as secrets
│   ├── imagePullSecret.yaml    # ghcr.io pull credential (image + OCI Helm chart)
│   ├── tokens.store            # server token store (BLAKE3 hashes, no plaintext)
│   ├── enrollment.secret       # organization assertion verification secret
│   ├── owner-connect.json      # bootstrap admin bearer — owner only
│   ├── values.enterprise.yaml  # pre-rendered Helm values for your org
│   └── INSTALL.md              # org-specific install steps
└── engineer/
    └── connect.json            # endpoint/license metadata — no admin bearer

tokens.store is the read-only bootstrap source. enrollment.secret lets MemDB verify short-lived organization assertions issued after member login. The owner's bootstrap bearer remains in cluster/owner-connect.json for recovery. Do not distribute the cluster half to engineers.

Prerequisites#

All paths require:

• Registry access to ghcr.io/syncable-dev/memcore (private image) via cluster/imagePullSecret.yaml
• cluster/tokens.store and cluster/enrollment.secret — auth is on
• cluster/owner-connect.json kept in your secret manager until the owner workstation is connected
• Outbound HTTPS to memtrace.io from engineer machines for online license validation (offline licenses available — see memtrace connect)
• Immutable vector dimensions: default 768 (jina-embeddings-v2-base-code). Set --vector-dims=768 on first boot; changing later requires a fresh empty data volume.

Docker on a VM (Azure, GCP, on-prem)#

Recommended first deploy when you do not run Kubernetes. Works on an Azure VM, a GCP Compute Engine instance, or any Linux host with Docker Engine 24+.

Pull the image

# Extract GHCR credentials from cluster/imagePullSecret.yaml, then:
docker pull ghcr.io/syncable-dev/memcore:<version-from-your-bundle>

Run single-node MemDB

docker volume create memcore-data

docker run -d --name memcore \
  --restart unless-stopped \
  -p 2424:2424 -p 2480:2480 \
  -v memcore-data:/var/lib/memcore \
  -v "$(pwd)/cluster/tokens.store:/etc/memcore/tokens/tokens.store:ro" \
  -v "$(pwd)/cluster/enrollment.secret:/etc/memcore/tokens/enrollment.secret:ro" \
  ghcr.io/syncable-dev/memcore:<version> \
  --bind 0.0.0.0:2424 \
  --rest-bind 0.0.0.0:2480 \
  --data-dir /var/lib/memcore \
  --default-db=<your-database-from-bundle> \
  --vector-dims=768 \
  --require-auth \
  --auth-token-store /etc/memcore/tokens/tokens.store \
  --auth-enrollment-secret-file /etc/memcore/tokens/enrollment.secret \
  --auth-enrollment-org <organization-id-from-bundle>

Ports: 2424 gRPC (authenticated), 2480 REST /health and /ready (no auth). Restrict gRPC to your VPN or engineer subnet — avoid exposing it on the public internet without TLS.

The memcore-data volume also persists the live user registry at /var/lib/memcore/auth/managed_tokens.toml. Keep tokens.store mounted read-only; adding, rotating, or revoking a user does not modify that mount or restart the container.

Docker Compose#

The single-node Compose file ships in the MemDB repository under deploy/. Copy both auth files next to it before up; missing files fail fast.

Single node

cp <bundle>/cluster/tokens.store deploy/tokens.store
cp <bundle>/cluster/enrollment.secret deploy/enrollment.secret

MEMCORE_IMAGE=ghcr.io/syncable-dev/memcore:<version> \
MEMCORE_ENROLLMENT_ORG=<organization-id-from-bundle> \
  docker compose -f deploy/docker-compose.single.yml up -d

# Health from the host (distroless image — no in-container curl):
curl -fsS http://localhost:2480/health
curl -fsS http://localhost:2480/ready

Three-node raft (one host)

cp <bundle>/cluster/tokens.store deploy/tokens.store

MEMCORE_IMAGE=ghcr.io/syncable-dev/memcore:<version> \
  docker compose -f deploy/docker-compose.ha.yml \
                 -f deploy/docker-compose.ha.publish-all.yml up -d

# Engineers use ordered failover — writes must reach the leader:
export MEMTRACE_MEMDB_ENDPOINTS=http://<host>:2424,http://<host>:2425,http://<host>:2426

Compose HA adds replication on a single machine — you get leader failover between containers, not separate fault domains. Organization enrollment is currently a single-replica feature because managed bearer state is local; keep static bootstrap credentials coordinated for raft deployments.

Kubernetes + Helm#

The canonical chart lives at memcore-rs/helm/memcore in the MemDB repo and publishes as oci://ghcr.io/syncable-dev/charts/memcore. Your bundle's values.enterprise.yaml pins image, auth, and pull secrets.

kubectl create namespace memcore
kubectl -n memcore apply -f cluster/imagePullSecret.yaml

kubectl -n memcore create secret generic memcore-auth \
  --from-file=tokens.store=cluster/tokens.store \
  --from-file=enrollment.secret=cluster/enrollment.secret

helm registry login ghcr.io --username <user> --password <token>

helm install memcore oci://ghcr.io/syncable-dev/charts/memcore \
  --version <chart-version-from-bundle> \
  --namespace memcore \
  -f cluster/values.enterprise.yaml \
  --set auth.existingSecret=memcore-auth

For HA with raft consensus (fixed 3 or 5 replicas, not autoscaling):

helm upgrade --install memcore oci://ghcr.io/syncable-dev/charts/memcore \
  --namespace memcore \
  -f cluster/values.enterprise.yaml \
  --set replicas=3 \
  --set memcore.replication=raft \
  --set networkPolicy.enabled=true \
  --set auth.existingSecret=memcore-auth

In-cluster gRPC endpoint: http://memcore:2424 (Service name follows the Helm release). Engineers outside the cluster need an ingress, VPN, or port-forward — see TLS below.

In the default single-replica deployment, the managed user registry lives on the pod's MemDB PVC and survives rescheduling or upgrades. The memcore-auth Secret remains the bootstrap credential only; normal user changes do not require a Secret update or StatefulSet rollout.

Azure quick reference#

Path A on Azure: provision a Linux VM, attach a Premium SSD data disk, install Docker, run the single-node command above. Set engineer/connect.json endpoint to http://<vm-private-ip>:2424 or your internal DNS name.

Path B on AKS: create a dedicated node pool (no cluster autoscaler on the MemDB pool), install via Helm as above, expose gRPC through an internal load balancer or gRPC-capable ingress.

Google Cloud quick reference#

Path A on GCP: same Docker flow as Azure — one Compute Engine VM with Docker Engine, persistent disk for /var/lib/memcore, NSG-equivalent firewall rules.

Path B on GKE: identical Helm steps to AKS/EKS. Use a regional persistent disk StorageClass for PVCs; snapshot backups via GCE volume snapshots or your CSI driver.

Verify the cluster#

# REST probes (no auth):
curl -fsS http://<host>:2480/health
curl -fsS http://127.0.0.1:2480/ready   # via kubectl port-forward on K8s

# Auth enforcement (grpcurl + memcore.proto — server has no reflection):
# Must REJECT without token:
grpcurl -plaintext -proto memcore.proto \
  <host>:2424 memcore.v1.Memcore/Ping

# Must SUCCEED with writer token:
grpcurl -plaintext -proto memcore.proto \
  -H "authorization: Bearer ${MEMCORE_TOKEN}" \
  <host>:2424 memcore.v1.Memcore/Ping

On Kubernetes: kubectl -n memcore rollout status statefulset/memcore and confirm pods are 2/2 Ready when Studio sidecar is enabled (off by default in current chart).

Connect local memtrace instances#

After MemDB is up, pin its endpoint in the organization enterprise settings and add members on memtrace.io/account. Each member then enrolls with their own signed-in identity:

Organization member onboarding

memtrace auth login
memtrace connect <organization-slug>
memtrace connect --status    # verify endpoint + token + probe
memtrace start               # external mode — no env vars needed

connect verifies the active organization member, exchanges a signed assertion with this MemDB, writes secretless .memtrace/team.toml, and stores the expiring bearer in the member's own credentials.json. No administrator copies or distributes user tokens. Full walkthrough: Self-hosted MemDB and memtrace access.

Environment-variable fallback (CI / scripts)

TLS, sizing, and operations#

TLS (ingress): enable chart ingress with a gRPC-capable controller (nginx by default) and cert-manager. Only the gRPC port is routed; REST probes stay cluster-internal. Set ingress.enabled=true, ingress.host=memdb.example.com, networkPolicy.enabled=true.

Sizing (planning guidance):

Day-two ops: add or remove normal users through organization membership. Removed users cannot renew and their local bearer expires within 24 hours. Use memtrace access revoke for urgent immediate removal and memtrace access add for offline/service accounts. Reserve memcore-auth Secret changes for bootstrap rotation. Upgrade MemDB with a fresh backup first. Prometheus metrics are on :9090/metrics (no auth). Detailed runbooks ship in the MemDB repo under docs/ops/.

Troubleshooting#

Next: engineer onboarding, user access management, memtrace connect flags, and Teams plan quotas.