Write Stage — Creating Context: Memory, Retrieved Docs, Tool Results, History

Context engineering breaks down into 4 fundamental stages, and Writing is the first: it means saving information outside the active context window to help an agent perform a task LATER, rather than trying to keep everything relevant live in the prompt at all times.

This matters because the context window is a scarce, temporary resource — anything that only exists inside the current prompt disappears the moment that request finishes, unless it's explicitly written somewhere durable first. This course identifies three destinations for writing context: long-term memory, which persists ACROSS sessions (a user's stated preference from three conversations ago, still available today); short-term memory, which persists WITHIN a single session (recalling something the user said five messages ago in the same conversation); and a state object, which tracks the current status of a multi-step task (which steps are done, what the intermediate results were, what's still pending).

In an agentic system specifically, the things worth writing include: memory outputs (facts learned about the user or task), retrieved documents (so a later step doesn't need to re-retrieve the same content), tool results (an API response or database query result, saved so subsequent steps can reference it without re-calling the tool), and relevant conversation history (not necessarily the full transcript, but the parts worth persisting). The decision of WHAT to write matters as much as the mechanism — writing indiscriminately creates the same downstream problem the Compress stage (later in this topic) has to clean up, so the write stage itself should already be somewhat selective about what's actually worth persisting versus what's genuinely disposable.

Writing context is the foundation the other three stages build on: there's nothing to Select, Compress, or Isolate later if nothing was durably written in the first place. This is also the stage most directly connected to the memory architecture concepts covered elsewhere in this curriculum — semantic, episodic, and procedural memory are all, at bottom, different KINDS of information this write stage is responsible for persisting.

from dataclasses import dataclass, field
from datetime import datetime

@dataclass
class AgentState:
    """A state object — one of the 3 write destinations the book
    describes, tracking a multi-step task's progress."""
    task: str
    completed_steps: list[str] = field(default_factory=list)
    tool_results: dict[str, str] = field(default_factory=dict)
    pending: list[str] = field(default_factory=list)

class ContextWriter:
    def __init__(self):
        self.long_term_memory: dict[str, str] = {}   # persists ACROSS sessions
        self.short_term_memory: list[str] = []       # persists WITHIN this session

    def write_long_term(self, key: str, value: str) -> None:
        self.long_term_memory[key] = value  # e.g. a stated user preference

    def write_short_term(self, note: str) -> None:
        self.short_term_memory.append(note)  # e.g. something said earlier this session

    def write_tool_result(self, state: AgentState, tool_name: str, result: str) -> None:
        state.tool_results[tool_name] = result  # so later steps don't re-call the tool
        state.completed_steps.append(tool_name)

writer = ContextWriter()
writer.write_long_term("preferred_language", "Spanish")
writer.write_short_term("User asked about order #4471 earlier in this session.")