Deployment

Docker Compose (Single Instance)

cd Memoria
cp .env.example .env   # Set MEMORIA_MASTER_KEY, MEMORIA_EMBEDDING_API_KEY
docker compose up -d

Services: API on :8100, MatrixOne on :6001. Verify: curl http://localhost:8100/health

Environment Variables

Required

Database

Embedding

Distributed

Governance

Security

LLM (for reflect/extract-entities/episodic)

External MatrixOne

Use an existing MatrixOne instead of the bundled one:

MEMORIA_DB_HOST=your-host MEMORIA_DB_PORT=6001 docker compose up -d api

Tables are auto-created on first startup.

Multi-Instance (K8s)

All coordination uses the shared MatrixOne database — zero external dependencies.

How it works:

• Governance scheduler: Each instance acquires a DB lock before each task. Only one wins; others skip. Heartbeat renews every TTL/3.
• Async tasks: Stored in mem_async_tasks table, visible cross-instance.
• Lock expiry: Crashed instance's locks expire after TTL, another takes over.
• Single-instance: NoopDistributedLock — zero overhead, identical behavior.

K8s Manifest

apiVersion: apps/v1
kind: Deployment
metadata:
  name: memoria-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: memoria-api
  template:
    metadata:
      labels:
        app: memoria-api
    spec:
      containers:
        - name: memoria
          image: matrixorigin/memoria:latest
          ports:
            - containerPort: 8100
          env:
            - name: MEMORIA_INSTANCE_ID
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
            - name: MEMORIA_MASTER_KEY
              valueFrom:
                secretKeyRef:
                  name: memoria-secrets
                  key: master-key
            - name: MEMORIA_DB_HOST
              value: "matrixone.default.svc.cluster.local"
            - name: MEMORIA_DB_PORT
              value: "6001"
            - name: MEMORIA_EMBEDDING_PROVIDER
              value: "openai"
            - name: MEMORIA_EMBEDDING_API_KEY
              valueFrom:
                secretKeyRef:
                  name: memoria-secrets
                  key: embedding-api-key
            # Optional: multi-backend round-robin (supersedes API_KEY + MODEL single-backend)
            # - name: MEMORIA_EMBEDDING_ENDPOINTS
            #   value: '[{"url":"https://api1.example.com/v1","api_key":"sk-1"},{"url":"https://api2.example.com/v1","api_key":"sk-2"}]'
            - name: MEMORIA_EMBEDDING_MODEL
              value: "BAAI/bge-m3"
            - name: MEMORIA_EMBEDDING_DIM
              value: "1024"
            - name: MEMORIA_GOVERNANCE_ENABLED
              value: "true"
            - name: MEMORIA_LOCK_TTL_SECS
              value: "120"
          livenessProbe:
            httpGet:
              path: /health
              port: 8100
            initialDelaySeconds: 5
            periodSeconds: 10
          readinessProbe:
            httpGet:
              path: /health/instance
              port: 8100
            initialDelaySeconds: 5
            periodSeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: memoria-api
spec:
  selector:
    app: memoria-api
  ports:
    - port: 8100
      targetPort: 8100

Key points:

• MEMORIA_INSTANCE_ID → fieldRef: metadata.name (Pod name)
• All replicas share one MatrixOne
• Leader election is automatic
• Liveness: /health, Readiness: /health/instance

Data Persistence

MatrixOne data bind-mounted to ./data/matrixone. Survives restarts. Change: MATRIXONE_DATA_DIR=/your/path

Security Notes

• API keys are HMAC-SHA256 hashed at rest
• Set MEMORIA_API_KEY_SECRET independently of MASTER_KEY for key rotation
• All queries scoped to authenticated user_id
• Snapshot names are regex-validated before SQL
• Rate limiting per API key (in-memory sliding window)
• Run behind reverse proxy with TLS in production

Rate Limits

Configurable via env: MEMORIA_RATE_LIMIT_AUTH_KEYS=1000,60 (format: max_requests,window_seconds)