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:
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.defaultis the prompt earlier releases used. - one of your own,
<name>.jinja2inEVOLVE_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=4withEVOLVE_TRAJECTORY_TAIL_STEPSof 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_callturns are one example. So 2 text turns plus 3function_callturns 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¶
Usage¶
First, enable auto-mode by setting the environment variable:
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.