langchain-ai/docs
1
0
Fork 0
mirror of https://github.com/langchain-ai/docs.git synced 2026-07-21 11:55:23 -04:00
Code Issues 490 Packages Projects Releases Wiki Activity

[GH-ISSUE #3738] [deepagents] Document MemoryMiddleware add_cache_control (Anthropic) in memory.mdx #2756

New Issue
Open
opened 2026-06-05 17:26:38 -04:00 by yindo · 0 comments
yindo commented 2026-06-05 17:26:38 -04:00
Owner
Copy Link
Copy Source

Originally created by @AdemBoukhris457 on GitHub (Apr 25, 2026).
Original GitHub issue: https://github.com/langchain-ai/docs/issues/3738

Type of issue

request for content

Language

Python

Description

Summary

When memory=[...] is passed to create_deep_agent, the stack attaches MemoryMiddleware with add_cache_control=True. That enables an Anthropic-specific prompt-cache breakpoint (cache_control: {"type": "ephemeral"} on the last system message content block after memory is injected). This behavior is documented in deepagents middleware/memory.py and comments in graph.py, but src/oss/deepagents/memory.mdx does not mention it, so users miss cost/latency and debugging context.

Library behavior (reference)

  • MemoryMiddleware (libs/deepagents/deepagents/middleware/memory.py): optional constructor flag add_cache_control. When True, modify_request tags the last system content_block with cache_control: {"type": "ephemeral"} only if request.model is ChatAnthropic and the system message has content_blocks. Docstring explains this pairs with AnthropicPromptCachingMiddleware on the static system prefix so shifting memory content does not undermine prompt caching; no-ops on non-Anthropic models; Bedrock / Vertex wrappers are called out as not qualifying for the isinstance check.

  • create_deep_agent (graph.py): when memory is set, appends MemoryMiddleware(backend=..., sources=memory, add_cache_control=True) and orders Anthropic prompt caching middleware before memory so memory updates do not invalidate the static prefix cache.

Documentation gap

memory.mdx should briefly explain:

  1. That enabling memory on the default agent turns on add_cache_control from the factory (not obvious vs MemoryMiddleware(..., add_cache_control=False) default for manual construction).
  2. What it does on native ChatAnthropic (second breakpoint at end of system message after memory).
  3. Why (separate dynamic memory from cached static prefix; link to LangChain Anthropic / agents docs on cache_control / prompt caching).
  4. Scope limits: no effect on other providers; Bedrock/Vertex paths as in source docstring.

Suggested fix

Add a Note or short subsection on Memory (for example under how memory is loaded or middleware) with the above bullets and an internal link to Anthropic prompt caching or the existing agents section that documents cache_control / AnthropicPromptCachingMiddleware.

Acceptance criteria

  • memory.mdx mentions add_cache_control / Anthropic cache_control in user-facing prose.
  • Docs distinguish this from LangGraph graph cache (see Customization / graph cache) and from checkpointer / store.
  • Docs align with current MemoryMiddleware and create_deep_agent wiring.
Originally created by @AdemBoukhris457 on GitHub (Apr 25, 2026). Original GitHub issue: https://github.com/langchain-ai/docs/issues/3738 ### Type of issue request for content ### Language Python ### Description ## Summary When `memory=[...]` is passed to `create_deep_agent`, the stack attaches `MemoryMiddleware` with **`add_cache_control=True`**. That enables an **Anthropic-specific** prompt-cache breakpoint (`cache_control: {"type": "ephemeral"}` on the last system message content block after memory is injected). This behavior is documented in **deepagents** `middleware/memory.py` and comments in `graph.py`, but **`src/oss/deepagents/memory.mdx` does not mention it**, so users miss cost/latency and debugging context. ## Library behavior (reference) - **`MemoryMiddleware`** (`libs/deepagents/deepagents/middleware/memory.py`): optional constructor flag **`add_cache_control`**. When `True`, **`modify_request`** tags the **last** system `content_block` with **`cache_control: {"type": "ephemeral"}`** only if **`request.model`** is **`ChatAnthropic`** and the system message has `content_blocks`. Docstring explains this pairs with **`AnthropicPromptCachingMiddleware`** on the static system prefix so **shifting memory content** does not undermine prompt caching; **no-ops** on non-Anthropic models; **Bedrock / Vertex wrappers** are called out as **not** qualifying for the `isinstance` check. - **`create_deep_agent`** (`graph.py`): when `memory` is set, appends `MemoryMiddleware(backend=..., sources=memory, add_cache_control=True)` and orders **Anthropic prompt caching middleware before memory** so memory updates do not invalidate the static prefix cache. ## Documentation gap **`memory.mdx`** should briefly explain: 1. That enabling **`memory`** on the default agent turns on **`add_cache_control`** from the factory (not obvious vs `MemoryMiddleware(..., add_cache_control=False)` default for manual construction). 2. **What** it does on **native `ChatAnthropic`** (second breakpoint at end of system message after memory). 3. **Why** (separate dynamic memory from cached static prefix; link to LangChain Anthropic / agents docs on **`cache_control`** / prompt caching). 4. **Scope limits**: no effect on other providers; Bedrock/Vertex paths as in source docstring. ## Suggested fix Add a **Note** or short subsection on **[Memory](/oss/deepagents/memory)** (for example under how memory is loaded or middleware) with the above bullets and an internal link to [Anthropic prompt caching](/oss/langchain/agents) or the existing agents section that documents `cache_control` / `AnthropicPromptCachingMiddleware`. ## Acceptance criteria - [ ] `memory.mdx` mentions `add_cache_control` / Anthropic `cache_control` in user-facing prose. - [ ] Docs distinguish this from LangGraph graph **`cache`** (see Customization / graph cache) and from **`checkpointer`** / **`store`**. - [ ] Docs align with current `MemoryMiddleware` and `create_deep_agent` wiring.
yindo added the externaldeepagents labels 2026-06-05 17:26:38 -04:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
deepagents
docs-infra
external
external
help wanted
integration
internal
internal
javascript
js/ts
langchain
langgraph
langsmith
needs-title
pull-request
Mirrored from GitHub Pull Request
 python
reference
No Label deepagents external
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langchain-ai/docs#2756
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?