Same agent Smaller bill. The tools and infrastructure to get more work from your AI. Fewer tokens. Less compute. Lower cost.
TypeScript agent-harnessagent-harness-engineeringai-engineeringai-observabilityamd-gpuclaude-codeclickhousecodexcoding-agentcoding-agentscursorgenaigpu-monitoringllm-observabilityllmopsnvidia-smiobservabilityopen-sourceopenaiopentelemetry
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.mdnew file mode 100644index 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.pynew file mode 100644index 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.txtnew file mode 100644index 00000000..79689493--- /dev/null+++ b/examples/mem0-agent-app/requirements.txt@@ -0,0 +1,3 @@+openlit>=1.0.0+mem0ai>=0.1.32+ollamadiff --git a/sdk/python/src/openlit/instrumentation/mem0/__init__.py b/sdk/python/src/openlit/instrumentation/mem0/__init__.pyindex 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 Collectiondiff --git a/sdk/python/src/openlit/instrumentation/mem0/utils.py b/sdk/python/src/openlit/instrumentation/mem0/utils.pyindex 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