Mem0

Common errors

• ModuleNotFoundError: No module named 'mem0'

  cause The Python package is named `mem0ai` on PyPI, but the import name within Python code is `mem0`.
  fix Ensure you have installed the correct package using `pip install mem0ai` and then import it as `import mem0` or `from mem0 import Memory, MemoryClient`.

• ValueError: The v1.0 API format is no longer supported in mem0ai 1.0.0+. Please use v1.1 format which returns a dict with 'results' key.

  cause This error occurs because mem0ai v1.0.0 introduced breaking changes, removing support for the v1.0 API format and standardizing all responses to a dictionary with a 'results' key.
  fix Update your code to use the v1.1 API format. This typically involves removing `version` and `output_format` parameters from method calls and accessing results via `result['results']` instead of treating the response directly as a list.

• AttributeError: 'Memory' object has no attribute 'version'

  cause This is typically caused by attempting to access or pass a `version` parameter to `Memory` or `MemoryClient` methods, which was removed in mem0ai v1.0.0. Other `AttributeError`s may arise from accessing removed parameters or properties that were part of pre-v1.0.0 API.
  fix Remove the `version` parameter from all `Memory` and `MemoryClient` method calls and configurations. Refer to the migration guide for other potential parameter removals and response format changes.

• ImportError: cannot import name 'MemoryClient' from partially initialized module 'mem0' (most likely due to a circular import)

  cause This specific ImportError usually means you have named one of your local Python files `mem0.py`, creating a circular import conflict with the installed `mem0` library.
  fix Rename your local `mem0.py` file to something else to avoid conflict with the library's import name.

• HTTP error occurred: Client error '400 Bad Request' for url 'https://api.mem0.ai/v1/memories/' Failed to add to long term memory: API request failed: {"error":"At least one of the filters: agent_id, user_id, app_id, run_id is required!"}

  cause When using `MemoryClient` with the managed platform, certain API calls (like adding memories) require specific identifiers such as `user_id`, `agent_id`, `app_id`, or `run_id` for proper scoping and data isolation.
  fix Ensure you are passing at least one of the required identification parameters (e.g., `user_id`) when making API calls that store or retrieve memories through the `MemoryClient`.

Warnings

• breaking v1.0 changed all response formats. add() and get_all() now return a dict with a 'results' key, not a flat list. Code iterating directly over the return value breaks with TypeError.
  Fix: Access results via memory.add(...)["results"] and memory.get_all(...)["results"].
• breaking output_format='v1.0' is removed server-side. Passing it raises DeprecationWarning then 400 Bad Request from the platform API.
  Fix: Remove all output_format parameters. v1.1 format is now the only format.
• gotcha Package name is mem0ai but import name is mem0. pip install mem0ai, then from mem0 import Memory.
  Fix: pip install mem0ai && from mem0 import Memory
• gotcha MemoryClient.add() defaults to async_mode=True in v1.0+. Calling search() immediately after add() may return empty results as memory has not yet been stored.
  Fix: Pass async_mode=False to block until memory is stored before querying.
• gotcha OSS Memory() with no config calls OpenAI by default. Fails with AuthenticationError if OPENAI_API_KEY is not set.
  Fix: Set OPENAI_API_KEY or pass a config dict to Memory() specifying an alternative LLM provider.
• gotcha Graph memory features require pip install mem0ai[graph]. Importing graph-related classes without this extra raises ImportError.
  Fix: pip install mem0ai[graph]
• breaking Installation fails when building 'psycopg2' from source due to 'pg_config executable not found'. This typically occurs in environments like Alpine Linux that lack PostgreSQL development headers, which are required to compile psycopg2.
  Fix: Ensure PostgreSQL development headers are installed in the environment (e.g., `apk add postgresql-dev` on Alpine Linux) or, if possible, use `psycopg2-binary` instead of `psycopg2` to avoid building from source.

Install

• pip install mem0ai Python (core)
• pip install mem0ai[graph] Python (with graph memory support)

Imports

• Memory
  wrong:

  from mem0ai import Memory

  correct:

  from mem0 import Memory

  Package is mem0ai but module is mem0. Common codegen error.
• MemoryClient
  wrong:

  from mem0 import Memory

  correct:

  from mem0 import MemoryClient

  MemoryClient is for the managed platform (needs MEM0_API_KEY). Memory is for OSS self-hosted. They are not interchangeable.

Quickstart

OSS self-hosted usage with Memory class. For platform usage, replace Memory() with MemoryClient(api_key=...).

from mem0 import Memory

memory = Memory()  # requires OPENAI_API_KEY by default

memory.add(
    [{"role": "user", "content": "I like basketball."}],
    user_id="alice"
)

results = memory.search(query="sports", user_id="alice", limit=3)
for r in results["results"]:
    print(r["memory"])