ALTK-Evolve MCP
Agent memory over MCP: past work trajectories become guidelines for new tasks, with a lite version for Claude Code and Codex
- 136 ★ on the repository
- Last commit
Extended access
Why this level
- Stores agent work trajectories and derived guidelines, and the API on a local address has no authentication
- Calls a configured LLM to resolve guideline conflicts, and publishing makes guidelines visible to other namespaces
Install
- Works in
Manual install
pip install altk-evolvePython 3.12 or newer is required. The server starts with uv run evolve-mcp, and for MCP clients that need a direct command uv run evolve-mcp --no-dashboard.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Stores agent work trajectories and derived guidelines, and the API on a local address has no authentication
- Calls a configured LLM to resolve guideline conflicts, and publishing makes guidelines visible to other namespaces
This is third-party code. Review the repository files before installing.
What it does
Evolve teaches agents from experience. It extracts reusable guidelines from past work trajectories and mixes them into future tasks without changing model weights. The author reports that on AppWorld a GPT-4.1 agent with Evolve raised scenario completion from 50.0 to 64.3 percent. There are two modes. The lite version plugs into Claude Code, Codex, IBM Bob and Hermes and does all its work inside the agent. The full service consists of an MCP server, vector memory storage and LLM-based guideline conflict resolution. Install comes from PyPI with pip install altk-evolve, the server starts with uv run evolve-mcp, and the web UI at 127.0.0.1:8000/ui/ lets you view and edit entities. Server tools: get_entities and get_guidelines fetch guidelines for a task, save_trajectory stores a trajectory and generates new guidelines, create_entity, publish_entity and unpublish_entity manage guidelines and their visibility across namespaces, and put_retention_policy and run_retention run a retention policy with a dry run. The default backend is filesystem, and Milvus or PostgreSQL with pgvector gives semantic search.
Who it is for. Agent developers and teams who want an agent to accumulate lessons from past runs and stop repeating the same mistakes.
Good fit when
- The agent repeats mistakes on similar tasks and its trajectories should become guidelines
- You need agent memory over MCP with a web UI to view and edit guidelines
- One agent's guidelines should reach others through publishing to a shared space
- You need a record retention policy with a dry run before applying
- You want a trial inside Claude Code or Codex without a separate service: the lite version
Not a fit when
- You need to fine-tune model weights: Evolve does not change weights
- The environment has no Python 3.12: the server is built for it
- You need access control on memory: the API on the local address has no authentication and any local process can read and change memory
- You need a plain notes list without extracting guidelines: another memory fits better
Example request
Save the trajectory of this task with save_trajectory and call get_guidelines before the next similar task, then apply the guidelines foundMCP
- Transport
- stdio, sse
- Authentication
- not required
Environment variables
EVOLVE_MODEL_NAME- Model name for LiteLLM, including a global fallback
Limitations
- Python 3.12 or newer and uv or pip are required; the web UI is built with npm ci && npm run build when installing from source.
- Over stdio evolve-mcp serves the web UI and REST API on 127.0.0.1:8000; the API has no authentication and any local process can read and change memory.
- Guideline conflict resolution needs a configured model through LiteLLM, for example EVOLVE_MODEL_NAME.
- The gains are reported by the author on AppWorld and τ²-bench with different models and configurations and need not repeat on your tasks.
How to disable. Remove the evolve-mcp MCP server entry from the agent settings and run pip uninstall altk-evolve. Filesystem backend data stays in the storage directory and is deleted manually.
FAQ
How do I install Evolve?
Run pip install altk-evolve, then uv run evolve-mcp. For MCP clients that need a direct command use uv run evolve-mcp --no-dashboard, and for SSE add --transport sse --port 8201.
Which agents work in lite mode?
Claude Code, Codex, IBM Bob and Hermes: each has a step-by-step guide in the project documentation.
Does Evolve change model weights?
No. It turns trajectories into guidelines and mixes them into future tasks while the weights stay as they are.
Where is memory stored?
By default in a filesystem backend with simple text matching. Semantic search needs Milvus or PostgreSQL with pgvector.
How do I check that the server is running?
Run npx @modelcontextprotocol/inspector@latest http://127.0.0.1:8201/sse --cli --method tools/list when started over SSE: the tool list confirms it works.
Discussion
No questions or reviews yet.
Related
MCP serversAn agent evolution framework that edits prompts and skills with parallel workers and keeps only what passes a held-out check.
Shared agent memory in plain YAML files: Claude Code, Codex and Cursor remember your corrections across sessions and tools
Six skills and the ae CLI: an agent runs an AlphaEvolve experiment from problem setup to merging the best evolved code
Parallel self-evolution of skills and prompts: workers propose edits and an aggregator merges them into one versioned artifact
A local trajectory compiler that turns Claude Code and Codex session history into training data, tasks and verifiers
Engineering team memory over MCP: decisions, bug causes and constraints recalled by every agent, from Claude Code to Cursor.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| ALTK-Evolve (this card) | no | not required | 136 | |
| Self-Improving Agent | no | 790 | a self-improvement skill; Evolve gives an MCP server, storage and guideline publishing | |
| Mem0 | no | 68,887 | a general AI memory layer; Evolve extracts guidelines from agent work trajectories |
README in short
The page presents Evolve as on-the-job learning for agents, gives results on AppWorld and τ²-bench and links to the paper and posts. Then come a quick start for the lite version, MCP server install from source and PyPI, the tools list with a filter note, features and an architecture with a feedback loop.