langchain-ai/deepagents · error · ValueError

system_prompt must contain the `{agent_memory}` format slot

Error message

system_prompt must contain the `{agent_memory}` format slot

What it means

A string system_prompt for MemoryMiddleware must contain the `{agent_memory}` format slot, which is where retrieved memory contents get injected. A string without the slot raises ValueError because memory would never appear in the prompt.

Source

Thrown at libs/deepagents/deepagents/middleware/memory.py:239

                No-ops on non-Anthropic models; Bedrock and Vertex wrappers do
                not qualify.
            system_prompt: System-prompt fragment template. Must contain a
                `{agent_memory}` slot for runtime memory substitution. Pass
                `None` to skip appending entirely (memory is still loaded
                into `state["memory_contents"]`).

        Raises:
            TypeError: If `system_prompt` is not `str` or `None`.
            ValueError: If `system_prompt` is a string missing the
                `{agent_memory}` format slot.
        """
        if system_prompt is not None:
            if not isinstance(system_prompt, str):
                msg = f"system_prompt must be str or None, got {type(system_prompt).__name__}"
                raise TypeError(msg)
            if "{agent_memory}" not in system_prompt:
                msg = "system_prompt must contain the `{agent_memory}` format slot"
                raise ValueError(msg)
        self._backend = backend
        self.sources = sources
        self._add_cache_control = add_cache_control
        self.system_prompt = system_prompt

    def _format_agent_memory(self, contents: dict[str, str], template: str = MEMORY_SYSTEM_PROMPT) -> str:
        """Format memory with locations and contents paired together.

        Substitutes loaded memory into the `{agent_memory}` slot of the
        supplied template.

        Args:
            contents: Dict mapping source paths to content.
            template: Surrounding template; must contain `{agent_memory}`.

        Returns:
            Formatted string with location+content pairs substituted into
            the supplied template.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Add "{agent_memory}" somewhere in the prompt string where memory should be inserted
2. Pass system_prompt=None to use the default MEMORY_SYSTEM_PROMPT template

Example fix

// before
mw = MemoryMiddleware(system_prompt="You are a helpful assistant.")
// after
mw = MemoryMiddleware(system_prompt="You are a helpful assistant.\n\nYour memories:\n{agent_memory}")

def check_prompt_slot(p):
    if isinstance(p, str) and "{agent_memory}" not in p:
        raise ValueError("system_prompt must contain the `{agent_memory}` format slot")
    return p

def has_memory_slot(p) -> bool:
    return p is None or (isinstance(p, str) and "{agent_memory}" in p)

try:
    mw = MemoryMiddleware(system_prompt=prompt)
except ValueError as e:
    if "agent_memory" in str(e):
        prompt = prompt + "\n\n{agent_memory}"
        mw = MemoryMiddleware(system_prompt=prompt)
    else:
        raise

When it happens

Trigger: MemoryMiddleware(system_prompt="You are a helpful assistant.") — any custom string missing the literal substring "{agent_memory}".

Common situations: Writing a custom system prompt and forgetting the injection point; copying a generic prompt from elsewhere; an editor or formatter stripping the braces.

Related errors

• modes can only be provided when agent is a factory
• models can only be provided when agent is a factory
• -32602
• recursion_limit must be None or a positive integer
• Context tool names conflict with rubric-grader tools: {names

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/ff8b043fd033f8d9. Report an issue: GitHub.