Appendix B: Configuration Reference #

This appendix provides a complete reference for the neam.toml configuration file. The neam.toml file lives in the root of your Neam project directory and configures the compiler, runtime, LLM gateway, telemetry, deployment targets, and secrets management.

All configuration sections are optional. A project with no neam.toml file uses default values for everything. Configuration is read at compile time by neamc and at runtime by the VM. Changes to neam.toml require recompilation for deployment targets but take effect immediately for runtime settings when using neam-cli with hot reload.

B.1 [project] #

Project metadata. Used by the compiler, package manager, and deployment generators.

[project]
name = "my-agent-system"
version = "1.0.0"
entry = "src/main.neam"
description = "A multi-agent customer service platform"
license = "MIT"
authors = ["Alice Smith <alice@example.com>"]
repository = "https://github.com/example/my-agent-system"

B.2 [state] #

Configures the state backend for agent memory, learning data, prompt evolution history, and distributed locks. The state backend persists all agent cognitive data and conversation history.

[state]
backend = "postgres"
connection-string = "postgresql://user:pass@host:5432/neam_db"
ttl = "7d"
prefix = "myapp"

Backend-Specific Connection Strings #

SQLite:

connection-string = "./data/memory.db"
# Or absolute path:
connection-string = "/var/lib/neam/memory.db"

PostgreSQL:

connection-string = "postgresql://user:pass@host:5432/dbname?sslmode=require"
# With environment variable:
connection-string = "${DATABASE_URL}"

Redis:

connection-string = "redis://user:pass@host:6379/0"
# Redis Sentinel:
connection-string = "redis-sentinel://host1:26379,host2:26379/mymaster/0"

DynamoDB:

connection-string = "dynamodb://us-east-1/neam-state-table"
# Uses AWS credentials from environment (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
# or IAM role when running on AWS.

CosmosDB:

connection-string = "${COSMOS_CONNECTION_STRING}"
# Format: AccountEndpoint=https://account.documents.azure.com:443/;AccountKey=...;

Firestore:

connection-string = "firestore://my-project-id/neam-state"
# Uses Application Default Credentials (ADC) for authentication.
# Collection name is derived from the path (neam-state).
# Each data type (memory, learning, evolution) uses a separate sub-collection.

B.3 [llm] #

Configures the LLM gateway: default provider, rate limiting, circuit breaking, response caching, and cost tracking.

[llm]
default-provider = "openai"
default-model = "gpt-4o"

[llm.rate-limits.*] #

Per-provider rate limiting using a token bucket algorithm.

[llm.rate-limits.openai]
requests-per-minute = 500

[llm.rate-limits.anthropic]
requests-per-minute = 200

[llm.rate-limits.gemini]
requests-per-minute = 300

[llm.rate-limits.ollama]
requests-per-minute = 0  # 0 = unlimited (local)

[llm.circuit-breaker] #

Circuit breaker configuration for LLM provider calls. Prevents cascading failures when a provider is experiencing issues.

[llm.circuit-breaker]
failure-threshold = 5
reset-timeout = "30s"
half-open-max = 2

Circuit breaker states: - Closed: Normal operation. All requests pass through. - Open: After failure-threshold consecutive failures. All requests immediately fail with a circuit-open error. - Half-Open: After reset-timeout elapses. Up to half-open-max requests are allowed through. If they succeed, the circuit closes. If any fail, the circuit re-opens.

[llm.cache] #

Response caching for deterministic LLM calls. Only caches responses when temperature == 0.0.

[llm.cache]
enabled = true
max-entries = 10000
ttl = "1h"

Cache key: SHA-256 hash of provider + model + serialized_messages. Only exact matches are served from cache.

[llm.cost] #

Daily cost tracking and budget alerts.

[llm.cost]
daily-budget-usd = 100.0

[llm.fallback] #

Provider fallback chains. When the primary provider fails and the circuit breaker opens, the gateway automatically routes requests to the next provider in the chain.

[llm.fallback]
chain = ["openai", "anthropic", "gemini"]

When a fallback is triggered, the gateway maps the original model to an equivalent model on the fallback provider (e.g., gpt-4o maps to claude-sonnet-4-20250514 on Anthropic). You can override these mappings:

[llm.fallback.model-map]
"gpt-4o" = { anthropic = "claude-sonnet-4-20250514", gemini = "gemini-2.0-flash" }
"gpt-4o-mini" = { anthropic = "claude-haiku-4-20250414", gemini = "gemini-2.0-flash-lite" }

[llm.retry] #

Retry configuration for failed LLM requests. Retries happen before circuit breaker evaluation and before fallback.

[llm.retry]
max-attempts = 3
initial-delay = "500ms"
max-delay = "10s"
multiplier = 2.0
retryable-status-codes = [429, 500, 502, 503]

[llm.logging] #

Controls LLM request and response logging for debugging and audit purposes.

[llm.logging]
log-requests = false
log-responses = false
log-level = "info"
redact-keys = true

B.4 [telemetry] #

OpenTelemetry export configuration. When enabled, the VM exports traces and metrics to an OTLP-compatible collector.

[telemetry]
enabled = true
endpoint = "http://otel-collector.monitoring:4318"
service-name = "my-agent-system"
sampling-rate = 0.1

Exported Spans #

B.5 [secrets] #

Configures how the runtime resolves secret values (API keys, database passwords).

[secrets]
provider = "env"

Provider-Specific Configuration #

Environment Variables (default):

[secrets]
provider = "env"
# Reads from environment variables. No additional configuration needed.
# Agent api_key_env fields reference env var names directly.

AWS Secrets Manager:

[secrets]
provider = "aws-secrets-manager"

[secrets.aws]
region = "us-east-1"
secret-name = "neam/production"
# Reads keys from the specified secret in AWS Secrets Manager.
# Each key in the JSON secret maps to an environment variable name.

GCP Secret Manager:

[secrets]
provider = "gcp-secret-manager"

[secrets.gcp]
project = "my-project-id"
# Reads from GCP Secret Manager. Secret names map to env var names.

Azure Key Vault:

[secrets]
provider = "azure-key-vault"

[secrets.azure]
vault-url = "https://my-vault.vault.azure.net/"
# Reads from Azure Key Vault. Secret names map to env var names.

File:

[secrets]
provider = "file"

[secrets.file]
path = "./.env"
# Reads from a dotenv-format file. One KEY=VALUE per line.

B.6 [deploy.aws] #

AWS deployment configuration shared across Lambda and ECS targets.

[deploy.aws]
region = "us-east-1"
account-id = "123456789012"

[deploy.aws.lambda] #

AWS Lambda deployment target. Generates a SAM template.

[deploy.aws.lambda]
function-name = "my-agent-function"
memory = 512
timeout = 30
runtime = "provided.al2023"

[deploy.aws.ecs] #

AWS ECS Fargate deployment target.

[deploy.aws.ecs]
cluster = "my-cluster"
service = "my-service"
task-family = "my-task"
cpu = "512"
memory = "1024"
desired-count = 2

B.7 [deploy.gcp] #

GCP deployment configuration.

[deploy.gcp]
project = "my-project-id"
region = "us-central1"

[deploy.gcp.cloud-run] #

GCP Cloud Run deployment target.

[deploy.gcp.cloud-run]
service = "my-agent-service"
max-instances = 10
memory = "512Mi"
cpu = "1"

B.8 [deploy.azure] #

Azure deployment configuration shared across deployment targets.

[deploy.azure]
subscription = "12345678-abcd-efgh-ijkl-123456789012"
resource-group = "my-resource-group"
location = "eastus"

[deploy.azure.container-apps] #

Azure Container Apps deployment target.

[deploy.azure.container-apps]
name = "my-agent-app"
environment = "my-container-env"
min-replicas = 1
max-replicas = 5

[deploy.azure.aks] #

Azure Kubernetes Service deployment target.

[deploy.azure.aks]
cluster = "my-aks-cluster"
namespace = "production"

B.9 [deploy.kubernetes.scaling] #

Horizontal Pod Autoscaler (HPA) configuration for Kubernetes deployments. Applies to any Kubernetes-based target (vanilla Kubernetes, AKS, EKS, GKE).

[deploy.kubernetes.scaling]
min-replicas = 2
max-replicas = 10
target-cpu-pct = 70

B.10 [deploy.kubernetes.persistence] #

Persistent Volume Claim (PVC) configuration for Kubernetes deployments. Required when using SQLite as the state backend in Kubernetes (not recommended for production -- use PostgreSQL or Redis instead).

[deploy.kubernetes.persistence]
enabled = true
storage-class = "gp3"
size = "10Gi"

B.11 [deploy.kubernetes.network] #

Network policy and ingress configuration for Kubernetes deployments.

[deploy.kubernetes.network]
ingress-enabled = true
allowed-namespaces = ["frontend", "api-gateway"]

B.12 [deploy.kubernetes.disruption] #

Pod Disruption Budget (PDB) configuration for Kubernetes deployments. Ensures a minimum number of pods remain available during node drains and cluster upgrades.

[deploy.kubernetes.disruption]
min-available = 1

B.13 [deploy.docker] #

Docker image configuration used by all container-based deployment targets.

[deploy.docker]
registry = "ghcr.io/myorg"
image = "my-agent-system"
tag-format = "v{version}-{git-sha}"

B.14 [neamclaw] #

Configures NeamClaw agent defaults for claw agents, forge agents, channels, and semantic memory. All keys are optional. Per-agent declarations override these project-wide defaults.

[neamclaw.claw] #

Default settings for claw agents (persistent conversational agents).

[neamclaw.claw]
max-history-turns = 200
idle-reset = "24h"
daily-reset = "04:00"
compaction-threshold = 0.8
compaction-ratio = 0.67

[neamclaw.forge] #

Default settings for forge agents (iterative build agents).

[neamclaw.forge]
max-iterations = 20
max-cost-usd = 5.0
max-tokens = 500000
checkpoint = "git"
workspace-dir = "./workspace"

[neamclaw.channels] #

Default channel configuration for claw agents.

[neamclaw.channels]
default-adapter = "cli"
http-port = 8090
max-message-size = 4096
dm-policy = "allow_all"
group-policy = "read_only"

[neamclaw.memory] #

Default semantic memory configuration for workspace indexing and search.

[neamclaw.memory]
backend = "sqlite"
search = "hybrid"
vector-weight = 0.7
keyword-weight = 0.3
chunk-size = 512
reindex-debounce = "5s"

B.15 Complete Example #

Here is a complete neam.toml file demonstrating all sections:

[project]
name = "shopco-platform"
version = "2.1.0"
entry = "src/main.neam"
description = "ShopCo AI-powered customer service platform"
license = "MIT"
authors = ["Platform Team <platform@shopco.com>"]

[state]
backend = "postgres"
connection-string = "${DATABASE_URL}"
ttl = "7d"
prefix = "shopco"

[llm]
default-provider = "openai"
default-model = "gpt-4o"

[llm.rate-limits.openai]
requests-per-minute = 500

[llm.rate-limits.anthropic]
requests-per-minute = 200

[llm.circuit-breaker]
failure-threshold = 5
reset-timeout = "30s"
half-open-max = 2

[llm.cache]
enabled = true
max-entries = 10000
ttl = "1h"

[llm.fallback]
chain = ["openai", "anthropic"]

[llm.retry]
max-attempts = 3
initial-delay = "500ms"
max-delay = "10s"
multiplier = 2.0

[llm.cost]
daily-budget-usd = 100.0

[telemetry]
enabled = true
endpoint = "http://otel-collector.monitoring:4318"
service-name = "shopco-platform"
sampling-rate = 0.1

[secrets]
provider = "aws-secrets-manager"

[secrets.aws]
region = "us-east-1"
secret-name = "shopco/production"

[deploy.docker]
registry = "123456789012.dkr.ecr.us-east-1.amazonaws.com"
image = "shopco-platform"
tag-format = "v{version}-{git-sha}"

[deploy.aws]
region = "us-east-1"
account-id = "123456789012"

[deploy.aws.ecs]
cluster = "shopco-prod"
service = "customer-service"
task-family = "shopco-agents"
cpu = "1024"
memory = "2048"
desired-count = 3

[deploy.gcp]
project = "shopco-backup"
region = "us-central1"

[deploy.gcp.cloud-run]
service = "shopco-backup"
max-instances = 2
memory = "1Gi"
cpu = "1"

[deploy.kubernetes.scaling]
min-replicas = 3
max-replicas = 15
target-cpu-pct = 70

[deploy.kubernetes.persistence]
enabled = false

[deploy.kubernetes.network]
ingress-enabled = true
allowed-namespaces = ["frontend", "api-gateway", "monitoring"]

[deploy.kubernetes.disruption]
min-available = 2

[neamclaw.claw]
max-history-turns = 200
idle-reset = "24h"
compaction-threshold = 0.8

[neamclaw.forge]
max-iterations = 20
max-cost-usd = 10.0
checkpoint = "git"
workspace-dir = "./workspace"

[neamclaw.channels]
default-adapter = "http"
http-port = 8090

[neamclaw.memory]
backend = "sqlite"
search = "hybrid"

B.16 Environment Variable Interpolation #

Any string value in neam.toml can reference environment variables using the ${VAR_NAME} syntax:

[state]
connection-string = "${DATABASE_URL}"

[deploy.aws]
account-id = "${AWS_ACCOUNT_ID}"

Environment variables are resolved at runtime. If a referenced variable is not set, the VM raises an error at startup with a clear message indicating which variable is missing and which configuration field references it.

You can also provide default values using the ${VAR_NAME:-default} syntax:

[state]
backend = "${NEAM_STATE_BACKEND:-sqlite}"

[telemetry]
sampling-rate = "${NEAM_SAMPLING_RATE:-1.0}"

B.17 [dependencies] and [dev-dependencies] #

Package dependencies managed by neam-pkg. Dependencies are downloaded from the Neam package registry and linked at compile time.

[dependencies]
rag-utilities = "1.2.0"
pii-guardrails = "0.8.0"
citation-tools = "1.0.0"

[dev-dependencies]
test-fixtures = "0.5.0"
mock-llm = "1.0.0"

Dependencies support three formats:

[dependencies]
# Version from registry
analytics = "1.0.0"

# Git repository
ai-tools = { git = "https://github.com/neam/ai-tools", branch = "main" }

# Local path (for development)
my-utils = { path = "../my-utils" }

# Version with optional features
ml-lib = { version = "2.0.0", features = ["gpu", "advanced"] }

B.18 [test] #

Test runner configuration for neamc test.

[test]
timeout = 120
parallel = true
coverage = true
coverage-threshold = 80
include = ["tests/**/*.neam"]
exclude = ["tests/integration/**"]

B.19 [profile.*] #

Build profiles control optimization and debug settings. Three built-in profiles are available: dev, release, and bench.

[profile.dev]
optimization = 0
debug = true
source-maps = true

[profile.release]
optimization = 2
debug = false
source-maps = false
strip = true

[profile.bench]
optimization = 2
debug = false
source-maps = false

The profile is selected with neamc build --release or neamc build --profile bench. The dev profile is used by default.

B.20 [scripts] #

Named scripts that can be executed with neamc run-script.

[scripts]
seed = "neam seed_data.neamb"
migrate = "neam migrate.neamb"
eval = "neam-gym --agent main.neam --dataset eval/tests.jsonl --runs 3"
lint = "neamc lint src/"

Scripts are executed in the project root directory. They can reference any installed CLI tool and accept additional arguments from the command line:

neamc run-script eval -- --verbose