> ## Documentation Index > Fetch the complete documentation index at: https://supermemory.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Vibe Coding Setup > Automatic Supermemory integration using AI coding agents Get your AI coding agent to integrate Supermemory in minutes. Copy the prompt below, paste it into Claude/GPT/Cursor, and let it do the work. ## Quick Setup Give your agent a way to reference and search through supermemory docs. Paste one prompt, answer questions, get working code Interactive guided setup ## MCP Server Give your agent a way to reference and search through supermemory docs. ### Quick Install ```bash theme={null} npx -y install-mcp@latest https://supermemory.ai/docs/mcp --client claude-code --oauth=no -y ``` Replace `claude` with: `cursor`, `opencode`, or `vscode` *** ## The Prompt **Copy everything in the code block below** and paste it into your AI coding agent. It will ask you questions and generate complete integration code. After adding the MCP, paste this in your agent session: ```` You are integrating Supermemory into my application. Supermemory provides user memory, semantic search, and automatic knowledge extraction for AI applications. Note: You can always reference the documentation by using the **SearchSupermemoryDocs MCP** or running a web search tool for content on **supermemory.ai/docs**. CANONICAL API SURFACE (use these, nothing else): - Auth header: `Authorization: Bearer $SUPERMEMORY_API_KEY` — the only supported auth header - Write content: POST https://api.supermemory.ai/v3/documents - Search: POST https://api.supermemory.ai/v4/search - Profile + search: POST https://api.supermemory.ai/v4/profile - Settings: PATCH https://api.supermemory.ai/v3/settings - Scoping: `containerTag` (singular string) in the JSON body — never in a header - SDK: `client.documents.add()`, `client.search.memories()`, `client.profile()` DO NOT USE — these are deprecated, undocumented, or fabricated by previous AI codegen: - Endpoints: /v1/anything, /v3/memories, /v3/search (use /v3/documents and /v4/search) - Headers: x-supermemory-api-key, x-api-key, x-sm-user-id, x-sm-project, x-project-id, X-Workspace-Id (always use Authorization: Bearer) - Body keys: containerTags (plural array), userId, spaces, schema, container, tags (top-level), filter (singular) (use containerTag + filters) - SDK calls: client.search.execute, client.documents.add (use client.add), client.documents.deleteBulk, client.documents.batch_add, client.memories.updateMemory (the real method is client.memories.update) - Kwargs: chunk_threshold (use `threshold`), sort, order, include_content, include_full_docs, timeout (as an SDK kwarg) NOTE on memory mutation: `client.memories.update`, `client.memories.delete`, and `client.memories.forget` ARE real and supported — but most apps don't need them. Memories are auto-extracted from documents. Only reach for these if you're exposing a "manage my memories" UI to end users or agents. - Mixing: `rerank` and `rewriteQuery` are valid on /v4/search ONLY — never on /v3/search SCOPING IS LOAD-BEARING. Every write and every search MUST include `containerTag`. If you omit it, every user's data collapses into the API key's default bucket — this is the single most common bug in AI-generated Supermemory integrations. STEP 1: ASK ME THESE QUESTIONS 1. What are you building? - Personal chatbot/assistant - Team knowledge base - Customer support bot - Document Q&A - Other 2. How do you want to integrate? - Vercel AI SDK (@supermemory/tools) - OpenAI plugins - Direct SDK (supermemory npm/pip) - Direct API calls 3. Data model? - Individual users only → containerTag: userId - Organizations only → containerTag: orgId - Both users AND orgs → ask for strategy 4. Do you want USER PROFILES? User profiles are automatically-maintained facts about users (what they like, what they're working on, preferences). - Yes (RECOMMENDED) → Use client.profile() to get context - No → Just use search 5. How should I retrieve context? - OPTION A: One call with search included → profile({ containerTag, q: userMessage }) - OPTION B: Separate calls → profile() for facts, search() for memories STEP 2: INSTALL # Get API key: https://console.supermemory.ai npm install supermemory # or: pip install supermemory # For Vercel AI SDK: npm install @supermemory/tools export SUPERMEMORY_API_KEY="sm_..." STEP 3: CONFIGURE SETTINGS (DO THIS FIRST) ```typescript // PATCH https://api.supermemory.ai/v3/settings fetch('https://api.supermemory.ai/v3/settings', { method: 'PATCH', headers: { 'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}`, 'Content-Type': 'application/json', }, body: JSON.stringify({ shouldLLMFilter: true, filterPrompt: `This is a [your app description]. containerTag is [userId/orgId]. We store [what data].` }) }) ``` STEP 4: CONTAINER TAG STRATEGY Based on their data model answer: USER-ONLY APP: ```typescript containerTag: userId // Each user's memories are isolated ``` ORG-ONLY APP: ```typescript containerTag: orgId // Org members share memories ``` BOTH (ask which): - Option A: `containerTag: \`\${userId}-\${orgId}\`` - Option B: `containerTag: orgId, metadata: { userId }` - Option C: `containerTag: userId, metadata: { orgId }` STEP 5: INTEGRATION CODE Based on their integration choice: --- VERCEL AI SDK --- ```typescript import { streamText } from 'ai' import { anthropic } from '@ai-sdk/anthropic' import { supermemoryTools } from '@supermemory/tools/ai-sdk' // Option 1: Agent tools (recommended for agentic flows) const result = await streamText({ model: anthropic('claude-3-5-sonnet-20241022'), prompt: userMessage, tools: supermemoryTools(process.env.SUPERMEMORY_API_KEY, { containerTag: userId // singular string — never an array }) }) // Agent gets searchMemories, addMemory, fetchMemory tools // Option 2: Profile middleware (automatic context injection) import { withSupermemory } from '@supermemory/tools/ai-sdk' const modelWithMemory = withSupermemory(anthropic('claude-3-5-sonnet-20241022'), { containerTag: userId, customId: 'conversation-1', }) const result = await generateText({ model: modelWithMemory, messages: [{ role: 'user', content: userMessage }] }) // Profile is automatically injected into context ``` --- DIRECT SDK (WITH PROFILES) --- ```typescript import Supermemory from 'supermemory' const client = new Supermemory() // Before each LLM call: const { profile, searchResults } = await client.profile({ containerTag: userId, q: userMessage // Include this if they chose OPTION A (one call) // Omit if they chose OPTION B (separate calls) }) // Build context const context = ` Static facts: ${profile.static.join('\n')} Recent context: ${profile.dynamic.join('\n')} ${searchResults ? `Memories: ${searchResults.results.map(r => r.memory).join('\n')}` : ''} ` // Send to LLM const messages = [ { role: 'system', content: `User context:\n${context}` }, { role: 'user', content: userMessage } ] // After LLM responds: await client.add({ content: `user: ${userMessage}\nassistant: ${response}`, containerTag: userId }) ``` --- DIRECT SDK (NO PROFILES) --- ```typescript import Supermemory from 'supermemory' const client = new Supermemory() // Search for relevant memories const results = await client.search({ q: userMessage, containerTag: userId, searchMode: 'hybrid', // Searches memories + document chunks limit: 5 }) // Build context const context = results.results.map(r => r.memory || r.chunk).join('\n') // Send to LLM with context const messages = [ { role: 'system', content: `Relevant context:\n${context}` }, { role: 'user', content: userMessage } ] // Store the conversation await client.add({ content: `user: ${userMessage}\nassistant: ${response}`, containerTag: userId }) ``` --- PYTHON VERSION --- ```python from supermemory import Supermemory client = Supermemory() # With profiles (if they want it) profile_data = client.profile( container_tag=user_id, q=user_message # Include if OPTION A, omit if OPTION B ) context = f""" Static: {chr(10).join(profile_data.profile.static)} Dynamic: {chr(10).join(profile_data.profile.dynamic)} """ # Store conversation client.add(content=f"user: {user_message}\\nassistant: {response}", container_tag=user_id) ``` --- DIRECT API --- ```bash # Add memory curl -X POST https://api.supermemory.ai/v3/documents \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"content": "conversation", "containerTag": "userId"}' # Get profile curl -X POST https://api.supermemory.ai/v4/profile \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"containerTag": "userId", "q": "search query"}' # Search curl -X POST https://api.supermemory.ai/v4/search \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"q": "query", "containerTag": "userId", "searchMode": "hybrid"}' ``` STEP 6: FILE UPLOADS (if they need it) ```typescript // Files are automatically extracted (PDFs, images with OCR, videos with transcription) const formData = new FormData() formData.append('file', fileBlob) formData.append('containerTag', userId) await fetch('https://api.supermemory.ai/v3/documents/file', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.SUPERMEMORY_API_KEY}` }, body: formData }) // Processing is async - check status before assuming searchable // GET /v3/documents/{documentId} ``` STEP 7: SEARCH MODES ```typescript // HYBRID (recommended) - searches memories + document chunks searchMode: 'hybrid' // MEMORIES ONLY - just extracted memories, no original text searchMode: 'memories' ``` STEP 8: METADATA FILTERS (if they need secondary filtering) ```typescript // Always against /v4/search — rerank/rewriteQuery/filters are v4-only await client.search.memories({ q: query, containerTag: userId, filters: { AND: [ { key: 'type', value: 'conversation', type: 'string_equal' }, { key: 'timestamp', value: '2024', type: 'string_contains' } ] } }) ``` KEY POINTS: 1. Configure settings FIRST with filterPrompt 2. User profiles = automatic facts about users (profile.static + profile.dynamic) 3. profile({ containerTag, q }) combines profile + search in ONE call 4. Search modes: 'hybrid' (recommended) or 'memories' 5. File extraction is automatic - no config needed 6. Store conversations after each interaction 7. containerTag should match what you put in filterPrompt TESTING: ```bash # 1. Configure settings curl -X PATCH https://api.supermemory.ai/v3/settings \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"shouldLLMFilter": true, "filterPrompt": "..."}' # 2. Add test memory curl -X POST https://api.supermemory.ai/v3/documents \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"content": "Test", "containerTag": "test_user"}' # 3. Get profile curl -X POST https://api.supermemory.ai/v4/profile \ -H "Authorization: Bearer $SUPERMEMORY_API_KEY" \ -H "Content-Type: application/json" \ -d '{"containerTag": "test_user"}' ``` NOW: 1. Ask me the 5 questions above 2. Generate complete working code based on my answers 3. Include installation, settings config, and full integration DOCS: https://supermemory.ai/docs ```` *** ## Claude Code Skill Interactive setup for Claude Code users. ### Install ```bash theme={null} # 1. Clone repo git clone https://github.com/supermemoryai/supermemory.git # 2. Copy skill mkdir -p ~/.claude/skills cp supermemory/.claude/skills/supermemory-integrate.md ~/.claude/skills/ # 3. Restart Claude Code ``` ### Use ```bash theme={null} /supermemory-integrate ``` The skill asks questions interactively and generates code for your specific setup. *** ## Next Steps Manual integration guide Deep dive into profiles Search modes and parameters Complete API docs