Skip to content

Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.

docs(examples): add mem0 agent memory tracing example (#1374)

FBISiriefbd2a0b9c34
diff --git a/examples/mem0-agent-app/README.md b/examples/mem0-agent-app/README.md
new file mode 100644
index 00000000..ba46795a
--- /dev/null
+++ b/examples/mem0-agent-app/README.md
@@ -0,0 +1,85 @@
+# mem0 Agent Memory Tracing with OpenLIT
+
+This example demonstrates how [OpenLIT](https://openlit.io) automatically
+instruments [mem0](https://mem0.ai) memory operations and exports them as
+[OpenTelemetry](https://opentelemetry.io) spans — giving you full visibility
+into the memory read/write patterns of your LLM agents.
+
+Agent memory is a growing observability need: when an agent adds, searches,
+and prunes memories, you want those operations to show up in your traces right
+alongside your LLM spans. OpenLIT's mem0 instrumentation does this
+automatically — no manual span creation required.
+
+## What this example demonstrates
+
+The [`app.py`](./app.py) script exercises the core `mem0` memory operations,
+each of which is captured as its own span by OpenLIT:
+
+| mem0 call | Span name | What it captures |
+| -------------------- | ------------------- | ---------------------------------------------------- |
+| `Memory.add()` | `memory add` | user id, input message count, (optional) raw input |
+| `Memory.search()` | `memory search` | search query, limit, threshold, result count |
+| `Memory.get_all()` | `memory get_all` | user id, number of memories returned |
+| `Memory.delete()` | `memory delete` | deleted memory id |
+
+## Prerequisites
+
+- Python 3.10+ (required by mem0)
+- An OpenTelemetry-compatible backend listening on `http://localhost:4318`
+ (for example, the [OpenLIT docker-compose stack](https://docs.openlit.io/latest/quickstart)).
+- A model backend for mem0. By default this example uses a local
+ [Ollama](https://ollama.com) server so it runs **without any hosted API keys**:
+
+ ```bash
+ ollama pull llama3.1
+ ollama pull nomic-embed-text
+ ```
+
+ The default Ollama path requires the `ollama` Python package (listed in
+ `requirements.txt`), which is installed by the `pip install` step below.
+
+ Alternatively, set `MEM0_USE_DEFAULT=1` to use mem0's default OpenAI-backed
+ configuration, in which case you must export `OPENAI_API_KEY`.
+
+## Install
+
+```bash
+pip install -r requirements.txt
+```
+
+## Run
+
+```bash
+python app.py
+```
+
+The script prints each memory operation as it runs and then flushes the spans
+to your OTLP endpoint.
+
+## Expected OpenTelemetry attributes
+
+Every mem0 span emitted by OpenLIT includes a common set of GenAI semantic
+convention attributes, for example:
+
+- `gen_ai.provider.name = mem0`
+- `gen_ai.operation.name = memory` (user-facing memory operations)
+- `gen_ai.user.id = alex-demo`
+- `service.name = mem0-agent-demo`
+- `deployment.environment = development`
+
+Operation-specific attributes are added on top, such as:
+
+- `gen_ai.memory.count` on `memory add`
+- `gen_ai.memory.search.query`, `gen_ai.memory.search.limit` on `memory search`
+- `gen_ai.memory.operation.result_count` on `memory search` / `memory get_all`
+- `db.delete.id` on `memory delete`
+
+If content capture is enabled in `openlit.init(...)`, the raw input messages
+(`gen_ai.input.messages`) and search results (`gen_ai.output.messages`) are
+captured as well.
+
+## Learn more
+
+- [OpenLIT documentation](https://docs.openlit.io)
+- [OpenLIT mem0 integration](https://docs.openlit.io/latest/sdk/integrations/mem0)
+- [mem0 documentation](https://docs.mem0.ai)
diff --git a/examples/mem0-agent-app/app.py b/examples/mem0-agent-app/app.py
new file mode 100644
index 00000000..adbe5816
--- /dev/null
+++ b/examples/mem0-agent-app/app.py
@@ -0,0 +1,209 @@
+"""mem0 + OpenLIT memory tracing example.
+
+This self-contained script demonstrates how `openlit` automatically
+instruments `mem0` memory operations and exports them as OpenTelemetry
+spans with rich GenAI semantic-convention attributes.
+
+The following memory operations are exercised, each of which is captured
+as its own span by the openlit mem0 instrumentation:
+
+ * ``Memory.add()`` -> span ``memory add``
+ * ``Memory.search()`` -> span ``memory search``
+ * ``Memory.get_all()`` -> span ``memory get_all``
+ * ``Memory.delete()`` -> span ``memory delete``
+
+Every span records provider/system attributes such as
+``gen_ai.provider.name = mem0`` and ``gen_ai.operation.name = memory``, plus
+operation-specific attributes (search query/limit, memory counts, result
+counts, user id, and so on).
+
+By default the example uses a local `Ollama <https://ollama.com>`_
+configuration so it can run without any hosted API keys. If ``mem0`` is
+configured to use a hosted LLM/embedder provider instead, set the matching
+API key via environment variables (for example ``OPENAI_API_KEY``) before
+running.
+
+Run with::
+
+ pip install -r requirements.txt
+ python app.py
+"""
+
+import os
+import sys
+
+import openlit
+
+# Initialize OpenLIT before importing/using mem0 so that the mem0
+# instrumentation is applied to the Memory class. The OTLP endpoint points
+# at a local OpenTelemetry collector (for example the openlit docker-compose
+# stack listening on port 4318).
+openlit.init(
+ otlp_endpoint="http://localhost:4318",
+ application_name="mem0-agent-demo",
+ environment=os.environ.get("OTEL_ENVIRONMENT", "development"),
+)
+
+# mem0 is imported after openlit.init() so instrumentation is in place.
+from mem0 import Memory # noqa: E402 pylint: disable=wrong-import-position
+
+
+# A fictional user we will attach memories to.
+USER_ID = "alex-demo"
+
+
+def build_memory():
+ """Create a mem0 ``Memory`` instance.
+
+ Uses a local Ollama-backed configuration so the example runs without any
+ hosted API keys. Ollama must be running locally with the referenced
+ models pulled (``ollama pull llama3.1`` and ``ollama pull nomic-embed-text``).
+
+ Set ``MEM0_USE_DEFAULT=1`` to fall back to mem0's default configuration,
+ which uses OpenAI and therefore requires ``OPENAI_API_KEY`` to be set.
+
+ Returns:
+ A configured ``mem0.Memory`` instance.
+ """
+ if os.getenv("MEM0_USE_DEFAULT"):
+ # Default mem0 config: OpenAI LLM + embedder (needs OPENAI_API_KEY).
+ return Memory()
+
+ config = {
+ "llm": {
+ "provider": "ollama",
+ "config": {
+ "model": "llama3.1:latest",
+ "temperature": 0,
+ "ollama_base_url": os.getenv(
+ "OLLAMA_BASE_URL", "http://localhost:11434"
+ ),
+ },
+ },
+ "embedder": {
+ "provider": "ollama",
+ "config": {
+ "model": "nomic-embed-text:latest",
+ "ollama_base_url": os.getenv(
+ "OLLAMA_BASE_URL", "http://localhost:11434"
+ ),
+ },
+ },
+ }
+ return Memory.from_config(config)
+
+
+def add_memories(memory):
+ """Add a few memories about the fictional user.
+
+ Each ``Memory.add()`` call is traced as a ``memory add`` span. The span
+ captures ``gen_ai.user.id``, the number of input messages
+ (``gen_ai.memory.count``), and — when content capture is enabled — the
+ raw input messages.
+
+ Args:
+ memory: The ``mem0.Memory`` instance to write to.
+ """
+ facts = [
+ "My name is Alex and I am a backend engineer.",
+ "I love hiking in the mountains on weekends.",
+ "I am allergic to peanuts.",
+ "I prefer dark roast coffee in the morning.",
+ ]
+ for fact in facts:
+ memory.add(fact, user_id=USER_ID)
+ print(f"[add] stored: {fact}")
+
+
+def search_memories(memory, query):
+ """Search stored memories with a natural-language query.
+
+ ``Memory.search()`` is traced as a ``memory search`` span, which records
+ ``gen_ai.memory.search.query``, ``gen_ai.memory.search.limit``, and the
+ number of results returned (``gen_ai.memory.operation.result_count``).
+
+ Args:
+ memory: The ``mem0.Memory`` instance to query.
+ query: The natural-language search query.
+
+ Returns:
+ The raw search results returned by mem0.
+ """
+ results = memory.search(query=query, filters={"user_id": USER_ID}, top_k=3)
+ print(f"[search] query={query!r} -> {results}")
+ return results
+
+
+def list_all_memories(memory):
+ """List every memory stored for the user.
+
+ ``Memory.get_all()`` is traced as a ``memory get_all`` span, recording
+ the user id and the total number of memories returned.
+
+ Args:
+ memory: The ``mem0.Memory`` instance to read from.
+
+ Returns:
+ All memories stored for :data:`USER_ID`.
+ """
+ all_memories = memory.get_all(filters={"user_id": USER_ID})
+ print(f"[get_all] {all_memories}")
+ return all_memories
+
+
+def delete_all_memories(memory, all_memories):
+ """Delete each stored memory by id.
+
+ Every ``Memory.delete()`` call is traced as a ``memory delete`` span,
+ which records the deleted memory id (``db.delete.id``).
+
+ Args:
+ memory: The ``mem0.Memory`` instance to delete from.
+ all_memories: The result of :func:`list_all_memories`, used to
+ extract memory ids.
+ """
+ results = all_memories.get("results", []) if isinstance(all_memories, dict) else []
+ for item in results:
+ memory_id = item.get("id")
+ if memory_id:
+ memory.delete(memory_id=memory_id)
+ print(f"[delete] removed memory id={memory_id}")
+
+
+def main():
+ """Run the end-to-end mem0 memory tracing demo.
+
+ Exercises add/search/get_all/delete so that a full span hierarchy is
+ exported to the configured OTLP endpoint.
+ """
+ try:
+ memory = build_memory()
+ except Exception as exc: # pragma: no cover - environment dependent
+ print(
+ "Failed to initialize mem0.Memory. Make sure a local Ollama server "
+ "is running (or set MEM0_USE_DEFAULT=1 with OPENAI_API_KEY).\n"
+ f"Underlying error: {exc}",
+ file=sys.stderr,
+ )
+ sys.exit(1)
+
+ print("== Adding memories ==")
+ add_memories(memory)
+
+ print("\n== Searching memories ==")
+ search_memories(memory, "What food is Alex allergic to?")
+
+ print("\n== Listing all memories ==")
+ all_memories = list_all_memories(memory)
+
+ print("\n== Deleting memories ==")
+ delete_all_memories(memory, all_memories)
+
+ print(
+ "\nDone. Check your OpenTelemetry backend for spans named "
+ "'memory add', 'memory search', 'memory get_all', and 'memory delete'."
+ )
+
+
+if __name__ == "__main__":
+ main()
diff --git a/examples/mem0-agent-app/requirements.txt b/examples/mem0-agent-app/requirements.txt
new file mode 100644
index 00000000..79689493
--- /dev/null
+++ b/examples/mem0-agent-app/requirements.txt
@@ -0,0 +1,3 @@
+openlit>=1.0.0
+mem0ai>=0.1.32
+ollama
diff --git a/sdk/python/src/openlit/instrumentation/mem0/__init__.py b/sdk/python/src/openlit/instrumentation/mem0/__init__.py
index b53e8d53..c289eddc 100644
--- a/sdk/python/src/openlit/instrumentation/mem0/__init__.py
+++ b/sdk/python/src/openlit/instrumentation/mem0/__init__.py
@@ -1,6 +1,20 @@
# pylint: disable=useless-return, bad-staticmethod-argument, disable=duplicate-code
"""
Optimized Auto Instrumentation of mem0 Functions following OpenLIT Framework Guide.
+
+This module wraps mem0's ``Memory`` and ``AsyncMemory`` methods so that each
+memory operation is captured as an OpenTelemetry span. The two module-level
+constants drive that wrapping:
+
+- ``SYNC_METHODS``: configuration entries for the synchronous ``Memory`` API
+ (and its internal ``mem0.memory.main`` helpers). Each entry maps a
+ ``package``/``object`` to a human-readable span ``endpoint`` name and a
+ ``priority`` hint.
+- ``ASYNC_METHODS``: the equivalent configuration for the asynchronous
+ ``AsyncMemory`` API.
+
+At instrumentation time each entry is passed to ``wrap_function_wrapper`` so
+the matching method is patched with the appropriate sync/async wrapper.
"""
from typing import Collection
diff --git a/sdk/python/src/openlit/instrumentation/mem0/utils.py b/sdk/python/src/openlit/instrumentation/mem0/utils.py
index 88b33b20..ec20370e 100644
--- a/sdk/python/src/openlit/instrumentation/mem0/utils.py
+++ b/sdk/python/src/openlit/instrumentation/mem0/utils.py
@@ -213,7 +213,23 @@ def set_mem0_span_attributes(
def _set_operation_attributes(span, operation_name: str, ctx: Mem0Context):
- """Set operation-specific attributes efficiently."""
+ """Set operation-specific span attributes based on the mem0 operation.
+
+ Inspects ``operation_name`` and adds attributes that are only meaningful
+ for a given operation:
+
+ - add: ``gen_ai.memory.infer`` (when provided) and
+ ``gen_ai.memory.count`` (number of input messages).
+ - search: ``gen_ai.memory.search.query``, ``gen_ai.memory.search.limit``,
+ and ``gen_ai.memory.search.threshold`` when present in the call kwargs.
+ - update / delete / get: the target memory id under the corresponding
+ ``db.*.id`` attribute.
+
+ Args:
+ span: The OpenTelemetry span to annotate.
+ operation_name: The mem0 operation/endpoint name (e.g. ``memory add``).
+ ctx: The :class:`Mem0Context` carrying the call args/kwargs.
+ """
if "add" in operation_name:
if "infer" in ctx.kwargs:
span.set_attribute(
@@ -257,7 +273,18 @@ def _set_operation_attributes(span, operation_name: str, ctx: Mem0Context):
def _set_response_attributes(span, response: Any):
- """Set response attributes for business intelligence."""
+ """Record result-count attributes derived from a mem0 response.
+
+ Normalizes the various response shapes mem0 can return (list/tuple, a
+ dict with a ``results`` key, or a scalar) into a single result count and
+ sets ``gen_ai.memory.operation.result_count`` and ``gen_ai.data.sources``.
+ A falsy response is ignored, and any error while measuring is swallowed so
+ instrumentation never breaks the wrapped call.
+
+ Args:
+ span: The OpenTelemetry span to annotate.
+ response: The value returned by the wrapped mem0 method.
+ """
if not response:
return
@@ -280,7 +307,21 @@ def _set_response_attributes(span, response: Any):
def set_mem0_content_attributes(
span, operation_name: str, ctx: Mem0Context, response: Any, capture_content: bool
):
- """Set content attributes if enabled."""
+ """Capture raw input/output content on the span when enabled.
+
+ When ``capture_content`` is true, records the memory operation's payload as
+ span attributes: input messages (``gen_ai.input.messages``) for ``add``
+ operations and search results (``gen_ai.output.messages``) for ``search``
+ operations. Content is JSON-encoded when possible, otherwise stringified.
+ Does nothing when content capture is disabled, and never raises.
+
+ Args:
+ span: The OpenTelemetry span to annotate.
+ operation_name: The mem0 operation/endpoint name (e.g. ``memory add``).
+ ctx: The :class:`Mem0Context` carrying the input messages.
+ response: The value returned by the wrapped mem0 method.
+ capture_content: When ``False``, this function is a no-op.
+ """
if not capture_content:
return