# Agentsop Session State Hygiene > | - **Type:** Skill - **Install:** `agentstack add skill-agentsope-skillalchemy-agentsop-session-state-hygiene` - **Verified:** Pending review - **Seller:** [agentsope](https://agentstack.voostack.com/s/agentsope) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [agentsope](https://github.com/agentsope) - **Source:** https://github.com/agentsope/SkillAlchemy/tree/master/skills/agentsop-session-state-hygiene ## Install ```sh agentstack add skill-agentsope-skillalchemy-agentsop-session-state-hygiene ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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 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: | Situation | Cut | Command | |---|---|---| | One bloated item (big file, old dump) | **partial** (OP-004) | Aider `/drop `; LangGraph `update_state(messages=trimmed)` | | Same topic, history polluted | **save + clear** (OP-002) | Aider `/clear`; Claude Code `/clear`; CrewAI re-instantiate `Crew` | | Topic fully changed, nothing carries | **fresh** (OP-003) | Aider `/reset` or relaunch; LangGraph new `thread_id`; web "New chat" | | Noisy sub-investigation pollutes main | **isolate** (OP-006) | LangGraph subgraph; separate CrewAI Crew; second Aider window | | Debugging, need reproducible runs | **memory off** (OP-007) | CrewAI `memory=False`; LangGraph `InMemorySaver` / throwaway thread | 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 ` + 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 **; 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. --- ### Case 2 · "Long task is 80% done — restart clean or push through?" **困境**: A multi-step migration is 80% complete. The window is at 34k tokens (past the ~25k distraction line `[aider/edit-errors]`), edits are starting to fail intermittently, and the model occasionally references a step it already finished. Do you restart (risking the 80% momentum) or push through the last 20%? **约束**: - Restarting costs a re-summary + reload; pushing through risks the failing edits corrupting the near-done work. - The done 80% is mostly *committed code* already. - The remaining 20% is well-defined. **决策步骤**: 1. **Recognize** (OP-001): "34k tokens, intermittent edit failures, model re-references finished steps" — this is bleed at the distraction threshold, not bad luck. 2. **Audit the keepers** (OP-008 → OP-002): is the 80% *durable*? If committed, the momentum lives in git, not the window — restarting loses almost nothing. If uncommitted, **commit first**. 3. **Decision rule on the seam** (OP-005): the remaining 20% shares little relevant context with the noisy 80%-of-failed-attempts history (the *code* is the shared part, and that's on disk). Shared *conversational* context is low → favor a fresh window. 4. **Save + clear** (OP-002): summarize the migration state ("steps 1-8 done, committed at ; remaining: steps 9-10 = update callers + delete shim"), `/clear`, paste, finish the last 20% in clean signal. 5. **Counter-case**: if the last 20% is a *single small edit* and tokens are only slightly over, the cheaper move is OP-004 — `/drop` the unused files and push through. Don't pay the restart tax for one trivial step. **结果**: At 80% with committed work, a clean restart usually *wins* — you finish the hardest 20% on full signal instead of fighting a distracted model. The threshold is whether the done work is durable; if it is, the sunk-cost feeling of the long session is an illusion. **可提取的操作**: OP-005 + OP-002. "Almost done" is not a reason to push through a distracted window; it's a reason to make the done part durable and finish clean. --- ### Case 3 · "I cleared it but the model still remembers" (the hidden-store trap) **困境**: A CrewAI debugging session: you re-instantiated the `Crew()` object between runs, but the agent still recalls a fact from a previous kickoff that you thought you'd wiped. **约束**: You need reproducible runs; the lingering recall makes traces unreadable. **决策步骤**: 1. **Recognize** (OP-001): the symptom is "cleared but remembers" → the state is not in the window you cleared. It's in a **persistent store** (§2.4). 2. CrewAI `memory=True` keeps a separate LanceDB store under `~/.crewai/` that a `Crew()` re-instantiation does **not** touch `[crewai/memory]`. 3. **Memory off for debug** (OP-007): set `memory=False`, and if a prior run used `memory=True`, wipe the store: `rm -rf ~/.crewai/storage/`. 4. Generalize: LangGraph reusing a `thread_id` resumes from a checkpoint — use a fresh `thread_id` (OP-003). Web UIs with cross-chat memory: "New chat" does not clear it; clear it in Settings `[langgraph/persistence]`. **结果**: Deterministic runs once the *actual* state location is cleared. **可提取的操作**: OP-007. Before concluding "clearing doesn't work," ask **which** state you cleared — the transcript or the persistent store. --- ## 6. 反模式与边界 (Anti-Patterns & Boundaries) | # | Anti-pattern | Symptom | Fix | |---|---|---|---| | AP-001 | **Never-clear marathon** | Hours-long session; model "forgets" instructions, invents files dropped 50 turns ago | Clear on any topic shift OR every ~25k tokens (OP-002). `/clear` is a stop-the-line tool, not a panic button `[aider/edit-errors]` | | AP-002 | **Reflexive clear-every-message** | Clearing so often the model loses useful continuity — re-asks answered questions, forgets which files are in scope | Clear only on a *named* symptom (OP-001). "Feels off" is not a trigger | | AP-003 | **Dump the whole old transcript back in** | You `/clear` then paste 50 messages back — pollution recreated with extra steps | Paste a *summary* (OP-002), not raw history. If you truly need the raw history, you didn't need to clear | | AP-004 | **Clear instead of fixing the real bug** | `/clear` after every failed edit, but the bug is in the prompt or model | If the failure repeats *after* a clean clear, the history wasn't the cause — fix the prompt/model | | AP-005 | **Forget memory is on (hidden store)** | "Cleared" the session but the agent still recalls a fact | The persistent store survived (§2.4, Case 3). `memory=False` in debug, or wipe the store `[crewai/memory]` | | AP-006 | **Keep huge old dumps "just in case"** | A 10k-token log/file sits in context for 30 turns "in case it's useful" | If unused for several turns, `/drop` it (OP-004). It can be re-added in seconds; the noise tax is paid every turn | | AP-007 | **Buy a bigger window instead of clearing** | Moving to a 1M-context model to avoid `/clear` | A bigger window doesn't *remove* stale signal — it just lets more noise accumulate. Signal-to-noise, not size, governs quality | **Hard boundaries — when this skill does *not* apply:** - A single LLM call or one-shot RAG query: no session to keep hygienic. - A clean window (` | n/a | trim Task `context=[...]` | `update_state({"messages":...})` / `RemoveMessage` | n/a | | Isolate a sub-task | second window | sub-process | separate `Crew`, `memory=False` | subgraph w/ own schema | New chat | | Memory off (debug) | `/clear` per repro | `/clear` per repro | `memory=False` | `InMemorySaver` / throwaway thread | n/a | Concrete, copy-pastable commands per tool are in `references/R2-tool-commands.md`. ### The four primitives, side by side - **Aider** `[aider/commands]`: file-level granularity. `/clear` wipes chat but keeps the `/add`-ed working set (so the model still knows *what* it can edit); `/reset` wipes both. `/drop` is the partial cut; `/tokens` is the gauge. The cleanest published distraction threshold (~25k) lives here `[aider/edit-errors]`. - **Claude Code** `[claude-code/slash]`: `/clear` resets the in-memory transcript; files on disk are the durable state and are never touched. `/context` to inspect. Hard reset = exit the process. - **CrewAI** `[crewai/memory]`: session state is *split* — the in-process Crew and an opt-in persistent store. `memory=False` (the default) is the debug posture; a `Crew()` re-instantiation clears the in-process state but **not** the persistent LanceDB store. `agent.reset()` / fresh `Agent()` clears per-agent state. Always `memory=False` while debugging. - **LangGraph** `[langgraph/persistence]` `[langgraph/subgraphs]`: state is keyed by `thread_id` in a checkpointer. A new `thread_id` = a clean conversation; reusing one resumes from the checkpoint. `update_state(messages=...)` is the finest-grained partial clear in any surveyed tool. Subgraphs give *structural* isolation — a sub-task with its own state schema can't bleed into the parent except on shared keys, the architecture-level analogue of `/clear`. ### Picking across them The SOP is identical everywhere: **detect bleed → save what's durable → cut at the smallest correct size → restart focused.** Only the command changes. If you work across tools, internalize the *move*, not the syntax — the table above maps the move onto each tool's command. --- ## 附录 · 引用速查 (Citation Index) Short tags used inline → full sources in `references/R1-source-evidence.md`. - `[aider/commands]` = aider.chat/docs/usage/commands.html (`/clear`, `/reset`, `/drop`, `/tokens`) - `[aider/edit-errors]` = aider.chat/docs/troubleshooting/edit-errors.html (~25k distraction threshold; `/clear` as first-line fix) - `[aider/conventions]` = aider.chat/docs/usage/conventions.html (CONVENTIONS.md persistence) - `[claude-code/slash]` = docs.anthropic.com/en/docs/claude-code/slash-commands (`/clear`, `/context`) - `[crewai/memory]` = docs.crewai.com/en/concepts/memory (opt-in memory; debug with memory=False) - `[langgraph/persistence]` = langchain-ai.github.io/langgraph/concepts/persistence/ (thread_id scopes state) - `[langgraph/manage-history]` = langchain-ai.github.io/langgraph/how-tos/manage-conversation-history/ (update_state, RemoveMessage) - `[langgraph/subgraphs]` = langchain-ai.github.io/langgraph/concepts/subgraphs/ (isolated child state) - `[langgraph/hitl]` = docs.bswen.com/blog/2026-04-16-langgraph-human-in-the-loop/ (TTL sweep for abandoned threads) Local sibling SOPs this skill distills from: - `aider-sop-skill/SKILL.md` — §6 context-hygiene table; §5 Case 3 (`/clear` as debugging move) - `crewai-sop-skill/SKILL.md` — DC-4 (memory default off), OP-5 (memory guidance) - `langgraph-sop-skill/SKILL.md` — OP-6 (subgraph isolation), OP-10 (time-travel from checkpoint), §2 (thread_id as session identity) ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [agentsope](https://github.com/agentsope) - **Source:** [agentsope/SkillAlchemy](https://github.com/agentsope/SkillAlchemy) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-agentsope-skillalchemy-agentsop-session-state-hygiene - Seller: https://agentstack.voostack.com/s/agentsope - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.