altk-evolve

Evolve: On‑the‑job learning for AI agents

Evolve helps AI agents learn from experience. It turns past trajectories into reusable guidelines that help agents complete future tasks, without changing model weights.

The Lite version is designed to effortlessly slot into existing agent assistants like Claude Code and Codex. The full service uses a combination of an MCP server for tool integration, vector storage for memory, and LLM-based conflict resolution to refine its knowledge base. It also supports guideline consolidation, clustering related guidelines and merging equivalent advice while preserving support counts and source provenance.

On AppWorld's held-out test split, a GPT-4.1 ReAct agent with Evolve increased scenario completion from 50.0% to 64.3% (+14.3 percentage points). See the evaluation protocol and results.

Research highlights

Finding	Reported result
More repeatable success	AppWorld tasks passing all five attempts increased from 53% to 66%, using sibling-task guidelines with GPT-4.1.
Efficient learning	With gpt-oss-120b, AppWorld task completion increased from 39.9% to 56.0% using curated retrieval.
Lifts frontier and non-frontier models	On τ²-bench, Evolve lifts both frontier and non-frontier models (held-out Pass^4: GPT-5.5 55% → 70%; GPT-4.1 57.5% → 67.5%).

These are separate benchmark experiments with different metrics, models, and memory configurations. Follow each link for its evaluation protocol and sources.

Important ⭐ Star the repo: it helps others discover it.

Latest from Evolve

Research, releases, and practical findings from the Evolve team.

• 2026-10-20 · Article — ALTK-Evolve: How learned memory tops the τ²-bench leaderboard on customer service tasks without a frontier model Learned guidelines raise GPT-4.1's held-out retail Pass^4 from 57.5% to 67.5%; the article also compares pending custom submissions with an October 12 leaderboard snapshot.
• 2026-09-25 · Paper — Memory as Middleware for Self-Improving AI Agents The case for agent memory as a pluggable middleware layer, with Evolve as the reference implementation (to appear at Middleware 2026).
• 2026-09-15 · Article — Your Agent Aced the Task. Will It Do It Again? Diagnosing where an agent's decisions wobble and stabilizing them so success repeats.
• 2026-09-08 · Paper — Closing the Consistency Gap: Self-Evolving Agents That Learn to Stay on Course Turning unstable trajectory steps into episodic memory to keep agents consistent across repeated runs.
• 2026-08-18 · Article — How Much Memory Does Your Agent Actually Need? Why agent memory should be calibrated to the model instead of simply increased.
• 2026-08-11 · Article — Thinking of ACE? We Can Do It with Fewer Tokens Comparing Evolve's targeted guideline retrieval with ACE's playbook approach and token usage.
• 2026-04-08 · Article — ALTK‑Evolve: On‑the‑Job Learning for AI Agents An introduction to learning reusable guidance from agent trajectories.
• 2026-04-07 · Announcement — IBM introduces ALTK Evolve Evolve is opened to builders creating agents that learn from experience.
• 2026-03-11 · Paper — Trajectory-Informed Memory Generation for Self-Improving Agent Systems The research framework and evaluation underlying Evolve.

Quick Start (Lite)

IBM Bob →

Claude Code →

Codex →

Hermes →

Quick Start (Evolve MCP Server)

Installation

Prerequisites:

• Python 3.12 or higher
• uv (recommended) or pip

From Source

# Clone the repository and install dependencies
git clone https://github.com/agenttoolkit/altk-evolve.git
cd altk-evolve
uv venv --python=3.12 && source .venv/bin/activate
uv sync --package altk-evolve
# Build the UI
cd frontend/ui
npm ci && npm run build
cd ../..

From PyPI

pip install altk-evolve

Choose your installation:

• altk-evolve bundles altk-evolve-core[server,cli,fastembed,tracing] at the same version.
• altk-evolve-core contains the Python implementation without server/CLI dependencies, an embedding runtime, or a Phoenix server. Libraries should depend on core and select the extras they need.
• Add [server] for the HTTP/MCP server and its telemetry exporters, or [cli] for the command-line interface. [telemetry] provides the SDK and OTLP exporter independently; both [server] and [tracing] include it. Core retains the OpenTelemetry API so host applications can supply their own telemetry providers.
• All extras belong to core. Existing altk-evolve[pgvector], [pii-semantic], and other extras forward to core while retaining the convenience defaults.
• Install altk-evolve-core[phoenix] (or altk-evolve[phoenix]) only to run the local Phoenix server. Remote tracing uses the separate arize-phoenix-otel package.

Both packages use the same altk_evolve imports and evolve / evolve-mcp commands; only core owns those files. Core-only filesystem storage works without an embedding runtime. Features that embed text require [fastembed] or [sentence-transformers].

Embedding migration: FastEmbed is now the default provider. To retain the previous runtime, install altk-evolve-core[sentence-transformers] and set EVOLVE_EMBEDDING_PROVIDER=sentence_transformers. Validate retrieval quality before switching an existing vector store to another runtime; changing models requires re-embedding stored vectors.

Source development and releases: The root project is core. Use uv sync --package altk-evolve for the convenience bundle, or select root extras explicitly. After changing the version or extras, run uv run --no-project python scripts/sync_convenience.py and uv lock. uv build --all-packages builds both distributions. Releases publish core first, then the exactly matching convenience package through the same trusted publisher.

Optional Backend Dependencies:

The default filesystem backend uses simple text matching and requires no additional dependencies. For semantic vector similarity search, install one of these backends:

For PostgreSQL with pgvector support (recommended for production):

uv sync --extra pgvector

For Milvus support (optimized for large-scale vector search):

uv sync --extra milvus

See the Backend Configuration Guide for detailed comparison and setup instructions.

Configuration

For direct OpenAI usage:

export OPENAI_API_KEY=sk-...

For LiteLLM proxy usage and model selection (including global fallback via EVOLVE_MODEL_NAME), see the configuration guide.

Running Services

Start the Web UI and MCP server

uv run evolve-mcp

The Web UI can be accessed from: http://127.0.0.1:8000/ui/

Over stdio, evolve-mcp serves the Web UI and REST API on 127.0.0.1:8000 alongside MCP and logs the address at startup. The API has no authentication, so any local process can read and change memories through it. Pass --no-dashboard or set EVOLVE_DASHBOARD=false to run MCP alone.

Starting the Web UI and MCP Server

If you only want to access the Web UI and API (without the MCP server stdio blocking the terminal), you can run the FastAPI application directly using uvicorn:

uv run uvicorn altk_evolve.frontend.mcp.mcp_server:app --host 127.0.0.1 --port 8000

Then navigate to http://127.0.0.1:8000/ui/.

Starting only the MCP Server

If you're attaching Evolve to an MCP client that requires a direct command (like Claude Desktop):

uv run evolve-mcp --no-dashboard

Or for SSE transport:

uv run evolve-mcp --transport sse --port 8201

Verify it's running:

npx @modelcontextprotocol/inspector@latest http://127.0.0.1:8201/sse --cli --method tools/list

Available tools:

• get_entities(task: str, entity_type: str = "guideline", include_public: bool = False): Get relevant entities for a specific task. Set include_public=True to merge in public entities from all other namespaces; those results are annotated with [public: {owner_id}].
• get_guidelines(task: str): Get relevant guidelines for a specific task (backward compatibility alias for get_entities).
• get_guidelines_with_attribution(task: str): Return formatted guidelines with the entity IDs used to build the prompt.
• get_relevant_guidelines(task: str, top_k: int | None, core_support: int | None): Retrieve the always-on guideline core plus a task-relevant dosage.
• list_entities(...): Return structured, filtered, cursor-paginated entity inventory for user and administrative UIs.
• get_entity(entity_id: str, user_id: str | None, record_access: bool = True): Return one structured entity, enforcing ownership when a caller ID is supplied.
• patch_entity_metadata(entity_id: str, metadata_patch: str, user_id: str | None): Merge JSON metadata through the memory hook seam.
• record_access(entity_ids: list[str], accessed_at: str | None): Explicitly stamp the retention engine's last_accessed signal.
• validate_retention_policy(policy: str): Validate and normalize a JSON retention policy without scanning data.
• put_retention_policy(policy_id: str, name: str, policy: str, ...): Create or replace an Evolve-owned retention policy.
• get_retention_policy(policy_id: str) / list_retention_policies(): Read the namespace's policy catalog for operators and management UIs.
• run_retention(policy_id: str, dry_run: bool = True, ...): Dry-run or apply a stored policy and persist a structured, entity-linked report.
• list_retention_runs(...): Read namespace-scoped retention run history, optionally filtered by agent or policy.
• get_compliance_status(): Report backend health, retention availability, hook coverage, and configured plugin health.