chore: updating the sdk version and changelog (#4561 )

Co-authored-by: Saket Aryan <saketaryan2002@gmail.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
fix(plugin): make Cursor plugin fully functional (#4547 )
2026-03-26 22:21:31 +05:30 · 2026-03-26 09:46:42 -07:00 · 2026-03-26 09:39:54 -07:00 · 2026-03-26 20:28:37 +05:30 · 2026-03-26 20:22:34 +05:30 · 2026-03-26 20:07:39 +05:30
63 changed files with 5313 additions and 876 deletions
@@ -0,0 +1,18 @@
+{
+  "name": "mem0-plugins",
+  "owner": {
+    "name": "Mem0",
+    "email": "support@mem0.ai"
+  },
+  "metadata": {
+    "description": "Official Mem0 plugins for Claude"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": "./mem0-plugin",
+      "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Claude workflows.",
+      "version": "0.1.0"
+    }
+  ]
+}
@@ -0,0 +1,18 @@
+{
+  "name": "mem0-plugins",
+  "owner": {
+    "name": "Mem0",
+    "email": "support@mem0.ai"
+  },
+  "metadata": {
+    "description": "Official Mem0 plugins for Cursor"
+  },
+  "plugins": [
+    {
+      "name": "mem0",
+      "source": "./mem0-plugin",
+      "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search.",
+      "version": "0.1.0"
+    }
+  ]
+}
@@ -8,20 +8,56 @@ mode: "wide"
 <Tabs>
 <Tab title="Python">

+<Update label="2026-03-26" description="v1.0.8">
+
+**New Features & Updates:**
+- **Vector Stores:** Integrated Turbopuffer as a vector database provider ([#4428](https://github.com/mem0ai/mem0/pull/4428))
+- **LLMs:** Added MiniMax LLM provider ([#4431](https://github.com/mem0ai/mem0/pull/4431))
+
+**Bug Fixes:**
+- **Core:** Fixed merging of multiple filter operators for the same key ([#4559](https://github.com/mem0ai/mem0/pull/4559))
+- **Core:** Prevented in-place mutation of metadata in `_create_memory` ([#4529](https://github.com/mem0ai/mem0/pull/4529))
+- **Core:** Preserved custom metadata when updating memory ([#4495](https://github.com/mem0ai/mem0/pull/4495))
+- **Core:** Handled chatty LLM responses in JSON parsing ([#4525](https://github.com/mem0ai/mem0/pull/4525))
+- **Core:** Prevented double embedding in `mem0.add` ([#3996](https://github.com/mem0ai/mem0/pull/3996))
+- **Core:** Raised `ValueError` when deleting nonexistent memory ([#4455](https://github.com/mem0ai/mem0/pull/4455))
+- **Core:** Cleaned up graph store data on `Memory.delete()` ([#4505](https://github.com/mem0ai/mem0/pull/4505))
+- **Vector Stores:** Prevented SQL injection in Databricks vector store ([#4558](https://github.com/mem0ai/mem0/pull/4558))
+- **Vector Stores:** Upgraded MongoDB vector store from deprecated `knnVector` to GA `vectorSearch` ([#3995](https://github.com/mem0ai/mem0/pull/3995))
+- **Vector Stores:** Prevented embedding corruption in Valkey and Redis when vector is `None` ([#4362](https://github.com/mem0ai/mem0/pull/4362))
+- **Vector Stores:** Accepted default `/tmp/chroma` path in `ChromaDbConfig` validator ([#4179](https://github.com/mem0ai/mem0/pull/4179))
+- **Vector Stores:** Wrapped vector and payload in lists for `Langchain.update` ([#4446](https://github.com/mem0ai/mem0/pull/4446))
+- **Graph:** Soft-delete graph relationships instead of hard `DELETE` ([#4188](https://github.com/mem0ai/mem0/pull/4188))
+- **Graph:** Sanitized hyphens in Neo4j Cypher relationship names ([#4154](https://github.com/mem0ai/mem0/pull/4154))
+- **Graph:** Used root LLM config as fallback for graph store instead of hardcoded OpenAI default ([#4466](https://github.com/mem0ai/mem0/pull/4466))
+- **Qdrant:** Fixed `do not remove local path on init` ([#4475](https://github.com/mem0ai/mem0/pull/4475))
+- **Qdrant:** Implemented enhanced metadata filtering operators ([#4127](https://github.com/mem0ai/mem0/pull/4127))
+- **Embeddings:** Fixed OpenAI embedding dimensions ([#4481](https://github.com/mem0ai/mem0/pull/4481))
+- **LLMs:** Omitted `topP` for Anthropic Converse in Bedrock; used `AWSBedrockConfig` in `LlmFactory` ([#4469](https://github.com/mem0ai/mem0/pull/4469))
+- **LLMs:** Avoided sending both `temperature` and `top_p` to Anthropic API ([#4471](https://github.com/mem0ai/mem0/pull/4471))
+- **LLMs:** Handled `None` content and empty candidates in `GeminiLLM` parsing ([#4462](https://github.com/mem0ai/mem0/pull/4462))
+- **LLMs:** Added missing `_parse_response` to `AzureOpenAIStructuredLLM` ([#4434](https://github.com/mem0ai/mem0/pull/4434))
+- **History:** Added timestamps for `DELETE` operations in history ([#4492](https://github.com/mem0ai/mem0/pull/4492))
+
+**Improvements:**
+- **Vector Stores:** Added vector validation to OpenSearchDB to ensure non-null, non-empty, and correct-dimension vectors ([#4472](https://github.com/mem0ai/mem0/pull/4472))
+
+</Update>
+
 <Update label="2026-03-19" description="v1.0.7">

 **Bug Fixes:**
- **Core:** Fixed control characters in LLM JSON responses causing parse failures (#4420)
- **Core:** Replaced hardcoded US/Pacific timezone references with `timezone.utc` (#4404)
- **Core:** Preserved `http_auth` in `_safe_deepcopy_config` for OpenSearch (#4418)
- **Core:** Normalized malformed LLM fact output before embedding (#4224)
- **Embeddings:** Pass `encoding_format='float'` in OpenAI embeddings for proxy compatibility (#4058)
- **LLMs:** Fixed Ollama to pass tools to `client.chat` and parse `tool_calls` from response (#4176)
- **Reranker:** Support nested LLM config in `LLMReranker` for non-OpenAI providers (#4405)
- **Vector Stores:** Cast `vector_distance` to float in Redis search (#4377)
+- **Core:** Fixed control characters in LLM JSON responses causing parse failures ([#4420](https://github.com/mem0ai/mem0/pull/4420))
+- **Core:** Replaced hardcoded US/Pacific timezone references with `timezone.utc` ([#4404](https://github.com/mem0ai/mem0/pull/4404))
+- **Core:** Preserved `http_auth` in `_safe_deepcopy_config` for OpenSearch ([#4418](https://github.com/mem0ai/mem0/pull/4418))
+- **Core:** Normalized malformed LLM fact output before embedding ([#4224](https://github.com/mem0ai/mem0/pull/4224))
+- **Embeddings:** Pass `encoding_format='float'` in OpenAI embeddings for proxy compatibility ([#4058](https://github.com/mem0ai/mem0/pull/4058))
+- **LLMs:** Fixed Ollama to pass tools to `client.chat` and parse `tool_calls` from response ([#4176](https://github.com/mem0ai/mem0/pull/4176))
+- **Reranker:** Support nested LLM config in `LLMReranker` for non-OpenAI providers ([#4405](https://github.com/mem0ai/mem0/pull/4405))
+- **Vector Stores:** Cast `vector_distance` to float in Redis search ([#4377](https://github.com/mem0ai/mem0/pull/4377))

 **Improvements:**
- **Embeddings:** Improved Ollama embedder with model name normalization and error handling (#4403)
+- **Embeddings:** Improved Ollama embedder with model name normalization and error handling ([#4403](https://github.com/mem0ai/mem0/pull/4403))

 </Update>

@@ -763,6 +799,20 @@ mode: "wide"

 <Tab title="TypeScript">

+<Update label="2026-03-26" description="v2.4.3">
+
+**New Features & Updates:**
+- **OSS:** Added pgvector support to NodeJS OSS `VectorStoreFactory` ([#3997](https://github.com/mem0ai/mem0/pull/3997))
+
+**Bug Fixes:**
+- **OSS:** Made pgvector `pg` import compatible with ESM ([#4544](https://github.com/mem0ai/mem0/pull/4544))
+- **OSS:** Registered pgvector in `VectorStoreFactory` ([#4502](https://github.com/mem0ai/mem0/pull/4502))
+- **OSS:** Used root LLM config as fallback for graph store instead of hardcoded OpenAI default ([#4466](https://github.com/mem0ai/mem0/pull/4466))
+- **OSS:** Fixed `toCamelCase` in Redis `get` method for the payload ([#3172](https://github.com/mem0ai/mem0/pull/3172))
+- **Client:** Fixed Zod Schema incompatibility with OpenAI Structured Outputs API ([#3462](https://github.com/mem0ai/mem0/pull/3462))
+
+</Update>
+
 <Update label="2026-03-19" description="v2.4.2">

 **Bug Fixes:**
@@ -7,58 +7,51 @@ When using LLM rerankers, you can customize the prompts used for ranking to bett

 ## Default Prompt

-The default LLM reranker prompt is designed to be general-purpose:
+The default LLM reranker prompt scores each memory individually on a 0.0-1.0 scale:

 ```
-Given a query and a list of memory entries, rank the memory entries based on their relevance to the query.
-Rate each memory on a scale of 1-10 where 10 is most relevant.
+You are a relevance scoring assistant. Given a query and a document, you need to score how relevant the document is to the query.

-Query: {query}
+Score the relevance on a scale from 0.0 to 1.0, where:
+- 1.0 = Perfectly relevant and directly answers the query
+- 0.8-0.9 = Highly relevant with good information
+- 0.6-0.7 = Moderately relevant with some useful information
+- 0.4-0.5 = Slightly relevant with limited useful information
+- 0.0-0.3 = Not relevant or no useful information

-Memory entries:
-{memories}
+Query: "{query}"
+Document: "{document}"

-Provide your ranking as a JSON array with scores for each memory.
+Provide only a single numerical score between 0.0 and 1.0. Do not include any explanation or additional text.
 ```

 ## Custom Prompt Configuration

-You can provide a custom prompt template when configuring the LLM reranker:
+You can provide a custom prompt template using the `scoring_prompt` parameter:

 ```python
 from mem0 import Memory

 custom_prompt = """
-You are an expert at ranking memories for a personal AI assistant.
-Given a user query and a list of memory entries, rank each memory based on:
-1. Direct relevance to the query
-2. Temporal relevance (recent memories may be more important)
-3. Emotional significance
-4. Actionability
+You are an expert at evaluating memories for a personal AI assistant.
+Given a user query and a memory entry, score how relevant the memory is.
+Consider direct relevance, temporal relevance, and actionability.

-Query: {query}
-User Context: {user_context}
+Query: "{query}"
+Memory: "{document}"

-Memory entries:
-{memories}
-
-Rate each memory from 1-10 and provide reasoning.
-Return as JSON: {{"rankings": [{{"index": 0, "score": 8, "reason": "..."}}]}}
+Provide only a single numerical score between 0.0 and 1.0.
 """

 config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
-            "llm": {
-                "provider": "openai",
-                "config": {
-                    "model": "gpt-4.1-nano-2025-04-14",
-                    "api_key": "your-openai-key"
-                }
-            },
-            "custom_prompt": custom_prompt,
-            "top_n": 5
+            "provider": "openai",
+            "model": "gpt-4o-mini",
+            "api_key": "your-openai-key",
+            "scoring_prompt": custom_prompt,
+            "top_k": 5
        }
    }
 }
@@ -70,12 +63,14 @@ memory = Memory.from_config(config)

 Your custom prompt can use the following variables:

-| Variable         | Description                           |
-| ---------------- | ------------------------------------- |
-| `{query}`        | The search query                      |
-| `{memories}`     | The list of memory entries to rank    |
-| `{user_id}`      | The user ID (if available)            |
-| `{user_context}` | Additional user context (if provided) |
+| Variable     | Description                   |
+| ------------ | ----------------------------- |
+| `{query}`    | The search query              |
+| `{document}` | The memory entry being scored |
+
+<Note>
+  Both `{query}` and `{document}` are required in your custom prompt. The LLM reranker scores each memory individually against the query, so the prompt is called once per candidate memory.
+</Note>

 ## Domain-Specific Examples

@@ -89,13 +84,10 @@ Prioritize memories that:
 - Show previous resolution patterns
 - Indicate customer preferences or constraints

-Query: {query}
-Customer Context: Previous interactions with this customer
+Query: "{query}"
+Memory: "{document}"

-Memories:
-{memories}
-
-Rank each memory 1-10 based on support relevance.
+Score relevance from 0.0 to 1.0.
 """
 ```

@@ -103,19 +95,16 @@ Rank each memory 1-10 based on support relevance.

 ```python
 educational_prompt = """
-Rank these learning memories for a student query.
+Score this learning memory for relevance to a student query.
 Consider:
 - Prerequisite knowledge requirements
 - Learning progression and difficulty
 - Relevance to current learning objectives

-Student Query: {query}
-Learning Context: {user_context}
+Student Query: "{query}"
+Memory: "{document}"

-Available memories:
-{memories}
-
-Score each memory for educational value (1-10).
+Score educational relevance from 0.0 to 1.0.
 """
 ```

@@ -123,73 +112,64 @@ Score each memory for educational value (1-10).

 ```python
 personal_assistant_prompt = """
-Rank personal memories for relevance to the user's query.
+Score this personal memory for relevance to the user's query.
 Consider:
 - Recent vs. historical importance
 - Personal preferences and habits
- Contextual relationships between memories
+- Contextual relationships

-Query: {query}
-Personal context: {user_context}
+Query: "{query}"
+Memory: "{document}"

-Memories to rank:
-{memories}
-
-Provide relevance scores (1-10) with brief explanations.
+Provide relevance score from 0.0 to 1.0.
 """
 ```

 ## Advanced Prompt Techniques

-### Multi-Criteria Ranking
+### Multi-Criteria Scoring

 ```python
 multi_criteria_prompt = """
-Evaluate memories using multiple criteria:
+Evaluate this memory using multiple criteria:

 1. RELEVANCE (40%): How directly related to the query
-2. RECENCY (20%): How recent the memory is
+2. RECENCY (20%): How recent the memory appears to be
 3. IMPORTANCE (25%): Personal or business significance
 4. ACTIONABILITY (15%): How useful for next steps

-Query: {query}
-Context: {user_context}
+Query: "{query}"
+Memory: "{document}"

-Memories:
-{memories}
-
-For each memory, provide:
- Overall score (1-10)
- Breakdown by criteria
- Final ranking recommendation
-
-Format: JSON with detailed scoring
+Compute a weighted score from 0.0 to 1.0 based on these criteria.
+Provide only the final numerical score.
 """
 ```

-### Contextual Ranking
+### Chain-of-Thought Scoring

 ```python
-contextual_prompt = """
-Consider the following context when ranking memories:
- Current user situation: {user_context}
- Time of day: {current_time}
- Recent activities: {recent_activities}
+reasoning_prompt = """
+Evaluate this memory's relevance step by step:

-Query: {query}
+1. What is the main intent of the query?
+2. What key information does the memory contain?
+3. How directly does the memory address the query?

-Rank these memories considering both direct relevance and contextual appropriateness:
-{memories}
+Based on this analysis, provide a single relevance score from 0.0 to 1.0.

-Provide contextually-aware relevance scores (1-10).
+Query: "{query}"
+Memory: "{document}"
+
+Score:
 """
 ```

 ## Best Practices

 1. **Be Specific**: Clearly define what makes a memory relevant for your use case
-2. **Use Examples**: Include examples in your prompt for better model understanding
-3. **Structure Output**: Specify the exact JSON format you want returned
+2. **Use 0.0-1.0 Scale**: The score extractor expects values between 0.0 and 1.0
+3. **Request Only the Score**: Ask for just the numerical score to improve extraction reliability
 4. **Test Iteratively**: Refine your prompt based on actual ranking performance
 5. **Consider Token Limits**: Keep prompts concise while being comprehensive

@@ -206,7 +186,7 @@ prompts = [
 ]

 for i, prompt in enumerate(prompts):
-    config["reranker"]["config"]["custom_prompt"] = prompt
+    config["reranker"]["config"]["scoring_prompt"] = prompt
    memory = Memory.from_config(config)

    results = memory.search("test query", user_id="test_user")
@@ -216,6 +196,6 @@ for i, prompt in enumerate(prompts):
 ## Common Issues

 - **Too Long**: Keep prompts under token limits for your chosen LLM
- **Too Vague**: Be specific about ranking criteria
- **Inconsistent Format**: Ensure JSON output format is clearly specified
- **Missing Context**: Include relevant variables for your use case
+- **Too Vague**: Be specific about scoring criteria
+- **Wrong Scale**: Use 0.0-1.0 scale to match the default score extractor
+- **Extra Output**: Ask for only the numeric score — extra text can confuse score extraction
@@ -18,13 +18,9 @@ config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
-            "llm": {
-                "provider": "openai",
-                "config": {
-                    "model": "gpt-4",
-                    "api_key": "your-openai-api-key"
-                }
-            }
+            "provider": "openai",
+            "model": "gpt-4o-mini",
+            "api_key": "your-openai-api-key"
        }
    }
 }
@@ -36,11 +32,14 @@ m = Memory.from_config(config)

 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `llm` | dict | Required | LLM configuration object |
-| `top_k` | int | 10 | Number of results to rerank |
+| `provider` | str | `"openai"` | LLM provider (openai, anthropic, etc.) |
+| `model` | str | `"gpt-4o-mini"` | LLM model to use for reranking |
+| `api_key` | str | None | API key for the LLM provider |
+| `top_k` | int | None | Number of top documents to return after reranking |
 | `temperature` | float | 0.0 | LLM temperature for consistency |
-| `custom_prompt` | str | None | Custom reranking prompt |
-| `score_range` | tuple | (0, 10) | Score range for relevance |
+| `max_tokens` | int | 100 | Maximum tokens for LLM response |
+| `scoring_prompt` | str | None | Custom prompt template for scoring documents |
+| `llm` | dict | None | Optional nested LLM config for provider-specific fields (e.g., `ollama_base_url`, `azure_endpoint`). Overrides top-level `provider`/`model`/`api_key` when provided. |

 ### Advanced Configuration

@@ -49,20 +48,19 @@ config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
-            "llm": {
-                "provider": "anthropic",
-                "config": {
-                    "model": "claude-3-sonnet-20240229",
-                    "api_key": "your-anthropic-api-key"
-                }
-            },
+            "provider": "anthropic",
+            "model": "claude-sonnet-4-20250514",
+            "api_key": "your-anthropic-api-key",
            "top_k": 15,
            "temperature": 0.0,
-            "score_range": (1, 5),
-            "custom_prompt": """
-            Rate the relevance of each memory to the query on a scale of 1-5.
+            "scoring_prompt": """
+            Rate the relevance of each memory to the query on a scale of 0.0-1.0.
            Consider semantic similarity, context, and practical utility.
            Only provide the numeric score.
+
+            Query: "{query}"
+            Document: "{document}"
+            Score:
            """
        }
    }
@@ -78,14 +76,10 @@ config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
-            "llm": {
-                "provider": "openai",
-                "config": {
-                    "model": "gpt-4",
-                    "api_key": "your-openai-api-key",
-                    "temperature": 0.0
-                }
-            }
+            "provider": "openai",
+            "model": "gpt-4o-mini",
+            "api_key": "your-openai-api-key",
+            "temperature": 0.0
        }
    }
 }
@@ -98,13 +92,9 @@ config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
-            "llm": {
-                "provider": "anthropic",
-                "config": {
-                    "model": "claude-3-sonnet-20240229",
-                    "api_key": "your-anthropic-api-key"
-                }
-            }
+            "provider": "anthropic",
+            "model": "claude-sonnet-4-20250514",
+            "api_key": "your-anthropic-api-key"
        }
    }
 }
@@ -117,10 +107,12 @@ config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
+            "provider": "ollama",
+            "model": "llama3.2",
            "llm": {
                "provider": "ollama",
                "config": {
-                    "model": "llama2",
+                    "model": "llama3.2",
                    "ollama_base_url": "http://localhost:11434"
                }
            }
@@ -129,6 +121,10 @@ config = {
 }
 ```

+<Note>
+  For providers like Ollama that need extra fields (e.g., `ollama_base_url`), use the optional nested `llm` key to pass provider-specific configuration. The nested `llm` config overrides top-level `provider`/`model`/`api_key` when provided.
+</Note>
+
 ### Azure OpenAI

 ```python
@@ -136,13 +132,16 @@ config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
+            "provider": "azure_openai",
+            "model": "gpt-4o-mini",
+            "api_key": "your-azure-api-key",
            "llm": {
                "provider": "azure_openai",
                "config": {
-                    "model": "gpt-4",
+                    "model": "gpt-4o-mini",
                    "api_key": "your-azure-api-key",
                    "azure_endpoint": "https://your-resource.openai.azure.com/",
-                    "azure_deployment": "gpt-4-deployment"
+                    "azure_deployment": "gpt-4o-mini-deployment"
                }
            }
        }
@@ -154,16 +153,22 @@ config = {

 ### Default Prompt Behavior

-The default prompt asks the LLM to score relevance on a 0-10 scale:
+The default prompt asks the LLM to score relevance on a 0.0-1.0 scale:

 ```
-Given a query and a memory, rate how relevant the memory is to answering the query.
-Score from 0 (completely irrelevant) to 10 (perfectly relevant).
-Only provide the numeric score.
+You are a relevance scoring assistant. Given a query and a document, you need to score how relevant the document is to the query.

-Query: {query}
-Memory: {memory}
-Score:
+Score the relevance on a scale from 0.0 to 1.0, where:
+- 1.0 = Perfectly relevant and directly answers the query
+- 0.8-0.9 = Highly relevant with good information
+- 0.6-0.7 = Moderately relevant with some useful information
+- 0.4-0.5 = Slightly relevant with limited useful information
+- 0.0-0.3 = Not relevant or no useful information
+
+Query: "{query}"
+Document: "{document}"
+
+Provide only a single numerical score between 0.0 and 1.0. Do not include any explanation or additional text.
 ```

 ### Custom Prompt Examples
@@ -174,14 +179,14 @@ Score:
 custom_prompt = """
 You are a medical information specialist. Rate how relevant each memory is for answering the medical query.
 Consider clinical accuracy, specificity, and practical applicability.
-Rate from 1-10 where:
- 1-3: Irrelevant or potentially harmful
- 4-6: Somewhat relevant but incomplete
- 7-8: Relevant and helpful
- 9-10: Highly relevant and clinically useful
+Rate from 0.0 to 1.0 where:
+- 0.0-0.3: Irrelevant or potentially harmful
+- 0.4-0.6: Somewhat relevant but incomplete
+- 0.7-0.8: Relevant and helpful
+- 0.9-1.0: Highly relevant and clinically useful

-Query: {query}
-Memory: {memory}
+Query: "{query}"
+Document: "{document}"
 Score:
 """

@@ -189,14 +194,10 @@ config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
-            "llm": {
-                "provider": "openai",
-                "config": {
-                    "model": "gpt-4",
-                    "api_key": "your-api-key"
-                }
-            },
-            "custom_prompt": custom_prompt
+            "provider": "openai",
+            "model": "gpt-4o-mini",
+            "api_key": "your-api-key",
+            "scoring_prompt": custom_prompt
        }
    }
 }
@@ -213,15 +214,15 @@ Consider:
 - Recency and accuracy
 - Practical usefulness

-Rate 1-5:
-1 = Not relevant
-2 = Slightly relevant
-3 = Moderately relevant
-4 = Very relevant
-5 = Perfectly answers the question
+Rate 0.0-1.0:
+0.0 = Not relevant
+0.25 = Slightly relevant
+0.5 = Moderately relevant
+0.75 = Very relevant
+1.0 = Perfectly answers the question

-Query: {query}
-Memory: {memory}
+Query: "{query}"
+Document: "{document}"
 Score:
 """
 ```
@@ -239,13 +240,17 @@ Consider:
 - Factual accuracy
 - Conversation flow

-Rate 0-10:
-Query: {query}
-Memory: {memory}
+Rate 0.0-1.0:
+Query: "{query}"
+Document: "{document}"
 Score:
 """
 ```

+<Note>
+  Custom prompts must include `{query}` and `{document}` placeholders. The LLM response should contain a numerical score which is automatically extracted.
+</Note>
+
 ## Usage Examples

 ### Basic Usage
@@ -295,9 +300,9 @@ results = safe_llm_rerank_search("What are my preferences?", "alice")

 | Model Type | Speed | Quality | Cost | Best For |
 |------------|-------|---------|------|----------|
-| GPT-3.5 Turbo | Fast | Good | Low | High-volume applications |
-| GPT-4 | Medium | Excellent | Medium | Quality-critical applications |
-| Claude 3 Sonnet | Medium | Excellent | Medium | Balanced performance |
+| GPT-4o mini | Fast | Good | Low | High-volume applications |
+| GPT-4o | Medium | Excellent | Medium | Quality-critical applications |
+| Claude Sonnet | Medium | Excellent | Medium | Balanced performance |
 | Ollama Local | Variable | Good | Free | Privacy-sensitive applications |

 ### Optimization Strategies
@@ -308,14 +313,10 @@ fast_config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
-            "llm": {
-                "provider": "openai",
-                "config": {
-                    "model": "gpt-3.5-turbo",
-                    "api_key": "your-api-key"
-                }
-            },
-            "top_k": 5,  # Limit candidates
+            "provider": "openai",
+            "model": "gpt-4o-mini",
+            "api_key": "your-api-key",
+            "top_k": 5,
            "temperature": 0.0
        }
    }
@@ -326,13 +327,9 @@ quality_config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
-            "llm": {
-                "provider": "openai",
-                "config": {
-                    "model": "gpt-4",
-                    "api_key": "your-api-key"
-                }
-            },
+            "provider": "openai",
+            "model": "gpt-4o",
+            "api_key": "your-api-key",
            "top_k": 15,
            "temperature": 0.0
        }
@@ -353,10 +350,10 @@ Evaluate this memory's relevance using multi-step reasoning:
 3. How directly does the memory address the query?
 4. What additional context might be needed?

-Based on this analysis, rate relevance 1-10:
+Based on this analysis, rate relevance 0.0-1.0:

-Query: {query}
-Memory: {memory}
+Query: "{query}"
+Document: "{document}"

 Analysis:
 Step 1 (Intent):
@@ -367,42 +364,6 @@ Final Score:
 """
 ```

-### Comparative Ranking
-
-```python
-comparative_prompt = """
-You will see a query and multiple memories. Rank them in order of relevance.
-Consider which memories best answer the question and would be most helpful.
-
-Query: {query}
-
-Memories to rank:
-{memories}
-
-Provide scores 1-10 for each memory, considering their relative usefulness.
-"""
-```
-
-### Emotional Intelligence
-
-```python
-emotional_prompt = """
-Consider both factual relevance and emotional appropriateness.
-Rate how suitable this memory is for responding to the user's query.
-
-Factors to consider:
- Factual accuracy and relevance
- Emotional tone and sensitivity
- User's likely emotional state
- Appropriateness of response
-
-Query: {query}
-Memory: {memory}
-Emotional Context: {context}
-Score (1-10):
-"""
-```
-
 ## Error Handling and Fallbacks

 ```python
@@ -433,14 +394,22 @@ class RobustLLMReranker:
 primary_config = {
    "reranker": {
        "provider": "llm_reranker",
-        "config": {"llm": {"provider": "openai", "config": {"model": "gpt-4"}}}
+        "config": {
+            "provider": "openai",
+            "model": "gpt-4o",
+            "api_key": "your-api-key"
+        }
    }
 }

 fallback_config = {
    "reranker": {
        "provider": "llm_reranker",
-        "config": {"llm": {"provider": "openai", "config": {"model": "gpt-3.5-turbo"}}}
+        "config": {
+            "provider": "openai",
+            "model": "gpt-4o-mini",
+            "api_key": "your-api-key"
+        }
    }
 }

@@ -486,4 +455,4 @@ results = reranker.search("What are my preferences?", "alice")
  <Card title="Performance Optimization" icon="bolt" href="/components/rerankers/optimization">
    Optimize LLM reranker performance
  </Card>
-</CardGroup>
+</CardGroup>
@@ -52,7 +52,7 @@ Here are the parameters available for configuring FAISS:
 | Parameter | Description | Default Value |
 | --- | --- | --- |
 | `collection_name` | The name of the collection | `mem0` |
-| `path` | Path to store FAISS index and metadata | `~/.local/share/mem0/faiss/<collection_name>` |
+| `path` | Path to store FAISS index and metadata | `/tmp/faiss/<collection_name>` |
 | `distance_strategy` | Distance metric strategy to use (options: 'euclidean', 'inner_product', 'cosine') | `euclidean` |
 | `normalize_L2` | Whether to normalize L2 vectors (only applicable for euclidean distance) | `False` |

@@ -73,7 +73,7 @@ Let's see the available parameters for the `qdrant` config:
 | `client` | Custom client for qdrant | `None` |
 | `host` | The host where the qdrant server is running | `None` |
 | `port` | The port where the qdrant server is running | `None` |
-| `path` | Path for the qdrant database | `~/.local/share/mem0/qdrant` |
+| `path` | Path for the qdrant database | `/tmp/qdrant` |
 | `url` | Full URL for the qdrant server | `None` |
 | `api_key` | API key for the qdrant server | `None` |
 | `on_disk` | For enabling persistent storage | `False` |
@@ -85,7 +85,7 @@ Let's see the available parameters for the `qdrant` config:
 | `embeddingModelDims` | Dimensions of the embedding model | `1536` |
 | `host` | The host where the Qdrant server is running | `None` |
 | `port` | The port where the Qdrant server is running | `None` |
-| `path` | Path for the Qdrant database | `~/.local/share/mem0/qdrant` |
+| `path` | Path for the Qdrant database | `/tmp/qdrant` |
 | `url` | Full URL for the Qdrant server | `None` |
 | `apiKey` | API key for the Qdrant server | `None` |
 | `onDisk` | For enabling persistent storage | `False` |
@@ -123,13 +123,9 @@ config = {
    "reranker": {
        "provider": "llm_reranker",
        "config": {
-            "llm": {
-                "provider": "openai",
-                "config": {
-                    "model": "gpt-4",
-                    "api_key": "your-openai-api-key"
-                }
-            },
+            "provider": "openai",
+            "model": "gpt-4o-mini",
+            "api_key": "your-openai-api-key",
            "top_k": 5
        }
    }
@@ -13,6 +13,10 @@ The Mem0 REST API server exposes every OSS memory operation over HTTP. Run it al
  - You plan to explore or debug endpoints through the built-in OpenAPI page at `/docs`.
 </Info>

+<Warning>
+  **OSS vs Platform API paths:** The self-hosted OSS server does **not** use the `/v1/` prefix. For example, the endpoint is `POST /memories`, not `POST /v1/memories/`. The [API Reference](/api-reference) documents the hosted platform at `api.mem0.ai` which uses `/v1/` paths — those do not apply to the OSS server.
+</Warning>
+
 <Warning>
  Enable API key authentication (see below) and HTTPS before exposing the server to anything beyond your internal network.
 </Warning>
@@ -147,13 +151,18 @@ curl -X POST http://localhost:8000/memories \
 </Info>

 ```bash
-curl "http://localhost:8000/memories/search?user_id=alice&query=vegetable"
+curl -X POST http://localhost:8000/search \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "vegetable",
+    "user_id": "alice"
+  }'
 ```

 ### Explore with OpenAPI docs

-1. Navigate to `http://localhost:8000/docs`.  
-2. Pick an endpoint (e.g., `POST /memories/search`).  
+1. Navigate to `http://localhost:8000/docs`.
+2. Pick an endpoint (e.g., `POST /search`).  
 3. Fill in parameters and click **Execute** to try requests in-browser.

 <Tip>
@@ -162,6 +171,25 @@ curl "http://localhost:8000/memories/search?user_id=alice&query=vegetable"

 ---

+## Endpoint reference
+
+The OSS REST server exposes the following endpoints. None use the `/v1/` prefix.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/configure` | Set memory configuration |
+| `POST` | `/memories` | Create memories |
+| `GET` | `/memories` | Get all memories (filter by `user_id`, `agent_id`, or `run_id`) |
+| `GET` | `/memories/{memory_id}` | Get a specific memory |
+| `PUT` | `/memories/{memory_id}` | Update a memory |
+| `DELETE` | `/memories/{memory_id}` | Delete a specific memory |
+| `DELETE` | `/memories` | Delete all memories for an identifier |
+| `GET` | `/memories/{memory_id}/history` | Get memory history |
+| `POST` | `/search` | Search memories |
+| `POST` | `/reset` | Reset all memories |
+
+---
+
 ## Verify the feature is working

 - Hit the root route and `/docs` to confirm the server is reachable.
@@ -77,7 +77,7 @@ Mem0 Open Source delivers the same adaptive memory engine as the platform, but p
  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 `~/.local/share/mem0/qdrant`
+  - 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

@@ -81,7 +81,7 @@ print(results)
 By default `Memory()` wires up:
 - OpenAI `gpt-4.1-nano-2025-04-14` for fact extraction and updates
 - OpenAI `text-embedding-3-small` embeddings (1536 dimensions)
- Qdrant vector store with on-disk data at `~/.local/share/mem0/qdrant`
+- Qdrant vector store with on-disk data at `/tmp/qdrant`
 - SQLite history at `~/.mem0/history.db`
 - No reranker (add one in the config when you need it)
 </Note>
@@ -4,7 +4,7 @@
 		"title": "Mem0 API Docs",
 		"description": "mem0.ai API Docs",
 		"contact": {
-			"email": "deshraj@mem0.ai"
+			"email": "support@mem0.ai"
 		},
 		"license": {
 			"name": "Apache 2.0"
@@ -1,6 +1,6 @@
 ---
 title: Integration Guide Template
-description: "Pattern for pairing Mem0 with third-party tools."
+description: "A reusable template for writing integration guides that pair Mem0 with third-party tools and services."
 icon: "plug"
 ---

@@ -0,0 +1,13 @@
+{
+  "name": "mem0",
+  "version": "0.1.0",
+  "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search to Claude workflows using the Mem0 Platform MCP server.",
+  "author": {
+    "name": "Mem0",
+    "email": "support@mem0.ai"
+  },
+  "homepage": "https://mem0.ai",
+  "repository": "https://github.com/mem0ai/mem0",
+  "logo": "logo.svg",
+  "license": "Apache-2.0"
+}
@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "mem0": {
+      "url": "https://mcp.mem0.ai/mcp/",
+      "headers": {
+        "Authorization": "Token ${env:MEM0_API_KEY}"
+      }
+    }
+  }
+}
@@ -0,0 +1,17 @@
+{
+  "name": "mem0",
+  "version": "0.1.0",
+  "description": "Mem0 memory layer for AI applications. Add persistent memory, personalization, and semantic search using the Mem0 Platform MCP server.",
+  "author": {
+    "name": "Mem0",
+    "email": "support@mem0.ai"
+  },
+  "homepage": "https://mem0.ai",
+  "repository": "https://github.com/mem0ai/mem0",
+  "logo": "logo.svg",
+  "license": "Apache-2.0",
+  "keywords": ["mem0", "memory", "mcp", "personalization", "semantic-search"],
+  "skills": "./skills/",
+  "hooks": "./hooks/cursor-hooks.json",
+  "mcpServers": ".cursor-mcp.json"
+}
@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "mem0": {
+      "type": "http",
+      "url": "https://mcp.mem0.ai/mcp/",
+      "headers": {
+        "Authorization": "Token ${MEM0_API_KEY}"
+      }
+    }
+  }
+}
@@ -0,0 +1,117 @@
+# Mem0 Plugin for Claude Code, Claude Cowork & Cursor
+
+Add persistent memory to your AI workflows. Store, retrieve, and manage memories across sessions using the Mem0 Platform. Works with **Claude Code** (CLI), **Claude Cowork** (desktop app), and **Cursor**.
+
+## Step 1: Set your API key
+
+> **You must complete this step before installing the plugin.**
+
+1. Sign up at [app.mem0.ai](https://app.mem0.ai) if you haven't already
+2. Go to [app.mem0.ai/dashboard/api-keys](https://app.mem0.ai/dashboard/api-keys)
+3. Click **Create API Key** and copy the key (starts with `m0-`)
+4. Add it to your shell profile:
+
+   ```bash
+   # For zsh (default on macOS)
+   echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.zshrc
+   source ~/.zshrc
+
+   # For bash
+   echo 'export MEM0_API_KEY="m0-your-api-key"' >> ~/.bashrc
+   source ~/.bashrc
+   ```
+
+5. Confirm it's set:
+
+   ```bash
+   echo $MEM0_API_KEY
+   # Should print: m0-your-api-key
+   ```
+
+## Step 2: Install the plugin
+
+Choose one of the options below. All require `MEM0_API_KEY` to be set first (see above).
+
+### Claude Code (CLI) / Claude Cowork (Desktop)
+
+Claude Code and Claude Cowork share the same plugin system.
+
+**CLI:**
+
+```
+/plugin marketplace add mem0ai/mem0
+/plugin install mem0@mem0-plugins
+```
+
+**Cowork desktop app:** Open the Cowork tab, click **Customize** in the sidebar, click **Browse plugins**, and install Mem0.
+
+This installs the full plugin including the MCP server, lifecycle hooks (automatic memory capture), and the Mem0 SDK skill.
+
+### Cursor
+
+> **Already have `mem0` configured as an MCP server?** Remove the existing entry from your Cursor MCP settings before installing to avoid duplicate tools.
+
+**Option A — One-click deeplink** (installs MCP server only):
+
+[Install Mem0 MCP in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=mem0&config=eyJtY3BTZXJ2ZXJzIjp7Im1lbTAiOnsidXJsIjoiaHR0cHM6Ly9tY3AubWVtMC5haS9tY3AvIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiVG9rZW4gJHtlbnY6TUVNMF9BUElfS0VZfSJ9fX19)
+
+**Option B — Manual configuration** (MCP server only):
+
+Add the following to your `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mem0": {
+      "url": "https://mcp.mem0.ai/mcp/",
+      "headers": {
+        "Authorization": "Token ${env:MEM0_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Option C — Cursor Marketplace** (full plugin with hooks and skills):
+
+Install from the [Cursor Marketplace](https://cursor.com/marketplace) for the complete experience including lifecycle hooks and the Mem0 SDK skill.
+
+## Verify it works
+
+After installing, confirm the MCP server is connected:
+
+1. Start a new session (or restart your current one)
+2. Ask: *"List my mem0 entities"* or *"Search my memories for hello"*
+3. If the `mem0` tools appear and respond, you're all set
+
+## What's included
+
+| Component | Claude Code / Cowork | Cursor (Marketplace) | Cursor (Deeplink/Manual) |
+|-----------|:--------------------:|:--------------------:|:------------------------:|
+| MCP Server | Yes | Yes | Yes |
+| Lifecycle Hooks | Yes | Yes | No |
+| Mem0 SDK Skill | Yes | Yes | No |
+
+- **MCP Server** — Connects to the Mem0 remote MCP server (`mcp.mem0.ai`), providing tools to add, search, update, and delete memories. No local dependencies required.
+- **Lifecycle Hooks** — Automatic memory capture at key points: session start, context compaction, task completion, and session end.
+- **Mem0 SDK Skill** — Guides the AI on how to integrate the Mem0 SDK (Python & TypeScript) into your applications.
+
+## MCP Tools
+
+Once installed, the following tools are available:
+
+| Tool | Description |
+|------|-------------|
+| `add_memory` | Save text or conversation history for a user/agent |
+| `search_memories` | Semantic search across memories with filters |
+| `get_memories` | List memories with filters and pagination |
+| `get_memory` | Retrieve a specific memory by ID |
+| `update_memory` | Overwrite a memory's text by ID |
+| `delete_memory` | Delete a single memory by ID |
+| `delete_all_memories` | Bulk delete all memories in scope |
+| `delete_entities` | Delete a user/agent/app/run entity and its memories |
+| `list_entities` | List users/agents/apps/runs stored in Mem0 |
+
+## License
+
+Apache-2.0
@@ -0,0 +1,37 @@
+{
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "${CURSOR_PLUGIN_ROOT}/scripts/on_session_start.sh",
+        "matcher": "startup|resume|compact"
+      }
+    ],
+    "preToolUse": [
+      {
+        "command": "${CURSOR_PLUGIN_ROOT}/scripts/block_memory_write.sh",
+        "matcher": "Write|Edit"
+      }
+    ],
+    "preCompact": [
+      {
+        "command": "${CURSOR_PLUGIN_ROOT}/scripts/on_pre_compact.sh"
+      },
+      {
+        "command": "python3 ${CURSOR_PLUGIN_ROOT}/scripts/on_pre_compact.py",
+        "timeout": 30
+      }
+    ],
+    "stop": [
+      {
+        "command": "${CURSOR_PLUGIN_ROOT}/scripts/on_stop.sh",
+        "timeout": 10
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "${CURSOR_PLUGIN_ROOT}/scripts/on_user_prompt.sh",
+        "timeout": 5
+      }
+    ]
+  }
+}
@@ -0,0 +1,79 @@
+{
+  "description": "Mem0 memory capture hooks — automatic memory extraction at key lifecycle points",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/on_session_start.sh",
+            "statusMessage": "Loading mem0 context..."
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/block_memory_write.sh"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/on_pre_compact.sh",
+            "statusMessage": "Preparing pre-compaction summary..."
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/scripts/on_pre_compact.py",
+            "statusMessage": "Saving session state to mem0...",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/on_stop.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/on_user_prompt.sh",
+            "statusMessage": "Searching mem0 memories...",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/on_task_completed.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -0,0 +1,19 @@
+<svg width="307" height="307" viewBox="0 0 307 307" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M162.496 25.3505C165.003 25.3505 167.453 24.6071 169.538 23.2144C171.622 21.8216 173.247 19.8419 174.206 17.5258C175.165 15.2097 175.416 12.6612 174.927 10.2024C174.438 7.74365 173.231 5.48516 171.458 3.71249C169.686 1.93983 167.427 0.73263 164.968 0.243552C162.51 -0.245525 159.961 0.00550576 157.645 0.964866C155.329 1.92423 153.349 3.54885 151.956 5.63328C150.564 7.71772 149.82 10.1683 149.82 12.6753C149.818 14.3404 150.145 15.9895 150.781 17.5283C151.417 19.0671 152.351 20.4653 153.528 21.6427C154.706 22.8201 156.104 23.7537 157.643 24.39C159.181 25.0262 160.83 25.3526 162.496 25.3505Z" fill="white"/>
+<path d="M69.3342 56.559C71.1066 54.7862 72.3135 52.5277 72.8024 50.069C73.2913 47.6103 73.0401 45.0619 72.0807 42.7459C71.1213 40.43 69.4967 38.4505 67.4123 37.0579C65.3279 35.6652 62.8774 34.9219 60.3706 34.9219C57.8637 34.9219 55.4132 35.6652 53.3288 37.0579C51.2444 38.4505 49.6198 40.43 48.6604 42.7459C47.701 45.0619 47.4498 47.6103 47.9387 50.069C48.4276 52.5277 49.6345 54.7862 51.4069 56.559C52.5839 57.7363 53.9813 58.6701 55.5193 59.3073C57.0573 59.9444 58.7058 60.2724 60.3706 60.2724C62.0353 60.2724 63.6838 59.9444 65.2218 59.3073C66.7598 58.6701 68.1572 57.7363 69.3342 56.559Z" fill="white"/>
+<path d="M25.3505 144.504C25.3505 141.997 24.6071 139.547 23.2143 137.462C21.8216 135.378 19.842 133.753 17.5259 132.794C15.2098 131.835 12.6612 131.584 10.2024 132.073C7.74368 132.562 5.48513 133.769 3.71247 135.542C1.9398 137.314 0.732655 139.573 0.243578 142.032C-0.2455 144.49 0.00543354 147.039 0.964793 149.355C1.92415 151.671 3.54877 153.651 5.63321 155.044C7.71764 156.436 10.1683 157.18 12.6752 157.18C16.0369 157.18 19.261 155.844 21.638 153.467C24.0151 151.09 25.3505 147.866 25.3505 144.504Z" fill="white"/>
+<path d="M56.5589 237.749C54.7862 235.976 52.5277 234.769 50.069 234.28C47.6103 233.792 45.0619 234.043 42.7459 235.002C40.43 235.962 38.4505 237.586 37.0579 239.671C35.6652 241.755 34.9219 244.206 34.9219 246.712C34.9219 249.219 35.6652 251.67 37.0579 253.754C38.4505 255.838 40.43 257.463 42.7459 258.423C45.0619 259.382 47.6103 259.633 50.069 259.144C52.5277 258.655 54.7862 257.448 56.5589 255.676C57.7362 254.499 58.6701 253.102 59.3073 251.564C59.9444 250.026 60.2724 248.377 60.2724 246.712C60.2724 245.048 59.9444 243.399 59.3073 241.861C58.6701 240.323 57.7362 238.926 56.5589 237.749Z" fill="white"/>
+<path d="M144.488 281.648C141.981 281.648 139.53 282.392 137.446 283.785C135.361 285.177 133.737 287.157 132.777 289.473C131.818 291.789 131.567 294.338 132.056 296.797C132.545 299.255 133.752 301.514 135.525 303.286C137.298 305.059 139.556 306.266 142.015 306.755C144.474 307.244 147.022 306.993 149.338 306.034C151.655 305.075 153.634 303.45 155.027 301.366C156.42 299.281 157.163 296.831 157.163 294.324C157.159 290.963 155.822 287.742 153.446 285.366C151.07 282.989 147.848 281.653 144.488 281.648Z" fill="white"/>
+<path d="M237.751 250.487C235.978 252.26 234.771 254.518 234.282 256.977C233.794 259.435 234.045 261.984 235.004 264.3C235.964 266.616 237.588 268.595 239.673 269.988C241.757 271.381 244.207 272.124 246.714 272.124C249.221 272.124 251.672 271.381 253.756 269.988C255.84 268.595 257.465 266.616 258.424 264.3C259.384 261.984 259.635 259.435 259.146 256.977C258.657 254.518 257.45 252.26 255.678 250.487C254.501 249.31 253.104 248.376 251.566 247.739C250.028 247.101 248.379 246.773 246.714 246.773C245.05 246.773 243.401 247.101 241.863 247.739C240.325 248.376 238.928 249.31 237.751 250.487Z" fill="white"/>
+<path d="M281.648 162.512C281.648 165.019 282.392 167.469 283.785 169.554C285.177 171.638 287.157 173.263 289.473 174.222C291.789 175.181 294.338 175.432 296.797 174.943C299.255 174.454 301.514 173.247 303.286 171.474C305.059 169.702 306.266 167.443 306.755 164.984C307.244 162.526 306.993 159.977 306.034 157.661C305.075 155.345 303.45 153.365 301.366 151.973C299.281 150.58 296.831 149.836 294.324 149.836C290.962 149.836 287.738 151.172 285.361 153.549C282.984 155.926 281.648 159.15 281.648 162.512Z" fill="white"/>
+<path d="M250.471 69.3303C252.244 71.1027 254.503 72.3097 256.961 72.7985C259.42 73.2874 261.968 73.0363 264.284 72.0768C266.6 71.1174 268.58 69.4928 269.972 67.4084C271.365 65.324 272.108 62.8735 272.108 60.3667C272.108 57.8599 271.365 55.4093 269.972 53.3249C268.58 51.2406 266.6 49.616 264.284 48.6565C261.968 47.6971 259.42 47.4459 256.961 47.9348C254.503 48.4236 252.244 49.6306 250.471 51.403C249.294 52.58 248.36 53.9775 247.723 55.5155C247.086 57.0535 246.758 58.7019 246.758 60.3667C246.758 62.0314 247.086 63.6799 247.723 65.2179C248.36 66.7559 249.294 68.1533 250.471 69.3303Z" fill="white"/>
+<path d="M184.782 60.8054C180.168 63.4713 178.3 69.0427 177.63 74.3267C177.047 78.9358 175.033 83.2457 171.87 86.6488C168.707 90.052 164.556 92.3766 160.002 93.2951C155.448 94.2136 150.721 93.6796 146.487 91.7683C142.252 89.857 138.724 86.6649 136.401 82.642C134.077 78.6192 133.075 73.9684 133.535 69.3455C133.995 64.7226 135.895 60.3607 138.966 56.8748C142.037 53.389 146.125 50.9549 150.653 49.9159C155.181 48.8768 159.921 49.2852 164.204 51.0834C169.121 53.1428 174.884 54.2762 179.514 51.6422C184.143 49.0082 185.995 43.4049 186.665 38.1208C187.245 33.5107 189.257 29.1987 192.418 25.7931C195.579 22.3876 199.73 20.0603 204.284 19.1394C208.838 18.2185 213.567 18.7505 217.803 20.6605C222.039 22.5704 225.568 25.7618 227.893 29.7846C230.218 33.8075 231.222 38.4587 230.763 43.0824C230.303 47.7062 228.404 52.0691 225.333 55.5559C222.262 59.0426 218.173 61.4773 213.645 62.5165C209.116 63.5557 204.375 63.147 200.091 61.3481C195.174 59.3048 189.411 58.1554 184.782 60.8054Z" fill="white"/>
+<path d="M110.073 65.8178C108.7 70.9742 111.318 76.2422 114.575 80.4567C117.417 84.1261 119.036 88.595 119.204 93.2335C119.372 97.872 118.08 102.446 115.51 106.311C112.941 110.177 109.223 113.138 104.881 114.778C100.538 116.419 95.7912 116.655 91.3077 115.454C86.8242 114.253 82.8306 111.675 79.8898 108.084C76.9489 104.493 75.2091 100.07 74.9155 95.4379C74.6219 90.8057 75.7894 86.1981 78.2533 82.2645C80.7173 78.331 84.3534 75.2698 88.6494 73.5124C93.5822 71.485 98.4991 68.2444 99.8241 63.0881C101.149 57.9317 98.579 52.6637 95.3224 48.4493C92.4827 44.7781 90.8665 40.3083 90.7018 35.6699C90.537 31.0315 91.8319 26.4583 94.4039 22.5949C96.976 18.7314 100.695 15.7724 105.038 14.1349C109.381 12.4974 114.128 12.2639 118.611 13.4673C123.094 14.6708 127.085 17.2505 130.024 20.8429C132.963 24.4354 134.7 28.8594 134.991 33.4916C135.283 38.1237 134.113 42.7305 131.647 46.6627C129.182 50.5948 125.544 53.6541 121.248 55.4095C116.363 57.4209 111.462 60.6775 110.073 65.8178Z" fill="white"/>
+<path d="M60.7892 122.218C63.4552 126.831 69.0425 128.699 74.3265 129.37C78.9361 129.955 83.2455 131.973 86.6471 135.138C90.0487 138.304 92.3707 142.457 93.2857 147.013C94.2006 151.569 93.6625 156.296 91.747 160.53C89.8314 164.763 86.6353 168.288 82.6093 170.608C78.5833 172.928 73.9305 173.926 69.3073 173.46C64.6841 172.995 60.3236 171.09 56.841 168.014C53.3583 164.938 50.9292 160.846 49.8962 156.316C48.8631 151.785 49.2783 147.045 51.0832 142.763C53.1426 137.846 54.2759 132.083 51.6419 127.454C49.0079 122.824 43.4046 120.973 38.1047 120.302C33.4951 119.717 29.1856 117.699 25.7841 114.533C22.3825 111.368 20.0604 107.214 19.1454 102.659C18.2304 98.1032 18.7687 93.3752 20.6842 89.1418C22.5997 84.9084 25.7959 81.3832 29.8219 79.0632C33.8479 76.7433 38.5006 75.7457 43.1238 76.2113C47.7471 76.6768 52.1075 78.582 55.5902 81.658C59.0728 84.7341 61.502 88.8258 62.535 93.3561C63.568 97.8865 63.1528 102.627 61.3479 106.908C59.2886 111.825 58.1552 117.588 60.7892 122.218Z" fill="white"/>
+<path d="M65.8204 196.93C70.9767 198.303 76.2287 195.685 80.4592 192.428C84.1286 189.586 88.5975 187.967 93.236 187.799C97.8745 187.631 102.449 188.923 106.314 191.493C110.179 194.062 113.141 197.78 114.781 202.122C116.421 206.464 116.657 211.212 115.457 215.695C114.256 220.179 111.678 224.172 108.087 227.113C104.496 230.054 100.073 231.794 95.4404 232.087C90.8082 232.381 86.2006 231.214 82.2671 228.75C78.3335 226.286 75.2723 222.649 73.5149 218.353C71.4875 213.421 68.231 208.504 63.0906 207.179C57.9503 205.854 52.6662 208.424 48.4518 211.681C44.7804 214.528 40.308 216.151 35.6652 216.32C31.0224 216.49 26.4435 215.199 22.5738 212.628C18.7042 210.057 15.7391 206.336 14.0968 201.99C12.4544 197.644 12.2176 192.892 13.4197 188.404C14.6218 183.917 17.2021 179.919 20.7969 176.976C24.3917 174.033 28.8195 172.293 33.4562 172C38.0929 171.708 42.7045 172.878 46.6407 175.345C50.577 177.813 53.6394 181.454 55.3961 185.755C57.4235 190.656 60.6641 195.541 65.8204 196.93Z" fill="white"/>
+<path d="M122.205 246.21C126.818 243.544 128.686 237.956 129.373 232.672C129.96 228.068 131.978 223.763 135.142 220.366C138.306 216.969 142.456 214.651 147.008 213.738C151.559 212.825 156.283 213.364 160.512 215.278C164.741 217.192 168.263 220.385 170.58 224.408C172.898 228.43 173.895 233.078 173.43 237.697C172.966 242.316 171.064 246.673 167.991 250.153C164.919 253.633 160.832 256.061 156.306 257.095C151.781 258.129 147.045 257.717 142.766 255.916C137.833 253.856 132.07 252.723 127.457 255.357C122.843 257.991 120.96 263.594 120.289 268.894C119.7 273.498 117.681 277.8 114.517 281.196C111.353 284.591 107.204 286.908 102.653 287.821C98.1027 288.733 93.3808 288.194 89.1525 286.281C84.9243 284.367 81.4031 281.175 79.085 277.154C76.767 273.134 75.7689 268.487 76.2316 263.869C76.6942 259.251 78.5942 254.895 81.6638 251.414C84.7334 247.933 88.8179 245.503 93.3417 244.466C97.8655 243.429 102.601 243.838 106.88 245.635C111.828 247.694 117.591 248.876 122.205 246.21Z" fill="white"/>
+<path d="M196.915 241.18C198.304 236.024 195.686 230.756 192.414 226.542C189.567 222.87 187.944 218.398 187.774 213.755C187.604 209.112 188.896 204.533 191.467 200.664C194.038 196.794 197.759 193.829 202.104 192.187C206.45 190.544 211.202 190.307 215.69 191.509C220.178 192.712 224.175 195.292 227.118 198.887C230.061 202.481 231.802 206.909 232.094 211.546C232.387 216.183 231.217 220.794 228.749 224.731C226.281 228.667 222.64 231.729 218.339 233.486C213.406 235.513 208.505 238.77 207.164 243.91C205.823 249.051 208.393 254.335 211.666 258.549C214.513 262.22 216.136 266.693 216.306 271.335C216.476 275.978 215.184 280.557 212.613 284.427C210.042 288.297 206.321 291.262 201.975 292.904C197.629 294.546 192.877 294.783 188.39 293.581C183.902 292.379 179.905 289.799 176.962 286.204C174.019 282.609 172.278 278.181 171.985 273.545C171.693 268.908 172.863 264.296 175.331 260.36C177.799 256.424 181.44 253.361 185.741 251.605C190.658 249.577 195.543 246.337 196.915 241.18Z" fill="white"/>
+<path d="M246.195 184.797C243.529 180.184 237.957 178.316 232.673 177.629C228.069 177.045 223.764 175.03 220.365 171.869C216.967 168.708 214.646 164.56 213.729 160.01C212.813 155.46 213.348 150.737 215.258 146.507C217.168 142.277 220.357 138.753 224.376 136.431C228.395 134.11 233.041 133.108 237.66 133.567C242.279 134.026 246.637 135.923 250.12 138.991C253.604 142.058 256.037 146.141 257.077 150.664C258.117 155.188 257.711 159.923 255.917 164.204C253.857 169.137 252.724 174.9 255.342 179.513C257.96 184.127 263.595 186.01 268.879 186.681C273.484 187.267 277.789 189.283 281.186 192.446C284.584 195.608 286.904 199.757 287.819 204.308C288.733 208.859 288.197 213.582 286.285 217.811C284.372 222.041 281.181 225.564 277.16 227.884C273.14 230.203 268.492 231.203 263.874 230.741C259.255 230.279 254.897 228.379 251.416 225.31C247.934 222.24 245.503 218.155 244.466 213.63C243.429 209.106 243.838 204.37 245.636 200.09C247.695 195.173 248.861 189.411 246.195 184.797Z" fill="white"/>
+<path d="M241.18 110.07C236.024 108.697 230.756 111.315 226.542 114.588C222.87 117.435 218.398 119.058 213.755 119.228C209.112 119.398 204.533 118.106 200.664 115.535C196.794 112.964 193.829 109.243 192.187 104.897C190.544 100.551 190.307 95.7994 191.509 91.3117C192.712 86.824 195.292 82.8268 198.887 79.8837C202.481 76.9405 206.909 75.2 211.546 74.9073C216.183 74.6147 220.794 75.7849 224.731 78.2527C228.667 80.7206 231.729 84.3617 233.486 88.6627C235.513 93.5955 238.754 98.4964 243.91 99.8374C249.066 101.178 254.335 98.6082 258.549 95.3356C262.22 92.4959 266.69 90.8798 271.328 90.7151C275.967 90.5503 280.54 91.8452 284.403 94.4172C288.267 96.9892 291.226 100.709 292.863 105.052C294.501 109.394 294.734 114.142 293.531 118.624C292.327 123.107 289.748 127.099 286.155 130.037C282.563 132.976 278.139 134.714 273.507 135.005C268.875 135.296 264.268 134.126 260.336 131.661C256.403 129.195 253.344 125.557 251.589 121.261C249.577 116.36 246.321 111.459 241.18 110.07Z" fill="white"/>
+<path d="M153.491 191.533C174.501 191.533 191.533 174.501 191.533 153.491C191.533 132.482 174.501 115.45 153.491 115.45C132.481 115.45 115.449 132.482 115.449 153.491C115.449 174.501 132.481 191.533 153.491 191.533Z" fill="white"/>
+</svg>
@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# Hook: PreToolUse (matcher: Write|Edit)
+#
+# Blocks writes to MEMORY.md and auto-memory files, redirecting Claude
+# to use the mem0 MCP add_memory tool instead.
+#
+# Input:  JSON on stdin with tool_name, tool_input
+# Output: stderr message (exit 2 = block)
+#
+# Exit codes:
+#   0 = allow the tool call
+#   2 = block the tool call (stderr is shown to Claude as feedback)
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.path // ""' 2>/dev/null || echo "")
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+case "$FILE_PATH" in
+  */MEMORY.md|*/memory/*.md|*/.claude/*/memory/*)
+    echo "BLOCKED: Do not write to $FILE_PATH. Use the mem0 MCP \`add_memory\` tool instead to persist memories. This project uses mem0 for all memory storage." >&2
+    exit 2
+    ;;
+  *)
+    exit 0
+    ;;
+esac
@@ -0,0 +1,239 @@
+#!/usr/bin/env python3
+"""Capture session state via the Mem0 REST API.
+
+Safety net for PreCompact and Stop hooks — reads the transcript JSONL,
+extracts structured session state, and stores it in Mem0 directly.
+
+Used by:
+  - PreCompact hook: Tags with "pre-compaction" (context about to be lost)
+  - Stop hook:       Tags with "session-end" (session ending, Claude can't respond)
+
+Input:  JSON on stdin with transcript_path, session_id, cwd
+Output: stderr logs only (exit 0 always — must not block)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import sys
+import urllib.request
+import urllib.error
+
+log = logging.getLogger("mem0-capture")
+log.setLevel(logging.DEBUG)
+_handler = logging.StreamHandler(sys.stderr)
+_handler.setFormatter(logging.Formatter("[mem0-capture] %(message)s"))
+log.addHandler(_handler)
+
+API_URL = "https://api.mem0.ai"
+MAX_TAIL_LINES = 500
+MAX_USER_MESSAGES = 30
+MAX_BASH_COMMANDS = 20
+MAX_ASSISTANT_TEXT = 10000
+
+
+def tail_lines(filepath: str, n: int) -> list[str]:
+    """Read last n lines of a file efficiently."""
+    try:
+        with open(filepath, "rb") as f:
+            f.seek(0, 2)
+            file_size = f.tell()
+            if file_size == 0:
+                return []
+            chunk_size = min(file_size, n * 4096)
+            f.seek(max(0, file_size - chunk_size))
+            data = f.read().decode("utf-8", errors="replace")
+            return data.splitlines()[-n:]
+    except OSError:
+        return []
+
+
+def parse_transcript(lines: list[str]) -> dict:
+    """Parse transcript JSONL lines and extract session state."""
+    user_messages: list[str] = []
+    files_modified: set[str] = set()
+    bash_commands: list[str] = []
+    last_assistant_text = ""
+
+    for line in lines:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entry = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+
+        entry_type = entry.get("type")
+        if entry_type not in ("user", "assistant"):
+            continue
+        if entry.get("isSidechain"):
+            continue
+
+        message = entry.get("message", {})
+        content_blocks = message.get("content", [])
+
+        if entry_type == "user":
+            parts = []
+            if isinstance(content_blocks, str):
+                parts.append(content_blocks)
+            elif isinstance(content_blocks, list):
+                for block in content_blocks:
+                    if isinstance(block, str):
+                        parts.append(block)
+                    elif isinstance(block, dict) and block.get("type") == "text":
+                        parts.append(block.get("text", ""))
+            text = "\n".join(parts).strip()
+            if text and len(text) > 10 and not text.startswith("<"):
+                user_messages.append(text)
+
+        elif entry_type == "assistant":
+            for block in content_blocks:
+                if not isinstance(block, dict):
+                    continue
+                if block.get("type") == "text":
+                    text = block.get("text", "").strip()
+                    if text:
+                        last_assistant_text = text
+                if block.get("type") == "tool_use":
+                    tool_name = block.get("name", "")
+                    tool_input = block.get("input", {})
+                    if tool_name in ("Write", "Edit"):
+                        fp = tool_input.get("file_path", "")
+                        if fp:
+                            files_modified.add(fp)
+                    elif tool_name == "Bash":
+                        cmd = tool_input.get("command", "")
+                        if cmd:
+                            bash_commands.append(cmd)
+
+    return {
+        "user_messages": user_messages[-MAX_USER_MESSAGES:],
+        "files_modified": sorted(files_modified),
+        "bash_commands": bash_commands[-MAX_BASH_COMMANDS:],
+        "last_assistant_text": last_assistant_text[:MAX_ASSISTANT_TEXT],
+    }
+
+
+def build_content(state: dict, source: str) -> str:
+    """Build structured markdown from parsed state."""
+    parts = [f"## Session State ({source})\n"]
+
+    if state["user_messages"]:
+        parts.append("### What the user was working on")
+        for msg in state["user_messages"]:
+            truncated = msg[:5000] + "..." if len(msg) > 5000 else msg
+            parts.append(f"- {truncated}")
+        parts.append("")
+
+    if state["files_modified"]:
+        parts.append("### Files modified this session")
+        for fp in state["files_modified"]:
+            parts.append(f"- `{fp}`")
+        parts.append("")
+
+    if state["bash_commands"]:
+        parts.append("### Recent commands")
+        for cmd in state["bash_commands"]:
+            truncated = cmd[:1000] + "..." if len(cmd) > 1000 else cmd
+            parts.append(f"- `{truncated}`")
+        parts.append("")
+
+    if state["last_assistant_text"]:
+        parts.append("### Last context")
+        parts.append(state["last_assistant_text"])
+        parts.append("")
+
+    return "\n".join(parts)
+
+
+def store_memory(api_key: str, content: str, user_id: str, source: str) -> bool:
+    """Store session state as a memory via the Mem0 REST API."""
+    body = {
+        "messages": [
+            {"role": "user", "content": content}
+        ],
+        "user_id": user_id,
+        "metadata": {
+            "type": "session_state",
+            "source": source,
+        },
+    }
+
+    data = json.dumps(body).encode("utf-8")
+    req = urllib.request.Request(
+        f"{API_URL}/v1/memories/",
+        data=data,
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Token {api_key}",
+        },
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            if resp.status in (200, 201):
+                log.info("Session state stored successfully")
+                return True
+            log.warning("API returned status %d", resp.status)
+            return False
+    except urllib.error.URLError as e:
+        log.warning("API call failed: %s", e)
+        return False
+
+
+def main():
+    source = "pre-compaction"
+    for arg in sys.argv[1:]:
+        if arg.startswith("--source="):
+            source = arg.split("=", 1)[1]
+
+    api_key = os.environ.get("MEM0_API_KEY", "")
+    if not api_key:
+        log.debug("MEM0_API_KEY not set, skipping capture")
+        return
+
+    try:
+        hook_input = json.loads(sys.stdin.read())
+    except (json.JSONDecodeError, OSError):
+        log.debug("No valid JSON on stdin")
+        return
+
+    transcript_path = hook_input.get("transcript_path", "")
+    if not transcript_path:
+        log.debug("No transcript_path provided")
+        return
+
+    user_id = os.environ.get("MEM0_USER_ID", os.environ.get("USER", "default"))
+
+    lines = tail_lines(transcript_path, MAX_TAIL_LINES)
+    if not lines:
+        log.debug("Transcript empty or unreadable: %s", transcript_path)
+        return
+
+    state = parse_transcript(lines)
+    if not state["user_messages"] and not state["files_modified"]:
+        log.debug("No meaningful session state to capture")
+        return
+
+    content = build_content(state, source)
+
+    log.info(
+        "Capturing session state: %d user msgs, %d files, %d commands",
+        len(state["user_messages"]),
+        len(state["files_modified"]),
+        len(state["bash_commands"]),
+    )
+
+    store_memory(api_key, content, user_id, source)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        log.error("Unexpected error: %s", e)
+    sys.exit(0)
@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# Hook: PreCompact
+#
+# Fires BEFORE context compaction. This is the last chance to capture
+# the full context before it gets compressed.
+#
+# Output: Text instructions injected into Claude's context.
+# Claude still has the full conversation and can write an accurate summary.
+# A companion Python script (on_pre_compact.py) also runs to capture
+# transcript state directly via the Mem0 REST API as a safety net.
+
+set -euo pipefail
+
+cat <<'EOF'
+## CRITICAL: Pre-Compaction Session Summary
+
+Context compaction is about to happen. You are about to lose most of your conversation history. You MUST store a comprehensive session summary NOW using the mem0 `add_memory` tool.
+
+### Step 1: Store session summary
+
+Call `add_memory` with a thorough summary covering ALL of the following:
+
+```
+## Session Summary (Pre-Compaction)
+
+### User's Goal
+[What the user originally asked for and their intent]
+
+### What Was Accomplished
+[Numbered list of tasks completed, features built, bugs fixed]
+
+### Key Decisions Made
+[Architectural choices, design decisions, trade-offs discussed]
+
+### Files Created or Modified
+[List of important file paths with what changed in each]
+
+### Current State
+[What is in progress RIGHT NOW — the task you were in the middle of]
+[Any pending items, blockers, or next steps]
+
+### Important Context
+[User preferences observed, coding patterns, anything that would help
+the post-compaction agent continue without asking redundant questions]
+```
+
+Include metadata: `{"type": "session_state", "source": "pre-compaction"}`
+
+### Step 2: Store any unstored learnings
+
+If there are learnings from this session that you haven't stored yet, store them as separate memories:
+- Failed approaches -> metadata `{"type": "anti_pattern"}`
+- Successful strategies -> metadata `{"type": "task_learning"}`
+- Architecture decisions -> metadata `{"type": "decision"}`
+
+### Step 3: Acknowledge
+
+After storing, briefly tell the user that session state has been saved and you're ready for compaction.
+
+Do this NOW. Do not skip any section. The quality of this summary directly determines whether you can continue the user's task after compaction.
+EOF
+
+exit 0
@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Hook: SessionStart (matcher: startup|resume|compact)
+#
+# Bootstraps mem0 context at the start of every session.
+# Output becomes part of Claude's context so it calls mem0 MCP tools.
+#
+# Input:  JSON on stdin with session_id, source, transcript_path, model, cwd
+# Output: Text injected into Claude's context (exit 0)
+
+# Intentionally omit -e so the script always outputs a bootstrap prompt
+# even if jq is missing or stdin is malformed.
+set -uo pipefail
+
+INPUT=$(cat)
+SOURCE=$(echo "$INPUT" | jq -r '.source // "startup"' 2>/dev/null || echo "startup")
+
+if [ "$SOURCE" = "startup" ]; then
+  cat <<'EOF'
+## Mem0 Session Bootstrap
+
+You have access to persistent memory via the mem0 MCP tools. Before doing anything else:
+
+1. Call `search_memories` with a query related to the current project or user request to load relevant context.
+2. Review the returned memories to understand what has been learned in prior sessions.
+3. If appropriate, call `get_memories` to browse all stored memories for this user.
+
+IMPORTANT: Do NOT skip this step. Always bootstrap context first.
+EOF
+
+elif [ "$SOURCE" = "resume" ]; then
+  cat <<'EOF'
+## Mem0 Session Resumed
+
+This is a resumed session. Your prior context is already loaded. Before continuing:
+
+1. Call `search_memories` with a query related to the current task to refresh relevant memories.
+2. If significant time has passed, search for recent project-wide updates.
+
+Continue where you left off.
+EOF
+
+elif [ "$SOURCE" = "compact" ]; then
+  cat <<'EOF'
+## Mem0 Post-Compaction Recovery
+
+Context was just compacted. You may have lost important session context.
+
+1. Call `search_memories` with queries related to what you were working on to reload relevant knowledge.
+2. Check for any session state memories that were saved before compaction.
+3. Continue working based on the recovered context.
+EOF
+fi
+
+exit 0
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+# Hook: Stop
+#
+# Fires when Claude finishes responding.
+# Reminds Claude to store any unsaved learnings, then spawns a background
+# process to capture transcript state via the Mem0 REST API directly.
+#
+# Input:  JSON on stdin with stop_hook_active, transcript_path, cwd
+# Output: Text that becomes Claude's context (exit 0), or nothing
+#
+# IMPORTANT: Check stop_hook_active to avoid infinite loops.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+INPUT=$(cat)
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null || echo "false")
+
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+cat <<'EOF'
+Before finishing, check if there are important learnings from this interaction that should be persisted using the mem0 `add_memory` tool:
+
+1. Were any significant decisions made? -> Store with metadata `{"type": "decision"}`
+2. Were any new patterns or strategies discovered? -> Store with metadata `{"type": "task_learning"}`
+3. Did any approach fail? -> Store with metadata `{"type": "anti_pattern"}`
+4. Did you learn anything about the user's preferences? -> Store with metadata `{"type": "user_preference"}`
+5. Were there environment/setup discoveries? -> Store with metadata `{"type": "environmental"}`
+
+Memories can be as detailed as needed — include full context, reasoning, code snippets, file paths, and examples. Longer, searchable memories are more valuable than vague one-liners.
+
+If nothing notable happened in this interaction, it's fine to skip. Only store genuinely useful learnings.
+EOF
+
+# Capture transcript state in the background via Mem0 REST API
+echo "$INPUT" | python3 "$SCRIPT_DIR/on_pre_compact.py" --source=session-end 2>/dev/null &
+
+exit 0
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# Hook: TaskCompleted
+#
+# Fires when a task is marked as completed. Reminds Claude to extract
+# and store learnings via the mem0 MCP tools.
+#
+# Input:  JSON on stdin with task_id, task_subject, task_description
+# Output: Text that becomes feedback to the model (exit 0)
+
+set -euo pipefail
+
+INPUT=$(cat)
+TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject // "unknown task"' 2>/dev/null || echo "unknown task")
+
+cat <<EOF
+Task completed: "$TASK_SUBJECT"
+
+Extract key learnings from this completed task and store them using the mem0 \`add_memory\` tool:
+
+1. What strategy worked well? -> Store with metadata \`{"type": "task_learning"}\`
+2. Were there failed approaches before finding the solution? -> Store with metadata \`{"type": "anti_pattern"}\`
+3. Were there architectural decisions? -> Store with metadata \`{"type": "decision"}\`
+4. Any new conventions or patterns established? -> Store with metadata \`{"type": "convention"}\`
+
+Memories can be as detailed as needed — include full context, reasoning, code snippets, and examples.
+Only store genuinely useful learnings — skip if the task was trivial.
+EOF
+
+exit 0
@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+# Hook: UserPromptSubmit
+#
+# Fires on every user message. Searches mem0 for relevant memories
+# and injects them into Claude's context before processing.
+#
+# Input:  JSON on stdin with prompt, session_id, cwd, transcript_path
+# Output: Matching memories as context text (exit 0)
+#
+# Skips search for very short prompts (< 20 chars) and when
+# MEM0_API_KEY is not set. Uses a 3s timeout to minimize latency.
+
+# Intentionally omit -e so the script always exits 0 even if
+# curl or jq fail — must never block the user's prompt.
+set -uo pipefail
+
+INPUT=$(cat)
+PROMPT=$(echo "$INPUT" | jq -r '.prompt // ""' 2>/dev/null || echo "")
+
+# Skip trivial prompts — not worth a network call
+if [ ${#PROMPT} -lt 20 ]; then
+  exit 0
+fi
+
+API_KEY="${MEM0_API_KEY:-}"
+if [ -z "$API_KEY" ]; then
+  exit 0
+fi
+
+USER_ID="${MEM0_USER_ID:-${USER:-default}}"
+
+# Build request body safely via jq to avoid injection
+BODY=$(jq -n --arg query "$PROMPT" --arg user_id "$USER_ID" \
+  '{query: $query, filters: {user_id: $user_id}, top_k: 5}')
+
+# Search mem0 for memories relevant to this prompt
+RESPONSE=$(curl -s --max-time 3 \
+  -X POST "https://api.mem0.ai/v2/memories/search/" \
+  -H "Authorization: Token $API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$BODY" \
+  2>/dev/null || echo "")
+
+if [ -z "$RESPONSE" ]; then
+  exit 0
+fi
+
+# Extract memories from response (API returns a flat array)
+MEMORIES=$(echo "$RESPONSE" | jq -r '
+  if type == "array" then . else .results // [] end |
+  if length == 0 then empty else
+  "## Relevant memories from mem0\n\n" +
+  (map(select(.memory != null) | "- " + .memory) | join("\n"))
+  end
+' 2>/dev/null || echo "")
+
+if [ -n "$MEMORIES" ]; then
+  echo "$MEMORIES"
+fi
+
+exit 0
@@ -0,0 +1,189 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but not
+      limited to compiled object code, generated documentation, and
+      conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work.
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024 Mem0.ai
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
@@ -0,0 +1,73 @@
+# Mem0 Skill for Claude
+
+Add persistent memory to any AI application in minutes using [Mem0 Platform](https://app.mem0.ai).
+
+## What This Skill Does
+
+When installed, Claude can:
+
+- **Set up Mem0** in your Python or TypeScript project
+- **Integrate memory** into your existing AI app (LangChain, CrewAI, Vercel AI, OpenAI Agents, LangGraph, LlamaIndex, etc.)
+- **Generate working code** using real API references and tested patterns
+- **Search live docs** on demand for the latest Mem0 documentation
+
+## Installation
+
+This skill is included automatically when you install the Mem0 plugin:
+
+```
+/plugin marketplace add mem0ai/mem0
+/plugin install mem0@mem0-plugins
+```
+
+See the [plugin README](../../README.md) for full setup instructions.
+
+### Prerequisites
+
+- A Mem0 Platform API key ([Get one here](https://app.mem0.ai/dashboard/api-keys))
+- Python 3.10+ or Node.js 18+
+- Set the environment variable:
+
+  ```bash
+  export MEM0_API_KEY="m0-your-api-key"
+  ```
+
+## Quick Start
+
+After installing, just ask Claude:
+
+- "Set up mem0 in my project"
+- "Add memory to my chatbot"
+- "Help me search user memories with filters"
+- "Integrate mem0 with my LangChain app"
+- "Add graph memory to track entity relationships"
+
+## What's Inside
+
+```text
+skills/mem0/
+├── SKILL.md                    # Skill definition and instructions
+├── README.md                   # This file
+├── LICENSE                     # Apache-2.0
+├── scripts/
+│   └── mem0_doc_search.py      # Search live Mem0 docs on demand
+└── references/                 # Documentation (loaded on demand)
+    ├── quickstart.md           # Full quickstart (Python, TS, cURL)
+    ├── sdk-guide.md            # All SDK methods (Python + TypeScript)
+    ├── api-reference.md        # REST endpoints, filters, memory object
+    ├── architecture.md         # Processing pipeline, lifecycle, scoping, performance
+    ├── features.md             # Retrieval, graph, categories, MCP, webhooks, multimodal
+    ├── integration-patterns.md # LangChain, CrewAI, Vercel AI, LangGraph, LlamaIndex, etc.
+    └── use-cases.md            # 7 real-world patterns with Python + TypeScript code
+```
+
+## Links
+
+- [Mem0 Platform Dashboard](https://app.mem0.ai)
+- [Mem0 Documentation](https://docs.mem0.ai)
+- [Mem0 GitHub](https://github.com/mem0ai/mem0)
+- [API Reference](https://docs.mem0.ai/api-reference)
+
+## License
+
+Apache-2.0
@@ -0,0 +1,156 @@
+---
+name: mem0
+description: >
+  Integrate Mem0 Platform into AI applications for persistent memory, personalization, and semantic search.
+  Use this skill when the user mentions "mem0", "memory layer", "remember user preferences",
+  "persistent context", "personalization", or needs to add long-term memory to chatbots, agents,
+  or AI apps. Covers Python and TypeScript SDKs, framework integrations (LangChain, CrewAI,
+  Vercel AI SDK, OpenAI Agents SDK, Pipecat), and the full Platform API. Use even when the user
+  doesn't explicitly say "mem0" but describes needing conversation memory, user context retention,
+  or knowledge retrieval across sessions.
+license: Apache-2.0
+metadata:
+  author: mem0ai
+  version: "0.1.0"
+  category: ai-memory
+  tags: "memory, personalization, ai, python, typescript, vector-search"
+compatibility: Requires Python 3.10+ or Node.js 18+, pip install mem0ai or npm install mem0ai, MEM0_API_KEY env var, and internet access to api.mem0.ai
+---
+
+# Mem0 Platform Integration
+
+Mem0 is a managed memory layer for AI applications. It stores, retrieves, and manages user memories via API — no infrastructure to deploy.
+
+## Step 1: Install and authenticate
+
+**Python:**
+```bash
+pip install mem0ai
+export MEM0_API_KEY="m0-your-api-key"
+```
+
+**TypeScript/JavaScript:**
+```bash
+npm install mem0ai
+export MEM0_API_KEY="m0-your-api-key"
+```
+
+Get an API key at: https://app.mem0.ai/dashboard/api-keys
+
+## Step 2: Initialize the client
+
+**Python:**
+```python
+from mem0 import MemoryClient
+client = MemoryClient(api_key="m0-xxx")
+```
+
+**TypeScript:**
+```typescript
+import MemoryClient from 'mem0ai';
+const client = new MemoryClient({ apiKey: 'm0-xxx' });
+```
+
+For async Python, use `AsyncMemoryClient`.
+
+## Step 3: Core operations
+
+Every Mem0 integration follows the same pattern: **retrieve → generate → store**.
+
+### Add memories
+```python
+messages = [
+    {"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
+    {"role": "assistant", "content": "Got it! I'll remember that."}
+]
+client.add(messages, user_id="alice")
+```
+
+### Search memories
+```python
+results = client.search("dietary preferences", user_id="alice")
+for mem in results.get("results", []):
+    print(mem["memory"])
+```
+
+### Get all memories
+```python
+all_memories = client.get_all(user_id="alice")
+```
+
+### Update a memory
+```python
+client.update("memory-uuid", text="Updated: vegetarian, nut allergy, prefers organic")
+```
+
+### Delete a memory
+```python
+client.delete("memory-uuid")
+client.delete_all(user_id="alice")  # delete all for a user
+```
+
+## Common integration pattern
+
+```python
+from mem0 import MemoryClient
+from openai import OpenAI
+
+mem0 = MemoryClient()
+openai = OpenAI()
+
+def chat(user_input: str, user_id: str) -> str:
+    # 1. Retrieve relevant memories
+    memories = mem0.search(user_input, user_id=user_id)
+    context = "\n".join([m["memory"] for m in memories.get("results", [])])
+
+    # 2. Generate response with memory context
+    response = openai.chat.completions.create(
+        model="gpt-4.1-nano-2025-04-14",
+        messages=[
+            {"role": "system", "content": f"User context:\n{context}"},
+            {"role": "user", "content": user_input},
+        ]
+    )
+    reply = response.choices[0].message.content
+
+    # 3. Store interaction for future context
+    mem0.add(
+        [{"role": "user", "content": user_input}, {"role": "assistant", "content": reply}],
+        user_id=user_id
+    )
+    return reply
+```
+
+## Common edge cases
+
+- **Search returns empty:** Memories process asynchronously. Wait 2-3s after `add()` before searching. Also verify `user_id` matches exactly (case-sensitive).
+- **AND filter with user_id + agent_id returns empty:** Entities are stored separately. Use `OR` instead, or query separately.
+- **Duplicate memories:** Don't mix `infer=True` (default) and `infer=False` for the same data. Stick to one mode.
+- **Wrong import:** Always use `from mem0 import MemoryClient` (or `AsyncMemoryClient` for async). Do not use `from mem0 import Memory`.
+- **Immutable memories:** Cannot be updated or deleted once created. Use `client.history(memory_id)` to track changes over time.
+
+## Live documentation search
+
+For the latest docs beyond what's in the references, use the doc search tool:
+
+```bash
+python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --query "topic"
+python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --page "/platform/features/graph-memory"
+python ${CLAUDE_SKILL_DIR}/scripts/mem0_doc_search.py --index
+```
+
+No API key needed — searches docs.mem0.ai directly.
+
+## References
+
+Load these on demand for deeper detail:
+
+| Topic | File |
+|-------|------|
+| Quickstart (Python, TS, cURL) | [references/quickstart.md](references/quickstart.md) |
+| SDK guide (all methods, both languages) | [references/sdk-guide.md](references/sdk-guide.md) |
+| API reference (endpoints, filters, object schema) | [references/api-reference.md](references/api-reference.md) |
+| Architecture (pipeline, lifecycle, scoping, performance) | [references/architecture.md](references/architecture.md) |
+| Platform features (retrieval, graph, categories, MCP, etc.) | [references/features.md](references/features.md) |
+| Framework integrations (LangChain, CrewAI, Vercel AI, etc.) | [references/integration-patterns.md](references/integration-patterns.md) |
+| Use cases & examples (real-world patterns with code) | [references/use-cases.md](references/use-cases.md) |
@@ -0,0 +1,140 @@
+# Mem0 Platform API Reference
+
+REST API endpoints for the Mem0 Platform. Base URL: `https://api.mem0.ai`
+
+All endpoints require: `Authorization: Token <MEM0_API_KEY>`
+
+## Endpoints
+
+| Operation | Method | URL |
+|-----------|--------|-----|
+| Add Memories | `POST` | `/v1/memories/` |
+| Search Memories | `POST` | `/v2/memories/search/` |
+| Get All Memories | `POST` | `/v2/memories/` |
+| Get Single Memory | `GET` | `/v1/memories/{memory_id}/` |
+| Update Memory | `PUT` | `/v1/memories/{memory_id}/` |
+| Delete Memory | `DELETE` | `/v1/memories/{memory_id}/` |
+
+## Memory Object Structure
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string (UUID) | Unique memory identifier |
+| `memory` | string | Text content of the memory |
+| `user_id` | string | Associated user |
+| `agent_id` | string (nullable) | Agent identifier |
+| `app_id` | string (nullable) | Application identifier |
+| `run_id` | string (nullable) | Run/session identifier |
+| `metadata` | object | Custom key-value pairs |
+| `categories` | array of strings | Auto-assigned category tags |
+| `immutable` | boolean | If true, prevents modification |
+| `expiration_date` | datetime (nullable) | Auto-expiry date |
+| `hash` | string | Content hash |
+| `created_at` | datetime | Creation timestamp |
+| `updated_at` | datetime | Last modification timestamp |
+
+Search results additionally include `score` (relevance metric).
+
+## Scoping Identifiers
+
+Memories can be scoped to different levels:
+
+| Scope | Parameter | Use Case |
+|-------|-----------|----------|
+| User | `user_id` | Per-user memory isolation |
+| Agent | `agent_id` | Per-agent memory partitioning |
+| Application | `app_id` | Cross-agent app-level memory |
+| Run/Session | `run_id` | Session-scoped temporary memory |
+
+**Critical:** Combining `user_id` and `agent_id` in a single AND filter yields empty results. Entities are stored separately. Use `OR` logic or separate queries.
+
+## Processing Model
+
+- Memories are processed **asynchronously by default** (`async_mode=true`)
+- Add responses return queued events (`ADD`, `UPDATE`, `DELETE`) for tracking
+- Set `async_mode=false` for synchronous processing when needed
+- Graph metadata is processed asynchronously -- use `get_all()` for complete graph data
+
+## Filter System
+
+Filters use nested JSON with a logical operator at the root:
+
+```json
+{
+    "AND": [
+        {"user_id": "alice"},
+        {"categories": {"contains": "finance"}},
+        {"created_at": {"gte": "2024-01-01"}}
+    ]
+}
+```
+
+Root must be `AND`, `OR`, or `NOT`. Simple shorthand `{"user_id": "alice"}` also works.
+
+### Supported Operators
+
+| Operator | Description |
+|----------|-------------|
+| `eq` | Equal to (default) |
+| `ne` | Not equal to |
+| `in` | Matches any value in array |
+| `gt`, `gte` | Greater than / greater than or equal |
+| `lt`, `lte` | Less than / less than or equal |
+| `contains` | Case-sensitive containment |
+| `icontains` | Case-insensitive containment |
+| `*` | Wildcard -- matches any non-null value |
+
+### Filterable Fields
+
+| Field | Valid Operators |
+|-------|-----------------|
+| `user_id`, `agent_id`, `app_id`, `run_id` | `eq`, `ne`, `in`, `*` |
+| `created_at`, `updated_at`, `timestamp` | `gt`, `gte`, `lt`, `lte`, `eq`, `ne` |
+| `categories` | `eq`, `ne`, `in`, `contains` |
+| `metadata` | `eq`, `ne`, `contains` (top-level keys only) |
+| `keywords` | `contains`, `icontains` |
+| `memory_ids` | `in` |
+
+### Filter Constraints
+
+1. **Entity scope partitioning:** `user_id` AND `agent_id` in one `AND` block yields empty results.
+2. **Metadata limitations:** Only top-level keys. Only `eq`, `contains`, `ne`. No `in` or `gt`.
+3. **Operator syntax:** Use `gte`, `lt`, `ne`. SQL-style (`>=`, `!=`) rejected.
+4. **Entity filter required for get-all:** At least one of `user_id`, `agent_id`, `app_id`, or `run_id`.
+5. **Wildcard excludes null:** `*` matches only non-null values.
+6. **Date format:** ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`). Timezone-naive defaults to UTC.
+
+## Response Formats
+
+### Add Response
+
+```json
+[
+  {
+    "id": "mem_01JF8ZS4Y0R0SPM13R5R6H32CJ",
+    "event": "ADD",
+    "data": { "memory": "The user moved to Austin in 2025." }
+  }
+]
+```
+
+Event types: `ADD`, `UPDATE`, `DELETE`. A single add can trigger multiple events.
+
+### Search Response
+
+```json
+{
+  "results": [
+    {
+      "id": "ea925981-...",
+      "memory": "Is a vegetarian and allergic to nuts.",
+      "user_id": "user123",
+      "categories": ["food", "health"],
+      "score": 0.89,
+      "created_at": "2024-07-26T10:29:36.630547-07:00"
+    }
+  ]
+}
+```
+
+With `enable_graph=true`, includes additional `relations` array with entity relationships.
@@ -0,0 +1,386 @@
+# Mem0 Platform Architecture
+
+How Mem0 processes, stores, and retrieves memories under the hood.
+
+## Table of Contents
+
+- [Core Concept](#core-concept)
+- [Memory Processing Pipeline](#memory-processing-pipeline)
+- [Retrieval Pipeline](#retrieval-pipeline)
+- [Memory Lifecycle](#memory-lifecycle)
+- [Memory Object Structure](#memory-object-structure)
+- [Scoping & Multi-Tenancy](#scoping--multi-tenancy)
+- [Memory Layers](#memory-layers)
+- [Performance Characteristics](#performance-characteristics)
+
+---
+
+## Core Concept
+
+Mem0 is a managed memory layer that sits between your AI application and users. Every integration follows the same 3-step loop:
+
+```
+User Input → Retrieve relevant memories → Enrich LLM prompt → Generate response → Store new memories
+```
+
+Mem0 handles the complexity of extraction, deduplication, conflict resolution, and semantic retrieval so your application only needs to call `search()` and `add()`.
+
+**Dual storage architecture:**
+- **Vector store**: Embeddings for semantic similarity search
+- **Graph store** (optional): Entity nodes and relationship edges for structured knowledge
+
+---
+
+## Memory Processing Pipeline
+
+### What happens when you call `client.add()`
+
+```
+Messages In
+    │
+    ▼
+┌─────────────────────┐
+│  1. EXTRACTION       │  LLM analyzes messages, extracts key facts
+│     (infer=True)     │  If infer=False, stores raw text as-is
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│  2. CONFLICT         │  Checks existing memories for duplicates
+│     RESOLUTION       │  Latest truth wins (newer overrides older)
+│                      │  Only runs when infer=True
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│  3. STORAGE          │  Generates embeddings → vector store
+│                      │  Optional: entity extraction → graph store
+│                      │  Indexes metadata, categories, timestamps
+└─────────┬───────────┘
+          │
+          ▼
+    Memory Object
+    (id, memory, categories, structured_attributes)
+```
+
+### Processing modes
+
+**Async (default, `async_mode=True`):**
+- API returns immediately: `{"status": "PENDING", "event_id": "..."}`
+- Processing happens in background
+- Use webhooks for completion notifications
+- Best for: high-throughput, non-blocking workflows
+
+**Sync (`async_mode=False`):**
+- API waits for full processing
+- Returns complete memory object with `id`, `event`, `memory`
+- Best for: real-time access immediately after add
+
+### Extraction modes
+
+**Inferred (`infer=True`, default):**
+- LLM extracts structured facts from conversation
+- Conflict resolution deduplicates and resolves contradictions
+- Best for: natural conversation → memory
+
+**Raw (`infer=False`):**
+- Stores text exactly as provided, no LLM processing
+- Skips conflict resolution — same fact can be stored twice
+- Only `user` role messages are stored; `assistant` messages ignored
+- Best for: bulk imports, pre-structured data, migrations
+
+**Warning:** Don't mix `infer=True` and `infer=False` for the same data — the same fact will be stored twice.
+
+---
+
+## Retrieval Pipeline
+
+### What happens when you call `client.search()`
+
+```
+Query In
+    │
+    ▼
+┌─────────────────────┐
+│  1. QUERY EMBEDDING  │  Convert query to vector representation
+└─────────┬───────────┘
+          │
+          ▼
+┌─────────────────────┐
+│  2. VECTOR SEARCH    │  Cosine similarity across stored embeddings
+│                      │  Scoped by filters (user_id, agent_id, etc.)
+└─────────┬───────────┘
+          │
+          ▼  (optional enhancements)
+┌─────────────────────┐
+│  3a. KEYWORD SEARCH  │  Expands results with specific terms (+10ms)
+│  3b. RERANKING       │  Deep semantic reordering (+150-200ms)
+│  3c. FILTER MEMORIES │  Precision filtering, removes low-relevance (+200-300ms)
+└─────────┬───────────┘
+          │
+          ▼  (if enable_graph=True)
+┌─────────────────────┐
+│  4. GRAPH LOOKUP     │  Finds entity relationships
+│                      │  Appends relations WITHOUT reranking vector results
+└─────────┬───────────┘
+          │
+          ▼
+    Results + Relations
+```
+
+### Retrieval enhancement combinations
+
+| Configuration | Latency | Best for |
+|--------------|---------|----------|
+| Base search only | ~100ms | Simple lookups |
+| `keyword_search=True` | ~110ms | Entity-heavy queries, broad coverage |
+| `rerank=True` | ~250-300ms | User-facing results, top-N precision |
+| `keyword_search=True` + `rerank=True` | ~310ms | Balanced (recommended for most apps) |
+| `rerank=True` + `filter_memories=True` | ~400-500ms | Safety-critical, production systems |
+
+### Implicit null scoping
+
+When you search with `user_id="alice"` only, Mem0 returns memories where `agent_id`, `app_id`, and `run_id` are all null. This prevents cross-scope leakage by default.
+
+To include memories with non-null fields, use explicit filters:
+```python
+# Gets memories for alice regardless of agent/app/run
+filters={"OR": [{"user_id": "alice"}]}
+```
+
+---
+
+## Memory Lifecycle
+
+```
+CREATE ──→ ACTIVE ──→ UPDATE ──→ ACTIVE
+  │           │                     │
+  │           ▼                     ▼
+  │       EXPIRED              EXPIRED
+  │      (still stored,       (still stored,
+  │       not retrieved)       not retrieved)
+  │           │                     │
+  ▼           ▼                     ▼
+DELETE    DELETE               DELETE
+(permanent)
+```
+
+### Creation
+- Triggered by `client.add(messages, user_id="...")`
+- Messages processed through extraction → conflict resolution → storage
+- Gets unique UUID, `created_at` timestamp
+- Optional: custom `timestamp`, `expiration_date`, `metadata`, `immutable`
+
+### Updates
+- `client.update(memory_id, text="...")` replaces text and reindexes
+- `client.batch_update([...])` for up to 1000 memories at once
+- Immutable memories (`immutable=True`) cannot be updated — must delete and re-add
+
+### Deduplication
+- Automatic during `add()` with `infer=True`
+- Conflict resolution merges duplicate facts
+- Latest truth wins when contradictions detected
+- Prevents memory bloat from repeated information
+
+### Expiration
+- Optional `expiration_date` parameter (ISO 8601 or `YYYY-MM-DD`)
+- After expiration: memory NOT returned in searches but remains in storage
+- Useful for time-sensitive info (events, temporary preferences, session state)
+
+### Deletion
+- Single: `client.delete(memory_id)` — permanent, no recovery
+- Batch: `client.batch_delete([memory_ids])` — up to 1000
+- Bulk: `client.delete_all(user_id="alice")` — all memories for entity
+- `delete_all()` without filters raises error to prevent accidental data loss
+
+### History tracking
+- `client.history(memory_id)` returns version timeline
+- Shows all changes: `{previous_value, new_value, action, timestamps}`
+- Useful for audit trails and debugging
+
+---
+
+## Memory Object Structure
+
+```json
+{
+  "id": "uuid-string",
+  "memory": "Extracted memory text",
+  "user_id": "user-identifier",
+  "agent_id": null,
+  "app_id": null,
+  "run_id": null,
+  "metadata": { "source": "chat", "priority": "high" },
+  "categories": ["health", "preferences"],
+  "created_at": "2025-03-12T12:34:56Z",
+  "updated_at": "2025-03-12T12:34:56Z",
+  "expiration_date": null,
+  "immutable": false,
+  "structured_attributes": {
+    "day": 12, "month": 3, "year": 2025,
+    "hour": 12, "minute": 34,
+    "day_of_week": "wednesday",
+    "is_weekend": false,
+    "quarter": 1, "week_of_year": 11
+  },
+  "score": 0.85
+}
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Unique identifier, used for update/delete |
+| `memory` | string | Extracted or stored text content |
+| `user_id` | string | Primary entity scope |
+| `agent_id` | string | Agent scope |
+| `app_id` | string | Application scope |
+| `run_id` | string | Session/run scope |
+| `metadata` | object | Custom key-value pairs for filtering |
+| `categories` | array | Auto-assigned or custom category tags |
+| `created_at` | datetime | Creation timestamp |
+| `updated_at` | datetime | Last modification timestamp |
+| `expiration_date` | datetime | Auto-expiry date (stops retrieval, data persists) |
+| `immutable` | boolean | If true, prevents modification |
+| `structured_attributes` | object | Temporal breakdown for time-based queries |
+| `score` | float | Semantic similarity (search results only, 0-1) |
+
+---
+
+## Scoping & Multi-Tenancy
+
+Mem0 separates memories across four dimensions to prevent data mixing:
+
+| Dimension | Field | Purpose | Example |
+|-----------|-------|---------|---------|
+| User | `user_id` | Persistent persona or account | `"customer_6412"` |
+| Agent | `agent_id` | Distinct agent or tool | `"meal_planner"` |
+| App | `app_id` | Product surface or deployment | `"ios_retail_app"` |
+| Session | `run_id` | Short-lived flow or thread | `"ticket-9241"` |
+
+### Storage model
+
+Each entity combination creates separate records. A memory with `user_id="alice"` is stored separately from one with `user_id="alice"` + `agent_id="bot"`.
+
+### Critical: cross-entity queries
+
+```python
+# This returns NOTHING — user and agent memories are stored separately
+filters={"AND": [{"user_id": "alice"}, {"agent_id": "bot"}]}
+
+# Use OR to query multiple scopes
+filters={"OR": [{"user_id": "alice"}, {"agent_id": "bot"}]}
+
+# Use wildcard to include any non-null value
+filters={"AND": [{"user_id": "*"}]}  # All users (excludes null)
+```
+
+### Recommended scoping patterns
+
+```python
+# User-level: persistent preferences
+client.add(messages, user_id="alice")
+
+# Session-level: temporary context
+client.add(messages, user_id="alice", run_id="session_123")
+# Clean up when done: client.delete_all(run_id="session_123")
+
+# Agent-level: agent-specific knowledge
+client.add(messages, agent_id="support_bot", app_id="helpdesk")
+
+# Multi-tenant: full isolation
+client.add(messages, user_id="alice", agent_id="bot", app_id="acme_corp", run_id="ticket_42")
+```
+
+---
+
+## Memory Layers
+
+Mem0 supports three layers of memory, from shortest to longest lived:
+
+### Conversation memory
+- In-flight messages within a single turn
+- Tool calls, chain-of-thought reasoning
+- **Lifetime:** Single response — lost after turn finishes
+- **Managed by:** Your application, not Mem0
+
+### Session memory
+- Short-lived facts for current task or channel
+- Multi-step flows (onboarding, debugging, support tickets)
+- **Lifetime:** Minutes to hours
+- **Managed by:** Mem0 via `run_id` parameter
+- Clean up with `client.delete_all(run_id="session_id")`
+
+### User memory
+- Long-lived knowledge tied to a person or account
+- Personal preferences, account state, compliance details
+- **Lifetime:** Weeks to forever
+- **Managed by:** Mem0 via `user_id` parameter
+- Persists across all sessions and interactions
+
+### How layering works in practice
+
+```python
+def chat(user_input: str, user_id: str, session_id: str) -> str:
+    # 1. Retrieve user memories (long-term preferences)
+    user_mems = mem0.search(user_input, user_id=user_id)
+
+    # 2. Retrieve session memories (current task context)
+    session_mems = mem0.search(user_input, filters={
+        "AND": [{"user_id": user_id}, {"run_id": session_id}]
+    })
+
+    # 3. Combine both layers for LLM context
+    context = format_memories(user_mems) + format_memories(session_mems)
+
+    # 4. Generate response
+    response = llm.generate(context=context, input=user_input)
+
+    # 5. Store in session scope (temporary) + user scope (persistent)
+    messages = [{"role": "user", "content": user_input}, {"role": "assistant", "content": response}]
+    mem0.add(messages, user_id=user_id, run_id=session_id)
+
+    return response
+```
+
+---
+
+## Performance Characteristics
+
+### Latency
+
+| Operation | Typical Latency |
+|-----------|----------------|
+| Base vector search | ~100ms |
+| + keyword_search | +10ms |
+| + reranking | +150-200ms |
+| + filter_memories | +200-300ms |
+| Add (async, default) | < 50ms response, background processing |
+| Add (sync) | 500ms-2s depending on extraction complexity |
+| Graph operations | Slight overhead for large stores |
+
+### Processing
+
+- **Async mode (default):** Returns immediately, processes in background
+- **Sync mode:** Waits for full extraction + storage pipeline
+- **Batch operations:** Up to 1000 memories per batch_update/batch_delete
+- **Webhooks:** Real-time notifications when async processing completes
+
+### Scoping strategy for performance
+
+- Use `user_id` for all user-facing queries (most common, fastest)
+- Add `run_id` for session isolation (narrows search space)
+- Avoid wildcard `"*"` filters on large datasets (scans all non-null records)
+- Use `top_k` to limit result count when you only need a few memories
+
+---
+
+## Comparison with Alternatives
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Raw vector DB** | Fast, full control | No extraction, no dedup, no conflict resolution |
+| **In-memory chat history** | Zero latency | Lost on restart, no cross-session, grows unbounded |
+| **RAG over documents** | Good for static knowledge | No personalization, no memory updates |
+| **Mem0 Platform** | Managed extraction + dedup + graph + scoping | External dependency, async processing delay |
+
+Mem0 combines the best of vector search (semantic retrieval) with automatic extraction (LLM-powered), conflict resolution (deduplication), and structured scoping (multi-tenancy) — in a single managed API.
@@ -0,0 +1,496 @@
+# Platform Features -- Mem0 Platform
+
+Additional platform capabilities beyond core CRUD operations.
+
+## Table of Contents
+
+- [Advanced Retrieval](#advanced-retrieval)
+- [Graph Memory](#graph-memory)
+- [Custom Categories](#custom-categories)
+- [Custom Instructions](#custom-instructions)
+- [Criteria Retrieval](#criteria-retrieval)
+- [Feedback Mechanism](#feedback-mechanism)
+- [Memory Export](#memory-export)
+- [Group Chat](#group-chat)
+- [MCP Integration](#mcp-integration)
+- [Webhooks](#webhooks)
+- [Multimodal Support](#multimodal-support)
+
+## Advanced Retrieval
+
+Three enhancement options for tuning search precision, recall, and latency.
+
+### Keyword Search (`keyword_search=True`)
+
+Expands results to include memories with specific terms, names, and technical keywords.
+
+- Latency: +10ms
+- Recall: Significantly increased
+- Best for: entity-heavy queries, comprehensive coverage
+
+### Reranking (`rerank=True`)
+
+Deep semantic reordering of results — most relevant first.
+
+- Latency: +150-200ms
+- Accuracy: Significantly improved
+- Best for: user-facing results, top-N precision
+
+### Filter Memories (`filter_memories=True`)
+
+Precision filtering — removes low-relevance results entirely.
+
+- Latency: +200-300ms
+- Precision: Maximized
+- Best for: safety-critical applications, production systems
+
+### Recommended Combinations
+
+**Python:**
+```python
+# Fast & broad
+results = client.search(query, keyword_search=True, user_id="user123")
+
+# Balanced (recommended for most apps)
+results = client.search(query, keyword_search=True, rerank=True, user_id="user123")
+
+# High precision (critical apps)
+results = client.search(query, rerank=True, filter_memories=True, user_id="user123")
+```
+
+**TypeScript:**
+```typescript
+const results = await client.search(query, {
+    user_id: 'user123',
+    keyword_search: true,
+    rerank: true,
+});
+```
+
+---
+
+## Graph Memory
+
+Entity-level knowledge graph that creates relationships between memories.
+
+### How It Works
+
+1. **Extraction**: LLM analyzes conversation and identifies entities and relationships
+2. **Storage**: Embeddings go to vector store; entity nodes and edges go to graph store
+3. **Retrieval**: Vector search returns semantic matches; graph relations are appended to results
+
+Graph relations **augment** vector results without reordering them. Vector similarity always determines hit sequence.
+
+### Enabling Graph Memory
+
+**Per request:**
+```python
+client.add(messages, user_id="alice", enable_graph=True)
+client.search("query", user_id="alice", enable_graph=True)
+client.get_all(filters={"AND": [{"user_id": "alice"}]}, enable_graph=True)
+```
+
+**Project-level (default for all operations):**
+```python
+client.project.update(enable_graph=True)
+```
+
+```javascript
+await client.updateProject({ enable_graph: true });
+```
+
+### Relation Structure
+
+Each relation in the response contains:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `source` | string | Source entity name |
+| `source_type` | string | Source entity type (e.g., "Person") |
+| `relationship` | string | Relationship label (e.g., "lives_in") |
+| `target` | string | Target entity name |
+| `target_type` | string | Target entity type (e.g., "City") |
+| `score` | number | Confidence score |
+
+**Example:**
+```json
+{
+  "relations": [
+    {
+      "source": "Joseph",
+      "source_type": "Person",
+      "relationship": "lives_in",
+      "target": "Seattle",
+      "target_type": "City",
+      "score": 0.92
+    }
+  ]
+}
+```
+
+### Technical Notes
+
+- Graph Memory adds processing time; see docs for current plan availability
+- Works optimally with rich conversation histories containing entity relationships
+- Best suited for long-running assistants tracking evolving information
+- Graph writes and reads toggle independently per request
+- Multi-agent context supported via `user_id`, `agent_id`, `run_id` scoping
+- Add operations are asynchronous; graph metadata may not be immediately available
+
+---
+
+## Custom Categories
+
+Replace Mem0's default 15 labels with domain-specific categories. The system automatically tags memories to the closest matching category.
+
+### Default Categories (15)
+
+`personal_details`, `family`, `professional_details`, `sports`, `travel`, `food`, `music`, `health`, `technology`, `hobbies`, `fashion`, `entertainment`, `milestones`, `user_preferences`, `misc`
+
+### Configuration
+
+**Set project-level categories:**
+```python
+new_categories = [
+    {"lifestyle_management": "Tracks daily routines, habits, wellness activities"},
+    {"seeking_structure": "Documents goals around creating routines and systems"},
+    {"personal_information": "Basic information about the user"}
+]
+client.project.update(custom_categories=new_categories)
+```
+
+```javascript
+await client.updateProject({ custom_categories: new_categories });
+```
+
+**Retrieve active categories:**
+```python
+categories = client.project.get(fields=["custom_categories"])
+```
+
+### Key Constraint
+
+Per-request overrides (`custom_categories=...` on `client.add`) are **not supported** on the managed API. Only project-level configuration works. Workaround: store ad-hoc labels in `metadata` field.
+
+---
+
+## Custom Instructions
+
+Natural language filters that control what information Mem0 extracts when creating memories.
+
+### Set Instructions
+
+```python
+client.project.update(custom_instructions="Your guidelines here...")
+```
+
+```javascript
+await client.updateProject({ custom_instructions: "Your guidelines here..." });
+```
+
+### Template Structure
+
+1. **Task Description** -- brief extraction overview
+2. **Information Categories** -- numbered sections with specific details to capture
+3. **Processing Guidelines** -- quality and handling rules
+4. **Exclusion List** -- sensitive/irrelevant data to filter out
+
+### Domain Examples
+
+**E-commerce:** Capture product issues, preferences, service experience; exclude payment data.
+
+**Education:** Extract learning progress, student preferences, performance patterns; exclude specific grades.
+
+**Finance:** Track financial goals, life events, investment interests; exclude account numbers and SSNs.
+
+### Best Practices
+
+- Start simply, test with sample messages, iterate based on results
+- Avoid overly lengthy instructions
+- Be specific about what to include AND exclude
+
+---
+
+## Criteria Retrieval
+
+Custom attribute-based memory ranking using LLM-evaluated criteria with weights. Goes beyond semantic similarity to prioritize memories based on domain-specific signals.
+
+### Configuration
+
+```python
+# Define criteria at project level
+retrieval_criteria = [
+    {"name": "joy", "description": "Positive emotions like happiness and excitement", "weight": 3},
+    {"name": "curiosity", "description": "Inquisitiveness and desire to learn", "weight": 2},
+    {"name": "urgency", "description": "Time-sensitive or high-priority items", "weight": 4},
+]
+client.project.update(retrieval_criteria=retrieval_criteria)
+```
+
+```typescript
+await client.updateProject({
+    retrieval_criteria: [
+        { name: 'joy', description: 'Positive emotions', weight: 3 },
+        { name: 'urgency', description: 'Time-sensitive items', weight: 4 },
+    ],
+});
+```
+
+### Usage
+
+Once configured, `client.search()` automatically applies criteria ranking:
+
+```python
+# Criteria-weighted results returned automatically
+results = client.search("Why am I feeling happy?", filters={"user_id": "alice"})
+```
+
+**Best for:** Wellness assistants, tutoring platforms, productivity tools — any app needing intent-aware retrieval.
+
+---
+
+## Feedback Mechanism
+
+Provide feedback on extracted memories to improve system quality over time.
+
+### Feedback Types
+
+| Type | Meaning |
+|------|---------|
+| `POSITIVE` | Memory is useful and accurate |
+| `NEGATIVE` | Memory is not useful |
+| `VERY_NEGATIVE` | Memory is harmful or completely wrong |
+| `None` | Clear existing feedback |
+
+### Usage
+
+**Python:**
+```python
+client.feedback(
+    memory_id="mem-123",
+    feedback="POSITIVE",
+    feedback_reason="Accurately captured dietary preference"
+)
+
+# Bulk feedback
+for item in feedback_data:
+    client.feedback(**item)
+```
+
+**TypeScript:**
+```typescript
+await client.feedback('mem-123', {
+    feedback: 'POSITIVE',
+    feedback_reason: 'Accurately captured dietary preference',
+});
+```
+
+---
+
+## Memory Export
+
+Create structured exports of memories using customizable schemas with filters.
+
+### Usage
+
+```python
+import json
+
+# Define export schema
+schema = {
+    "type": "object",
+    "properties": {
+        "name": {"type": "string"},
+        "preferences": {"type": "array", "items": {"type": "string"}},
+        "health_info": {"type": "string"},
+    }
+}
+
+# Create export
+response = client.create_memory_export(
+    schema=json.dumps(schema),
+    filters={"user_id": "alice"},
+    export_instructions="Create comprehensive profile based on all memories"
+)
+
+# Retrieve export (may take a moment to process)
+result = client.get_memory_export(memory_export_id=response["id"])
+```
+
+**Best for:** Data analytics, user profile generation, compliance audits, CRM sync.
+
+---
+
+## Group Chat
+
+Process multi-participant conversations and automatically attribute memories to individual speakers.
+
+### Usage
+
+```python
+messages = [
+    {"role": "user", "name": "Alice", "content": "I think we should use React for the frontend"},
+    {"role": "user", "name": "Bob", "content": "I prefer Vue.js, it's simpler for our use case"},
+    {"role": "assistant", "content": "Both are great choices. Let me note your preferences."},
+]
+
+# Mem0 automatically attributes memories to each speaker
+response = client.add(messages, run_id="team_meeting_1")
+
+# Retrieve Alice's memories from that session
+alice_mems = client.get_all(
+    filters={"AND": [{"user_id": "alice"}, {"run_id": "team_meeting_1"}]}
+)
+```
+
+Use the `name` field in messages to identify speakers. Mem0 maps names to entity scopes automatically.
+
+---
+
+## MCP Integration
+
+Model Context Protocol integration enables AI clients (Claude Desktop, Cursor, custom agents) to manage Mem0 memory autonomously.
+
+### Configuration
+
+```json
+{
+  "mcpServers": {
+    "mem0": {
+      "command": "uvx",
+      "args": ["mem0-mcp-server"],
+      "env": {
+        "MEM0_API_KEY": "m0-your-api-key",
+        "MEM0_DEFAULT_USER_ID": "your-user-id"
+      }
+    }
+  }
+}
+```
+
+### Available MCP Tools
+
+The MCP server exposes 9 memory tools that AI agents can use autonomously:
+- Add, search, get, update, delete memories
+- Get history, list users, delete users
+- Search Mem0 documentation
+
+### How It Works
+
+1. Configure the MCP server in your AI client
+2. The agent autonomously decides when to store/retrieve memories
+3. No manual API calls needed — the agent manages memory as part of its reasoning
+
+**Best for:** Universal AI client integration — one protocol works everywhere.
+
+---
+
+## Webhooks
+
+Real-time event notifications for memory operations.
+
+### Supported Events
+
+| Event | Trigger |
+|-------|---------|
+| `memory_add` | Memory created |
+| `memory_update` | Memory modified |
+| `memory_delete` | Memory removed |
+| `memory_categorize` | Memory tagged |
+
+### Create Webhook
+
+Note: `project_id` here refers to the Mem0 dashboard project scope for webhooks — not the deprecated client init parameter.
+
+```python
+webhook = client.create_webhook(
+    url="https://your-app.com/webhook",
+    name="Memory Logger",
+    project_id="proj_123",
+    event_types=["memory_add", "memory_categorize"]
+)
+```
+
+### Manage Webhooks
+
+```python
+# Retrieve
+webhooks = client.get_webhooks(project_id="proj_123")
+
+# Update
+client.update_webhook(
+    name="Updated Logger",
+    url="https://your-app.com/new-webhook",
+    event_types=["memory_update", "memory_add"],
+    webhook_id="wh_123"
+)
+
+# Delete
+client.delete_webhook(webhook_id="wh_123")
+```
+
+### Payload Structure
+
+Memory events contain: ID, data object with memory content, event type (`ADD`/`UPDATE`/`DELETE`).
+Categorization events contain: memory ID, event type (`CATEGORIZE`), assigned category labels.
+
+---
+
+## Multimodal Support
+
+Mem0 can process images and documents alongside text.
+
+### Supported Media Types
+
+- Images: JPG, PNG
+- Documents: MDX, TXT, PDF
+
+### Image via URL
+
+```python
+image_message = {
+    "role": "user",
+    "content": {
+        "type": "image_url",
+        "image_url": {"url": "https://example.com/image.jpg"}
+    }
+}
+client.add([image_message], user_id="alice")
+```
+
+### Image via Base64
+
+```python
+import base64
+with open("photo.jpg", "rb") as f:
+    base64_image = base64.b64encode(f.read()).decode("utf-8")
+
+image_message = {
+    "role": "user",
+    "content": {
+        "type": "image_url",
+        "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}
+    }
+}
+client.add([image_message], user_id="alice")
+```
+
+### Document (MDX/TXT)
+
+```python
+doc_message = {
+    "role": "user",
+    "content": {"type": "mdx_url", "mdx_url": {"url": document_url}}
+}
+client.add([doc_message], user_id="alice")
+```
+
+### PDF Document
+
+```python
+pdf_message = {
+    "role": "user",
+    "content": {"type": "pdf_url", "pdf_url": {"url": pdf_url}}
+}
+client.add([pdf_message], user_id="alice")
+```
@@ -0,0 +1,444 @@
+# Mem0 Integration Patterns
+
+Working code examples for integrating Mem0 Platform with popular AI frameworks.
+All examples use `MemoryClient` (Platform API key).
+
+Code examples are sourced from official Mem0 integration docs at docs.mem0.ai, simplified for quick reference.
+
+---
+
+## Common Pattern
+
+Every integration follows the same 3-step loop:
+
+1. **Retrieve** -- search relevant memories before generating a response
+2. **Generate** -- include memories as context in the LLM prompt
+3. **Store** -- save the interaction back to Mem0 for future use
+
+---
+
+## LangChain
+
+Source: [docs.mem0.ai/integrations/langchain](https://docs.mem0.ai/integrations/langchain)
+
+```python
+from langchain_openai import ChatOpenAI
+from langchain_core.messages import SystemMessage, HumanMessage
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from mem0 import MemoryClient
+
+llm = ChatOpenAI(model="gpt-4.1-nano-2025-04-14")
+mem0 = MemoryClient()
+
+prompt = ChatPromptTemplate.from_messages([
+    SystemMessage(content="You are a helpful travel agent AI. Use the provided context to personalize your responses."),
+    MessagesPlaceholder(variable_name="context"),
+    HumanMessage(content="{input}")
+])
+
+def retrieve_context(query: str, user_id: str):
+    """Retrieve relevant memories from Mem0"""
+    memories = mem0.search(query, user_id=user_id)
+    memory_list = memories['results']
+    serialized = ' '.join([m["memory"] for m in memory_list])
+    return [
+        {"role": "system", "content": f"Relevant information: {serialized}"},
+        {"role": "user", "content": query}
+    ]
+
+def chat_turn(user_input: str, user_id: str) -> str:
+    # 1. Retrieve
+    context = retrieve_context(user_input, user_id)
+    # 2. Generate
+    chain = prompt | llm
+    response = chain.invoke({"context": context, "input": user_input})
+    # 3. Store
+    mem0.add(
+        [{"role": "user", "content": user_input}, {"role": "assistant", "content": response.content}],
+        user_id=user_id
+    )
+    return response.content
+```
+
+---
+
+## CrewAI
+
+Source: [docs.mem0.ai/integrations/crewai](https://docs.mem0.ai/integrations/crewai)
+
+CrewAI has native Mem0 integration via `memory_config`:
+
+```python
+from crewai import Agent, Task, Crew, Process
+from mem0 import MemoryClient
+
+client = MemoryClient()
+
+# Store user preferences first
+messages = [
+    {"role": "user", "content": "I am more of a beach person than a mountain person."},
+    {"role": "assistant", "content": "Noted! I'll recommend beach destinations."},
+    {"role": "user", "content": "I like Airbnb more than hotels."},
+]
+client.add(messages, user_id="crew_user_1")
+
+# Create agent
+travel_agent = Agent(
+    role="Personalized Travel Planner",
+    goal="Plan personalized travel itineraries",
+    backstory="You are a seasoned travel planner.",
+    memory=True,
+)
+
+# Create task
+task = Task(
+    description="Find places to live, eat, and visit in San Francisco.",
+    expected_output="A detailed list of places to live, eat, and visit.",
+    agent=travel_agent,
+)
+
+# Setup crew with Mem0 memory
+crew = Crew(
+    agents=[travel_agent],
+    tasks=[task],
+    process=Process.sequential,
+    memory=True,
+    memory_config={
+        "provider": "mem0",
+        "config": {"user_id": "crew_user_1"},
+    }
+)
+
+result = crew.kickoff()
+```
+
+---
+
+## Vercel AI SDK
+
+Source: [docs.mem0.ai/integrations/vercel-ai-sdk](https://docs.mem0.ai/integrations/vercel-ai-sdk)
+
+Install: `npm install @mem0/vercel-ai-provider`
+
+### Basic Text Generation with Memory
+
+```typescript
+import { generateText } from "ai";
+import { createMem0 } from "@mem0/vercel-ai-provider";
+
+const mem0 = createMem0({
+    provider: "openai",
+    mem0ApiKey: "m0-xxx",
+    apiKey: "openai-api-key",
+});
+
+const { text } = await generateText({
+    model: mem0("gpt-4-turbo", { user_id: "borat" }),
+    prompt: "Suggest me a good car to buy!",
+});
+```
+
+### Streaming with Memory
+
+```typescript
+import { streamText } from "ai";
+import { createMem0 } from "@mem0/vercel-ai-provider";
+
+const mem0 = createMem0();
+
+const { textStream } = streamText({
+    model: mem0("gpt-4-turbo", { user_id: "borat" }),
+    prompt: "Suggest me a good car to buy!",
+});
+
+for await (const textPart of textStream) {
+    process.stdout.write(textPart);
+}
+```
+
+### Using Memory Utilities Standalone
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { generateText } from "ai";
+import { retrieveMemories, addMemories } from "@mem0/vercel-ai-provider";
+
+// Retrieve memories and inject into any provider
+const prompt = "Suggest me a good car to buy.";
+const memories = await retrieveMemories(prompt, { user_id: "borat", mem0ApiKey: "m0-xxx" });
+
+const { text } = await generateText({
+    model: openai("gpt-4-turbo"),
+    prompt: prompt,
+    system: memories,
+});
+
+// Store new memories
+await addMemories(
+    [{ role: "user", content: [{ type: "text", text: "I love red cars." }] }],
+    { user_id: "borat", mem0ApiKey: "m0-xxx" }
+);
+```
+
+### Supported Providers
+
+`openai`, `anthropic`, `google`, `groq`
+
+---
+
+## OpenAI Agents SDK
+
+Source: [docs.mem0.ai/integrations/openai-agents-sdk](https://docs.mem0.ai/integrations/openai-agents-sdk)
+
+```python
+from agents import Agent, Runner, function_tool
+from mem0 import MemoryClient
+
+mem0 = MemoryClient()
+
+@function_tool
+def search_memory(query: str, user_id: str) -> str:
+    """Search through past conversations and memories"""
+    memories = mem0.search(query, user_id=user_id, top_k=3)
+    if memories and memories.get('results'):
+        return "\n".join([f"- {mem['memory']}" for mem in memories['results']])
+    return "No relevant memories found."
+
+@function_tool
+def save_memory(content: str, user_id: str) -> str:
+    """Save important information to memory"""
+    mem0.add([{"role": "user", "content": content}], user_id=user_id)
+    return "Information saved to memory."
+
+agent = Agent(
+    name="Personal Assistant",
+    instructions="""You are a helpful personal assistant with memory capabilities.
+    Use search_memory to recall past conversations.
+    Use save_memory to store important information.""",
+    tools=[search_memory, save_memory],
+    model="gpt-4.1-nano-2025-04-14"
+)
+
+result = Runner.run_sync(agent, "I love Italian food and I'm planning a trip to Rome next month")
+print(result.final_output)
+```
+
+### Multi-Agent with Handoffs
+
+```python
+from agents import Agent, Runner, function_tool
+
+travel_agent = Agent(
+    name="Travel Planner",
+    instructions="You are a travel planning specialist. Use search_memory and save_memory tools.",
+    tools=[search_memory, save_memory],
+    model="gpt-4.1-nano-2025-04-14"
+)
+
+health_agent = Agent(
+    name="Health Advisor",
+    instructions="You are a health and wellness advisor. Use search_memory and save_memory tools.",
+    tools=[search_memory, save_memory],
+    model="gpt-4.1-nano-2025-04-14"
+)
+
+triage_agent = Agent(
+    name="Personal Assistant",
+    instructions="""Route travel questions to Travel Planner, health questions to Health Advisor.""",
+    handoffs=[travel_agent, health_agent],
+    model="gpt-4.1-nano-2025-04-14"
+)
+
+result = Runner.run_sync(triage_agent, "Plan a healthy meal for my Italy trip")
+```
+
+---
+
+## Pipecat (Voice / Real-Time)
+
+Source: [docs.mem0.ai/integrations/pipecat](https://docs.mem0.ai/integrations/pipecat)
+
+```python
+from pipecat.services.mem0 import Mem0MemoryService
+
+memory = Mem0MemoryService(
+    api_key=os.getenv("MEM0_API_KEY"),
+    user_id="alice",
+    agent_id="voice_bot",
+    params={
+        "search_limit": 10,
+        "search_threshold": 0.1,
+        "system_prompt": "Here are your past memories:",
+        "add_as_system_message": True,
+    }
+)
+
+# Use in pipeline
+pipeline = Pipeline([
+    transport.input(),
+    stt,
+    user_context,
+    memory,          # Memory enhances context automatically
+    llm,
+    transport.output(),
+    assistant_context
+])
+```
+
+
+
+---
+
+## LangGraph
+
+Source: [docs.mem0.ai/integrations/langgraph](https://docs.mem0.ai/integrations/langgraph)
+
+State-based agent workflows with memory persistence. Best for complex conversation flows with branching logic.
+
+```python
+from typing import Annotated, TypedDict, List
+from langgraph.graph import StateGraph, START
+from langgraph.graph.message import add_messages
+from langchain_openai import ChatOpenAI
+from mem0 import MemoryClient
+from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
+
+llm = ChatOpenAI(model="gpt-4")
+mem0 = MemoryClient()
+
+class State(TypedDict):
+    messages: Annotated[List[HumanMessage | AIMessage], add_messages]
+    mem0_user_id: str
+
+def chatbot(state: State):
+    messages = state["messages"]
+    user_id = state["mem0_user_id"]
+
+    # Retrieve relevant memories
+    memories = mem0.search(messages[-1].content, user_id=user_id)
+    context = "Relevant context:\n"
+    for memory in memories["results"]:
+        context += f"- {memory['memory']}\n"
+
+    system_message = SystemMessage(content=f"""You are a helpful support assistant.
+{context}""")
+
+    response = llm.invoke([system_message] + messages)
+
+    # Store the interaction
+    mem0.add(
+        [{"role": "user", "content": messages[-1].content},
+         {"role": "assistant", "content": response.content}],
+        user_id=user_id
+    )
+    return {"messages": [response]}
+
+graph = StateGraph(State)
+graph.add_node("chatbot", chatbot)
+graph.add_edge(START, "chatbot")
+app = graph.compile()
+
+# Usage
+result = app.invoke({
+    "messages": [HumanMessage(content="I need help with my order")],
+    "mem0_user_id": "customer_123"
+})
+```
+
+---
+
+## LlamaIndex
+
+Source: [docs.mem0.ai/integrations/llama-index](https://docs.mem0.ai/integrations/llama-index)
+
+Install: `pip install llama-index-core llama-index-memory-mem0`
+
+LlamaIndex has native Mem0 support via `Mem0Memory`. Works with ReAct and FunctionCalling agents.
+
+```python
+from llama_index.memory.mem0 import Mem0Memory
+
+context = {"user_id": "alice", "agent_id": "llama_agent_1"}
+memory = Mem0Memory.from_client(
+    context=context,
+    search_msg_limit=4,  # messages from chat history used for retrieval (default: 5)
+)
+
+# Use with LlamaIndex agent
+from llama_index.core.agent import FunctionCallingAgent
+from llama_index.llms.openai import OpenAI
+
+llm = OpenAI(model="gpt-4")
+agent = FunctionCallingAgent.from_tools(
+    tools=[],
+    llm=llm,
+    memory=memory,
+    verbose=True,
+)
+
+response = agent.chat("I prefer vegetarian restaurants")
+# Memory automatically stores and retrieves context
+response = agent.chat("What kind of food do I like?")
+# Agent retrieves the vegetarian preference from Mem0
+```
+
+---
+
+## AutoGen
+
+Source: [docs.mem0.ai/integrations/autogen](https://docs.mem0.ai/integrations/autogen)
+
+Install: `pip install autogen mem0ai`
+
+Multi-agent conversational systems with memory persistence.
+
+```python
+from autogen import ConversableAgent
+from mem0 import MemoryClient
+
+memory_client = MemoryClient()
+USER_ID = "alice"
+
+agent = ConversableAgent(
+    "chatbot",
+    llm_config={"config_list": [{"model": "gpt-4", "api_key": os.environ["OPENAI_API_KEY"]}]},
+    code_execution_config=False,
+    human_input_mode="NEVER",
+)
+
+def get_context_aware_response(question: str) -> str:
+    # Retrieve memories for context
+    relevant_memories = memory_client.search(question, user_id=USER_ID)
+    context = "\n".join([m["memory"] for m in relevant_memories.get("results", [])])
+
+    prompt = f"""Answer considering previous interactions:
+    Previous context: {context}
+    Question: {question}"""
+
+    reply = agent.generate_reply(messages=[{"content": prompt, "role": "user"}])
+
+    # Store the new interaction
+    memory_client.add(
+        [{"role": "user", "content": question}, {"role": "assistant", "content": reply}],
+        user_id=USER_ID
+    )
+    return reply
+```
+
+---
+
+## All Supported Frameworks
+
+Beyond the examples above, Mem0 integrates with:
+
+| Framework | Type | Install |
+|-----------|------|---------|
+| [Mastra](https://docs.mem0.ai/integrations/mastra) | TS agent framework | `npm install @mastra/mem0` |
+| [ElevenLabs](https://docs.mem0.ai/integrations/elevenlabs) | Voice AI | `pip install elevenlabs mem0ai` |
+| [LiveKit](https://docs.mem0.ai/integrations/livekit) | Real-time voice/video | `pip install livekit-agents mem0ai` |
+| [Camel AI](https://docs.mem0.ai/integrations/camel-ai) | Multi-agent framework | `pip install camel-ai[all] mem0ai` |
+| [AWS Bedrock](https://docs.mem0.ai/integrations/aws-bedrock) | Cloud LLM provider | `pip install boto3 mem0ai` |
+| [Dify](https://docs.mem0.ai/integrations/dify) | Low-code AI platform | Plugin-based |
+| [Google AI ADK](https://docs.mem0.ai/integrations/google-ai-adk) | Google agent framework | `pip install google-adk mem0ai` |
+
+For the general Python pattern (no framework), see the "Common integration pattern" in [SKILL.md](../SKILL.md).
@@ -0,0 +1,119 @@
+# Mem0 Platform Quickstart
+
+Get running with Mem0 in 2 minutes. No infrastructure to deploy -- just an API key.
+
+## Prerequisites
+
+- Python 3.10+ or Node.js 18+
+- A Mem0 Platform API key ([Get one here](https://app.mem0.ai/dashboard/api-keys))
+
+## Python Setup
+
+```bash
+pip install mem0ai
+export MEM0_API_KEY="m0-your-api-key"
+```
+
+```python
+from mem0 import MemoryClient
+
+client = MemoryClient(api_key="your-api-key")
+
+# Add a memory
+messages = [
+    {"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
+    {"role": "assistant", "content": "Got it! I'll remember your dietary preferences."}
+]
+client.add(messages, user_id="user123")
+
+# Search memories
+results = client.search("What are my dietary restrictions?", user_id="user123")
+print(results)
+```
+
+### Async Client
+
+```python
+from mem0 import AsyncMemoryClient
+
+client = AsyncMemoryClient(api_key="your-api-key")
+
+await client.add(messages, user_id="user123")
+results = await client.search("query", user_id="user123")
+```
+
+## TypeScript / JavaScript Setup
+
+```bash
+npm install mem0ai
+export MEM0_API_KEY="m0-your-api-key"
+```
+
+```javascript
+import MemoryClient from 'mem0ai';
+
+const client = new MemoryClient({ apiKey: 'your-api-key' });
+
+// Add a memory
+const messages = [
+    {"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
+    {"role": "assistant", "content": "Got it! I'll remember your dietary preferences."}
+];
+await client.add(messages, { user_id: "user123" });
+
+// Search memories
+const results = await client.search("What are my dietary restrictions?", {
+    user_id: "user123"
+});
+console.log(results);
+```
+
+## cURL
+
+```bash
+export MEM0_API_KEY="m0-your-api-key"
+
+# Add memory
+curl -X POST https://api.mem0.ai/v1/memories/ \
+  -H "Authorization: Token $MEM0_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "I am a vegetarian and allergic to nuts."},
+      {"role": "assistant", "content": "Got it! I will remember your dietary preferences."}
+    ],
+    "user_id": "user123"
+  }'
+
+# Search memories
+curl -X POST https://api.mem0.ai/v2/memories/search/ \
+  -H "Authorization: Token $MEM0_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "query": "What are my dietary restrictions?",
+    "filters": {"user_id": "user123"}
+  }'
+```
+
+## Sample Response
+
+```json
+{
+  "results": [
+    {
+      "id": "14e1b28a-2014-40ad-ac42-69c9ef42193d",
+      "memory": "Allergic to nuts",
+      "user_id": "user123",
+      "categories": ["health"],
+      "created_at": "2025-10-22T04:40:22.864647-07:00",
+      "score": 0.30
+    }
+  ]
+}
+```
+
+## Next Steps
+
+- [SDK Guide](sdk-guide.md) -- all methods for Python and TypeScript
+- [API Reference](api-reference.md) -- REST endpoints and memory object structure
+- [Integration Patterns](integration-patterns.md) -- LangChain, CrewAI, Vercel AI, etc.
@@ -0,0 +1,308 @@
+# Mem0 SDK Guide
+
+Complete SDK reference for Python and TypeScript. All methods use `MemoryClient` (Platform API).
+
+## Initialization
+
+**Python:**
+```python
+from mem0 import MemoryClient
+client = MemoryClient(api_key="m0-your-api-key")
+```
+
+**Python (Async):**
+```python
+from mem0 import AsyncMemoryClient
+client = AsyncMemoryClient(api_key="m0-your-api-key")
+```
+
+**TypeScript:**
+```typescript
+import MemoryClient from 'mem0ai';
+const client = new MemoryClient({ apiKey: 'm0-your-api-key' });
+```
+
+Constructor accepts `apiKey` (required) and `host` (optional, default: `https://api.mem0.ai`).
+
+---
+
+## add() -- Store Memories
+
+**Python:**
+```python
+messages = [
+    {"role": "user", "content": "I'm a vegetarian and allergic to nuts."},
+    {"role": "assistant", "content": "Got it! I'll remember that."}
+]
+client.add(messages, user_id="alice")
+
+# With metadata
+client.add(messages, user_id="alice", metadata={"source": "onboarding"})
+
+# With graph memory
+client.add(messages, user_id="alice", enable_graph=True)
+```
+
+**TypeScript:**
+```typescript
+await client.add(messages, { user_id: "alice" });
+await client.add(messages, { user_id: "alice", metadata: { source: "onboarding" } });
+await client.add(messages, { user_id: "alice", enable_graph: true });
+```
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `messages` | array | `[{"role": "user", "content": "..."}]` |
+| `user_id` | string | User identifier (recommended) |
+| `agent_id` | string | Agent identifier |
+| `run_id` | string | Session identifier |
+| `metadata` | object | Custom key-value pairs |
+| `enable_graph` | boolean | Activate knowledge graph |
+| `infer` | boolean | If `false`, store raw text without inference (default: `true`) |
+| `immutable` | boolean | Prevents modification after creation |
+| `expiration_date` | string | Auto-expiry date (`YYYY-MM-DD`) |
+| `includes` | string | Preference filters for inclusion |
+| `excludes` | string | Preference filters for exclusion |
+| `async_mode` | boolean | Async processing (default: `true`). Set `false` to wait |
+
+### Advanced Add Options
+
+```python
+# Immutable -- cannot be modified or overwritten
+client.add(messages, user_id="alice", immutable=True)
+
+# Expiring memory
+client.add(messages, user_id="alice", expiration_date="2025-12-31")
+
+# Selective extraction
+client.add(messages, user_id="alice", includes="dietary preferences", excludes="payment info")
+
+# Agent + session scoping
+client.add(messages, user_id="alice", agent_id="nutrition-agent", run_id="session-456")
+
+# Synchronous processing (wait for completion)
+client.add(messages, user_id="alice", async_mode=False)
+
+# Raw text -- skip LLM inference
+client.add(
+    [{"role": "user", "content": "User prefers dark mode."}],
+    user_id="alice",
+    infer=False,
+)
+```
+
+---
+
+## search() -- Find Memories
+
+**Python:**
+```python
+results = client.search("dietary preferences?", user_id="alice")
+
+# With filters and reranking
+results = client.search(
+    query="work experience",
+    filters={"AND": [{"user_id": "alice"}, {"categories": {"contains": "professional_details"}}]},
+    top_k=5,
+    rerank=True,
+    threshold=0.5
+)
+
+# With graph relations
+results = client.search("colleagues", user_id="alice", enable_graph=True)
+
+# Keyword search
+results = client.search("vegetarian", user_id="alice", keyword_search=True)
+```
+
+**TypeScript:**
+```typescript
+const results = await client.search("dietary preferences", { user_id: "alice" });
+const results = await client.search("work experience", {
+    filters: { AND: [{ user_id: "alice" }, { categories: { contains: "professional_details" } }] },
+    top_k: 5,
+    rerank: true,
+});
+```
+
+### Parameters
+
+| Name | Type | Description |
+|------|------|-------------|
+| `query` | string | Natural language search query |
+| `user_id` | string | Filter by user |
+| `filters` | object | V2 filter object (AND/OR operators) |
+| `top_k` | number | Number of results (default: 10) |
+| `rerank` | boolean | Enable reranking for better relevance |
+| `threshold` | number | Minimum similarity score (default: 0.3) |
+| `keyword_search` | boolean | Use keyword-based search |
+| `enable_graph` | boolean | Include graph relations |
+
+### Common Filter Patterns
+
+```python
+# Single user (shorthand)
+client.search("query", user_id="alice")
+
+# OR across agents
+filters={"OR": [{"user_id": "alice"}, {"agent_id": {"in": ["travel-agent", "sports-agent"]}}]}
+
+# Category filtering (partial match)
+filters={"AND": [{"user_id": "alice"}, {"categories": {"contains": "finance"}}]}
+
+# Category filtering (exact match)
+filters={"AND": [{"user_id": "alice"}, {"categories": {"in": ["personal_information"]}}]}
+
+# Wildcard (match any non-null run)
+filters={"AND": [{"user_id": "alice"}, {"run_id": "*"}]}
+
+# Date range
+filters={"AND": [
+    {"user_id": "alice"},
+    {"created_at": {"gte": "2024-01-01T00:00:00Z"}},
+    {"created_at": {"lt": "2024-02-01T00:00:00Z"}}
+]}
+
+# Exclude categories with NOT
+filters={"AND": [{"user_id": "user_123"}, {"NOT": {"categories": {"in": ["spam", "test"]}}}]}
+
+# Multi-dimensional query
+filters={"AND": [
+    {"user_id": "user_123"},
+    {"keywords": {"icontains": "invoice"}},
+    {"categories": {"in": ["finance"]}},
+    {"created_at": {"gte": "2024-01-01T00:00:00Z"}}
+]}
+```
+
+---
+
+## get() / getAll() -- Retrieve Memories
+
+**Python:**
+```python
+# Single memory by ID
+memory = client.get(memory_id="ea925981-...")
+
+# All memories for a user
+memories = client.get_all(filters={"AND": [{"user_id": "alice"}]})
+
+# With date range
+memories = client.get_all(
+    filters={"AND": [
+        {"user_id": "alex"},
+        {"created_at": {"gte": "2024-07-01", "lte": "2024-07-31"}}
+    ]}
+)
+
+# With graph data
+memories = client.get_all(filters={"AND": [{"user_id": "alice"}]}, enable_graph=True)
+```
+
+**TypeScript:**
+```typescript
+const memory = await client.get("ea925981-...");
+const memories = await client.getAll({ filters: { AND: [{ user_id: "alice" }] } });
+```
+
+**Note:** `get_all` requires at least one of `user_id`, `agent_id`, `app_id`, or `run_id` in filters.
+
+---
+
+## update() -- Modify Memories
+
+**Python:**
+```python
+client.update(memory_id="ea925981-...", text="Updated: vegan since 2024")
+client.update(memory_id="ea925981-...", text="Updated", metadata={"verified": True})
+```
+
+**TypeScript:**
+```typescript
+await client.update("ea925981-...", { text: "Updated: vegan since 2024" });
+```
+
+Cannot update immutable memories.
+
+---
+
+## delete() / deleteAll() -- Remove Memories
+
+**Python:**
+```python
+client.delete(memory_id="ea925981-...")
+client.delete_all(user_id="alice")  # Irreversible bulk delete
+```
+
+**TypeScript:**
+```typescript
+await client.delete("ea925981-...");
+await client.deleteAll({ user_id: "alice" });
+```
+
+---
+
+## history() -- Track Changes
+
+**Python:**
+```python
+history = client.history(memory_id="ea925981-...")
+# Returns: [{previous_value, new_value, action, timestamps}]
+```
+
+**TypeScript:**
+```typescript
+const history = await client.history("ea925981-...");
+```
+
+---
+
+## Batch Operations (TypeScript)
+
+```typescript
+// Batch update
+await client.batchUpdate([
+    { memoryId: "uuid-1", text: "Updated text" },
+    { memoryId: "uuid-2", text: "Another updated text" },
+]);
+
+// Batch delete
+await client.batchDelete(["uuid-1", "uuid-2", "uuid-3"]);
+```
+
+---
+
+## Additional Methods
+
+```python
+# List all users/agents/sessions with memories
+users = client.users()
+
+# Delete a user/agent entity
+client.delete_users(user_id="alice")
+
+# Submit feedback on a memory
+client.feedback(memory_id="...", feedback="POSITIVE", feedback_reason="Accurate extraction")
+
+# Export memories
+export = client.create_memory_export(filters={"AND": [{"user_id": "alice"}]})
+data = client.get_memory_export(memory_export_id=export["id"])
+```
+
+---
+
+## Common Pitfalls
+
+1. **Entity cross-filtering fails silently** -- `AND` with `user_id` + `agent_id` returns empty. Use `OR`.
+2. **SQL operators rejected** -- use `gte`, `lt`, etc. Not `>=`, `<`.
+3. **Metadata filtering is limited** -- only top-level keys with `eq`, `contains`, `ne`.
+4. **Wildcard `*` excludes null** -- only matches non-null values.
+5. **Default threshold is 0.3** -- increase for stricter matching.
+6. **Async processing** -- memories process asynchronously. Wait 2-3s after `add()` before searching.
+7. **Immutable memories** -- cannot be updated or deleted once created.
+
+## Naming Conventions
+
+Python uses `snake_case` (`user_id`, `memory_id`, `get_all`). TypeScript uses `camelCase` for methods (`getAll`, `deleteAll`, `batchUpdate`) but `snake_case` for API parameters (`user_id`, `agent_id`).
@@ -0,0 +1,720 @@
+# Mem0 Use Cases & Examples
+
+Real-world implementation patterns for Mem0 Platform. Each use case includes complete, runnable code in both Python and TypeScript.
+
+## Table of Contents
+
+- [Personalized AI Companion](#1-personalized-ai-companion)
+- [Customer Support with Categories](#2-customer-support-with-categories)
+- [Healthcare Coach](#3-healthcare-coach)
+- [Content Creation Workflow](#4-content-creation-workflow)
+- [Multi-Agent / Multi-Tenant](#5-multi-agent--multi-tenant)
+- [Personalized Search](#6-personalized-search)
+- [Email Intelligence](#7-email-intelligence)
+- [Common Patterns Across Use Cases](#common-patterns-across-use-cases)
+
+---
+
+## 1. Personalized AI Companion
+
+A fitness coach that remembers goals, preferences, and progress across sessions. Mem0 persists context across app restarts — no session state needed.
+
+### Implementation (Python)
+
+```python
+from mem0 import MemoryClient
+from openai import OpenAI
+
+mem0 = MemoryClient()
+openai_client = OpenAI()
+
+def chat(user_input: str, user_id: str) -> str:
+    # 1. Retrieve relevant memories
+    memories = mem0.search(user_input, user_id=user_id)
+    context = "\n".join([f"- {m['memory']}" for m in memories.get("results", [])])
+
+    # 2. Generate response with memory context
+    system_prompt = f"""You are Ray, a personal fitness coach.
+Use these known facts about the user to personalize your response:
+{context if context else 'No prior context yet.'}"""
+
+    response = openai_client.chat.completions.create(
+        model="gpt-4.1-nano-2025-04-14",
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": user_input},
+        ]
+    )
+    reply = response.choices[0].message.content
+
+    # 3. Store interaction for future context
+    mem0.add(
+        [{"role": "user", "content": user_input}, {"role": "assistant", "content": reply}],
+        user_id=user_id
+    )
+    return reply
+
+# Usage
+chat("I want to run a marathon in under 4 hours", user_id="max")
+# Next day, app restarted:
+chat("What should I focus on today?", user_id="max")
+# Ray remembers the sub-4 marathon goal
+```
+
+### Implementation (TypeScript)
+
+```typescript
+import MemoryClient from 'mem0ai';
+import OpenAI from 'openai';
+
+const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
+const openai = new OpenAI();
+
+async function chat(userInput: string, userId: string): Promise<string> {
+    // 1. Retrieve relevant memories
+    const memories = await mem0.search(userInput, { user_id: userId });
+    const context = memories.results
+        ?.map((m: any) => `- ${m.memory}`)
+        .join('\n') || 'No prior context yet.';
+
+    // 2. Generate response with memory context
+    const response = await openai.chat.completions.create({
+        model: 'gpt-4.1-nano-2025-04-14',
+        messages: [
+            { role: 'system', content: `You are Ray, a personal fitness coach.\nUser context:\n${context}` },
+            { role: 'user', content: userInput },
+        ],
+    });
+    const reply = response.choices[0].message.content!;
+
+    // 3. Store interaction
+    await mem0.add(
+        [{ role: 'user', content: userInput }, { role: 'assistant', content: reply }],
+        { user_id: userId }
+    );
+    return reply;
+}
+```
+
+### Key Benefits
+
+- Context persists across app restarts — no session management needed
+- Memories are automatically deduplicated and updated
+- Works with any LLM provider (OpenAI, Anthropic, etc.)
+
+**Best for:** Fitness coaches, tutors, therapists — any assistant that needs to remember goals across sessions.
+
+---
+
+## 2. Customer Support with Categories
+
+Auto-categorize support data so teams retrieve the right facts fast. Uses custom categories for structured retrieval.
+
+### Implementation (Python)
+
+```python
+from mem0 import MemoryClient
+
+client = MemoryClient()
+
+# 1. Define categories at the project level (one-time setup)
+custom_categories = [
+    {"support_tickets": "Customer issues and resolutions"},
+    {"account_info": "Account details and preferences"},
+    {"billing": "Payment history and billing questions"},
+    {"product_feedback": "Feature requests and feedback"},
+]
+client.project.update(custom_categories=custom_categories)
+
+# 2. Store interactions — auto-classified into categories
+def log_support_interaction(user_id: str, message: str, priority: str = "normal"):
+    client.add(
+        [{"role": "user", "content": message}],
+        user_id=user_id,
+        metadata={"priority": priority, "source": "support_chat"}
+    )
+
+# 3. Retrieve by category
+def get_billing_issues(user_id: str):
+    return client.get_all(
+        filters={
+            "AND": [
+                {"user_id": user_id},
+                {"categories": {"in": ["billing"]}}
+            ]
+        }
+    )
+
+def search_support_history(user_id: str, query: str):
+    return client.search(
+        query,
+        filters={
+            "AND": [
+                {"user_id": user_id},
+                {"categories": {"contains": "support_tickets"}}
+            ]
+        },
+        top_k=5
+    )
+
+# Usage
+log_support_interaction("maria", "I was charged twice for last month's subscription", priority="high")
+log_support_interaction("maria", "The dashboard is loading slowly on mobile")
+billing = get_billing_issues("maria")  # Returns only billing-related memories
+```
+
+### Implementation (TypeScript)
+
+```typescript
+import MemoryClient from 'mem0ai';
+
+const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
+
+// Setup categories (one-time)
+await client.updateProject({
+    custom_categories: [
+        { support_tickets: 'Customer issues and resolutions' },
+        { billing: 'Payment history and billing questions' },
+        { product_feedback: 'Feature requests and feedback' },
+    ],
+});
+
+async function logInteraction(userId: string, message: string, priority = 'normal') {
+    await client.add(
+        [{ role: 'user', content: message }],
+        { user_id: userId, metadata: { priority, source: 'support_chat' } }
+    );
+}
+
+async function getBillingIssues(userId: string) {
+    return client.getAll({
+        filters: { AND: [{ user_id: userId }, { categories: { in: ['billing'] } }] },
+    });
+}
+```
+
+### Key Benefits
+
+- Automatic categorization — no manual tagging
+- Filter by category for structured retrieval
+- Metadata (`priority`, `source`) enables multi-dimensional queries
+
+**Best for:** Help desks, SaaS support, e-commerce — structured retrieval by category eliminates manual scanning.
+
+---
+
+## 3. Healthcare Coach
+
+Guide patients with an assistant that remembers medical history. Uses high `threshold` for confident retrieval in safety-critical contexts.
+
+### Implementation (Python)
+
+```python
+from mem0 import MemoryClient
+from openai import OpenAI
+
+mem0 = MemoryClient()
+openai_client = OpenAI()
+
+def save_patient_info(user_id: str, information: str):
+    mem0.add(
+        [{"role": "user", "content": information}],
+        user_id=user_id,
+        run_id="healthcare_session",
+        metadata={"type": "patient_information"}
+    )
+
+def consult(user_id: str, question: str) -> str:
+    # High threshold for medical accuracy
+    memories = mem0.search(question, user_id=user_id, top_k=5, threshold=0.7)
+    context = "\n".join([f"- {m['memory']}" for m in memories.get("results", [])])
+
+    response = openai_client.chat.completions.create(
+        model="gpt-4.1-nano-2025-04-14",
+        messages=[
+            {"role": "system", "content": f"You are a health coach. Patient context:\n{context}"},
+            {"role": "user", "content": question},
+        ]
+    )
+    reply = response.choices[0].message.content
+
+    # Store the interaction
+    mem0.add(
+        [{"role": "user", "content": question}, {"role": "assistant", "content": reply}],
+        user_id=user_id,
+        run_id="healthcare_session",
+    )
+    return reply
+
+# Usage
+save_patient_info("alex", "I'm allergic to penicillin and take metformin for type 2 diabetes")
+consult("alex", "Can I take amoxicillin for my sore throat?")
+# Remembers penicillin allergy — amoxicillin is a penicillin-type antibiotic
+```
+
+### Implementation (TypeScript)
+
+```typescript
+import MemoryClient from 'mem0ai';
+import OpenAI from 'openai';
+
+const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
+const openai = new OpenAI();
+
+async function savePatientInfo(userId: string, info: string) {
+    await mem0.add(
+        [{ role: 'user', content: info }],
+        { user_id: userId, run_id: 'healthcare_session', metadata: { type: 'patient_information' } }
+    );
+}
+
+async function consult(userId: string, question: string): Promise<string> {
+    const memories = await mem0.search(question, {
+        user_id: userId,
+        top_k: 5,
+        threshold: 0.7,
+    });
+    const context = memories.results?.map((m: any) => `- ${m.memory}`).join('\n') || '';
+
+    const response = await openai.chat.completions.create({
+        model: 'gpt-4.1-nano-2025-04-14',
+        messages: [
+            { role: 'system', content: `You are a health coach. Patient context:\n${context}` },
+            { role: 'user', content: question },
+        ],
+    });
+    const reply = response.choices[0].message.content!;
+
+    await mem0.add(
+        [{ role: 'user', content: question }, { role: 'assistant', content: reply }],
+        { user_id: userId, run_id: 'healthcare_session' }
+    );
+    return reply;
+}
+```
+
+### Key Benefits
+
+- High threshold (0.7) ensures only confident matches for safety-critical retrieval
+- Session scoping via `run_id` groups related health interactions
+- Metadata tagging separates patient info from conversation history
+
+**Best for:** Telehealth, wellness apps, patient management — persistent health context across visits.
+
+---
+
+## 4. Content Creation Workflow
+
+Store voice guidelines once and apply them across every draft. Uses `run_id` and `metadata` to scope writing preferences per session.
+
+### Implementation (Python)
+
+```python
+from mem0 import MemoryClient
+from openai import OpenAI
+
+mem0 = MemoryClient()
+openai_client = OpenAI()
+
+def store_writing_preferences(user_id: str, preferences: str):
+    mem0.add(
+        [{"role": "user", "content": preferences}],
+        user_id=user_id,
+        run_id="editing_session",
+        metadata={"type": "preferences", "category": "writing_style"}
+    )
+
+def draft_content(user_id: str, topic: str) -> str:
+    # Retrieve writing preferences
+    prefs = mem0.search(
+        "writing style preferences",
+        filters={"AND": [{"user_id": user_id}, {"run_id": "editing_session"}]}
+    )
+    style_context = "\n".join([f"- {m['memory']}" for m in prefs.get("results", [])])
+
+    response = openai_client.chat.completions.create(
+        model="gpt-4.1-nano-2025-04-14",
+        messages=[
+            {"role": "system", "content": f"Write content matching these style preferences:\n{style_context}"},
+            {"role": "user", "content": f"Write a blog post about: {topic}"},
+        ]
+    )
+    return response.choices[0].message.content
+
+# Usage
+store_writing_preferences("writer_01", "I prefer short sentences. Active voice. No jargon. Use analogies.")
+draft_content("writer_01", "Why AI memory matters for chatbots")
+# Drafts content matching the stored voice guidelines
+```
+
+### Implementation (TypeScript)
+
+```typescript
+import MemoryClient from 'mem0ai';
+import OpenAI from 'openai';
+
+const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
+const openai = new OpenAI();
+
+async function storePreferences(userId: string, preferences: string) {
+    await mem0.add(
+        [{ role: 'user', content: preferences }],
+        { user_id: userId, run_id: 'editing_session', metadata: { type: 'preferences' } }
+    );
+}
+
+async function draftContent(userId: string, topic: string): Promise<string> {
+    const prefs = await mem0.search('writing style preferences', {
+        filters: { AND: [{ user_id: userId }, { run_id: 'editing_session' }] },
+    });
+    const styleContext = prefs.results?.map((m: any) => `- ${m.memory}`).join('\n') || '';
+
+    const response = await openai.chat.completions.create({
+        model: 'gpt-4.1-nano-2025-04-14',
+        messages: [
+            { role: 'system', content: `Write content matching these preferences:\n${styleContext}` },
+            { role: 'user', content: `Write a blog post about: ${topic}` },
+        ],
+    });
+    return response.choices[0].message.content!;
+}
+```
+
+### Key Benefits
+
+- Voice consistency across all content without repeating guidelines
+- Scoped sessions let you maintain different style profiles
+- Preferences update automatically as you refine them
+
+**Best for:** Marketing teams, technical writers, agencies — consistent voice across all content.
+
+---
+
+## 5. Multi-Agent / Multi-Tenant
+
+Keep memories separate using `user_id`, `agent_id`, `app_id`, and `run_id` scoping. Critical for multi-agent workflows and multi-tenant apps.
+
+### Implementation (Python)
+
+```python
+from mem0 import MemoryClient
+
+client = MemoryClient()
+
+# Store memories scoped to user + agent + session
+def store_scoped_memory(messages: list, user_id: str, agent_id: str, run_id: str, app_id: str):
+    client.add(
+        messages,
+        user_id=user_id,
+        agent_id=agent_id,
+        run_id=run_id,
+        app_id=app_id
+    )
+
+# Query within a specific scope
+def search_user_session(query: str, user_id: str, app_id: str, run_id: str):
+    """Search memories for a specific user within a specific session."""
+    return client.search(
+        query,
+        filters={
+            "AND": [
+                {"user_id": user_id},
+                {"app_id": app_id},
+                {"run_id": run_id}
+            ]
+        }
+    )
+
+def search_agent_knowledge(query: str, agent_id: str, app_id: str):
+    """Search all memories an agent has across all users."""
+    return client.search(
+        query,
+        filters={
+            "AND": [
+                {"agent_id": agent_id},
+                {"app_id": app_id}
+            ]
+        }
+    )
+
+# Usage: Travel concierge app with multiple agents
+store_scoped_memory(
+    [{"role": "user", "content": "I'm vegetarian and prefer window seats"}],
+    user_id="traveler_cam",
+    agent_id="travel_planner",
+    run_id="tokyo-2025",
+    app_id="concierge_app"
+)
+
+# User-scoped query: "What does Cam prefer?"
+user_mems = search_user_session("dietary restrictions?", "traveler_cam", "concierge_app", "tokyo-2025")
+
+# Agent-scoped query: "What do all travelers prefer?" (across users)
+agent_mems = search_agent_knowledge("common dietary restrictions?", "travel_planner", "concierge_app")
+```
+
+### Implementation (TypeScript)
+
+```typescript
+import MemoryClient from 'mem0ai';
+
+const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
+
+async function storeScopedMemory(
+    messages: Array<{ role: string; content: string }>,
+    userId: string, agentId: string, runId: string, appId: string
+) {
+    await client.add(messages, {
+        user_id: userId,
+        agent_id: agentId,
+        run_id: runId,
+        app_id: appId,
+    });
+}
+
+async function searchUserSession(query: string, userId: string, appId: string, runId: string) {
+    return client.search(query, {
+        filters: { AND: [{ user_id: userId }, { app_id: appId }, { run_id: runId }] },
+    });
+}
+
+async function searchAgentKnowledge(query: string, agentId: string, appId: string) {
+    return client.search(query, {
+        filters: { AND: [{ agent_id: agentId }, { app_id: appId }] },
+    });
+}
+```
+
+### Key Benefits
+
+- Full isolation between users, agents, sessions, and apps
+- Query at any scope level — user, agent, session, or app-wide
+- No memory leakage between tenants
+
+**Best for:** Multi-agent workflows, multi-tenant SaaS — proper isolation at every level.
+
+---
+
+## 6. Personalized Search
+
+Blend real-time search results with personal context. Uses `custom_instructions` to infer preferences from queries.
+
+### Implementation (Python)
+
+```python
+from mem0 import MemoryClient
+from openai import OpenAI
+
+mem0 = MemoryClient()
+openai_client = OpenAI()
+
+# One-time setup: configure Mem0 to infer from queries
+mem0.project.update(
+    custom_instructions="""Infer user preferences and facts from their search queries.
+Extract dietary preferences, location, interests, and purchase history."""
+)
+
+def personalized_search(user_id: str, query: str, search_results: list) -> str:
+    # Get user context from memory
+    memories = mem0.search(query, user_id=user_id, top_k=5)
+    user_context = "\n".join([f"- {m['memory']}" for m in memories.get("results", [])])
+
+    response = openai_client.chat.completions.create(
+        model="gpt-4.1-nano-2025-04-14",
+        messages=[
+            {"role": "system", "content": f"Personalize search results using user context:\n{user_context}"},
+            {"role": "user", "content": f"Query: {query}\n\nSearch results:\n{search_results}"},
+        ]
+    )
+    reply = response.choices[0].message.content
+
+    # Store the query to learn preferences over time
+    mem0.add(
+        [{"role": "user", "content": query}],
+        user_id=user_id
+    )
+    return reply
+
+# Usage
+personalized_search("user_42", "best restaurants nearby", ["Restaurant A", "Restaurant B"])
+# Over time, Mem0 learns: "user prefers vegetarian, lives in Austin"
+# Future searches are automatically personalized
+```
+
+### Implementation (TypeScript)
+
+```typescript
+import MemoryClient from 'mem0ai';
+import OpenAI from 'openai';
+
+const mem0 = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
+const openai = new OpenAI();
+
+async function personalizedSearch(userId: string, query: string, searchResults: string[]): Promise<string> {
+    const memories = await mem0.search(query, { user_id: userId, top_k: 5 });
+    const context = memories.results?.map((m: any) => `- ${m.memory}`).join('\n') || '';
+
+    const response = await openai.chat.completions.create({
+        model: 'gpt-4.1-nano-2025-04-14',
+        messages: [
+            { role: 'system', content: `Personalize results using user context:\n${context}` },
+            { role: 'user', content: `Query: ${query}\nResults: ${searchResults.join(', ')}` },
+        ],
+    });
+    const reply = response.choices[0].message.content!;
+
+    await mem0.add([{ role: 'user', content: query }], { user_id: userId });
+    return reply;
+}
+```
+
+### Key Benefits
+
+- Learns preferences from queries automatically via `custom_instructions`
+- Personalizes any search provider (Tavily, Google, Bing)
+- Zero manual preference setup — improves over time
+
+**Best for:** Personalized search engines, recommendation systems — search results tailored to individual users.
+
+---
+
+## 7. Email Intelligence
+
+Capture, categorize, and recall inbox threads using persistent memories with rich metadata.
+
+### Implementation (Python)
+
+```python
+from mem0 import MemoryClient
+
+client = MemoryClient()
+
+def store_email(user_id: str, sender: str, subject: str, body: str, date: str):
+    client.add(
+        [{"role": "user", "content": f"Email from {sender}: {subject}\n\n{body}"}],
+        user_id=user_id,
+        metadata={"email_type": "incoming", "sender": sender, "subject": subject, "date": date}
+    )
+
+def search_emails(user_id: str, query: str):
+    return client.search(
+        query,
+        filters={"AND": [{"user_id": user_id}, {"categories": {"contains": "email"}}]},
+        top_k=10
+    )
+
+def get_emails_from_sender(user_id: str, sender: str):
+    return client.get_all(
+        filters={
+            "AND": [
+                {"user_id": user_id},
+                {"metadata": {"contains": sender}}
+            ]
+        }
+    )
+
+# Usage
+store_email("alice", "bob@acme.com", "Q3 Budget Review", "Attached is the Q3 budget...", "2025-01-15")
+store_email("alice", "carol@acme.com", "Sprint Planning", "Here are the priorities...", "2025-01-16")
+
+results = search_emails("alice", "budget discussions")
+sender_emails = get_emails_from_sender("alice", "bob@acme.com")
+```
+
+### Implementation (TypeScript)
+
+```typescript
+import MemoryClient from 'mem0ai';
+
+const client = new MemoryClient({ apiKey: process.env.MEM0_API_KEY! });
+
+async function storeEmail(userId: string, sender: string, subject: string, body: string, date: string) {
+    await client.add(
+        [{ role: 'user', content: `Email from ${sender}: ${subject}\n\n${body}` }],
+        { user_id: userId, metadata: { email_type: 'incoming', sender, subject, date } }
+    );
+}
+
+async function searchEmails(userId: string, query: string) {
+    return client.search(query, {
+        filters: { AND: [{ user_id: userId }, { categories: { contains: 'email' } }] },
+        top_k: 10,
+    });
+}
+```
+
+### Key Benefits
+
+- Rich metadata enables multi-dimensional queries (sender, date, subject)
+- Category filtering separates emails from other memory types
+- Semantic search across all email content
+
+**Best for:** Inbox management, email automation — searchable email memories with metadata filtering.
+
+---
+
+## Common Patterns Across Use Cases
+
+### Pattern 1: Retrieve → Generate → Store
+
+Every use case follows the same 3-step loop:
+
+```python
+# 1. Retrieve relevant context
+memories = mem0.search(user_input, user_id=user_id)
+context = "\n".join([m["memory"] for m in memories.get("results", [])])
+
+# 2. Generate with context
+response = llm.generate(system_prompt=f"Context:\n{context}", user_input=user_input)
+
+# 3. Store the interaction
+mem0.add(
+    [{"role": "user", "content": user_input}, {"role": "assistant", "content": response}],
+    user_id=user_id
+)
+```
+
+### Pattern 2: Scope with Entity Identifiers
+
+Use `user_id`, `agent_id`, `app_id`, and `run_id` to isolate memories:
+
+```python
+# User-level: personal preferences
+client.add(messages, user_id="alice")
+
+# Session-level: conversation within one session
+client.add(messages, user_id="alice", run_id="session_123")
+
+# Agent-level: agent-specific knowledge
+client.add(messages, agent_id="support_bot", app_id="helpdesk")
+```
+
+### Pattern 3: Rich Metadata for Filtering
+
+Attach structured metadata for multi-dimensional queries:
+
+```python
+# Store with metadata
+client.add(messages, user_id="alice", metadata={"priority": "high", "source": "phone_call"})
+
+# Filter by category + metadata
+client.search("billing issues", filters={
+    "AND": [{"user_id": "alice"}, {"categories": {"contains": "billing"}}]
+})
+```
+
+### Pattern 4: Custom Instructions for Domain-Specific Extraction
+
+Control what Mem0 extracts from conversations:
+
+```python
+client.project.update(
+    custom_instructions="Extract medical conditions, medications, and allergies. Exclude billing info."
+)
+```
+
+---
+
+## More Examples
+
+For 30+ cookbooks with complete working code: [docs.mem0.ai/cookbooks](https://docs.mem0.ai/cookbooks)
@@ -0,0 +1,224 @@
+#!/usr/bin/env python3
+"""
+Mem0 Documentation Search Agent (Mintlify-based)
+On-demand search tool for querying Mem0 documentation without storing content locally.
+
+This tool leverages Mintlify's documentation structure to perform just-in-time
+retrieval of technical information from docs.mem0.ai.
+
+Usage:
+    python mem0_doc_search.py --query "how to add graph memory"
+    python mem0_doc_search.py --query "filter syntax for categories"
+    python mem0_doc_search.py --page "/platform/features/graph-memory"
+    python mem0_doc_search.py --index
+    python mem0_doc_search.py --query "webhook events" --section platform
+
+Purpose:
+    - Avoid bloating local context with full documentation
+    - Enable just-in-time retrieval of technical details
+    - Query specific documentation pages on demand
+    - Search across the full Mem0 documentation site
+"""
+
+import argparse
+import json
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+
+DOCS_BASE = "https://docs.mem0.ai"
+SEARCH_ENDPOINT = f"{DOCS_BASE}/api/search"
+LLMS_INDEX = f"{DOCS_BASE}/llms.txt"
+
+# Known documentation sections for targeted retrieval
+SECTION_MAP = {
+    "platform": [
+        "/platform/overview",
+        "/platform/quickstart",
+        "/platform/features",
+        "/platform/features/graph-memory",
+        "/platform/features/selective-memory",
+        "/platform/features/custom-categories",
+        "/platform/features/v2-memory-filters",
+        "/platform/features/async-client",
+        "/platform/features/webhooks",
+        "/platform/features/multimodal-support",
+    ],
+    "api": [
+        "/api-reference/memory/add-memories",
+        "/api-reference/memory/v2-search-memories",
+        "/api-reference/memory/v2-get-memories",
+        "/api-reference/memory/get-memory",
+        "/api-reference/memory/update-memory",
+        "/api-reference/memory/delete-memory",
+    ],
+    "open-source": [
+        "/open-source/overview",
+        "/open-source/python-quickstart",
+        "/open-source/node-quickstart",
+        "/open-source/features",
+        "/open-source/features/graph-memory",
+        "/open-source/features/rest-api",
+        "/open-source/configure-components",
+    ],
+    "openmemory": [
+        "/openmemory/overview",
+        "/openmemory/quickstart",
+    ],
+    "sdks": [
+        "/sdks/python",
+        "/sdks/js",
+    ],
+    "integrations": [
+        "/integrations",
+    ],
+}
+
+
+def fetch_url(url: str) -> str:
+    """Fetch content from a URL."""
+    req = urllib.request.Request(url, headers={"User-Agent": "Mem0DocSearchAgent/1.0"})
+    try:
+        with urllib.request.urlopen(req, timeout=15) as resp:
+            return resp.read().decode("utf-8")
+    except urllib.error.HTTPError as e:
+        return f"HTTP Error {e.code}: {e.reason}"
+    except urllib.error.URLError as e:
+        return f"URL Error: {e.reason}"
+
+
+def search_docs(query: str, section: str | None = None) -> dict:
+    """
+    Search Mem0 documentation using Mintlify's search API.
+    Falls back to the llms.txt index for keyword matching if the API is unavailable.
+    """
+    # Try Mintlify search API first
+    params = urllib.parse.urlencode({"query": query})
+    search_url = f"{SEARCH_ENDPOINT}?{params}"
+
+    try:
+        result = fetch_url(search_url)
+        data = json.loads(result)
+        if isinstance(data, dict) and data.get("results"):
+            results = data["results"]
+            if section and section in SECTION_MAP:
+                section_paths = SECTION_MAP[section]
+                results = [r for r in results if any(r.get("url", "").startswith(p) for p in section_paths)]
+            return {"source": "mintlify_search", "results": results}
+    except (json.JSONDecodeError, Exception):
+        pass
+
+    # Fallback: search llms.txt index for matching URLs
+    index_content = fetch_url(LLMS_INDEX)
+    query_lower = query.lower()
+    matching_urls = []
+
+    for line in index_content.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#"):
+            continue
+        if query_lower in line.lower():
+            matching_urls.append(line)
+
+    if section and section in SECTION_MAP:
+        section_paths = SECTION_MAP[section]
+        matching_urls = [u for u in matching_urls if any(p in u for p in section_paths)]
+
+    return {
+        "source": "llms_txt_index",
+        "query": query,
+        "matching_urls": matching_urls[:20],
+        "suggestion": "Fetch specific URLs for detailed content",
+    }
+
+
+def fetch_page(page_path: str) -> dict:
+    """Fetch a specific documentation page."""
+    url = f"{DOCS_BASE}{page_path}" if page_path.startswith("/") else page_path
+    content = fetch_url(url)
+    return {"url": url, "content": content[:10000], "truncated": len(content) > 10000}
+
+
+def get_index() -> dict:
+    """Fetch the full documentation index from llms.txt."""
+    content = fetch_url(LLMS_INDEX)
+    urls = [line.strip() for line in content.splitlines() if line.strip() and not line.startswith("#")]
+    return {"total_pages": len(urls), "urls": urls, "sections": list(SECTION_MAP.keys())}
+
+
+def list_section(section: str) -> dict:
+    """List all known pages in a documentation section."""
+    if section not in SECTION_MAP:
+        return {"error": f"Unknown section: {section}", "available": list(SECTION_MAP.keys())}
+    return {
+        "section": section,
+        "pages": [f"{DOCS_BASE}{p}" for p in SECTION_MAP[section]],
+    }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Search Mem0 documentation on demand")
+    parser.add_argument("--query", help="Search query for documentation")
+    parser.add_argument("--page", help="Fetch a specific page path (e.g., /platform/features/graph-memory)")
+    parser.add_argument("--index", action="store_true", help="Show full documentation index")
+    parser.add_argument("--section", help="Filter by section or list section pages")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+
+    args = parser.parse_args()
+
+    if args.index:
+        result = get_index()
+    elif args.section and not args.query:
+        result = list_section(args.section)
+    elif args.page:
+        result = fetch_page(args.page)
+    elif args.query:
+        result = search_docs(args.query, section=args.section)
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.json:
+        print(json.dumps(result, indent=2))
+    else:
+        if isinstance(result, dict):
+            if "results" in result:
+                print(f"Source: {result.get('source', 'unknown')}")
+                for r in result["results"]:
+                    print(f"  - {r.get('title', 'N/A')}: {r.get('url', 'N/A')}")
+                    if r.get("description"):
+                        print(f"    {r['description'][:200]}")
+            elif "matching_urls" in result:
+                print(f"Source: {result['source']}")
+                print(f"Query: {result['query']}")
+                for url in result["matching_urls"]:
+                    print(f"  - {url}")
+                if result.get("suggestion"):
+                    print(f"\n{result['suggestion']}")
+            elif "urls" in result:
+                print(f"Total documentation pages: {result['total_pages']}")
+                print(f"Sections: {', '.join(result['sections'])}")
+                for url in result["urls"][:30]:
+                    print(f"  - {url}")
+                if result["total_pages"] > 30:
+                    print(f"  ... and {result['total_pages'] - 30} more")
+            elif "pages" in result:
+                print(f"Section: {result['section']}")
+                for page in result["pages"]:
+                    print(f"  - {page}")
+            elif "content" in result:
+                print(f"URL: {result['url']}")
+                if result.get("truncated"):
+                    print("[Content truncated to 10000 chars]")
+                print(result["content"])
+            elif "error" in result:
+                print(f"Error: {result['error']}")
+                if result.get("available"):
+                    print(f"Available sections: {', '.join(result['available'])}")
+            else:
+                print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()
@@ -2,6 +2,7 @@
 module.exports = {
  ...require("./jest.config"),
  testMatch: ["**/integration/**/*.test.ts"],
+  globalSetup: "<rootDir>/src/client/tests/integration/global-setup.ts",
  globalTeardown: "<rootDir>/src/client/tests/integration/global-teardown.ts",
  // Run integration tests serially to avoid rate limiting and race conditions
  maxWorkers: 1,
@@ -1,6 +1,6 @@
 {
  "name": "mem0ai",
-  "version": "2.4.2",
+  "version": "2.4.3",
  "description": "The Memory Layer For Your AI Apps",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
@@ -1,4 +1,6 @@
-import { Client } from "pg";
+import type { Client as ClientType } from "pg";
+import pkg from "pg";
+const { Client } = pkg;
 import { VectorStore } from "./base";
 import { SearchFilters, VectorStoreConfig, VectorStoreResult } from "../types";

@@ -14,7 +16,7 @@ interface PGVectorConfig extends VectorStoreConfig {
 }

 export class PGVector implements VectorStore {
-  private client: Client;
+  private client: ClientType;
  private collectionName: string;
  private useDiskann: boolean;
  private useHnsw: boolean;
@@ -2,8 +2,6 @@ from typing import Any, ClassVar, Dict, Optional

 from pydantic import BaseModel, ConfigDict, Field, model_validator

-from mem0.vector_stores.configs import get_default_vector_store_path
-

 class ChromaDbConfig(BaseModel):
    try:
@@ -25,25 +23,24 @@ class ChromaDbConfig(BaseModel):
    def check_connection_config(cls, values):
        host, port, path = values.get("host"), values.get("port"), values.get("path")
        api_key, tenant = values.get("api_key"), values.get("tenant")
-        default_path = get_default_vector_store_path("chroma")
-
+        
        # Check if cloud configuration is provided
        cloud_config = bool(api_key and tenant)
-
+        
        # If cloud configuration is provided, remove any default path that might have been added
-        if cloud_config and path == default_path:
+        if cloud_config and path == "/tmp/chroma":
            values.pop("path", None)
            return values
-
+        
        # Check if local/server configuration is provided
        local_config = bool(path) or bool(host and port)
-
+        
        if not cloud_config and not local_config:
            raise ValueError("Either ChromaDB Cloud configuration (api_key, tenant) or local configuration (path or host/port) must be provided.")
-
+        
        if cloud_config and local_config:
            raise ValueError("Cannot specify both cloud configuration and local configuration. Choose one.")
-
+            
        return values

    @model_validator(mode="before")
@@ -2,8 +2,6 @@ from typing import Any, ClassVar, Dict, Optional

 from pydantic import BaseModel, ConfigDict, Field, model_validator

-from mem0.vector_stores.configs import get_default_vector_store_path
-

 class QdrantConfig(BaseModel):
    from qdrant_client import QdrantClient
@@ -15,7 +13,7 @@ class QdrantConfig(BaseModel):
    client: Optional[QdrantClient] = Field(None, description="Existing Qdrant client instance")
    host: Optional[str] = Field(None, description="Host address for Qdrant server")
    port: Optional[int] = Field(None, description="Port for Qdrant server")
-    path: Optional[str] = Field(default_factory=lambda: get_default_vector_store_path("qdrant"), description="Path for local Qdrant database")
+    path: Optional[str] = Field("/tmp/qdrant", description="Path for local Qdrant database")
    url: Optional[str] = Field(None, description="Full URL for Qdrant server")
    api_key: Optional[str] = Field(None, description="API key for Qdrant server")
    on_disk: Optional[bool] = Field(False,description="Enables persistent storage. Vectors are kept on disk (True) or in memory (False). Does not delete the local database path.")
@@ -13,6 +13,9 @@ class OpenAIEmbedding(EmbeddingBase):
        super().__init__(config)

        self.config.model = self.config.model or "text-embedding-3-small"
+        # Only pass `dimensions` to the API when the user set embedding_dims; non-matryoshka
+        # OpenAI-compatible backends (vLLM, Voyage, etc.) reject the parameter
+        self._pass_dimensions_to_api = self.config.embedding_dims is not None
        self.config.embedding_dims = self.config.embedding_dims or 1536

        api_key = self.config.api_key or os.getenv("OPENAI_API_KEY")
@@ -42,13 +45,11 @@ class OpenAIEmbedding(EmbeddingBase):
            list: The embedding vector.
        """
        text = text.replace("\n", " ")
-        return (
-            self.client.embeddings.create(
-                input=[text],
-                model=self.config.model,
-                dimensions=self.config.embedding_dims,
-                encoding_format="float",
-            )
-            .data[0]
-            .embedding
-        )
+        kwargs = {
+            "input": [text],
+            "model": self.config.model,
+            "encoding_format": "float",
+        }
+        if self._pass_dimensions_to_api:
+            kwargs["dimensions"] = self.config.embedding_dims
+        return self.client.embeddings.create(**kwargs).data[0].embedding
@@ -516,15 +516,15 @@ class Memory(MemoryBase):
        )

        try:
-            response = remove_code_blocks(response)
-            if not response.strip():
+            cleaned_response = remove_code_blocks(response)
+            if not cleaned_response.strip():
                new_retrieved_facts = []
            else:
                try:
                    # First try direct JSON parsing
-                    new_retrieved_facts = json.loads(response, strict=False)["facts"]
+                    new_retrieved_facts = json.loads(cleaned_response, strict=False)["facts"]
                except json.JSONDecodeError:
-                    # Try extracting JSON from response using built-in function
+                    # Try extracting JSON from response (handles chatty LLM output)
                    extracted_json = extract_json(response)
                    new_retrieved_facts = json.loads(extracted_json, strict=False)["facts"]
                new_retrieved_facts = normalize_facts(new_retrieved_facts)
@@ -589,8 +589,11 @@ class Memory(MemoryBase):
                    logger.warning("Empty response from LLM, no memories to extract")
                    new_memories_with_actions = {}
                else:
-                    response = remove_code_blocks(response)
-                    new_memories_with_actions = json.loads(response, strict=False)
+                    try:
+                        new_memories_with_actions = json.loads(remove_code_blocks(response), strict=False)
+                    except json.JSONDecodeError:
+                        extracted_json = extract_json(response)
+                        new_memories_with_actions = json.loads(extracted_json, strict=False)
            except Exception as e:
                logger.error(f"Invalid JSON response: {e}")
                new_memories_with_actions = {}
@@ -974,11 +977,11 @@ class Memory(MemoryBase):
                }
                
                if operator in operator_map:
-                    result[key] = {operator_map[operator]: value}
+                    result.setdefault(key, {})[operator_map[operator]] = value
                else:
                    raise ValueError(f"Unsupported metadata filter operator: {operator}")
            return result
-        
+
        for key, value in metadata_filters.items():
            if key == "AND":
                # Logical AND: combine multiple conditions
@@ -1078,13 +1081,15 @@ class Memory(MemoryBase):

        return original_memories

-    def update(self, memory_id, data):
+    def update(self, memory_id, data, metadata: Optional[Dict[str, Any]] = None):
        """
        Update a memory by ID.

        Args:
            memory_id (str): ID of the memory to update.
            data (str): New content to update the memory with.
+            metadata (dict, optional): Additional metadata to update. Existing metadata fields
+                not specified here will be preserved. Defaults to None.

        Returns:
            dict: Success message indicating the memory was updated.
@@ -1092,12 +1097,14 @@ class Memory(MemoryBase):
        Example:
            >>> m.update(memory_id="mem_123", data="Likes to play tennis on weekends")
            {'message': 'Memory updated successfully!'}
+            >>> m.update(memory_id="mem_123", data="Likes tennis", metadata={"category": "sports"})
+            {'message': 'Memory updated successfully!'}
        """
        capture_event("mem0.update", self, {"memory_id": memory_id, "sync_type": "sync"})

        existing_embeddings = {data: self.embedding_model.embed(data, "update")}

-        self._update_memory(memory_id, data, existing_embeddings)
+        self._update_memory(memory_id, data, existing_embeddings, metadata)
        return {"message": "Memory updated successfully!"}

    def delete(self, memory_id):
@@ -1317,12 +1324,19 @@ class Memory(MemoryBase):
            if existing_memory is None:
                raise ValueError(f"Memory with id {memory_id} not found")
        prev_value = existing_memory.payload.get("data", "")
+
+        # Preserve original created_at and record deletion time
+        created_at = _normalize_iso_timestamp_to_utc(existing_memory.payload.get("created_at"))
+        updated_at = datetime.now(timezone.utc).isoformat()
+
        self.vector_store.delete(vector_id=memory_id)
        self.db.add_history(
            memory_id,
            prev_value,
            None,
            "DELETE",
+            created_at=created_at,
+            updated_at=updated_at,
            actor_id=existing_memory.payload.get("actor_id"),
            role=existing_memory.payload.get("role"),
            is_deleted=1,
@@ -1590,15 +1604,15 @@ class AsyncMemory(MemoryBase):
            response_format={"type": "json_object"},
        )
        try:
-            response = remove_code_blocks(response)
-            if not response.strip():
+            cleaned_response = remove_code_blocks(response)
+            if not cleaned_response.strip():
                new_retrieved_facts = []
            else:
                try:
                    # First try direct JSON parsing
-                    new_retrieved_facts = json.loads(response, strict=False)["facts"]
+                    new_retrieved_facts = json.loads(cleaned_response, strict=False)["facts"]
                except json.JSONDecodeError:
-                    # Try extracting JSON from response using built-in function
+                    # Try extracting JSON from response (handles chatty LLM output)
                    extracted_json = extract_json(response)
                    new_retrieved_facts = json.loads(extracted_json, strict=False)["facts"]
                new_retrieved_facts = normalize_facts(new_retrieved_facts)
@@ -1666,8 +1680,11 @@ class AsyncMemory(MemoryBase):
                    logger.warning("Empty response from LLM, no memories to extract")
                    new_memories_with_actions = {}
                else:
-                    response = remove_code_blocks(response)
-                    new_memories_with_actions = json.loads(response, strict=False)
+                    try:
+                        new_memories_with_actions = json.loads(remove_code_blocks(response), strict=False)
+                    except json.JSONDecodeError:
+                        extracted_json = extract_json(response)
+                        new_memories_with_actions = json.loads(extracted_json, strict=False)
            except Exception as e:
                logger.error(f"Invalid JSON response: {e}")
                new_memories_with_actions = {}
@@ -2082,7 +2099,7 @@ class AsyncMemory(MemoryBase):
                }

                if operator in operator_map:
-                    result[key] = {operator_map[operator]: value}
+                    result.setdefault(key, {})[operator_map[operator]] = value
                else:
                    raise ValueError(f"Unsupported metadata filter operator: {operator}")
            return result
@@ -2188,13 +2205,15 @@ class AsyncMemory(MemoryBase):

        return original_memories

-    async def update(self, memory_id, data):
+    async def update(self, memory_id, data, metadata: Optional[Dict[str, Any]] = None):
        """
        Update a memory by ID asynchronously.

        Args:
            memory_id (str): ID of the memory to update.
            data (str): New content to update the memory with.
+            metadata (dict, optional): Additional metadata to update. Existing metadata fields
+                not specified here will be preserved. Defaults to None.

        Returns:
            dict: Success message indicating the memory was updated.
@@ -2202,13 +2221,15 @@ class AsyncMemory(MemoryBase):
        Example:
            >>> await m.update(memory_id="mem_123", data="Likes to play tennis on weekends")
            {'message': 'Memory updated successfully!'}
+            >>> await m.update(memory_id="mem_123", data="Likes tennis", metadata={"category": "sports"})
+            {'message': 'Memory updated successfully!'}
        """
        capture_event("mem0.update", self, {"memory_id": memory_id, "sync_type": "async"})

        embeddings = await asyncio.to_thread(self.embedding_model.embed, data, "update")
        existing_embeddings = {data: embeddings}

-        await self._update_memory(memory_id, data, existing_embeddings)
+        await self._update_memory(memory_id, data, existing_embeddings, metadata)
        return {"message": "Memory updated successfully!"}

    async def delete(self, memory_id):
@@ -2454,6 +2475,10 @@ class AsyncMemory(MemoryBase):
                raise ValueError(f"Memory with id {memory_id} not found")
        prev_value = existing_memory.payload.get("data", "")

+        # Preserve original created_at and record deletion time
+        created_at = _normalize_iso_timestamp_to_utc(existing_memory.payload.get("created_at"))
+        updated_at = datetime.now(timezone.utc).isoformat()
+
        await asyncio.to_thread(self.vector_store.delete, vector_id=memory_id)
        await asyncio.to_thread(
            self.db.add_history,
@@ -2461,6 +2486,8 @@ class AsyncMemory(MemoryBase):
            prev_value,
            None,
            "DELETE",
+            created_at=created_at,
+            updated_at=updated_at,
            actor_id=existing_memory.payload.get("actor_id"),
            role=existing_memory.payload.get("role"),
            is_deleted=1,
@@ -124,14 +124,20 @@ def remove_code_blocks(content: str) -> str:
 def extract_json(text):
    """
    Extracts JSON content from a string, removing enclosing triple backticks and optional 'json' tag if present.
-    If no code block is found, returns the text as-is.
+    If no code block is found, attempts to locate JSON by finding the first '{' and last '}'.
+    If that also fails, returns the text as-is.
    """
    text = text.strip()
    match = re.search(r"```(?:json)?\s*(.*?)\s*```", text, re.DOTALL)
    if match:
        json_str = match.group(1)
    else:
-        json_str = text  # assume it's raw JSON
+        start_idx = text.find("{")
+        end_idx = text.rfind("}")
+        if start_idx != -1 and end_idx != -1 and end_idx > start_idx:
+            json_str = text[start_idx : end_idx + 1]
+        else:
+            json_str = text
    return json_str


@@ -249,6 +255,7 @@ def sanitize_relationship_for_cypher(relationship) -> str:
        "}": "_rbrace_",
        "<": "_langle_",
        ">": "_rangle_",
+        "-": "_",
    }

    # Apply replacements and clean up
@@ -1,88 +1,7 @@
-import logging
-import os
-import shutil
-from pathlib import Path
 from typing import Dict, Optional

 from pydantic import BaseModel, Field, model_validator

-logger = logging.getLogger(__name__)
-
-
-def get_default_vector_store_path(provider: str) -> str:
-    """Return a platform-appropriate default path for a vector store provider.
-
-    Preference order: MEM0_DATA_DIR → XDG_DATA_HOME (Linux) → APPDATA (Windows) → ~/.local/share
-    """
-    mem0_data_dir = os.environ.get("MEM0_DATA_DIR")
-    if mem0_data_dir:
-        base = Path(mem0_data_dir)
-    else:
-        xdg = os.environ.get("XDG_DATA_HOME")
-        app_data = os.environ.get("APPDATA")
-        if xdg:
-            base = Path(xdg)
-        elif app_data:
-            base = Path(app_data)
-        else:
-            base = Path.home() / ".local" / "share"
-        base = base / "mem0"
-    return str(base / provider)
-
-
-def _migrate_legacy_data(provider: str, new_path: str, legacy_path: Optional[str] = None):
-    """Auto-migrate data from legacy /tmp/{provider} to the new persistent path.
-
-    Skips migration if:
-    - Legacy path doesn't exist, is empty, or is a symlink (security)
-    - New path already contains data (no clobbering)
-    - A .migration_complete sentinel exists at the new path (already migrated)
-
-    Falls back to a warning with manual instructions if the copy fails.
-    Note: On Windows /tmp doesn't exist, so this is effectively a no-op.
-
-    Args:
-        provider: Vector store provider name (e.g. 'qdrant').
-        new_path: The new persistent path to migrate data to.
-        legacy_path: Override the legacy path (default: /tmp/{provider}).
-                     Exposed for testing; production callers should omit this.
-    """
-    legacy_path = Path(legacy_path if legacy_path is not None else f"/tmp/{provider}")
-    if not legacy_path.exists() or legacy_path.is_symlink() or not any(legacy_path.iterdir()):
-        return
-
-    new_path_obj = Path(new_path)
-
-    # Skip if already migrated in a previous run
-    sentinel = new_path_obj / ".migration_complete"
-    if sentinel.exists():
-        return
-
-    if new_path_obj.exists() and any(new_path_obj.iterdir()):
-        logger.info(
-            "Both legacy path '%s' and new path '%s' contain data. "
-            "Using new path. Legacy data at '%s' is untouched.",
-            legacy_path, new_path, legacy_path,
-        )
-        return
-
-    try:
-        shutil.copytree(str(legacy_path), new_path, dirs_exist_ok=True)
-        # Write sentinel to prevent repeated migration attempts on future startups
-        sentinel.touch()
-        logger.info(
-            "Migrated vector store data from '%s' to '%s'. "
-            "You may remove the old directory once verified.",
-            legacy_path, new_path,
-        )
-    except Exception as e:
-        logger.warning(
-            "Could not auto-migrate data from '%s' to '%s': %s. "
-            "Please manually copy/move the data, or set path='/tmp/%s' in your config "
-            "to keep using the old location.",
-            legacy_path, new_path, e, provider,
-        )
-

 class VectorStoreConfig(BaseModel):
    provider: str = Field(
@@ -142,8 +61,7 @@ class VectorStoreConfig(BaseModel):

        # also check if path in allowed kays for pydantic model, and whether config extra fields are allowed
        if "path" not in config and "path" in config_class.__annotations__:
-            config["path"] = get_default_vector_store_path(provider)
-            _migrate_legacy_data(provider, config["path"])
+            config["path"] = f"/tmp/{provider}"

        self.config = config_class(**config)
        return self
@@ -1,11 +1,13 @@
 import json
 import logging
+import re
 import uuid
 from typing import Optional, List
 from datetime import datetime, date
 from databricks.sdk.service.catalog import ColumnInfo, ColumnTypeName, TableType, DataSourceFormat
 from databricks.sdk.service.catalog import TableConstraint, PrimaryKeyConstraint
 from databricks.sdk import WorkspaceClient
+from databricks.sdk.service.sql import StatementParameterListItem
 from databricks.sdk.service.vectorsearch import (
    VectorIndexType,
    DeltaSyncVectorIndexSpecRequest,
@@ -28,6 +30,9 @@ class MemoryResult(BaseModel):

 excluded_keys = {"user_id", "agent_id", "run_id", "hash", "data", "created_at", "updated_at"}

+# Pattern for valid SQL identifiers to prevent column name injection
+_VALID_SQL_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+

 class Databricks(VectorStoreBase):
    def __init__(
@@ -388,28 +393,46 @@ class Databricks(VectorStoreBase):
        # Determine the number of items to process
        num_items = len(payloads) if payloads else len(vectors) if vectors else 0

+        params = []
        value_tuples = []
        for i in range(num_items):
-            values = []
+            placeholders = []
            for col in self.columns:
+                param_name = f"{col.name}_{i}"
                if col.name == "memory_id":
                    val = ids[i] if ids and i < len(ids) else str(uuid.uuid4())
                elif col.name == "embedding":
                    val = vectors[i] if vectors and i < len(vectors) else []
+                    # Vectors are numeric arrays — ARRAY type not supported by StatementParameterListItem,
+                    # so we inline using _format_sql_value (values are floats from the embedding model).
+                    placeholders.append(self._format_sql_value(val))
+                    continue
                elif col.name == "memory":
                    val = payloads[i].get("data") if payloads and i < len(payloads) else None
                else:
                    val = payloads[i].get(col.name) if payloads and i < len(payloads) else None
-                values.append(val)
-            formatted = [self._format_sql_value(v) for v in values]
-            value_tuples.append(f"({', '.join(formatted)})")
+
+                if val is None:
+                    placeholders.append("NULL")
+                else:
+                    placeholders.append(f":{param_name}")
+                    if isinstance(val, dict):
+                        val = json.dumps(val)
+                    # Use explicit type for TIMESTAMP columns so Databricks doesn't
+                    # rely on implicit STRING→TIMESTAMP casting.
+                    param_type = "TIMESTAMP" if col.type_name == ColumnTypeName.TIMESTAMP else None
+                    params.append(StatementParameterListItem(name=param_name, value=str(val), type=param_type))
+            value_tuples.append(f"({', '.join(placeholders)})")

        insert_sql = f"INSERT INTO {self.fully_qualified_table_name} ({', '.join(self.column_names)}) VALUES {', '.join(value_tuples)}"

        # Execute the insert
        try:
            response = self.client.statement_execution.execute_statement(
-                statement=insert_sql, warehouse_id=self.warehouse_id, wait_timeout="30s"
+                statement=insert_sql,
+                warehouse_id=self.warehouse_id,
+                wait_timeout="30s",
+                parameters=params,
            )
            if response.status.state.value == "SUCCEEDED":
                logger.info(
@@ -494,10 +517,13 @@ class Databricks(VectorStoreBase):
        try:
            logger.info(f"Deleting vector with ID {vector_id} from Delta table {self.fully_qualified_table_name}")

-            delete_sql = f"DELETE FROM {self.fully_qualified_table_name} WHERE memory_id = '{vector_id}'"
+            delete_sql = f"DELETE FROM {self.fully_qualified_table_name} WHERE memory_id = :vector_id"

            response = self.client.statement_execution.execute_statement(
-                statement=delete_sql, warehouse_id=self.warehouse_id, wait_timeout="30s"
+                statement=delete_sql,
+                warehouse_id=self.warehouse_id,
+                wait_timeout="30s",
+                parameters=[StatementParameterListItem(name="vector_id", value=str(vector_id))],
            )

            if response.status.state.value == "SUCCEEDED":
@@ -519,8 +545,8 @@ class Databricks(VectorStoreBase):
            payload (dict, optional): New payload data.
        """

-        update_sql = f"UPDATE {self.fully_qualified_table_name} SET "
        set_clauses = []
+        params = []
        if not vector_id:
            logger.error("vector_id is required for update operation")
            return
@@ -528,25 +554,38 @@ class Databricks(VectorStoreBase):
            if not isinstance(vector, list):
                logger.error("vector must be a list of float values")
                return
-            set_clauses.append(f"embedding = {vector}")
+            # Vectors are numeric arrays — safe to inline since StatementParameterListItem
+            # doesn't support ARRAY types, and values are validated as list of floats above.
+            # Use array() SQL syntax, not Python list repr which is invalid Databricks SQL.
+            set_clauses.append(f"embedding = {self._format_sql_value(vector)}")
        if payload:
            if not isinstance(payload, dict):
                logger.error("payload must be a dictionary")
                return
            for key, value in payload.items():
                if key not in excluded_keys:
-                    set_clauses.append(f"{key} = '{value}'")
+                    if not _VALID_SQL_IDENTIFIER.match(key):
+                        logger.warning(f"Skipping invalid column name in payload: {key!r}")
+                        continue
+                    param_name = f"payload_{key}"
+                    set_clauses.append(f"{key} = :{param_name}")
+                    params.append(StatementParameterListItem(name=param_name, value=str(value)))

        if not set_clauses:
            logger.error("No fields to update")
            return
+        update_sql = f"UPDATE {self.fully_qualified_table_name} SET "
        update_sql += ", ".join(set_clauses)
-        update_sql += f" WHERE memory_id = '{vector_id}'"
+        update_sql += " WHERE memory_id = :vector_id"
+        params.append(StatementParameterListItem(name="vector_id", value=str(vector_id)))
        try:
            logger.info(f"Updating vector with ID {vector_id} in Delta table {self.fully_qualified_table_name}")

            response = self.client.statement_execution.execute_statement(
-                statement=update_sql, warehouse_id=self.warehouse_id, wait_timeout="30s"
+                statement=update_sql,
+                warehouse_id=self.warehouse_id,
+                wait_timeout="30s",
+                parameters=params,
            )

            if response.status.state.value == "SUCCEEDED":
@@ -8,8 +8,6 @@ from typing import Dict, List, Optional
 import numpy as np
 from pydantic import BaseModel

-from mem0.vector_stores.configs import get_default_vector_store_path
-
 import warnings

 try:
@@ -60,7 +58,7 @@ class FAISS(VectorStoreBase):
                Defaults to False.
        """
        self.collection_name = collection_name
-        self.path = path or f"{get_default_vector_store_path('faiss')}/{collection_name}"
+        self.path = path or f"/tmp/faiss/{collection_name}"
        self.distance_strategy = distance_strategy
        self.normalize_L2 = normalize_L2
        self.embedding_model_dims = embedding_model_dims
@@ -2,6 +2,15 @@

 All notable changes to the `@mem0/openclaw-mem0` plugin will be documented in this file.

+## [0.4.1] - 2026-03-26
+
+### Added
+- **Improved extraction quality**: Enhanced noise filtering, deduplication, and better extraction instructions for higher-quality memory capture (#4302)
+
+### Fixed
+- **Credential detection in extraction**: Improved detection of credentials, API keys, and secrets in extraction instructions to prevent them from being stored as memories (#4552)
+- **Standalone timestamp extraction**: Prevented extraction of standalone timestamps as memories when no meaningful content accompanies them (#4550)
+
 ## [0.4.0] - 2026-03-16

 ### Added
@@ -111,12 +111,15 @@ LANGUAGE:
 - If the user speaks Spanish, store the memory in Spanish; do not translate

 Exclude (NEVER store):
- Passwords, API keys, tokens, secrets, or any credentials — even if shared in conversation. Instead store: "Tavily API key was configured and saved to .env (as of 2026-02-20)"
+- Passwords, API keys, tokens, secrets, or any credentials — even when embedded in configuration blocks, setup logs, or tool output. This includes strings starting with sk-, m0-, ak_, ghp_, bot tokens (digits followed by colon and alphanumeric string), bearer tokens, webhook URLs containing tokens, pairing codes, and any long alphanumeric strings that appear in config/env contexts. Never include the actual secret value in a memory. Instead, record that the credential was configured:
+  WRONG: "User's API key is sk-abc123..." or "Bot token is 12345:AABcd..."
+  RIGHT: "API key was configured for the service (as of YYYY-MM-DD)" or "Telegram bot token was set up"
 - One-time commands or instructions ("stop the script", "continue where you left off")
 - Acknowledgments or emotional reactions ("ok", "sounds good", "you're right", "sir")
 - Transient UI/navigation states ("user is in the admin panel", "relay is attached")
 - Ephemeral process status ("download at 50%", "daemon not running", "still syncing")
 - Cron heartbeat outputs, NO_REPLY responses, compaction flush directives
+- The current date/time as a standalone fact — timestamps are conversation context, not durable knowledge. "User indicates current time is 3:25 PM" is NEVER worth storing. However, DO use timestamps to anchor other facts: "User installed Ollama on 2026-03-21" is correct.
 - System routing metadata (message IDs, sender IDs, channel routing info)
 - Generic small talk with no informational content
 - Raw code snippets (capture the intent/decision, not the code itself)
@@ -1,6 +1,6 @@
 {
  "name": "@mem0/openclaw-mem0",
-  "version": "0.4.0",
+  "version": "0.4.1",
  "type": "module",
  "description": "Mem0 memory backend for OpenClaw — platform or self-hosted open-source",
  "license": "Apache-2.0",
@@ -4,10 +4,10 @@ build-backend = "hatchling.build"

 [project]
 name = "mem0ai"
-version = "1.0.7"
+version = "1.0.8"
 description = "Long-term memory for AI Agents"
 authors = [
-    { name = "Mem0", email = "founders@mem0.ai" }
+    { name = "Mem0", email = "support@mem0.ai" }
 ]
 readme = "README.md"
 license = "Apache-2.0"
@@ -24,7 +24,7 @@ def test_embed_default_model(mock_openai_client):
    result = embedder.embed("Hello world")

    mock_openai_client.embeddings.create.assert_called_once_with(
-        input=["Hello world"], model="text-embedding-3-small", dimensions=1536, encoding_format="float"
+        input=["Hello world"], model="text-embedding-3-small", encoding_format="float"
    )
    assert result == [0.1, 0.2, 0.3]

@@ -54,7 +54,7 @@ def test_embed_removes_newlines(mock_openai_client):
    result = embedder.embed("Hello\nworld")

    mock_openai_client.embeddings.create.assert_called_once_with(
-        input=["Hello world"], model="text-embedding-3-small", dimensions=1536, encoding_format="float"
+        input=["Hello world"], model="text-embedding-3-small", encoding_format="float"
    )
    assert result == [0.7, 0.8, 0.9]

@@ -69,7 +69,7 @@ def test_embed_without_api_key_env_var(mock_openai_client):
    result = embedder.embed("Testing API key")

    mock_openai_client.embeddings.create.assert_called_once_with(
-        input=["Testing API key"], model="text-embedding-3-small", dimensions=1536, encoding_format="float"
+        input=["Testing API key"], model="text-embedding-3-small", encoding_format="float"
    )
    assert result == [1.0, 1.1, 1.2]

@@ -85,7 +85,7 @@ def test_embed_uses_environment_api_key(mock_openai_client, monkeypatch):
    result = embedder.embed("Environment key test")

    mock_openai_client.embeddings.create.assert_called_once_with(
-        input=["Environment key test"], model="text-embedding-3-small", dimensions=1536, encoding_format="float"
+        input=["Environment key test"], model="text-embedding-3-small", encoding_format="float"
    )
    assert result == [1.3, 1.4, 1.5]

@@ -107,3 +107,18 @@ def test_embed_passes_encoding_format_float(mock_openai_client):

    call_kwargs = mock_openai_client.embeddings.create.call_args
    assert call_kwargs.kwargs.get("encoding_format") == "float" or call_kwargs[1].get("encoding_format") == "float"
+
+
+def test_embed_passes_dimensions_only_when_explicit(mock_openai_client):
+    """Matryoshka / truncated embeddings: dimensions sent only if user sets embedding_dims (#4153)."""
+    config = BaseEmbedderConfig(embedding_dims=256)
+    embedder = OpenAIEmbedding(config)
+    mock_response = Mock()
+    mock_response.data = [Mock(embedding=[0.1] * 256)]
+    mock_openai_client.embeddings.create.return_value = mock_response
+
+    embedder.embed("truncate me")
+
+    mock_openai_client.embeddings.create.assert_called_once_with(
+        input=["truncate me"], model="text-embedding-3-small", dimensions=256, encoding_format="float"
+    )
@@ -1,6 +1,6 @@
 import logging
 from datetime import datetime, timezone
-from unittest.mock import MagicMock
+from unittest.mock import MagicMock, Mock

 import pytest

@@ -79,6 +79,57 @@ class TestAddToVectorStoreErrors:
        assert "Empty response from LLM, no memories to extract" in caplog.text


+class TestAsyncUpdate:
+    @pytest.fixture
+    def mock_async_memory(self, mocker):
+        """Fixture for AsyncMemory with mocker-based mocks"""
+        _setup_mocks(mocker)
+        memory = AsyncMemory()
+        return memory
+
+    @pytest.mark.asyncio
+    async def test_async_update_without_metadata(self, mock_async_memory, mocker):
+        """Test async update passes None metadata by default"""
+        mock_async_memory.embedding_model = Mock()
+        mock_async_memory.embedding_model.embed = Mock(return_value=[0.1, 0.2, 0.3])
+        mock_async_memory._update_memory = mocker.AsyncMock()
+
+        result = await mock_async_memory.update("test_id", "Updated memory")
+
+        mock_async_memory._update_memory.assert_called_once_with(
+            "test_id", "Updated memory", {"Updated memory": [0.1, 0.2, 0.3]}, None
+        )
+        assert result["message"] == "Memory updated successfully!"
+
+    @pytest.mark.asyncio
+    async def test_async_update_with_metadata(self, mock_async_memory, mocker):
+        """Test async update correctly forwards metadata"""
+        mock_async_memory.embedding_model = Mock()
+        mock_async_memory.embedding_model.embed = Mock(return_value=[0.1, 0.2, 0.3])
+        mock_async_memory._update_memory = mocker.AsyncMock()
+        metadata = {"category": "sports", "priority": "high"}
+
+        result = await mock_async_memory.update("test_id", "Updated memory", metadata=metadata)
+
+        mock_async_memory._update_memory.assert_called_once_with(
+            "test_id", "Updated memory", {"Updated memory": [0.1, 0.2, 0.3]}, metadata
+        )
+        assert result["message"] == "Memory updated successfully!"
+
+    @pytest.mark.asyncio
+    async def test_async_update_with_empty_metadata(self, mock_async_memory, mocker):
+        """Test async update with empty metadata dict"""
+        mock_async_memory.embedding_model = Mock()
+        mock_async_memory.embedding_model.embed = Mock(return_value=[0.1, 0.2, 0.3])
+        mock_async_memory._update_memory = mocker.AsyncMock()
+
+        await mock_async_memory.update("test_id", "Updated memory", metadata={})
+
+        mock_async_memory._update_memory.assert_called_once_with(
+            "test_id", "Updated memory", {"Updated memory": [0.1, 0.2, 0.3]}, {}
+        )
+
+
@pytest.mark.asyncio
 class TestAsyncAddToVectorStoreErrors:
    @pytest.fixture
@@ -1,6 +1,32 @@
 import os
 from unittest.mock import Mock, patch

+from mem0.memory.utils import sanitize_relationship_for_cypher
+
+
+class TestSanitizeRelationshipForCypher:
+    """Test that relationship names are properly sanitized for Neo4j Cypher queries."""
+
+    def test_hyphen_replaced_with_underscore(self):
+        """Hyphens in relationship names cause Neo4j CypherSyntaxError and must be replaced."""
+        assert sanitize_relationship_for_cypher("manages_via_low-cost_models") == "manages_via_low_cost_models"
+
+    def test_multiple_hyphens(self):
+        assert sanitize_relationship_for_cypher("co-owns-with") == "co_owns_with"
+
+    def test_no_special_chars_unchanged(self):
+        assert sanitize_relationship_for_cypher("works_at") == "works_at"
+
+    def test_spaces_not_handled_here(self):
+        """Spaces are replaced upstream before this function is called."""
+        # sanitize only handles special chars, spaces are handled by the caller
+        result = sanitize_relationship_for_cypher("has relationship")
+        assert result == "has relationship"
+
+    def test_existing_chars_still_sanitized(self):
+        assert "_slash_" in sanitize_relationship_for_cypher("read/write")
+        assert "_at_" in sanitize_relationship_for_cypher("user@company")
+

 class TestNeo4jCypherSyntaxFix:
    """Test that Neo4j Cypher syntax fixes work correctly"""
@@ -0,0 +1,232 @@
+"""Tests for chatty LLM JSON parsing robustness.
+
+Validates that extract_json and the full fallback chain correctly handle
+responses from local LLMs (LM Studio, Ollama) that wrap JSON in
+conversational text, markdown code blocks, or both.
+"""
+
+import json
+
+import pytest
+
+from mem0.memory.utils import extract_json, remove_code_blocks
+
+
+# --- Test extract_json ---
+
+class TestExtractJson:
+    """Tests for extract_json utility."""
+
+    def test_pure_json(self):
+        text = '{"memory": [{"id": "0", "text": "likes basketball", "event": "ADD"}]}'
+        result = extract_json(text)
+        parsed = json.loads(result)
+        assert parsed["memory"][0]["text"] == "likes basketball"
+
+    def test_json_in_markdown_code_block(self):
+        text = '```json\n{"memory": [{"id": "0", "text": "likes basketball", "event": "ADD"}]}\n```'
+        result = extract_json(text)
+        parsed = json.loads(result)
+        assert parsed["memory"][0]["text"] == "likes basketball"
+
+    def test_json_in_plain_code_block(self):
+        text = '```\n{"memory": [{"id": "0", "text": "likes basketball", "event": "ADD"}]}\n```'
+        result = extract_json(text)
+        parsed = json.loads(result)
+        assert parsed["memory"][0]["text"] == "likes basketball"
+
+    def test_chatty_with_markdown(self):
+        """extract_json can handle embedded code blocks via re.search."""
+        text = """Here is the extracted memory:
+```json
+{"memory": [{"id": "0", "text": "likes basketball", "event": "ADD"}]}
+```
+I hope this helps!"""
+        result = extract_json(text)
+        parsed = json.loads(result)
+        assert parsed["memory"][0]["text"] == "likes basketball"
+
+    def test_chatty_without_markdown(self):
+        """extract_json finds JSON by {/} boundaries when no code block is present."""
+        text = """Here is the memory update you requested:
+{"memory": [{"id": "0", "text": "likes gaming", "event": "ADD"}]}
+That's the result."""
+        result = extract_json(text)
+        parsed = json.loads(result)
+        assert parsed["memory"][0]["text"] == "likes gaming"
+
+    def test_chatty_multiline_json_without_markdown(self):
+        """extract_json finds multi-line JSON by {/} boundaries."""
+        text = """Here is the memory update:
+{
+  "memory": [
+    {
+      "id": "0",
+      "text": "User likes gaming",
+      "event": "ADD"
+    }
+  ]
+}
+"""
+        result = extract_json(text)
+        parsed = json.loads(result)
+        assert parsed["memory"][0]["text"] == "User likes gaming"
+
+    def test_no_json_at_all(self):
+        """No JSON in the text — should return as-is."""
+        text = "I don't have any memory updates."
+        result = extract_json(text)
+        assert result == text
+
+    def test_whitespace_padding(self):
+        text = '  \n  {"memory": []}  \n  '
+        result = extract_json(text)
+        parsed = json.loads(result)
+        assert parsed == {"memory": []}
+
+    def test_nested_json_objects(self):
+        """JSON with nested objects should find outermost braces."""
+        text = 'Sure! {"memory": [{"id": "0", "text": "test", "event": "ADD"}]} Done.'
+        result = extract_json(text)
+        parsed = json.loads(result)
+        assert parsed["memory"][0]["id"] == "0"
+
+
+# --- Test remove_code_blocks ---
+
+class TestRemoveCodeBlocks:
+    """Tests for remove_code_blocks — verify it does NOT handle chatty text."""
+
+    def test_clean_code_block(self):
+        text = '```json\n{"memory": []}\n```'
+        result = remove_code_blocks(text)
+        parsed = json.loads(result)
+        assert parsed == {"memory": []}
+
+    def test_no_code_block(self):
+        """Without code blocks, returns content as-is (may not be valid JSON)."""
+        text = 'Here is the result: {"memory": []}'
+        result = remove_code_blocks(text)
+        # This should NOT be parseable as JSON because it has leading text
+        with pytest.raises(json.JSONDecodeError):
+            json.loads(result)
+
+    def test_think_tags_removed_inside_code_block(self):
+        """Think tags inside a code block response are removed."""
+        text = '```json\n<think>reasoning here</think>\n{"memory": []}\n```'
+        result = remove_code_blocks(text)
+        parsed = json.loads(result)
+        assert parsed == {"memory": []}
+
+    def test_think_tags_before_code_block_not_handled(self):
+        """Think tags before code block cause regex to miss — fallback needed.
+
+        This is a known limitation of remove_code_blocks: it matches the code
+        block regex first, and only strips think tags from the result. When
+        think tags come before the code block, the regex fails entirely.
+        The fallback chain (extract_json) handles this case.
+        """
+        text = '<think>reasoning here</think>\n```json\n{"memory": []}\n```'
+        result = remove_code_blocks(text)
+        with pytest.raises(json.JSONDecodeError):
+            json.loads(result)
+
+
+# --- Test the full fallback chain (remove_code_blocks -> extract_json) ---
+
+class TestFallbackChain:
+    """Tests the actual fallback pattern used in _add_to_vector_store:
+    try json.loads(remove_code_blocks(response))
+    except JSONDecodeError: json.loads(extract_json(response))
+    """
+
+    def _parse_with_fallback(self, response):
+        """Mimics the parsing logic in _add_to_vector_store."""
+        try:
+            return json.loads(remove_code_blocks(response), strict=False)
+        except json.JSONDecodeError:
+            extracted = extract_json(response)
+            return json.loads(extracted, strict=False)
+
+    def test_clean_json(self):
+        response = '{"memory": [{"id": "0", "text": "Name is Alex", "event": "ADD"}]}'
+        result = self._parse_with_fallback(response)
+        assert result["memory"][0]["text"] == "Name is Alex"
+
+    def test_markdown_wrapped(self):
+        response = '```json\n{"memory": [{"id": "0", "text": "Name is Alex", "event": "ADD"}]}\n```'
+        result = self._parse_with_fallback(response)
+        assert result["memory"][0]["text"] == "Name is Alex"
+
+    def test_chatty_markdown(self):
+        """Issue #3788: LLM wraps in conversational text + markdown."""
+        response = """Here is the extracted memory:
+```json
+{
+  "memory": [
+    {"id": "0", "text": "Name is Alex", "event": "ADD"},
+    {"id": "1", "text": "Love basketball", "event": "ADD"},
+    {"id": "2", "text": "Love gaming", "event": "ADD"}
+  ]
+}
+```
+I hope this helps!"""
+        result = self._parse_with_fallback(response)
+        assert len(result["memory"]) == 3
+        assert result["memory"][0]["text"] == "Name is Alex"
+        assert result["memory"][1]["text"] == "Love basketball"
+        assert result["memory"][2]["text"] == "Love gaming"
+
+    def test_chatty_no_markdown(self):
+        """Issue #3788: LLM wraps in conversational text without markdown."""
+        response = """Here is the memory update you requested:
+{
+  "memory": [
+    {"id": "0", "text": "Name is Alex", "event": "ADD"},
+    {"id": "1", "text": "Love basketball", "event": "ADD"}
+  ]
+}"""
+        result = self._parse_with_fallback(response)
+        assert len(result["memory"]) == 2
+
+    def test_think_tags_with_json(self):
+        """Reasoning model with <think> tags."""
+        response = '<think>Let me process this...</think>\n```json\n{"memory": [{"id": "0", "text": "test", "event": "ADD"}]}\n```'
+        result = self._parse_with_fallback(response)
+        assert result["memory"][0]["text"] == "test"
+
+    def test_lmstudio_style_response(self):
+        """Mimics the actual LM Studio response format from the issue."""
+        response = """{
+  "memory": [
+    {
+      "id": "0",
+      "text": "Name is Alex",
+      "event": "ADD"
+    },
+    {
+      "id": "1",
+      "text": "Love basketball",
+      "event": "ADD"
+    },
+    {
+      "id": "2",
+      "text": "Love gaming",
+      "event": "ADD"
+    }
+  ]
+}"""
+        result = self._parse_with_fallback(response)
+        assert len(result["memory"]) == 3
+
+    def test_completely_invalid_response(self):
+        """If both attempts fail, the outer except in main.py catches it."""
+        response = "I don't understand the question"
+        with pytest.raises(json.JSONDecodeError):
+            self._parse_with_fallback(response)
+
+    def test_facts_extraction_fallback(self):
+        """Also verify the pattern works for facts extraction responses."""
+        response = 'Sure! Here are the facts:\n{"facts": ["Name is Alex", "Loves basketball"]}\nHope that helps!'
+        result = self._parse_with_fallback(response)
+        assert result["facts"] == ["Name is Alex", "Loves basketball"]
@@ -175,12 +175,41 @@ def test_update(memory_instance):
    result = memory_instance.update("test_id", "Updated memory")

    memory_instance._update_memory.assert_called_once_with(
-        "test_id", "Updated memory", {"Updated memory": [0.1, 0.2, 0.3]}
+        "test_id", "Updated memory", {"Updated memory": [0.1, 0.2, 0.3]}, None
    )

    assert result["message"] == "Memory updated successfully!"


+def test_update_with_metadata(memory_instance):
+    memory_instance.embedding_model = Mock()
+    memory_instance.embedding_model.embed = Mock(return_value=[0.1, 0.2, 0.3])
+
+    memory_instance._update_memory = Mock()
+    metadata = {"category": "sports", "priority": "high"}
+
+    result = memory_instance.update("test_id", "Updated memory", metadata=metadata)
+
+    memory_instance._update_memory.assert_called_once_with(
+        "test_id", "Updated memory", {"Updated memory": [0.1, 0.2, 0.3]}, metadata
+    )
+
+    assert result["message"] == "Memory updated successfully!"
+
+
+def test_update_with_empty_metadata(memory_instance):
+    memory_instance.embedding_model = Mock()
+    memory_instance.embedding_model.embed = Mock(return_value=[0.1, 0.2, 0.3])
+
+    memory_instance._update_memory = Mock()
+
+    memory_instance.update("test_id", "Updated memory", metadata={})
+
+    memory_instance._update_memory.assert_called_once_with(
+        "test_id", "Updated memory", {"Updated memory": [0.1, 0.2, 0.3]}, {}
+    )
+
+
 def test_delete(memory_instance):
    memory_instance._delete_memory = Mock()

@@ -1,4 +1,5 @@
 import json
+from datetime import datetime
 from unittest.mock import MagicMock, patch

 import pytest
@@ -10,7 +11,7 @@ from mem0.memory.utils import normalize_facts

 class MockVectorMemory:
    """Mock memory object for testing incomplete payloads."""
-    
+
    def __init__(self, memory_id: str, payload: dict, score: float = 0.8):
        self.id = memory_id
        self.payload = payload
@@ -104,7 +105,7 @@ def test_collection_name_preserved_after_reset(mock_sqlite, mock_llm_factory, mo

    reset_calls = [call for call in mock_vector_factory.call_args_list if len(mock_vector_factory.call_args_list) > 2]
    if reset_calls:
-        reset_config = reset_calls[-1][0][1]  
+        reset_config = reset_calls[-1][0][1]
        assert reset_config.collection_name == test_collection_name, f"Reset used wrong collection name: {reset_config.collection_name}"


@@ -129,13 +130,13 @@ def test_search_handles_incomplete_payloads(mock_sqlite, mock_llm_factory, mock_
    complete_memory = MockVectorMemory("mem_2", {"data": "content", "hash": "def456"})

    mock_vector_store.search.return_value = [incomplete_memory, complete_memory]
-    
+
    mock_embedder = MagicMock()
    mock_embedder.embed.return_value = [0.1, 0.2, 0.3]
    memory.embedding_model = mock_embedder

    result = memory._search_vector_store("test", {"user_id": "test"}, 10)
-    
+
    assert len(result) == 2
    memories_by_id = {mem["id"]: mem for mem in result}

@@ -572,3 +573,187 @@ def test_update_infer_true_caches_embedding_on_llm_rewrite(mock_sqlite, mock_llm
    # It should NOT be called a 3rd time inside _update_memory
    assert embedder.embed.call_count == 2
    mock_vector_store.update.assert_called_once()
+
+
+@patch('mem0.utils.factory.EmbedderFactory.create')
+@patch('mem0.utils.factory.VectorStoreFactory.create')
+@patch('mem0.utils.factory.LlmFactory.create')
+@patch('mem0.memory.main.SQLiteManager')
+def test_delete_memory_history_has_timestamps(mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory):
+    """
+    Test that deleting a memory records created_at and updated_at in history.
+
+    Ensures DELETE operations preserve the original creation timestamp
+    and record the deletion time for proper audit trails.
+    """
+    mock_embedder_factory.return_value = MagicMock()
+    mock_vector_store = MagicMock()
+    mock_vector_factory.return_value = mock_vector_store
+    mock_llm_factory.return_value = MagicMock()
+    mock_sqlite.return_value = MagicMock()
+
+    from mem0.memory.main import Memory as MemoryClass
+    config = MemoryConfig()
+    memory = MemoryClass(config)
+
+    existing_memory = MagicMock()
+    existing_memory.payload = {
+        "data": "I like Python.",
+        "created_at": "2024-01-01T00:00:00+00:00",
+        "actor_id": None,
+        "role": None,
+    }
+    mock_vector_store.get.return_value = existing_memory
+
+    memory.delete("mem-123")
+
+    call_kwargs = memory.db.add_history.call_args.kwargs
+    assert call_kwargs["created_at"] == "2024-01-01T00:00:00+00:00"
+    assert call_kwargs["updated_at"] is not None
+    datetime.fromisoformat(call_kwargs["updated_at"])  # verify valid ISO timestamp
+
+
+@patch('mem0.utils.factory.EmbedderFactory.create')
+@patch('mem0.utils.factory.VectorStoreFactory.create')
+@patch('mem0.utils.factory.LlmFactory.create')
+@patch('mem0.memory.main.SQLiteManager')
+def test_delete_memory_normalizes_non_utc_created_at(mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory):
+    """Test that non-UTC created_at timestamps are normalized to UTC on delete."""
+    mock_embedder_factory.return_value = MagicMock()
+    mock_vector_store = MagicMock()
+    mock_vector_factory.return_value = mock_vector_store
+    mock_llm_factory.return_value = MagicMock()
+    mock_sqlite.return_value = MagicMock()
+
+    from mem0.memory.main import Memory as MemoryClass
+    config = MemoryConfig()
+    memory = MemoryClass(config)
+
+    existing_memory = MagicMock()
+    existing_memory.payload = {
+        "data": "I like Python.",
+        "created_at": "2024-01-01T05:00:00+05:00",  # UTC+5
+        "actor_id": None,
+        "role": None,
+    }
+    mock_vector_store.get.return_value = existing_memory
+
+    memory.delete("mem-123")
+
+    call_kwargs = memory.db.add_history.call_args.kwargs
+    assert call_kwargs["created_at"] == "2024-01-01T00:00:00+00:00"  # normalized to UTC
+
+
+@patch('mem0.utils.factory.EmbedderFactory.create')
+@patch('mem0.utils.factory.VectorStoreFactory.create')
+@patch('mem0.utils.factory.LlmFactory.create')
+@patch('mem0.memory.main.SQLiteManager')
+def test_delete_memory_missing_created_at(mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory):
+    """Test that delete works when created_at is absent from the payload (pre-existing memories)."""
+    mock_embedder_factory.return_value = MagicMock()
+    mock_vector_store = MagicMock()
+    mock_vector_factory.return_value = mock_vector_store
+    mock_llm_factory.return_value = MagicMock()
+    mock_sqlite.return_value = MagicMock()
+
+    from mem0.memory.main import Memory as MemoryClass
+    config = MemoryConfig()
+    memory = MemoryClass(config)
+
+    existing_memory = MagicMock()
+    existing_memory.payload = {
+        "data": "I like Python.",
+        "actor_id": None,
+        "role": None,
+    }
+    mock_vector_store.get.return_value = existing_memory
+
+    memory.delete("mem-123")
+
+    call_kwargs = memory.db.add_history.call_args.kwargs
+    assert call_kwargs["created_at"] is None
+    assert call_kwargs["updated_at"] is not None
+    datetime.fromisoformat(call_kwargs["updated_at"])  # verify valid ISO timestamp
+
+
+@pytest.mark.asyncio
+@patch('mem0.utils.factory.EmbedderFactory.create')
+@patch('mem0.utils.factory.VectorStoreFactory.create')
+@patch('mem0.utils.factory.LlmFactory.create')
+@patch('mem0.memory.main.SQLiteManager')
+async def test_async_delete_memory_history_has_timestamps(mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory):
+    """
+    Test that async deleting a memory records created_at and updated_at in history.
+
+    Ensures async DELETE operations preserve the original creation timestamp
+    and record the deletion time for proper audit trails.
+    """
+    mock_embedder_factory.return_value = MagicMock()
+    mock_vector_store = MagicMock()
+    mock_vector_factory.return_value = mock_vector_store
+    mock_llm_factory.return_value = MagicMock()
+    mock_sqlite.return_value = MagicMock()
+
+    from mem0.memory.main import AsyncMemory
+    config = MemoryConfig()
+    memory = AsyncMemory(config)
+
+    existing_memory = MagicMock()
+    existing_memory.payload = {
+        "data": "I like Python.",
+        "created_at": "2024-01-01T00:00:00+00:00",
+        "actor_id": None,
+        "role": None,
+    }
+    mock_vector_store.get.return_value = existing_memory
+
+    await memory.delete("mem-123")
+
+    call_kwargs = memory.db.add_history.call_args.kwargs
+    assert call_kwargs["created_at"] == "2024-01-01T00:00:00+00:00"
+    assert call_kwargs["updated_at"] is not None
+    datetime.fromisoformat(call_kwargs["updated_at"])  # verify valid ISO timestamp
+
+
+@patch('mem0.utils.factory.EmbedderFactory.create')
+@patch('mem0.utils.factory.VectorStoreFactory.create')
+@patch('mem0.utils.factory.LlmFactory.create')
+@patch('mem0.memory.storage.SQLiteManager')
+class TestProcessMetadataFiltersMerge:
+    """Regression tests for issue #3952: multiple operators on the same key must be merged."""
+
+    def _make_memory(self, mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory):
+        mock_embedder_factory.return_value = MagicMock()
+        mock_vector_factory.return_value = MagicMock()
+        mock_llm_factory.return_value = MagicMock()
+        mock_sqlite.return_value = MagicMock()
+        from mem0.memory.main import Memory as MemoryClass
+        return MemoryClass(MemoryConfig())
+
+    def test_multiple_operators_same_key_merged(self, mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory):
+        """Filters like created_at: {gte: X, lte: Y} must preserve both operators."""
+        memory = self._make_memory(mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory)
+        result = memory._process_metadata_filters({
+            "created_at": {"gte": 1000, "lte": 2000}
+        })
+        assert result == {"created_at": {"gte": 1000, "lte": 2000}}
+
+    def test_single_operator_still_works(self, mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory):
+        """Single operator filters must continue to work."""
+        memory = self._make_memory(mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory)
+        result = memory._process_metadata_filters({
+            "created_at": {"gte": 1000}
+        })
+        assert result == {"created_at": {"gte": 1000}}
+
+    def test_multiple_keys_with_multiple_operators(self, mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory):
+        """Multiple keys each with multiple operators."""
+        memory = self._make_memory(mock_sqlite, mock_llm_factory, mock_vector_factory, mock_embedder_factory)
+        result = memory._process_metadata_filters({
+            "created_at": {"gte": 1000, "lte": 2000},
+            "score": {"gt": 0.5, "lt": 0.9},
+        })
+        assert result == {
+            "created_at": {"gte": 1000, "lte": 2000},
+            "score": {"gt": 0.5, "lt": 0.9},
+        }
@@ -153,9 +153,16 @@ def test_insert_generates_sql(db_instance_direct, mock_workspace_client):
    sql = kwargs["statement"] if "statement" in kwargs else args[0]
    assert "INSERT INTO" in sql
    assert "catalog.schema.table" in sql
-    assert "id1" in sql
-    # Embedding list rendered
+    # Embedding list rendered inline (ARRAY type not supported by parameterized queries)
    assert "array(0.1, 0.2, 0.3, 0.4)" in sql
+    # User-supplied values should use parameterized queries, not inline values
+    assert ":memory_id_0" in sql
+    assert "id1" not in sql  # id should be in params, not in SQL
+    params = kwargs["parameters"]
+    param_names = {p.name for p in params}
+    assert "memory_id_0" in param_names
+    id_param = next(p for p in params if p.name == "memory_id_0")
+    assert id_param.value == "id1"


 # ---------------------- Search Tests ---------------------- #
@@ -246,7 +253,13 @@ def test_delete_vector(db_instance_delta, mock_workspace_client):
    db_instance_delta.delete("id-delete")
    args, kwargs = mock_workspace_client.statement_execution.execute_statement.call_args
    sql = kwargs.get("statement") or args[0]
-    assert "DELETE FROM" in sql and "id-delete" in sql
+    assert "DELETE FROM" in sql
+    assert ":vector_id" in sql
+    assert "id-delete" not in sql  # value should be in params, not in SQL
+    params = kwargs["parameters"]
+    assert len(params) == 1
+    assert params[0].name == "vector_id"
+    assert params[0].value == "id-delete"


 # ---------------------- Update Tests ---------------------- #
@@ -260,10 +273,17 @@ def test_update_vector(db_instance_direct, mock_workspace_client):
    )
    args, kwargs = mock_workspace_client.statement_execution.execute_statement.call_args
    sql = kwargs.get("statement") or args[0]
-    assert "UPDATE" in sql and "id-upd" in sql
-    assert "embedding = [0.4, 0.5, 0.6, 0.7]" in sql
-    assert "custom = 'val'" in sql
+    assert "UPDATE" in sql
+    assert "embedding = array(0.4, 0.5, 0.6, 0.7)" in sql
+    assert "custom = :payload_custom" in sql
+    assert ":vector_id" in sql
+    assert "id-upd" not in sql  # value should be in params, not in SQL
+    assert "'val'" not in sql  # value should be in params, not in SQL
    assert "user_id" not in sql  # excluded
+    params = kwargs["parameters"]
+    param_map = {p.name: p.value for p in params}
+    assert param_map["payload_custom"] == "val"
+    assert param_map["vector_id"] == "id-upd"


 # ---------------------- Get Tests ---------------------- #
@@ -703,9 +723,12 @@ def test_e2e_crud_lifecycle_delta_sync(mock_workspace_client):
        payloads=[{"data": "test memory", "user_id": "u1", "hash": "h1"}],
        ids=["mem-001"],
    )
-    insert_sql = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs["statement"]
+    insert_call = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    insert_sql = insert_call["statement"]
    assert "INSERT INTO cat.sch.tbl" in insert_sql
-    assert "mem-001" in insert_sql
+    assert ":memory_id_0" in insert_sql  # parameterized, not inline
+    insert_params = {p.name: p.value for p in insert_call["parameters"]}
+    assert insert_params["memory_id_0"] == "mem-001"

    # SEARCH
    mock_workspace_client.vector_search_indexes.query_index.return_value = SimpleNamespace(
@@ -753,16 +776,23 @@ def test_e2e_crud_lifecycle_delta_sync(mock_workspace_client):

    # UPDATE
    db.update(vector_id="mem-001", payload={"memory": "updated memory"})
-    update_sql = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs["statement"]
+    update_call = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    update_sql = update_call["statement"]
    assert "UPDATE cat.sch.tbl" in update_sql
-    assert "mem-001" in update_sql
-    assert "updated memory" in update_sql
+    assert ":vector_id" in update_sql
+    assert ":payload_memory" in update_sql
+    update_params = {p.name: p.value for p in update_call["parameters"]}
+    assert update_params["vector_id"] == "mem-001"
+    assert update_params["payload_memory"] == "updated memory"

    # DELETE
    db.delete("mem-001")
-    delete_sql = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs["statement"]
+    delete_call = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    delete_sql = delete_call["statement"]
    assert "DELETE FROM cat.sch.tbl" in delete_sql
-    assert "mem-001" in delete_sql
+    assert ":vector_id" in delete_sql
+    delete_params = {p.name: p.value for p in delete_call["parameters"]}
+    assert delete_params["vector_id"] == "mem-001"


 def test_e2e_crud_lifecycle_direct_access(mock_workspace_client):
@@ -796,8 +826,11 @@ def test_e2e_crud_lifecycle_direct_access(mock_workspace_client):
        payloads=[{"data": "direct memory", "user_id": "u1", "hash": "h1"}],
        ids=["mem-da-001"],
    )
-    insert_sql = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs["statement"]
+    insert_call = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    insert_sql = insert_call["statement"]
    assert "array(0.1, 0.2, 0.3, 0.4)" in insert_sql
+    insert_params = {p.name: p.value for p in insert_call["parameters"]}
+    assert insert_params["memory_id_0"] == "mem-da-001"

    # SEARCH with vector
    mock_workspace_client.vector_search_indexes.query_index.return_value = SimpleNamespace(
@@ -838,3 +871,191 @@ def test_e2e_crud_lifecycle_direct_access(mock_workspace_client):
    list_kwargs = mock_workspace_client.vector_search_indexes.query_index.call_args.kwargs
    assert "query_vector" in list_kwargs
    assert "query_text" not in list_kwargs
+
+
+# ---------------------- SQL Injection Prevention Tests (Issue #4073) ---------------------- #
+
+
+SQLI_PAYLOADS = [
+    "'; DELETE FROM table; --",
+    "' OR '1'='1",
+    "'; DROP TABLE memories; --",
+    "1' UNION SELECT * FROM secrets --",
+]
+
+
+@pytest.mark.parametrize("malicious_id", SQLI_PAYLOADS)
+def test_delete_prevents_sql_injection(db_instance_delta, mock_workspace_client, malicious_id):
+    """Verify delete() uses parameterized queries so SQL injection payloads are never in the SQL string."""
+    db_instance_delta.delete(malicious_id)
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    # The malicious payload must NOT appear in the SQL statement itself
+    assert malicious_id not in sql
+    assert ":vector_id" in sql
+    # It should be safely passed as a parameter
+    assert kwargs["parameters"][0].value == malicious_id
+
+
+@pytest.mark.parametrize("malicious_id", SQLI_PAYLOADS)
+def test_update_prevents_sql_injection_in_vector_id(db_instance_delta, mock_workspace_client, malicious_id):
+    """Verify update() parameterizes vector_id."""
+    db_instance_delta.update(vector_id=malicious_id, payload={"memory": "safe value"})
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    assert malicious_id not in sql
+    assert ":vector_id" in sql
+    param_map = {p.name: p.value for p in kwargs["parameters"]}
+    assert param_map["vector_id"] == malicious_id
+
+
+@pytest.mark.parametrize("malicious_value", SQLI_PAYLOADS)
+def test_update_prevents_sql_injection_in_payload(db_instance_delta, mock_workspace_client, malicious_value):
+    """Verify update() parameterizes payload values."""
+    db_instance_delta.update(vector_id="safe-id", payload={"memory": malicious_value})
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    assert malicious_value not in sql
+    assert ":payload_memory" in sql
+    param_map = {p.name: p.value for p in kwargs["parameters"]}
+    assert param_map["payload_memory"] == malicious_value
+
+
+@pytest.mark.parametrize("malicious_id", SQLI_PAYLOADS)
+def test_insert_prevents_sql_injection_in_ids(db_instance_delta, mock_workspace_client, malicious_id):
+    """Verify insert() parameterizes memory IDs."""
+    db_instance_delta.insert(
+        vectors=[[0.1, 0.2]],
+        payloads=[{"data": "test", "hash": "h1"}],
+        ids=[malicious_id],
+    )
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    assert malicious_id not in sql
+    assert ":memory_id_0" in sql
+    param_map = {p.name: p.value for p in kwargs["parameters"]}
+    assert param_map["memory_id_0"] == malicious_id
+
+
+@pytest.mark.parametrize("malicious_data", SQLI_PAYLOADS)
+def test_insert_prevents_sql_injection_in_payload_data(db_instance_delta, mock_workspace_client, malicious_data):
+    """Verify insert() parameterizes payload data values."""
+    db_instance_delta.insert(
+        vectors=[[0.1, 0.2]],
+        payloads=[{"data": malicious_data, "hash": "h1"}],
+        ids=["safe-id"],
+    )
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    assert malicious_data not in sql
+    param_map = {p.name: p.value for p in kwargs["parameters"]}
+    assert param_map["memory_0"] == malicious_data
+
+
+@pytest.mark.parametrize("malicious_key", [
+    "memory; DROP TABLE x--",
+    "col' OR '1'='1",
+    "valid_col; DELETE FROM t",
+    "col\nname",
+])
+def test_update_rejects_malicious_column_names(db_instance_delta, mock_workspace_client, malicious_key):
+    """Verify update() skips payload keys that are not valid SQL identifiers."""
+    db_instance_delta.update(
+        vector_id="safe-id",
+        payload={malicious_key: "some value", "memory": "legit"},
+    )
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    # The malicious key must NOT appear as a column name in the SQL
+    assert malicious_key not in sql
+    # The legitimate key should still be present
+    assert ":payload_memory" in sql
+
+
+def test_insert_multi_row(db_instance_delta, mock_workspace_client):
+    """Verify multi-row insert generates unique parameter names per row."""
+    db_instance_delta.insert(
+        vectors=[[0.1, 0.2], [0.3, 0.4]],
+        payloads=[
+            {"data": "first memory", "hash": "h1"},
+            {"data": "second memory", "hash": "h2"},
+        ],
+        ids=["id-1", "id-2"],
+    )
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    params = kwargs["parameters"]
+    param_map = {p.name: p.value for p in params}
+    # Each row should have distinct parameter names
+    assert ":memory_id_0" in sql
+    assert ":memory_id_1" in sql
+    assert param_map["memory_id_0"] == "id-1"
+    assert param_map["memory_id_1"] == "id-2"
+    assert param_map["memory_0"] == "first memory"
+    assert param_map["memory_1"] == "second memory"
+
+
+def test_insert_with_none_values(db_instance_delta, mock_workspace_client):
+    """Verify insert() uses NULL literal for None values, not parameters."""
+    db_instance_delta.insert(
+        vectors=[[0.1, 0.2]],
+        payloads=[{"data": "test", "hash": "h1"}],  # agent_id, run_id etc will be None
+        ids=["id-1"],
+    )
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    assert "NULL" in sql  # None values should be literal NULL
+    # Only non-None values should have parameters
+    param_names = {p.name for p in kwargs["parameters"]}
+    assert "memory_id_0" in param_names
+    assert "memory_0" in param_names
+    assert "hash_0" in param_names
+
+
+def test_update_payload_only(db_instance_delta, mock_workspace_client):
+    """Verify update() works with payload only (no vector)."""
+    db_instance_delta.update(vector_id="id-1", payload={"memory": "new text"})
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    assert "UPDATE" in sql
+    assert "embedding" not in sql
+    assert ":payload_memory" in sql
+    assert ":vector_id" in sql
+
+
+def test_update_vector_only(db_instance_direct, mock_workspace_client):
+    """Verify update() works with vector only (no payload)."""
+    db_instance_direct.update(vector_id="id-1", vector=[0.1, 0.2, 0.3, 0.4])
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    sql = kwargs["statement"]
+    assert "UPDATE" in sql
+    assert "embedding = array(0.1, 0.2, 0.3, 0.4)" in sql
+    assert ":vector_id" in sql
+    param_map = {p.name: p.value for p in kwargs["parameters"]}
+    assert param_map["vector_id"] == "id-1"
+    assert len(kwargs["parameters"]) == 1  # only vector_id param
+
+
+def test_insert_timestamp_params_have_explicit_type(db_instance_delta, mock_workspace_client):
+    """Verify insert() sets type='TIMESTAMP' on created_at/updated_at parameters
+    so Databricks doesn't rely on implicit STRING->TIMESTAMP casting."""
+    db_instance_delta.insert(
+        vectors=[[0.1, 0.2]],
+        payloads=[{
+            "data": "test",
+            "hash": "h1",
+            "created_at": "2024-01-01T00:00:00+00:00",
+            "updated_at": "2024-01-02T00:00:00+00:00",
+        }],
+        ids=["id-1"],
+    )
+    kwargs = mock_workspace_client.statement_execution.execute_statement.call_args.kwargs
+    params = kwargs["parameters"]
+    ts_params = [p for p in params if "created_at" in p.name or "updated_at" in p.name]
+    assert len(ts_params) == 2
+    for p in ts_params:
+        assert p.type == "TIMESTAMP", f"Parameter {p.name} should have type=TIMESTAMP, got {p.type}"
+    # Non-timestamp params should not have a type set (defaults to STRING)
+    non_ts_params = [p for p in params if "created_at" not in p.name and "updated_at" not in p.name]
+    for p in non_ts_params:
+        assert p.type is None, f"Parameter {p.name} should not have explicit type, got {p.type}"
@@ -1,458 +0,0 @@
-"""Tests for the vector store default path fix (issue #4279).
-
-Verifies that vector store defaults use platform-appropriate persistent directories
-instead of /tmp, which is ephemeral and may be inaccessible in restricted environments.
-"""
-
-import logging
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-from mem0.vector_stores.configs import (
-    VectorStoreConfig,
-    _migrate_legacy_data,
-    get_default_vector_store_path,
-)
-
-# ---------------------------------------------------------------------------
-# get_default_vector_store_path unit tests
-# ---------------------------------------------------------------------------
-
-class TestGetDefaultVectorStorePath:
-    """Tests for the get_default_vector_store_path helper function."""
-
-    def _clean_env(self, monkeypatch):
-        """Remove all relevant env vars to get a clean baseline."""
-        for var in ("MEM0_DATA_DIR", "XDG_DATA_HOME", "APPDATA"):
-            monkeypatch.delenv(var, raising=False)
-
-    def test_default_falls_back_to_local_share(self, monkeypatch):
-        """With no env vars set, path should be ~/.local/share/mem0/{provider}."""
-        self._clean_env(monkeypatch)
-        result = get_default_vector_store_path("qdrant")
-        expected = str(Path.home() / ".local" / "share" / "mem0" / "qdrant")
-        assert result == expected
-
-    def test_xdg_data_home_respected(self, monkeypatch):
-        """XDG_DATA_HOME should be used as the base when set."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("XDG_DATA_HOME", "/custom/xdg/data")
-        result = get_default_vector_store_path("chroma")
-        assert result == "/custom/xdg/data/mem0/chroma"
-
-    def test_appdata_respected_on_windows(self, monkeypatch):
-        """APPDATA should be used when XDG_DATA_HOME is not set (Windows)."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("APPDATA", "C:\\Users\\test\\AppData\\Roaming")
-        result = get_default_vector_store_path("faiss")
-        expected = str(Path("C:\\Users\\test\\AppData\\Roaming") / "mem0" / "faiss")
-        assert result == expected
-
-    def test_xdg_takes_precedence_over_appdata(self, monkeypatch):
-        """XDG_DATA_HOME should take precedence over APPDATA."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("XDG_DATA_HOME", "/xdg/path")
-        monkeypatch.setenv("APPDATA", "C:\\windows\\path")
-        result = get_default_vector_store_path("qdrant")
-        assert result == "/xdg/path/mem0/qdrant"
-
-    def test_mem0_data_dir_takes_highest_precedence(self, monkeypatch):
-        """MEM0_DATA_DIR should override all other env vars."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("MEM0_DATA_DIR", "/custom/mem0/data")
-        monkeypatch.setenv("XDG_DATA_HOME", "/should/be/ignored")
-        monkeypatch.setenv("APPDATA", "C:\\also\\ignored")
-        result = get_default_vector_store_path("qdrant")
-        assert result == "/custom/mem0/data/qdrant"
-
-    def test_mem0_data_dir_no_extra_mem0_subdir(self, monkeypatch):
-        """MEM0_DATA_DIR is already mem0-specific, so no extra 'mem0' subdir."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("MEM0_DATA_DIR", "/data/mem0")
-        result = get_default_vector_store_path("qdrant")
-        # Should be /data/mem0/qdrant, NOT /data/mem0/mem0/qdrant
-        assert result == "/data/mem0/qdrant"
-
-    def test_different_providers_get_different_paths(self, monkeypatch):
-        """Each provider should get its own subdirectory."""
-        self._clean_env(monkeypatch)
-        qdrant_path = get_default_vector_store_path("qdrant")
-        chroma_path = get_default_vector_store_path("chroma")
-        faiss_path = get_default_vector_store_path("faiss")
-        assert qdrant_path != chroma_path != faiss_path
-        assert qdrant_path.endswith("/qdrant")
-        assert chroma_path.endswith("/chroma")
-        assert faiss_path.endswith("/faiss")
-
-    def test_path_never_contains_tmp(self, monkeypatch):
-        """Default path should never be under /tmp (the whole point of #4279)."""
-        self._clean_env(monkeypatch)
-        for provider in ("qdrant", "chroma", "faiss"):
-            result = get_default_vector_store_path(provider)
-            assert not result.startswith("/tmp"), f"Provider {provider} still defaults to /tmp: {result}"
-
-
-# ---------------------------------------------------------------------------
-# VectorStoreConfig integration tests
-# ---------------------------------------------------------------------------
-
-class TestVectorStoreConfigPathInjection:
-    """Tests that VectorStoreConfig correctly injects the new default path."""
-
-    def _clean_env(self, monkeypatch):
-        for var in ("MEM0_DATA_DIR", "XDG_DATA_HOME", "APPDATA"):
-            monkeypatch.delenv(var, raising=False)
-
-    def test_qdrant_gets_persistent_default_path(self, monkeypatch):
-        """Qdrant should get a persistent default path, not /tmp."""
-        self._clean_env(monkeypatch)
-        vc = VectorStoreConfig(provider="qdrant", config={})
-        assert "/tmp" not in vc.config.path
-        assert "mem0" in vc.config.path
-        assert vc.config.path.endswith("/qdrant")
-
-    def test_explicit_path_not_overridden(self, monkeypatch):
-        """An explicitly provided path should be used as-is."""
-        self._clean_env(monkeypatch)
-        custom_path = "/my/custom/qdrant/path"
-        vc = VectorStoreConfig(provider="qdrant", config={"path": custom_path})
-        assert vc.config.path == custom_path
-
-    def test_explicit_tmp_path_still_works(self, monkeypatch):
-        """Users who explicitly want /tmp should still be able to use it."""
-        self._clean_env(monkeypatch)
-        vc = VectorStoreConfig(provider="qdrant", config={"path": "/tmp/qdrant"})
-        assert vc.config.path == "/tmp/qdrant"
-
-    def test_mem0_data_dir_flows_through_config(self, monkeypatch):
-        """MEM0_DATA_DIR should be respected through VectorStoreConfig."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("MEM0_DATA_DIR", "/custom/data")
-        vc = VectorStoreConfig(provider="qdrant", config={})
-        assert vc.config.path == "/custom/data/qdrant"
-
-    def test_xdg_data_home_flows_through_config(self, monkeypatch):
-        """XDG_DATA_HOME should be respected through VectorStoreConfig."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("XDG_DATA_HOME", "/xdg/data")
-        vc = VectorStoreConfig(provider="qdrant", config={})
-        assert vc.config.path == "/xdg/data/mem0/qdrant"
-
-
-# ---------------------------------------------------------------------------
-# Qdrant-specific config tests
-# ---------------------------------------------------------------------------
-
-class TestQdrantConfigDefault:
-    """Tests that QdrantConfig's own default_factory uses the new path."""
-
-    def _clean_env(self, monkeypatch):
-        for var in ("MEM0_DATA_DIR", "XDG_DATA_HOME", "APPDATA"):
-            monkeypatch.delenv(var, raising=False)
-
-    def test_qdrant_field_default_is_persistent(self, monkeypatch):
-        """QdrantConfig's path Field default should not be /tmp."""
-        self._clean_env(monkeypatch)
-        from mem0.configs.vector_stores.qdrant import QdrantConfig
-
-        # When path is explicitly provided, the before-validator sees it
-        config = QdrantConfig(path=get_default_vector_store_path("qdrant"))
-        assert "/tmp" not in config.path
-        assert config.path.endswith("/qdrant")
-
-    def test_qdrant_via_vector_store_config_no_path(self, monkeypatch):
-        """Creating QdrantConfig via VectorStoreConfig with empty config should work."""
-        self._clean_env(monkeypatch)
-        vc = VectorStoreConfig(provider="qdrant", config={})
-        assert vc.config.path is not None
-        assert "/tmp" not in vc.config.path
-
-
-# ---------------------------------------------------------------------------
-# ChromaDB-specific config tests
-# ---------------------------------------------------------------------------
-
-class TestChromaDbConfigDefault:
-    """Tests that ChromaDB's sentinel check works with the new default path."""
-
-    def _clean_env(self, monkeypatch):
-        for var in ("MEM0_DATA_DIR", "XDG_DATA_HOME", "APPDATA"):
-            monkeypatch.delenv(var, raising=False)
-
-    def test_chroma_default_path_via_vector_store_config(self, monkeypatch):
-        """ChromaDB via VectorStoreConfig should get a non-/tmp default path."""
-        self._clean_env(monkeypatch)
-        vc = VectorStoreConfig(provider="chroma", config={})
-        assert "/tmp" not in vc.config.path
-        assert vc.config.path.endswith("/chroma")
-
-    def test_chroma_cloud_config_strips_default_path(self, monkeypatch):
-        """ChromaDB cloud config should strip the injected default path."""
-        self._clean_env(monkeypatch)
-        default_path = get_default_vector_store_path("chroma")
-        from mem0.configs.vector_stores.chroma import ChromaDbConfig
-
-        # Simulate what VectorStoreConfig does: inject default path, then create config
-        config = ChromaDbConfig(
-            path=default_path,
-            api_key="test-key",
-            tenant="test-tenant",
-        )
-        # When cloud config is provided and path matches default, path should be stripped
-        assert config.path is None
-
-    def test_chroma_explicit_path_with_cloud_raises(self, monkeypatch):
-        """ChromaDB with both explicit custom path and cloud config should raise."""
-        self._clean_env(monkeypatch)
-        from mem0.configs.vector_stores.chroma import ChromaDbConfig
-
-        with pytest.raises(ValueError, match="Cannot specify both"):
-            ChromaDbConfig(
-                path="/my/custom/path",
-                api_key="test-key",
-                tenant="test-tenant",
-            )
-
-
-# ---------------------------------------------------------------------------
-# FAISS-specific tests
-# ---------------------------------------------------------------------------
-
-class TestFaissDefaultPath:
-    """Tests that FAISS uses the new default path."""
-
-    def _clean_env(self, monkeypatch):
-        for var in ("MEM0_DATA_DIR", "XDG_DATA_HOME", "APPDATA"):
-            monkeypatch.delenv(var, raising=False)
-
-    def test_faiss_default_path_via_vector_store_config(self, monkeypatch):
-        """FAISS via VectorStoreConfig should get a non-/tmp default path."""
-        self._clean_env(monkeypatch)
-        vc = VectorStoreConfig(provider="faiss", config={})
-        assert "/tmp" not in vc.config.path
-        assert vc.config.path.endswith("/faiss")
-
-    def test_faiss_implementation_uses_new_default(self, monkeypatch):
-        """FAISS implementation's own fallback should not use /tmp."""
-        self._clean_env(monkeypatch)
-        with patch("faiss.IndexFlatL2") as mock_index:
-            mock_index.return_value = MagicMock()
-            with patch("faiss.write_index"):
-                from mem0.vector_stores.faiss import FAISS
-                store = FAISS(collection_name="test")
-                assert "/tmp" not in store.path
-                assert "mem0" in store.path
-
-
-# ---------------------------------------------------------------------------
-# Legacy path migration warning tests
-# ---------------------------------------------------------------------------
-
-class TestLegacyPathMigration:
-    """Tests that legacy /tmp data is automatically migrated to the new path.
-
-    Uses the ``legacy_path`` parameter of ``_migrate_legacy_data`` so that every
-    test exercises real filesystem operations (via pytest ``tmp_path``) instead of
-    mocking ``Path`` and ``shutil.copytree``.  This catches real issues like
-    permission errors, path resolution, and symlink handling that mocks silently
-    skip over.
-    """
-
-    def test_auto_migration_copies_legacy_data(self, tmp_path, caplog):
-        """When legacy dir has data and new path doesn't exist, data is copied."""
-        legacy = tmp_path / "legacy_qdrant"
-        legacy.mkdir()
-        (legacy / "collection").mkdir()
-        (legacy / "collection" / "data.bin").write_bytes(b"\x00real-vector-data")
-
-        new = tmp_path / "new_qdrant"
-
-        with caplog.at_level(logging.INFO, logger="mem0.vector_stores.configs"):
-            _migrate_legacy_data("qdrant", str(new), legacy_path=str(legacy))
-
-        # Data was actually copied
-        assert (new / "collection" / "data.bin").exists()
-        assert (new / "collection" / "data.bin").read_bytes() == b"\x00real-vector-data"
-        # Sentinel was written
-        assert (new / ".migration_complete").exists()
-        # Legacy data is untouched (copy, not move)
-        assert (legacy / "collection" / "data.bin").exists()
-        assert "migrated" in caplog.text.lower()
-
-    def test_no_migration_when_legacy_path_missing(self, tmp_path):
-        """No-op when the legacy directory doesn't exist at all."""
-        nonexistent = tmp_path / "does_not_exist"
-        new = tmp_path / "new"
-
-        _migrate_legacy_data("qdrant", str(new), legacy_path=str(nonexistent))
-
-        assert not new.exists()
-
-    def test_no_migration_when_legacy_path_empty_dir(self, tmp_path):
-        """No-op when the legacy directory exists but is empty."""
-        legacy = tmp_path / "empty_qdrant"
-        legacy.mkdir()
-
-        new = tmp_path / "new"
-
-        _migrate_legacy_data("qdrant", str(new), legacy_path=str(legacy))
-
-        assert not new.exists()
-
-    def test_no_migration_when_legacy_path_is_symlink(self, tmp_path):
-        """Refuse to migrate if legacy path is a symlink (prevents symlink attacks)."""
-        real_dir = tmp_path / "real_data"
-        real_dir.mkdir()
-        (real_dir / "secret.key").write_text("sensitive")
-
-        symlink = tmp_path / "symlink_qdrant"
-        symlink.symlink_to(real_dir)
-
-        new = tmp_path / "new"
-
-        _migrate_legacy_data("qdrant", str(new), legacy_path=str(symlink))
-
-        assert not new.exists()
-
-    def test_no_migration_when_new_path_already_has_data(self, tmp_path, caplog):
-        """Don't clobber existing data at the new path."""
-        legacy = tmp_path / "legacy"
-        legacy.mkdir()
-        (legacy / "old.bin").write_text("legacy data")
-
-        new = tmp_path / "new"
-        new.mkdir()
-        (new / "existing.bin").write_text("keep this")
-
-        with caplog.at_level(logging.INFO, logger="mem0.vector_stores.configs"):
-            _migrate_legacy_data("qdrant", str(new), legacy_path=str(legacy))
-
-        # Existing data preserved, legacy data NOT copied
-        assert (new / "existing.bin").read_text() == "keep this"
-        assert not (new / "old.bin").exists()
-        assert "both legacy path" in caplog.text.lower()
-
-    def test_no_migration_when_sentinel_exists(self, tmp_path):
-        """Skip migration when .migration_complete sentinel already exists."""
-        legacy = tmp_path / "legacy"
-        legacy.mkdir()
-        (legacy / "data.bin").write_text("legacy data")
-
-        new = tmp_path / "new"
-        new.mkdir()
-        (new / ".migration_complete").touch()
-
-        _migrate_legacy_data("qdrant", str(new), legacy_path=str(legacy))
-
-        # Legacy data was NOT copied (sentinel prevented it)
-        assert not (new / "data.bin").exists()
-
-    def test_migration_failure_falls_back_to_warning(self, tmp_path, caplog):
-        """If copytree fails, log a warning with manual instructions."""
-        legacy = tmp_path / "legacy"
-        legacy.mkdir()
-        (legacy / "data.bin").write_text("legacy data")
-
-        new = tmp_path / "new"
-
-        with patch("shutil.copytree", side_effect=PermissionError("denied")):
-            with caplog.at_level(logging.WARNING, logger="mem0.vector_stores.configs"):
-                _migrate_legacy_data("qdrant", str(new), legacy_path=str(legacy))
-
-        # No sentinel on failure
-        assert not (new / ".migration_complete").exists()
-        assert "denied" in caplog.text
-
-    def test_migration_is_idempotent(self, tmp_path):
-        """Running migration twice doesn't duplicate data (sentinel prevents re-run)."""
-        legacy = tmp_path / "legacy"
-        legacy.mkdir()
-        (legacy / "data.bin").write_text("original")
-
-        new = tmp_path / "new"
-
-        _migrate_legacy_data("qdrant", str(new), legacy_path=str(legacy))
-        assert (new / "data.bin").read_text() == "original"
-
-        # Modify legacy data after first migration
-        (legacy / "data.bin").write_text("modified")
-
-        # Second call is a no-op because sentinel exists
-        _migrate_legacy_data("qdrant", str(new), legacy_path=str(legacy))
-        assert (new / "data.bin").read_text() == "original"
-
-    def test_migration_preserves_nested_directory_structure(self, tmp_path):
-        """Deep directory trees are faithfully copied."""
-        legacy = tmp_path / "legacy"
-        (legacy / "collections" / "default" / "segments").mkdir(parents=True)
-        (legacy / "collections" / "default" / "segments" / "index.bin").write_bytes(b"\x01\x02")
-        (legacy / "meta.json").write_text('{"version": 1}')
-
-        new = tmp_path / "new"
-
-        _migrate_legacy_data("qdrant", str(new), legacy_path=str(legacy))
-
-        assert (new / "meta.json").read_text() == '{"version": 1}'
-        assert (new / "collections" / "default" / "segments" / "index.bin").read_bytes() == b"\x01\x02"
-
-    def test_no_migration_when_explicit_path_provided(self, monkeypatch, caplog):
-        """VectorStoreConfig with explicit path should not trigger migration."""
-        for var in ("MEM0_DATA_DIR", "XDG_DATA_HOME", "APPDATA"):
-            monkeypatch.delenv(var, raising=False)
-        with caplog.at_level(logging.WARNING, logger="mem0.vector_stores.configs"):
-            VectorStoreConfig(provider="qdrant", config={"path": "/my/path"})
-
-        assert "migrat" not in caplog.text.lower()
-
-
-# ---------------------------------------------------------------------------
-# Cross-platform / issue #4279 scenario tests
-# ---------------------------------------------------------------------------
-
-class TestIssue4279Scenarios:
-    """End-to-end tests for the specific scenarios described in issue #4279."""
-
-    def _clean_env(self, monkeypatch):
-        for var in ("MEM0_DATA_DIR", "XDG_DATA_HOME", "APPDATA"):
-            monkeypatch.delenv(var, raising=False)
-
-    def test_windows_no_tmp(self, monkeypatch):
-        """Windows doesn't have /tmp — APPDATA should be used."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("APPDATA", "C:\\Users\\test\\AppData\\Roaming")
-        for provider in ("qdrant", "chroma", "faiss"):
-            path = get_default_vector_store_path(provider)
-            assert not path.startswith("/tmp"), f"Windows path for {provider} still uses /tmp"
-            assert "AppData" in path
-
-    def test_linux_systemd_with_xdg(self, monkeypatch):
-        """Linux systemd services should respect XDG_DATA_HOME."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("XDG_DATA_HOME", "/var/lib/myservice")
-        path = get_default_vector_store_path("qdrant")
-        assert path == "/var/lib/myservice/mem0/qdrant"
-
-    def test_docker_with_custom_data_dir(self, monkeypatch):
-        """Docker users can mount a volume and point MEM0_DATA_DIR to it."""
-        self._clean_env(monkeypatch)
-        monkeypatch.setenv("MEM0_DATA_DIR", "/data/mem0")
-        path = get_default_vector_store_path("qdrant")
-        assert path == "/data/mem0/qdrant"
-
-    def test_macos_default_is_persistent(self, monkeypatch):
-        """macOS default should be under home directory, not /tmp."""
-        self._clean_env(monkeypatch)
-        path = get_default_vector_store_path("qdrant")
-        assert path.startswith(str(Path.home()))
-        assert "/tmp" not in path
-
-    def test_all_affected_providers_fixed(self, monkeypatch):
-        """All providers with a path field (qdrant, chroma, faiss) should be fixed."""
-        self._clean_env(monkeypatch)
-        for provider in ("qdrant", "chroma", "faiss"):
-            vc = VectorStoreConfig(provider=provider, config={})
-            assert "/tmp" not in vc.config.path, (
-                f"Provider '{provider}' still defaults to /tmp: {vc.config.path}"
-            )
Author	SHA1	Message	Date
Kartik GitHub Saket Aryan Claude Opus 4.6	e8004b93db	chore: updating the sdk version and changelog (#4561 ) Co-authored-by: Saket Aryan <saketaryan2002@gmail.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>	2026-03-26 22:21:31 +05:30
Gabriel SteinandGitHub	4e414e4015	fix(plugin): make Cursor plugin fully functional (#4547 )	2026-03-26 09:46:42 -07:00
mintlify[bot]andGitHub	16455789d4	Fix short SEO description in integration guide template (#4551 )	2026-03-26 09:39:54 -07:00
Utkarsh GitHub utkarsh240799 Claude Opus 4.6	3ac4e047de	fix: merge multiple filter operators for same key (#4559 ) Co-authored-by: utkarsh240799 <utkarsh240799@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-26 20:28:37 +05:30
Utkarsh GitHub utkarsh240799 Claude Opus 4.6	a2ffca3266	fix: prevent SQL injection in Databricks vector store (#4558 ) Co-authored-by: utkarsh240799 <utkarsh240799@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-26 20:22:34 +05:30
Felippe MercurioandGitHub	3a9fcdbec2	fix(oss): make pgvector pg import compatible with ESM (#4544 )	2026-03-26 20:07:39 +05:30
Utkarsh GitHub utkarsh240799 Claude Opus 4.6	515f87b6bd	docs: fix OSS REST API endpoint discrepancies (#4555 ) Co-authored-by: utkarsh240799 <utkarsh240799@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-26 20:05:23 +05:30
zaid khan GitHub utkarsh240799 Claude Opus 4.6	5edc0cc99f	fix: update parameter added to the update function which is exposed t… (#3799 ) Co-authored-by: utkarsh240799 <utkarsh240799@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-26 20:02:33 +05:30
Utkarsh GitHub utkarsh240799 Claude Opus 4.6	7fff26f374	docs: fix LLM reranker config examples and field names (#4539 ) Co-authored-by: utkarsh240799 <utkarsh240799@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-26 19:58:05 +05:30
VictorECDSAandGitHub	1aecfadf45	fix: add timestamps for DELETE operations in history (#4492 )	2026-03-26 18:52:10 +05:30
Chaithanya Kumar GitHub Claude Opus 4.6	7e06aeeada	fix(openclaw): improve credential detection in extraction instructions (#4552 ) Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-26 17:28:18 +05:30
Utkarsh GitHub utkarsh240799 Claude Opus 4.6	2a59c9fd99	fix: handle chatty LLM responses in JSON parsing (#4525 ) Co-authored-by: utkarsh240799 <utkarsh240799@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-26 16:39:17 +05:30
Chaithanya Kumar GitHub Claude Opus 4.6	669ed184e4	fix(openclaw): prevent extraction of standalone timestamps as memories (#4550 ) Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>	2026-03-26 15:19:50 +05:30
Gabriel SteinandGitHub	3c2683c1b5	feat: add Mem0 plugin for Claude Code and Cursor (#4518 )	2026-03-25 14:45:59 -07:00
HimanshuandGitHub	f06e2d744d	Fix/OpenAI embedding dimensions 4153 (#4481 )	2026-03-25 19:59:28 +05:30
lamost423andGitHub	f9e30304d7	fix: sanitize hyphens in Neo4j Cypher relationship names (#4154 )	2026-03-25 19:58:27 +05:30