Vibe Coding Setup

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