[docs] platform core concept revamp and overview update (#3664)

2025-10-26 15:15:13 +05:30
parent 61faf71064
commit 2c18355dd2
19 changed files with 595 additions and 318 deletions
@@ -5,43 +5,52 @@ icon: "plus"
 iconType: "solid"
 ---
 # How Mem0 Adds Memory
-## Overview
+Adding memory is how Mem0 captures useful details from a conversation so your agents can reuse them later. Think of it as saving the important sentences from a chat transcript into a structured notebook your agent can search.
-The `add` operation stores memory into Mem0. Whether you're working with a chatbot, a voice assistant, or a multi-agent system, this is the entry point to create long-term memory.
+<Info>
  **Why it matters**
  - Preserves user preferences, goals, and feedback across sessions.
  - Powers personalization and decision-making in downstream conversations.
  - Keeps context consistent between managed Platform and OSS deployments.
 </Info>
-Memories typically come from a **user-assistant interaction** and Mem0 handles the extraction, transformation, and storage for you.
+## Key terms
-Mem0 offers two implementation flows:
+- **Messages** – The ordered list of user/assistant turns you send to `add`.
 - **Infer** – Controls whether Mem0 extracts structured memories (`infer=True`, default) or stores raw messages.
 - **Metadata** – Optional filters (e.g., `{"category": "movie_recommendations"}`) that improve retrieval later.
 - **User / Session identifiers** – `user_id`, `session_id`, or `run_id` that scope the memory for future searches.
- **Mem0 Platform** (Managed, scalable, with dashboard + API)
+## How does it work?
 - **Mem0 Open Source** (Lightweight, fully local, flexible SDKs)
-Each supports the same core memory operations, but with slightly different setup.
+Mem0 offers two flows:
 - **Mem0 Platform** – Fully managed API with dashboard, scaling, and graph features.
 - **Mem0 Open Source** – Local SDK that you run in your own environment.
-## Architecture
+Both flows take the same payload and pass it through the same pipeline.
 <Frame caption="Architecture diagram illustrating the process of adding memories.">
  <img src="../../images/add_architecture.png" />
 </Frame>
-When you call `add`, Mem0 performs the following steps under the hood:
+<Steps>
 <Step title="Information extraction">
 Mem0 sends the messages through an LLM that pulls out key facts, decisions, or preferences to remember.
 </Step>
 <Step title="Conflict resolution">
 Existing memories are checked for duplicates or contradictions so the latest truth wins.
 </Step>
 <Step title="Storage">
 The resulting memories land in managed vector storage (and optional graph storage) so future searches return them quickly.
 </Step>
 </Steps>
-1. **Information Extraction**
+You trigger this pipeline with a single `add` call—no manual orchestration needed.
   The input messages are passed through an LLM that extracts key facts, decisions, preferences, or events worth remembering.
-2. **Conflict Resolution**
+## Add with Mem0 Platform
   Mem0 compares the new memory against existing ones to detect duplication or contradiction and handles updates accordingly.
 3. **Memory Storage**
   The result is stored in a vector database (for semantic search) and optionally in a graph structure (for relationship mapping).
 You don't need to handle any of this manually - Mem0 takes care of it with a single API call or SDK method.
 ---
 ## Example: Mem0 Platform
 <CodeGroup>
 ```python Python
@@ -79,9 +88,11 @@ await client.add({
 ```
 </CodeGroup>
---
+<Info icon="check">
  Expect a `memory_id` (or list of IDs) in the response. Check the Mem0 dashboard to confirm the new entry under the correct user.
 </Info>
-## Example: Mem0 Open Source
+## Add with Mem0 Open Source
 <CodeGroup>
 ```python Python
@@ -125,7 +136,9 @@ const result = memory.add(messages, {
 ```
 </CodeGroup>
---
+<Tip>
  Use `infer=False` only when you need to store raw transcripts. Most workflows benefit from Mem0 extracting structured memories automatically.
 </Tip>
 ## When Should You Add Memory?
@@ -145,9 +158,38 @@ Storing this context allows the agent to reason better in future interactions.
 For full list of supported fields, required formats, and advanced options, see the
 [Add Memory API Reference](/api-reference/memory/add-memories).
---
+## Managed vs OSS differences
-## Need help?
+| Capability | Mem0 Platform | Mem0 OSS |
-If you have any questions, please feel free to reach out to us using one of the following methods:
+| --- | --- | --- |
 | Conflict resolution | Automatic with dashboard visibility | SDK handles merges locally; you control storage |
 | Graph writes | Toggle per request (`enable_graph=True`) | Requires configuring a graph provider |
 | Rate limits | Managed quotas per workspace | Limited by your hardware and provider APIs |
 | Dashboard visibility | Yes — inspect memories visually | Inspect via CLI, logs, or custom UI |
-<Snippet file="get-help.mdx"/>
+## Put it into practice
 - Review the <Link href="/platform/advanced-memory-operations">Advanced Memory Operations</Link> guide to layer metadata, rerankers, and graph toggles.
 - Explore the <Link href="/api-reference/memory/add-memories">Add Memories API reference</Link> for every request/response field.
 ## See it live
 - <Link href="/examples/customer-support-agent">Customer Support Agent</Link> shows add + search powering a support flow.
 - <Link href="/examples/personal-ai-tutor">Personal AI Tutor</Link> uses add to personalize lesson plans.
 {/* DEBUG: verify CTA targets */}
 <CardGroup cols={2}>
  <Card
    title="Explore Search Concepts"
    description="See how stored memories feed retrieval in the Search guide."
    icon="search"
    href="/core-concepts/memory-operations/search"
  />
  <Card
    title="Build a Support Agent"
    description="Follow the cookbook to apply add/search/update in production."
    icon="rocket"
    href="/examples/customer-support-agent"
  />
 </CardGroup>
@@ -5,27 +5,39 @@ icon: "trash"
 iconType: "solid"
 ---
-## Overview
+# Remove Memories Safely
-Memories can become outdated, irrelevant, or need to be removed for privacy or compliance reasons. Mem0 offers flexible ways to delete memory:
+Deleting memories is how you honor compliance requests, undo bad data, or clean up expired sessions. Mem0 lets you delete a specific memory, a list of IDs, or everything that matches a filter.
-1. **Delete a Single Memory**: Using a specific memory ID
+<Info>
-2. **Batch Delete**: Delete multiple known memory IDs (up to 1000)
+  **Why it matters**
-3. **Filtered Delete**: Delete memories matching a filter (e.g., `user_id`, `metadata`, `run_id`)
+  - Satisfies user erasure (GDPR/CCPA) without touching the rest of your data.
  - Keeps knowledge bases accurate by removing stale or incorrect facts.
  - Works for both the managed Platform API and the OSS SDK.
 </Info>
-This page walks through code examples for each method.
+## Key terms
 - **memory_id** – Unique ID returned by `add`/`search` identifying the record to delete.
 - **batch_delete** – API call that removes up to 1000 memories in one request.
 - **delete_all** – Filter-based deletion by user, agent, run, or metadata.
 - **immutable** – Flagged memories that cannot be updated; delete + re-add instead.
-## Use Cases
+## How the delete flow works
- Forget a user’s past preferences by request
+<Steps>
- Remove outdated or incorrect memory entries
+<Step title="Choose the scope">
- Clean up memory after session expiration
+Decide whether you’re removing a single memory, a list, or everything that matches a filter.
- Comply with data deletion requests (e.g., GDPR)
+</Step>
 <Step title="Submit the delete call">
 Call `delete`, `batch_delete`, or `delete_all` with the required IDs or filters.
 </Step>
 <Step title="Verify">
 Confirm the response message, then re-run `search` or check the dashboard/logs to ensure the memory is gone.
 </Step>
 </Steps>
---
+## Delete a single memory (Platform)
 ## 1. Delete a Single Memory by ID
 <CodeGroup>
 ```python Python
@@ -48,9 +60,11 @@ client.delete("your_memory_id")
 ```
 </CodeGroup>
---
+<Info icon="check">
  You’ll receive a confirmation payload. The dashboard reflects the removal within seconds.
 </Info>
-## 2. Batch Delete Multiple Memories
+## Batch delete multiple memories (Platform)
 <CodeGroup>
 ```python Python
@@ -83,9 +97,7 @@ client.batchDelete(deleteMemories)
 ```
 </CodeGroup>
---
+## Delete memories by filter (Platform)
 ## 3. Delete Memories by Filter (e.g., user_id)
 <CodeGroup>
 ```python Python
@@ -114,27 +126,65 @@ You can also filter by other parameters such as:
 - `run_id`
 - `metadata` (as JSON string)
---
+<Warning>
  `delete_all` requires at least one filter (user, agent, run, or metadata). Calling it with no filters raises an error to prevent accidental data loss.
 </Warning>
-## Key Differences
+## Delete with Mem0 OSS
-| Method                | Use When                                | IDs Needed | Filters |
+<CodeGroup>
-|----------------------|-------------------------------------------|------------|----------|
+```python Python
-| `delete(memory_id)`  | You know exactly which memory to remove   | ✔          | ✘        |
+from mem0 import Memory
 | `batch_delete([...])`| You have a known list of memory IDs       | ✔          | ✘        |
 | `delete_all(...)`    | You want to delete by user/agent/run/etc | ✘          | ✔        |
 memory = Memory()
-### More Details
+memory.delete(memory_id="mem_123")
 memory.delete_all(user_id="alice")
 ```
 </CodeGroup>
-For request/response schema and additional filtering options, see:
+<Note>
- [Delete Memory API Reference](/api-reference/memory/delete-memory)
+  The OSS JavaScript SDK does not yet expose deletion helpers—use the REST API or Python SDK when self-hosting.
- [Batch Delete API Reference](/api-reference/memory/batch-delete)
+</Note>
 - [Delete Memories by Filter Reference](/api-reference/memory/delete-memories)
-You’ve now seen how to add, search, update, and delete memories in Mem0.
+## Use cases recap
-## Need help?
+- Forget a user’s preferences at their request.
-If you have any questions, please feel free to reach out to us using one of the following methods:
+- Remove outdated or incorrect facts before they spread.
 - Clean up memories after session expiration or retention deadlines.
 - Comply with privacy legislation (GDPR, CCPA) and internal policies.
-<Snippet file="get-help.mdx"/>
+## Method comparison
 | Method | Use when | IDs required | Filters |
 | --- | --- | --- | --- |
 | `delete(memory_id)` | You know the exact record | ✔️ | ✖️ |
 | `batch_delete([...])` | You have a list of IDs to purge | ✔️ | ✖️ |
 | `delete_all(...)` | You need to forget a user/agent/run | ✖️ | ✔️ |
 ## Put it into practice
 - Review the <Link href="/api-reference/memory/delete-memory">Delete Memory API reference</Link>, plus <Link href="/api-reference/memory/batch-delete">Batch Delete</Link> and <Link href="/api-reference/memory/delete-memories">Filtered Delete</Link>.
 - Pair deletes with <Link href="/platform/features/expiration-date">Expiration Policies</Link> to automate retention.
 ## See it live
 - <Link href="/examples/customer-support-agent">Customer Support Agent</Link> demonstrates compliance-driven deletes.
 - <Link href="/platform/features/direct-import">Data Management tooling</Link> shows how deletes fit into broader lifecycle flows.
 {/* DEBUG: verify CTA targets */}
 <CardGroup cols={2}>
  <Card
    title="Review Add Concepts"
    description="Ensure the memories you keep are structured from the start."
    icon="circle-check"
    href="/core-concepts/memory-operations/add"
  />
  <Card
    title="Enable Expiration Policies"
    description="Automate retention with the platform’s expiration feature."
    icon="clock"
    href="/platform/features/expiration-date"
  />
 </CardGroup>
@@ -5,20 +5,23 @@ icon: "magnifying-glass"
 iconType: "solid"
 ---
-## Overview
+# How Mem0 Searches Memory
-The `search` operation allows you to retrieve relevant memories based on a natural language query and optional filters like user ID, agent ID, categories, and more. This is the foundation of giving your agents memory-aware behavior.
+Mem0’s search operation lets agents ask natural-language questions and get back the memories that matter most. It’s the bridge between everything you’ve stored and the next response your agent writes.
-Mem0 supports:
+<Info>
- Semantic similarity search
+  **Why it matters**
- Metadata filtering (with advanced logic)
+  - Retrieves the right facts without rebuilding prompts from scratch.
- Reranking and thresholds
+  - Supports both managed Platform and OSS so you can test locally and deploy at scale.
- Cross-agent, multi-session context resolution
+  - Keeps results relevant with filters, rerankers, and thresholds.
 </Info>
-This applies to both:
+## Key terms
 - **Mem0 Platform** (hosted API with full-scale features)
 - **Mem0 Open Source** (local-first with LLM inference and local vector DB)
 - **Query** – Natural-language question or statement you pass to `search`.
 - **Filters** – JSON logic (AND/OR, comparison operators) that narrows results by user, categories, dates, etc.
 - **top_k / threshold** – Controls how many memories return and the minimum similarity score.
 - **Rerank** – Optional second pass that boosts precision when a reranker is configured.
 ## Architecture
@@ -26,23 +29,26 @@ This applies to both:
  <img src="../../images/search_architecture.png" />
 </Frame>
-When you call `search`, Mem0 performs the following steps:
+<Steps>
 <Step title="Query processing">
 Mem0 cleans and enriches your natural-language query so the downstream embedding search is accurate.
 </Step>
 <Step title="Vector search">
 Embeddings locate the closest memories using cosine similarity across your scoped dataset.
 </Step>
 <Step title="Filtering & reranking">
 Logical filters narrow candidates; rerankers or thresholds fine-tune ordering.
 </Step>
 <Step title="Results delivery">
 Formatted memories (with metadata and timestamps) return to your agent or calling service.
 </Step>
 </Steps>
-1. **Query Processing**
+This pipeline runs the same way for the hosted Platform API and the OSS SDK.
   An LLM refines and optimizes your natural language query.
 2. **Vector Search**
   Semantic embeddings are used to find the most relevant memories using cosine similarity.
 3. **Filtering & Ranking**
   Logical and comparison-based filters are applied. Memories are scored, filtered, and optionally reranked.
 4. **Results Delivery**
   Relevant memories are returned with associated metadata and timestamps.
 ---
-## Example: Mem0 Platform
+## Search with Mem0 Platform
 <CodeGroup>
 ```python Python
@@ -81,7 +87,7 @@ const results = await client.search(query, {
 ---
-## Example: Mem0 Open Source
+## Search with Mem0 Open Source
 <CodeGroup>
 ```python Python
@@ -118,7 +124,11 @@ const memories = memory.search("food preferences", {
 ---
-## Using Filters
+<Info icon="check">
  Expect an array of memory documents. Platform responses include vectors, metadata, and timestamps; OSS returns your stored schema.
 </Info>
 ## Filter patterns
 Filters help narrow down search results. Common use cases:
@@ -152,7 +162,7 @@ client.search("preferences", filters={
 ---
-## Tips for Better Search
+## Tips for better search
 - **Use natural language**: Mem0 understands intent, so describe what you're looking for naturally
 - **Scope with session IDs**: Always provide at least `user_id` to scope search to relevant memories
@@ -167,7 +177,38 @@ client.search("preferences", filters={
 For the full list of filter logic, comparison operators, and optional search parameters, see the
 [Search Memory API Reference](/api-reference/memory/search-memories).
-## Need help?
+## Managed vs OSS differences
 If you have any questions, please feel free to reach out to us using one of the following methods:
-<Snippet file="get-help.mdx"/>
+| Capability | Mem0 Platform | Mem0 OSS |
 | --- | --- | --- |
 | Filters | Logical operators (`AND`, `OR`, comparisons) with field-level access | Basic field filters, extend via Python hooks |
 | Reranking | Toggle `rerank=True` with managed reranker catalog | Requires configuring local or third-party rerankers |
 | Thresholds | Request-level configuration (`threshold`, `top_k`) | Controlled via SDK parameters |
 | Response metadata | Includes confidence scores, timestamps, dashboard visibility | Determined by your storage backend |
 ## Put it into practice
 - Revisit the <Link href="/core-concepts/memory-operations/add">Add Memory</Link> guide to ensure you capture the context you expect to retrieve.
 - Configure rerankers and filters in <Link href="/platform/features/advanced-retrieval">Advanced Retrieval</Link> for higher precision.
 ## See it live
 - <Link href="/examples/customer-support-agent">Customer Support Agent</Link> demonstrates scoped search with rerankers.
 - <Link href="/examples/personalized-search-tavily-mem0">Personalized Search with Tavily</Link> shows hybrid search in action.
 {/* DEBUG: verify CTA targets */}
 <CardGroup cols={2}>
  <Card
    title="Tune Update Concepts"
    description="Learn how to adjust memories after search results come back."
    icon="pencil"
    href="/core-concepts/memory-operations/update"
  />
  <Card
    title="Build Hybrid Search"
    description="Follow the cookbook to combine Mem0 with external search."
    icon="rocket"
    href="/examples/personalized-search-tavily-mem0"
  />
 </CardGroup>
@@ -5,29 +5,40 @@ icon: "pen-to-square"
 iconType: "solid"
 ---
-## Overview
+# Keep Memories Accurate with Update
-User preferences, interests, and behaviors often evolve over time. The `update` operation lets you revise a stored memory, whether it's updating facts, rephrasing a message, or enriching metadata.
+Mem0’s update operation lets you fix or enrich an existing memory without deleting it. When a user changes their preference or clarifies a fact, use update to keep the knowledge base fresh.
-Mem0 supports both:
+<Info>
- **Single Memory Update** for one specific memory using its ID
+  **Why it matters**
- **Batch Update** for updating many memories at once (up to 1000)
+  - Corrects outdated or incorrect memories immediately.
  - Adds new metadata so filters and rerankers stay sharp.
  - Works for both one-off edits and large batches (up to 1000 memories).
 </Info>
-This guide includes usage for both single update and batch update of memories through **Mem0 Platform**.
+## Key terms
 - **memory_id** – Unique identifier returned by `add` or `search` results.
 - **text** / **data** – New content that replaces the stored memory value.
 - **metadata** – Optional key-value pairs you update alongside the text.
 - **batch_update** – Platform API that edits multiple memories in a single request.
 - **immutable** – Flagged memories that must be deleted and re-added instead of updated.
-## Use Cases
+## How the update flow works
- Refine a vague or incorrect memory after a correction
+<Steps>
- Add or edit memory with new metadata (e.g., categories, tags)
+<Step title="Locate the memory">
- Evolve factual knowledge as the user's profile changes
+Use `search` or dashboard inspection to capture the `memory_id` you want to change.
- Handle profile evolution: "I love spicy food" → later says "Actually, I can't handle spicy food"
+</Step>
 <Step title="Submit the update">
 Call `update` (or `batch_update`) with new text and optional metadata. Mem0 overwrites the stored value and adjusts indexes.
 </Step>
 <Step title="Verify">
 Check the response or re-run `search` to ensure the revised memory appears with the new content.
 </Step>
 </Steps>
-Updating memory ensures your agents remain accurate, adaptive, and personalized.
+## Single memory update (Platform)
 ---
 ## Update Memory
 <CodeGroup>
 ```python Python
@@ -49,18 +60,18 @@ import MemoryClient from 'mem0ai';
 const client = new MemoryClient({ apiKey: "your-api-key" });
 const memory_id = "your_memory_id";
-client.update(memory_id, {
+await client.update(memory_id, {
  text: "Updated memory content about the user",
  metadata: { category: "profile-update" }
-})
+});
  .then(result => console.log(result))
  .catch(error => console.error(error));
 ```
 </CodeGroup>
---
+<Info icon="check">
  Expect a confirmation message and the updated memory to appear in the dashboard almost instantly.
 </Info>
-## Batch Update
+## Batch update (Platform)
 Update up to 1000 memories in one call.
@@ -95,21 +106,66 @@ client.batchUpdate(updateMemories)
 ```
 </CodeGroup>
---
+## Update with Mem0 OSS
 <CodeGroup>
 ```python Python
 from mem0 import Memory
 memory = Memory()
 memory.update(
    memory_id="mem_123",
    data="Alex now prefers decaf coffee",
 )
 ```
 ```
 ```
 </CodeGroup>
 <Note>
  OSS JavaScript SDK does not expose `update` yet—use the REST API or Python SDK when self-hosting.
 </Note>
 ## Tips
- You can update both `text` and `metadata` in the same call
+- Update both `text` **and** `metadata` together to keep filters accurate.
- Use `batchUpdate` when you're applying similar corrections at scale
+- Batch updates are ideal after large imports or when syncing CRM corrections.
- If memory is marked `immutable`, it must first be deleted and re-added
+- Immutable memories must be deleted and re-added instead of updated.
- Combine this with feedback mechanisms (e.g., user thumbs-up/down) to self-improve memory
+- Pair updates with feedback signals (thumbs up/down) to self-heal memories automatically.
 ## Managed vs OSS differences
-### More Details
+| Capability | Mem0 Platform | Mem0 OSS |
 | --- | --- | --- |
 | Update call | `client.update(memory_id, {...})` | `memory.update(memory_id, data=...)` |
 | Batch updates | `client.batch_update` (up to 1000 memories) | Script your own loop or bulk job |
 | Dashboard visibility | Inspect updates in the UI | Inspect via logs or custom tooling |
 | Immutable handling | Returns descriptive error | Raises exception—delete and re-add |
-Refer to the full [Update Memory API Reference](/api-reference/memory/update-memory) and [Batch Update Reference](/api-reference/memory/batch-update) for schema and advanced fields.
+## Put it into practice
-## Need help?
+- Review the <Link href="/api-reference/memory/update-memory">Update Memory API reference</Link> for request/response details.
-If you have any questions, please feel free to reach out to us using one of the following methods:
+- Combine updates with <Link href="/platform/features/feedback-mechanism">Feedback Mechanism</Link> to automate corrections.
-<Snippet file="get-help.mdx"/>
+## See it live
 - <Link href="/examples/customer-support-agent">Customer Support Agent</Link> uses updates to refine customer profiles.
 - <Link href="/examples/personal-ai-tutor">Personal AI Tutor</Link> demonstrates user preference corrections mid-course.
 {/* DEBUG: verify CTA targets */}
 <CardGroup cols={2}>
  <Card
    title="Learn Delete Concepts"
    description="Understand when to remove memories instead of editing them."
    icon="trash"
    href="/core-concepts/memory-operations/delete"
  />
  <Card
    title="Automate Corrections"
    description="See how feedback loops trigger updates in production."
    icon="rocket"
    href="/platform/features/feedback-mechanism"
  />
 </CardGroup>
@@ -1,50 +1,129 @@
 ---
 title: Memory Types
-description: Understanding different types of memory in AI Applications
+description: "See how Mem0 layers conversation, session, and user memories to keep agents contextual."
-icon: "memory"
+icon: "tag"
 iconType: "solid"
 ---
-To build useful AI applications, we need to understand how different memory systems work together. This guide explores the fundamental types of memory in AI systems and shows how Mem0 implements these concepts.
+# How Mem0 Organizes Memory
-## Why Memory Matters
+Mem0 separates memory into layers so agents remember the right detail at the right time. Think of it like a notebook: a sticky note for the current task, a daily journal for the session, and an archive for everything a user has shared.
-AI systems need memory for three key purposes:
+<Info>
-1. Maintaining context during conversations
+  **Why it matters**
-2. Learning from past interactions
+  - Keeps conversations coherent without repeating instructions.
-3. Building personalized experiences over time
+  - Lets agents personalize responses based on long-term preferences.
  - Avoids over-fetching data by scoping memory to the correct layer.
 </Info>
-Without proper memory systems, AI applications would treat each interaction as completely new, losing valuable context and personalization opportunities.
+## Key terms
-## Short-Term Memory
+- **Conversation memory** – In-flight messages inside a single turn (what was just said).
 - **Session memory** – Short-lived facts that apply for the current task or channel.
 - **User memory** – Long-lived knowledge tied to a person, account, or workspace.
 - **Organizational memory** – Shared context available to multiple agents or teams.
-The most basic form of memory in AI systems holds immediate context - like a person remembering what was just said in a conversation. This includes:
+```mermaid
 graph LR
  A[Conversation turn] --> B[Session memory]
  B --> C[User memory]
  C --> D[Org memory]
  C --> E[Mem0 retrieval layer]
 ```
- **Conversation History**: Recent messages and their order
+## Short-term vs long-term memory
 - **Working Memory**: Temporary variables and state
 - **Attention Context**: Current focus of the conversation
-## Long-Term Memory
+Short-term memory keeps the current conversation coherent. It includes:
-More sophisticated AI applications implement long-term memory to retain information across conversations. This includes:
+- **Conversation history** – recent turns in order so the agent remembers what was just said.
 - **Working memory** – temporary state such as tool outputs or intermediate calculations.
 - **Attention context** – the immediate focus of the assistant, similar to what a person holds in mind mid-sentence.
- **Factual Memory**: Stored knowledge about users, preferences, and domain-specific information
+Long-term memory preserves knowledge across sessions. It captures:
 - **Episodic Memory**: Past interactions and experiences
 - **Semantic Memory**: Understanding of concepts and their relationships
-## Memory Characteristics
+- **Factual memory** – user preferences, account details, and domain facts.
 - **Episodic memory** – summaries of past interactions or completed tasks.
 - **Semantic memory** – relationships between concepts so agents can reason about them later.
-Each memory type has distinct characteristics:
+Mem0 maps these classic categories onto its layered storage so you can decide what should fade quickly versus what should last for months.
-| Type | Persistence | Access Speed | Use Case |
+## How does it work?
 |------|-------------|--------------|-----------|
 | Short-Term | Temporary | Instant | Active conversations |
 | Long-Term | Persistent | Fast | User preferences and history |
-## How Mem0 Implements Long-Term Memory
+Mem0 stores each layer separately and merges them when you query:
-Mem0's long-term memory system builds on these foundations by:
+1. **Capture** – Messages enter the conversation layer while the turn is active.
 2. **Promote** – Relevant details persist to session or user memory based on your `user_id`, `session_id`, and metadata.
 3. **Retrieve** – The search pipeline pulls from all layers, ranking user memories first, then session notes, then raw history.
-1. Using vector embeddings to store and retrieve semantic information
+```python
-2. Maintaining user-specific context across sessions
+import os
-3. Implementing efficient retrieval mechanisms for relevant past interactions
+
 from mem0 import Memory
 memory = Memory(api_key=os.environ["MEM0_API_KEY"])
 # Sticky note: conversation memory
 memory.add(
    ["I'm Alex and I prefer boutique hotels."],
    user_id="alex",
    session_id="trip-planning-2025",
 )
 # Later in the session, pull long-term + session context
 results = memory.search(
    "Any hotel preferences?",
    user_id="alex",
    session_id="trip-planning-2025",
 )
 ```
 <Tip>
  Use `session_id` when you want short-term context to expire automatically; rely on `user_id` for lasting personalization.
 </Tip>
 ## When should you use each layer?
 - **Conversation memory** – Tool calls or chain-of-thought that only matter within the current turn.
 - **Session memory** – Multi-step tasks (onboarding flows, debugging sessions) that should reset once complete.
 - **User memory** – Personal preferences, account state, or compliance details that must persist across interactions.
 - **Organizational memory** – Shared FAQs, product catalogs, or policies that every agent should recall.
 ## How it compares
 | Layer | Lifetime | Short or long term | Best for | Trade-offs |
 | --- | --- | --- | --- | --- |
 | Conversation | Single response | Short-term | Tool execution detail | Lost after the turn finishes |
 | Session | Minutes to hours | Short-term | Multi-step flows | Clear it manually when done |
 | User | Weeks to forever | Long-term | Personalization | Requires consent/governance |
 | Org | Configured globally | Long-term | Shared knowledge | Needs owner to keep current |
 <Warning>
  Avoid storing secrets or unredacted PII in user or org memories—Mem0 is retrievable by design. Encrypt or hash sensitive values first.
 </Warning>
 ## Put it into practice
 - Use the <Link href="/core-concepts/memory-operations/add">Add Memory</Link> guide to persist user preferences.
 - Follow <Link href="/platform/advanced-memory-operations">Advanced Memory Operations</Link> to tune metadata and graph writes.
 ## See it live
 - <Link href="/examples/personal-ai-tutor">Personal AI Tutor</Link> shows session vs user memories in action.
 - <Link href="/examples/customer-support-agent">Customer Support Agent</Link> demonstrates shared org memory.
 {/* DEBUG: verify CTA targets */}
 <CardGroup cols={2}>
  <Card
    title="Explore Memory Operations"
    description="Dive into the add/search/update/delete concepts next."
    icon="circle-check"
    href="/core-concepts/memory-operations/add"
  />
  <Card
    title="See a Cookbook"
    description="Apply layered memories inside a customer support agent."
    icon="rocket"
    href="/examples/customer-support-agent"
  />
 </CardGroup>
@@ -5,82 +5,105 @@ iconType: "solid"
 description: "Self-host Mem0 with full control over your infrastructure and data"
 ---
 # Mem0 Open Source Overview
 Mem0 Open Source delivers the same adaptive memory engine as the platform, but packaged for teams that need to run everything on their own infrastructure. You own the stack, the data, and the customizations.
 <Tip>
-**Mem0 v1.0.0 is now available** — Introducing rerankers, async by default, Azure support, and more. [View changelog →](/changelog)
+  Mem0 v1.0.0 brought rerankers, async-by-default clients, and Azure OpenAI support. See the <Link href="/changelog">release notes</Link> for the full rundown before upgrading.
 </Tip>
-## Self-Host Mem0 with Full Control
+## What Mem0 OSS provides
-Mem0 Open Source gives you a powerful, self-hosted memory layer for AI agents. Deploy on your infrastructure, customize every component, and maintain complete data ownership.
+- **Full control**: Tune every component, from LLMs to vector stores, inside your environment.
 - **Offline ready**: Keep memory on your own network when compliance or privacy demands it.
 - **Extendable codebase**: Fork the repo, add providers, and ship custom automations.
-## Get Started
+<Info>
  Begin with the <Link href="/open-source/python-quickstart">Python quickstart</Link> (or the Node.js variant) to clone the repo, configure dependencies, and validate memory reads/writes locally.
 </Info>
-Choose your preferred SDK and get Mem0 running locally in minutes:
+## Choose your path
 <CardGroup cols={2}>
  <Card title="Python Quickstart" icon="python" href="/open-source/python-quickstart">
-    Install and configure Mem0 OSS with Python in 10 minutes
+    Bootstrap the CLI, run dockerized dependencies, and verify the add/search loop.
  </Card>
  <Card title="Node.js Quickstart" icon="node" href="/open-source/node-quickstart">
-    Set up Mem0 OSS with Node.js and TypeScript support
+    Install the TypeScript SDK, wire environment variables, and run the starter script.
  </Card>
 </CardGroup>
 ## Explore OSS Capabilities
 Mem0 Open Source offers powerful features for building production-grade AI applications with memory. From graph-based knowledge structures to flexible component configuration, you have full control over how memory works in your system.
 <CardGroup cols={3}>
-  <Card title="Graph Memory" icon="network-wired" href="/open-source/features/graph-memory">
+  <Card title="Configure Components" icon="sliders" href="/open-source/configuration">
-    Build relationship-aware memory with knowledge graph capabilities
+    Choose your LLM, embedder, vector store, and reranker with YAML or code.
  </Card>
-
+  <Card title="Graph Memory Capability" icon="network-wired" href="/open-source/features/graph-memory">
-  <Card title="Component Configuration" icon="sliders" href="/open-source/configuration">
+    Add relationship-aware recall across providers like Neo4j, Memgraph, or Kùzu.
    Choose your LLM, vector database, embedding model, and rerankers
  </Card>
-
+  <Card title="Tune Retrieval & Rerankers" icon="sparkles" href="/open-source/features/reranker-search">
-  <Card title="REST API" icon="bolt" href="/open-source/features/rest-api">
+    Optimize search quality with hybrid retrieval and reranker depth controls.
    Build high-throughput pipelines with async clients and REST endpoints
  </Card>
 </CardGroup>
-<Note>
+<CardGroup cols={2}>
-**Platform vs OSS?** See our [comparison guide](/platform/platform-vs-oss) to understand which deployment option fits your use case.
+  <Card title="Deploy with Docker Compose" icon="server" href="/examples/mem0-with-ollama">
-</Note>
+    Follow the reference deployment to persist memories and expose REST endpoints.
  </Card>
  <Card title="Use the REST API" icon="code" href="/open-source/features/rest-api">
    Call the REST endpoints for async add/search flows and project automation.
  </Card>
 </CardGroup>
---
+<Tip>
  Need a managed alternative? Compare hosting models in the <Link href="/platform/platform-vs-oss">Platform vs OSS guide</Link> or switch tabs to the Platform documentation.
 </Tip>
-## Why Choose Open Source?
+<AccordionGroup>
  <Accordion title="What you get with Mem0 OSS" icon="code-branch">
-| Benefit | What You Get |
+    | Benefit | What you get |
-|---------|--------------|
+    | --- | --- |
-| **Full Infrastructure Control** | Host on your own servers with complete access to configuration and deployment |
+    | Full infrastructure control | Host on your own servers with complete access to configuration and deployment. |
-| **Complete Customization** | Modify implementation, extend functionality, and adapt to your specific needs |
+    | Complete customization | Modify the implementation, extend functionality, and tailor it to your stack. |
-| **Local Development** | Perfect for development, testing, and air-gapped environments |
+    | Local development | Perfect for development, testing, and offline environments. |
-| **No Vendor Lock-in** | Own your data, choose your stack, and maintain full independence |
+    | No vendor lock-in | Keep ownership of your data, providers, and pipelines. |
-| **Community Driven** | Contribute to and benefit from active community improvements and integrations |
+    | Community driven | Contribute improvements and tap into a growing ecosystem. |
  </Accordion>
 </AccordionGroup>
-<Info>
+## Default components
 **Looking for production scale?** [Mem0 Platform](/platform/overview) offers managed infrastructure with advanced features like webhooks, multimodal support, and enterprise support.
 </Info>
 <Note>
-**Need help?** Check out our [GitHub repository](https://mem0.dev/gd) for source code, issues, and community discussions.
+  Mem0 OSS works out of the box with sensible defaults:
  - LLM: OpenAI `gpt-4.1-nano-2025-04-14` (via `OPENAI_API_KEY`)
  - Embeddings: OpenAI `text-embedding-3-small`
  - Vector store: Local Qdrant instance storing data at `/tmp/qdrant`
  - History store: SQLite database at `~/.mem0/history.db`
  - Reranker: Disabled until you configure a provider
  Override any component with <Link href="/open-source/configuration">`Memory.from_config`</Link>.
 </Note>
---
+## Keep going
-## Default Components
+{/* DEBUG: verify CTA targets */}
-<Note>
+<CardGroup cols={2}>
-**No configuration needed to get started.** Mem0 works out of the box with sensible defaults:
+  <Card
    title="Review Platform vs OSS"
    description="Confirm whether managed infrastructure or self-hosting better suits your workload."
    icon="arrows-left-right"
    href="/platform/platform-vs-oss"
  />
  <Card
    title="Run the Python Quickstart"
    description="Clone the repo, install dependencies, and persist your first local memory."
    icon="terminal"
    href="/open-source/python-quickstart"
  />
 </CardGroup>
- **LLM**: OpenAI `gpt-4.1-nano-2025-04-14` via your `OPENAI_API_KEY`
+<Tip>
- **Embeddings**: OpenAI `text-embedding-3-small` (1536 dimensions)
+  Need a managed alternative? Compare hosting models in the <Link href="/platform/platform-vs-oss">Platform vs OSS guide</Link> or switch tabs to the Platform documentation.
- **Vector store**: Local Qdrant instance storing data at `/tmp/qdrant`
+</Tip>
 - **History storage**: SQLite database at `~/.mem0/history.db`
 - **Reranker**: Disabled unless you configure one
 Override any component with [`Memory.from_config`](/open-source/configuration).
 </Note>
@@ -4,126 +4,87 @@ description: "Managed memory layer for AI agents - production-ready in minutes"
 icon: "cloud"
 ---
 # Mem0 Platform Overview
 Mem0 is the memory engine that keeps conversations contextual so users never repeat themselves and your agents respond with continuity. Mem0 Platform delivers that experience as a fully managed service—scaling, securing, and enriching memories without any infrastructure work on your side.
 <Tip>
-**Mem0 v1.0.0 is now available** — Introducing rerankers, async by default, Azure support, and more. [View changelog →](/changelog)
+  Mem0 v1.0.0 shipped rerankers, async-by-default behavior, and Azure OpenAI support. Catch the full list of changes in the <Link href="/changelog">release notes</Link>.
 </Tip>
-## Welcome to Mem0 Platform
+## Why it matters
-**Mem0 Platform is a fully managed memory layer for AI agents.** Add persistent, personalized memory to your AI applications in minutes - no infrastructure setup required.
+- **Personalized replies**: Memories persist across users and agents, cutting prompt bloat and repeat questions.
 - **Hosted stack**: Mem0 runs the vector store, graph services, and rerankers—no provisioning, tuning, or maintenance.
 - **Enterprise controls**: SOC 2, audit logs, and workspace governance ship by default for production readiness.
-## What is Mem0?
+<AccordionGroup>
  <Accordion title="What you get with Mem0 Platform" icon="sparkles">
-Mem0 is a memory layer that enables your AI applications to remember user preferences, conversation history, and contextual information across sessions. Instead of treating every interaction as isolated, Mem0 allows your AI to build on previous conversations and adapt to individual users over time.
+    | Feature | Why it helps |
    | --- | --- |
    | Fast setup | Add a few lines of code and you’re production-ready—no vector database or LLM configuration required. |
    | Production scale | Automatic scaling, high availability, and managed infrastructure so you focus on product work. |
    | Advanced features | Graph memory, webhooks, multimodal support, and custom categories are ready to enable. |
    | Enterprise ready | SOC 2 Type II, GDPR compliance, and dedicated support keep security and governance covered. |
  </Accordion>
 </AccordionGroup>
-## What Problem Does It Solve?
+<Info>
  Start with the <Link href="/platform/quickstart">Platform quickstart</Link> to provision your workspace, then pick the journey below that matches your next milestone.
 </Info>
-Without Mem0, every AI conversation starts from scratch:
+## Choose your path
 - User preferences disappear between sessions
 - Previous context is lost and must be re-explained
 - Personalization becomes impossible
 - AI can't learn or adapt to individual users
 With Mem0, your AI remembers:
 - Context persists across sessions with sub-50ms latency
 - Preferences are automatically recalled
 - Responses adapt to each user's history
 - No infrastructure setup or vector DB management required
 ## Where Can I Use Mem0?
 Mem0 powers memory for diverse AI applications. Explore real-world implementations:
 - **[Customer Support Agents](/examples/customer-support-agent)** - Remember customer history and preferences
 - **[AI Tutors](/examples/personal-ai-tutor)** - Track learning progress and adapt lessons
 - **[Travel Assistants](/examples/personal-travel-assistant)** - Recall travel preferences and past trips
 - **[Content Writing](/examples/memory-guided-content-writing)** - Maintain consistent voice and context
 [View all cookbooks →](/examples)
 ---
 ## Explore Platform Capabilities
 <CardGroup cols={2}>
-  <Card
+  <Card title="Launch Your Workspace" icon="rocket" href="/platform/quickstart">
-    title="Platform Quickstart"
+    Create a project, export an API key, and ship your first memory in minutes.
    icon="rocket"
    href="/platform/quickstart"
  >
    Get your first memory stored in 5 minutes. Step-by-step guide with code examples.
  </Card>
-
+  <Card title="Understand Memory Types" icon="brain" href="/core-concepts/memory-types">
-  <Card
+    Learn how user, agent, and session memories behave across the platform.
    title="Platform vs Open Source"
    icon="scale"
    href="/platform/platform-vs-oss"
  >
    Compare managed and self-hosted options. See which fits your needs best.
  </Card>
  <Card
    title="Memory Types"
    icon="brain"
    href="/core-concepts/memory-types"
  >
    Understand user memories, agent memories, and session-specific context.
  </Card>
  <Card
    title="Platform Features"
    icon="sparkles"
    href="/platform/features/platform-overview"
  >
    Explore graph memory, multimodal support, webhooks, and advanced retrieval.
  </Card>
  <Card
    title="Framework Integrations"
    icon="plug"
    href="/integrations"
  >
    Use Mem0 with LangChain, CrewAI, LlamaIndex, and 15+ other frameworks.
  </Card>
  <Card
    title="Dashboard"
    icon="chart-line"
    href="https://app.mem0.ai"
  >
    Monitor memory operations, track usage, and manage your AI agents.
  </Card>
 </CardGroup>
---
+<CardGroup cols={3}>
  <Card title="Master Core Operations" icon="circle-check" href="/core-concepts/memory-operations/add">
    See how add/search/update/delete work together with verification steps.
  </Card>
  <Card title="Explore Platform Features" icon="sparkles" href="/platform/features/platform-overview">
    Browse graph memory, async clients, and rerankers before turning them on.
  </Card>
  <Card title="Configure Advanced Operations" icon="bolt" href="/platform/advanced-memory-operations">
    Layer metadata filters, rerankers, and per-request toggles onto your flows.
  </Card>
 </CardGroup>
-## Why Choose Mem0 Platform?
+<CardGroup cols={2}>
  <Card title="Connect Integrations" icon="plug" href="/integrations">
    Wire Mem0 into LangChain, CrewAI, Vercel AI SDK, and other partner tools.
  </Card>
  <Card title="Monitor in the Dashboard" icon="presentation" href="https://app.mem0.ai">
    Track memory activity, adjust settings, and manage workspaces from one place.
  </Card>
 </CardGroup>
-| Feature | What You Get |
+<Tip>
-|---------|--------------|
+  Evaluating self-hosting instead? Jump to the <Link href="/platform/platform-vs-oss">Platform vs OSS comparison</Link> to see trade-offs before you commit.
-| **Fast Setup** | Add 4 lines of code and you're production-ready. No vector DB setup, no LLM configuration, no DevOps. |
+</Tip>
 | **Production Scale** | Automatic scaling, high availability, and fully managed infrastructure. Focus on your app, not operations. |
 | **Advanced Features** | Graph memory, webhooks, multimodal support, and custom categories - exclusive to Platform. |
 | **Enterprise Ready** | SOC 2 Type II certified, GDPR compliant, with dedicated support for production workloads. |
---
+## Keep going
-## Next Steps
+{/* DEBUG: verify CTA targets */}
 <CardGroup cols={2}>
  <Card
-    title="Start Building"
+    title="Compare with Open Source"
    description="Review feature parity, migration paths, and when to stay managed."
    icon="arrows-left-right"
    href="/platform/platform-vs-oss"
  />
  <Card
    title="Run the Quickstart"
    description="Provision your workspace, install the SDK, and persist your first memory."
    icon="rocket"
    href="/platform/quickstart"
-  >
+  />
    Follow the quickstart guide to create your first memory in 5 minutes
  </Card>
  <Card
    title="Compare Options"
    icon="code-compare"
    href="/platform/platform-vs-oss"
  >
    See the full comparison between Platform and Open Source
  </Card>
 </CardGroup>
@@ -14,6 +14,7 @@ API reference pages document a single endpoint contract. Present metadata, reque
 - Frontmatter must include `title`, `description`, `icon`, `method`, `path`. Heading should be `# METHOD /path`.
 - Provide a quick facts table (Method, Path, Auth, Rate limit) followed by an `<Info>` block describing when to use the endpoint. Add `<Warning>` for beta headers or scope requirements.
 - Requests require headers table, body/parameters table, and `<CodeGroup>` with cURL, Python, TypeScript. If a language is unavailable, include a `<Note>` explaining why.
 - When migrating an existing endpoint page, keep the canonical examples and edge-case notes—drop them into these sections rather than inventing new payloads unless the API changed.
 - Response section must show a canonical success payload, status-code table, and troubleshooting tips. Document pagination/idempotency in `<Tip>` or `<Note>` blocks.
 - End with related endpoints, a sample workflow link, and two CTA cards (left = concept/feature, right = applied tutorial). Keep the comment reminder for reviewers.
@@ -14,6 +14,7 @@ Concept guides establish a shared mental model before feature or API docs. Defin
 - Frontmatter must include `title`, `description`, `icon`. Lead with a definition + analogy in two sentences max.
 - Add an `<Info>` block (“Why it matters”) with 2–3 bullets summarizing user impact. Use `<Warning>` near limitations or beta callouts.
 - Introduce vocabulary via `## Key terms` (table or bullets) before diving deeper.
 - When migrating legacy pages, preserve canonical distinctions (e.g., short-term vs long-term) and fold them into the template rather than replacing them with new frameworks.
 - Organize the body with question-style headings (`How does it work?`, `When should you use it?`, `How it compares`). Optional diagrams should be left-to-right (`graph LR`).
 - Include at least one light code/JSON snippet or data table so the concept ties back to implementation.
 - Close with a “Put it into practice” checklist, “See it live” links, and the standard two-card CTA (left = feature/reference, right = applied cookbook).
@@ -15,6 +15,7 @@ Cookbooks are narrative tutorials. They start with a real problem, show the brok
 - Keep tone conversational; use real names ("Max", "Sarah"), not `user_123`.
 - Opening must stay tight: ≤2 short paragraphs (no bullet lists) before the first section.
 - Inline expected outputs immediately after each code block.
 - When modernizing an existing cookbook, keep the narrative beats, screenshots, and sample outputs—reshape them into this arc instead of rewriting unless the workflow changed.
 - Limit callouts to 3–5 per page. Prefer narrative text over stacked boxes.
 - Always provide Python **and** TypeScript tabs when an SDK exists for both.
 - Every page must end with exactly two navigation cards (left = related/side quest, right = next cookbook in the journey).
@@ -19,6 +19,7 @@ Use this when you introduce or deepen a single Mem0 capability (Graph Memory, Ad
 - Frontmatter stays outcome-driven: `title`, `description`, `icon`, optional `badge` (e.g., “Advanced”).
 - Opening paragraph = two sentences: problem, then payoff. Keep energy high right from the start.
 - Include an `<Info>` block titled “You’ll use this when…” with 3 bullets (user persona, workload, expected benefit).
 - When reshaping legacy feature docs, carry over existing diagrams, tables, and gotchas—organize them under these headings rather than replacing them unless the product has changed.
 - If there’s a known caveat (pricing, performance), surface it early in a `<Warning>` so readers don’t get surprised later.
 - Optional but encouraged: add a Mermaid diagram right after the intro to show how components connect; delete it if the story is obvious without visuals.
 - Add a `## Configure access` snippet (even if it’s “Confirm your Mem0 API key is already configured”) so contributors never forget to mention the baseline setup.
@@ -14,6 +14,7 @@ Integration guides prove a joint journey: configure Mem0 and the partner with mi
 - Frontmatter must include `title`, `description`, `icon`, and optional `partnerBadge`/`tags`. State the joint value in one sentence right after the H1.
 - List prerequisites for **both** platforms inside an `<Info>` block. Surface limited-access or beta flags in a `<Warning>` before any setup.
 - Default to Tabs + Steps when instructions diverge (Platform vs OSS, Python vs TypeScript). When only one path exists, add a `<Note>` explaining the missing variant.
 - When migrating an existing integration, keep the proven steps/screenshots—map them into this structure rather than rewriting unless either product has changed.
 - Keep any Mermaid diagrams optional and left-to-right (`graph LR`) to avoid vertical overflow; use only if architecture clarity is needed.
 - Every major step must finish with a verification `<Info icon="check">`. End the page with exactly two CTA cards (left = related reference, right = next integration/cookbook).
@@ -14,6 +14,7 @@ Migrations lower blood pressure. They explain what’s changing, why it matters,
 - Keep the frontmatter complete (`title`, `description`, `icon`, `versionFrom`, `versionTo`, and optional `releaseDate`). Readers should know at a glance what versions they are moving between.
 - Start with context: summary table + “Should you upgrade?” checklist. Highlight deadlines with `<Warning>` and call out optional paths with `<Tip>`.
 - Break the body into **Plan → Migrate → Validate**. Use numbered headings inside **Migrate** and put rollback instructions directly after any risky step.
 - When porting older migration guides, keep existing change tables, screenshots, and warnings—slot them into this format unless the upgrade path has materially changed.
 - Document breaking changes with an `Old behavior` vs `New behavior` table. Use `<Info icon="check">` for mandatory verification steps.
 - Optional flow diagrams are allowed, but only when a left-to-right Mermaid (`graph LR`) clarifies the upgrade path.
 - End with two CTA cards (left = deep dive reference, right = applied example) and keep the comment reminder for reviewers.
@@ -15,6 +15,7 @@ Operation guides focus on a single action (add, search, update, delete). Show th
 - Lead with a two-sentence promise (problem → outcome), followed by an `<Info>` prerequisites block and optional `<Warning>` for hazards (overwrites, rate limits).
 - Include a “When to pick this” bullet list (≤3 items) so readers confirm they’re in the right doc.
 - Use Tabs with Python and TypeScript examples. If only one SDK exists, add a `<Note>` stating that explicitly.
 - When migrating legacy guides, keep existing code paths and notes—slot them into these sections instead of replacing them unless behavior changed.
 - Provide `<Info icon="check">` verification after each critical step; call out the most common error with a `<Warning>` close to where it can occur.
 - End with exactly two CTA cards: left = conceptual depth, right = applied example/cookbook.
@@ -14,6 +14,7 @@ Parameter references document every input/output detail for one operation after
 - Frontmatter requires `title`, `description`, `icon`. Titles should mirror the operation (“Add Memories Parameters”).
 - Place canonical Python and TypeScript signatures right under the heading using `<CodeGroup>`. Mention defaults or breaking changes in an `<Info>` or `<Warning>` immediately after.
 - Parameter table must include columns: Name, Type, Required, Description, Notes. Add a Managed/OSS distinction either as a column or in Notes.
 - When updating legacy parameter sheets, keep the authoritative field lists and notes—reformat them into this structure rather than trimming details unless the schema changed.
 - Response table must include Field, Type, Description, Example. For nested objects, add subtables or `<CodeGroup>` JSON snippets beneath the row.
 - Examples section should show minimal Python and TypeScript calls with one-sentence explanations. If a language is missing, include a `<Note>` explaining why.
 - Finish with related operations, troubleshooting tied to parameter misuse, and a two-card CTA (operation guide on the left, cookbook/integration on the right).
@@ -14,6 +14,7 @@ Quickstarts are the fastest path to first success. Each page should configure th
 - Keep the intro tight: one-sentence promise + `<Info>` prerequisites. Add `<Warning>` only for blocking requirements (e.g., “requires paid tier”).
 - Default to Python + TypeScript examples inside `<Tabs>` with `<Steps>` per language. If a second language truly doesn’t exist, add a `<Note>` explaining why.
 - Every journey must follow **Install → Configure → Add → Search → Delete** (or closest equivalents). Drop verification `<Info icon="check">` immediately after the critical operation.
 - When migrating an existing quickstart, reuse canonical snippets and screenshots—reshape them into this flow rather than rewriting content unless the product changed.
 - If you include a Mermaid diagram, keep it optional and render left-to-right (`graph LR`) so it doesn’t flood the page.
 - End with exactly two CTA cards: left = related/alternative path, right = next step in the journey. No link farms.
@@ -14,6 +14,7 @@ Release notes are heartbeat updates. They tell readers what shipped, what needs
 - Frontmatter must include `title`, `description`, `icon`, `releaseDate`, and `version`. Add `tags` if you need filters (e.g., `["platform", "oss"]`).
 - Lead with a one-sentence headline plus a quick stats table (New features, Fixes, Required action). Keep the TL;DR in an `<Info>` block; use `<Warning>` only for breaking changes or deadlines.
 - Organize the body into Highlights, Improvements & fixes (grouped by product), and Known issues. Each bullet links to docs where appropriate.
 - When reshaping older release notes, retain the shipped items and shout-outs—map them to these sections instead of rewriting history.
 - Include an Upgrade checklist with concrete next steps. Optional “Community shout-outs” should remain short.
 - Two-card CTA at the end, as always: left = deeper reference, right = applied next step.
@@ -13,7 +13,9 @@ Overview pages orient readers for an entire section. Summarize who it’s for, s
 ## ❌ DO NOT COPY — Guidance & Constraints
 - Frontmatter must include `title`, `description`, `icon`. Keep the hero paragraph under two sentences describing audience + outcome.
 - Provide an `<Info>` block pointing to the primary entry point (usually the quickstart). Use `<Warning>` only for major caveats (beta, deprecation).
- Card grids should list 4–6 journeys max using `<CardGroup cols={3}>` or `<Cards>`. Copy must stay ≤15 words, and every card needs an icon + link.
+- Stage journeys in 4–6 cards total. Break into multiple `<CardGroup>` rows when a binary choice (e.g., Python vs Node) or stacked journeys reads better. Keep copy ≤15 words with icons + links.
 - When migrating an existing overview, reuse the established journeys, images, and stats—reshape them into this layout rather than cutting content unless it’s outdated.
 - Optional accordions (`<AccordionGroup>`) can tuck detailed tables (feature breakdowns, comparisons) beneath the hero when extra context is helpful.
 - Optional visuals (comparison table, Mermaid diagram) should be left-to-right and only added when they reduce confusion.
 - Finish with exactly two CTA cards: left = adjacent/alternative track, right = next logical step deeper in the section.
@@ -36,6 +38,15 @@ icon: "compass"
  Start with [Quickstart link] if you’re new, then choose a deeper topic below.
 </Info>
 {/* Optional: delete if not needed */}
 <AccordionGroup>
  <Accordion title="[Optional value table]" icon="sparkles">
    | Feature | Why it helps |
    | --- | --- |
    | ... | ... |
  </Accordion>
 </AccordionGroup>
 {/* Optional: delete if not needed */}
 ```mermaid
 graph LR
@@ -46,27 +57,30 @@ graph LR
 ## Choose your path
-<CardGroup cols={3}>
+{/* Use multiple rows if a 2-up decision helps */}
-  <Card title="[Journey 1]" icon="rocket" href="/[link-1]">
+<CardGroup cols={2}>
  <Card title="[Decision 1]" icon="rocket" href="/[link-1]">
    [One-line outcome]
  </Card>
-  <Card title="[Journey 2]" icon="brain" href="/[link-2]">
+  <Card title="[Decision 2]" icon="brain" href="/[link-2]">
    [One-line outcome]
  </Card>
  <Card title="[Journey 3]" icon="sparkles" href="/[link-3]">
    [One-line outcome]
  </Card>
  <Card title="[Journey 4]" icon="book" href="/[link-4]">
    [One-line outcome]
  </Card>
  <Card title="[Journey 5]" icon="life-ring" href="/[link-5]">
    [One-line outcome]
  </Card>
  <Card title="[Journey 6]" icon="gear" href="/[link-6]">
    [One-line outcome]
  </Card>
 </CardGroup>
 <CardGroup cols={3}>
  <Card title="[Journey 1]" icon="sparkles" href="/[link-3]">
    [One-line outcome]
  </Card>
  <Card title="[Journey 2]" icon="gear" href="/[link-4]">
    [One-line outcome]
  </Card>
  <Card title="[Journey 3]" icon="book" href="/[link-5]">
    [One-line outcome]
  </Card>
 </CardGroup>
 {/* Duplicate another CardGroup (2 or 3 columns) if you need more coverage, but keep the total ≤6 cards. */}
 <Tip>
  [Optional cross-link, e.g., “Self-hosting? Jump to the OSS overview.”] Delete if unused.
 </Tip>
@@ -14,6 +14,7 @@ Troubleshooting playbooks map symptoms to diagnostics and fixes. Keep them fast
 - Frontmatter must include `title`, `description`, `icon`. Lead with one sentence about the system or workflow this playbook covers.
 - Add an `<Info>` block (“Use this when…”) and a quick index table (Symptom, Likely cause, Fix link). Surface critical safety warnings in `<Warning>`.
 - Each symptom section needs: diagnostic command/snippet, `<Info icon="check">` expected output, `<Warning>` for the observed failure, numbered fix steps, and optional `<Tip>` for prevention.
 - If you’re migrating an existing playbook, carry forward the known failure modes and scripts—reformat them into this structure unless the troubleshooting path changed.
 - Group unrelated issues with horizontal rules and provide escalation guidance when self-service stops.
 - Conclude with prevention checklist, related docs, and the standard two-card CTA (concept/reference left, applied workflow right).