/agentsop-session-state-hygiene

name: agentsop-session-state-hygiene
version: 0.1.0
description: |
  Decision protocol for managing the context/session state of an AI coding tool:
  when to /clear, when to keep context, and how to detect "context bleed" — the
  failure mode where stale conversation history biases the model against the
  current task. Surfaces a discipline that Aider (/clear), Claude Code (/clear),
  CrewAI (memory=False, re-instantiate), and LangGraph (new thread_id, subgraph
  isolation) all encode separately but none name as a skill.
phase: D
tier: common
frequency: daily
audience: coder-agents and human engineers who run multi-turn LLM coding sessions
source: aider-sop, crewai-sop, langgraph-sop (local) + vendor docs

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**