# How `start_long_term_update` Distills Experience into L3 Long-Term Memory in GenericAgent

> Discover how start_long_term_update in GenericAgent distills experience into L3 long-term memory skills. Learn to compress agent insights into persistent memory.

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

---

**The `start_long_term_update` tool triggers a workflow that extracts verified environment facts and hard-earned task insights from completed agent interactions, compressing them into persistent L3 (Level 3) skills stored in [`memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/memory_management_sop.md).**

In the GenericAgent architecture, memory is stratified into layers where L3 represents distilled procedural knowledge or Standard Operating Procedures (SOPs). The `start_long_term_update` function, implemented in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py), serves as the gateway between ephemeral task execution and permanent skill formation. When an agent judges that a finished task contains knowledge worth preserving, this built-in tool initiates a structured distillation workflow that transforms raw interaction logs into compact, reusable long-term memory.

## When `start_long_term_update` Initiates the L3 Workflow

The distillation process begins when the agent emits a tool-call payload targeting `start_long_term_update`. According to the source code in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) at line 508, the implementation handler `do_start_long_term_update` receives the call:

```python
def do_start_long_term_update(self, args, response):
    '''Agent觉得当前任务完成后有重要信息需要记忆时调用此工具。'''

```

- The method receives `args` (typically empty) and the **previous LLM response** (`response`), allowing inspection of the completed task context.
- Invocation occurs via standard JSON tool-call semantics: `{"tool_name":"start_long_term_update", ...}`.
- The agent invokes this only after tasks where "verified facts" or "hard-earned experience" warrant preservation beyond the current session.

## Building the Distillation Prompt

The core logic of `do_start_long_term_update` constructs a **system prompt** that instructs the LLM on exactly what to extract for L3 storage. The prompt distinguishes between two memory tiers:

- **Environment facts (L2)** – Verified paths, credentials, and configuration details that persist across sessions.
- **Complex-task experience (L3)** – "坑点 / 前置条件 / 重要步骤" (pitfalls, preconditions, critical steps) that required significant effort to discover, destined to become reusable SOPs.

The prompt explicitly excludes temporary variables, raw reasoning chains, unverified information, and generic knowledge that the agent can reproduce on demand.

```python
prompt = '''

### [总结提炼经验] 既然你觉得当前任务有重要信息需要记忆，请提取最近一次任务中【事实验证成功且长期有效】的环境事实、用户偏好、重要步骤，更新记忆。

...
**操作**：先 `file_read` 看现有 → 判断类型 → 最小化更新 → 无新内容跳过，保证对记忆库最小局部修改。
''' + get_global_memory()

```

The helper `get_global_memory()`, also defined in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py), injects the current global memory snapshot—including paths to memory files and insight templates—so the LLM can reference existing knowledge while generating minimal delta updates.

## Reading the L3 Skill Repository

Before returning control to the LLM, the tool loads the canonical **L3 skill repository** to provide context for the update:

```python
path = './memory/memory_management_sop.md'
if os.path.exists(path):
    result = file_read(path, show_linenos=False)
else:
    result = "Memory Management SOP not found. Do not update memory."

```

The content of [`memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/memory_management_sop.md) is returned as the tool's result, while the distillation prompt is passed as `next_prompt`:

```python
return StepOutcome(result, next_prompt=prompt)

```

This design allows the LLM to see existing L3 SOPs and generate only the necessary additions or modifications, enforcing the principle of minimal local modification to the memory store.

## From Experience to L3 Skills: Verification and Compression

The transformation from raw task logs to L3 skills involves three critical stages:

- **Verification** – Only facts that have passed a `VERIFY` sub-agent check (implemented in the plan mode logic of [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py)) are eligible for L3 promotion. This ensures the memory layer contains validated, reliable information.
- **Abstraction** – The distillation prompt forces the LLM to summarize the core difficulty or insight, stripping away transient variables and session-specific noise to create generic, reusable procedures.
- **Persistence** – The LLM's generated SOP update is written back to [`./memory/memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/./memory/memory_management_sop.md) via a separate `file_patch` call, handled by the agent's generic tool-dispatch logic. This file persists on disk and is reloaded on every new session via `get_global_memory()`.

Each execution of `start_long_term_update` therefore **compresses** a full-blown interaction into a succinct, actionable L3 skill that can be recalled instantly in future tasks.

## Practical Example: Triggering L3 Memory Updates

### Triggering the Tool

When the agent identifies valuable experience, it emits a tool call like:

```python

# Example payload the Agent might emit

tool_call = {
    "tool_name": "start_long_term_update",
    "args": {}
}

# The Agent's runtime sends this to the tool dispatcher,

# which routes it to ga.do_start_long_term_update(...)

```

### Processing the Response

The tool returns a structured outcome:

```json
{
  "result": "# Memory Management SOP\n\n- **Avoid re‑initialising browser when already open**\n- **Always persist user token after first login**\n",

  "next_prompt": "### [总结提炼经验] ..."

}

```

The LLM then generates an update such as:

```

# Updated L3 SOP

- **When a task repeatedly fails at step 3 because of missing Chrome profile, first run `file_patch` to add `--user-data-dir` to the driver init.**

```

The agent subsequently issues a `file_patch` call to persist this snippet into [`memory/memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/memory/memory_management_sop.md), completing the long-term memory update cycle.

## Summary

- **`start_long_term_update`** is implemented as `do_start_long_term_update` in [`ga.py`](https://github.com/lsdefine/GenericAgent/blob/main/ga.py) (line 508) and serves as the entry point for L3 memory formation.
- The tool constructs a **distillation prompt** that directs the LLM to extract only verified environment facts and hard-earned task insights.
- **L3 skills** are stored in [`./memory/memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/./memory/memory_management_sop.md), which acts as a persistent SOP library loaded on every session startup.
- The workflow enforces **minimal local modifications** by requiring the LLM to read existing memory, judge relevance, and produce delta updates rather than wholesale replacements.
- Only **verified information** (checked by VERIFY sub-agents) qualifies for L3 promotion, ensuring the long-term memory layer maintains high reliability.

## Frequently Asked Questions

### What is the difference between L2 and L3 memory in GenericAgent?

**L2 memory** stores verified environment facts such as file paths, credentials, and configuration details. **L3 memory** contains higher-level "skills" or Standard Operating Procedures (SOPs)—abstracted recipes for handling complex tasks, common pitfalls, and critical preconditions that the agent learned through experience. While L2 answers "what is the state," L3 answers "how should I approach this problem."

### How does the agent decide when to call `start_long_term_update`?

The agent invokes `start_long_term_update` through its own judgment mechanism after completing tasks that contain "important information worth remembering." This typically occurs when the agent encounters novel solutions, verified environment constraints, or repeated failure patterns that required significant effort to resolve—indicating the presence of hard-earned experience worth distilling into reusable L3 skills.

### What file stores the L3 skills generated by `start_long_term_update`?

L3 skills are persisted in **[`./memory/memory_management_sop.md`](https://github.com/lsdefine/GenericAgent/blob/main/./memory/memory_management_sop.md)** relative to the agent's working directory. This markdown file serves as the canonical repository for distilled SOPs. The `do_start_long_term_update` function explicitly reads this file via `file_read` before prompting the LLM for updates, ensuring the agent maintains contextually aware, minimally invasive modifications to its long-term skill library.

### Why does `start_long_term_update` use a prompt-based approach rather than directly writing to memory?

The prompt-based design allows the LLM to **judge relevance and minimize updates** rather than blindly appending content. By loading existing L3 memory into context and providing strict extraction guidelines, the tool leverages the LLM's reasoning capabilities to identify truly novel insights, avoid duplicates, and maintain coherent SOP structures. This abstraction layer prevents memory bloat and ensures only compressed, high-value knowledge enters the long-term store.