Configuration

Memory Service is configured entirely through environment variables. This approach works consistently across all deployment methods—Docker, Kubernetes, or bare metal.

Note: Environment variables follow Quarkus conventions. Property names like memory-service.datastore.type become MEMORY_SERVICE_DATASTORE_TYPE as environment variables (dots and hyphens become underscores, all uppercase).

Memory Service Configuration

These are the core Memory Service configuration options:

Database Configuration

Memory Service supports multiple database backends for storing conversation data.

PostgreSQL (Recommended)

# Select PostgreSQL as the datastore
MEMORY_SERVICE_DATASTORE_TYPE=postgres

# PostgreSQL connection
QUARKUS_DATASOURCE_DB_KIND=postgresql
QUARKUS_DATASOURCE_JDBC_URL=jdbc:postgresql://localhost:5432/memoryservice
QUARKUS_DATASOURCE_USERNAME=postgres
QUARKUS_DATASOURCE_PASSWORD=postgres

MongoDB

# Select MongoDB as the datastore
MEMORY_SERVICE_DATASTORE_TYPE=mongo

# MongoDB connection
QUARKUS_MONGODB_CONNECTION_STRING=mongodb://localhost:27017
QUARKUS_MONGODB_DATABASE=memoryservice

Cache Configuration

Memory Service uses a unified cache configuration for all cache-dependent features, including the response resumer and memory entries cache. Configure the cache backend once, and all features will use it automatically.

Memory Entries Cache

When a cache backend is configured, Memory Service caches memory entries to reduce database load and improve GET/sync latency. The cache stores the complete list of memory entries at the latest epoch for each conversation/client pair.

Features of the memory entries cache:

• Automatic population: Cache is populated on first read and updated after sync operations
• Sliding TTL: TTL is refreshed on every cache access (get or set)
• In-memory pagination: Cache stores complete entry list; pagination is applied in-memory
• Graceful degradation: Falls back to database queries if cache is unavailable

Response Resumer Settings

The Response Resumer enables clients to reconnect to in-progress streaming responses after a network interruption. It automatically uses the configured cache backend.

Redis Backend

# Enable Redis cache (response resumer will automatically use it)
MEMORY_SERVICE_CACHE_TYPE=redis

# Redis connection
QUARKUS_REDIS_HOSTS=redis://localhost:6379

# Optional: specify a named Redis client
MEMORY_SERVICE_CACHE_REDIS_CLIENT=my-redis-client

# Optional: disable response resumer even with cache enabled
MEMORY_SERVICE_RESPONSE_RESUMER_ENABLED=false

Infinispan Backend

# Enable Infinispan cache (response resumer will automatically use it)
MEMORY_SERVICE_CACHE_TYPE=infinispan

# Infinispan connection
QUARKUS_INFINISPAN_CLIENT_HOSTS=localhost:11222
QUARKUS_INFINISPAN_CLIENT_USERNAME=admin
QUARKUS_INFINISPAN_CLIENT_PASSWORD=password

# Optional: startup timeout for Infinispan connection
MEMORY_SERVICE_CACHE_INFINISPAN_STARTUP_TIMEOUT=PT30S

# Optional: disable response resumer even with cache enabled
MEMORY_SERVICE_RESPONSE_RESUMER_ENABLED=false

Vector Store Configuration

For semantic search capabilities, configure a vector store and embedding settings.

Embedding Configuration

pgvector (PostgreSQL)

When using PostgreSQL with the pgvector extension:

# Enable pgvector for semantic search
MEMORY_SERVICE_VECTOR_TYPE=pgvector

# Embedding configuration
MEMORY_EMBEDDING_TYPE=hash
MEMORY_EMBEDDING_DIMENSION=256

MongoDB Atlas Vector Search

# Enable MongoDB vector search
MEMORY_SERVICE_VECTOR_TYPE=mongodb

# Embedding configuration
MEMORY_EMBEDDING_TYPE=hash
MEMORY_EMBEDDING_DIMENSION=256

API Key Authentication

Memory Service supports API key authentication for trusted agents. Configure API keys by client ID:

# Format: MEMORY_SERVICE_API_KEYS_<CLIENT_ID>=key1,key2,...
MEMORY_SERVICE_API_KEYS_AGENT_A=agent-a-key-1,agent-a-key-2
MEMORY_SERVICE_API_KEYS_AGENT_B=agent-b-key-1

Clients include the API key in requests via the X-API-Key header.

OIDC Authentication

Memory Service supports OIDC authentication via Keycloak or any compliant provider.

# OIDC configuration
QUARKUS_OIDC_AUTH_SERVER_URL=http://localhost:8180/realms/memory-service
QUARKUS_OIDC_CLIENT_ID=memory-service
QUARKUS_OIDC_CREDENTIALS_SECRET=your-client-secret

Admin Access Configuration

Memory Service provides /v1/admin/* APIs for platform administrators and auditors. Access is controlled through role assignment, which can be configured via OIDC token roles, explicit user lists, or API key client IDs. All three mechanisms are checked — if any grants a role, the caller has that role.

Roles

Role Assignment

Roles can be assigned through three complementary mechanisms:

OIDC Role Mapping

Map OIDC token roles to internal Memory Service roles. This is useful when the OIDC provider uses different role names (e.g., administrator instead of admin).

# Map OIDC "administrator" role to internal "admin" role
MEMORY_SERVICE_ROLES_ADMIN_OIDC_ROLE=administrator

# Map OIDC "manager" role to internal "auditor" role
MEMORY_SERVICE_ROLES_AUDITOR_OIDC_ROLE=manager

# Map OIDC "transcript-indexer" role to internal "indexer" role
MEMORY_SERVICE_ROLES_INDEXER_OIDC_ROLE=transcript-indexer

User-Based Assignment

Assign roles directly to user IDs (matched against the OIDC token principal name):

MEMORY_SERVICE_ROLES_ADMIN_USERS=alice,bob
MEMORY_SERVICE_ROLES_AUDITOR_USERS=charlie,dave
MEMORY_SERVICE_ROLES_INDEXER_USERS=indexer-user

Client-Based Assignment (API Key)

Assign roles to API key client IDs, allowing agents or services to call admin APIs. The client ID is resolved from the X-API-Key header via the existing API key configuration.

MEMORY_SERVICE_ROLES_ADMIN_CLIENTS=admin-agent
MEMORY_SERVICE_ROLES_AUDITOR_CLIENTS=monitoring-agent,audit-agent
MEMORY_SERVICE_ROLES_INDEXER_CLIENTS=indexer-service,summarizer-agent

Audit Logging

All admin API calls are logged to a dedicated logger (io.github.chirino.memory.admin.audit). Each request can include a justification field explaining why the admin action was taken.

# Require justification for all admin operations
MEMORY_SERVICE_ADMIN_REQUIRE_JUSTIFICATION=true

To route admin audit logs to a separate file or external system, configure the Quarkus logging category:

# Set admin audit log level
QUARKUS_LOG_CATEGORY__IO_GITHUB_CHIRINO_MEMORY_ADMIN_AUDIT__LEVEL=INFO

Server Configuration

# HTTP port (default: 8080)
QUARKUS_HTTP_PORT=8080

# gRPC port (uses HTTP port when use-separate-server=false)
QUARKUS_GRPC_SERVER_USE_SEPARATE_SERVER=false

# Enable CORS
QUARKUS_HTTP_CORS=true
QUARKUS_HTTP_CORS_ORIGINS=http://localhost:3000

Production Recommendations

For production deployments, consider the following environment variables:

Connection Pooling

# Database connection pool
QUARKUS_DATASOURCE_JDBC_MAX_SIZE=20
QUARKUS_DATASOURCE_JDBC_MIN_SIZE=5

Health Checks and Metrics

# Enable health endpoints
QUARKUS_HEALTH_EXTENSIONS_ENABLED=true

# Enable Prometheus metrics
QUARKUS_MICROMETER_EXPORT_PROMETHEUS_ENABLED=true

When cache is enabled, the following metrics are available:

Logging

# Set log level
QUARKUS_LOG_LEVEL=INFO
QUARKUS_LOG_CATEGORY__IO_GITHUB_CHIRINO__LEVEL=DEBUG

Example: Docker Compose

services:
  memory-service:
    image: ghcr.io/chirino/memory-service:latest
    environment:
      # Datastore selection
      MEMORY_SERVICE_DATASTORE_TYPE: postgres

      # PostgreSQL connection
      QUARKUS_DATASOURCE_DB_KIND: postgresql
      QUARKUS_DATASOURCE_JDBC_URL: jdbc:postgresql://postgres:5432/memoryservice
      QUARKUS_DATASOURCE_USERNAME: postgres
      QUARKUS_DATASOURCE_PASSWORD: postgres

      # Cache with Redis (response resumer and memory entries cache automatically enabled)
      MEMORY_SERVICE_CACHE_TYPE: redis
      QUARKUS_REDIS_HOSTS: redis://redis:6379
      # Optional: memory entries cache TTL (default: 10 minutes)
      # MEMORY_SERVICE_CACHE_EPOCH_TTL: PT10M

      # Authentication
      QUARKUS_OIDC_AUTH_SERVER_URL: http://keycloak:8180/realms/memory-service
      QUARKUS_OIDC_CLIENT_ID: memory-service
      QUARKUS_OIDC_CREDENTIALS_SECRET: ${OIDC_SECRET}
    depends_on:
      - postgres
      - redis

Next Steps

• Learn about Core Concepts
• Explore Deployment Options