nexus/wiki/concepts/State-Externalization.md

title, type, tags, sources, last_updated

title	type	tags	sources	last_updated
State Externalization	concept	harness-engineering agentic-ai memory	Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog	2026-04-20

Overview

State Externalization——将任务状态（pending/in-progress/completed）写入磁盘文件而非仅保存在 context window 的工程实践，是 Harness-Engineering 第二原则的具体实现。

Core Principle

如果一条信息对任务连续性重要——已完成什么、待处理什么、什么失败了——它必须存在于 context window 之外。

Context window 是易失的。磁盘文件是持久的。

Two-Tier Memory Model

Working Memory (Short-term)

当前步骤所需的即时对话和 context window。

Persistent State (Long-term)

结构化文件（如 state.json）追踪精确的子任务状态：

{
  "task_id": "market-research-report",
  "steps": {
    "fetch_competitor_a": "COMPLETED",
    "fetch_competitor_b": "COMPLETED",
    "fetch_competitor_c": "FAILED",
    "compare": "PENDING"
  },
  "last_updated": "2026-04-20T10:30:00Z"
}

Why It Matters

• Context window 在每次新 LLM 调用时重置
• 状态不外部化 → 每次重置都丢失进度
• 进程崩溃 → 整个任务从头开始

Context-Reset Integration

State Externalization 是 Context-Reset 的前提——必须先有可写磁盘的状态文件，才能实现有意义的 Context Reset。

Memory-Consolidation Integration

State Externalization 写入的是原始状态，Memory-Consolidation 定期压缩这些状态防止膨胀。

Source

• Your-AI-Isn-t-Stupid---It-Just-Needs-a-Better-Harness--Lychee-Technology-Engineering-Blog