update quickstart

14 files changed, 995 insertions, 1505 deletions

diff --git a/apps/docs/docs.json b/apps/docs/docs.json
index 26725632..e86446c0 100644
--- a/apps/docs/docs.json
+++ b/apps/docs/docs.json
@@ -71,7 +71,7 @@
 						"pages": [
 							{
 								"group": "Getting Started",
-								"pages": ["intro", "routervsapi", "quickstart", "memory-vs-rag"]
+								"pages": ["intro", "quickstart", "memory-vs-rag"]
 							},
 							{
 								"group": "Memory API",
@@ -112,7 +112,6 @@
 										]
 									},
 									"search/filtering",
-									"user-profiles",
 									"memory-api/track-progress",
 									{
 										"group": "List Memories",
@@ -148,6 +147,16 @@
 								]
 							},
 							{
+								"group": "User Profiles",
+								"icon": "user",
+								"pages": [
+									"user-profiles/overview",
+									"user-profiles/api",
+									"user-profiles/examples",
+									"user-profiles/use-cases"
+								]
+							},
+							{
 								"group": "Memory Router",
 								"icon": "route",
 								"pages": [
diff --git a/apps/docs/images/memory-graph.png b/apps/docs/images/memory-graph.png
new file mode 100644
index 00000000..06dfd839
--- /dev/null
+++ b/apps/docs/images/memory-graph.png
diff --git a/apps/docs/intro.mdx b/apps/docs/intro.mdx
index 3c0f76b7..efdcee38 100644
--- a/apps/docs/intro.mdx
+++ b/apps/docs/intro.mdx
@@ -15,49 +15,57 @@ Supermemory gives your LLMs long-term memory. Instead of stateless text generati
 - Supermemory [intelligently indexes them](/how-it-works) and builds a semantic understanding graph on top of an entity (e.g., a user, a document, a project, an organization).
 - At query time, we fetch only the most relevant context and pass it to your models.
 
-We offer three ways to add memory to your LLMs:
+## Supermemory is context engineering.
 
-### Memory API — full control
+#### Ingestion and Extraction
 
-- Ingest text, files, and chats (supports multi-modal); search & filter; re-rank results.
-- Modelled after the actual human brain's working with smart forgetting, decay, recency bias, context rewriting, etc.
-- API + SDKs for Node & Python; designed to scale in production.
+Supermemory handles all the extraction, for any data type that you have.
+- Text
+- Conversations
+- Files (PDF, Images, Docs)
+- Even videos!
 
-<Info>
-    You can reference the full API documentation for the Memory API [here](/api-reference/manage-memories/add-memory).
-</Info>
+... and then,
 
-### AI SDK
+We offer three ways to add context to your LLMs:
 
-- Native Vercel AI SDK integration with `@supermemory/tools/ai-sdk`
-- Memory tools for agents or infinite chat for automatic context
-- Works with streamText, generateText, and all AI SDK features
+#### Memory API — Learned user context
 
-```typescript
-import { streamText } from "ai"
-import { supermemoryTools } from "@supermemory/tools/ai-sdk"
+![memory graph](/images/memory-graph.png)
 
-const result = await streamText({
-  model: anthropic("claude-3"),
-  tools: supermemoryTools("YOUR_KEY")
-})
-```
+Supermemory learns and builds the memory for the user. These are extracted facts about the user, that:
+- Evolve on top of existing context about the user, **in real time**
+- Handle **knowledge updates, temporal changes, forgetfulness**
+- Creates a **user profile** as the default context provider for the LLM.
 
-<Info>
-The AI SDK is recommended for new projects using Vercel AI SDK. The Router works best for existing **chat applications**, whereas the Memory API works as a **complete memory database** with granular control.
-</Info>
+_This can then be provided to the LLM, to give more contextual, personalized responses._
+
+#### User profiles
+
+Having the latest, evolving context about the user allows us to also create a **User Profile**. This is a combination of static and dynamic facts about the user, that the agent should **always know**
+Developers can configure supermemory with what static and dynamic contents are, depending on their use case.
 
+- Static: Information that the agent should **always** know.
+- Dynamic: **Episodic** information, about last few conversations etc.
 
-### Memory Router — drop-in proxy with minimal code
+This leads to a much better retrieval system, and extremely personalized responses.
+
+#### RAG - Advanced semantic search
+
+Along with the user context, developers can also choose to do a search on the raw context. We provide full RAG-as-a-service, along with
+- Full advanced metadata filtering
+- Contextual chunking
+- Works well with the memory engine
+
+<Info>
+    You can reference the full API reference for the Memory API [here](/api-reference/manage-documents/add-document).
+</Info>
 
-- Keep your existing LLM client; just append `api.supermemory.ai/v3/` to your base URL.
-- Automatic chunking and token management that fits your context window.
-- Adds minimal latency on top of existing LLM requests.
 
 <Note>
-All three approaches share the **same memory pool** when using the same user ID. You can mix and match based on your needs.
+All three approaches share the **same context pool** when using the same user ID (`containerTag`). You can mix and match based on your needs.
 </Note>
 
 ## Next steps
 
-Head to the [**Router vs API**](/routervsapi) guide to understand the technical differences between the two and pick what’s best for you with a simple 4-question flow.
+Head to the [**How it works**](/how-it-works) guide to understand the underlying way of how supermemory represents and learns in data.
diff --git a/apps/docs/introduction.mdx b/apps/docs/introduction.mdx
index a56eb603..197586d6 100644
--- a/apps/docs/introduction.mdx
+++ b/apps/docs/introduction.mdx
@@ -38,12 +38,12 @@ export const HeroCard = ({ imageUrl, title, description, href }) => {
         imageUrl="https://imagedelivery.net/_Zs8NCbSWCQ8-iurXrWjBg/40fe287e-b392-4bd6-9fc5-128ef674ca00/public"
         title="Memory APIs"
         description="Use our hyper fast, scalable and composable APIs for memory and RAG"
-        href="/how-it-works"
+        href="/intro"
       />
 
       <HeroCard
-        imageUrl="https://imagedelivery.net/_Zs8NCbSWCQ8-iurXrWjBg/eda8b2fd-9633-4e93-c6bd-10b44be75e00/public"
-        title="Model Enhancer (Infinite chat)"
+        imageUrl="https://imagedelivery.net/_Zs8NCbSWCQ8-iurXrWjBg/9af9572c-9f8d-42d8-f7d0-503a5f87a300/public"
+        title="User profiles"
         description="One line to add memory to your app. Supercharge your LLM with supermemory's intelligent context management."
         href="/memory-router/overview"
       />
@@ -56,7 +56,7 @@ export const HeroCard = ({ imageUrl, title, description, href }) => {
       />
 
       <HeroCard
-        imageUrl="https://imagedelivery.net/_Zs8NCbSWCQ8-iurXrWjBg/9af9572c-9f8d-42d8-f7d0-503a5f87a300/public"
+        imageUrl="https://imagedelivery.net/_Zs8NCbSWCQ8-iurXrWjBg/eda8b2fd-9633-4e93-c6bd-10b44be75e00/public"
         title="Cookbooks"
         description="Get started with supermemory with tutorials and examples"
         href="/cookbook/overview"
diff --git a/apps/docs/package.json b/apps/docs/package.json
index 46e0b708..908f5fa5 100644
--- a/apps/docs/package.json
+++ b/apps/docs/package.json
@@ -10,5 +10,8 @@
     "@types/bun": "latest",
     "mintlify": "^4.2.112",
     "typescript": "^5.9.2"
+  },
+  "dependencies": {
+    "supermemory": "3.10.0"
   }
 }
diff --git a/apps/docs/quickstart.mdx b/apps/docs/quickstart.mdx
index b0d12fad..eeb88768 100644
--- a/apps/docs/quickstart.mdx
+++ b/apps/docs/quickstart.mdx
@@ -9,871 +9,112 @@ description: Make your first API call to Supermemory - add and retrieve memories
 
 ## Memory API
 
-**Step 1.** Sign up for [Supermemory’s Developer Platform](http://console.supermemory.ai) to get the API key. Click on **API Keys -> Create API Key** to generate one.
+**Step 1.** Sign up for [Supermemory's Developer Platform](http://console.supermemory.ai) to get the API key. Click on **API Keys -> Create API Key** to generate one.
 
 ![create api key](./images/create-api.png)
 
-<Tabs>
-
-    <Tab title="Python">
-        **Step 2.** Install the Supermemory client
-
-        ```python
-        pip install supermemory
-        ```
-
-        **Step 3.** Run this in your terminal to create an environment variable with your API key:
-
-        ```bash
-        export SUPERMEMORY_API_KEY=“YOUR_API_KEY”
-        ```
-
-        **Step 4.** Import the module in your python file:
-
-        ```python
-        from supermemory import Supermemory
-        import os
-
-
-        client = Supermemory(api_key=os.environ.get("SUPERMEMORY_API_KEY"))
-        ```
-
-        **Step 5.** Add your first memory as follows:
-
-        ```python
-        # Create one rich memory about quantum computing applications
-        memory_content = """Quantum computing represents a paradigm shift in computational power, leveraging quantum mechanical phenomena like superposition and entanglement to solve problems that are intractable for classical computers.
-
-
-        The field emerged from theoretical work in the 1980s, when physicist Richard Feynman proposed that quantum systems could simulate other quantum systems more efficiently than classical computers. This insight led to the development of quantum algorithms like Shor's algorithm for factoring large numbers and Grover's algorithm for unstructured search problems.
-
-
-        Today, quantum computing applications span multiple domains: in cryptography, quantum computers threaten current encryption standards while enabling new quantum-resistant protocols; in drug discovery, they can simulate molecular interactions with unprecedented accuracy; in optimization problems like logistics and financial modeling, they offer exponential speedups for certain classes of problems.
-
-
-        Major tech companies including IBM, Google, and Microsoft have invested billions in quantum computing research, while startups like Rigetti Computing and IonQ focus on specific hardware approaches. The race for quantum advantage - demonstrating a quantum computer solving a problem faster than any classical computer - has become a key milestone in the field.
-
-
-        Despite the promise, significant challenges remain: quantum decoherence, error correction, and scaling qubit counts while maintaining coherence. Researchers are exploring various approaches including superconducting qubits, trapped ions, topological qubits, and photonic systems, each with different trade-offs between coherence time, gate fidelity, and scalability."""
-
-
-        # Add the memory to Supermemory
-        response = client.memories.add(
-            content=memory_content,
-            container_tag="quantum-computing",
-            metadata={
-                "category": "technology-overview",
-                "topic": "quantum-computing",
-                "complexity": "intermediate",
-                "word_count": len(memory_content.split())
-            }
-        )
-
-
-        print(f"Memory added successfully!")
-        print(f"Memory ID: {response.id}")
-        print(f"Content length: {len(memory_content)} characters")
-        ```
-
-        Run your code. The output is as follows:
-
-        ```bash
-        Memory added successfully!
-        Memory ID: uLtGU14SBDzfsvefYWbwe7
-        Content length: 1701 characters
-        ```
-
-        **Step 6.** Search for this memory as follows:
-
-        ```python
-        results = client.search.memories(q="what are some applications of quantum computing?", limit=3)
-
-
-        print(results)
-        ```
-        The output is as follows:
-
-        ```bash
-        SearchMemoriesResponse(
-            results=[
-                Result(
-                    id="Bn1uc1yQdw3Huf8oitruwF",
-                    memory="Quantum computing applications include cryptography (threatening current encryption standards, enabling quantum-resistant protocols), drug discovery (simulating molecular interactions), and optimization problems (logistics, financial modeling, offering exponential speedups).",
-                    metadata=None,
-                    similarity=0.7920647723809932,
-                    updated_at=datetime.datetime(
-                        2025, 8, 24, 5, 41, 55, 87000, tzinfo=datetime.timezone.utc
-                    ),
-                    context=ResultContext(children=[], parents=[]),
-                    documents=None,
-                    version=1.0,
-                    updatedAt="2025-08-24T05:41:55.087Z",
-                    rootMemoryId="Bn1uc1yQdw3Huf8oitruwF",
-                ),
-                Result(
-                    id="4aCa4oM8praVBCWdNksjxf",
-                    memory="Quantum computing is a paradigm shift in computational power, leveraging quantum mechanical phenomena like superposition and entanglement to solve problems intractable for classical computers.",
-                    metadata=None,
-                    similarity=0.7198909950191389,
-                    updated_at=datetime.datetime(
-                        2025, 8, 24, 5, 41, 55, 87000, tzinfo=datetime.timezone.utc
-                    ),
-                    context=ResultContext(children=[], parents=[]),
-                    documents=None,
-                    version=1.0,
-                    updatedAt="2025-08-24T05:41:55.087Z",
-                    rootMemoryId="4aCa4oM8praVBCWdNksjxf",
-                ),
-                Result(
-                    id="8vzhZhBCuqyrLNXtzBDx7y",
-                    memory="IBM, Google, and Microsoft have invested billions in quantum computing research.",
-                    metadata=None,
-                    similarity=0.6960905375426799,
-                    updated_at=datetime.datetime(
-                        2025, 8, 24, 5, 41, 55, 87000, tzinfo=datetime.timezone.utc
-                    ),
-                    context=ResultContext(children=[], parents=[]),
-                    documents=None,
-                    version=1.0,
-                    updatedAt="2025-08-24T05:41:55.087Z",
-                    rootMemoryId="8vzhZhBCuqyrLNXtzBDx7y",
-                ),
-            ],
-            timing=214.0,
-            total=3.0,
-        )
-        ```
-        Awesome! Now that you’ve made your first request, explore all of Supermemory’s features in detail and how you can use them in your app.
-    </Tab>
-
-    <Tab title="Typescript">
-        **Step 2.** Install the Supermemory dependency:
-
-        ```bash
-        npm install supermemory
-        ```
-
-        **Step 3.** Set the environment variable:
-
-        ```bash
-        export SUPERMEMORY_API_KEY="your_actual_api_key_here"
-        ```
-        **Step 4.** Create a `quickstart.ts` file and import the package:
-
-        ```ts
-        import 'dotenv/config';
-        import Supermemory from 'supermemory';
-
-
-        const client = new Supermemory({
-        apiKey: process.env.SUPERMEMORY_API_KEY});
-        ```
-
-        **Step 5.** Add a memory:
-
-        ```ts
-
-        const memoryContent = `Quantum computing represents a paradigm shift in computational power, leveraging quantum mechanical phenomena like superposition and entanglement to solve problems that are intractable for classical computers.
-
-
-        The field emerged from theoretical work in the 1980s, when physicist Richard Feynman proposed that quantum systems could simulate other quantum systems more efficiently than classical computers. This insight led to the development of quantum algorithms like Shor's algorithm for factoring large numbers and Grover's algorithm for unstructured search problems.
-
-
-        Today, quantum computing applications span multiple domains: in cryptography, quantum computers threaten current encryption standards while enabling new quantum-resistant protocols; in drug discovery, they can simulate molecular interactions with unprecedented accuracy; in optimization problems like logistics and financial modeling, they offer exponential speedups for certain classes of problems.
-
-
-        Major tech companies including IBM, Google, and Microsoft have invested billions in quantum computing research, while startups like Rigetti Computing and IonQ focus on specific hardware approaches. The race for quantum advantage - demonstrating a quantum computer solving a problem faster than any classical computer - has become a key milestone in the field.
-
-
-        Despite the promise, significant challenges remain: quantum decoherence, error correction, and scaling qubit counts while maintaining coherence. Researchers are exploring various approaches including superconducting qubits, trapped ions, topological qubits, and photonic systems, each with different trade-offs between coherence time, gate fidelity, and scalability.`;
-
-
-        async function addMemory() {
-            try {
-                const response = await client.memories.add({
-                    content: memoryContent,
-                    containerTag: "quantum-computing",
-                    metadata: {
-                    category: "technology-overview",
-                    topic: "quantum-computing",
-                    complexity: "intermediate",
-                    wordCount: memoryContent.split(' ').length
-                    }
-                });
-                console.log("Memory added successfully!");
-                console.log(`Memory ID: ${response.id}`);
-                return response.id
-            } catch (error) {
-                console.error("Error adding memory:", error);
-                throw error;
-            }
-        }
-        ```
-
-        Running this code block gives the following output:
-
-        ```bash
-
-        Memory added successfully!
-        Memory ID: adMxzQgSxo37jq6kjpsFMg
-        ```
-
-        **Step 6.** Search for your memory using natural language:
-
-        ```ts
-        async function searchMemories() {
-            try {
-                const results = await client.search.memories({
-                    q: "what are some applications of quantum computing?",
-                    limit: 3
-                });
-
-                console.log('Search results:', results);
-
-                return results;
-            } catch (error) {
-                console.error('Error searching memories:', error);
-            }
-        }
-        ```
-
-        The output is as follows:
-
-        ```bash
-        Search results: {
-            results: [
-                {
-                    id: 'Bn1uc1yQdw3Huf8oitruwF',
-                    memory: 'Quantum computing applications include cryptography (threatening current encryption standards, enabling quantum-resistant protocols), drug discovery (simulating molecular interactions), and optimization problems (logistics, financial modeling, offering exponential speedups).',
-                    metadata: null,
-                    updatedAt: '2025-08-24T05:41:55.087Z',
-                    version: 1,
-                    rootMemoryId: 'Bn1uc1yQdw3Huf8oitruwF',
-                    similarity: 0.7920647723809932,
-                    context: [Object]
-                },
-                {
-                    id: '4aCa4oM8praVBCWdNksjxf',
-                    memory: 'Quantum computing is a paradigm shift in computational power, leveraging quantum mechanical phenomena like superposition and entanglement to solve problems intractable for classical computers.',
-                    metadata: null,
-                    updatedAt: '2025-08-24T05:41:55.087Z',
-                    version: 1,
-                    rootMemoryId: '4aCa4oM8praVBCWdNksjxf',
-                    similarity: 0.7198909950191389,
-                    context: [Object]
-                },
-                {
-                    id: '8vzhZhBCuqyrLNXtzBDx7y',
-                    memory: 'IBM, Google, and Microsoft have invested billions in quantum computing research.',
-                    metadata: null,
-                    updatedAt: '2025-08-24T05:41:55.087Z',
-                    version: 1,
-                    rootMemoryId: '8vzhZhBCuqyrLNXtzBDx7y',
-                    similarity: 0.6960905375426799,
-                    context: [Object]
-                }
-            ],
-            timing: 216,
-            total: 3
-        }
-        ```
-        As you can see, Supermemory automatically chunked the main memory into smaller parts and returned them. You can visually see that in the graph in the console:
-
-        ![graph view](./images/graph-view.png)
-
-        Now that you’ve made your first request, explore all of Supermemory’s features in detail and how you can use them in your app.
-    </Tab>
-
-    <Tab title="cURL">
-        **Step 2.** The base URL for requests is as follows:
-
-        ```bash
-        https://api.supermemory.ai/
-        ```
-
-        **Step 3.** Set the environment variable:
-
-        ```bash
-        export SUPERMEMORY_API_KEY="your_api_key"
-        ```
-
-        **Step 4.** Add a memory as follows:
-
-        ```bash
-        curl -X POST "https://api.supermemory.ai/v3/documents" \
-          -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-          -H "Content-Type: application/json" \
-          -d '{
-            "content": "Quantum computing represents a paradigm shift in computational power, leveraging quantum mechanical phenomena like superposition and entanglement to solve problems that are intractable for classical computers. The field emerged from theoretical work in the 1980s, when physicist Richard Feynman proposed that quantum systems could simulate other quantum systems more efficiently than classical computers. This insight led to the development of quantum algorithms like Shor'\''s algorithm for factoring large numbers and Grover'\''s algorithm for unstructured search problems. Today, quantum computing applications span multiple domains: in cryptography, quantum computers threaten current encryption standards while enabling new quantum-resistant protocols; in drug discovery, they can simulate molecular interactions with unprecedented accuracy; in optimization problems like logistics and financial modeling, they offer exponential speedups for certain classes of problems. Major tech companies including IBM, Google, and Microsoft have invested billions in quantum computing research, while startups like Rigetti Computing and IonQ focus on specific hardware approaches. The race for quantum advantage - demonstrating a quantum computer solving a problem faster than any classical computer - has become a key milestone in the field. Despite the promise, significant challenges remain: quantum decoherence, error correction, and scaling qubit counts while maintaining coherence. Researchers are exploring various approaches including superconducting qubits, trapped ions, topological qubits, and photonic systems, each with different trade-offs between coherence time, gate fidelity, and scalability.",
-            "containerTag": "quantum-computing",
-            "metadata": {
-              "category": "technology-overview",
-              "topic": "quantum-computing",
-              "complexity": "intermediate",
-              "wordCount": 156
-            }
-          }'
-        ```
-
-        The response is as follows:
-
-        ```json
-        {"id":"D2Ar7Vo7ub83w3PRPZcaP1","status":"queued"}
-        ```
-
-        **Step 5.** Search for this memory using natural language:
-
-        ```bash
-        curl -X POST "https://api.supermemory.ai/v4/search" \
-          -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \
-          -H "Content-Type: application/json" \
-          -d '{
-            "q": "what are some applications of quantum computing?",
-            "limit": 3
-          }'
-        ```
-
-        The result is as follows:
-
-        ```json
-        {
-          "results": [
-            {
-              "id": "Bn1uc1yQdw3Huf8oitruwF",
-              "memory": "Quantum computing applications include cryptography (threatening current encryption standards, enabling quantum-resistant protocols), drug discovery (simulating molecular interactions), and optimization problems (logistics, financial modeling, offering exponential speedups).",
-              "metadata": null,
-              "updatedAt": "2025-08-24T05:41:55.087Z",
-              "version": 1,
-              "rootMemoryId": "Bn1uc1yQdw3Huf8oitruwF",
-              "similarity": 0.7920647723809932,
-              "context": {
-                "parents": [],
-                "children": []
-              }
-            },
-            {
-              "id": "4aCa4oM8praVBCWdNksjxf",
-              "memory": "Quantum computing is a paradigm shift in computational power, leveraging quantum mechanical phenomena like superposition and entanglement to solve problems intractable for classical computers.",
-              "metadata": null,
-              "updatedAt": "2025-08-24T05:41:55.087Z",
-              "version": 1,
-              "rootMemoryId": "4aCa4oM8praVBCWdNksjxf",
-              "similarity": 0.7198909950191389,
-              "context": {
-                "parents": [],
-                "children": []
-              }
-            },
-            {
-              "id": "8vzhZhBCuqyrLNXtzBDx7y",
-              "memory": "IBM, Google, and Microsoft have invested billions in quantum computing research.",
-              "metadata": null,
-              "updatedAt": "2025-08-24T05:41:55.087Z",
-              "version": 1,
-              "rootMemoryId": "8vzhZhBCuqyrLNXtzBDx7y",
-              "similarity": 0.6960905375426799,
-              "context": {
-                "parents": [],
-                "children": []
-              }
-            }
-          ],
-          "timing": 363,
-          "total": 3
-        }
-        ```
-
-        And that's it! Good job!
-
-    </Tab>
-</Tabs>
-
-
-## Memory Router
-Learn how you can add the Memory Router to your existing LLM requests.
-
-The memory router works as a proxy on top of LLM calls. When conversations get very long, it automatically chunks them for optimal performance, retrieves the most relevant information from the history, and balances token usage + cost.
-
-The best part is that it requires no changes to your application logic. Here’s how to get started:
-
-**Step 1.** Sign up for [Supermemory’s Developer Platform](http://console.supermemory.ai) to get the API key. Click on **API Keys -> Create API Key** to generate one.
-
-**Step 2.** Get your LLM provider’s API key
-
-- [OpenAI](https://help.openai.com/en/articles/4936850-where-do-i-find-my-openai-api-key)
-- [Gemini](https://ai.google.dev/gemini-api/docs/api-key)
-- [Anthropic](https://docs.anthropic.com/en/api/admin-api/apikeys/get-api-key)
-- [Groq](https://console.groq.com/keys)
-
-**Step 3.** Append Supermemory’s URL to your LLM provider’s OpenAI-compatible API URL:
-
-<CodeGroup>
+**Step 2.** Install the SDK and set your API key:
 
-```bash OpenAI
-https://api.supermemory.ai/v3/https://api.openai.com/v1/
-```
-```bash Anthropic
-https://api.supermemory.ai/v3/https://api.anthropic.com/v1/
-```
-
-```bash Gemini
-https://api.supermemory.ai/v3/https://generativelanguage.googleapis.com/v1beta/openai/
+<Tabs>
+<Tab title="Python">
+```bash
+pip install supermemory
+export SUPERMEMORY_API_KEY="YOUR_API_KEY"
 ```
-
-```bash Groq
-https://api.supermemory.ai/v3/https://api.groq.com/openai/v1
+</Tab>
+<Tab title="TypeScript">
+```bash
+npm install supermemory
+export SUPERMEMORY_API_KEY="YOUR_API_KEY"
 ```
+</Tab>
+</Tabs>
 
-```bash Others
-https://api.supermemory.ai/v3/[openai-api-url-here]
-```
-</CodeGroup>
+**Step 3.** Here's everything you need to add memory to your LLM:
 
 <Tabs>
-
-
-<Tab title="Typescript">
-    **Step 4.** Install the dependencies
-
-    ```bash
-    npm install openai
-    ```
-
-    **Step 5.** Set two environment variables in your environment: one for Supermemory, and one for your model provider.
-
-    ```bash
-    export SUPERMEMORY_API_KEY=“your_api_key_here”
-
-    # export OPENAI_API_KEY/ANTHROPIC_API_KEY/GEMINI_API_KEY/GROQ_API_KEY=“api_key_here” (based on your model)
-    ```
-
-    **Step 6.** Send a request to the updated endpoint:
-
-    <CodeGroup>
-
-    ```ts OpenAI
-    import OpenAI from 'openai';
-
-    const client = new OpenAI({
-    apiKey: process.env.OPENAI_API_KEY,
-    baseURL: 'https://api.supermemory.ai/v3/https://api.openai.com/v1',
-    defaultHeaders: {
-        'x-supermemory-api-key': process.env.SUPERMEMORY_API_KEY!,
-        'x-sm-user-id': 'user_123' // Your user identifier
-    }
-    });
-
-    async function chatWithOpenAI() {
-    try {
-        const response = await client.chat.completions.create({
-        model: 'gpt-5',
-        messages: [
-            { role: 'user', content: 'Hello my name is Naman. How are you?' }
-        ],
-        max_tokens: 1000,
-        temperature: 0.7
-        });
-
-        console.log('OpenAI Response:', response.choices[0].message.content);
-        return response;
-    } catch (error) {
-        console.error('Error with OpenAI:', error);
-    }
-    }
-
-    ```
-    ```ts Anthropic
-    import OpenAI from 'openai';
-
-    const anthropicClient = new OpenAI({
-    apiKey: process.env.ANTHROPIC_API_KEY,
-    baseURL: 'https://api.supermemory.ai/v3/https://api.anthropic.com/v1',
-    defaultHeaders: {
-        'x-supermemory-api-key': process.env.SUPERMEMORY_API_KEY!,
-        'x-sm-user-id': 'user_123'
-    }
-    });
-
-    async function chatWithClaude() {
-    try {
-        const response = await anthropicClient.chat.completions.create({
-        model: 'claude-3-sonnet-20240229',
-        messages: [
-            { role: 'user', content: 'Hello my name is Naman. How are you?' }
-        ],
-        max_tokens: 1000
-        });
-
-        console.log('Claude Response:', response.choices[0].message.content);
-        return response;
-    } catch (error) {
-        console.error('Error with Claude:', error);
-    }
-    }
-    ```
-
-    ```ts Gemini
-
-    import OpenAI from 'openai';
-
-    const geminiClient = new OpenAI({
-    apiKey: process.env.GEMINI_API_KEY,
-    baseURL: 'https://api.supermemory.ai/v3/https://generativelanguage.googleapis.com/v1beta',
-    defaultHeaders: {
-        'x-supermemory-api-key': process.env.SUPERMEMORY_API_KEY!,
-        'x-sm-user-id': 'user_123'
-    }
-    });
-
-    async function chatWithGemini() {
-    try {
-        const response = await geminiClient.chat.completions.create({
-        model: 'gemini-pro',
-        messages: [
-            { role: 'user', content: 'Hello my name is Naman. How are you?' }
-        ],
-        max_tokens: 1000
-        });
-
-        console.log('Gemini Response:', response.choices[0].message.content);
-        return response;
-    } catch (error) {
-        console.error('Error with Gemini:', error);
-    }
-    }
-
-    ```
-
-    ```ts Groq
-
-    import OpenAI from 'openai';
-
-    const groqClient = new OpenAI({
-    apiKey: process.env.GROQ_API_KEY,
-    baseURL: 'https://api.supermemory.ai/v3/https://api.groq.com/openai/v1',
-    defaultHeaders: {
-        'x-supermemory-api-key': process.env.SUPERMEMORY_API_KEY!,
-        'x-sm-user-id': 'user_123'
-    }
-    });
-
-    async function chatWithGroq() {
-    try {
-        const response = await groqClient.chat.completions.create({
-        model: 'mixtral-8x7b-32768',
-        messages: [
-            { role: 'user', content: 'Hello my name is Naman. How are you?' }
-        ],
-        max_tokens: 1000
-        });
-
-        console.log('Groq Response:', response.choices[0].message.content);
-        return response;
-    } catch (error) {
-        console.error('Error with Groq:', error);
-    }
-    }
-
-
-    ```
-
-    </CodeGroup>
-
-    Each of these code snippets changes the Base URL based on the OpenAI-compatible API URL given by the model providers. Some of the key parameters to note are:
-
-    - `apiKey`: Your model provider’s API key
-    - `x-supermemory-api-key`: Your Supermemory API key
-    - `x-sm-user-id`: Scope conversations by user with a user ID. This will enable cross-conversation memory, meaning users can reference other chats and draw information from them.
-
-    Additionally, while not shown in this quickstart, you can also pass an `x-sm-conversation-id` header.
-
-    Then, you won’t have to send the entire array of messages to the LLM as conversation history. Supermemory will handle it.
-
-    If you run the above code blocks, you’ll get an output from your LLM like this:
-
-    ```
-    “Hello, Naman! I'm just a computer program, so I don't have feelings, but I'm here and ready to help you. How can I assist you today?”
-    ```
-
-    After that, if you modify the request to ask, ‘What is my name?’ instead, you’ll get the following response:
-
-    ```
-    Your name is Naman.
-    ```
-
-    Thus, the memory router is working!
-</Tab>
-
 <Tab title="Python">
-        **Step 4.** Install the Python dependency:
-
-        ```
-        pip install openai
-        ```
-
-        **Step 5.** Set two environment variables in your environment: one for Supermemory and one for your model provider.
-
-        ```bash
-        export SUPERMEMORY_API_KEY=“your_api_key_here”
-
-        # export OPENAI_API_KEY/ANTHROPIC_API_KEY/GEMINI_API_KEY/GROQ_API_KEY=“api_key_here” (based on your model)
-        ```
-
-        **Step 6.** Send a request to the LLM with the updated base URL and parameters:
-
-        <CodeGroup>
-
-        ```python OpenAI
-        import os
-        from openai import OpenAI
-
-        client = OpenAI(
-            api_key=os.getenv("OPENAI_API_KEY"),
-            base_url="https://api.supermemory.ai/v3/https://api.openai.com/v1",
-            default_headers={
-                "x-supermemory-api-key": os.getenv("SUPERMEMORY_API_KEY"),
-                "x-sm-user-id": "user_123"
-            }
-        )
-
-        def chat_with_openai():
-            try:
-                response = client.chat.completions.create(
-                    model="gpt-5",
-                    messages=[
-                        {"role": "user", "content": "Hello my name is Naman. How are you?"}
-                    ],
-                    max_tokens=1000,
-                    temperature=0.7
-                )
-
-                print("OpenAI Response:", response.choices[0].message.content)
-                return response
-            except Exception as error:
-                print(f"Error with OpenAI: {error}")
-
-        ```
-        ```python Anthropic
-        from openai import OpenAI
-
-        anthropic_client = OpenAI(
-            api_key=os.getenv("ANTHROPIC_API_KEY"),
-            base_url="https://api.supermemory.ai/v3/https://api.anthropic.com/v1",
-            default_headers={
-                "x-supermemory-api-key": os.getenv("SUPERMEMORY_API_KEY"),
-                "x-sm-user-id": "user_123"
-            }
-        )
-
-        def chat_with_claude():
-            try:
-                response = anthropic_client.chat.completions.create(
-                    model="claude-3-sonnet-20240229",
-                    messages=[
-                        {"role": "user", "content": "Hello my name is Naman. How are you?"}
-                    ],
-                    max_tokens=1000
-                )
+```python
+from supermemory import Supermemory
 
-                print("Claude Response:", response.choices[0].message.content)
-                return response
-            except Exception as error:
-                print(f"Error with Claude: {error}")
+client = Supermemory()
+USER_ID = "dhravya"
 
-        ```
+conversation = [
+    {"role": "assistant", "content": "Hello, how are you doing?"},
+    {"role": "user", "content": "Hello! I am Dhravya. I am 20 years old. I love to code!"},
+    {"role": "user", "content": "Can I go to the club?"},
+]
 
-        ```python Gemini
-        from openai import OpenAI
+# Get user profile + relevant memories for context
+profile = client.profile(container_tag=USER_ID, q=conversation[-1]["content"])
 
-        gemini_client = OpenAI(
-            api_key=os.getenv("GEMINI_API_KEY"),
-            base_url="https://api.supermemory.ai/v3/https://generativelanguage.googleapis.com/v1beta",
-            default_headers={
-                "x-supermemory-api-key": os.getenv("SUPERMEMORY_API_KEY"),
-                "x-sm-user-id": "user_123"
-            }
-        )
+context = f"""Static profile:
+{"\n".join(profile.profile.static)}
 
-        def chat_with_gemini():
-            try:
-                response = gemini_client.chat.completions.create(
-                    model="gemini-pro",
-                    messages=[
-                        {"role": "user", "content": "Hello my name is Naman. How are you?"}
-                    ],
-                    max_tokens=1000
-                )
+Dynamic profile:
+{"\n".join(profile.profile.dynamic)}
 
-                print("Gemini Response:", response.choices[0].message.content)
-                return response
-            except Exception as error:
-                print(f"Error with Gemini: {error}")
-        ```
+Relevant memories:
+{"\n".join(r.content for r in profile.search_results.results)}"""
 
-        ```python Groq
-        from openai import OpenAI
+# Build messages with memory-enriched context
+messages = [{"role": "system", "content": f"User context:\n{context}"}, *conversation]
 
-        groq_client = OpenAI(
-            api_key=os.getenv("GROQ_API_KEY"),
-            base_url="https://api.supermemory.ai/v3/https://api.groq.com/openai/v1",
-            default_headers={
-                "x-supermemory-api-key": os.getenv("SUPERMEMORY_API_KEY"),
-                "x-sm-user-id": "user_123"
-            }
-        )
+# response = llm.chat(messages=messages)
 
-        def chat_with_groq():
-            try:
-                response = groq_client.chat.completions.create(
-                    model="mixtral-8x7b-32768",
-                    messages=[
-                        {"role": "user", "content": "Hello my name is Naman. How are you?"}
-                    ],
-                    max_tokens=1000
-                )
-
-                print("Groq Response:", response.choices[0].message.content)
-                return response
-            except Exception as error:
-                print(f"Error with Groq: {error}")
-        ```
-
-        </CodeGroup>
-
-        Each of these code snippets changes the Base URL based on the OpenAI-compatible API URL given by the model providers. Some of the key parameters to note are:
-
-        - `api_key`: Your model provider’s API key
-        - `x-supermemory-api-key`: Your Supermemory API key
-        - `x-sm-user-id`: Scope conversations by user with a user ID. This will enable cross-conversation memory, meaning users can reference other chats and draw information from them.
-
-        Additionally, while not shown in this quickstart, you can also pass an `x-sm-conversation-id` header.
-
-        Then, you won’t have to send the entire array of messages to the LLM as conversation history. Supermemory will handle it.
-
-        If you run the above code blocks, you’ll get an output from your LLM like this:
-
-        ```
-        “Hello, Naman! I'm just a computer program, so I don't have feelings, but I'm here and ready to help you. How can I assist you today?”
-        ```
-
-        After that, if you modify the request to ask, ‘What is my name?’ instead, you’ll get the following response:
-
-        ```
-        Your name is Naman.
-        ```
-
-        Thus, the memory router is working!
-    </Tab>
-    <Tab title="cURL">
-        **Step 4.** Set the environment variables:
-
-        ```bash
-        export SUPERMEMORY_API_KEY="your_supermemory_api_key"
-        export OPENAI_API_KEY="your_openai_api_key"
-        export ANTHROPIC_API_KEY="your_anthropic_api_key"
-        export GEMINI_API_KEY="your_gemini_api_key"
-        export GROQ_API_KEY="your_groq_api_key"
-        ```
-
-        **Step 5.** Send a request to the LLM with the updated base URL and parameters:
-
-        <CodeGroup>
-        ```bash OpenAI
-        curl https://api.supermemory.ai/v3/https://api.openai.com/v1/chat/completions \
-        -H "Content-Type: application/json" \
-        -H "Authorization: Bearer $OPENAI_API_KEY" \
-        -H "x-supermemory-api-key: $SUPERMEMORY_API_KEY" \
-        -H "x-sm-user-id: user_123" \
-        -d '{
-            "model": "gpt-5",
-            "messages": [
-            {"role": "user", "content": "Hello my name is Naman. How are you?"}
-            ],
-            "max_tokens": 1000,
-            "temperature": 0.7
-        }'
-        ```
-
-        ```bash Claude
-        curl https://api.supermemory.ai/v3/https://api.anthropic.com/v1/messages \
-        -H "Content-Type: application/json" \
-        -H "Authorization: Bearer $ANTHROPIC_API_KEY" \
-        -H "x-supermemory-api-key: $SUPERMEMORY_API_KEY" \
-        -H "x-sm-user-id: user_123" \
-        -d '{
-            "model": "claude-3-sonnet-20240229",
-            "messages": [
-            {"role": "user", "content": "Hello my name is Naman. How are you?"}
-            ],
-            "max_tokens": 1000
-        }'
-        ```
-
-        ```bash Gemini
-        curl https://api.supermemory.ai/v3/https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent \
-        -H "Content-Type: application/json" \
-        -H "Authorization: Bearer $GEMINI_API_KEY" \
-        -H "x-supermemory-api-key: $SUPERMEMORY_API_KEY" \
-        -H "x-sm-user-id: user_123" \
-        -d '{
-            "contents": [
-            {
-                "parts": [
-                {"text": "Hello my name is Naman. How are you?"}
-                ]
-            }
-            ],
-            "generationConfig": {
-            "maxOutputTokens": 1000
-            }
-        }'
-        ```
-
-        ```bash Groq
-        curl https://api.supermemory.ai/v3/https://api.groq.com/openai/v1/chat/completions \
-        -H "Content-Type: application/json" \
-        -H "Authorization: Bearer $GROQ_API_KEY" \
-        -H "x-supermemory-api-key: $SUPERMEMORY_API_KEY" \
-        -H "x-sm-user-id: user_123" \
-        -d '{
-            "model": "mixtral-8x7b-32768",
-            "messages": [
-            {"role": "user", "content": "Hello my name is Naman. How are you?"}
-            ],
-            "max_tokens": 1000
-        }'
-        ```
-        </CodeGroup>
+# Store conversation for future context
+client.add(
+    content="\n".join(f"{m['role']}: {m['content']}" for m in conversation),
+    container_tag=USER_ID,
+)
+```
+</Tab>
+<Tab title="TypeScript">
+```typescript
+import Supermemory from "supermemory";
 
-        Each of these code snippets changes the Base URL based on the OpenAI-compatible API URL given by the model providers. Some of the key parameters to note are:
+const client = new Supermemory();
+const USER_ID = "dhravya";
 
-        - **Authorization header**: Your model provider’s API key
-        - `x-supermemory-api-key`: Your Supermemory API key
-        - `x-sm-user-id`: Scope conversations by user with a user ID. This will enable cross-conversation memory, meaning users can reference other chats and draw information from them.
+const conversation = [
+  { role: "assistant", content: "Hello, how are you doing?" },
+  { role: "user", content: "Hello! I am Dhravya. I am 20 years old. I love to code!" },
+  { role: "user", content: "Can I go to the club?" },
+];
 
-        Additionally, while not shown in this quickstart, you can also pass an `x-sm-conversation-id` header.
+// Get user profile + relevant memories for context
+const profile = await client.profile({
+  containerTag: USER_ID,
+  q: conversation.at(-1)!.content,
+});
 
-        Then, you won’t have to send the entire array of messages to the LLM as conversation history. Supermemory will handle it.
+const context = `Static profile:
+${profile.profile.static.join("\n")}
 
-        If you run the above code blocks, you’ll get an output from your LLM like this:
+Dynamic profile:
+${profile.profile.dynamic.join("\n")}
 
-        ```
-        “Hello, Naman! I'm just a computer program, so I don't have feelings, but I'm here and ready to help you. How can I assist you today?”
-        ```
+Relevant memories:
+${profile.searchResults.results.map((r) => r.content).join("\n")}`;
 
-        After that, if you modify the request to ask, ‘What is my name?’ instead, you’ll get the following response:
+// Build messages with memory-enriched context
+const messages = [{ role: "system", content: `User context:\n${context}` }, ...conversation];
 
-        ```
-        Your name is Naman.
-        ```
+// const response = await llm.chat({ messages });
 
-        Thus, the memory router is working!
-    </Tab>
+// Store conversation for future context
+await client.memories.add({
+  content: conversation.map((m) => `${m.role}: ${m.content}`).join("\n"),
+  containerTag: USER_ID,
+});
+```
+</Tab>
 </Tabs>
 
+That's it! Supermemory automatically:
+- Extracts memories from conversations
+- Builds and maintains user profiles (static facts + dynamic context)
+- Returns relevant context for personalized LLM responses
 
-For additional reference, here are links to the model providers’ documentation:
-- [OpenAI API Reference](https://platform.openai.com/docs/api-reference)
-- [Anthropic Claude API](https://docs.anthropic.com/claude/reference)
-- [Google Gemini API](https://ai.google.dev/docs)
-- [Groq API Documentation](https://console.groq.com/docs)
+Learn more about [User Profiles](/user-profiles) and [Search](/search/overview).
diff --git a/apps/docs/routervsapi.mdx b/apps/docs/routervsapi.mdx
deleted file mode 100644
index 94d44f3e..00000000
--- a/apps/docs/routervsapi.mdx
+++ /dev/null
@@ -1,63 +0,0 @@
----
-title: "Memory API vs Router — Which one should I use?"
-sidebarTitle: "Memory API vs Router"
-description: "Two ways to add long-term memory to your LLMs. Same engine under the hood. Choose speed (Router) or control (Memory API), or use both together."
----
-
-<Tip>
-### <strong>TL;DR</strong>
-- <strong>Memory API:</strong> You ingest/search/filter memories yourself and decide exactly what goes into the prompt. Maximum control for production apps and custom retrieval. <br/>
-- <strong>Memory Router:</strong> Keep your existing LLM client and just point it at Supermemory. We automatically fetch relevant memories and append them to your prompt. <br />
-
-Both use the same memory engine underneath, and share a common key (`user_id`). Thus, anything you store via the API is available to the Router, and vice versa, as long as the `user_id` matches.
-</Tip>
-
-We’ll first explain how the Router works, because the API is quite straightforward.
-
-![](./images/infinite-context.png)
-
-You send a request to your LLM, and Supermemory acts as a proxy. The Router will automatically remove unnecessary context from the message, search the user’s memories for additional relevant context, append it to the prompt, and send it to the LLM. 
-
-It also writes new memories asynchronously, so your context keeps expanding without any blockages. The Router is specifically built for conversational memory in chat applications, and its utility shows when your conversations get very long.
-
-For you, it leads to:
-
-- No code refactoring - just swap the base URL with one provided by Supermemory. Read the quickstart to learn more.
-- Better chatbot performance due to long-thread retrieval, when conversations go beyond the model window.
-- Cost savings due to our automatic chunking and context management.
-
-The API, on the other hand, is a full-fledged API you can call in your app to ingest documents, create memories, search them, rerank, etc., with very granular control. The Router is built on top of our API.
-
-Technically, you could build your own Memory Router too on top of our API, but it wouldn’t come with the same one-line integration, ease of use, minimal latency, and intelligent token budgeting.
-
-Again, both use the same memory engine underneath the hood, so your memories are available across both products.
-
-Here’s a quick 30-second flow to decide which one to use for your specific use case:
-
-- <strong> Already have a working LLM chat and just want it to remember? </strong> Start with the Router.
-
-
-- <strong> Building a new app or need strict tenancy, filters, ranking, or custom prompts? </strong> Go to the Memory API.
-
-
-- <strong> Need both? </strong> Ingest via API, chat via Router; keep the user_id consistent.
-
-
-- <strong> Still unsure? </strong> Pilot on the Router, then graduate parts of the flow to the API as you need more control.
-
-Now, head over to the quickstart to integrate the API/Router in your app within 5 minutes.
-
-## FAQs
-
-<AccordionGroup>
-  <Accordion title="Is the Router just calling the Memory API behind the scenes?">
-    Conceptually, yes. The Router orchestrates the same Supermemory engine operations (retrieve, re-rank, budget, cite) and wraps them around your model call.
-  </Accordion>
-  <Accordion title="Does the Router store new memories automatically?">
-    It can. The create-memory step is asynchronous, so the user’s response isn’t delayed.
-  </Accordion>
-  <Accordion title="What identifies the user’s memory across Router and API?">
-    <code>user_id</code>. Keep it consistent across Router and API calls to share the same memory pool.
-  </Accordion>
-</AccordionGroup>
-
diff --git a/apps/docs/test.py b/apps/docs/test.py
new file mode 100644
index 00000000..ee5309d6
--- /dev/null
+++ b/apps/docs/test.py
@@ -0,0 +1,33 @@
+from supermemory import Supermemory
+
+client = Supermemory()
+USER_ID = "dhravya"
+
+conversation = [
+    {"role": "assistant", "content": "Hello, how are you doing?"},
+    {"role": "user", "content": "Hello! I am Dhravya. I am 20 years old. I love to code!"},
+    {"role": "user", "content": "Can I go to the club?"},
+]
+
+# Get user profile + relevant memories for context
+profile = client.profile(container_tag=USER_ID, q=conversation[-1]["content"])
+
+context = f"""Static profile:
+{ "\n".join(profile.profile.static)}
+
+Dynamic profile:
+{"\n".join(profile.profile.dynamic)}
+
+Relevant memories:
+{"\n".join(r.content for r in profile.search_results.results)}"""
+
+# Build messages with memory-enriched context
+messages = [{"role": "system", "content": f"User context:\n{context}"}, *conversation]
+
+# response = llm.chat(messages=messages)
+
+# Store conversation for future context
+client.add(
+    content="\n".join(f"{m['role']}: {m['content']}" for m in conversation),
+    container_tag=USER_ID,
+)
diff --git a/apps/docs/test.ts b/apps/docs/test.ts
new file mode 100644
index 00000000..21c8bb8e
--- /dev/null
+++ b/apps/docs/test.ts
@@ -0,0 +1,42 @@
+import Supermemory from "supermemory"
+
+const client = new Supermemory()
+const USER_ID = "dhravya"
+
+const conversation = [
+	{ role: "assistant", content: "Hello, how are you doing?" },
+	{
+		role: "user",
+		content: "Hello! I am Dhravya. I am 20 years old. I love to code!",
+	},
+	{ role: "user", content: "Can I go to the club?" },
+]
+
+// Get user profile + relevant memories for context
+const profile = await client.profile({
+	containerTag: USER_ID,
+	q: conversation.at(-1)!.content,
+})
+
+const context = `Static profile:
+${profile.profile.static.join("\n")}
+
+Dynamic profile:
+${profile.profile.dynamic.join("\n")}
+
+Relevant memories:
+${profile.searchResults?.results.map((r) => r["content"]).join("\n")}`
+
+// Build messages with memory-enriched context
+const messages = [
+	{ role: "system", content: `User context:\n${context}` },
+	...conversation,
+]
+
+// const response = await llm.chat({ messages });
+
+// Store conversation for future context
+await client.add({
+	content: conversation.map((m) => `${m.role}: ${m.content}`).join("\n"),
+	containerTag: USER_ID,
+})
diff --git a/apps/docs/user-profiles.mdx b/apps/docs/user-profiles.mdx
deleted file mode 100644
index c6a097ec..00000000
--- a/apps/docs/user-profiles.mdx
+++ /dev/null
@@ -1,570 +0,0 @@
----
-title: "User Profiles - Persistent Context for LLMs"
-description: "Automatically maintained user profiles that provide instant, comprehensive context to your LLMs"
-sidebarTitle: "User Profiles"
-icon: "user"
----
-
-## What are User Profiles?
-
-User profiles are **automatically maintained collections of facts about your users** that Supermemory builds from all their interactions and content. Think of it as a persistent "about me" document that's always up-to-date and instantly accessible.
-
-Instead of searching through memories every time you need context about a user, profiles give you:
-- **Instant access** to comprehensive user information
-- **Automatic updates** as users interact with your system
-- **Two-tier structure** separating permanent facts from temporary context
-
-<Note>
-  Profile data can be appended to the system prompt so that it's always sent to your LLM and you don't need to run multiple queries.
-</Note>
-
-## Static vs Dynamic Profiles
-
-![](/images/static-dynamic-profile.png)
-
-Profiles are intelligently divided into two categories:
-
-### Static Profile
-**Long-term, stable facts that define who the user is**
-
-These are facts that rarely change - the foundational information about a user that remains consistent over time.
-
-Examples:
-- "Sarah Chen is a senior software engineer at TechCorp"
-- "Sarah specializes in distributed systems and Kubernetes"
-- "Sarah has a PhD in Computer Science from MIT"
-- "Sarah prefers technical documentation over video tutorials"
-
-### Dynamic Profile
-**Recent context and temporary information**
-
-These are current activities, recent interests, and temporary states that provide immediate context.
-
-Examples:
-- "Sarah is currently migrating the payment service to microservices"
-- "Sarah recently started learning Rust for a side project"
-- "Sarah is preparing for a conference talk next month"
-- "Sarah is debugging a memory leak in the authentication service"
-
-<Accordion title="How are profiles different from search?" defaultOpen>
-  **Traditional Search**: You query "What does Sarah know about Kubernetes?" and get specific memory chunks about Kubernetes.
-  
-  **User Profiles**: You get Sarah's complete professional context instantly - her role, expertise, preferences, and current projects - without needing to craft specific queries.
-  
-  The profile is **always there**, providing consistent personalization across every interaction.
-</Accordion>
-
-## Why We Built Profiles
-
-### The Problem with Search-Only Approaches
-
-Traditional memory systems rely entirely on search, which has fundamental limitations:
-
-1. **Search is too narrow**: When you search for "project updates", you miss that the user prefers bullet points, works in PST timezone, and uses specific technical terminology.
-
-2. **Search is repetitive**: Every chat message triggers multiple searches for basic context that rarely changes.
-
-3. **Search misses relationships**: Individual memory chunks don't capture the full picture of who someone is and how different facts relate.
-
-
-Profiles solve these problems by maintaining a **persistent, holistic view** of each user:
-## How Profiles Work with Search
-
-Profiles don't replace search - they complement it perfectly:
-
-<Steps>
-  <Step title="Profile provides foundation">
-    The user's profile gives your LLM comprehensive background context about who they are, what they know, and what they're working on.
-  </Step>
-  
-  <Step title="Search adds specificity">
-    When you need specific information (like "error in deployment yesterday"), search finds those exact memories.
-  </Step>
-  
-  <Step title="Combined for perfect context">
-    Your LLM gets both the broad understanding from profiles AND the specific details from search.
-  </Step>
-</Steps>
-
-### Real-World Example
-
-Imagine a user asks: **"Can you help me debug this?"**
-
-**Without profiles**: The LLM has no context about the user's expertise level, current projects, or debugging preferences.
-
-**With profiles**: The LLM knows:
-- The user is a senior engineer (adjust technical level)
-- They're working on a payment service migration (likely context)
-- They prefer command-line tools over GUIs (tool suggestions)
-- They recently had issues with memory leaks (possible connection)
-
-## Technical Implementation
-
-### Endpoint Details
-
-Based on the [API reference](https://api.supermemory.ai/v3/reference#tag/profile), the profile endpoint provides a simple interface:
-
-**Endpoint**: `POST /v4/profile`
-
-### Request Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `containerTag` | string | **Yes** | The container tag (usually user ID) to get profiles for |
-| `q` | string | No | Optional search query to include search results with the profile |
-
-### Response Structure
-
-The response includes both profile data and optional search results:
-
-```json
-{
-  "profile": {
-    "static": [
-      "User is a software engineer",
-      "User specializes in Python and React"
-    ],
-    "dynamic": [
-      "User is working on Project Alpha",
-      "User recently started learning Rust"
-    ]
-  },
-  "searchResults": {
-    "results": [...],  // Only if 'q' parameter was provided
-    "total": 15,
-    "timing": 45.2
-  }
-}
-```
-
-## Code Examples
-
-### Basic Profile Retrieval
-
-<CodeGroup>
-
-```typescript TypeScript
-// Direct API call using fetch
-const response = await fetch('https://api.supermemory.ai/v4/profile', {
-  method: 'POST',
-  headers: {
-    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    containerTag: 'user_123'
-  })
-});
-
-const data = await response.json();
-
-console.log("Static facts:", data.profile.static);
-console.log("Dynamic context:", data.profile.dynamic);
-
-// Use in your LLM prompt
-const systemPrompt = `
-User Context:
-${data.profile.static?.join('\n') || ''}
-
-Current Activity:
-${data.profile.dynamic?.join('\n') || ''}
-
-Please provide personalized assistance based on this context.
-`;
-```
-
-```python Python
-import requests
-import os
-
-# Direct API call
-response = requests.post(
-    'https://api.supermemory.ai/v4/profile',
-    headers={
-        'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
-        'Content-Type': 'application/json'
-    },
-    json={
-        'containerTag': 'user_123'
-    }
-)
-
-data = response.json()
-
-print("Static facts:", data['profile']['static'])
-print("Dynamic context:", data['profile']['dynamic'])
-
-# Use in your LLM prompt
-static_context = '\n'.join(data['profile'].get('static', []))
-dynamic_context = '\n'.join(data['profile'].get('dynamic', []))
-
-system_prompt = f"""
-User Context:
-{static_context}
-
-Current Activity:
-{dynamic_context}
-
-Please provide personalized assistance based on this context.
-"""
-```
-
-```bash cURL
-curl -X POST https://api.supermemory.ai/v4/profile \
-  -H "Authorization: Bearer YOUR_API_KEY" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "containerTag": "user_123"
-  }'
-```
-
-</CodeGroup>
-
-### Profile with Search
-
-Sometimes you want both the user's profile AND specific search results:
-
-<CodeGroup>
-
-```typescript TypeScript
-// Get profile with search results
-const response = await fetch('https://api.supermemory.ai/v4/profile', {
-  method: 'POST',
-  headers: {
-    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
-    'Content-Type': 'application/json'
-  },
-  body: JSON.stringify({
-    containerTag: 'user_123',
-    q: 'deployment errors yesterday'  // Optional search query
-  })
-});
-
-const data = await response.json();
-
-// Now you have both profile and specific search results
-const profile = data.profile;
-const searchResults = data.searchResults?.results || [];
-
-// Combine for comprehensive context
-const context = {
-  userBackground: profile.static,
-  currentContext: profile.dynamic,
-  specificInfo: searchResults.map(r => r.content)
-};
-```
-
-```python Python
-import requests
-
-# Get profile with search results
-response = requests.post(
-    'https://api.supermemory.ai/v4/profile',
-    headers={
-        'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
-        'Content-Type': 'application/json'
-    },
-    json={
-        'containerTag': 'user_123',
-        'q': 'deployment errors yesterday'  # Optional search query
-    }
-)
-
-data = response.json()
-
-# Access both profile and search results
-profile = data['profile']
-search_results = data.get('searchResults', {}).get('results', [])
-
-# Combine for comprehensive context
-context = {
-    'user_background': profile.get('static', []),
-    'current_context': profile.get('dynamic', []),
-    'specific_info': [r['content'] for r in search_results]
-}
-```
-
-</CodeGroup>
-
-### Integration with Chat Applications
-
-Here's how to use profiles in a real chat application:
-
-<CodeGroup>
-
-```typescript TypeScript
-async function handleChatMessage(userId: string, message: string) {
-  // Get user profile for personalization
-  const profileResponse = await fetch('https://api.supermemory.ai/v4/profile', {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify({
-      containerTag: userId
-    })
-  });
-  
-  const profileData = await profileResponse.json();
-
-  // Build personalized system prompt
-  const systemPrompt = buildPersonalizedPrompt(profileData.profile);
-
-  // Send to your LLM with context
-  const response = await llm.chat({
-    messages: [
-      { role: "system", content: systemPrompt },
-      { role: "user", content: message }
-    ]
-  });
-
-  return response;
-}
-
-function buildPersonalizedPrompt(profile: any) {
-  return `You are assisting a user with the following context:
-
-ABOUT THE USER:
-${profile.static?.join('\n') || 'No profile information yet.'}
-
-CURRENT CONTEXT:
-${profile.dynamic?.join('\n') || 'No recent activity.'}
-
-Provide responses that are personalized to their expertise level, 
-preferences, and current work context.`;
-}
-```
-
-```python Python
-import requests
-import os
-
-async def handle_chat_message(user_id: str, message: str):
-    # Get user profile for personalization
-    response = requests.post(
-        'https://api.supermemory.ai/v4/profile',
-        headers={
-            'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
-            'Content-Type': 'application/json'
-        },
-        json={'containerTag': user_id}
-    )
-    
-    profile_data = response.json()
-    
-    # Build personalized system prompt
-    system_prompt = build_personalized_prompt(profile_data['profile'])
-    
-    # Send to your LLM with context
-    llm_response = await llm.chat(
-        messages=[
-            {"role": "system", "content": system_prompt},
-            {"role": "user", "content": message}
-        ]
-    )
-    
-    return llm_response
-
-def build_personalized_prompt(profile):
-    static_facts = '\n'.join(profile.get('static', ['No profile information yet.']))
-    dynamic_context = '\n'.join(profile.get('dynamic', ['No recent activity.']))
-    
-    return f"""You are assisting a user with the following context:
-
-ABOUT THE USER:
-{static_facts}
-
-CURRENT CONTEXT:
-{dynamic_context}
-
-Provide responses that are personalized to their expertise level, 
-preferences, and current work context."""
-```
-
-</CodeGroup>
-
-## AI SDK Integration
-
-<Note>
-  The Supermemory AI SDK provides a more elegant way to use profiles through the `withSupermemory` middleware, which automatically handles profile retrieval and injection into your LLM prompts.
-</Note>
-
-### Automatic Profile Integration
-
-The AI SDK's `withSupermemory` middleware abstracts away all the profile endpoint complexity:
-
-```typescript
-import { generateText } from "ai"
-import { withSupermemory } from "@supermemory/tools/ai-sdk"
-import { openai } from "@ai-sdk/openai"
-
-// Automatically injects user profile into every LLM call
-const modelWithMemory = withSupermemory(openai("gpt-4"), "user_123")
-
-const result = await generateText({
-  model: modelWithMemory,
-  messages: [{ role: "user", content: "What do you know about me?" }],
-})
-
-// The model automatically has access to the user's profile!
-```
-
-### Memory Search Modes
-
-The AI SDK supports three modes for memory retrieval:
-
-#### Profile Mode (Default)
-Retrieves user profile memories without query filtering:
-
-```typescript
-import { generateText } from "ai"
-import { withSupermemory } from "@supermemory/tools/ai-sdk"
-import { openai } from "@ai-sdk/openai"
-
-// Uses profile mode by default - gets all user profile memories
-const modelWithMemory = withSupermemory(openai("gpt-4"), "user-123")
-
-// Explicitly specify profile mode
-const modelWithProfile = withSupermemory(openai("gpt-4"), "user-123", { 
-  mode: "profile" 
-})
-
-const result = await generateText({
-  model: modelWithMemory,
-  messages: [{ role: "user", content: "What do you know about me?" }],
-})
-```
-
-#### Query Mode
-Searches memories based on the user's message:
-
-```typescript
-import { generateText } from "ai"
-import { withSupermemory } from "@supermemory/tools/ai-sdk"
-import { openai } from "@ai-sdk/openai"
-
-const modelWithQuery = withSupermemory(openai("gpt-4"), "user-123", { 
-  mode: "query" 
-})
-
-const result = await generateText({
-  model: modelWithQuery,
-  messages: [{ role: "user", content: "What's my favorite programming language?" }],
-})
-```
-
-#### Full Mode
-Combines both profile and query results:
-
-```typescript
-import { generateText } from "ai"
-import { withSupermemory } from "@supermemory/tools/ai-sdk"
-import { openai } from "@ai-sdk/openai"
-
-const modelWithFull = withSupermemory(openai("gpt-4"), "user-123", { 
-  mode: "full" 
-})
-
-const result = await generateText({
-  model: modelWithFull,
-  messages: [{ role: "user", content: "Tell me about my preferences" }],
-})
-```
-
-<Card title="Learn More About AI SDK" icon="triangle" href="/ai-sdk/overview">
-  Explore the full capabilities of the Supermemory AI SDK, including tools for adding memories, searching, and automatic profile injection.
-</Card>
-
-### Understanding the Modes (Without AI SDK)
-
-When using the API directly without the AI SDK:
-
-- **Profile Only**: Call `/v4/profile` and add the profile data to your system prompt. This gives persistent user context without query-specific search.
-
-- **Query Only**: Use the `/v4/search` endpoint with the user's specific question to find relevant memories based on their current query. Read [the search docs.](/search/overview)
-
-- **Full Mode**: Combine both approaches - add profile data to the system prompt AND use the search endpoint for conversational context based on the user's specific query. This provides the most comprehensive context.
-
-```typescript
-// Full mode example without AI SDK
-async function getFullContext(userId: string, userQuery: string) {
-  // 1. Get user profile for system prompt
-  const profileResponse = await fetch('https://api.supermemory.ai/v4/profile', {
-    method: 'POST',
-    headers: { /* ... */ },
-    body: JSON.stringify({ containerTag: userId })
-  });
-  const profileData = await profileResponse.json();
-  
-  // 2. Search for query-specific memories
-  const searchResponse = await fetch('https://api.supermemory.ai/v3/search', {
-    method: 'POST',
-    headers: { /* ... */ },
-    body: JSON.stringify({ 
-      q: userQuery,
-      containerTag: userId 
-    })
-  });
-  const searchData = await searchResponse.json();
-  
-  // 3. Combine both in your prompt
-  return {
-    systemPrompt: `User Profile:\n${profileData.profile.static?.join('\n')}`,
-    queryContext: searchData.results
-  };
-}
-```
-Or you can also juse use the `q` parameter in the `v4/profiles` endpoint to get those search results. I just wanted to demonstrate how you can use search and profile separately, so I put this elaborate code snippet.
-
-## How Profiles are Built
-
-Profiles are **automatically constructed and maintained** through Supermemory's ingestion pipeline:
-
-<Steps>
-  <Step title="Content Ingestion">
-    When users add documents, chat, or any content to Supermemory, it goes through the standard ingestion workflow.
-  </Step>
-  
-  <Step title="Intelligence Extraction">
-    AI analyzes the content to extract not just memories, but also facts about the user themselves.
-  </Step>
-  
-  <Step title="Profile Operations">
-    The system generates profile operations (add, update, or remove facts) based on the new information.
-  </Step>
-  
-  <Step title="Automatic Updates">
-    Profiles are updated in real-time, ensuring they always reflect the latest information about the user.
-  </Step>
-</Steps>
-
-<Note>
-  You don't need to manually manage profiles - they're automatically maintained as users interact with your system. Just ingest content normally, and profiles build themselves.
-</Note>
-
-
-## Common Use Cases
-
-### Personalized AI Assistants
-Profiles ensure your AI assistant remembers user preferences, expertise, and context across conversations.
-
-### Customer Support Systems
-Support agents (or AI) instantly see customer history, preferences, and current issues without manual searches.
-
-### Educational Platforms
-Adapt content difficulty and teaching style based on the learner's profile and progress.
-
-### Development Tools
-IDE assistants that understand your coding style, current projects, and technical preferences.
-
-## Performance Benefits
-
-Profiles provide significant performance improvements:
-
-| Metric | Without Profiles | With Profiles |
-|--------|-----------------|---------------|
-| Context Retrieval | 3-5 search queries | 1 profile call |
-| Response Time | 200-500ms | 50-100ms |
-| Token Usage | High (multiple searches) | Low (single response) |
-| Consistency | Varies by search quality | Always comprehensive |
\ No newline at end of file
diff --git a/apps/docs/user-profiles/api.mdx b/apps/docs/user-profiles/api.mdx
new file mode 100644
index 00000000..73135aa6
--- /dev/null
+++ b/apps/docs/user-profiles/api.mdx
@@ -0,0 +1,183 @@
+---
+title: "Profile API"
+description: "Endpoint details and response structure for user profiles"
+sidebarTitle: "API Reference"
+icon: "code"
+---
+
+## Endpoint
+
+**`POST /v4/profile`**
+
+Retrieves a user's profile, optionally combined with search results.
+
+## Request
+
+### Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Authorization` | Yes | Bearer token with your API key |
+| `Content-Type` | Yes | `application/json` |
+
+### Body Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `containerTag` | string | Yes | The container tag (usually user ID) to get profiles for |
+| `q` | string | No | Optional search query to include search results with the profile |
+
+## Response
+
+```json
+{
+  "profile": {
+    "static": [
+      "User is a software engineer",
+      "User specializes in Python and React",
+      "User prefers dark mode interfaces"
+    ],
+    "dynamic": [
+      "User is working on Project Alpha",
+      "User recently started learning Rust",
+      "User is debugging authentication issues"
+    ]
+  },
+  "searchResults": {
+    "results": [...],  // Only if 'q' parameter was provided
+    "total": 15,
+    "timing": 45.2
+  }
+}
+```
+
+### Response Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `profile.static` | string[] | Long-term, stable facts about the user |
+| `profile.dynamic` | string[] | Recent context and temporary information |
+| `searchResults` | object | Only present if `q` parameter was provided |
+| `searchResults.results` | array | Matching memory results |
+| `searchResults.total` | number | Total number of matches |
+| `searchResults.timing` | number | Query execution time in milliseconds |
+
+## Basic Request
+
+<CodeGroup>
+
+```typescript TypeScript
+const response = await fetch('https://api.supermemory.ai/v4/profile', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    containerTag: 'user_123'
+  })
+});
+
+const data = await response.json();
+
+console.log("Static facts:", data.profile.static);
+console.log("Dynamic context:", data.profile.dynamic);
+```
+
+```python Python
+import requests
+import os
+
+response = requests.post(
+    'https://api.supermemory.ai/v4/profile',
+    headers={
+        'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
+        'Content-Type': 'application/json'
+    },
+    json={
+        'containerTag': 'user_123'
+    }
+)
+
+data = response.json()
+
+print("Static facts:", data['profile']['static'])
+print("Dynamic context:", data['profile']['dynamic'])
+```
+
+```bash cURL
+curl -X POST https://api.supermemory.ai/v4/profile \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "containerTag": "user_123"
+  }'
+```
+
+</CodeGroup>
+
+## Profile with Search
+
+Include a search query to get both profile data and relevant memories in one call:
+
+<CodeGroup>
+
+```typescript TypeScript
+const response = await fetch('https://api.supermemory.ai/v4/profile', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({
+    containerTag: 'user_123',
+    q: 'deployment errors yesterday'
+  })
+});
+
+const data = await response.json();
+
+// Profile data
+const profile = data.profile;
+
+// Search results (only present because we passed 'q')
+const searchResults = data.searchResults?.results || [];
+```
+
+```python Python
+response = requests.post(
+    'https://api.supermemory.ai/v4/profile',
+    headers={
+        'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
+        'Content-Type': 'application/json'
+    },
+    json={
+        'containerTag': 'user_123',
+        'q': 'deployment errors yesterday'
+    }
+)
+
+data = response.json()
+
+profile = data['profile']
+search_results = data.get('searchResults', {}).get('results', [])
+```
+
+</CodeGroup>
+
+## Error Responses
+
+| Status | Description |
+|--------|-------------|
+| `400` | Missing or invalid `containerTag` |
+| `401` | Invalid or missing API key |
+| `404` | Container not found |
+| `500` | Internal server error |
+
+## Rate Limits
+
+Profile requests count toward your standard API rate limits. Since profiles are cached, repeated requests for the same user are efficient.
+
+<Card title="See Examples" icon="laptop-code" href="/user-profiles/examples">
+  View complete integration examples for chat apps, support systems, and more
+</Card>
diff --git a/apps/docs/user-profiles/examples.mdx b/apps/docs/user-profiles/examples.mdx
new file mode 100644
index 00000000..75ae163a
--- /dev/null
+++ b/apps/docs/user-profiles/examples.mdx
@@ -0,0 +1,316 @@
+---
+title: "Profile Examples"
+description: "Complete code examples for integrating user profiles"
+sidebarTitle: "Examples"
+icon: "laptop-code"
+---
+
+## Building a Personalized Prompt
+
+The most common use case: inject profile data into your LLM's system prompt.
+
+<CodeGroup>
+
+```typescript TypeScript
+async function handleChatMessage(userId: string, message: string) {
+  // Get user profile
+  const profileResponse = await fetch('https://api.supermemory.ai/v4/profile', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ containerTag: userId })
+  });
+
+  const { profile } = await profileResponse.json();
+
+  // Build personalized system prompt
+  const systemPrompt = `You are assisting a user with the following context:
+
+ABOUT THE USER:
+${profile.static?.join('\n') || 'No profile information yet.'}
+
+CURRENT CONTEXT:
+${profile.dynamic?.join('\n') || 'No recent activity.'}
+
+Provide responses personalized to their expertise level and preferences.`;
+
+  // Send to your LLM
+  const response = await llm.chat({
+    messages: [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: message }
+    ]
+  });
+
+  return response;
+}
+```
+
+```python Python
+import requests
+import os
+
+async def handle_chat_message(user_id: str, message: str):
+    # Get user profile
+    response = requests.post(
+        'https://api.supermemory.ai/v4/profile',
+        headers={
+            'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
+            'Content-Type': 'application/json'
+        },
+        json={'containerTag': user_id}
+    )
+
+    profile = response.json()['profile']
+
+    # Build personalized system prompt
+    static_facts = '\n'.join(profile.get('static', ['No profile information yet.']))
+    dynamic_context = '\n'.join(profile.get('dynamic', ['No recent activity.']))
+
+    system_prompt = f"""You are assisting a user with the following context:
+
+ABOUT THE USER:
+{static_facts}
+
+CURRENT CONTEXT:
+{dynamic_context}
+
+Provide responses personalized to their expertise level and preferences."""
+
+    # Send to your LLM
+    llm_response = await llm.chat(
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": message}
+        ]
+    )
+
+    return llm_response
+```
+
+</CodeGroup>
+
+## Full Context Mode
+
+Combine profile data with query-specific search for comprehensive context:
+
+<CodeGroup>
+
+```typescript TypeScript
+async function getFullContext(userId: string, userQuery: string) {
+  // Single call gets both profile and search results
+  const response = await fetch('https://api.supermemory.ai/v4/profile', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+      containerTag: userId,
+      q: userQuery  // Include the user's query
+    })
+  });
+
+  const data = await response.json();
+
+  return {
+    // Static background about the user
+    userBackground: data.profile.static,
+    // Current activities and context
+    currentContext: data.profile.dynamic,
+    // Query-specific memories
+    relevantMemories: data.searchResults?.results || []
+  };
+}
+
+// Usage
+const context = await getFullContext('user_123', 'deployment error last week');
+
+const systemPrompt = `
+User Background:
+${context.userBackground.join('\n')}
+
+Current Context:
+${context.currentContext.join('\n')}
+
+Relevant Information:
+${context.relevantMemories.map(m => m.content).join('\n')}
+`;
+```
+
+```python Python
+async def get_full_context(user_id: str, user_query: str):
+    # Single call gets both profile and search results
+    response = requests.post(
+        'https://api.supermemory.ai/v4/profile',
+        headers={
+            'Authorization': f'Bearer {os.getenv("SUPERMEMORY_API_KEY")}',
+            'Content-Type': 'application/json'
+        },
+        json={
+            'containerTag': user_id,
+            'q': user_query  # Include the user's query
+        }
+    )
+
+    data = response.json()
+
+    return {
+        'user_background': data['profile'].get('static', []),
+        'current_context': data['profile'].get('dynamic', []),
+        'relevant_memories': data.get('searchResults', {}).get('results', [])
+    }
+
+# Usage
+context = await get_full_context('user_123', 'deployment error last week')
+
+system_prompt = f"""
+User Background:
+{chr(10).join(context['user_background'])}
+
+Current Context:
+{chr(10).join(context['current_context'])}
+
+Relevant Information:
+{chr(10).join(m['content'] for m in context['relevant_memories'])}
+"""
+```
+
+</CodeGroup>
+
+## Separate Profile and Search
+
+For more control, you can call profile and search endpoints separately:
+
+```typescript TypeScript
+async function advancedContext(userId: string, query: string) {
+  // Parallel requests for profile and search
+  const [profileRes, searchRes] = await Promise.all([
+    fetch('https://api.supermemory.ai/v4/profile', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ containerTag: userId })
+    }),
+    fetch('https://api.supermemory.ai/v3/search', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        q: query,
+        containerTag: userId,
+        limit: 5
+      })
+    })
+  ]);
+
+  const profile = await profileRes.json();
+  const search = await searchRes.json();
+
+  return { profile: profile.profile, searchResults: search.results };
+}
+```
+
+## Express.js Middleware
+
+Add profile context to all authenticated requests:
+
+```typescript TypeScript
+import express from 'express';
+
+// Middleware to fetch user profile
+async function withUserProfile(req, res, next) {
+  if (!req.user?.id) {
+    return next();
+  }
+
+  try {
+    const response = await fetch('https://api.supermemory.ai/v4/profile', {
+      method: 'POST',
+      headers: {
+        'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ containerTag: req.user.id })
+    });
+
+    req.userProfile = await response.json();
+  } catch (error) {
+    console.error('Failed to fetch profile:', error);
+    req.userProfile = null;
+  }
+
+  next();
+}
+
+const app = express();
+
+// Apply to all routes
+app.use(withUserProfile);
+
+app.post('/chat', async (req, res) => {
+  const { message } = req.body;
+
+  // Profile is automatically available
+  const profile = req.userProfile?.profile;
+
+  // Use in your LLM call...
+});
+```
+
+## Next.js API Route
+
+```typescript TypeScript
+// app/api/chat/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const { userId, message } = await req.json();
+
+  // Fetch profile
+  const profileRes = await fetch('https://api.supermemory.ai/v4/profile', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`,
+      'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({ containerTag: userId })
+  });
+
+  const { profile } = await profileRes.json();
+
+  // Build context and call your LLM...
+  const response = await generateResponse(message, profile);
+
+  return NextResponse.json({ response });
+}
+```
+
+## AI SDK Integration
+
+For the cleanest integration, use the Supermemory AI SDK middleware:
+
+```typescript TypeScript
+import { generateText } from "ai"
+import { withSupermemory } from "@supermemory/tools/ai-sdk"
+import { openai } from "@ai-sdk/openai"
+
+// One line setup - profiles automatically injected
+const model = withSupermemory(openai("gpt-4"), "user-123")
+
+const result = await generateText({
+  model,
+  messages: [{ role: "user", content: "Help me with my current project" }]
+})
+// Model automatically has access to user's profile!
+```
+
+<Card title="AI SDK User Profiles" icon="triangle" href="/ai-sdk/user-profiles">
+  Learn more about automatic profile injection with the AI SDK
+</Card>
diff --git a/apps/docs/user-profiles/overview.mdx b/apps/docs/user-profiles/overview.mdx
new file mode 100644
index 00000000..80acd1c2
--- /dev/null
+++ b/apps/docs/user-profiles/overview.mdx
@@ -0,0 +1,135 @@
+---
+title: "User Profiles"
+description: "Automatically maintained user context that gives your LLMs instant, comprehensive knowledge about each user"
+sidebarTitle: "Overview"
+icon: "user"
+---
+
+User profiles are **automatically maintained collections of facts about your users** that Supermemory builds from all their interactions and content. Think of it as a persistent "about me" document that's always up-to-date and instantly accessible.
+
+<CardGroup cols={2}>
+  <Card title="Instant Context" icon="bolt">
+    No search queries needed - comprehensive user information is always ready
+  </Card>
+  <Card title="Auto-Updated" icon="rotate">
+    Profiles update automatically as users interact with your system
+  </Card>
+  <Card title="Two-Tier Structure" icon="layer-group">
+    Static facts + dynamic context for perfect personalization
+  </Card>
+  <Card title="Zero Setup" icon="wand-magic-sparkles">
+    Just ingest content normally - profiles build themselves
+  </Card>
+</CardGroup>
+
+## Why Profiles?
+
+Traditional memory systems rely entirely on search, which has fundamental limitations:
+
+| Problem | With Search Only | With Profiles |
+|---------|-----------------|---------------|
+| **Context retrieval** | 3-5 search queries | 1 profile call |
+| **Response time** | 200-500ms | 50-100ms |
+| **Consistency** | Varies by search quality | Always comprehensive |
+| **Basic user info** | Requires specific queries | Always available |
+
+**Search is too narrow**: When you search for "project updates", you miss that the user prefers bullet points, works in PST timezone, and uses specific terminology.
+
+**Profiles provide the foundation**: Instead of repeatedly searching for basic context, profiles give your LLM a complete picture of who the user is.
+
+## Static vs Dynamic
+
+Profiles intelligently separate two types of information:
+
+![](/images/static-dynamic-profile.png)
+
+### Static Profile
+
+Long-term, stable facts that rarely change:
+
+- "Sarah Chen is a senior software engineer at TechCorp"
+- "Sarah specializes in distributed systems and Kubernetes"
+- "Sarah has a PhD in Computer Science from MIT"
+- "Sarah prefers technical documentation over video tutorials"
+
+### Dynamic Profile
+
+Recent context and temporary states:
+
+- "Sarah is currently migrating the payment service to microservices"
+- "Sarah recently started learning Rust for a side project"
+- "Sarah is preparing for a conference talk next month"
+- "Sarah is debugging a memory leak in the authentication service"
+
+## How It Works
+
+Profiles are **automatically built and maintained** through Supermemory's ingestion pipeline:
+
+<Steps>
+  <Step title="Content Ingestion">
+    When users add documents, chat, or any content to Supermemory, it goes through the standard ingestion workflow.
+  </Step>
+
+  <Step title="Intelligence Extraction">
+    AI analyzes the content to extract not just memories, but also facts about the user themselves.
+  </Step>
+
+  <Step title="Profile Operations">
+    The system generates profile operations (add, update, or remove facts) based on the new information.
+  </Step>
+
+  <Step title="Automatic Updates">
+    Profiles are updated in real-time, ensuring they always reflect the latest information.
+  </Step>
+</Steps>
+
+<Note>
+  You don't need to manually manage profiles - they build themselves as users interact with your system.
+</Note>
+
+## Profiles + Search
+
+Profiles don't replace search - they complement it:
+
+<Steps>
+  <Step title="Profile provides foundation">
+    The user's profile gives your LLM comprehensive background context about who they are, what they know, and what they're working on.
+  </Step>
+
+  <Step title="Search adds specificity">
+    When you need specific information (like "error in deployment yesterday"), search finds those exact memories.
+  </Step>
+
+  <Step title="Combined for perfect context">
+    Your LLM gets both the broad understanding from profiles AND the specific details from search.
+  </Step>
+</Steps>
+
+### Example
+
+User asks: **"Can you help me debug this?"**
+
+**Without profiles**: The LLM has no context about the user's expertise level, current projects, or debugging preferences.
+
+**With profiles**: The LLM knows:
+- The user is a senior engineer (adjust technical level)
+- They're working on a payment service migration (likely context)
+- They prefer command-line tools over GUIs (tool suggestions)
+- They recently had issues with memory leaks (possible connection)
+
+## Next Steps
+
+<CardGroup cols={2}>
+  <Card title="API Reference" icon="code" href="/user-profiles/api">
+    Learn how to fetch and use profiles via the API
+  </Card>
+  <Card title="Code Examples" icon="laptop-code" href="/user-profiles/examples">
+    See complete integration examples
+  </Card>
+  <Card title="AI SDK Integration" icon="triangle" href="/ai-sdk/user-profiles">
+    Use the AI SDK for automatic profile injection
+  </Card>
+  <Card title="Use Cases" icon="lightbulb" href="/user-profiles/use-cases">
+    Common patterns and applications
+  </Card>
+</CardGroup>
diff --git a/apps/docs/user-profiles/use-cases.mdx b/apps/docs/user-profiles/use-cases.mdx
new file mode 100644
index 00000000..db383513
--- /dev/null
+++ b/apps/docs/user-profiles/use-cases.mdx
@@ -0,0 +1,153 @@
+---
+title: "Profile Use Cases"
+description: "Common patterns and applications for user profiles"
+sidebarTitle: "Use Cases"
+icon: "lightbulb"
+---
+
+## Personalized AI Assistants
+
+The most common use case: building AI assistants that truly know your users.
+
+**What profiles provide:**
+- User's expertise level (adjust technical depth)
+- Communication preferences (brief vs detailed, formal vs casual)
+- Tools and technologies they use
+- Current projects and priorities
+
+**Example prompt enhancement:**
+
+```typescript
+const systemPrompt = `You are assisting ${userName}.
+
+Their background:
+${profile.static.join('\n')}
+
+Current focus:
+${profile.dynamic.join('\n')}
+
+Adjust your responses to match their expertise level and preferences.`;
+```
+
+**Result:** An assistant that explains React hooks differently to a junior developer vs a senior architect.
+
+## Customer Support Systems
+
+Give support agents (or AI) instant context about customers.
+
+**What profiles provide:**
+- Customer's product usage history
+- Previous issues and resolutions
+- Preferred communication channels
+- Technical proficiency level
+
+**Benefits:**
+- No more "let me look up your account"
+- Agents immediately understand customer context
+- AI support can reference past interactions naturally
+
+```typescript
+// Support agent dashboard
+async function loadCustomerContext(customerId: string) {
+  const { profile } = await getProfile(customerId);
+
+  return {
+    summary: profile.static,      // Long-term customer info
+    recentIssues: profile.dynamic // Current tickets, recent problems
+  };
+}
+```
+
+## Educational Platforms
+
+Adapt learning content to each student's level and progress.
+
+**What profiles provide:**
+- Learning style preferences
+- Completed courses and topics
+- Areas of strength and weakness
+- Current learning goals
+
+**Example adaptation:**
+
+```typescript
+// Profile might contain:
+// static: ["Visual learner", "Strong in algebra, struggles with geometry"]
+// dynamic: ["Currently studying calculus", "Preparing for AP exam"]
+
+const tutorPrompt = `You're helping a student with:
+${profile.static.join('\n')}
+
+Current focus: ${profile.dynamic.join('\n')}
+
+Adapt explanations to their learning style and build on their strengths.`;
+```
+
+## Development Tools
+
+IDE assistants and coding tools that understand your codebase and habits.
+
+**What profiles provide:**
+- Preferred languages and frameworks
+- Coding style and conventions
+- Current project context
+- Frequently used patterns
+
+**Example:**
+
+```typescript
+// Profile for a developer:
+// static: ["Prefers TypeScript", "Uses functional patterns", "Senior engineer"]
+// dynamic: ["Working on auth refactor", "Recently learning Rust"]
+
+// Code assistant knows to:
+// - Suggest TypeScript solutions
+// - Use functional patterns in examples
+// - Provide senior-level explanations
+// - Connect suggestions to the auth refactor when relevant
+```
+
+## Knowledge Base Assistants
+
+Internal tools that understand each employee's role and responsibilities.
+
+**What profiles provide:**
+- Department and role
+- Projects they're involved in
+- Access level and permissions context
+- Areas of expertise (for routing questions)
+
+**Example:**
+
+```typescript
+// HR assistant that knows:
+// - Employee's team and manager
+// - Their location/timezone
+// - Recent PTO requests
+// - Benefits elections
+
+const response = await hrAssistant.answer(
+  "When is my next performance review?",
+  { profile: employeeProfile }
+);
+// Can answer with specific dates, manager name, etc.
+```
+
+## E-commerce Recommendations
+
+Personalized shopping experiences beyond basic recommendation engines.
+
+**What profiles provide:**
+- Style preferences
+- Size information
+- Past purchases and returns
+- Budget range
+- Occasions they shop for
+
+**Example conversation:**
+
+```
+User: "I need something for a wedding next month"
+
+// Profile knows: prefers classic styles, size M, budget-conscious,
+// previously bought navy suits
\ No newline at end of file