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

> Troubleshoot Mem0 not returning memories with Python debug logging and telemetry. Inspect filters, vector store ops, and metadata in real time.

- Repository: [Mem0/mem0](https://github.com/mem0ai/mem0)
- Tags: debugging-guide
- Published: 2026-03-07

---

**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`](https://github.com/mem0ai/mem0/blob/main/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`.

```python
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`](https://github.com/mem0ai/mem0/blob/main/mem0/vector_stores/qdrant.py) (lines 91-119), debug statements trace collection creation, vector insertion, and search operations with exact filter payloads.

```text
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`](https://github.com/mem0ai/mem0/blob/main/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:

```bash
export MEM0_TELEMETRY=True

```

Or in Python:

```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`](https://github.com/mem0ai/mem0/blob/main/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.

```python
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`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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:

```bash
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`](https://github.com/mem0ai/mem0/blob/main/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:

```bash
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`](https://github.com/mem0ai/mem0/blob/main/mem0/memory/main.py) and vector-store adapters like [`mem0/vector_stores/qdrant.py`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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`](https://github.com/mem0ai/mem0/blob/main/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.