Memories declares project-scoped memory resources that agents and tasks can reference
by ID. These are indexed into the ResourceStore under the current project and can be
used across workflows for conversation and state sharing.
Runtime specifies the JavaScript/TypeScript execution environment for custom tools.
NOTE: Runtime configuration has been moved to global config (pkg/config.RuntimeConfig)
This field is kept for backwards compatibility and project-specific overrides.
Tools defines shared tool definitions available to all workflows and agents
within this project. These tools are inherited unless explicitly overridden.
Inheritance Rules:
Agent tools completely override inheritance when present
Workflow tools override project tools by ID
Tool ID collisions resolved by precedence: Agent > Workflow > Project
Location & autoload:
Place reusable tool configuration files under the tools/ directory (e.g., tools/*.yaml)
If autoload is enabled, files in tools/ will be discovered and validated automatically
Example:
tools: - id: code-analyzer description: Analyzes code quality and patterns timeout: 30s - id: data-processor description: Processes and transforms data
version
string
Version specifies the semantic version of this project configuration.
Config represents the cache-specific configuration This combines Redis connection settings with cache behavior settings
compression_enabled
boolean
CompressionEnabled activates data compression for cached items.
Reduces memory usage and network bandwidth at the cost of CPU.
Uses gzip compression for items above CompressionThreshold.
Default: true
compression_threshold
integer
CompressionThreshold sets the minimum size for compression.
Items smaller than this are stored uncompressed to avoid
CPU overhead for minimal space savings.
Default: 1024 (1KB)
db
integer
DB selects the Redis database number.
Default: 0
dial_timeout
integer
DialTimeout sets timeout for establishing new connections.
Default: 5s
enabled
boolean
Enabled determines if caching is active.
When disabled, all cache operations become no-ops.
Useful for debugging or when Redis is unavailable.
Default: true
eviction_policy
string
EvictionPolicy controls how items are removed when cache is full.
Options:
"lru": Least Recently Used (default)
"lfu": Least Frequently Used
"ttl": Time-based expiration only
Default: "lru"
host
string
Host specifies the Redis server hostname or IP address.
Default: "localhost"
key_scan_count
integer
KeyScanCount controls the COUNT hint used by Redis SCAN for key iteration.
Larger values reduce round-trips but may increase per-iteration latency.
Set to a positive integer; defaults to 100.
max_idle_conns
integer
MaxIdleConns sets the maximum number of idle connections.
Default: 0
max_item_size
integer
MaxItemSize limits the maximum size of a single cached item.
Prevents large objects from consuming excessive memory.
Items larger than this are not cached.
Default: 1048576 (1MB)
max_retries
integer
MaxRetries sets the maximum number of retries before giving up.
Default: 3
max_retry_backoff
integer
MaxRetryBackoff sets maximum backoff between retries.
Default: 512ms
min_idle_conns
integer
MinIdleConns sets the minimum number of idle connections.
Default: 0
min_retry_backoff
integer
MinRetryBackoff sets minimum backoff between retries.
Default: 8ms
notification_buffer_size
integer
NotificationBufferSize sets buffer size for pub/sub notifications.
Default: 100
password
string
Password authenticates with Redis.
Security: Use environment variables in production.
ping_timeout
integer
PingTimeout sets timeout for ping command.
Default: 1s
pool_size
integer
PoolSize sets the maximum number of socket connections.
Default: 10 per CPU
pool_timeout
integer
PoolTimeout sets timeout for getting connection from pool.
Default: ReadTimeout + 1s
port
string
Port specifies the Redis server port as a string.
Format: String representation of port number (1-65535)
YAML: Both "6379" (quoted) and 6379 (numeric) are accepted
Breaking Change: Changed from int to string in v2.0.0
Default: "6379"
prefix
string
Prefix namespaces cache keys in Redis.
Prevents key collisions when sharing Redis with other applications.
Format: "<app>:<environment>:cache:"
Default: "compozy:cache:"
read_timeout
integer
ReadTimeout sets timeout for socket reads.
Default: 3s
stats_interval
integer
StatsInterval controls how often cache statistics are logged.
Set to 0 to disable statistics logging.
Useful for monitoring cache hit rates and performance.
Default: 5m
tls_enabled
boolean
TLSEnabled enables TLS encryption.
Default: false
ttl
integer
TTL sets the default time-to-live for cached items.
Balances data freshness with cache efficiency.
Can be overridden per operation.
Default: 24h
url
string
URL provides a complete Redis connection string.
Format: redis://[user:password@]host:port/db
Takes precedence over individual connection parameters.
Config represents the autoload configuration for automatically discovering and loading resources.
enabled
boolean
Enabled determines whether autoload functionality is active.
When true, Compozy will automatically discover and load resources
matching the patterns specified in include. When false, all resources
must be explicitly defined in workflow configurations.
Exclude specifies patterns for files to ignore during discovery.
Common exclusion patterns:
"**/*-test.yaml" - Test fixtures
"**/*-draft.yaml" - Work in progress
"**/archive/**" - Archived resources
"**/.backup/**" - Backup directories
include
array
Include specifies glob patterns for discovering resources.
Common patterns:
"agents/*.yaml" - Direct children only
"agents/**/*.yaml" - All nested files
"tools/*-tool.yaml" - Files ending with "-tool"
"memory/*/config.yaml" - Config files in subdirectories
Required when: enabled is true
strict
boolean
Strict controls error handling when resources cannot be loaded.
When true (default), any failure to load a discovered resource
will cause the workflow to fail immediately. When false, load
errors are logged but workflow execution continues.
Use cases for non-strict mode:
Development environments with partial resources
Graceful degradation in production
Migration periods when refactoring resources
Default: true (fail on any load error)
watch_enabled
boolean
WatchEnabled activates file system monitoring for hot reloading.
When true, Compozy monitors included directories for changes
and automatically reloads modified resources without restarting.
This is particularly useful during development.
Note: Watch mode may impact performance in directories with
many files. Use specific include patterns to limit scope.
