## Installation

Install the required dependencies:

```bash
pip install mem0ai qdrant-client openai ollama
```

Then start Qdrant and pull the Ollama models:

```bash
docker run -d -p 6333:6333 qdrant/qdrant
ollama pull llama3.1:latest
ollama pull nomic-embed-text:latest
```

<Note>You can swap `nomic-embed-text` for any Ollama-supported embedding model (e.g., `snowflake-arctic-embed`, `mxbai-embed-large`). Just update the `model` in the `embedder` config and set `embedding_model_dims` in the Qdrant config to match the model's output dimensions (768 for `nomic-embed-text`).</Note>

# Call LLM with memory context
response = openai_client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": f"You're Ray, a running coach. Memories:\\n{context}"},
        {"role": "user", "content": user_input}
    ]
).choices[0].message.content

# Store the exchange
mem0_client.add([
    {"role": "user", "content": user_input},
    {"role": "assistant", "content": response}
], user_id=user_id)

return response

  </Tab>
  <Tab title="Open Source">
```python
from openai import OpenAI
from mem0 import Memory

OLLAMA_URL = "http://localhost:11434"
CHAT_MODEL = "llama3.1:latest"

memory = Memory.from_config({
    "vector_store": {
        "provider": "qdrant",
        "config": {
            "collection_name": "fitness_companion",
            "host": "localhost",
            "port": 6333,
            "embedding_model_dims": 768,
        },
    },
    "llm": {
        "provider": "ollama",
        "config": {
            "model": CHAT_MODEL,
            "temperature": 0,
            "max_tokens": 2000,
            "ollama_base_url": OLLAMA_URL,
        },
    },
    "embedder": {
        "provider": "ollama",
        "config": {
            "model": "nomic-embed-text:latest",
            "ollama_base_url": OLLAMA_URL,
        },
    },
})

ollama_chat = OpenAI(base_url=f"{OLLAMA_URL}/v1", api_key="ollama")

def chat(user_input, user_id):
    # Retrieve relevant memories
    memories = memory.search(user_input, filters={"user_id": user_id}, top_k=5)
    context = "\n".join(m["memory"] for m in memories["results"])

    # Call LLM with memory context (Ollama via OpenAI-compatible API)
    response = ollama_chat.chat.completions.create(
        model=CHAT_MODEL,
        messages=[
            {"role": "system", "content": f"You're Ray, a running coach. Memories:\n{context}"},
            {"role": "user", "content": user_input},
        ],
    ).choices[0].message.content

    # Store the exchange
    memory.add(
        [
            {"role": "user", "content": user_input},
            {"role": "assistant", "content": response},
        ],
        user_id=user_id,
    )

    return response

chat("I want to run a marathon in under 4 hours", user_id="max")
# Output: "That's a solid goal. What's your current weekly mileage?"
# Stored in Mem0: "Max wants to run sub-4 marathon"

chat("What should I focus on today?", user_id="max")
# Output: "Based on your sub-4 marathon goal, let's work on building your aerobic base..."

mem0_client.project.update(custom_categories=[
    {"goals": "Race targets and training objectives"},
    {"constraints": "Injuries, limitations, recovery needs"},
    {"preferences": "Training style, surfaces, schedules"}
])

# Add goal - Mem0 automatically tags it as "goals"
mem0_client.add(
    [{"role": "user", "content": "Sub-4 marathon is my A-race"}],
    user_id="max"
)

# Add constraint - Mem0 automatically tags it as "constraints"
mem0_client.add(
    [{"role": "user", "content": "My right knee flares up on downhills"}],
    user_id="max"
)

# Force tag using metadata (not categories)
mem0_client.add(
    [{"role": "user", "content": "Some workout note"}],
    user_id="max",
    metadata={"workout_type": "speed", "forced_tag": "custom_label"}
)

# Add goal
memory.add(
    [{"role": "user", "content": "Sub-4 marathon is my A-race"}],
    user_id="max",
    metadata={"memory_bucket": "goals"},
)

# Add constraint
memory.add(
    [{"role": "user", "content": "My right knee flares up on downhills"}],
    user_id="max",
    metadata={"memory_bucket": "constraints"},
)

# Force tag using metadata
memory.add(
    [{"role": "user", "content": "Some workout note"}],
    user_id="max",
    metadata={"memory_bucket": "goals", "workout_type": "speed", "forced_tag": "custom_label"},
)

mem0_client.project.update(custom_instructions="""
Extract from running coach conversations:
- Training goals and race targets
- Physical constraints or injuries
- Training preferences (time of day, surfaces, weather)
- Progress milestones

Exclude:
- Greetings and filler
- Casual chatter
- Hypotheticals unless planning related
""")

MEMORY_CONFIG["custom_instructions"] = """
Extract from running coach conversations:
- Training goals and race targets
- Physical constraints or injuries
- Training preferences (time of day, surfaces, weather)
- Progress milestones

Exclude:
- Greetings and filler
- Casual chatter
- Hypotheticals unless planning related

Return JSON with key "facts" as a list of strings (use [] if nothing to store).
"""

memory = Memory.from_config(MEMORY_CONFIG)

  </Tab>
  <Tab title="Open Source">
```python
chat("hey how's it going", user_id="max")
chat("I prefer trail running over roads", user_id="max")

memories = memory.get_all(filters={"user_id": "max"})
print([m["memory"] for m in memories["results"]])
# Output: ["Max wants to run marathon under 4 hours", "Max prefers trail running over roads"]

  </Tab>
  <Tab title="Open Source">
```python
# Get coach personality
agent_memories = memory.search("coaching style", filters={"agent_id": "ray_coach"})
# Output: ["Max wants direct, data-driven feedback. Skip motivational language."]

# Store conversations with agent_id
memory.add(
    [
        {"role": "user", "content": "How'd my run look today?"},
        {"role": "assistant", "content": "Pace was 8:15/mile. Heart rate 152, zone 2."},
    ],
    user_id="max",
    agent_id="ray_coach",
)

  </Tab>
  <Tab title="Open Source">
```python
# Store only meaningful exchanges in Mem0
memory.add(
    [
        {"role": "user", "content": "I want to run a marathon"},
        {"role": "assistant", "content": "Let's build a training plan"},
    ],
    user_id="max",
)

# Skip storing filler
# "hey" → don't store
# "cool thanks" → don't store

# Or rely on custom_instructions to filter automatically

Store `expires_on` in metadata and periodically clean up expired memories. Ray stops asking about the ankle once it's removed.
  </Tab>
  <Tab title="Open Source">
```python
from datetime import datetime, timedelta

expiration = (datetime.now() + timedelta(days=14)).strftime("%Y-%m-%d")

memory.add(
    [{"role": "user", "content": "Rolled my left ankle, needs rest"}],
    user_id="max",
    metadata={"memory_bucket": "constraints", "expires_on": expiration},
)

  </Tab>
  <Tab title="Open Source">
```python
from mem0 import Memory
from datetime import datetime, timedelta

MEMORY_CONFIG = {
    "vector_store": {
        "provider": "qdrant",
        "config": {
            "collection_name": "fitness_companion",
            "host": "localhost",
            "port": 6333,
            "embedding_model_dims": 768,
        },
    },
    "llm": {
        "provider": "ollama",
        "config": {
            "model": "llama3.1:latest",
            "temperature": 0,
            "max_tokens": 2000,
            "ollama_base_url": "http://localhost:11434",
        },
    },
    "embedder": {
        "provider": "ollama",
        "config": {
            "model": "nomic-embed-text:latest",
            "ollama_base_url": "http://localhost:11434",
        },
    },
    "custom_instructions": """
    Extract: goals, constraints, preferences, progress
    Exclude: greetings, filler, casual chat
    Return JSON with key "facts" as a list of strings.
    """,
}

memory = Memory.from_config(MEMORY_CONFIG)

  </Tab>
  <Tab title="Open Source">
```python
memory.add(
    [
        {"role": "user", "content": "I want to run a sub-4 marathon"},
        {"role": "assistant", "content": "Got it. Let's build a training plan."},
    ],
    user_id="max",
    agent_id="ray",
    metadata={"memory_bucket": "goals"},
)

memory.add(
    [{"role": "user", "content": "I prefer trail running over roads"}],
    user_id="max",
    metadata={"memory_bucket": "preferences"},
)

  </Tab>
  <Tab title="Open Source">
```python
memory.add(messages, user_id="max", run_id="boston-2025")
memory.add(messages, user_id="max", run_id="nyc-2025")

# Retrieve only Boston memories
boston_memories = memory.search(
    "training plan",
    user_id="max",
    run_id="boston-2025",
)

  </Tab>
  <Tab title="Open Source">
```python
old_logs = [
    [{"role": "user", "content": "Completed 20-mile long run"}],
    [{"role": "user", "content": "Hit 8:00 pace on tempo run"}],
]

for log in old_logs:
    memory.add(log, user_id="max")

  </Tab>
  <Tab title="Open Source">
```python
# Find the old memory
memories = memory.get_all(filters={"user_id": "max"})
goal_memory = [m for m in memories["results"] if "sub-4" in m["memory"]][0]

# Update it
memory.update(goal_memory["id"], "Max wants to run sub-3:45 marathon")

  </Tab>
</Tabs>

### Metadata Tagging

Tag workouts by type:

<Tabs>
  <Tab title="Platform">
```python
mem0_client.add(
    [{"role": "user", "content": "10x400m intervals"}],
    user_id="max",
    metadata={"workout_type": "speed", "intensity": "high"}
)

# Later, find all speed workouts
speed_sessions = mem0_client.search(
    "speed work",
    user_id="max",
    filters={"metadata": {"workout_type": "speed"}}
)

  </Tab>
</Tabs>

### Pruning Old Memories

Delete irrelevant memories:

<Tabs>
  <Tab title="Platform">
```python
mem0_client.delete(memory_id="mem_xyz")

# Or clear an entire run_id
mem0_client.delete_all(user_id="max", run_id="old-training-cycle")

  </Tab>
</Tabs>

---

## What You Built

A companion that:

- **Persists across sessions** - Mem0 storage
- **Filters noise** - custom instructions
- **Organizes by type** - categories
- **Adapts personality** - **`agent_id`**
- **Stays fast** - short-term buffer
- **Handles temporal facts** - expiration
- **Scales to production** - batching, metadata, pruning

This pattern works for any companion: fitness coaches, tutors, roleplay characters, therapy bots, creative writing partners.

---

<Tip>
Start with 2-3 categories max (e.g., goals, constraints, preferences). More categories dilute tagging accuracy. You can always add more later after seeing what Mem0 extracts.
</Tip>

---

## Production Checklist

Before launching:

- Set custom instructions for your domain
- Define 2-3 categories (goals, constraints, preferences)
- Add expiration strategy for time-bound facts
- Implement error handling for API calls
- Monitor memory quality (Mem0 dashboard or `get_all` / Qdrant when local)
- Clear test data from production project

---

<CardGroup cols={2}>
  <Card title="Partition Memories by Entity" icon="layers" href="/cookbooks/essentials/entity-partitioning-playbook">
    Keep companions from leaking context by combining user, agent, and session scopes.
  </Card>
  <Card title="Tag Support Memories" icon="tag" href="/cookbooks/essentials/tagging-and-organizing-memories">
    Organize customer context to keep assistants responsive at scale.
  </Card>
</CardGroup>