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

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.

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, 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 at line 508, the implementation handler do_start_long_term_update receives the call:

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.

prompt = '''

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

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

The helper get_global_memory(), also defined in 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:

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 is returned as the tool's result, while the distillation prompt is passed as next_prompt:

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) 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 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:

# 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:

{
  "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, completing the long-term memory update cycle.

Summary

• start_long_term_update is implemented as do_start_long_term_update in 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}