ALTK-Evolve

// Overview

Coding agents repeat the same mistakes because every session starts from zero. ALTK-Evolve, from IBM Research, is the memory layer that fixes that: it takes the trajectory of a completed run and distils it into reusable guidelines, then retrieves the relevant ones the next time the agent faces a similar task. The point is targeted guidance rather than a growing transcript — the agent gets the lesson, not the log.

The system is built from an MCP server for tool integration, a vector store for the guideline memory, and LLM-based conflict resolution that reconciles a new guideline against what is already stored. The default filesystem backend uses simple text matching and needs no extra dependencies; pgvector and Milvus backends are available as extras for semantic similarity search at production scale. A Web UI ships alongside the MCP server for browsing and editing the knowledge base.

The "Lite" configuration is meant to slot into an existing assistant — the repo documents hello-world setups for Claude Code, Codex and IBM Bob. Guidelines are namespaced per owner and private by default, with explicit `publish_entity` / `unpublish_entity` calls to share one across namespaces and server-side ownership enforcement on the way back. IBM reports a +8.9 point overall reliability improvement on the AppWorld benchmark, with a 74% relative increase on hard multi-step tasks; the underlying research is published as arXiv 2603.10600.

// What it does

• Trajectory-to-guideline distillation: `save_trajectory` turns a completed run into reusable guidance instead of a transcript
• Targeted retrieval via `get_entities` / `get_guidelines`, so the agent pulls only the guidelines relevant to the task at hand
• LLM-based conflict resolution when a new guideline contradicts one already in the store
• Pluggable backends — filesystem text matching by default, pgvector or Milvus extras for semantic vector search
• An MCP server (stdio or SSE transport) plus a FastAPI Web UI for inspecting and editing the knowledge base
• Per-owner namespaces with private-by-default visibility and explicit publish / unpublish, enforced server-side

// Getting started

Python 3.12 or higher and uv (or pip) are the prerequisites. The quickest path is the PyPI package plus an OpenAI key; LiteLLM proxy configuration is documented for other providers.

pip install altk-evolve

git clone https://github.com/agenttoolkit/altk-evolve.git
cd altk-evolve
uv venv --python=3.12 && source .venv/bin/activate
uv sync
cd frontend/ui && npm ci && npm run build && cd ../..

uv sync --extra pgvector   # or: uv sync --extra milvus

export OPENAI_API_KEY=sk-...

uv run evolve-mcp
# SSE instead:
uv run evolve-mcp --transport sse --port 8201

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

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Give Claude Code or Codex a memory of what worked and what failed on this codebase, so the same mistake is not repeated next session
• Build an agent that improves across runs without stuffing prior transcripts back into its context window
• Share vetted guidelines across a team by publishing selected entities out of a private namespace
• Compare memory strategies with a research-backed baseline — the approach is documented in arXiv 2603.10600 and evaluated on AppWorld

// How ALTK-Evolve compares

ALTK-Evolve alongside other open-source agent memory tools AI/TLDR tracks, ranked by GitHub stars.