Skip to content

Configuration

Evolve uses environment variables for configuration. You can set these in a .env file or export them directly.

LLM Configuration

Required for OpenAI models:

export OPENAI_API_KEY=sk-...

Custom LLM Configuration

Evolve uses LiteLLM and supports OpenAI-compatible proxy endpoints (including LiteLLM) via standard OpenAI environment variables:

# OpenAI-compatible endpoint configuration (works with LiteLLM)
export OPENAI_API_KEY="your-api-key"
export OPENAI_BASE_URL="https://your-litellm-proxy.com/v1"

# Evolve Model Configuration
export EVOLVE_GUIDELINES_MODEL="openai/gpt-4o-mini"
export EVOLVE_CONFLICT_RESOLUTION_MODEL="openai/gpt-4o-mini"
export EVOLVE_FACT_EXTRACTION_MODEL="openai/gpt-4o-mini"
export EVOLVE_MODEL_NAME="openai/gpt-4o-mini"
export EVOLVE_CUSTOM_LLM_PROVIDER="openai"

Model selection precedence: 1. Task-specific models: EVOLVE_GUIDELINES_MODEL, EVOLVE_CONFLICT_RESOLUTION_MODEL, EVOLVE_FACT_EXTRACTION_MODEL 2. Global Evolve fallback: EVOLVE_MODEL_NAME 3. Built-in default: gpt-4o

EVOLVE_TIPS_MODEL is still accepted as a deprecated fallback for one release cycle.

If EVOLVE_*_MODEL are unset, set EVOLVE_MODEL_NAME to control all Evolve LLM calls.

Environment Variables

All configuration variables are prefixed with EVOLVE_.

General Settings

Variable Description Default
EVOLVE_BACKEND Backend provider (milvus, filesystem, or postgres) milvus
EVOLVE_NAMESPACE_ID Namespace ID for isolation evolve
EVOLVE_GUIDELINES_MODE Guideline generation pipeline: standard, consistency, or all — see Enabling Guidelines standard
EVOLVE_CONSISTENCY_METHOD Consistency mode only: fast (LLM self-judged) or accurate (resampling based) — see Enabling Guidelines fast
EVOLVE_CONSISTENCY_RESAMPLE_MAX_WORKERS accurate method only: how many resampling calls run in parallel when a provider won't return several completions in one call — see Enabling Guidelines. Raise it to cut resampling wall-clock, lower it to 1 if the provider rate-limits you 4
EVOLVE_SEGMENTATION_ENABLED Segment trajectories into logical subtasks before generating guidelines. Governs all three generation paths (standard, and both consistency methods). Disabled by default — see Trajectory segmentation false
EVOLVE_TRAJECTORY_MAX_STEPS Most trajectory steps rendered into a generation prompt (standard and fast consistency; not accurate) — see Trajectory limits 50
EVOLVE_TRAJECTORY_MAX_STEP_CHARS Characters kept per step before truncation 2000
EVOLVE_GUIDELINES_PROMPT Name of the prompt the standard guideline generator uses — see Guideline prompt default
EVOLVE_GUIDELINES_PROMPTS_DIR A directory of your own prompts, <name>.jinja2, selectable by name alongside the shipped ones unset
EVOLVE_TRAJECTORY_TAIL_STEPS How much of the step budget is reserved for the end of a long run. 0 truncates head-only, as before — see Trajectory limits 0
EVOLVE_CONSOLIDATION_MODE How consolidation merges a cluster: none (skip), lossless (merge only equivalent advice) or lossy (merge more aggressively) — see Guideline consolidation lossless
EVOLVE_CLUSTERING_KEY What consolidation clusters on: task_description or guideline_text task_description
EVOLVE_CLUSTERING_THRESHOLD Cosine similarity at which two guidelines join a cluster 0.80
EVOLVE_CONSOLIDATION_MAX_CLUSTER_SIZE Split larger clusters into chunks of at most this many guidelines (at least 2). Unset means unbounded unset
EVOLVE_CONSOLIDATION_MAX_ROUNDS Re-cluster and merge up to this many times; stops early once a round merges nothing 1
EVOLVE_GUIDELINES_MODEL Model for guideline generation only EVOLVE_MODEL_NAME -> gpt-4o
EVOLVE_CONFLICT_RESOLUTION_MODEL Model for conflict resolution only EVOLVE_MODEL_NAME -> gpt-4o
EVOLVE_FACT_EXTRACTION_MODEL Model for fact extraction only EVOLVE_MODEL_NAME -> gpt-4o
EVOLVE_MODEL_NAME Global fallback model for all Evolve LLM calls gpt-4o
EVOLVE_CUSTOM_LLM_PROVIDER LiteLLM provider (use openai for OpenAI-compatible endpoints). Defaults to openai whenever OPENAI_API_KEY or OPENAI_BASE_URL is set, even if you never set this variable yourself — see the consistency guide for a case where that implicit default causes misrouting openai if OPENAI_API_KEY/OPENAI_BASE_URL is set, else None
EVOLVE_EMBEDDING_MODEL Embedding model sentence-transformers/all-MiniLM-L6-v2
EVOLVE_DASHBOARD evolve-mcp over stdio only: also serve the Web UI and REST API on 127.0.0.1:8000, which has no authentication. Read as a boolean like the other EVOLVE_ switches: false, 0, no, off, f or n turns it off. An unrecognised value also turns it off and logs a warning; an empty or whitespace-only value counts as unset, so it does not override .env. --dashboard / --no-dashboard on the command line take precedence true

Trajectory limits

A trajectory is rendered into the generation prompt as at most EVOLVE_TRAJECTORY_MAX_STEPS steps of at most EVOLVE_TRAJECTORY_MAX_STEP_CHARS characters each. Both were fixed at 50 and 2000 before; the defaults are unchanged.

These settings govern the standard path, trajectory segmentation, and the fast consistency method. The accurate consistency method does not use them: its prompt renderer keeps its own fixed window of the first 50 steps at 500 characters each, whatever these are set to.

Keeping the end of a long run. By default the window is head-only: a 200-step run is rendered as its first 50 steps, and the 150 that follow — including whatever the run finished with — are not in the prompt at all. A run's outcome is at its end, so a guideline mined from the head alone can state an approach that the run went on to abandon. EVOLVE_TRAJECTORY_TAIL_STEPS carves part of the budget out for the end:

# 40 steps from the start, 10 from the end, the middle replaced by a marker
EVOLVE_TRAJECTORY_MAX_STEPS=50
EVOLVE_TRAJECTORY_TAIL_STEPS=10

The tail comes out of EVOLVE_TRAJECTORY_MAX_STEPS, not on top of it, so the prompt never holds more than that many steps; the omitted middle is announced in the prompt as [... N intermediate step(s) omitted; M steps in the full run ...] rather than silently closed up. That marker takes one extra position, so an elided run renders as EVOLVE_TRAJECTORY_MAX_STEPS + 1 numbered entries. It must stay below EVOLVE_TRAJECTORY_MAX_STEPS — a tail that consumed the whole budget would leave no steps from the start of the run.

Leave it at 0 if you compare results against runs recorded earlier: it changes which steps reach the model, so guidelines mined before and after the change come from different views of the same trajectory. One interaction to know about: with elision in effect, the accurate consistency method skips segmentation on any trajectory long enough to be elided, because its step numbering and the segmenter's stop agreeing across the gap. Trajectories within the step budget are unaffected, as is the fast method.

Guideline prompt

EVOLVE_GUIDELINES_PROMPT names the prompt the standard generator renders. The consistency pipelines keep their own prompts. A name refers to either:

  • a prompt shipped with Evolve, altk_evolve/llm/guidelines/prompts/generation/<name>.jinja2. default is the prompt earlier releases used.
  • one of your own, <name>.jinja2 in EVOLVE_GUIDELINES_PROMPTS_DIR.

evolve prompts list shows the available names, and evolve prompts show <name> prints a template. The setting is always a name, never a path, and your prompts may not reuse a shipped name, so default means the same prompt in every deployment.

Shipped prompts:

Name Use it when
default Unless you have a reason not to. It is domain-agnostic: with an outcome, guidelines are grounded in the evaluation; without one, in what the trajectory shows
environment-grounded The agent works where the environment states its own requirements: pre-commit hooks, CI checks, linters, validators, error messages that say what to do. The default prompt, plus two instructions: turn each requirement such a message states into a step to take before the action it blocked ("Before committing, add an entry under ## Unreleased in CHANGES.md"), not into advice about recovering from the error; and keep the project's own file, command and format names in those guidelines rather than generalizing them away

environment-grounded changes nothing else in the default prompt, and a test keeps the two in step. On a coding-agent session whose first commit was rejected by a hook asking for a changelog entry and a version bump, the default prompt learned to "complete the required metadata before retrying the commit"; environment-grounded learned to "add the required CHANGES.md entry and bump clients/python/VERSION; do this before the initial git commit attempt".

A processing profile can set it per profile, as guidelines_prompt in the evolve.guidelines processor's config, so one namespace can try a prompt while the rest keep the default:

evolve processing-profiles get cortex > current.json
# apply takes a definition, not get's output, and replaces the whole definition, so this keeps
# the profile's other settings and changes only the prompt. Only evolve.guidelines takes
# guidelines_prompt, so other processors keep their config as it is.
jq '{processors: [.manifest.processors[] | {id, plugin, config: (
      if .plugin == "evolve.guidelines" then .config + {guidelines_prompt: "mine"} else .config end)}]}' \
  current.json > profile.json
evolve processing-profiles apply cortex --file profile.json --expected-revision "$(jq .revision current.json)"

Profiles can be written remotely (MCP, REST), so they can only name prompts already in place, and EVOLVE_GUIDELINES_PROMPTS_DIR itself is set only by the environment. An unknown name is rejected when the profile is published, if the profile uses the standard generator (guidelines_mode standard or all); a bad EVOLVE_GUIDELINES_PROMPT is reported by name. evolve prompts list checks the selected prompt too, and exits 1 if it can't be used. The profile records the name, not the template, so editing a prompt file changes what later runs of that profile render. Templates are read once per process: restart Evolve after editing one.

Writing a prompt

Start from a copy of the default: mkdir -p my-prompts && evolve prompts show default > my-prompts/mine.jinja2. A template is Jinja2 and receives these variables:

Variable Contents
task_instruction The task, or the subtask's description when the trajectory is segmented
trajectory_summary The agent's steps, rendered and truncated as set by Trajectory limits
num_steps How many steps trajectory_summary covers (a subtask's, when segmented)
supporting_context Earlier conversation to interpret the steps by; empty if none
rules_section The rules or policies the agent worked under, rendered as a section; empty if none
constrained_decoding_supported Whether the model is held to the response schema. When false, the prompt must spell out the JSON format
outcome The evaluation's verdict; outcome.success is a boolean. Set only when the trajectory has an outcome, like the four below
failed_checks The checks the evaluation failed, at most 10, each truncated to 500 characters
omitted_checks How many failed checks were left out of failed_checks
detail The evaluation's free-text detail, truncated to 2,500 characters
segmented Whether the steps are one subtask of a longer trajectory

A template that uses any other variable is rejected when it is selected, rather than rendering the variable as empty. A template must also be self-contained: one that includes, imports or extends another template (Jinja's include, import, from and extends tags) is rejected, as is one with a syntax error or a filter or test Jinja doesn't have, even in a branch that only some trajectories render. Templates are read as UTF-8. A name is used exactly as given; one with surrounding whitespace is rejected. The model's reply is parsed against the same guideline schema whichever prompt is used.

A leading Jinja comment is the description evolve prompts list shows. Write it as {#- ... -#}, so that it adds no blank line to the prompt.

Trajectory segmentation

EVOLVE_SEGMENTATION_ENABLED is disabled by default. With it enabled, a trajectory is split into subtasks and each subtask gets its own guideline-generation call.

A trajectory with fewer than five steps is still generated in one pass, but the paths count steps differently:

  • Standard and consistency-fast count the steps they render: each non-empty text turn and each function or tool call is one step. Under head+tail elision only real steps in the rendered window count; the omitted-steps marker is not a step. This changed after v1.7.1 for the consistency-fast path, which used to count the marker: an elided run under EVOLVE_TRAJECTORY_MAX_STEPS=4 with EVOLVE_TRAJECTORY_TAIL_STEPS of 1 or more renders four real steps plus the marker, and was segmented before but is now generated in one pass. Any other window gives the same result as before.
  • Consistency-accurate counts the steps it can score, which are the steps of its trajectory IR. Turns it cannot resample are not steps there. Agents-SDK function_call turns are one example. So 2 text turns plus 3 function_call turns are 5 steps on the standard and fast paths, which segment them, but 2 on the accurate path, which generates them in one pass.

On the standard and consistency-fast paths, subtasks that cover the same real steps share one call, a subtask covering only the marker is dropped, and a trajectory whose subtasks reduce to fewer than two distinct step ranges is generated in one pass. If exactly one distinct range remains, however many subtasks repeated it, that pass keeps the subtask's generalized description. Otherwise a one-pass task_description is the first user message, as with segmentation off; this includes a trajectory below five steps. The consistency-accurate path also generates a repeated range once, and always uses the first user message for its one pass.

"The first user message" is the first user message in context_messages, if there is one, or else the first in the trajectory. The standard and consistency-fast paths cut a message taken from context_messages to 2000 characters; every other case keeps it verbatim.

Why it defaults to off. A subtask boundary can fall between a failed attempt and the correction that followed it. The failing segment is then summarised on its own terms — its description asserts the wrong approach — and the generator writes confident guidelines from it, with no access to the correction in the neighbouring segment. Both segments' output is stored at equal support_count, so nothing marks one as the anti-lesson, and retrieval can rank the inverted rule above the correct one. In end-to-end measurement on a learning-episode trajectory, enabling segmentation produced directly contradictory ordering rules and cost roughly half of the achievable improvement on the affected cases; disabling it removed the contradiction at source.

What you give up by leaving it off. task_description becomes the raw first user message, verbatim, shared by every guideline from that trajectory. It is the default clustering key and the retrieval ranking key, so within a single trajectory it no longer separates subtasks, and it carries whatever user-specific values the original request contained into stored entity metadata. If your trajectories are single-purpose, this costs little; if one trajectory routinely spans unrelated subtasks, weigh enabling it.

Turning it on later (mixed corpora). Entities written while segmentation was off carry verbatim request text as task_description; entities written with it on carry generalized subtask descriptions, except for the verbatim one-pass cases above. Both are embedded in the same space, so a namespace written across a change of this setting holds two kinds of key. Nothing breaks and no migration is required — clustering and retrieval keep working — but similarity between the two kinds is lower than within either, so recurrence spanning the change may go undetected. To avoid the mix, use a fresh namespace when you change this setting.

Guideline consolidation

evolve entities consolidate <namespace> --no-dry-run (or EvolveClient.consolidate_guidelines) embeds each guideline's clustering key (its task description or its text; see below), joins pairs whose cosine similarity is at least EVOLVE_CLUSTERING_THRESHOLD, and asks the LLM to merge each cluster. Support is conserved: a merged guideline's support is the sum of its sources'. Clusters never mix memory scopes. Without --no-dry-run the command only lists the clusters it would merge.

What to cluster on. By default (EVOLVE_CLUSTERING_KEY=task_description) guidelines are grouped by the task they were learned on. That merges advice from similar tasks, but the same advice learned on dissimilar tasks never meets, and guidelines without a task description are left out. guideline_text groups by the guideline's own text instead. Guidelines share a lot of phrasing ("When ..., check ..."), so two unrelated guidelines can score higher than their tasks would; calibrate the threshold on your corpus (a dry run shows the clusters) rather than reusing the task-key value. The embedding model reads only the start of a long input (the default all-MiniLM-L6-v2 truncates at 256 tokens), so two long guidelines that share a preamble and differ only at the end can look identical.

A guideline merged from members learned on different tasks keeps no single task description, because keeping one would tie it to that task alone. It records every member task in source_tasks instead (carried through later merges), and with the default EVOLVE_RETRIEVAL_SIMILARITY_KEY=source_task retrieval scores it by the source task that best matches the current one, so it stays retrievable for each task it was learned on.

Large clusters. Clustering is transitive: if A is similar to B and B to C, all three join, even when A and C are not similar. On a large namespace, and especially with guideline_text, this can chain hundreds of guidelines into one merge call. EVOLVE_CONSOLIDATION_MAX_CLUSTER_SIZE splits such a cluster into chunks of nearest neighbours, each within the threshold of its first member. Duplicates that land in different chunks are left apart unless you allow more than one round: EVOLVE_CONSOLIDATION_MAX_ROUNDS re-clusters the namespace after each round, stops after a round that merges nothing, and does not send the same merge's outputs back to the model together. Each round re-embeds the whole namespace, which on CPU takes minutes for thousands of long guidelines.

evolve entities consolidate my-ns --cluster-key guideline_text --threshold 0.85 \
    --max-cluster-size 20 --max-rounds 3            # dry run: lists round-1 clusters
evolve entities consolidate my-ns --cluster-key guideline_text --threshold 0.85 \
    --max-cluster-size 20 --max-rounds 3 --no-dry-run

Originals that cannot be deleted. After writing a merged guideline, consolidation deletes its originals. If a delete is vetoed (for example by the legal_hold plugin) or fails, the original stays stored next to the merged guideline that already counts its support. Each merged guideline therefore records the originals it absorbed in metadata.merged_from: one {"id", "content_sha256"} entry per original, with the digest of the content the merge read. When a guideline is merged again, the new guideline keeps the entries of absorbed originals that are still stored. Later rounds and later consolidate runs leave a recorded original out of clustering, so its support is never counted twice, and the dry-run listing leaves it out too. Each run retries the delete once: if the hold has since been lifted, the original is deleted then, with no change to any support count. An original edited after it was merged is not deleted, because the merged guideline does not hold the edit; it stays out of clustering too, since its support is still counted. Delete it, or delete the merged guideline, which makes the original eligible to merge again. A record matches the original by ID, so it still holds after the merged guideline is published or unpublished. merged_from is managed by consolidation: the three caller-facing create front doors drop it — the MCP create_entity tool and the REST create route silently, evolve entities add with a warning — and patch_entity_metadata rejects it. Paths that do not gate it yet (process_trajectory and the Python client) leave caller-supplied merged_from in place. Redactors leave well-formed entries alone and treat any other value under the key as free text. Consolidation reads at most 10,000 guidelines and logs a warning when it hits that limit. Past it, a merged guideline can fall outside the read while its held original does not, and the original is then merged again.

Milvus Backend Settings

When EVOLVE_BACKEND=milvus:

Variable Description Default
EVOLVE_URI Milvus URI (file path for Lite) entities.milvus.db
EVOLVE_USER Milvus user (optional) ""
EVOLVE_PASSWORD Milvus password (optional) ""
EVOLVE_DB_NAME Milvus database name (optional) ""
EVOLVE_TOKEN Milvus token (optional) ""
EVOLVE_TIMEOUT Milvus timeout (optional) None

Filesystem Backend Settings

When EVOLVE_BACKEND=filesystem:

Variable Description Default
EVOLVE_DATA_DIR Directory to store JSON data files evolve_data

Postgres Backend Settings

When EVOLVE_BACKEND=postgres:

Variable Description Default
EVOLVE_PG_HOST PostgreSQL host localhost
EVOLVE_PG_PORT PostgreSQL port 5432
EVOLVE_PG_USER PostgreSQL user postgres
EVOLVE_PG_PASSWORD PostgreSQL password postgres
EVOLVE_PG_DBNAME PostgreSQL database name evolve
EVOLVE_PG_AUTO_CREATE_DB Automatically create EVOLVE_PG_DBNAME when missing false
EVOLVE_PG_BOOTSTRAP_DB Existing database to connect to for CREATE DATABASE bootstrap postgres
EVOLVE_PG_EMBEDDING_MODEL Embedding model used for pgvector-backed entities sentence-transformers/all-MiniLM-L6-v2

Storage Backends

Evolve supports three storage backends:

Backend Description Search Best For
Milvus (default) Vector database with embeddings Semantic similarity Production
Filesystem JSON files, no embeddings Text substring match Development/testing
Postgres PostgreSQL with pgvector embeddings Semantic similarity Teams already running PostgreSQL

Switching Backends

# Use Milvus backend (default)
export EVOLVE_BACKEND=milvus

# Use Filesystem backend
export EVOLVE_BACKEND=filesystem

# Use Postgres backend
export EVOLVE_BACKEND=postgres

Filesystem Backend Details

The filesystem backend stores all data in JSON files - one file per namespace. This is ideal for: - Local development and testing - Debugging (you can inspect/edit the JSON files directly) - Environments where you don't want to run Milvus - Quick prototyping without embedding model overhead

JSON File Structure:

Each namespace is stored as <data_dir>/<namespace_id>.json:

{
  "id": "my_guidelines",
  "created_at": "2026-01-13T21:29:51.986882+00:00",
  "entities": [
    {
      "id": "1",
      "type": "guideline",
      "content": "Always write tests before code",
      "created_at": "2026-01-13T21:30:00.023283+00:00",
      "metadata": null
    }
  ],
  "next_id": 2
}

Low-Code Tracing (Phoenix Integration)

Evolve provides easy integration with Phoenix for tracing LLM calls.

Installation

pip install evolve[tracing]

Usage

First, enable auto-mode by setting the environment variable:

export EVOLVE_AUTO_ENABLED=true

Then, add one import at the top of your agent to trigger the patching:

try:
    import altk_evolve.auto # noqa: F401
except ImportError:
    pass

# Your existing code unchanged...

Tracing Environment Variables

Variable Description Default
EVOLVE_AUTO_ENABLED Enable auto-patching on import false
EVOLVE_TRACING_PROJECT Phoenix project name evolve-agent
EVOLVE_TRACING_ENDPOINT Phoenix collector endpoint http://localhost:6006/v1/traces

Note: Auto-patching skips if existing tracing is detected. Use enable_tracing(force=True) to override.

Runtime processing profiles

Processing profiles select built-in or installed trajectory processors with validated, versioned configuration. Profiles use the existing configured database: PostgreSQL for the PostgreSQL backend, or SQLite for filesystem and Milvus. Milvus already uses SQLite for namespace metadata; filesystem namespaces remain in JSON and profile SQLite defaults to entities.sqlite.db inside EVOLVE_DATA_DIR. Explicit EVOLVE_SQLITE_PATH / EVOLVE_SQLITE_URI overrides are respected. Milvus profiles use its configured sqlite_uri (or EVOLVE_SQLITE_PATH override). No separate profile database configuration is required; applications can still inject a custom repository. See processing profiles for Python, REST, MCP, CLI, and plugin-discovery examples.