Debugging Mem0 When Memories Aren't Returned: Essential Tools and Techniques

Enable Python debug logging and telemetry to trace why Mem0 queries return empty results by inspecting filter construction, vector store operations, and metadata validation in real time.

Mem0 is an open-source memory layer for AI applications. When memory.get() or memory.get_all() calls fail to retrieve expected records, the codebase provides specific debugging mechanisms to diagnose filter mismatches, vector store connectivity issues, and metadata validation errors. This guide covers the primary debugging tools available in the mem0ai/mem0 repository.

Python Debug Logging

The most immediate way to diagnose missing memories is to enable Python's built-in logging at the DEBUG level. This exposes the step-by-step execution flow through the core memory pipeline and vector-store adapters.

Core Memory Pipeline Logging

In mem0/memory/main.py, the Memory class uses module-level loggers to trace filter building, LLM calls, and storage actions. When debug logging is active, you'll see output tracing the construction of effective_query_filters and any validation errors that occur during _build_filters_and_metadata.

import logging

# Enable global debug logging

logging.basicConfig(level=logging.DEBUG)

# Or target Mem0 specifically

logging.getLogger("mem0").setLevel(logging.DEBUG)

Vector Store Adapter Logging

Each vector-store implementation (Qdrant, Pinecone, Valkey, etc.) maintains its own logger instance. For example, in mem0/vector_stores/qdrant.py (lines 91-119), debug statements trace collection creation, vector insertion, and search operations with exact filter payloads.

DEBUG:mem0.vector_stores.qdrant:Collection mem0_collection already exists. Skipping creation.
DEBUG:mem0.vector_stores.qdrant:Starting search
DEBUG:mem0.vector_stores.qdrant:Limit: 10, Filters: {'user_id': 'U123'}

Telemetry and Event Tracking

Mem0 includes an anonymous telemetry system that captures high-level operation metadata without exposing sensitive data. This helps verify that filter parameters are reaching the backend correctly.

AnonymousTelemetry Implementation

The telemetry client lives in mem0/memory/telemetry.py and creates a PostHog instance when MEM0_TELEMETRY=True (the default). It captures events for mem0.init, mem0.add, mem0.get, and mem0.get_all, including the collection name, vector dimensions, and filter keys.

Enable telemetry explicitly via environment variable:

export MEM0_TELEMETRY=True

Or in Python:

import os
os.environ["MEM0_TELEMETRY"] = "True"

Inspecting Filter Keys with process_telemetry_filters

To verify exactly which filter fields are being transmitted, use the process_telemetry_filters helper in mem0/memory/utils.py (lines 41-56). This function converts your filter dictionary into a list of keys and MD5-hashed IDs, allowing you to confirm that user_id, agent_id, or run_id are correctly formed.

from mem0.memory.utils import process_telemetry_filters

filters = {"user_id": "U123", "agent_id": "A456", "run_id": "R789"}
keys, encoded = process_telemetry_filters(filters)

print("Filter keys sent to telemetry:", keys)

# Output: ['user_id', 'agent_id', 'run_id']

print("Encoded IDs:", encoded)

# Output: {'user_id': '<md5_hash>', 'agent_id': '<md5_hash>', 'run_id': '<md5_hash>'}

Filter Validation and Construction

Most empty-result issues stem from filter construction errors. Mem0 validates filters through specific helper methods that raise explicit errors when constraints are violated.

_build_filters_and_metadata Validation

Located in mem0/memory/main.py (lines 87-120), the _build_filters_and_metadata method enforces that at least one of user_id, agent_id, or run_id is present. It also resolves optional actor_id fields. If validation fails, it raises a Mem0ValidationError with a descriptive message indicating which required identifiers are missing.

Common validation errors include:

• Missing all session identifiers (no user_id, agent_id, or run_id)
• Mismatched actor_id resolution when using agent-specific queries

Debugging Filter Mismatches

When memories exist but aren't returned, verify that the filter keys used in your query match those used during insertion. The process_telemetry_filters output reveals exactly which keys are being transmitted. A typo such as runid instead of run_id will silently return empty results because the vector store query includes an unrecognized filter field.

Vector Store Specific Debugging

Each vector-store backend in Mem0 includes implementation-specific logging that reveals connection issues, collection mismatches, and query parameters.

Qdrant Debug Output Example

In mem0/vector_stores/qdrant.py (lines 91-119), the Qdrant adapter logs:

• Collection existence checks during initialization
• Search operation starts with limit and filter details
• Vector insertion and deletion confirmations

When debugging Qdrant specifically, look for log lines indicating:

• Collection name mismatches: If mem0_collection differs from your expected name
• Filter serialization: How the filters dict converts to Qdrant's query format
• Connection errors: Network timeouts or authentication failures when contacting the Qdrant server

Other vector stores (Pinecone, Valkey, Chroma, etc.) follow the same pattern in their respective mem0/vector_stores/{name}.py files.

Test Harnesses for Local Verification

The Mem0 repository includes comprehensive unit tests that exercise the telemetry and filter logic, allowing you to verify expected behavior locally.

Running Telemetry Tests

The mem0/tests/test_telemetry.py file validates that:

• Telemetry is completely disabled when MEM0_TELEMETRY=False (no PostHog threads spawned)
• The AnonymousTelemetry class correctly instantiates when enabled
• Event capture includes the expected payload structure

Run these tests to confirm your environment handles telemetry correctly:

pytest -vv mem0/tests/test_telemetry.py

Vector Store Test Suites

Each vector store has dedicated tests in mem0/tests/vector_stores/test_*.py. For example, test_qdrant.py mocks the Qdrant client to verify that filters are passed correctly to the search method. Running these tests can reveal if your specific filter structure is compatible with the vector store's query format:

pytest -vv mem0/tests/vector_stores/test_qdrant.py

Summary

• Enable Python debug logging to trace the full execution path through mem0/memory/main.py and vector-store adapters like mem0/vector_stores/qdrant.py.
• Activate telemetry via MEM0_TELEMETRY=True to capture high-level operation metadata and verify filter keys are correctly transmitted using process_telemetry_filters.
• Validate filter construction by checking _build_filters_and_metadata for required identifiers (user_id, agent_id, or run_id) and watching for Mem0ValidationError.
• Inspect vector-store logs for collection name mismatches, connection errors, and filter serialization details specific to your backend (Qdrant, Pinecone, etc.).
• Run unit tests locally using pytest on test_telemetry.py and vector-store test suites to verify expected behavior and isolate environment-specific issues.

Frequently Asked Questions

How do I enable debug logging for Mem0 to see why my query returns no results?

Set the Python logging level to DEBUG for the mem0 logger. This exposes detailed output from mem0/memory/main.py showing filter construction, LLM calls, and storage actions, plus vector-store specific logs from files like mem0/vector_stores/qdrant.py revealing collection operations and search parameters.

What is the Mem0 telemetry system and how does it help with debugging?

Mem0 includes an AnonymousTelemetry class in mem0/memory/telemetry.py that captures high-level events (mem0.get, mem0.add, etc.) via PostHog when MEM0_TELEMETRY=True. It records filter keys and vector dimensions without exposing sensitive values, allowing you to verify that parameters like user_id and agent_id are reaching the backend correctly.

Why does my Mem0 query return empty results even though I added memories earlier?

The most common cause is filter mismatch or missing session identifiers. The _build_filters_and_metadata method in mem0/memory/main.py requires at least one of user_id, agent_id, or run_id. If these don't match between add() and get() calls, or if you have a typo like runid instead of run_id, the vector store query returns empty results. Use process_telemetry_filters to inspect exactly which keys are being transmitted.

How can I run Mem0's test suite to verify my debugging setup?

Run the telemetry tests with pytest -vv mem0/tests/test_telemetry.py to confirm that telemetry is correctly enabled or disabled based on environment variables. For vector-store specific issues, run the corresponding test file such as pytest -vv mem0/tests/vector_stores/test_qdrant.py. These tests validate that filters are correctly passed to the underlying storage backends and that the AnonymousTelemetry class behaves as expected.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}