docs: fold contextual-add into the Add concept page and redirect (#6286)

2026-07-14 20:02:47 +05:30
parent 42cf18c4e6
commit 6c1741e3a4
4 changed files with 48 additions and 253 deletions
@@ -83,6 +83,50 @@ await client.add(messages, {
  Expect a `status: "PENDING"` response with an `event_id`. Poll `GET /v1/event/{event_id}/` to confirm completion.
 </Info>
 ### Automatic conversation context
 On the Platform, you only send new messages. Mem0 automatically pulls the earlier messages that share the same identifiers (`user_id`, and `run_id` if you use one) and uses them as context when extracting memories, so you never need to resend conversation history.
 This means a follow-up turn is understood against what came before it:
 <CodeGroup>
 ```python Python
 # First interaction
 client.add(
    [{"role": "user", "content": "My dog's name is Biscuit. He's a golden retriever."}],
    user_id="alice",
 )
 # Later — send only the new turn, no history
 client.add(
    [{"role": "user", "content": "He turned 5 today, and I'm taking him to the vet on Friday."}],
    user_id="alice",
 )
 # Stored as: "User's dog Biscuit turned 5" — "He" is resolved against the earlier turn.
 ```
 ```javascript JavaScript
 // First interaction
 await client.add(
  [{ role: "user", content: "My dog's name is Biscuit. He's a golden retriever." }],
  { userId: "alice" },
 );
 // Later — send only the new turn, no history
 await client.add(
  [{ role: "user", content: "He turned 5 today, and I'm taking him to the vet on Friday." }],
  { userId: "alice" },
 );
 // Stored as: "User's dog Biscuit turned 5" — "He" is resolved against the earlier turn.
 ```
 </CodeGroup>
 Without that earlier turn, the same message can only be stored as "User's male pet turned 5", because there is nothing to resolve "He" against. Scope each conversation with a consistent `user_id` (plus `run_id` for a distinct session) and Mem0 handles the rest.
 <Info>
  This is default behavior and needs no configuration. Earlier SDK versions gated it behind a `version="v2"` argument on `add`; that argument no longer exists and is ignored if sent.
 </Info>
 ## Add with Mem0 Open Source
 <CodeGroup>
@@ -85,7 +85,6 @@
                          "platform/features/advanced-retrieval",
                          "platform/advanced-memory-operations",
                          "platform/features/criteria-retrieval",
                          "platform/features/contextual-add",
                          "platform/features/custom-instructions",
                          "platform/features/memory-decay"
                        ]
@@ -609,6 +608,10 @@
    ]
  },
  "redirects": [
    {
      "source": "/platform/features/contextual-add",
      "destination": "/core-concepts/memory-operations/add"
    },
    {
      "source": "/changelog/openclaw",
      "destination": "/changelog/sdk"
@@ -206,7 +206,6 @@ If the user is on a pre-current major (Python < 2, TS < 3, or Platform `output_f
 - [Advanced Retrieval](https://docs.mem0.ai/platform/features/advanced-retrieval) [Platform]: Use when the user needs keyword search, reranking, or hybrid retrieval.
 - [Criteria-Based Retrieval](https://docs.mem0.ai/platform/features/criteria-retrieval) [Platform]: Use when targeting memories by custom criteria, not just semantic similarity.
 - [Temporal Reasoning](https://docs.mem0.ai/platform/features/temporal-reasoning) [Platform]: Use when time-aware searches like last week, upcoming, or right now need better result ordering.
 - [Contextual Add](https://docs.mem0.ai/platform/features/contextual-add) [Platform]: Use when `add()` should consider the surrounding conversation, not just the latest turn.
 - [Custom Instructions](https://docs.mem0.ai/platform/features/custom-instructions) [Platform]: Use when tailoring what Mem0 extracts and stores on Platform.
 - [Memory Decay](https://docs.mem0.ai/platform/features/memory-decay) [Platform]: Use when search results should boost recently-reinforced memories and dampen stale ones. Opt in per project; applies at search time and never filters candidates out.
 - [Advanced Memory Operations](https://docs.mem0.ai/platform/advanced-memory-operations) [Platform]: Use when basic CRUD is not enough - batch ops, complex filters, workflows.
@@ -1,251 +0,0 @@
 ---
 title: Contextual Memory Creation
 description: "Add messages with automatic context management - no manual history tracking required"
 ---
 ## What is Contextual Memory Creation?
 Contextual memory creation automatically manages message history, allowing you to focus on building AI experiences without manually tracking interactions. Simply send new messages, and Mem0 handles the context automatically.
 <CodeGroup>
 ```python Python
 # Just send new messages - Mem0 handles the context
 messages = [
    {"role": "user", "content": "I love Italian food, especially pasta"},
    {"role": "assistant", "content": "Great! I'll remember your preference for Italian cuisine."}
 ]
 client.add(messages, user_id="user123")
 ```
 ```javascript JavaScript
 // Just send new messages - Mem0 handles the context
 const messages = [
    {"role": "user", "content": "I love Italian food, especially pasta"},
    {"role": "assistant", "content": "Great! I'll remember your preference for Italian cuisine."}
 ];
 await client.add(messages, { userId: "user123" });
 ```
 </CodeGroup>
 ## Why Use Contextual Memory Creation?
 - **Simple**: Send only new messages, no manual history tracking
 - **Efficient**: Smaller payloads and faster processing
 - **Automatic**: Context management handled by Mem0
 - **Reliable**: No risk of missing interaction history
 - **Scalable**: Works seamlessly as your application grows
 ## How It Works
 ### Basic Usage
 <CodeGroup>
 ```python Python
 # First interaction
 messages1 = [
    {"role": "user", "content": "Hi, I'm Sarah from New York"},
    {"role": "assistant", "content": "Hello Sarah! Nice to meet you."}
 ]
 client.add(messages1, user_id="sarah")
 # Later interaction - just send new messages
 messages2 = [
    {"role": "user", "content": "I'm planning a trip to Italy next month"},
    {"role": "assistant", "content": "How exciting! Italy is beautiful this time of year."}
 ]
 client.add(messages2, user_id="sarah")
 # Mem0 automatically knows Sarah is from New York and can use this context
 ```
 ```javascript JavaScript
 // First interaction
 const messages1 = [
    {"role": "user", "content": "Hi, I'm Sarah from New York"},
    {"role": "assistant", "content": "Hello Sarah! Nice to meet you."}
 ];
 await client.add(messages1, { userId: "sarah" });
 // Later interaction - just send new messages
 const messages2 = [
    {"role": "user", "content": "I'm planning a trip to Italy next month"},
    {"role": "assistant", "content": "How exciting! Italy is beautiful this time of year."}
 ];
 await client.add(messages2, { userId: "sarah" });
 // Mem0 automatically knows Sarah is from New York and can use this context
 ```
 </CodeGroup>
 ## Organization Strategies
 Choose the right approach based on your application's needs:
 ### User-Level Memories (`user_id` only)
 **Best for:** Personal preferences, profile information, long-term user data
 <CodeGroup>
 ```python Python
 # Persistent user memories across all interactions
 messages = [
    {"role": "user", "content": "I'm allergic to nuts and dairy"},
    {"role": "assistant", "content": "I've noted your allergies for future reference."}
 ]
 client.add(messages, user_id="user123")
 # This allergy info will be available in ALL future interactions
 ```
 ```javascript JavaScript
 // Persistent user memories across all interactions
 const messages = [
    {"role": "user", "content": "I'm allergic to nuts and dairy"},
    {"role": "assistant", "content": "I've noted your allergies for future reference."}
 ];
 await client.add(messages, { userId: "user123" });
 // This allergy info will be available in ALL future interactions
 ```
 </CodeGroup>
 ### Session-Specific Memories (`user_id` + `run_id`)
 **Best for:** Task-specific context, separate interaction threads, project-based sessions
 <CodeGroup>
 ```python Python
 # Trip planning session
 messages1 = [
    {"role": "user", "content": "I want to plan a 5-day trip to Tokyo"},
    {"role": "assistant", "content": "Perfect! Let's plan your Tokyo adventure."}
 ]
 client.add(messages1, user_id="user123", run_id="tokyo-trip-2024")
 # Later in the same trip planning session
 messages2 = [
    {"role": "user", "content": "I prefer staying near Shibuya"},
    {"role": "assistant", "content": "Great choice! Shibuya is very convenient."}
 ]
 client.add(messages2, user_id="user123", run_id="tokyo-trip-2024")
 # Different session for work project (separate context)
 work_messages = [
    {"role": "user", "content": "Let's discuss the Q4 marketing strategy"},
    {"role": "assistant", "content": "Sure! What are your main goals for Q4?"}
 ]
 client.add(work_messages, user_id="user123", run_id="q4-marketing")
 ```
 ```javascript JavaScript
 // Trip planning session
 const messages1 = [
    {"role": "user", "content": "I want to plan a 5-day trip to Tokyo"},
    {"role": "assistant", "content": "Perfect! Let's plan your Tokyo adventure."}
 ];
 await client.add(messages1, { userId: "user123", runId: "tokyo-trip-2024" });
 // Later in the same trip planning session
 const messages2 = [
    {"role": "user", "content": "I prefer staying near Shibuya"},
    {"role": "assistant", "content": "Great choice! Shibuya is very convenient."}
 ];
 await client.add(messages2, { userId: "user123", runId: "tokyo-trip-2024" });
 // Different session for work project (separate context)
 const workMessages = [
    {"role": "user", "content": "Let's discuss the Q4 marketing strategy"},
    {"role": "assistant", "content": "Sure! What are your main goals for Q4?"}
 ];
 await client.add(workMessages, { userId: "user123", runId: "q4-marketing" });
 ```
 </CodeGroup>
 ## Real-World Use Cases
 <Tabs>
  <Tab title="Customer Support">
 ```python Python
 # Support ticket context - keeps interaction focused
 messages = [
    {"role": "user", "content": "My subscription isn't working"},
    {"role": "assistant", "content": "I can help with that. What specific issue are you experiencing?"},
    {"role": "user", "content": "I can't access premium features even though I paid"}
 ]
 # Each support ticket gets its own run_id
 client.add(messages, 
    user_id="customer123", 
    run_id="ticket-2024-001"
 )
 ```
  </Tab>
  <Tab title="Personal AI Assistant">
 ```python Python
 # Personal preferences (persistent across all interactions)
 preference_messages = [
    {"role": "user", "content": "I prefer morning workouts and vegetarian meals"},
    {"role": "assistant", "content": "Got it! I'll keep your fitness and dietary preferences in mind."}
 ]
 client.add(preference_messages, user_id="user456")
 # Daily planning session (session-specific)
 planning_messages = [
    {"role": "user", "content": "Help me plan tomorrow's schedule"},
    {"role": "assistant", "content": "Of course! I'll consider your morning workout preference."}
 ]
 client.add(planning_messages, 
    user_id="user456", 
    run_id="daily-plan-2024-01-15"
 )
 ```
  </Tab>
  <Tab title="Educational Platform">
 ```python Python
 # Student profile (persistent)
 profile_messages = [
    {"role": "user", "content": "I'm studying computer science and struggle with math"},
    {"role": "assistant", "content": "I'll tailor explanations to help with math concepts."}
 ]
 client.add(profile_messages, user_id="student789")
 # Specific lesson session
 lesson_messages = [
    {"role": "user", "content": "Can you explain algorithms?"},
    {"role": "assistant", "content": "Sure! I'll explain algorithms with math-friendly examples."}
 ]
 client.add(lesson_messages,
    user_id="student789",
    run_id="algorithms-lesson-1"
 )
 ```
  </Tab>
 </Tabs>
 ## Best Practices
 ### ✅ Do
 - **Organize by context scope**: Use `user_id` only for persistent data, add `run_id` for session-specific context
 - **Keep messages focused** on the current interaction
 - **Test with real interaction flows** to ensure context works as expected
 ### ❌ Don't
 - Send duplicate messages or interaction history
 - Skip identifiers like `user_id` or `run_id` that scope the memory
 - Mix contextual and non-contextual approaches in the same application
 ## Troubleshooting
 | Issue | Solution |
 |-------|----------|
 | **Context not working** | Ensure each call uses the same `user_id` / `run_id` combo; version is automatic |
 | **Wrong context retrieved** | Check if you need separate `run_id` values for different interaction topics |
 | **Missing interaction history** | Verify all messages in the interaction thread use the same `user_id` and `run_id` |
 | **Too much irrelevant context** | Use more specific `run_id` values to separate different interaction types |
 <Snippet file="get-help.mdx" />