FoundationAgents/MetaGPT · error · ImportError

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

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.

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)

Solutions

1. Install the rag extra: pip install metagpt[rag] (or add the extra to your dependency pin).
2. 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).
3. 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]"

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

use_rag = rag_available()

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

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

• To use the similarity search, you need to install the RAG mo
• Content column not found in DataFrame.
• File format not supported.
• File {data_path} not found.
• text too long:{text_length}

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