{"record":{"id":"e855afc993224a8f","repo":"FoundationAgents/MetaGPT","slug":"to-use-the-rolezeromemory-you-need-to-install-the","errorCode":null,"errorMessage":"To use the RoleZeroMemory, you need to install the rag module.","messagePattern":"To use the RoleZeroMemory, you need to install the rag module\\.","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"metagpt/memory/role_zero_memory.py","lineNumber":56,"sourceCode":"\n    @property\n    def rag_engine(self) -> \"SimpleEngine\":\n        if self._rag_engine is None:\n            self._rag_engine = self._resolve_rag_engine()\n\n        return self._rag_engine\n\n    def _resolve_rag_engine(self) -> \"SimpleEngine\":\n        \"\"\"Lazy loading of the RAG engine components, ensuring they are only loaded when needed.\n\n        It uses `Chroma` for retrieval and `LLMRanker` for ranking.\n        \"\"\"\n\n        try:\n            from metagpt.rag.engines import SimpleEngine\n            from metagpt.rag.schema import ChromaRetrieverConfig, LLMRankerConfig\n        except ImportError:\n            raise ImportError(\"To use the RoleZeroMemory, you need to install the rag module.\")\n\n        retriever_configs = [\n            ChromaRetrieverConfig(\n                persist_path=self.persist_path,\n                collection_name=self.collection_name,\n                similarity_top_k=self.similarity_top_k,\n            )\n        ]\n        ranker_configs = [LLMRankerConfig()] if self.use_llm_ranker else []\n\n        rag_engine = SimpleEngine.from_objs(retriever_configs=retriever_configs, ranker_configs=ranker_configs)\n\n        return rag_engine\n\n    def add(self, message: Message):\n        \"\"\"Add a new message and potentially transfer it to long-term memory.\"\"\"\n\n        super().add(message)","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/FoundationAgents/MetaGPT/blob/11cdf466d042aece04fc6cfd13b28e1a70341b1f/metagpt/memory/role_zero_memory.py#L38-L74","documentation":"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.","triggerScenarios":"Instantiating RoleZeroMemory and accessing its rag engine (e.g. calling index/add/retrieve) in an environment where the 'rag' optional dependencies were never installed.","commonSituations":"pip install metagpt without extras, then using RoleZero with memory retrieval enabled; slim environments/containers trimmed to base requirements; upgrading MetaGPT without reinstalling extras.","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."],"exampleFix":"# before\npip install metagpt\nmem = RoleZeroMemory(); mem.rag_engine  # ImportError\n\n# after\npip install \"metagpt[rag]\"","handlingStrategy":"validation","validationCode":"def rag_available() -> bool:\n    try:\n        import metagpt.rag  # noqa\n        return True\n    except ImportError:\n        return False\n\nuse_rag = rag_available()","typeGuard":null,"tryCatchPattern":"try:\n    mem = RoleZeroMemory(); _ = mem.rag_engine\nexcept ImportError as e:\n    if \"rag module\" in str(e):\n        raise RuntimeError(\"install with: pip install metagpt[rag]\") from e\n    raise","preventionTips":["Pin metagpt[rag] in requirements when using RoleZero memory retrieval.","Feature-detect the rag import at startup and fall back to plain memory."],"tags":["optional-dependency","rag","import","memory"],"backgroundTag":null,"analyzedSha":"11cdf466d042aece04fc6cfd13b28e1a70341b1f","analyzedAt":"2026-08-14T23:20:02.994Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}