Agentsop Session State Hygiene

Session-State Hygiene · SOP

One line: context is signal; stale context is noise; clearing restores signal. A coding session is a sliding window of evidence. Early in a task the window is pure signal. The longer it runs, the more dead ends, abandoned plans, and superseded files accumulate — and at some point yesterday's good context becomes today's bad bias. This skill is the discipline of noticing that moment and acting on it with the smallest correct cut.

Source posture: every framework-specific claim is cited inline as [tool/topic]. Resolve tags against references/R1-source-evidence.md (full URLs) and references/R2-tool-commands.md (copy-pastable commands).

1. 何时激活 (When to Activate)

Activate this skill the moment any of these fire — they are the symptoms of context bleed, not vague unease:

• Topic shift inside a session. You finish feature A and start unrelated bug B in the same window/REPL/thread. The A-history is now pure noise for B.
• Length / window warning. The tool reports the context window is N% full, or Aider's /tokens crosses ~25k — the empirically observed point where "most models start to become distracted and become less likely to conform to their system prompt" [aider/edit-errors].
• Weird behavior — the tell-tale signs of bleed:
  • The model repeats a mistake you already corrected ("don't use requests" → it uses requests again).
  • It references a file or decision you already removed / dropped.
  • It obeys an older instruction over the newest one (it conforms to turn 3 but ignores turn 30).
  • Edit-format errors climb (Aider "SEARCH block not found" recurs) [aider/edit-errors].

The activation trap to avoid: when behavior gets weird, the reflex is to rephrase the prompt, retry, or swap the model. If the history is polluted, none of those help — you are arguing with a model that is reading stale evidence. Activate this skill before reaching for a prompt rewrite.

Do not activate for: a single LLM call, a one-shot RAG query, or a brand new session with <25k tokens that is behaving correctly. Hygiene on a clean window is just superstition — see §6.

2. 核心心智模型 (Core Mental Model)

Context is signal; stale context is noise; clearing restores signal.

Three load-bearing ideas ride this axiom:

2.1 The session window is evidence, and evidence decays

Every turn you add to a session is evidence the model reasons over. Good evidence (the current goal, the relevant files, the last working diff) raises signal. Stale evidence (a failed approach you abandoned, a 5k-token search dump you no longer need, a file you dropped) raises noise. The signal-to-noise ratio of the window — not its absolute size — is what governs output quality. A 10k window of pure noise is worse than a 30k window of pure signal.

2.2 There is a measured distraction threshold

Aider's tooling is built around a hard, published number: above ~25k tokens "most models start to become distracted" [aider/edit-errors]. No other framework publishes a number, but the heuristic transfers: treat ~25k as the point where you should be actively shedding context, not passively letting it grow. This is why /tokens exists and why it is the first move in Aider's edit-error remediation, before swapping model or edit format [aider/edit-errors].

2.3 Clearing is a cut, and cuts have a size

"Clear the context" is not one operation — it is a family ordered by blast radius. The skill is choosing the smallest cut that removes the noise:

        smallest cut                                      largest cut
   ┌───────────────┬────────────────┬───────────────┬──────────────────┐
   │ drop one item │ trim history   │ clear history  │ fresh session /  │
   │ (a file, a    │ (keep last N   │ (keep files,   │ new thread_id    │
   │  message)     │  messages)     │  drop history) │ (zero carry-over)│
   └───────────────┴────────────────┴───────────────┴──────────────────┘
     OP-004 partial   OP-004 partial   OP-002 save+clear   OP-003 fresh

Reaching for "fresh session" when a single /drop would do is as wrong as never clearing at all. Match the cut to the noise.

2.4 The window is not the only state

A subtle trap: "session state" is broader than the visible transcript. CrewAI's memory=True keeps a separate persistent store (LanceDB by default) that a Crew() re-instantiation does not wipe [crewai/memory]. LangGraph's state lives in a checkpointer keyed by thread_id — a new thread_id is clean, but reusing the old one resumes from the last checkpoint [langgraph/persistence]. "I cleared the chat but it still remembers" almost always means a persistent store you didn't clear (§6, AP-005).

3. SOP 工作流 (Standard Operating Procedure)

The flow is four steps: recognize → save what's worth → clear → restart focused. Walk it top-down; each step has a gate.

Step 1 — Recognize (don't act yet)

Gate: name the symptom in one line before touching anything. "The model is still using the JWT approach we abandoned." "Token count is 38k and edits are failing." Naming forces you to identify the single offending source — stale history, an oversized item, or the wrong file set — which then selects the cut size. If you cannot name a symptom, you do not have bleed; do not clear (§6, AP-002). This is OP-001.

Step 2 — Save what's worth keeping (before any clear)

Gate: is there a durable artifact in this session you'd hate to retype? A decision, a file list, a working plan, a passing-test state. If yes, externalize it to something that survives the clear:

• Code → it's already safe if committed (git commit); commit before you clear.
• Decisions / conventions → write to CONVENTIONS.md (Aider re-loads it via --read) or a scratch note [aider/conventions].
• The plan / state-of-the-world → ask the model for a one-paragraph summary (decisions made, files touched, tests passing, open questions), copy it.

The keepers go to disk/git/clipboard — never left only in the volatile window you are about to wipe. This is OP-002.

If the bug you're hunting depends on the exact phrasing the model used three turns ago, a summary is too lossy — save the raw transcript instead. But if you need the raw transcript, ask whether you actually needed to clear.

Step 3 — Clear (smallest correct cut)

Pick the cut from §2.3 by blast radius:

For code tools, the working tree on disk is never touched by a chat clear — /clear resets the transcript, not your files [claude-code/slash] [aider/commands].

Step 4 — Restart focused

Gate: the first message of the new context is a focused goal statement, not a data dump. Open with the saved one-paragraph summary (OP-002) plus the single current objective. Do not paste the old transcript back — that recreates the pollution with extra steps (§6, AP-003). A clean window seeded with distilled state is the entire payoff of clearing.

4. 操作模型 (Operation Models)

Each operation: Trigger → Action → Output → Evidence. Full machine-readable form in intermediate/operation_candidates.json; commands in references/R2.

OP-001 · Detect context bleed

• Trigger: Any §1 symptom — topic shift, length warning, or weird behavior (repeats corrected mistake / cites removed item / obeys old over new).
• Action: Stop. Do not edit the prompt, retry, or swap model. Name the symptom in one line and identify the single offending source.
• Output: A named symptom and a chosen cut (OP-002/003/004/006).
• Evidence: [aider/edit-errors] (25k distraction); [langgraph/persistence].

OP-002 · Save-and-clear (same topic, polluted history)

• Trigger: Continue the same topic but history is full of dead ends.
• Action: (1) Have the model summarize decisions + state in one paragraph. (2) Copy it to disk/clipboard. (3) Clear: Aider /clear, Claude Code /clear, CrewAI re-instantiate Crew, LangGraph new thread_id, web "New chat". (4) Paste the summary as the first message.
• Output: Fresh history seeded with distilled state; files/working tree untouched.
• Evidence: [aider/commands] (/clear preserves /add-ed files).

OP-003 · Fresh thread (topic fully changed)

• Trigger: New feature/bug/task AND nothing from the old session is needed.
• Action: Start a genuinely new session. Aider: relaunch or /reset. Claude Code: /clear or exit. CrewAI: a new Crew() instance (do not reuse). LangGraph: a fresh thread_id (do not reuse the old uuid). Web: New chat.
• Output: Zero bleed; cheapest possible window for the new task.
• Evidence: [crewai/memory]; [langgraph/persistence] (different thread_id = different conversation).

OP-004 · Partial clear (drop a subset, keep continuity)

• Trigger: History is mostly good; one item (a big paste, a stale tool result, an unneeded file) is the noise.
• Action: Surgical removal, not a full clear. Aider: /drop <file> + confirm with /tokens. LangGraph: update_state(config, {"messages": trimmed}) or RemoveMessage. CrewAI: trim a Task's context=[...] to only the needed upstream tasks.
• Output: Reduced footprint, conversational continuity preserved.
• Evidence: [aider/commands] (/drop, /tokens); [langgraph/manage-history].

OP-005 · Fresh thread vs reuse (where to put the seam)

• Trigger: Starting a related-but-new subtask; unsure whether to continue.
• Action: Default to a fresh thread when the new subtask shares <30% of relevant context with the old one. Reuse only when the new task strictly builds on the live state (next step of the same diff).
• Output: A session boundary placed at the natural task seam.
• Evidence: [langgraph/persistence]; [crewai/memory].

OP-006 · Isolate a noisy sub-task in a sub-context

• Trigger: A noisy sub-investigation (debugging, big search, exploratory dump) would pollute the main session if run inline.
• Action: Run it in an isolated context and return only the conclusion. LangGraph: a subgraph with its own state schema. CrewAI: a separate Crew with memory=False, return result.raw. Aider: a second window whose only output back to the main task is a committed diff or a note.
• Output: Main session receives a one-line conclusion, not the full trace.
• Evidence: [langgraph/subgraphs] (child state isolated to shared keys); [crewai/memory].

OP-007 · Memory off during debug

• Trigger: Debugging or evaluating behavior; you need reproducible traces.
• Action: Turn off persistent/auto memory so each run starts from a known state. CrewAI: memory=False (and wipe ~/.crewai/storage/ if memory=True was used). LangGraph: InMemorySaver or a throwaway thread_id. Aider: /clear before each repro.
• Output: Deterministic starting state; runs become comparable.
• Evidence: [crewai/memory] (memory runs extra LLM calls, hard to trace); [langgraph/persistence].

OP-008 · Inspect before you cut

• Trigger: You suspect bloat but haven't confirmed the source.
• Action: Look first. Aider: /tokens, /ls, /map. Claude Code: /context. LangGraph: len(state["messages"]) / get_state. CrewAI: read the LangSmith/MLflow trace.
• Output: The offending source identified, so OP-002/004 cut the right thing.
• Evidence: [aider/commands]; [claude-code/slash]; [langgraph/manage-history].

OP-009 · TTL-sweep stale sessions

• Trigger: Long-lived setups accumulate abandoned threads / huge old stores.
• Action: Expire sessions past a threshold (e.g. 24h). LangGraph: a TTL sweep on the checkpointer for interrupted-but-never-resumed threads. CrewAI: clear the long-term store. Aider: end sessions; don't keep one REPL alive for days.
• Output: Bounded state growth; no zombie context resurfacing.
• Evidence: [langgraph/hitl] (without a sweep, "state is held in the checkpointer indefinitely").

5. 困境决策案例 (Dilemma Cases)

Case 1 · "The fix depends on a prior file — but bleed is getting worse"

困境: You're 20 turns into refactoring auth.py. The model now mixes in a JWT approach you explicitly abandoned at turn 8, and the correct new code genuinely depends on the session.py changes made at turn 5. Clearing risks losing the dependency; not clearing keeps the bleed.

约束:

• The session.py changes are load-bearing for the current edit.
• The abandoned JWT history is actively misleading the model.
• You don't want to retype the whole refactor plan.

决策步骤:

1. Recognize (OP-001): name it — "model resurrects abandoned JWT; correct edit depends on the turn-5 session.py change."
2. Make the dependency durable, not conversational (OP-002): the turn-5 change is code — commit it (git commit). Now it lives in the working tree, not the volatile transcript. The model will see the file content after a /clear because /clear keeps /add-ed files [aider/commands].
3. Prefer the smallest cut: if only the JWT turns are noise, OP-004 partial — LangGraph update_state to drop those messages; Aider has no message-level drop, so escalate to OP-002.
4. Save + clear (OP-002): one-paragraph summary ("refactoring auth.py to use the new session.py API committed at <sha>; do NOT use JWT"), then /clear, then paste the summary.
5. Restart focused: the new window has the committed file + the summary — the dependency survives, the bleed is gone.

结果: The prior-file dependency is preserved through git, not through chat history — so clearing is safe. The general rule: if the thing you fear losing can be made durable (committed, written to a note), clearing is always safe.

可提取的操作: OP-002 + OP-001. Never let "I might need it" keep a polluted window alive — externalize the keeper, then cut freely.