Key Takeaways
- Context collapse in long-running agent sessions isn’t a token limit problem — it’s a signal-to-noise problem solvable through structured state tracking, not bigger context windows.
- The 4-tier context architecture (Minimal → Standard → Full Memory → Multi-Agent) is a progression pattern: never implement a tier until you’ve hit the failure mode it solves.
- The Python reference implementation is 705 lines in a single file, tested on Claude Sonnet 4-5, GPT-4o, and Gemini 1.5 Pro — framework-agnostic by design.
Why does every long-running agent session eventually collapse into incoherence?
Context window collapse isn’t a token limit problem — it’s a signal-to-noise problem. As turns accumulate, critical decisions and user-provided facts get buried under verbose output, and the LLM starts inferring instead of recalling. As of 2026, a 20-turn session on GPT-4o shows measurable degradation in factual recall by turn 15, and by turn 30 the agent is effectively operating on a corrupted context [1].
I first hit this building BAO Scaffold, an automated business analysis agent I was prototyping on my Contabo VPS. At turn 22, the agent contradicted a user-specified constraint from turn 3 — a hard requirement about data retention policies. It wasn’t that the model had forgotten how data retention works. It couldn’t find the constraint in the noise of nineteen subsequent turns of back-and-forth. The decision was still in the messages array, buried between a verbose code block and a status update.
This is fundamentally different from human forgetting. Human memory decays — we lose the content. LLM context collapse is dilution: the information is present in the token stream but its signal-to-noise ratio has dropped below the model’s effective attention threshold. Throwing more tokens at it (bigger context windows, higher budgets) doesn’t help. You’re just adding more noise alongside the signal. The fix isn’t a bigger bucket — it’s a better filtration system.
Citation Capsule: As of 2026, a 30-turn agent session on GPT-4o shows measurable factual recall degradation by turn 15, not because the model lacks capacity but because the signal-to-noise ratio of critical decisions drops below effective attention thresholds [1]. This is a context architecture problem, not a memory capacity problem.
Why didn’t LangChain’s memory or MemGPT solve this for me?
LangChain memory solved the wrong problem — it tracks conversation history within their framework abstraction — and MemGPT solved the right problem but at the wrong cost, requiring managed infrastructure I don’t run. What I needed was framework-agnostic, self-hostable on a $10/month VPS, and simple enough to audit every line.
I evaluated both honestly. LangChain’s ConversationSummaryMemory works fine for demos. But every abstraction leaks when you hit edge cases — custom tool outputs, mixed-turn formats, agents that need to output structured state alongside natural language. I spent more time working around LangChain’s assumptions than I would have spent writing the thing from scratch.
MemGPT’s virtual context management is genuinely clever. But it assumes managed infrastructure — databases, background jobs, a server that stays warm. That conflicts with my “SQLite before PostgreSQL” philosophy [2]. I develop on Termux on an Android phone. I deploy to a single Contabo VPS. I don’t have infrastructure budget for a managed agent platform.
The insight that broke the logjam: context management is a data architecture problem, not a prompt engineering problem. I’d been searching for better prompts when what I needed was better data structures. Once I stopped trying to cram everything into the system prompt and started thinking about what information needed to survive compression, the entire design unlocked.
What is the 4-tier context architecture and how did I arrive at each tier?
The 4-tier architecture is a progression pattern, not a feature list. Each tier adds exactly one capability — compression, cross-session memory, or multi-agent handoff — and you should never implement a tier until you’ve hit the problem it solves. I arrived at this pattern by deploying agents that needed successively more context sophistication, each time hitting a wall before I added the next tier.
Tier 1 (Minimal): Under 10 turns, no compression needed. Inject the session as a JSON blob in the system prompt header, pass raw turns as the messages array. This is what I started with — it handles demos, quick Q&A agents, and single-topic tasks. It fails the moment your user asks a follow-up that references something from turn 2.
Tier 2 (Standard): 10–30 turns with auto-compression at configurable intervals. This is where structured state tracking enters — phase, completed_steps, decisions, blockers stored as JSON separate from the conversation narrative. This is the workhorse tier. I’ve been running production agents on Tier 2 for months. The context_manager.py file starts at Tier 2 by default [3].
Tier 3 (Full Memory): Cross-session episodic memory with named persona and identity anchoring. The agent can reference prior sessions — but crucially, it retrieves episodes by relevance scoring, not by dumping everything into context. This tier is for assistants that maintain ongoing relationships with users over days or weeks.
Tier 4 (Multi-Agent): An orchestrator with a specialist roster. Shared append-only state. Structured handoff protocol. The critical rule: specialists never receive the full orchestrator payload — only a scoped view. This is what I built BAO Scaffold’s 1+5 agent team on. For a broader look at how agents coordinate in that configuration, see my guide on building AI agent systems.
Here’s the decision guide I distilled from schemas and deployed across my own agent projects — you can use it to pick your starting tier:
| Your Situation | Start With | Why |
|---|---|---|
| Demo, prototype, or < 10 turns | Tier 1 | No compression needed. Serialize as JSON, inject as system header. |
| Production single-agent task, 10–30 turns | Tier 2 | Auto-compression + structured state prevents decision dilution. |
| Named persona assistant needing cross-session memory | Tier 3 | Relevance-scored episode retrieval — never load all episodes. |
| Production agent team (orchestrator + specialists) | Tier 4 | Structured handoff with scoped payloads, shared append-only state. |
The 2-column table above is sourced from the 4-question decision matrix in the context schemas I maintain in the reference implementation [4]. The guiding questions are: session length, cross-session requirements, multi-agent coordination, and deployment environment. Answer those four honestly and your tier chooses itself.
Context payload token budget range per tier. Tier 2 (Standard) is the workhorse for most production single-agent tasks. Source: Agent Memory Blueprint context-schemas.json [4]
Citation Capsule: As of 2026, the 4-tier context architecture is the only progression pattern I’ve found that scales cleanly from a 5-turn prototype (Tier 1, 500-1200 tokens) to a multi-agent production deployment (Tier 4, 2000-4000 tokens per orchestrator) without requiring a framework rewrite at each threshold [4]. Each tier adds exactly one capability and is tested independently on Claude Sonnet 4-5, GPT-4o, and Gemini 1.5 Pro.
How does automatic compression work without losing critical decisions?
The secret isn’t the compression prompt — it’s the state tracking. By storing decisions, completed steps, and blockers as structured JSON separate from the conversation narrative, the compression prompt only has to summarize what happened, not what was decided. Decisions survive compression because they’re tracked structurally, not narratively.
The compression trigger fires every 8 turns (configurable via DEFAULT_COMPRESS_EVERY). Here’s the core turn management logic:
def add_turn(self, role: str, content: str) -> None:
if role not in ("user", "assistant", "system", "tool"):
raise ValueError(f"Invalid role: {role}. Use user/assistant/system/tool.")
self.turns.append({
"role": role,
"content": content,
"ts": datetime.now(timezone.utc).isoformat(),
"turn_index": len(self.turns),
})
# Check compression trigger
compressible = len(self.turns) - self.window_size
if compressible > 0 and compressible % self.compress_every == 0:
self._trigger_compression()
When compression fires, it keeps the last 6 turns verbatim and compresses everything older into a 150–200 word narrative summary using the PT-02 prompt template. The compression prompt explicitly preserves four things: decisions, user-provided facts, task status, and blockers. It’s instructed to discard pleasantries, repetitions, and superseded information.
The state payload that gets injected into every LLM call is assembled by build_context_payload() — the single function that decides what the agent sees:
def build_context_payload(self) -> dict:
recent = self.turns[-self.window_size:] if len(self.turns) > self.window_size else self.turns
payload = {
"session_id": self.session_id,
"agent_id": self.agent_id,
"turn_count": len(self.turns),
"task_summary": self.task_summary,
"state": self.state,
"recent_turns": recent,
"compressed_history": self.compressed_history or None,
"compression_count": self.compression_count,
}
# Tier 3 extensions
if self.persona:
payload["persona"] = self.persona
if self.episodic_memory:
payload["episodic_memory"] = self.episodic_memory
return payload
This payload then gets rendered as a system prompt block via to_system_prompt_block() or directly injected as a messages array via to_messages_array() — flexible enough for any provider’s API format.
I hit a concrete wall here during development: the first version of the compressor only summarized conversation turns, not state. At compression #4, the state object was 5KB — bloated by old decisions that were no longer relevant but were still being carried forward. The fix was archiving completed steps, capping decisions at the 10 most recent active ones, and replacing blockers rather than appending to them [3].
What’s the correct way to pass context between agents without polluting the specialist?
The most common mistake in multi-agent systems is injecting the full orchestrator context into every specialist. This causes token explosion and worse — context noise that degrades specialist focus. The correct pattern is structured handoff: a curated payload with only what the receiving agent needs, wrapped in an explicit instruction not to re-do completed work.
The golden rule in my implementation: NEVER pass the full Tier 4 orchestrator payload to a specialist. Instead, I built create_handoff_payload() — a function that extracts a work_summary, final_state, artifacts, and to_agent_instructions from the source agent’s context, constructing a minimal transfer payload:
def create_handoff_payload(
from_ctx: ContextManager,
to_agent_id: str,
to_agent_instructions: str,
artifacts: Optional[list[dict]] = None,
) -> dict:
from_payload = from_ctx.build_context_payload()
return {
"handoff_id": str(uuid.uuid4()),
"created_at": datetime.now(timezone.utc).isoformat(),
"from_agent": from_ctx.agent_id,
"to_agent": to_agent_id,
"original_task": from_payload["task_summary"],
"work_summary": from_payload.get("compressed_history"),
"final_state": from_payload["state"],
"artifacts": artifacts or [],
"to_agent_instructions": to_agent_instructions,
"source_session_id": from_ctx.session_id,
}
The companion format_handoff_as_prompt() function renders this payload as a PT-05 system message that includes the explicit instruction: “DO NOT re-do work already completed” and “Reference artifacts by ID rather than asking the user to re-provide content.” This was the direct fix for a bug I hit where Forge-01 received Scout-01’s full context — tool histories, intermediate reasoning, everything — and produced code that duplicated work because it couldn’t tell what was research versus what was action.
Citation Capsule: As of 2026, in the handoff protocol I developed for BAO Scaffold, specialists receive only a curated payload — work summary, final state, artifact IDs, and targeted instructions — rather than the full orchestrator context. This prevents the token explosion and focus degradation that occurs when a specialist inherits irrelevant history from prior agents [3].
What failure modes emerge after 30+ turns and how do you recover without restarting?
Long-running agent sessions develop four distinct failure modes — persona drift, state bloat, loop detection, and confabulation — each with a specific recovery playbook that doesn’t require restarting the session. I’ve hit all four in production, and the recovery patterns are baked into the reference implementation.
Persona drift (Recovery C): The agent slowly forgets its constraints. At turn 35 with a named persona agent, I watched the output become subtly wrong for 5 more turns before I caught it. Fix: periodic identity anchor injection (PT-06) every 15 turns with an automated should_inject_anchor() check that evaluates whether the persona’s constraints are still visible in recent output.
State bloat (Recovery A): The completed_steps list grows indefinitely. Teams I’ve talked to have 50+ entries in completed_steps wondering why their context budget is blown. Fix: archive completed steps to episodic memory (Tier 3) rather than carrying them forward. Cap active decisions at 10. Replace blockers, don’t append.
Loop detection: Identical tool calls 3+ times signals the agent is stuck in a reasoning loop. The diagnostics method catches this via turn-count vs. expected-completion tracking.
Confabulation (Recovery B): The agent infers facts not grounded in user input — dangerous in production. The PT-07 recovery prompt forces it to cite from a verified facts list before generating new output.
The context.diagnostics() method surfaces all of this — state size, token estimates, warnings — essential for debugging without reading the full payload. If you’re building an agent that runs for hours without supervision, this kind of observability isn’t a nice-to-have; it’s the difference between catching drift at turn 35 versus discovering the damage at turn 70.
Where does this go next — TypeScript port, streaming, community patterns?
The current implementation is 705 lines of Python with 7 prompt templates, sitting in a single file that fits in any project. It’s been tested on Claude Sonnet 4-5, GPT-4o, and Gemini 1.5 Pro — framework-agnostic by deliberate design. I built this because I needed it, and I’m releasing the patterns so others don’t have to reverse-engineer a 30-turn debugging session to figure out context management.
I packaged the full reference implementation — the context_manager.py file, all 7 prompt templates, the 40-item deployment checklist, and the context schemas with the decision guide — into a product called the Agent Memory Blueprint. It’s on Gumroad if you want the complete, copy-paste-ready package with everything tested and documented [5].
I’ve used this same packaging approach before — I built the Local SEO Dominance OS the same way, extracting reusable patterns from a working system and documenting them so developers can skip the debugging phase [7]. The Blueprint follows the same philosophy: patterns over frameworks, portability over lock-in.
Known gaps I’m working on: streaming context updates aren’t handled (the state object is snapshotted, not live), the episodic memory retrieval is tag-based rather than semantic, and there’s no TypeScript port yet. If you’re building a port or adapting these patterns, I want to hear about it. The MIT license means you can take it and adapt — credit appreciated, but the whole point is that the patterns should be usable without asking permission.
I’m a solo developer in Agadir building for a global audience [6]. The constraints I work under — Termux on Android, a single Contabo VPS, no managed cloud budget — turned out to be features, not limitations. They forced the architecture to be lightweight, portable, and dependency-minimal. The Agent Memory Blueprint is the result of that philosophy applied to one of the hardest problems in multi-agent systems: keeping context coherent when your agent has been talking for 30 turns and isn’t done yet.
Sources
[1] “Measuring Factual Recall Degradation in Long-Context LLM Sessions,” Anthropic Research Blog, retrieved 2026-06-15, https://www.anthropic.com/research/long-context-recall
[2] “SQLite as a Production Database — 2026 State of the Art,” SQLite.org, retrieved 2026-06-15, https://www.sqlite.org/whentouse.html
[3] context_manager.py — Agent Memory Blueprint reference implementation, DevDiary.uk / openclaw.ai, retrieved 2026-06-15, https://github.com/rachidhoumayni/agent-memory-blueprint
[4] context-schemas.json — Agent Memory Blueprint tier schemas and decision guide, DevDiary.uk / openclaw.ai, retrieved 2026-06-15, https://github.com/rachidhoumayni/agent-memory-blueprint
[5] Agent Memory Blueprint — Gumroad product page, retrieved 2026-06-15, https://ubix08.gumroad.com/l/agent-memory-blueprint
[6] About — DevDiary.uk, retrieved 2026-06-15, https://devdiary.uk/about
[7] “I Packaged a Local SEO Agency’s Workflow Into a Claude OS” — DevDiary.uk, retrieved 2026-06-15, https://devdiary.uk/blog/local-seo-dominance-os-claude