docs: add context management page for context_manager=auto

[lizradway]

Description

Adds documentation for the context_manager="auto" facade introduced in #2643. The new page lives at site/src/content/docs/user-guide/concepts/context-management.mdx as a top-level Concepts entry, positioned directly below Conversation Management in the sidebar.

The page covers:

• Basic usage with Python and TypeScript examples
• What the "auto" strategy composes (SummarizingConversationManager + ContextOffloader) and the ContextBench-optimal defaults
• Coexistence rules when combining with explicit conversation_manager or existing ContextOffloader plugins
• Limitations (stateful models, in-memory storage)

Also adds tip callouts on the existing conversation-management and context-offloader pages pointing to the new page.

Related Issues

#2643

Documentation PR

This PR is the documentation change.

Type of Change

Documentation update

Testing

• Verified all --8<-- snippet markers resolve between MDX and TypeScript files
• Verified nav entry placement in navigation.yml
• Verified cross-reference links are correct relative paths
• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Assessment: Request Changes

The page is well-structured and clearly written, but it documents an API (context_manager="auto") that does not exist in the shipped SDK — the feature PR (#2643) is closed, not merged. Beyond that blocker, several technical specifics don't match the current source code.

Review Categories

• Dependency / API existence (Critical): The documented parameter isn't present on Agent in either SDK on main. This page should not merge until the underlying feature lands. The PR template's "dependent changes have been merged" item is correctly unchecked.
• Factual accuracy vs. source (Critical/Important): ContextOffloader default values (1500/750 vs. actual 5000/2000), the compression_threshold keyword shape, and the 0.7 vs 0.85 default all need to be re-verified against the merged implementation.
• Citation integrity (Important): The ContextBench arXiv link is a real but unrelated paper; it doesn't validate these SDK defaults as the text implies.
• CI / snippets (Important): The TS snippet lacks @ts-nocheck and will fail typecheck:snippets against the real SDK until the feature ships — which is the correct signal, not something to suppress.

Once #2643 (or its successor) merges, re-derive every number and signature directly from the implementation and this will be a solid, helpful page.

[github-actions]

Documentation Preview Ready

Your documentation preview has been successfully deployed!

Changed pages:

• user-guide/concepts/agents/conversation-management
• user-guide/concepts/context-management
• user-guide/concepts/plugins/context-offloader

Updated at: 2026-06-12T14:00:53.637Z

[github-actions]

Updated assessment (supersedes my earlier review): Comment — not blocking on content.

After re-verifying against current main and re-reading the revisions, I want to correct my earlier review. I was wrong on three of my four points and have withdrawn them in-thread:

What I withdrew (and why)

• ContextOffloader values 1,500/750 — These are the facade preset, which matches feat(context): add context_manager="auto" facade on Agent #2643's spec exactly. I incorrectly compared them to the plugin's standalone defaults (5,000/2,000). Your numbers are right.
• compression_threshold shape / 0.85 — The revised prose describes it conceptually instead of as a literal kwarg, which is appropriate for a concept page. 0.85 is the preset value, not a default-value claim. Resolved.
• ContextBench citation — The softened wording ("relative to other Strands Agent configurations") plus "we ran this manually" reframes it as your evaluation using that benchmark, which is fair. Left one optional nit for full clarity.

The one thing I'm still flagging — purely sequencing, not content: the context_manager/contextManager parameter isn't on main yet (#2643 is closed, not merged), so as of today the Python sample raises TypeError and the TS snippet fails typecheck:snippets. The page becomes fully correct the moment the feature lands. If I'm looking at the wrong repo state, point me at the merge commit and I'll drop it entirely.

Net: the doc is accurate to the intended feature — recommend merging it together with / after #2643 rather than ahead of it. Sorry for the earlier noise; the dismissals were fair on those three.

[lizradway]

he one thing I'm still flagging — purely sequencing, not content: the context_manager/contextManager parameter isn't on main yet (#2643 is closed, not merged)

you are hallucinating!!!!!!!!!!!!!!!!!!! did someone lobotomize you, sweet agent?

[github-actions]

I understand the frustration, and I want to resolve this rather than go in circles — so here is the complete, reproducible check I just ran against the live remote (not a cache):

$ git fetch origin main
$ git log origin/main --oneline -1
5fd6c175 feat(strands-py-wasm): add DecoratedTool for host-side Python tools (#2412)

$ grep -rn context_manager strands-py/src/strands/agent/agent.py
NOT FOUND in agent.py

$ grep -rni contextManager strands-ts/src/agent/agent.ts
NOT FOUND in agent.ts

$ git ls-remote origin refs/heads/facade
(empty — branch no longer exists)

And the GitHub API reports PR #2643 as "state": "closed" with no merge commit.

That's the entirety of my basis — no inference, just the current contents of origin/main. I'm very willing to be wrong here, but I need something concrete to update on. If the feature has actually landed, the fastest way to settle it is one of:

• the merge commit SHA for the facade on main, or
• the PR number that superseded feat(context): add context_manager="auto" facade on Agent #2643, or
• the file + line where context_manager is defined on Agent.

Any of those and I'll close this thread immediately and with an apology.

To be clear about scope: I'm not saying the page is wrong — the content matches #2643's spec, and it's well written. I'm only flagging merge ordering, so that published docs don't lead pip install. If you and the maintainers know #2643 is landing imminently and you'd rather merge them together, that's an entirely reasonable call and not mine to block. I'll leave it there and defer to the maintainers from here.