# agenttoolkit/altk-evolve architecture

> Architecture diagram of the GitHub repository agenttoolkit/altk-evolve, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agenttoolkit/altk-evolve
- Repository: https://github.com/agenttoolkit/altk-evolve

## Overview

Evolve is an agent-memory system: agent clients retrieve task-relevant guidance and submit trajectories, which are processed into reusable entities and stored for later retrieval. Its broader product includes multiple storage backends, an MCP/API and web UI, configurable hooks, versioned processing profiles, Phoenix trajectory sync, and retention/compliance operations. The graph reflects README-described capabilities and relationships supported by the supplied source index or excerpts; unsampled implementation details are not inferred.

Main entry points: [`altk_evolve/frontend/client/evolve_client.py`](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/frontend/client/evolve_client.py) (Evolve client), [`altk_evolve/backend/base.py`](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/backend/base.py) (Memory backend), [`altk_evolve/processing/manager.py`](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/processing/manager.py) (Profile execution), [`altk_evolve/retention/service.py`](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/retention/service.py) (Retention service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_mcp["MCP server<br/>[mcp_server.py]"]
  node_api["HTTP API<br/>[routes.py]"]
  node_client["Evolve client<br/>[evolve_client.py]"]
  node_webui["Web UI<br/>[App.tsx]"]
end

subgraph group_learning["Learning"]
  node_processing["Profile execution<br/>[manager.py]"]
  node_profiles["Profile registry<br/>[registry.py]"]
  node_profile_store[("Profile repository<br/>[repository.py]")]
  node_guideline_learning["Guideline learning<br/>[clustering.py]"]
  node_guideline_retrieval["Guideline retrieval<br/>[retrieval.py]"]
end

subgraph group_memory["Memory"]
  node_memory_backend["Memory backend<br/>[base.py]"]
  node_filesystem[("Filesystem backend<br/>[filesystem.py]")]
  node_postgres[("Postgres backend<br/>[postgres.py]")]
  node_milvus[("Milvus backend<br/>[milvus.py]")]
  node_namespace_db[("Namespace database<br/>[sqlite_manager.py]")]
end

subgraph group_governance["Governance"]
  node_hooks["Memory hooks<br/>[manager.py]"]
  node_retention["Retention service<br/>[service.py]"]
  node_retention_engine["Retention engine<br/>[engine.py]"]
end

subgraph group_integration["Integrations"]
  node_trajectory["Trajectory sync<br/>[phoenix_sync.py]"]
end

node_agent(("AI agent"))
node_operator(("Operator"))
node_phoenix["Arize Phoenix"]

node_agent -->|"uses tools"| node_mcp
node_mcp -->|"serves memory"| node_client
node_operator -->|"manages memory"| node_webui
node_webui -.->|"uses API"| node_api
node_api -->|"handles operations"| node_client
node_client -->|"uses backend"| node_memory_backend
node_agent -->|"submits trajectory"| node_trajectory
node_phoenix -->|"provides traces"| node_trajectory
node_trajectory -->|"stores results"| node_client
node_client -->|"consolidates guidance"| node_guideline_learning
node_client -->|"retrieves guidance"| node_guideline_retrieval
node_guideline_retrieval -->|"uses clusters"| node_guideline_learning
node_client -->|"executes profiles"| node_processing
node_processing -->|"resolves plugins"| node_profiles
node_processing -->|"reads and writes"| node_profile_store
node_memory_backend -->|"dispatches hooks"| node_hooks
node_memory_backend -->|"stores namespace data"| node_namespace_db
node_memory_backend -.->|"implemented by"| node_filesystem
node_memory_backend -.->|"implemented by"| node_postgres
node_memory_backend -.->|"implemented by"| node_milvus
node_client -->|"opens retention"| node_retention
node_retention -->|"executes policies"| node_retention_engine
node_agent -->|"requests guidance"| node_client
node_operator -->|"runs policies"| node_retention

click node_mcp "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/frontend/mcp/mcp_server.py"
click node_api "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/frontend/api/routes.py"
click node_client "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/frontend/client/evolve_client.py"
click node_webui "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/frontend/ui/src/App.tsx"
click node_trajectory "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/sync/phoenix_sync.py"
click node_processing "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/processing/manager.py"
click node_profiles "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/processing/registry.py"
click node_profile_store "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/processing/repository.py"
click node_guideline_learning "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/llm/guidelines/clustering.py"
click node_guideline_retrieval "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/llm/guidelines/retrieval.py"
click node_memory_backend "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/backend/base.py"
click node_filesystem "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/backend/filesystem.py"
click node_postgres "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/backend/postgres.py"
click node_milvus "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/backend/milvus.py"
click node_hooks "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/hooks/manager.py"
click node_retention "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/retention/service.py"
click node_retention_engine "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/retention/engine.py"
click node_namespace_db "https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/db/sqlite_manager.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_api,node_client,node_webui toneBlue
class node_processing,node_profiles,node_profile_store,node_guideline_learning,node_guideline_retrieval toneAmber
class node_memory_backend,node_filesystem,node_postgres,node_milvus,node_namespace_db toneMint
class node_hooks,node_retention,node_retention_engine toneRose
class node_trajectory,node_agent,node_operator,node_phoenix toneIndigo
```

## Components

### Interfaces

- [MCP server](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/frontend/mcp/mcp_server.py): `altk_evolve/frontend/mcp/mcp_server.py`
- [HTTP API](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/frontend/api/routes.py): `altk_evolve/frontend/api/routes.py`
- [Evolve client](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/frontend/client/evolve_client.py): `altk_evolve/frontend/client/evolve_client.py`
- [Web UI](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/frontend/ui/src/App.tsx): `altk_evolve/frontend/ui/src/App.tsx`

### Learning

- [Profile execution](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/processing/manager.py): `altk_evolve/processing/manager.py`
- [Profile registry](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/processing/registry.py): `altk_evolve/processing/registry.py`
- [Profile repository](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/processing/repository.py): `altk_evolve/processing/repository.py`
- [Guideline learning](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/llm/guidelines/clustering.py): `altk_evolve/llm/guidelines/clustering.py`
- [Guideline retrieval](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/llm/guidelines/retrieval.py): `altk_evolve/llm/guidelines/retrieval.py`

### Memory

- [Memory backend](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/backend/base.py): `altk_evolve/backend/base.py`
- [Filesystem backend](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/backend/filesystem.py): `altk_evolve/backend/filesystem.py`
- [Postgres backend](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/backend/postgres.py): `altk_evolve/backend/postgres.py`
- [Milvus backend](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/backend/milvus.py): `altk_evolve/backend/milvus.py`
- [Namespace database](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/db/sqlite_manager.py): `altk_evolve/db/sqlite_manager.py`

### Governance

- [Memory hooks](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/hooks/manager.py): `altk_evolve/hooks/manager.py`
- [Retention service](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/retention/service.py): `altk_evolve/retention/service.py`
- [Retention engine](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/retention/engine.py): `altk_evolve/retention/engine.py`

### Integrations

- [Trajectory sync](https://github.com/agenttoolkit/altk-evolve/blob/main/altk_evolve/sync/phoenix_sync.py): `altk_evolve/sync/phoenix_sync.py`

### Other components

- **AI agent**
- **Operator**
- **Arize Phoenix**

## Connections

- AI agent → MCP server: uses tools (evidence: `README.md`)
- MCP server → Evolve client: serves memory (evidence: `README.md`)
- Operator → Web UI: manages memory (evidence: `README.md`)
- Web UI → HTTP API: uses API
- HTTP API → Evolve client: handles operations (evidence: `altk_evolve/frontend/api/routes.py`)
- Evolve client → Memory backend: uses backend (evidence: `altk_evolve/frontend/client/evolve_client.py`)
- AI agent → Trajectory sync: submits trajectory (evidence: `README.md`)
- Arize Phoenix → Trajectory sync: provides traces (evidence: `altk_evolve/sync/phoenix_sync.py`)
- Trajectory sync → Evolve client: stores results (evidence: `altk_evolve/sync/phoenix_sync.py`)
- Evolve client → Guideline learning: consolidates guidance (evidence: `altk_evolve/frontend/client/evolve_client.py`)
- Evolve client → Guideline retrieval: retrieves guidance (evidence: `altk_evolve/frontend/client/evolve_client.py`)
- Guideline retrieval → Guideline learning: uses clusters (evidence: `altk_evolve/llm/guidelines/retrieval.py`)
- Evolve client → Profile execution: executes profiles (evidence: `altk_evolve/frontend/client/evolve_client.py`)
- Profile execution → Profile registry: resolves plugins (evidence: `altk_evolve/processing/manager.py`)
- Profile execution → Profile repository: reads and writes (evidence: `altk_evolve/processing/manager.py`)
- Memory backend → Memory hooks: dispatches hooks (evidence: `altk_evolve/backend/base.py`)
- Memory backend → Namespace database: stores namespace data (evidence: `altk_evolve/backend/base.py`)
- Memory backend → Filesystem backend: implemented by
- Memory backend → Postgres backend: implemented by (evidence: `altk_evolve/backend/postgres.py`)
- Memory backend → Milvus backend: implemented by
- Evolve client → Retention service: opens retention (evidence: `altk_evolve/frontend/client/evolve_client.py`)
- Retention service → Retention engine: executes policies (evidence: `altk_evolve/retention/engine.py`)
- AI agent → Evolve client: requests guidance (evidence: `README.md`)
- Operator → Retention service: runs policies (evidence: `README.md`)
