Dev Services

The Memory Service Quarkus extension provides Dev Services that automatically start a memory-service container in development mode. This lets a Quarkus agent app run locally without a separate Memory Service setup.

Why Use Dev Services?

Dev Services automatically:

  • Starts a memory-service container using the ghcr.io/chirino/memory-service:latest image
  • Configures your application with the correct connection URL and API key
  • Uses self-contained local storage inside the container for development
  • Connects to Keycloak Dev Services when your app configures OIDC
  • Handles container lifecycle when the application starts and stops
  • Generates secure API keys automatically if not configured

The default memory-service container does not require PostgreSQL, MongoDB, Redis, Infinispan, Qdrant, or pgvector dev services. It runs with SQLite, local cache, SQLite vector search, local embeddings, and filesystem attachments.

How It Works

When you run your Quarkus application in dev mode (mvn quarkus:dev), the extension:

  1. Checks if Docker is available
  2. Checks if memory-service.client.url is already configured
  3. If not configured, starts a memory-service container
  4. Configures your application with:
    • memory-service.client.url - The base URL of the dev memory-service
    • memory-service.client.api-key - The API key, generated or from your config
    • quarkus.grpc.clients.responserecorder.* - The gRPC client host, port, and plaintext settings

The memory-service container is configured by default with:

MEMORY_SERVICE_DB_KIND=sqlite
MEMORY_SERVICE_DB_URL=file:/tmp/memory-service-dev/memory-service.db
MEMORY_SERVICE_DB_MIGRATE_AT_START=true
MEMORY_SERVICE_TLS_SELF_SIGNED=true
MEMORY_SERVICE_CACHE_KIND=local
MEMORY_SERVICE_VECTOR_KIND=sqlite
MEMORY_SERVICE_EMBEDDING_KIND=local
MEMORY_SERVICE_ATTACHMENTS_KIND=fs
MEMORY_SERVICE_ATTACHMENTS_FS_DIR=/tmp/memory-service-dev/attachments
MEMORY_SERVICE_TEMP_DIR=/tmp/memory-service-dev/tmp

If the app uses Keycloak Dev Services, the extension also passes the OIDC issuer and internal discovery URL to the memory-service container.

Configuration Properties

The following configuration properties control Dev Services behavior.

memory-service.client.url

Type: String
Default: Not set (triggers Dev Services)
Description: The base URL of the memory-service instance. If this is set, Dev Services will not start automatically. Use this to point to an existing memory-service instance.

# Disable Dev Services and use an existing instance
memory-service.client.url=http://localhost:8082

memory-service.client.api-key

Type: String
Default: Auto-generated random key if not set
Description: The API key used to authenticate agent requests to the memory-service. If not configured, Dev Services generates a random Base64-encoded key and exposes it to both the container and your application.

# Use a specific API key
memory-service.client.api-key=my-custom-api-key

memory-service.devservices.port

Type: int Default: Random Docker host port Description: Optional fixed host port for the memory-service container. This is useful when you want to call the dev memory-service directly with curl or from browser code.

# Make the dev memory-service available at http://localhost:8082
memory-service.devservices.port=8082

When this property is not set, the Quarkus app still receives the correct dynamic port through generated config.

memory-service.devservices.env.*

Type: String Default: Not set Description: Extra environment variables passed through to the memory-service container. Use this for roles, CORS, feature flags, or to override the default local storage settings.

memory-service.devservices.env.MEMORY_SERVICE_ROLES_ADMIN_OIDC_ROLE=admin
memory-service.devservices.env.MEMORY_SERVICE_CORS_ENABLED=true
memory-service.devservices.env.MEMORY_SERVICE_CORS_ORIGINS=http://localhost:3000

quarkus.devservices.enabled

Type: boolean
Default: true
Description: Global Quarkus Dev Services toggle. Set to false to disable all Dev Services, including the memory-service container.

# Disable all Dev Services
quarkus.devservices.enabled=false

Required Dependencies

For a basic agent app, add the Memory Service extension:

<dependency>
<groupId>io.github.chirino.memory-service</groupId>
<artifactId>memory-service-extension</artifactId>
<version>999-SNAPSHOT</version>
</dependency>

If your app authenticates users with OIDC, add Quarkus OIDC so Keycloak Dev Services can start and the memory-service container can validate the same tokens:

<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-oidc</artifactId>
</dependency>

You do not need quarkus-jdbc-postgresql, quarkus-mongodb-client, quarkus-redis-client, or quarkus-infinispan-client just to back the memory-service Dev Service.

Example

<dependencies>
<dependency>
  <groupId>io.github.chirino.memory-service</groupId>
  <artifactId>memory-service-extension</artifactId>
  <version>999-SNAPSHOT</version>
</dependency>

<dependency>
  <groupId>io.quarkus</groupId>
  <artifactId>quarkus-oidc</artifactId>
</dependency>
</dependencies>

And the corresponding application.properties:

memory-service.client.api-key=agent-api-key-1
memory-service.devservices.port=8082
memory-service.devservices.env.MEMORY_SERVICE_API_KEYS_AGENT=agent-api-key-1
memory-service.devservices.env.MEMORY_SERVICE_ROLES_ADMIN_OIDC_ROLE=admin

quarkus.oidc.client-id=memory-service-client
quarkus.oidc.credentials.secret=change-me