# How GenericAgent's Self-Evolution Mechanism Crystallizes Tasks into Reusable Skills

> Discover how GenericAgent's self-evolution mechanism transforms tasks into reusable skills. Learn about its hierarchical memory system for efficient pattern storage and recall.

- Repository: [LJQ/GenericAgent](https://github.com/lsdefine/GenericAgent)
- Tags: deep-dive
- Published: 2026-04-16

---

**GenericAgent's self-evolution mechanism automatically distills successful task executions into persistent, reusable skills through a hierarchical memory system that promotes verified execution patterns from transient working memory to durable long-term storage.**

The `lsdefine/GenericAgent` repository implements an autonomous agent architecture that doesn't just complete tasks—it learns from them. By analyzing the source code in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) and the memory management subsystem, we can see exactly how the agent transforms one-off tool executions into a growing library of **L3 Task Skills** that can be indexed and recalled for future work.

## The Memory-Layered Architecture

GenericAgent organizes knowledge into three distinct layers that govern the lifecycle of learned information:

- **L1 (Working Memory)** – Transient storage for the current session's raw tool calls and summaries.
- **L2 (Global Facts)** – Persistent storage for environment constants like file paths, credentials, and configuration snippets.
- **L3 (Task Skills / SOPs)** – Reusable standard operating procedures that encode complete execution patterns.

This architecture is enforced by the **Memory Management SOP** documented in [`memory/memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/memory/memory_management_sop.md), which specifies that only stable, verified information may be promoted to L2 and L3 layers.

## The Crystallization Pipeline

The self-evolution process follows a strict pipeline from execution to skill creation, implemented across several core files.

### Execution and Recording in Working Memory

During an autonomous run, every tool invocation is intercepted by the agent loop in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py). The loop logs the action, its result, and a concise `<summary>` tag into L1 working memory.

According to the source at [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) line 36-46, this wrapping occurs for all tool calls including `code_run`, `web_scan`, and `file_write`, creating a complete execution trace before any long-term storage occurs.

### Triggering Long-Term Updates

When the agent determines a task is complete, it invokes the **`start_long_term_update`** tool, also defined in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) (lines 8-16). This tool prompts the agent to extract:

- **Verified facts** proven during the execution
- **Preferred settings** that yielded successful results
- **High-value execution steps** that form the core of the new skill

This trigger acts as the gatekeeper between transient working memory and permanent skill storage.

### Memory Management SOP Enforcement

The prompt for `start_long_term_update` references [`memory/memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/memory/memory_management_sop.md) (lines 3-8), which mandates strict criteria for L2 and L3 writes. The SOP ensures that:

- Only reproducible patterns reach L3
- Environment-specific data is isolated in L2
- Working memory is cleared or archived after crystallization

### L2 Global Facts and L3 Task Skills Creation

Based on the SOP guidelines, the agent separates extracted knowledge into two streams:

**L2 (Global Facts)** are appended to the L2 index via `file_patch`, maintaining searchable environment constants.

**L3 (Task Skills)** are crafted as markdown SOPs capturing the **execution pattern** (inputs → tool calls → outcomes). These are stored under `memory/` subdirectories like `memory/skill_search/`. Each SOP represents a **reusable skill** that can be invoked directly without repeating the original reasoning steps.

## Skill Indexing and Retrieval

Once crystallized, skills must be discoverable. The [`memory/skill_search/skill_search/engine.py`](https://github.com/lsdefine/GenericAgent/blob/main/memory/skill_search/skill_search/engine.py) file implements the indexing system.

### SkillIndex Data Structure

Lines 8-31 of [`engine.py`](https://github.com/lsdefine/GenericAgent/blob/main/engine.py) define the `SkillIndex` dataclass, which stores metadata for each L3 SOP:

```python

# Conceptual structure based on engine.py

@dataclass
class SkillIndex:
    key: str              # Unique identifier

    name: str             # Human-readable name

    description: str      # What the skill does

    category: str         # Classification

    tags: List[str]       # Searchable keywords

    autonomous_safe: bool # Can run without supervision

```

This structured metadata enables semantic and keyword-based skill retrieval.

### The Search Interface

Lines 47-52 of [`engine.py`](https://github.com/lsdefine/GenericAgent/blob/main/engine.py) implement the `search(query, env)` function, which:

1. Accepts a natural language query and environment context
2. Returns `SearchResult` objects containing matching `SkillIndex` entries
3. Provides ready-to-run tool configurations derived from the stored SOPs

When the agent encounters a new task, it queries this engine to determine if a crystallized skill exists, enabling **one-line invocation** of previously complex workflows.

## Practical Code Examples

The following examples demonstrate the crystallization workflow using the actual tool interfaces defined in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) and the skill search engine.

### Executing and Crystallizing a Task

```python

# Execute a complex data processing task

response = agent.run({
    "tool": "code_run",
    "args": {
        "code": "import pandas as pd; df = pd.read_csv('data.csv'); df_clean = df.dropna(); df_clean.to_csv('clean.csv')",
        "type": "python"
    }
})

# Trigger the crystallization process at task completion

result = agent.run({
    "tool": "start_long_term_update",
    "args": {}
})
print(result)  # Output: Memory snippet distilled and SOP created in memory/skill_search/

```

### Retrieving and Reusing a Crystallized Skill

```python
from skill_search import search

# Search for previously crystallized data cleaning skills

matches = search("process CSV with pandas")

for result in matches:
    print(f"📌 Skill: {result.skill.name}")
    print(f"📝 Description: {result.skill.description}")
    print(f"🔧 Tools: {result.skill.tools}")
    
    # Direct invocation of the reusable skill

    if result.skill.autonomous_safe:
        agent.run(result.skill.invocation_config)

```

## Summary

- **GenericAgent's self-evolution mechanism** operates through a three-layer memory hierarchy (L1 Working, L2 Global Facts, L3 Task Skills).
- The **`start_long_term_update`** tool in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) triggers the crystallization process when tasks complete.
- **Memory Management SOP** constraints ensure only stable, reusable patterns reach L3 storage.
- **SkillIndex** objects in [`memory/skill_search/skill_search/engine.py`](https://github.com/lsdefine/GenericAgent/blob/main/memory/skill_search/skill_search/engine.py) provide structured metadata for discovering crystallized skills.
- The system enables **autonomous skill reuse** through the `search()` interface, allowing one-line invocation of complex previously-solved workflows.

## Frequently Asked Questions

### What triggers the skill crystallization process in GenericAgent?

The crystallization process triggers when the agent invokes the **`start_long_term_update`** tool, defined in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) at lines 8-16. This tool executes only after the agent determines that a task is complete, prompting the system to extract verified facts and high-value execution steps from the current working memory (L1) and promote them to long-term storage layers (L2 and L3).

### How does GenericAgent distinguish between temporary working memory and permanent skills?

GenericAgent implements a **Memory Management SOP** documented in [`memory/memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/memory/memory_management_sop.md) (lines 3-8) that enforces strict boundaries between memory layers. **L1 (Working Memory)** holds transient session data like raw tool calls and immediate summaries. **L2 (Global Facts)** stores stable environment constants such as paths and credentials. **L3 (Task Skills)** contains only reusable Standard Operating Procedures (SOPs) that capture complete execution patterns validated through successful task completion.

### Where are crystallized skills stored and how are they indexed?

Crystallized skills are stored as markdown SOP files within the `memory/` directory, typically organized under subfolders like `memory/skill_search/`. Each skill is indexed via the **`SkillIndex`** dataclass defined in [`memory/skill_search/skill_search/engine.py`](https://github.com/lsdefine/GenericAgent/blob/main/memory/skill_search/skill_search/engine.py) (lines 8-31). The index tracks metadata including `key`, `name`, `description`, `category`, `tags`, and `autonomous_safe` status, enabling the `search()` function (lines 47-52) to retrieve relevant skills based on natural language queries and environmental context.

### Can crystallized skills be executed automatically without human intervention?

Yes, provided the skill has been marked as **`autonomous_safe`** in its `SkillIndex` metadata. When the `search()` function in [`memory/skill_search/skill_search/engine.py`](https://github.com/lsdefine/GenericAgent/blob/main/memory/skill_search/skill_search/engine.py) returns a `SearchResult`, it includes the skill's configuration and invocation details. If `autonomous_safe` is set to `True`, the agent can execute the skill directly using `agent.run(result.skill.invocation_config)` without requiring additional human oversight or step-by-step reasoning.