agentscope-ai/agentscope · error · ValueError

f"Unknown mode {mode!r}; expected one of 'static_control', '

Error message

f"Unknown mode {mode!r}; expected one of 'static_control', 'agent_control', 'both'."

What it means

Mem0Middleware supports exactly three memory-injection modes ('static_control', 'agent_control', 'both'); any other string is rejected at construction with the offending value echoed.

Source

Thrown at src/agentscope/middleware/_longterm_memory/_mem0/_middleware.py:258

                When ``True`` (default) the post-turn ``add`` call is
                awaited inline. When ``False`` it's fire-and-forget —
                faster response but exceptions only surface in logs.
            memory_section_header, memory_section_intro:
                Strings used when injecting retrieved memories into
                the model's messages list (``static_control`` /
                ``both`` modes).
            tool_instructions:
                Markdown block appended to the agent's system prompt
                in ``agent_control`` / ``both`` modes, advertising the
                ``search_memory`` / ``add_memory`` tools to the LLM.
        """
        is_empty_user_id = isinstance(user_id, str) and not user_id.strip()
        if user_id is None or is_empty_user_id:
            raise ValueError(
                "Mem0Middleware requires a non-empty `user_id`.",
            )
        if mode not in ("static_control", "agent_control", "both"):
            raise ValueError(
                f"Unknown mode {mode!r}; expected one of "
                f"'static_control', 'agent_control', 'both'.",
            )

        client = self._resolve_client(
            client=client,
            chat_model=chat_model,
            embedding_model=embedding_model,
            mem0_config=mem0_config,
        )
        self._client = client

        self._user_id = user_id
        self._agent_id = agent_id
        self._mode = mode
        self._top_k = top_k
        self._threshold = threshold
        self._scope_search_by_agent = scope_search_by_agent

View on GitHub (pinned to e90f1c7592)

Solutions

1. Use one of 'static_control', 'agent_control', 'both'
2. Check the installed version's signature if the mode list changed
3. Consider 'both' when unsure — it enables both injection styles

Example fix

// before
Mem0Middleware(user_id='u1', mode='auto')
// after
Mem0Middleware(user_id='u1', mode='both')

VALID_MODES = ('static_control', 'agent_control', 'both')
if mode not in VALID_MODES:
    raise ValueError(f'mode must be one of {VALID_MODES}')

from typing import Literal
Mode = Literal['static_control', 'agent_control', 'both']
def is_valid_mode(m: str) -> bool:
    return m in ('static_control', 'agent_control', 'both')

try:
    mw = Mem0Middleware(user_id='u1', mode=mode)
except ValueError as e:
    if 'Unknown mode' in str(e):
        mw = Mem0Middleware(user_id='u1', mode='both')
    else:
        raise

When it happens

Trigger: Mem0Middleware(mode='auto'), mode='static', or a typo like 'agent-controll'.

Common situations: Assuming mode names from other middleware; renaming during version upgrades; IDE autocomplete typos.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• "AgentScopeLLM requires `model` in the config to be an Agent
• f"AgentScopeLLM `model` must be a ChatModelBase, got {type(s
• "AgentScopeLLM received no usable messages (empty list or al
• "AgentScopeEmbedding requires `model` in the config to be an
• f"AgentScopeEmbedding `model` must be an EmbeddingModelBase,

AI-assisted analysis of agentscope-ai/agentscope@e90f1c7592 (2026-08-28). Data as JSON: /api/errors/745d2c20ae2b46da. Report an issue: GitHub.