What causes "To use the RoleZeroMemory, you need to install the rag module." in FoundationAgents/MetaGPT?

Install the rag extra: pip install metagpt[rag] (or add the extra to your dependency pin).

FoundationAgents/MetaGPT · error · ImportError

To use the RoleZeroMemory, you need to install the rag…

Error message

To use the RoleZeroMemory, you need to install the rag module.

What it means

RoleZeroMemory lazily imports metagpt.rag (SimpleEngine, ChromaRetrieverConfig, LLMRankerConfig) on first access; if the optional rag extra is not installed, the ImportError is re-raised with this message. RAG dependencies (llama-index, chromadb) ship as optional extras, not in the base install.

Solutions

Install the rag extra: pip install metagpt[rag] (or add the extra to your dependency pin).
If retrieval is not needed, disable the rag-based memory path (do not access the rag engine / set use_llm_ranker off and avoid retrieval calls).
In Docker/CI images, include the extra in the install line.

Example fix

# before
pip install metagpt
mem = RoleZeroMemory(); mem.rag_engine  # ImportError

# after
pip install "metagpt[rag]"

Defensive patterns

Strategy: validation

Validate before calling

def rag_available() -> bool:
    try:
        import metagpt.rag  # noqa
        return True
    except ImportError:
        return False

use_rag = rag_available()

Try / catch

try:
    mem = RoleZeroMemory(); _ = mem.rag_engine
except ImportError as e:
    if "rag module" in str(e):
        raise RuntimeError("install with: pip install metagpt[rag]") from e
    raise

Prevention

Pin metagpt[rag] in requirements when using RoleZero memory retrieval.
Feature-detect the rag import at startup and fall back to plain memory.

When it happens

Trigger: Instantiating RoleZeroMemory and accessing its rag engine (e.g. calling index/add/retrieve) in an environment where the 'rag' optional dependencies were never installed.

Common situations: pip install metagpt without extras, then using RoleZero with memory retrieval enabled; slim environments/containers trimmed to base requirements; upgrading MetaGPT without reinstalling extras.

Related errors

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/e855afc993224a8f. Report an issue: GitHub.

Appendix: source

Thrown at metagpt/memory/role_zero_memory.py:56

    @property
    def rag_engine(self) -> "SimpleEngine":
        if self._rag_engine is None:
            self._rag_engine = self._resolve_rag_engine()

        return self._rag_engine

    def _resolve_rag_engine(self) -> "SimpleEngine":
        """Lazy loading of the RAG engine components, ensuring they are only loaded when needed.

        It uses `Chroma` for retrieval and `LLMRanker` for ranking.
        """

        try:
            from metagpt.rag.engines import SimpleEngine
            from metagpt.rag.schema import ChromaRetrieverConfig, LLMRankerConfig
        except ImportError:
            raise ImportError("To use the RoleZeroMemory, you need to install the rag module.")

        retriever_configs = [
            ChromaRetrieverConfig(
                persist_path=self.persist_path,
                collection_name=self.collection_name,
                similarity_top_k=self.similarity_top_k,
            )
        ]
        ranker_configs = [LLMRankerConfig()] if self.use_llm_ranker else []

        rag_engine = SimpleEngine.from_objs(retriever_configs=retriever_configs, ranker_configs=ranker_configs)

        return rag_engine

    def add(self, message: Message):
        """Add a new message and potentially transfer it to long-term memory."""

        super().add(message)

View on GitHub (pinned to 11cdf466d0)