diff --git a/apps/docs/ai-sdk/examples.mdx b/apps/docs/ai-sdk/examples.mdx deleted file mode 100644 index 9eabbae9..00000000 --- a/apps/docs/ai-sdk/examples.mdx +++ /dev/null @@ -1,357 +0,0 @@ ---- -title: "AI SDK Examples" -description: "Complete examples showing how to use Supermemory with Vercel AI SDK" -sidebarTitle: "Examples" ---- - -This page provides comprehensive examples of using Supermemory with the Vercel AI SDK, covering Memory Tools and User Profiles approaches. - -## Personal Assistant with Memory Tools - -Build an AI assistant that remembers user preferences and past interactions: - - - -```typescript Next.js API Route -import { streamText } from 'ai' -import { createAnthropic } from '@ai-sdk/anthropic' -import { supermemoryTools } from '@supermemory/tools/ai-sdk' - -const anthropic = createAnthropic({ - apiKey: process.env.ANTHROPIC_API_KEY! -}) - -export async function POST(request: Request) { - const { messages } = await request.json() - - const result = await streamText({ - model: anthropic('claude-3-sonnet-20240229'), - messages, - tools: supermemoryTools(process.env.SUPERMEMORY_API_KEY!), - system: `You are a helpful personal assistant. When users share information about themselves, - remember it using the addMemory tool. When they ask questions, search your memories to provide - personalized responses. Always be proactive about remembering important details.` - }) - - return result.toAIStreamResponse() -} -``` - -```typescript Client Component -'use client' - -import { useChat } from 'ai/react' - -export default function PersonalAssistant() { - const { messages, input, handleInputChange, handleSubmit } = useChat() - - return ( -
-
- {messages.map((message) => ( -
-

{message.content}

-
- ))} -
- -
- -
-
- ) -} -``` - - - -**Example conversation:** -- User: "I'm allergic to peanuts and I love Italian food" -- AI: *Uses addMemory tool* "I've remembered that you're allergic to peanuts and love Italian food!" -- User: "Suggest a restaurant for dinner" -- AI: *Uses searchMemories tool* "Based on what I know about you, I'd recommend an Italian restaurant that's peanut-free..." - -## Customer Support with Context - -Build a customer support system that remembers customer history: - -```typescript -import { streamText } from 'ai' -import { createOpenAI } from '@ai-sdk/openai' -import { supermemoryTools } from '@supermemory/tools/ai-sdk' - -const openai = createOpenAI({ - apiKey: process.env.OPENAI_API_KEY! -}) - -export async function POST(request: Request) { - const { messages, customerId } = await request.json() - - const result = await streamText({ - model: openai('gpt-5'), - messages, - tools: supermemoryTools(process.env.SUPERMEMORY_API_KEY!, { - containerTags: [customerId] - }), - system: `You are a customer support agent. Before responding to any query: - 1. Search for the customer's previous interactions and issues - 2. Remember any new information shared in this conversation - 3. Provide personalized help based on their history - 4. Always be empathetic and solution-focused` - }) - - return result.toAIStreamResponse() -} -``` - -## Multi-User Learning Assistant - -Build an assistant that learns from multiple users but keeps data separate: - -```typescript -import { streamText } from 'ai' -import { createAnthropic } from '@ai-sdk/anthropic' -import { supermemoryTools } from '@supermemory/tools/ai-sdk' - -const anthropic = createAnthropic({ - apiKey: process.env.ANTHROPIC_API_KEY! -}) - -export async function POST(request: Request) { - const { messages, userId, courseId } = await request.json() - - const result = await streamText({ - model: anthropic('claude-3-haiku-20240307'), - messages, - tools: supermemoryTools(process.env.SUPERMEMORY_API_KEY!, { - containerTags: [userId] - }), - system: `You are a learning assistant. Help students with their coursework by: - 1. Remembering their learning progress and struggles - 2. Searching for relevant information from their past sessions - 3. Providing personalized explanations based on their learning style - 4. Tracking topics they've mastered vs topics they need more help with` - }) - - return result.toAIStreamResponse() -} -``` - -## Research Assistant with File Processing - -Combine file upload with memory tools for research assistance: - - - -```typescript API Route -import { streamText } from 'ai' -import { createOpenAI } from '@ai-sdk/openai' -import { supermemoryTools } from '@supermemory/tools/ai-sdk' - -const openai = createOpenAI({ - apiKey: process.env.OPENAI_API_KEY! -}) - -export async function POST(request: Request) { - const { messages, projectId } = await request.json() - - const result = await streamText({ - model: openai('gpt-5'), - messages, - tools: supermemoryTools(process.env.SUPERMEMORY_API_KEY!, { - containerTags: [projectId] - }), - system: `You are a research assistant. You can: - 1. Search through uploaded research papers and documents - 2. Remember key findings and insights from conversations - 3. Help synthesize information across multiple sources - 4. Track research progress and important discoveries` - }) - - return result.toAIStreamResponse() -} -``` - -```typescript File Upload Handler -import { addMemory } from '@supermemory/tools' - -export async function POST(request: Request) { - const formData = await request.formData() - const file = formData.get('file') as File - const projectId = formData.get('projectId') as string - - // Upload file and add to memory - const memory = await addMemory({ - apiKey: process.env.SUPERMEMORY_API_KEY!, - content: file, // Supermemory handles file processing - title: file.name, - headers: { - 'x-sm-conversation-id': projectId - } - }) - - return Response.json({ - success: true, - message: "Document uploaded and processed for research", - memoryId: memory.id - }) -} -``` - - - -## Code Assistant with Project Memory - -Create a coding assistant that remembers your codebase and preferences: - -```typescript -import { streamText } from 'ai' -import { createAnthropic } from '@ai-sdk/anthropic' -import { - supermemoryTools, - searchMemoriesTool, - addMemoryTool -} from '@supermemory/tools/ai-sdk' - -const anthropic = createAnthropic({ - apiKey: process.env.ANTHROPIC_API_KEY! -}) - -export async function POST(request: Request) { - const { messages, repositoryId } = await request.json() - - const result = await streamText({ - model: anthropic('claude-3-sonnet-20240229'), - messages, - tools: { - // Use individual tools for more control - searchMemories: searchMemoriesTool(process.env.SUPERMEMORY_API_KEY!, { - headers: { - 'x-sm-conversation-id': `repo-${repositoryId}` - } - }), - addMemory: addMemoryTool(process.env.SUPERMEMORY_API_KEY!, { - headers: { - 'x-sm-conversation-id': `repo-${repositoryId}` - } - }), - // Add custom tools - executeCode: { - description: 'Execute code in a sandbox environment', - parameters: z.object({ - code: z.string(), - language: z.string() - }), - execute: async ({ code, language }) => { - // Your code execution logic - return { result: "Code executed successfully" } - } - } - }, - system: `You are a coding assistant with memory. You can: - 1. Remember coding patterns and preferences from past conversations - 2. Search through previous code examples and solutions - 3. Track project architecture and design decisions - 4. Learn from debugging sessions and common issues` - }) - - return result.toAIStreamResponse() -} -``` - -## Advanced: Custom Tool Integration - -Combine Supermemory tools with your own custom tools: - -```typescript -import { streamText } from 'ai' -import { createOpenAI } from '@ai-sdk/openai' -import { supermemoryTools } from '@supermemory/tools/ai-sdk' -import { z } from 'zod' - -const openai = createOpenAI({ - apiKey: process.env.OPENAI_API_KEY! -}) - -// Custom tool for calendar integration -const calendarTool = { - description: 'Create calendar events', - parameters: z.object({ - title: z.string(), - date: z.string(), - duration: z.number() - }), - execute: async ({ title, date, duration }) => { - // Your calendar API integration - return { eventId: "cal_123", message: "Event created" } - } -} - -export async function POST(request: Request) { - const { messages } = await request.json() - - const result = await streamText({ - model: openai('gpt-5'), - messages, - tools: { - // Spread Supermemory tools - ...supermemoryTools(process.env.SUPERMEMORY_API_KEY!), - // Add custom tools - createEvent: calendarTool, - }, - system: `You are a personal assistant that can remember information and - manage calendars. When users mention events or appointments: - 1. Remember the details using addMemory - 2. Create calendar events using createEvent - 3. Search for conflicts using searchMemories` - }) - - return result.toAIStreamResponse() -} -``` - -## Environment Setup - -For all examples, ensure you have these environment variables: - -```bash .env.local -SUPERMEMORY_API_KEY=your_supermemory_key -OPENAI_API_KEY=your_openai_key -ANTHROPIC_API_KEY=your_anthropic_key -``` - -## Best Practices - -### Memory Tools -- Use descriptive memory content for better search results -- Include context in your system prompts about when to use each tool -- Use project headers to separate different use cases -- Implement error handling for tool failures - -### General Tips -- Start with simple examples and gradually add complexity -- Use the search functionality to avoid duplicate memories -- Implement proper authentication for production use -- Consider rate limiting for high-volume applications - -## Next Steps - - - - Advanced memory management with full API control - - - - Automatic personalization with user profiles - - diff --git a/apps/docs/ai-sdk/npm.mdx b/apps/docs/ai-sdk/npm.mdx deleted file mode 100644 index 88ced6c2..00000000 --- a/apps/docs/ai-sdk/npm.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "NPM link" -url: "https://www.npmjs.com/package/@supermemory/tools" -icon: npm ---- diff --git a/apps/docs/cookbook/inf-chat-blog.mdx b/apps/docs/cookbook/inf-chat-blog.mdx deleted file mode 100644 index f5c2fcbe..00000000 --- a/apps/docs/cookbook/inf-chat-blog.mdx +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Extending context windows in LLMs" -url: "https://supermemory.ai/blog/extending-context-windows-in-llms/" ---- diff --git a/apps/docs/docs.json b/apps/docs/docs.json index d3a62eff..1b3f7a27 100644 --- a/apps/docs/docs.json +++ b/apps/docs/docs.json @@ -3,7 +3,11 @@ "api": { "examples": { "defaults": "required", - "languages": ["javascript", "python", "curl"] + "languages": [ + "javascript", + "python", + "curl" + ] }, "openapi": "https://api.supermemory.ai/v3/openapi" }, @@ -13,7 +17,12 @@ "primary": "#1E3A8A" }, "contextual": { - "options": ["copy", "view", "chatgpt", "claude"] + "options": [ + "copy", + "view", + "chatgpt", + "claude" + ] }, "favicon": "/favicon.png", "fonts": { @@ -69,7 +78,11 @@ "pages": [ { "group": "Getting Started", - "pages": ["intro", "quickstart", "vibe-coding"] + "pages": [ + "intro", + "quickstart", + "vibe-coding" + ] }, { "group": "Self-Hosting", @@ -142,7 +155,10 @@ { "group": "From another provider", "icon": "truck", - "pages": ["migration/from-mem0", "migration/from-zep"] + "pages": [ + "migration/from-mem0", + "migration/from-zep" + ] } ] } @@ -157,7 +173,9 @@ { "group": "Setups", "icon": "layers", - "pages": ["supermemory-mcp/claude-desktop"] + "pages": [ + "supermemory-mcp/claude-desktop" + ] } ] }, @@ -213,7 +231,9 @@ { "group": "Migration Guides", "icon": "arrow-up-right", - "pages": ["migration/tools-v2-upgrade"] + "pages": [ + "migration/tools-v2-upgrade" + ] } ] } @@ -258,7 +278,10 @@ "memorybench/github", { "group": "Getting Started", - "pages": ["memorybench/installation", "memorybench/quickstart"] + "pages": [ + "memorybench/installation", + "memorybench/quickstart" + ] }, { "group": "Development", @@ -274,7 +297,8 @@ "pages": [ "memorybench/memscore", "memorybench/cli", - "memorybench/integrations" + "memorybench/integrations", + "memorybench/supported-models" ] } ] @@ -311,7 +335,10 @@ "anchors": [ { "anchor": "Changelog", - "pages": ["changelog/overview", "changelog/plugins"] + "pages": [ + "changelog/overview", + "changelog/plugins" + ] } ], "tab": "Changelog" @@ -548,6 +575,138 @@ "destination": "/add-memories", "permanent": true, "source": "/memory-api/overview" + }, + { + "source": "/ai-sdk/examples", + "destination": "/integrations/ai-sdk" + }, + { + "source": "/ai-sdk/npm", + "destination": "/integrations/ai-sdk" + }, + { + "source": "/cookbook/inf-chat-blog", + "destination": "/cookbook/overview" + }, + { + "source": "/memory-api/connectors/google-drive", + "destination": "/connectors/google-drive" + }, + { + "source": "/memory-api/connectors/overview", + "destination": "/connectors/overview" + }, + { + "source": "/memory-api/creation/adding-memories", + "destination": "/add-memories" + }, + { + "source": "/memory-api/creation/status", + "destination": "/document-operations" + }, + { + "source": "/openai-sdks/usage", + "destination": "/integrations/openai" + }, + { + "source": "/overview/why-supermemory", + "destination": "/intro" + }, + { + "source": "/supermemory-mcp/introduction", + "destination": "/supermemory-mcp/mcp" + }, + { + "source": "/supermemory-mcp/technology", + "destination": "/supermemory-mcp/mcp" + }, + { + "source": "/memory-graph/npm", + "destination": "/integrations/memory-graph" + }, + { + "source": "/memory-router/overview", + "destination": "/integrations/ai-sdk" + }, + { + "source": "/memory-router/usage", + "destination": "/integrations/ai-sdk" + }, + { + "source": "/memory-router/with-memory-api", + "destination": "/integrations/ai-sdk" + }, + { + "source": "/memory-api/features/reranking", + "destination": "/search" + }, + { + "source": "/memory-api/introduction", + "destination": "/intro" + }, + { + "source": "/memory-api/sdks/anthropic-claude-memory", + "destination": "/integrations/claude-memory" + }, + { + "source": "/memory-api/sdks/python", + "destination": "/integrations/supermemory-sdk" + }, + { + "source": "/memory-api/sdks/supermemory-npm", + "destination": "/integrations/supermemory-sdk" + }, + { + "source": "/memory-api/sdks/supermemory-pypi", + "destination": "/integrations/supermemory-sdk" + }, + { + "source": "/memory-api/sdks/typescript", + "destination": "/integrations/supermemory-sdk" + }, + { + "source": "/memory-api/searching/searching-memories", + "destination": "/search" + }, + { + "source": "/model-enhancement/context-extender", + "destination": "/integrations/ai-sdk" + }, + { + "source": "/model-enhancement/getting-started", + "destination": "/integrations/ai-sdk" + }, + { + "source": "/model-enhancement/identifying-users", + "destination": "/integrations/ai-sdk" + }, + { + "source": "/memory-api/features/auto-multi-modal", + "destination": "/concepts/content-types" + }, + { + "source": "/memory-api/features/content-cleaner", + "destination": "/concepts/customization" + }, + { + "source": "/memory-api/features/filtering", + "destination": "/concepts/filtering" + }, + { + "source": "/memory-api/features/query-rewriting", + "destination": "/search" + }, + { + "source": "/introduction", + "destination": "/intro" + }, + { + "source": "/memory-api/connectors/advanced/bring-your-own-key", + "destination": "/connectors/overview" + }, + { + "source": "/memory-api/connectors/creating-connection", + "destination": "/connectors/overview" } ], "styling": { diff --git a/apps/docs/install.md b/apps/docs/install.md deleted file mode 100644 index 2968ea08..00000000 --- a/apps/docs/install.md +++ /dev/null @@ -1,317 +0,0 @@ -You are integrating Supermemory into my application. Supermemory provides user memory, semantic search, and automatic knowledge extraction for AI applications. - -You can always reference the documentation by using the **SearchSupermemoryDocs MCP** or running a web search tool for content on **supermemory.ai/docs**. - -## 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 - -```bash -# 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 -``` - -**ORG-ONLY APP:** - -```typescript -containerTag: orgId // Org members share memories -``` - -**BOTH (ask which):** - -```typescript -// Option A: Unique per user-org combination -containerTag: `${userId}-${orgId}` - -// Option B: Org-scoped with user metadata -containerTag: orgId, metadata: { userId } - -// Option C: User-scoped with org metadata -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, { - containerTags: [userId] - }) -}) -// 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.content).join('\n')}` : ''} -` - -// Send to LLM -const messages = [ - { role: 'system', content: `User context:\n${context}` }, - { role: 'user', content: userMessage } -] - -// After LLM responds: -await client.memories.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.content).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.memories.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}`, - 'Content-Type': 'application/json', - }, - 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 -await client.search({ - 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 diff --git a/apps/docs/introduction.mdx b/apps/docs/introduction.mdx deleted file mode 100644 index 89f2437d..00000000 --- a/apps/docs/introduction.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "Introduction" -description: "supermemory is the Memory API for the AI era" -mode: "custom" ---- - -export const HeroCard = ({ imageUrl, title, description, href }) => { - return ( - -
- {title} -
-
-

{title}

-

{description}

-
- - ) -} - -
- -
-

- supermemory [docs] -

- -

- Meet the memory API for the AI era — scalable, powerful, affordable, and production-ready. -

- -
- - - - - - - -
-
-
diff --git a/apps/docs/memory-api/connectors/advanced/bring-your-own-key.mdx b/apps/docs/memory-api/connectors/advanced/bring-your-own-key.mdx deleted file mode 100644 index 3d63cb46..00000000 --- a/apps/docs/memory-api/connectors/advanced/bring-your-own-key.mdx +++ /dev/null @@ -1,138 +0,0 @@ ---- -title: 'Bring Your Own Key (BYOK)' -description: 'Configure your own OAuth application credentials for enhanced security and control' ---- - -By default, supermemory uses its own OAuth applications to connect to third-party providers. However, you can configure your own OAuth application credentials for enhanced security and control. This is particularly useful for enterprise customers who want to maintain control over their data access. - - - Some providers like Google Drive require extensive verification and approval before you can use custom keys. - - -### Setting up Custom Provider Keys - -To configure custom OAuth credentials for your organization, use the `PATCH /v3/settings` endpoint: - -1. Set up your OAuth application on the provider's developer console. - -Google: https://console.developers.google.com/apis/credentials/oauthclient \ -Notion: https://www.notion.so/my-integrations \ -OneDrive: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationsMenu - -2. If using Google drive, - -- Select the application type as `Web application` -- **Enable the Google drive api in "APIs and Services" in the Cloud Console** - -3. Configure the redirect URL, set it to: - -``` -https://api.supermemory.ai/v3/connections/auth/callback/{provider} -``` - -For example, if you are using Google Drive, the redirect URL would be: - -``` -https://api.supermemory.ai/v3/connections/auth/callback/google-drive -``` - -4. Configure the client ID and client secret in the `PATCH /v3/settings` endpoint. - - -```typescript Typescript -import Supermemory from 'supermemory'; - -const client = new Supermemory({ - apiKey: process.env['SUPERMEMORY_API_KEY'], -}); - -// Example: Configure Google Drive custom OAuth credentials -const settings = await client.settings.update({ - googleCustomKeyEnabled: true, - googleDriveClientId: "your-google-client-id", - googleDriveClientSecret: "your-google-client-secret" -}); - -// Example: Configure Notion custom OAuth credentials -const settings = await client.settings.update({ - notionCustomKeyEnabled: true, - notionClientId: "your-notion-client-id", - notionClientSecret: "your-notion-client-secret" -}); - -// Example: Configure OneDrive custom OAuth credentials -const settings = await client.settings.update({ - onedriveCustomKeyEnabled: true, - onedriveClientId: "your-onedrive-client-id", - onedriveClientSecret: "your-onedrive-client-secret" -}); -``` - -```python Python -from supermemory import supermemory - -client = supermemory( - api_key=os.environ.get("SUPERMEMORY_API_KEY"), # This is the default and can be omitted -) - -# Example: Configure Google Drive custom OAuth credentials -settings = client.settings.update( - google_custom_key_enabled=True, - google_client_id="your-google-client-id", - google_client_secret="your-google-client-secret" -) - -# Example: Configure Notion custom OAuth credentials -settings = client.settings.update( - notion_custom_key_enabled=True, - notion_client_id="your-notion-client-id", - notion_client_secret="your-notion-client-secret" -) - -# Example: Configure OneDrive custom OAuth credentials -settings = client.settings.update( - onedrive_custom_key_enabled=True, - onedrive_client_id="your-onedrive-client-id", - onedrive_client_secret="your-onedrive-client-secret" -) -``` - -```bash cURL -# Example: Configure Google Drive custom OAuth credentials -curl --request PATCH \ - --url https://api.supermemory.ai/v3/settings \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "googleDriveCustomKeyEnabled": true, - "googleDriveClientId": "your-google-client-id", - "googleDriveClientSecret": "your-google-client-secret" -}' - -# Example: Configure Notion custom OAuth credentials -curl --request PATCH \ - --url https://api.supermemory.ai/v3/settings \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "notionCustomKeyEnabled": true, - "notionClientId": "your-notion-client-id", - "notionClientSecret": "your-notion-client-secret" -}' - -# Example: Configure OneDrive custom OAuth credentials -curl --request PATCH \ - --url https://api.supermemory.ai/v3/settings \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "onedriveCustomKeyEnabled": true, - "onedriveClientId": "your-onedrive-client-id", - "onedriveClientSecret": "your-onedrive-client-secret" -}' -``` - - - - Once you enable custom keys for a provider, all new connections for that provider will use your custom OAuth application. Existing connections WILL need to be re-authorized. - \ No newline at end of file diff --git a/apps/docs/memory-api/connectors/creating-connection.mdx b/apps/docs/memory-api/connectors/creating-connection.mdx deleted file mode 100644 index debabe7b..00000000 --- a/apps/docs/memory-api/connectors/creating-connection.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: 'Creating connections' -description: 'Create a connection to sync your content with supermemory' ---- - -To create a connection, just make a `POST` request to `/v3/connections/{provider}` - - -```typescript Typescript -import Supermemory from 'supermemory'; - -const client = new Supermemory({ - apiKey: process.env['SUPERMEMORY_API_KEY'], // This is the default and can be omitted -}); - -// For OAuth providers (notion, google-drive, onedrive) -const connection = await client.connections.create('notion'); -console.debug(connection.authLink); - -// For web-crawler (no OAuth required) -const webCrawlerConnection = await client.connections.create('web-crawler', { - metadata: { startUrl: 'https://docs.example.com' } -}); -console.debug(webCrawlerConnection.id); // authLink will be null -``` - -```python Python -import requests - -url = "https://api.supermemory.ai/v3/connections/{provider}" - -payload = { - "redirectUrl": "", - "containerTags": [""], - "metadata": {}, - "documentLimit": 5000 -} -headers = { - "Authorization": "Bearer ", - "Content-Type": "application/json" -} - -response = requests.request("POST", url, json=payload, headers=headers) - -print(response.text) -``` - -```bash cURL -curl --request POST \ - --url https://api.supermemory.ai/v3/connections/{provider} \ - --header 'Authorization: Bearer ' \ - --header 'Content-Type: application/json' \ - --data '{ - "redirectUrl": "", - "containerTags": [ - "" - ], - "metadata": {}, - "documentLimit": 5000 -}' -``` - - -### Parameters - -- `provider`: The provider to connect to. Currently supported providers are `notion`, `google-drive`, `onedrive`, `web-crawler` -- `redirectUrl`: The URL to redirect to after the connection is created (your app URL) - - Note: For `web-crawler`, this is optional as no OAuth flow is required -- `containerTags`: Optional. For partitioning users, organizations, etc. in your app. - - Example: `["user_123", "project_alpha"]` -- `metadata`: Optional. Any metadata you want to associate with the connection. - - This metadata is added to every document synced from this connection. - - For `web-crawler`, must include `startUrl` in metadata: `{"startUrl": "https://example.com"}` -- `documentLimit`: Optional. Caps how many provider items are fetched **per sync run** (allowed range **1–10,000** when set). Exact behavior is provider-specific. - - **Notion:** Pages come from the Notion Search API, **newest edited first**; once the limit is reached, remaining shareable pages are skipped until a later sync or a higher limit. See [Notion connector — Document limit](/connectors/notion#document-limit). - - Default when omitted depends on how the connection is created (often **10,000** for hosted flows). - - Use this to control scope and cost per sync. - - -## Response - -supermemory sends a response with the following schema: -```json -{ - "id": "", - "authLink": "", - "expiresIn": "", - "redirectsTo": "" -} -``` - -For most providers (notion, google-drive, onedrive), you can use the `authLink` to redirect the user to the provider's login page. - - -**Web Crawler Exception:** For `web-crawler` provider, `authLink` and `expiresIn` will be `null` since no OAuth flow is required. The connection is established immediately upon creation. - - -Next up, managing connections. diff --git a/apps/docs/memory-api/connectors/google-drive.mdx b/apps/docs/memory-api/connectors/google-drive.mdx deleted file mode 100644 index 8413fdd2..00000000 --- a/apps/docs/memory-api/connectors/google-drive.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: 'Google Drive' -description: 'Sync your Google Drive content with supermemory' ---- - -supermemory syncs Google Drive documents automatically and instantaneously. - -## Supported file types - -- Google Docs -- Google Slides -- Google Sheets - -## Conversions - -To import items, supermemory converts documents into markdown, and then ingests them into supermemory. -This conversion is lossy, and some formatting may be lost. - -## Sync frequency - -supermemory syncs documents: -- **A document is modified or created (Webhook recieved)** - - Note that not all providers are synced via webhook (Instant sync right now) - - `Google-Drive` and `Notion` documents are synced instantaneously -- Every **four hours** -- On **Manual Sync** (API call) - - You can call `/v3/connections/{provider}/sync` to sync documents manually diff --git a/apps/docs/memory-api/connectors/overview.mdx b/apps/docs/memory-api/connectors/overview.mdx deleted file mode 100644 index e7f9d479..00000000 --- a/apps/docs/memory-api/connectors/overview.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: 'Connectors Overview' -sidebarTitle: 'Overview' -description: 'Sync external connections like Google Drive, Notion, OneDrive, Web Crawler with supermemory' ---- - -supermemory can sync external connections like Google Drive, Notion, OneDrive, and Web Crawler. - -### The Flow - -For OAuth-based connectors (Notion, Google Drive, OneDrive): -1. Make a `POST` request to `/v3/connections/{provider}` -2. supermemory will return an `authLink` which you can redirect the user to -3. The user will be redirected to the provider's login page -4. User is redirected back to your app's `redirectUrl` - -For Web Crawler: -1. Make a `POST` request to `/v3/connections/web-crawler` with `startUrl` in metadata -2. Connection is established immediately (no OAuth required) -3. Crawling begins automatically - -![Connectors Flow](/images/connectors-flow.png) - -## Sync frequency - -supermemory syncs documents: -- **A document is modified or created (Webhook received)** - - Note that not all providers are synced via webhook (Instant sync right now) - - `Google-Drive` and `Notion` documents are synced instantaneously - - `Web-Crawler` uses scheduled recrawling instead of webhooks -- Every **four hours** (for OAuth-based connectors) -- **Scheduled recrawling** (for Web Crawler - sites recrawled if not synced in 7+ days) -- On **Manual Sync** (API call) - - You can call `/v3/connections/{provider}/sync` to sync documents manually diff --git a/apps/docs/memory-api/creation/adding-memories.mdx b/apps/docs/memory-api/creation/adding-memories.mdx deleted file mode 100644 index 4c6471e3..00000000 --- a/apps/docs/memory-api/creation/adding-memories.mdx +++ /dev/null @@ -1,374 +0,0 @@ ---- -title: "Adding Memories" -description: "Learn how to add content to supermemory" -icon: "plus" ---- - - -1. **Content Organization** - - **Use `containerTags` for grouping/partitioning** - - Optional tags (array of strings) to group memories. - - Can be a user ID, project ID, or any other identifier. - - Allows filtering for memories that share specific tags. - - Example: `["user_123", "project_alpha"]` - - Read more about [filtering](/memory-api/features/filtering) - -2. **Performance Tips** - - **Batch Operations** - - You can add multiple items in parallel - - Use different `containerTags` for different spaces - - Don't wait for processing to complete unless needed - - - **Search Optimization** - ```json - { - "q": "error logs", - "documentThreshold": 0.7, // Higher = more precise - "limit": 5, // Keep it small - "onlyMatchingChunks": true // Skip extra context if not needed - } - ``` - -3. **URL Content** - - Send clean URLs without tracking parameters - - Use article URLs, not homepage URLs - - Check URL accessibility before sending - - - -## Basic Usage - -To add a memory, send a POST request to `/add` with your content: - - - -```bash cURL -curl https://api.supermemory.ai/v3/documents \ - --request POST \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - --data '{ - "customId": "xyz-my-db-id", - "content": "This is the content of my memory", - "metadata": { - "category": "technology", - "tag_1": "ai", - "tag_2": "machine-learning", - }, - "containerTags": ["user_123", "project_xyz"] -}' -``` - -```typescript Typescript -await client.memory.create({ - customId: "xyz-mydb-id", - content: "This is the content of my memory", - metadata: { - category: "technology", - tag_1": "ai", - tag_2": "machine-learning", - }, - containerTags: ["user_123", "project_xyz"] -}) -``` - -```python Python -client.memory.create( - customId="xyz-mydb-id", - content="documents related to python", - metadata={ - "category": "datascience", - "tag_1": "ai", - "tag_2": "machine-learning", - }, - containerTags=["user_123", "project_xyz"] -) -``` - - - -The API will return a response with an ID and initial status: - -```json -{ - "id": "mem_abc123", - "status": "queued" -} -``` - - - -```bash cURL -curl https://api.supermemory.ai/v3/documents \ - --request POST \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - -d '{ - "content": "https://example.com/article", - "metadata": { - "source": "web", # Just example metadata - "category": "technology" # NOT required - }, - "containerTags": ["user_456", "research_papers"] - }' -``` - -```typescript Typescript -await client.memory.create({ - content: "https://example.com/article", - userId: "user_456", - metadata: { - source: "web", // Just example metadata - category: "technology", // NOT required - }, - containerTags: ["user_456", "research_papers"], -}); -``` - -```python Python -client.memory.create( - content="https://example.com/article", - userId="user_456", - metadata={ - "source": "web", - "category": "technology" - }, - containerTags=["user_456", "research_papers"] -) -``` - - - - -## Metadata and Organization - -You can add rich metadata to organize your content: - -```json -{ - "metadata": { - "source": "string", // String - "priority": 1234, // Custom numeric field - "custom_field": "any" // Any custom field - } -} -``` - - -## Partitioning by user - -You can attribute and partition your data by providing a `userId`: - - - -```bash cURL -curl https://api.supermemory.ai/v3/documents \ - --request POST \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - -d '{ - "content": "This is space-specific content", - "userId": "space_123", - "metadata": { - "category": "space-content" - } - }' -``` - -```typescript Typescript -await client.memory.create({ - content: "This is space-specific content", - userId: "space_123", - metadata: { - category: "space-content", - }, -}); -``` - -```python Python -client.memory.create( - content="This is space-specific content", - userId="space_123", - metadata={ - "category": "space-content" - } -) -``` - - - - - When searching, if you provide a `userId`, only memories from that space will - be returned. - - -## Grouping - -You can group memories by providing an array of `containerTags`: - - - -```bash cURL -curl https://api.supermemory.ai/v3/documents \ - --request POST \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - -d '{ - "content": "This is space-specific content", - "containerTags": ["user_123", "project_xyz"] - }' -``` - -```typescript Typescript -await client.memory.create({ - content: "This is space-specific content", - containerTags: ["user_123", "project_xyz"], -}); -``` - -```python Python -client.memory.create( - content="This is space-specific content", - containerTags=["user_123", "project_xyz"] -) -``` - - - -## Checking Status - -Check status using the memory ID: - - - -```bash cURL -curl https://api.supermemory.ai/v3/documents/mem_abc123 \ - --request GET \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' -``` - -```typescript Typescript -await client.memory.get("mem_abc123"); -``` - -```python Python -client.memory.get("mem_abc123") -``` - - - - - -Memories are deleted after 2 minutes if an irrecoverable error occurs. - - - -## File Uploads - -For file uploads, use the dedicated file upload endpoint. You can include `containerTags` directly in the form data: - - - -```bash cURL -curl https://api.supermemory.ai/v3/documents/file \ - --request POST \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - --form 'file=@/path/to/your/file.pdf' \ - --form 'containerTags=["user_123", "project_xyz"]' -``` - -```typescript Typescript -const formData = new FormData(); -formData.append("file", fileBlob); -formData.append("containerTags", JSON.stringify(["user_123", "project_xyz"])); - -const response = await fetch("https://api.supermemory.ai/v3/documents/file", { - method: "POST", - headers: { - Authorization: "Bearer SUPERMEMORY_API_KEY", - }, - body: formData, -}); -``` - -```python Python -import requests -import json - -with open('/path/to/your/file.pdf', 'rb') as f: - files = {'file': f} - data = {'containerTags': json.dumps(["user_123", "project_xyz"])} - response = requests.post( - 'https://api.supermemory.ai/v3/documents/file', - headers={'Authorization': 'Bearer SUPERMEMORY_API_KEY'}, - files=files, - data=data - ) -``` - - - -### Adding Additional Metadata to Files - -If you need to add additional metadata (like title or description) after upload, you can use the PATCH endpoint: - - - -```bash cURL -curl https://api.supermemory.ai/v3/documents/MEMORY_ID \ - --request PATCH \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - --data '{ - "metadata": { - "title": "My Document", - "description": "Important project document" - } - }' -``` - -```typescript Typescript -await fetch(`https://api.supermemory.ai/v3/documents/${memoryId}`, { - method: "PATCH", - headers: { - "Content-Type": "application/json", - Authorization: "Bearer SUPERMEMORY_API_KEY", - }, - body: JSON.stringify({ - metadata: { - title: "My Document", - description: "Important project document", - }, - }), -}); -``` - -```python Python -import requests - -requests.patch( - f'https://api.supermemory.ai/v3/documents/{memory_id}', - headers={ - 'Content-Type': 'application/json', - 'Authorization': 'Bearer SUPERMEMORY_API_KEY' - }, - json={ - 'metadata': { - 'title': 'My Document', - 'description': 'Important project document' - } - } -) -``` - - - - - Metadata-only PATCH updates the document in place—no reindexing. Use this when adding or changing metadata (e.g. `accepted`, `title`, `description`) without modifying the document content. - - -## Next Steps - -Explore more advanced features in our API Reference tab. diff --git a/apps/docs/memory-api/creation/status.mdx b/apps/docs/memory-api/creation/status.mdx deleted file mode 100644 index 44a53656..00000000 --- a/apps/docs/memory-api/creation/status.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: "Processing Status" -description: "Learn about the stages of content processing" ---- - -After adding content, you can check its processing status: - -1. `queued`: Content is queued for processing -2. `extracting`: Extracting content from source -3. `chunking`: Splitting content into semantic chunks -4. `embedding`: Generating vector embeddings -5. `indexing`: Adding to search index -6. `done`: Processing complete -7. `failed`: Processing failed \ No newline at end of file diff --git a/apps/docs/memory-api/features/auto-multi-modal.mdx b/apps/docs/memory-api/features/auto-multi-modal.mdx deleted file mode 100644 index df20c318..00000000 --- a/apps/docs/memory-api/features/auto-multi-modal.mdx +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: "Auto Multi Modal" -description: "supermemory automatically detects the content type of the document you are adding." -icon: "sparkles" ---- - -supermemory is natively multi-modal, and can automatically detect the content type of the document you are adding. - -We use the best of breed tools to extract content from URLs, and process it for optimal memory storage. - -## Automatic Content Type Detection - -supermemory automatically detects the content type of the document you're adding. Simply pass your content to the API, and supermemory will handle the rest. - - - - The content detection system analyzes: - - URL patterns and domains - - File extensions and MIME types - - Content structure and metadata - - Headers and response types - - - - 1. **Type Selection** - - Use `note` for simple text - - Use `webpage` for online content - - Use native types when possible - - 2. **URL Content** - - Send clean URLs without tracking parameters - - Use article URLs, not homepage URLs - - Check URL accessibility before sending - - - - - -### Quick Implementation - -All you need to do is pass the content to the `/documents` endpoint: - - - -```bash cURL -curl https://api.supermemory.ai/v3/documents \ - --request POST \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - -d '{"content": "https://example.com/article"}' -``` - -```typescript -await client.add.create({ - content: "https://example.com/article", -}); -``` - -```python -client.add.create( - content="https://example.com/article" -) -``` - - - - - supermemory uses [Markdowner](https://md.dhr.wtf) to extract content from - URLs. - - -## Supported Content Types - -supermemory supports a wide range of content formats to ensure versatility in memory creation: - - - - - `note`: Plain text notes and documents - - Directly processes raw text content - - Automatically chunks content for optimal retrieval - - Preserves formatting and structure - - - - - `webpage`: Web pages (just provide the URL) - - Intelligently extracts main content - - Preserves important metadata (title, description, images) - - Extracts OpenGraph metadata when available - - - `tweet`: Twitter content - - Captures tweet text, media, and metadata - - Preserves thread structure if applicable - - - - - - `pdf`: PDF files - - Extracts text content while maintaining structure - - Handles both searchable PDFs and scanned documents with OCR - - Preserves page breaks and formatting - - - `google_doc`: Google Documents - - Seamlessly integrates with Google Docs API - - Maintains document formatting and structure - - Auto-updates when source document changes - - - `notion_doc`: Notion pages - - Extracts content while preserving Notion's block structure - - Handles rich text formatting and embedded content - - - - - - `image`: Images with text content - - Advanced OCR for text extraction - - Visual content analysis and description - - - `video`: Video content - - Transcription and content extraction - - Key frame analysis - - - - -## Processing Pipeline - - - - supermemory automatically identifies the content type based on the input provided. - - - - Type-specific extractors process the content with: - Specialized parsing for - each format - Error handling with retries - Rate limit management - - - - ```typescript - interface ProcessedContent { - content: string; // Extracted text - summary?: string; // AI-generated summary - tags?: string[]; // Extracted tags - categories?: string[]; // Content categories - } - ``` - - - - - Sentence-level splitting - - 2-sentence overlap - - Context preservation - - Semantic coherence - - - -## Technical Specifications - -### Size Limits - -| Content Type | Max Size | -| ------------ | -------- | -| Text/Note | 1MB | -| PDF | 10MB | -| Image | 5MB | -| Video | 100MB | -| Web Page | N/A | -| Google Doc | N/A | -| Notion Page | N/A | -| Tweet | N/A | - -### Processing Time - -| Content Type | Processing Time | -| ------------ | --------------- | -| Text/Note | Almost instant | -| PDF | 1-5 seconds | -| Image | 2-10 seconds | -| Video | 10+ seconds | -| Web Page | 1-3 seconds | -| Google Doc | N/A | -| Notion Page | N/A | -| Tweet | N/A | diff --git a/apps/docs/memory-api/features/content-cleaner.mdx b/apps/docs/memory-api/features/content-cleaner.mdx deleted file mode 100644 index e586c3dc..00000000 --- a/apps/docs/memory-api/features/content-cleaner.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "Cleaning and Categorizing" -description: "Document Cleaning Summaries in supermemory" -icon: "washing-machine" ---- - -supermemory provides advanced configuration options to customize your content processing pipeline. At its core is an AI-powered system that can automatically analyze, categorize, and filter your content based on your specific needs. - -## Configuration Schema - -```json -{ - "shouldLLMFilter": true, - "categories": ["feature-request", "bug-report", "positive", "negative"], - "filterPrompt": "Analyze feedback sentiment and identify feature requests", - "includeItems": ["critical", "high-priority"], - "excludeItems": ["spam", "irrelevant"] -} -``` - -## Core Settings - -### shouldLLMFilter -- **Type**: `boolean` -- **Required**: No (defaults to `false`) -- **Description**: Master switch for AI-powered content analysis. Must be enabled to use any of the advanced filtering features. - -### categories -- **Type**: `string[]` -- **Limits**: Each category must be 1-50 characters -- **Required**: No -- **Description**: Define custom categories for content classification. When specified, the AI will only use these categories. If not specified, it will generate 3-5 relevant categories automatically. - -### filterPrompt -- **Type**: `string` -- **Limits**: 1-750 characters -- **Required**: No -- **Description**: Custom instructions for the AI on how to analyze and categorize content. Use this to guide the categorization process based on your specific needs. - -### includeItems & excludeItems -- **Type**: `string[]` -- **Limits**: Each item must be 1-20 characters -- **Required**: No -- **Description**: Fine-tune content filtering by specifying items to explicitly include or exclude during processing. - -## Content Processing Pipeline - -When content is ingested with LLM filtering enabled: - -1. **Initial Processing** - - Content is extracted and normalized - - Basic metadata (title, description) is captured - -2. **AI Analysis** - - Content is analyzed based on your `filterPrompt` - - Categories are assigned (either from your predefined list or auto-generated) - - Tags are evaluated and scored - -3. **Chunking & Indexing** - - Content is split into semantic chunks - - Each chunk is embedded for efficient search - - Metadata and classifications are stored - -## Example Use Cases - -### 1. Customer Feedback System -```json -{ - "shouldLLMFilter": true, - "categories": ["positive", "negative", "neutral"], - "filterPrompt": "Analyze customer sentiment and identify key themes", -} -``` - -### 2. Content Moderation -```json -{ - "shouldLLMFilter": true, - "categories": ["safe", "needs-review", "flagged"], - "filterPrompt": "Identify potentially inappropriate or sensitive content", - "excludeItems": ["spam", "offensive"], - "includeItems": ["user-generated"] -} -``` - -> **Important**: All filtering features (`categories`, `filterPrompt`, `includeItems`, `excludeItems`) require `shouldLLMFilter` to be enabled. Attempting to use these features without enabling `shouldLLMFilter` will result in a 400 error. diff --git a/apps/docs/memory-api/features/filtering.mdx b/apps/docs/memory-api/features/filtering.mdx deleted file mode 100644 index e7e3a14d..00000000 --- a/apps/docs/memory-api/features/filtering.mdx +++ /dev/null @@ -1,297 +0,0 @@ ---- -title: "Filtering" -description: "Learn how to filter content while searching from supermemory" -icon: "list-filter-plus" ---- - -## Container Tag - -Container tag is an identifier for your end users, to group memories together.. - -This can be: -- A user using your product -- An organization using a SaaS - -A project ID, or even a dynamic one like `user_project_etc` - -We recommend using single containerTag in all API requests. - -The graph is built on top of the Container Tags. For example, each user / tag in your supermemory account will have one single graph built for them. - - - -```bash cURL -curl https://api.supermemory.ai/v3/search \ - --request POST \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - --data '{ - "q": "machine learning", - "containerTags": ["user_123"] - }' -``` - -```typescript Typescript -await client.search.execute({ - q: "machine learning", - containerTags: ["user_123"], -}); -``` - -```python Python -client.search.execute( - q="machine learning", - containerTags=["user_123"] -) -``` - - - -## Metadata - -Sometimes, you might want to add metadata and do advanced filtering based on it. - -Using metadata filtering, you can search based on: - -- AND and OR conditions -- String matching -- Numeric matching -- Date matching -- Time range queries - -### Validation Rules & Limits - -To ensure optimal performance and security, the filtering system has the following limits: - -- **Metadata keys**: Must contain only alphanumeric characters, underscores, and hyphens (`/^[a-zA-Z0-9_-]+$/`) -- **Metadata key length**: Maximum of 64 characters -- **Maximum conditions**: Up to 200 conditions per query -- **Maximum nesting depth**: Up to 8 levels of nested AND/OR expressions -- **Valid operators**: `=`, `!=`, `<`, `<=`, `>`, `>=` for numeric filtering - - -These limits help prevent overly complex queries that could impact performance. If you need to filter on more conditions, consider breaking your query into multiple requests or using broader search terms with post-processing. - - - - -```bash cURL -curl https://api.supermemory.ai/v3/search \ - --request POST \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - --data '{ - "q": "machine learning", - "filters": { - "AND": [ - { - "key": "category", - "value": "technology", - "negate": false - }, - { - "filterType": "numeric", - "key": "readingTime", - "value": "5", - "negate": false, - "numericOperator": "<=" - } - ] - } -}' -``` - -```typescript Typescript -await client.search.execute({ - q: "machine learning", - filters: { - AND: [ - { - key: "category", - value: "technology", - negate: false, - }, - { - filterType: "numeric", - key: "readingTime", - value: "5", - negate: false, - numericOperator: "<=", - }, - ], - }, -}); -``` - -```python Python -client.search.execute( - q="machine learning", - filters={ - "AND": [ - { - "key": "category", - "value": "technology", - "negate": false - }, - { - "filterType": "numeric", - "key": "readingTime", - "value": "5", - "negate": false, - "numericOperator": "<=" - } - ] - } -) -``` - - - -## Array Contains Filtering - -You can filter memories by array values using the `array_contains` filter type. This is particularly useful for filtering by participants or other array-based metadata. - -First, create a memory with participants in the metadata: - - - -```bash cURL -curl --location 'https://api.supermemory.ai/v3/documents' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ ---data '{ - "content": "quarterly planning meeting discussion", - "metadata": { - "participants": ["john.doe", "sarah.smith", "mike.wilson"] - } - }' -``` - -```typescript Typescript -await client.documents.create({ - content: "quarterly planning meeting discussion", - metadata: { - participants: ["john.doe", "sarah.smith", "mike.wilson"] - } -}); -``` - -```python Python -client.documents.create( - content="quarterly planning meeting discussion", - metadata={ - "participants": ["john.doe", "sarah.smith", "mike.wilson"] - } -) -``` - - - -Then search using the `array_contains` filter: - - - -```bash cURL -curl --location 'https://api.supermemory.ai/v3/search' \ ---header 'Content-Type: application/json' \ ---header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ ---data '{ - "q": "meeting", - "filters": { - "AND": [ - { - "key": "participants", - "value": "john.doe", - "filterType": "array_contains" - } - ] - }, - "limit": 5 - }' -``` - -```typescript Typescript -await client.search.execute({ - q: "meeting", - filters: { - AND: [ - { - key: "participants", - value: "john.doe", - filterType: "array_contains" - } - ] - }, - limit: 5 -}); -``` - -```python Python -client.search.execute( - q="meeting", - filters={ - "AND": [ - { - "key": "participants", - "value": "john.doe", - "filterType": "array_contains" - } - ] - }, - limit=5 -) -``` - - - -## Migration Notes - - -**Breaking Changes**: Recent updates to the filtering system have introduced stricter validation rules. If you're experiencing filter validation errors, please check the following: - -1. **Metadata Key Format**: Ensure all metadata keys only contain alphanumeric characters, underscores, and hyphens. Keys with spaces, dots, or other special characters will now fail validation. - -2. **Key Length**: Metadata keys must be 64 characters or fewer. - -3. **Filter Complexity**: Queries with more than 200 conditions or more than 8 levels of nesting will be rejected. - -**Example of invalid keys that need updating**: -- `"user.email"` → `"user_email"` -- `"reading time"` → `"reading_time"` -- `"category-with-very-long-name-that-exceeds-the-limit"` → `"category_name"` - - -## Document - -You can also find chunks within a specific, large document. - -This can be particularly useful for extremely large documents like Books, Podcasts, etc. - - - -```bash cURL -curl https://api.supermemory.ai/v3/search \ - --request POST \ - --header 'Content-Type: application/json' \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - --data '{ - "q": "machine learning", - "docId": "doc_123" - }' -``` - -```typescript Typescript -await client.search.execute({ - q: "machine learning", - docId: "doc_123", -}); -``` - -```python Python -client.search.execute( - q="machine learning", - docId="doc_123" -) -``` - - diff --git a/apps/docs/memory-api/features/query-rewriting.mdx b/apps/docs/memory-api/features/query-rewriting.mdx deleted file mode 100644 index 9508297a..00000000 --- a/apps/docs/memory-api/features/query-rewriting.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: "Query Rewriting" -description: "Query Rewriting in supermemory" -icon: "blend" ---- - -Query Rewriting is a feature that allows you to rewrite queries to make them more accurate. - -![Query Rewriting](/images/query-rewriting.png) - -### Usage - -In supermemory, you can enable query rewriting by setting the `rewriteQuery` parameter to `true` in the search API. - - - -```bash cURL -curl https://api.supermemory.ai/v3/search \ - --request POST \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - --header 'Content-Type: application/json' \ - -d '{ - "q": "What is the capital of France?", - "rewriteQuery": true - }' -``` - -```typescript -await client.search.create({ - q: "What is the capital of France?", - rewriteQuery: true, -}); -``` - -```python -client.search.create( - q="What is the capital of France?", - rewriteQuery=True -) -``` - - - -### Notes and limitations - -- supermemory generates multiple rewrites, and runs the search through all of them. -- The results are then merged and returned to you. -- There is no additional costs associated with query rewriting. -- While query rewriting makes the quality much better, it also **incurs additional latency**. -- All other features like filtering, hybrid search, recency bias, etc. work with rewritten results as well. diff --git a/apps/docs/memory-api/features/reranking.mdx b/apps/docs/memory-api/features/reranking.mdx deleted file mode 100644 index 1df8a9c5..00000000 --- a/apps/docs/memory-api/features/reranking.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: "Reranking" -description: "Reranked search results in supermemory" -icon: "chart-bar-increasing" ---- - -Reranking is a feature that allows you to rerank search results based on the query. - -![Reranking](/images/rerank.png) - -### Usage - -In supermemory, you can enable answer rewriting by setting the `rerank` parameter to `true` in the search API. - - - -```bash cURL -curl https://api.supermemory.ai/v3/search?q=What+is+the+capital+of+France?&rerank=true \ - --request GET \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' -``` - -```typescript -await client.search.create({ - q: "What is the capital of France?", - rerank: true, -}); -``` - -```python -client.search.create( - q="What is the capital of France?", - rerank=True -) -``` - - - -### Notes and limitations - -- We currently use `bge-reranker-base` model for reranking. -- There is no additional costs associated with reranking. -- While reranking makes the quality much better, it also **incurs additional latency**. -- All other features like filtering, hybrid search, recency bias, etc. work with reranked results as well. diff --git a/apps/docs/memory-api/introduction.mdx b/apps/docs/memory-api/introduction.mdx deleted file mode 100644 index 24a46f8b..00000000 --- a/apps/docs/memory-api/introduction.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Introduction - Memory endpoints" -sidebarTitle: "Introduction" -description: "Ingest content at scale, in any format." ---- - -**supermemory** automatically **ingests and processes your data**, and makes it searchable. - - - The Memory engine scales linearly - which means we're **incredibly fast and scalable**, while providing one of the more affordable - - -![supermemory](/images/processing.png) - -It also gives you features like: - -- [Connectors and Syncing](/memory-api/connectors/) -- [Multimodality](/memory-api/features/auto-multi-modal) -- [Advanced Filtering](/memory-api/features/filtering) -- [Reranking](/memory-api/features/reranking) -- [Extracting details from text](/memory-api/features/content-cleaner) -- [Query Rewriting](/memory-api/features/query-rewriting) - -... and lots more\! - - -Check out the following resources to get started: - - - - - Get started in 5 minutes - - - Learn more about the API - - - See what supermemory can do for you - - - Learn more about the SDKs - - \ No newline at end of file diff --git a/apps/docs/memory-api/sdks/anthropic-claude-memory.mdx b/apps/docs/memory-api/sdks/anthropic-claude-memory.mdx deleted file mode 100644 index 10bc195b..00000000 --- a/apps/docs/memory-api/sdks/anthropic-claude-memory.mdx +++ /dev/null @@ -1,375 +0,0 @@ ---- -title: "Claude Memory Tool" -description: "Enable Claude's persistent memory capabilities with Supermemory as the backend" ---- - -Enable Claude's native memory tool functionality with Supermemory as the persistent storage backend. Claude can automatically store and retrieve information across conversations using familiar filesystem operations. - - - Check out the NPM page for more details - - -## Installation - -```bash -npm install @supermemory/tools @anthropic-ai/sdk -``` - -## Quick Start - -```typescript -import Anthropic from "@anthropic-ai/sdk" -import { createClaudeMemoryTool } from "@supermemory/tools/claude-memory" - -const anthropic = new Anthropic({ - apiKey: process.env.ANTHROPIC_API_KEY!, -}) - -const memoryTool = createClaudeMemoryTool(process.env.SUPERMEMORY_API_KEY!, { - projectId: 'my-app', -}) - -async function chatWithMemory(userMessage: string) { - const response = await anthropic.beta.messages.create({ - model: 'claude-sonnet-4-5', - max_tokens: 8096, - tools: [{ type: 'memory_20250818', name: 'memory' }], - betas: ['context-management-2025-06-27'], - messages: [{ role: 'user', content: userMessage }], - }) - - // Handle memory tool calls - for (const block of response.content) { - if (block.type === 'tool_use' && block.name === 'memory') { - const result = await memoryTool.handleCommandForToolResult( - block.input as MemoryCommand, - block.id - ) - console.log('Memory operation result:', result) - } - } - - return response -} -``` - -## How It Works - -Claude's memory tool uses a filesystem metaphor to manage persistent information: - -- **Files**: Individual memory items stored as Supermemory documents -- **Directories**: Organized using path structure (e.g., `/memories/user-preferences`) -- **Operations**: View, create, edit, delete, and rename files -- **Path Normalization**: Paths like `/memories/preferences` are stored as `--memories--preferences` - -## Configuration - -### Basic Configuration - -```typescript -import { createClaudeMemoryTool } from "@supermemory/tools/claude-memory" - -const memoryTool = createClaudeMemoryTool( - process.env.SUPERMEMORY_API_KEY!, - { - projectId: 'my-app', // Project identifier - baseUrl: 'https://api.supermemory.ai', // Optional: custom API endpoint - } -) -``` - -### Using Container Tags - -```typescript -const memoryTool = createClaudeMemoryTool( - process.env.SUPERMEMORY_API_KEY!, - { - containerTags: ['user:alice', 'app:chat'], - } -) -``` - -## Memory Operations - -Claude automatically performs these operations when managing memory: - -### View Files - -List directory contents or read file contents: - -```typescript -// Claude will automatically check /memories/ directory -// This maps to searching Supermemory documents with path prefix -``` - -### Create Files - -Store new information: - -```typescript -// Claude creates: /memories/user-preferences.txt -// Stored as document with customId: "--memories--user-preferences.txt" -``` - -### Edit Files - -Update existing memories using string replacement: - -```typescript -// Claude performs str_replace on file contents -// Updates the corresponding Supermemory document -``` - -### Delete Files - -Remove information: - -```typescript -// Claude deletes: /memories/old-data.txt -// Removes document from Supermemory -``` - -### Rename Files - -Reorganize memory structure: - -```typescript -// Claude renames: /memories/temp.txt -> /memories/final.txt -// Updates document customId in Supermemory -``` - -## Complete Chat Example - -Here's a full example with conversation handling: - -```typescript -import Anthropic from "@anthropic-ai/sdk" -import { createClaudeMemoryTool, type MemoryCommand } from "@supermemory/tools/claude-memory" - -const anthropic = new Anthropic({ - apiKey: process.env.ANTHROPIC_API_KEY!, -}) - -const memoryTool = createClaudeMemoryTool(process.env.SUPERMEMORY_API_KEY!, { - projectId: 'chat-app', -}) - -async function chat() { - const messages: Anthropic.MessageParam[] = [] - - // First message: store information - messages.push({ - role: 'user', - content: 'Remember that I prefer dark mode and use TypeScript' - }) - - let response = await anthropic.beta.messages.create({ - model: 'claude-sonnet-4-5', - max_tokens: 8096, - tools: [{ type: 'memory_20250818', name: 'memory' }], - betas: ['context-management-2025-06-27'], - messages, - }) - - // Process tool calls - const toolResults: Anthropic.ToolResultBlockParam[] = [] - - for (const block of response.content) { - if (block.type === 'tool_use' && block.name === 'memory') { - const result = await memoryTool.handleCommandForToolResult( - block.input as MemoryCommand, - block.id - ) - toolResults.push(result) - } - } - - // Continue conversation with tool results - if (toolResults.length > 0) { - messages.push({ role: 'assistant', content: response.content }) - messages.push({ role: 'user', content: toolResults }) - - response = await anthropic.beta.messages.create({ - model: 'claude-sonnet-4-5', - max_tokens: 8096, - tools: [{ type: 'memory_20250818', name: 'memory' }], - betas: ['context-management-2025-06-27'], - messages, - }) - } - - console.log(response.content) -} - -chat() -``` - -## Advanced Usage - -### Custom Path Management - -Control where Claude stores information: - -```typescript -// Claude automatically organizes by path -// /memories/preferences/editor.txt -// /memories/projects/current.txt -// /memories/notes/meeting-2024.txt - -// Each path is normalized and stored with appropriate metadata -``` - -### Error Handling - -Handle operations gracefully: - -```typescript -const result = await memoryTool.handleCommandForToolResult(command, toolUseId) - -if (result.is_error) { - console.error('Memory operation failed:', result.content) - // Handle error appropriately -} else { - console.log('Success:', result.content) -} -``` - -### Monitoring Operations - -Track memory operations: - -```typescript -for (const block of response.content) { - if (block.type === 'tool_use' && block.name === 'memory') { - console.log('Operation:', block.input.command) - console.log('Path:', block.input.path) - - const result = await memoryTool.handleCommandForToolResult( - block.input as MemoryCommand, - block.id - ) - - console.log('Result:', result.is_error ? 'Failed' : 'Success') - } -} -``` - -## Memory Organization - -### Best Practices - -1. **Use Descriptive Paths**: `/memories/user-preferences/theme.txt` is better than `/mem1.txt` -2. **Organize by Category**: Group related information under directories -3. **Keep Files Focused**: Store specific information in separate files -4. **Use Clear Naming**: Make file names self-explanatory - -### Path Structure Examples - -``` -/memories/ - ├── user-profile/ - │ ├── name.txt - │ ├── preferences.txt - │ └── settings.txt - ├── projects/ - │ ├── current-task.txt - │ └── goals.txt - └── notes/ - ├── meeting-notes.txt - └── ideas.txt -``` - -## API Reference - -### `createClaudeMemoryTool(apiKey, config)` - -Creates a memory tool instance for Claude. - -**Parameters:** -- `apiKey` (string): Your Supermemory API key -- `config` (optional): - - `projectId` (string): Project identifier - - `containerTags` (string[]): Alternative to projectId - - `baseUrl` (string): Custom API endpoint - -**Returns:** `ClaudeMemoryTool` instance - -### `handleCommandForToolResult(command, toolUseId)` - -Processes a memory command and returns formatted result. - -**Parameters:** -- `command` (MemoryCommand): The memory operation from Claude -- `toolUseId` (string): Tool use ID from Claude's response - -**Returns:** `Promise` with: -- `type`: "tool_result" -- `tool_use_id`: The tool use ID -- `content`: Operation result or error message -- `is_error`: Boolean indicating success/failure - -## Memory Commands - -Claude uses these command types internally: - -| Command | Description | Example | -|---------|-------------|---------| -| `view` | List directory or read file | `/memories/` or `/memories/file.txt` | -| `create` | Create new file | Create `/memories/new.txt` with content | -| `str_replace` | Edit file contents | Replace "old text" with "new text" | -| `insert` | Add content at line | Insert at line 5 | -| `delete` | Remove file | Delete `/memories/old.txt` | -| `rename` | Rename/move file | Rename `old.txt` to `new.txt` | - -## Environment Variables - -```bash -ANTHROPIC_API_KEY=your_anthropic_key -SUPERMEMORY_API_KEY=your_supermemory_key -``` - -## When to Use - -The Claude Memory Tool is ideal for: - -- **Conversational AI**: Claude automatically remembers user preferences and context -- **Personal Assistants**: Store and retrieve user-specific information -- **Documentation Bots**: Maintain knowledge across conversations -- **Project Management**: Track tasks and project state -- **Note-Taking Apps**: Persistent memory for meeting notes and ideas - -## Comparison with Other Approaches - -| Feature | Claude Memory Tool | OpenAI SDK Tools | AI SDK Tools | -|---------|-------------------|------------------|--------------| -| Automatic Memory | ✅ Claude decides | ❌ Manual control | ❌ Manual control | -| Filesystem Metaphor | ✅ Files/directories | ❌ Flat storage | ❌ Flat storage | -| Path Organization | ✅ Hierarchical | ❌ Tags only | ❌ Tags only | -| Integration | Anthropic SDK only | OpenAI SDK only | Vercel AI SDK | - -## Limitations - -- Requires Anthropic SDK with beta features enabled -- Path separators (`/`) are normalized to `--` for storage -- Maximum 100 files per directory listing -- File operations are asynchronous - -## Next Steps - - - - Use memory tools with OpenAI function calling - - - - Integrate with Vercel AI SDK - - - - Direct API access for advanced control - - - - See real-world examples - - \ No newline at end of file diff --git a/apps/docs/memory-api/sdks/python.mdx b/apps/docs/memory-api/sdks/python.mdx deleted file mode 100644 index 0888f2b0..00000000 --- a/apps/docs/memory-api/sdks/python.mdx +++ /dev/null @@ -1,349 +0,0 @@ ---- -title: 'Python SDK' -sidebarTitle: "Python" -description: 'Learn how to use supermemory with Python' ---- - -## Installation - -```sh -# install from PyPI -pip install --pre supermemory -``` - -## Usage - - -```python -import os -from supermemory import Supermemory - -client = Supermemory( - api_key=os.environ.get("SUPERMEMORY_API_KEY"), # This is the default and can be omitted -) - -response = client.search.execute( - q="documents related to python", -) -print(response.results) -``` - -While you can provide an `api_key` keyword argument, -we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/) -to add `SUPERMEMORY_API_KEY="My API Key"` to your `.env` file -so that your API Key is not stored in source control. - -## Async usage - -Simply import `AsyncSupermemory` instead of `Supermemory` and use `await` with each API call: - -```python -import os -import asyncio -from supermemory import AsyncSupermemory - -client = AsyncSupermemory( - api_key=os.environ.get("SUPERMEMORY_API_KEY"), # This is the default and can be omitted -) - - -async def main() -> None: - response = await client.search.execute( - q="documents related to python", - ) - print(response.results) - - -asyncio.run(main()) -``` - -Functionality between the synchronous and asynchronous clients is otherwise identical. - -## Using types - -Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev) which also provide helper methods for things like: - -- Serializing back into JSON, `model.to_json()` -- Converting to a dictionary, `model.to_dict()` - -Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`. - -## File uploads - -Request parameters that correspond to file uploads can be passed as `bytes`, or a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance or a tuple of `(filename, contents, media type)`. - -```python -from pathlib import Path -from supermemory import Supermemory - -client = Supermemory() - -client.documents.upload_file( - file=Path("/path/to/file"), -) -``` - -The async client uses the exact same interface. If you pass a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance, the file contents will be read asynchronously automatically. - -## Handling errors - -When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `supermemory.APIConnectionError` is raised. - -When the API returns a non-success status code (that is, 4xx or 5xx -response), a subclass of `supermemory.APIStatusError` is raised, containing `status_code` and `response` properties. - -All errors inherit from `supermemory.APIError`. - -```python -import supermemory -from supermemory import Supermemory - -client = Supermemory() - -try: - client.add( - content="This is a detailed article about machine learning concepts...", - ) -except supermemory.APIConnectionError as e: - print("The server could not be reached") - print(e.__cause__) # an underlying Exception, likely raised within httpx. -except supermemory.RateLimitError as e: - print("A 429 status code was received; we should back off a bit.") -except supermemory.APIStatusError as e: - print("Another non-200-range status code was received") - print(e.status_code) - print(e.response) -``` - -Error codes are as follows: - -| Status Code | Error Type | -| ----------- | -------------------------- | -| 400 | `BadRequestError` | -| 401 | `AuthenticationError` | -| 403 | `PermissionDeniedError` | -| 404 | `NotFoundError` | -| 422 | `UnprocessableEntityError` | -| 429 | `RateLimitError` | -| >=500 | `InternalServerError` | -| N/A | `APIConnectionError` | - -### Retries - -Certain errors are automatically retried 2 times by default, with a short exponential backoff. -Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, -429 Rate Limit, and >=500 Internal errors are all retried by default. - -You can use the `max_retries` option to configure or disable retry settings: - -```python -from supermemory import Supermemory - -# Configure the default for all requests: -client = Supermemory( - # default is 2 - max_retries=0, -) - -# Or, configure per-request: -client.with_options(max_retries=5).documents.add( - content="This is a detailed article about machine learning concepts...", -) -``` - -### Timeouts - -By default requests time out after 1 minute. You can configure this with a `timeout` option, -which accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/#fine-tuning-the-configuration) object: - -```python -from supermemory import Supermemory - -# Configure the default for all requests: -client = Supermemory( - # 20 seconds (default is 1 minute) - timeout=20.0, -) - -# More granular control: -client = Supermemory( - timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0), -) - -# Override per-request: -client.with_options(timeout=5.0).documents.add( - content="This is a detailed article about machine learning concepts...", -) -``` - -On timeout, an `APITimeoutError` is thrown. - -Note that requests that time out are [retried twice by default](#retries). - -## Advanced - -### Logging - -We use the standard library [`logging`](https://docs.python.org/3/library/logging.html) module. - -You can enable logging by setting the environment variable `SUPERMEMORY_LOG` to `info`. - -```shell -$ export SUPERMEMORY_LOG=info -``` - -Or to `debug` for more verbose logging. - -### How to tell whether `None` means `null` or missing - -In an API response, a field may be explicitly `null`, or missing entirely; in either case, its value is `None` in this library. You can differentiate the two cases with `.model_fields_set`: - -```py -if response.my_field is None: - if 'my_field' not in response.model_fields_set: - print('Got json like {}, without a "my_field" key present at all.') - else: - print('Got json like {"my_field": null}.') -``` - -### Accessing raw response data (e.g. headers) - -The "raw" Response object can be accessed by prefixing `.with_raw_response.` to any HTTP method call, e.g., - -```py -from supermemory import Supermemory - -client = Supermemory() -response = client.documents.with_raw_response.add( - content="This is a detailed article about machine learning concepts...", -) -print(response.headers.get('X-My-Header')) - -memory = response.parse() # get the object that `documents.add()` would have returned -print(memory.id) -``` - -These methods return an [`APIResponse`](https://github.com/supermemoryai/python-sdk/tree/main/src/supermemory/_response.py) object. - -The async client returns an [`AsyncAPIResponse`](https://github.com/supermemoryai/python-sdk/tree/main/src/supermemory/_response.py) with the same structure, the only difference being `await`able methods for reading the response content. - -#### `.with_streaming_response` - -The above interface eagerly reads the full response body when you make the request, which may not always be what you want. - -To stream the response body, use `.with_streaming_response` instead, which requires a context manager and only reads the response body once you call `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` or `.parse()`. In the async client, these are async methods. - -```python -with client.documents.with_streaming_response.add( - content="This is a detailed article about machine learning concepts...", -) as response: - print(response.headers.get("X-My-Header")) - - for line in response.iter_lines(): - print(line) -``` - -The context manager is required so that the response will reliably be closed. - -### Making custom/undocumented requests - -This library is typed for convenient access to the documented API. - -If you need to access undocumented endpoints, params, or response properties, the library can still be used. - -#### Undocumented endpoints - -To make requests to undocumented endpoints, you can make requests using `client.get`, `client.post`, and other -http verbs. Options on the client will be respected (such as retries) when making this request. - -```py -import httpx - -response = client.post( - "/foo", - cast_to=httpx.Response, - body={"my_param": True}, -) - -print(response.headers.get("x-foo")) -``` - -#### Undocumented request params - -If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` request -options. - -#### Undocumented response properties - -To access undocumented response properties, you can access the extra fields like `response.unknown_prop`. You -can also get all the extra fields on the Pydantic model as a dict with -[`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra). - -### Configuring the HTTP client - -You can directly override the [httpx client](https://www.python-httpx.org/api/#client) to customize it for your use case, including: - -- Support for [proxies](https://www.python-httpx.org/advanced/proxies/) -- Custom [transports](https://www.python-httpx.org/advanced/transports/) -- Additional [advanced](https://www.python-httpx.org/advanced/clients/) functionality - -```python -import httpx -from supermemory import Supermemory, DefaultHttpxClient - -client = Supermemory( - # Or use the `SUPERMEMORY_BASE_URL` env var - base_url="http://my.test.server.example.com:8083", - http_client=DefaultHttpxClient( - proxy="http://my.test.proxy.example.com", - transport=httpx.HTTPTransport(local_address="0.0.0.0"), - ), -) -``` - -You can also customize the client on a per-request basis by using `with_options()`: - -```python -client.with_options(http_client=DefaultHttpxClient(...)) -``` - -### Managing HTTP resources - -By default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting. - -```py -from supermemory import Supermemory - -with Supermemory() as client: - # make requests here - ... - -# HTTP client is now closed -``` - -## Versioning - -This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions: - -1. Changes that only affect static types, without breaking runtime behavior. -2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_ -3. Changes that we do not expect to impact the vast majority of users in practice. - -We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience. - -We are keen for your feedback; please open an [issue](https://www.github.com/supermemoryai/python-sdk/issues) with questions, bugs, or suggestions. - -### Determining the installed version - -If you've upgraded to the latest version but aren't seeing any new features you were expecting then your python environment is likely still using an older version. - -You can determine the version that is being used at runtime with: - -```py -import supermemory -print(supermemory.__version__) -``` - -## Requirements - -Python 3.8 or higher. diff --git a/apps/docs/memory-api/sdks/supermemory-npm.mdx b/apps/docs/memory-api/sdks/supermemory-npm.mdx deleted file mode 100644 index c872458a..00000000 --- a/apps/docs/memory-api/sdks/supermemory-npm.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "`supermemory` on npm" -url: "https://www.npmjs.com/package/supermemory" -icon: npm ---- diff --git a/apps/docs/memory-api/sdks/supermemory-pypi.mdx b/apps/docs/memory-api/sdks/supermemory-pypi.mdx deleted file mode 100644 index 1b831245..00000000 --- a/apps/docs/memory-api/sdks/supermemory-pypi.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "`supermemory` on pypi" -url: "https://pypi.org/project/supermemory/" -icon: python ---- diff --git a/apps/docs/memory-api/sdks/typescript.mdx b/apps/docs/memory-api/sdks/typescript.mdx deleted file mode 100644 index d6670b10..00000000 --- a/apps/docs/memory-api/sdks/typescript.mdx +++ /dev/null @@ -1,391 +0,0 @@ ---- -title: 'Typescript SDK' -sidebarTitle: "Typescript" -description: 'Learn how to use supermemory with Typescript' ---- - -## Installation - -```sh -npm install supermemory -``` - -## Usage - -```js -import Supermemory from 'supermemory'; - -const client = new Supermemory({ - apiKey: process.env['SUPERMEMORY_API_KEY'], // This is the default and can be omitted -}); - -async function main() { - const response = await client.search.execute({ q: 'documents related to python' }); - - console.debug(response.results); -} - -main(); -``` - -### Request & Response types - -This library includes TypeScript definitions for all request params and response fields. You may import and use them like so: - - -```ts -import Supermemory from 'supermemory'; - -const client = new Supermemory({ - apiKey: process.env['SUPERMEMORY_API_KEY'], // This is the default and can be omitted -}); - -async function main() { - const params: Supermemory.AddParams = { - content: 'This is a detailed article about machine learning concepts...', - }; - const response: Supermemory.AddResponse = await client.add(params); -} - -main(); -``` - -Documentation for each method, request param, and response field are available in docstrings and will appear on hover in most modern editors. - -## File uploads - -Request parameters that correspond to file uploads can be passed in many different forms: - -- `File` (or an object with the same structure) -- a `fetch` `Response` (or an object with the same structure) -- an `fs.ReadStream` -- the return value of our `toFile` helper - -```ts -import fs from 'fs'; -import Supermemory, { toFile } from 'supermemory'; - -const client = new Supermemory(); - -// If you have access to Node `fs` we recommend using `fs.createReadStream()`: -await client.documents.uploadFile({ file: fs.createReadStream('/path/to/file') }); - -// Or if you have the web `File` API you can pass a `File` instance: -await client.documents.uploadFile({ file: new File(['my bytes'], 'file') }); - -// You can also pass a `fetch` `Response`: -await client.documents.uploadFile({ file: await fetch('https://somesite/file') }); - -// Finally, if none of the above are convenient, you can use our `toFile` helper: -await client.documents.uploadFile({ file: await toFile(Buffer.from('my bytes'), 'file') }); -await client.documents.uploadFile({ file: await toFile(new Uint8Array([0, 1, 2]), 'file') }); -``` - -## Handling errors - -When the library is unable to connect to the API, -or if the API returns a non-success status code (i.e., 4xx or 5xx response), -a subclass of `APIError` will be thrown: - - -```ts -async function main() { - const response = await client.documents - .add({ content: 'This is a detailed article about machine learning concepts...' }) - .catch(async (err) => { - if (err instanceof supermemory.APIError) { - console.debug(err.status); // 400 - console.debug(err.name); // BadRequestError - console.debug(err.headers); // {server: 'nginx', ...} - } else { - throw err; - } - }); -} - -main(); -``` - -Error codes are as follows: - -| Status Code | Error Type | -| ----------- | -------------------------- | -| 400 | `BadRequestError` | -| 401 | `AuthenticationError` | -| 403 | `PermissionDeniedError` | -| 404 | `NotFoundError` | -| 422 | `UnprocessableEntityError` | -| 429 | `RateLimitError` | -| >=500 | `InternalServerError` | -| N/A | `APIConnectionError` | - -### Retries - -Certain errors will be automatically retried 2 times by default, with a short exponential backoff. -Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, -429 Rate Limit, and >=500 Internal errors will all be retried by default. - -You can use the `maxRetries` option to configure or disable this: - - -```js -// Configure the default for all requests: -const client = new Supermemory({ - maxRetries: 0, // default is 2 -}); - -// Or, configure per-request: -await client.add({ content: 'This is a detailed article about machine learning concepts...' }, { - maxRetries: 5, -}); -``` - -### Timeouts - -Requests time out after 1 minute by default. You can configure this with a `timeout` option: - - -```ts -// Configure the default for all requests: -const client = new Supermemory({ - timeout: 20 * 1000, // 20 seconds (default is 1 minute) -}); - -// Override per-request: -await client.add({ content: 'This is a detailed article about machine learning concepts...' }, { - timeout: 5 * 1000, -}); -``` - -On timeout, an `APIConnectionTimeoutError` is thrown. - -Note that requests which time out will be [retried twice by default](#retries). - -## Advanced Usage - -### Accessing raw Response data (e.g., headers) - -The "raw" `Response` returned by `fetch()` can be accessed through the `.asResponse()` method on the `APIPromise` type that all methods return. -This method returns as soon as the headers for a successful response are received and does not consume the response body, so you are free to write custom parsing or streaming logic. - -You can also use the `.withResponse()` method to get the raw `Response` along with the parsed data. -Unlike `.asResponse()` this method consumes the body, returning once it is parsed. - - -```ts -const client = new Supermemory(); - -const response = await client.documents - .add({ content: 'This is a detailed article about machine learning concepts...' }) - .asResponse(); -console.debug(response.headers.get('X-My-Header')); -console.debug(response.statusText); // access the underlying Response object - -const { data: response, response: raw } = await client.documents - .add({ content: 'This is a detailed article about machine learning concepts...' }) - .withResponse(); -console.debug(raw.headers.get('X-My-Header')); -console.debug(response.id); -``` - -### Logging - - -All log messages are intended for debugging only. The format and content of log messages may change between releases. - - -#### Log levels - -The log level can be configured in two ways: - -1. Via the `SUPERMEMORY_LOG` environment variable -2. Using the `logLevel` client option (overrides the environment variable if set) - -```ts -import Supermemory from 'supermemory'; - -const client = new Supermemory({ - logLevel: 'debug', // Show all log messages -}); -``` - -Available log levels, from most to least verbose: - -- `'debug'` - Show debug messages, info, warnings, and errors -- `'info'` - Show info messages, warnings, and errors -- `'warn'` - Show warnings and errors (default) -- `'error'` - Show only errors -- `'off'` - Disable all logging - -At the `'debug'` level, all HTTP requests and responses are logged, including headers and bodies. -Some authentication-related headers are redacted, but sensitive data in request and response bodies -may still be visible. - -#### Custom logger - -By default, this library logs to `globalThis.console`. You can also provide a custom logger. -Most logging libraries are supported, including [pino](https://www.npmjs.com/package/pino), [winston](https://www.npmjs.com/package/winston), [bunyan](https://www.npmjs.com/package/bunyan), [consola](https://www.npmjs.com/package/consola), [signale](https://www.npmjs.com/package/signale), and [@std/log](https://jsr.io/@std/log). If your logger doesn't work, please open an issue. - -When providing a custom logger, the `logLevel` option still controls which messages are emitted, messages -below the configured level will not be sent to your logger. - -```ts -import Supermemory from 'supermemory'; -import pino from 'pino'; - -const logger = pino(); - -const client = new Supermemory({ - logger: logger.child({ name: 'supermemory' }), - logLevel: 'debug', // Send all messages to pino, allowing it to filter -}); -``` - -### Making custom/undocumented requests - -This library is typed for convenient access to the documented API. If you need to access undocumented -endpoints, params, or response properties, the library can still be used. - -#### Undocumented endpoints - -To make requests to undocumented endpoints, you can use `client.get`, `client.post`, and other HTTP verbs. -Options on the client, such as retries, will be respected when making these requests. - -```ts -await client.post('/some/path', { - body: { some_prop: 'foo' }, - query: { some_query_arg: 'bar' }, -}); -``` - -#### Undocumented request params - -To make requests using undocumented parameters, you may use `// @ts-expect-error` on the undocumented -parameter. This library doesn't validate at runtime that the request matches the type, so any extra values you -send will be sent as-is. - -```ts -client.foo.create({ - foo: 'my_param', - bar: 12, - // @ts-expect-error baz is not yet public - baz: 'undocumented option', -}); -``` - -For requests with the `GET` verb, any extra params will be in the query, all other requests will send the -extra param in the body. - -If you want to explicitly send an extra argument, you can do so with the `query`, `body`, and `headers` request -options. - -#### Undocumented response properties - -To access undocumented response properties, you may access the response object with `// @ts-expect-error` on -the response object, or cast the response object to the requisite type. Like the request params, we do not -validate or strip extra properties from the response from the API. - -### Customizing the fetch client - -By default, this library expects a global `fetch` function is defined. - -If you want to use a different `fetch` function, you can either polyfill the global: - -```ts -import fetch from 'my-fetch'; - -globalThis.fetch = fetch; -``` - -Or pass it to the client: - -```ts -import Supermemory from 'supermemory'; -import fetch from 'my-fetch'; - -const client = new Supermemory({ fetch }); -``` - -### Fetch options - -If you want to set custom `fetch` options without overriding the `fetch` function, you can provide a `fetchOptions` object when instantiating the client or making a request. (Request-specific options override client options.) - -```ts -import Supermemory from 'supermemory'; - -const client = new Supermemory({ - fetchOptions: { - // `RequestInit` options - }, -}); -``` - -#### Configuring proxies - -To modify proxy behavior, you can provide custom `fetchOptions` that add runtime-specific proxy options to requests: - -```ts -import Supermemory from 'supermemory'; -import * as undici from 'undici'; - -const proxyAgent = new undici.ProxyAgent('http://localhost:8888'); -const client = new Supermemory({ - fetchOptions: { - dispatcher: proxyAgent, - }, -}); -``` - -```ts -import Supermemory from 'supermemory'; - -const client = new Supermemory({ - fetchOptions: { - proxy: 'http://localhost:8888', - }, -}); -``` - -```ts -import Supermemory from 'npm:supermemory'; - -const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } }); -const client = new Supermemory({ - fetchOptions: { - client: httpClient, - }, -}); -``` - -## Frequently Asked Questions - -## Semantic versioning - -This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions: - -1. Changes that only affect static types, without breaking runtime behavior. -2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_ -3. Changes that we do not expect to impact the vast majority of users in practice. - -We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience. - -We are keen for your feedback; please open an [issue](https://www.github.com/supermemoryai/sdk-ts/issues) with questions, bugs, or suggestions. - -## Requirements - -TypeScript >= 4.9 is supported. - -The following runtimes are supported: - -- Web browsers (Up-to-date Chrome, Firefox, Safari, Edge, and more) -- Node.js 20 LTS or later ([non-EOL](https://endoflife.date/nodejs)) versions. -- Deno v1.28.0 or higher. -- Bun 1.0 or later. -- Cloudflare Workers. -- Vercel Edge Runtime. -- Jest 28 or greater with the `"node"` environment (`"jsdom"` is not supported at this time). -- Nitro v2.6 or greater. - -Note that React Native is not supported at this time. - -If you are interested in other runtime environments, please open or upvote an issue on GitHub. diff --git a/apps/docs/memory-api/searching/searching-memories.mdx b/apps/docs/memory-api/searching/searching-memories.mdx deleted file mode 100644 index 6e5f3454..00000000 --- a/apps/docs/memory-api/searching/searching-memories.mdx +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: "Searching Memories" -description: "Learn how to search for and retrieve content from supermemory" ---- - - -1. **Query Formulation**: - - Use natural language queries - - Include relevant keywords - - Be specific but not too verbose - -2. **Filtering**: - - Use metadata filters for precision - - Combine multiple filters when needed - - Use appropriate thresholds - -3. **Performance**: - - Set appropriate result limits - - Use specific document/chunk filters - - Consider response timing - - - -## Basic Search - -To search through your memories, send a POST request to `/search`: - - - -```bash cURL -curl https://api.supermemory.ai/v3/search?q=machine+learning+concepts&limit=10 \ - --request GET \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' -``` - -```typescript Typescript -await client.search.execute({ - q: "machine learning concepts", - limit: 10, -}); -``` - -```python Python -client.search.execute( - q="machine learning concepts", - limit=10 -) -``` - - - -The API will return relevant matches with their similarity scores: - -```json -{ - "results": [ - { - "documentId": "doc_xyz789", - "chunks": [ - { - "content": "Machine learning is a subset of artificial intelligence...", - "isRelevant": true, - "score": 0.85 - } - ], - "score": 0.95, - "metadata": { - "source": "web", - "category": "technology" - }, - "title": "Introduction to Machine Learning" - } - ], - "total": 1, - "timing": 123.45 -} -``` - -## Search Parameters - -```json -{ - "q": "search query", // Required: Search query string - "limit": 10, // Optional: Max results (default: 10) - "threshold": 0.6, // Optional: Min similarity score (0-1, default: 0.6) - "containerTag": "user_123", // Optional: Filter by container tag - "rerank": false, // Optional: Rerank results for better relevance - "rewriteQuery": false, // Optional: Rewrite query for better matching - "include": { - "documents": false, // Optional: Include document metadata - "summaries": false, // Optional: Include document summaries - "relatedMemories": false, // Optional: Include related memory context - "forgottenMemories": false // Optional: Include forgotten memories in results - }, - "filters": { - // Optional: Metadata filters - "AND": [ - { - "key": "category", - "value": "technology" - } - ] - } -} -``` - -## Search Response - -The search response includes: - -```json -{ - "results": [ - { - "documentId": "string", // Document ID - "chunks": [ - { - // Matching chunks - "content": "string", // Chunk content - "isRelevant": true, // Is directly relevant - "score": 0.95 // Similarity score - } - ], - "score": 0.95, // Document score - "metadata": {}, // Document metadata - "title": "string", // Document title - "createdAt": "string", // Creation date - "updatedAt": "string" // Last update date - } - ], - "total": 1, // Total results - "timing": 123.45 // Search time (ms) -} -``` - -## Including Forgotten Memories - -By default, the search API excludes memories that have been marked as forgotten or have passed their expiration date. To include these in your search results, set `include.forgottenMemories` to `true`: - - - -```bash cURL -curl https://api.supermemory.ai/v4/search \ - --request POST \ - --header 'Authorization: Bearer SUPERMEMORY_API_KEY' \ - --header 'Content-Type: application/json' \ - --data '{ - "q": "old project notes", - "include": { - "forgottenMemories": true - } - }' -``` - -```typescript Typescript -await client.search.memories({ - q: "old project notes", - include: { - forgottenMemories: true - } -}); -``` - -```python Python -await client.search.memories( - q="old project notes", - include={ - "forgottenMemories": True - } -) -``` - - - - -Forgotten memories are memories that have been explicitly forgotten using the forget API or have passed their automatic expiration date (`forgetAfter`). Including them in search results can help recover information that may still be relevant. - - -## Next Steps - -Explore more advanced features in our API Reference tab. diff --git a/apps/docs/memory-graph/npm.mdx b/apps/docs/memory-graph/npm.mdx deleted file mode 100644 index 73185178..00000000 --- a/apps/docs/memory-graph/npm.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "NPM link" -url: "https://www.npmjs.com/package/@supermemory/memory-graph" -icon: npm ---- diff --git a/apps/docs/memory-router/overview.mdx b/apps/docs/memory-router/overview.mdx deleted file mode 100644 index 9ed0ba99..00000000 --- a/apps/docs/memory-router/overview.mdx +++ /dev/null @@ -1,158 +0,0 @@ ---- -title: "Overview" -description: "Transform any LLM into an intelligent agent with unlimited context and persistent memory" -sidebarTitle: "Overview" ---- - -The Memory Router is a transparent proxy that sits between your application and your LLM provider, automatically managing context and memories without requiring any code changes. - - -**Live Demo**: Try the Memory Router at [supermemory.chat](https://supermemory.chat) to see it in action. - - - -**Using Vercel AI SDK?** Check out our [AI SDK integration](/integrations/ai-sdk) for the cleanest implementation with `@supermemory/tools/ai-sdk` - it's our recommended approach for new projects. - - -## What is the Memory Router? - -The Memory Router gives your LLM applications: - -- **Unlimited Context**: No more token limits - conversations can extend indefinitely -- **Automatic Memory Management**: Intelligently chunks, stores, and retrieves relevant context -- **Zero Code Changes**: Works with your existing OpenAI-compatible clients -- **Cost Optimization**: Save up to 70% on token costs through intelligent context management - -## How It Works - - - - Your application sends requests to Supermemory instead of directly to your LLM provider - - - - Supermemory automatically: - - Removes unnecessary context from long conversations - - Searches relevant memories from previous interactions - - Appends the most relevant context to your prompt - - - - The optimized request is forwarded to your chosen LLM provider - - - - New memories are created asynchronously without blocking the response - - - -## Key Benefits - -### For Developers - -- **Drop-in Integration**: Just change your base URL - no other code changes needed -- **Provider Agnostic**: Works with OpenAI, Anthropic, Google, Groq, and more -- **Shared Memory Pool**: Memories created via API are available to the Router and vice versa -- **Automatic Fallback**: If Supermemory has issues, requests pass through directly - -### For Applications - -- **Better Long Conversations**: Maintains context even after thousands of messages -- **Consistent Responses**: Memories ensure consistent information across sessions -- **Smart Retrieval**: Only relevant context is included, improving response quality -- **Cost Savings**: Automatic chunking reduces token usage significantly - -## When to Use the Memory Router - -The Memory Router is ideal for: - - - - - **Chat Applications**: Customer support, AI assistants, chatbots - - **Long Conversations**: Sessions that exceed model context windows - - **Multi-Session Memory**: Users who return and continue conversations - - **Quick Prototypes**: Get memory capabilities without building infrastructure - - - - - **Custom Retrieval Logic**: Need specific control over what memories to fetch - - **Non-Conversational Use**: Document processing, analysis tools - - **Complex Filtering**: Need advanced metadata filtering - - **Batch Operations**: Processing multiple documents at once - - - -## Supported Providers - -The Memory Router works with any OpenAI-compatible endpoint: - -| Provider | Base URL | Status | -|----------|----------|---------| -| OpenAI | `api.openai.com/v1` | ✅ Fully Supported | -| Anthropic | `api.anthropic.com/v1` | ✅ Fully Supported | -| Google Gemini | `generativelanguage.googleapis.com/v1beta/openai` | ✅ Fully Supported | -| Groq | `api.groq.com/openai/v1` | ✅ Fully Supported | -| DeepInfra | `api.deepinfra.com/v1/openai` | ✅ Fully Supported | -| OpenRouter | `openrouter.ai/api/v1` | ✅ Fully Supported | -| Custom | Any OpenAI-compatible | ✅ Supported | - - -**Not Yet Supported**: -- OpenAI Assistants API (`/v1/assistants`) - - -## Authentication - -The Memory Router requires two API keys: - -1. **Supermemory API Key**: For memory management -2. **Provider API Key**: For your chosen LLM provider - -You can provide these via: -- Headers (recommended for production) -- URL parameters (useful for testing) -- Request body (for compatibility) - -## How Memories Work - -When using the Memory Router: - -1. **Automatic Extraction**: Important information from conversations is automatically extracted -2. **Intelligent Chunking**: Long messages are split into semantic chunks -3. **Relationship Building**: New memories connect to existing knowledge -4. **Smart Retrieval**: Only the most relevant memories are included in context - - -Memories are shared between the Memory Router and Memory API when using the same `user_id`, allowing you to use both together. - - -## Response Headers - -The Memory Router adds diagnostic headers to help you understand what's happening: - -| Header | Description | -|--------|-------------| -| `x-supermemory-conversation-id` | Unique conversation identifier | -| `x-supermemory-context-modified` | Whether context was modified (`true`/`false`) | -| `x-supermemory-tokens-processed` | Number of tokens processed | -| `x-supermemory-chunks-created` | New memory chunks created | -| `x-supermemory-chunks-retrieved` | Memory chunks added to context | - -## Error Handling - -The Memory Router is designed for reliability: - -- **Automatic Fallback**: If Supermemory encounters an error, your request passes through unmodified -- **Error Headers**: `x-supermemory-error` header provides error details -- **Zero Downtime**: Your application continues working even if memory features are unavailable - -## Rate Limits & Pricing - -### Rate Limits -- No Supermemory-specific rate limits -- Subject only to your LLM provider's limits - -### Pricing -- **Free Tier**: 100k tokens stored at no cost -- **Standard Plan**: $20/month after free tier -- **Usage-Based**: Each conversation includes 20k free tokens, then $1 per million tokens diff --git a/apps/docs/memory-router/usage.mdx b/apps/docs/memory-router/usage.mdx deleted file mode 100644 index 68dad6f6..00000000 --- a/apps/docs/memory-router/usage.mdx +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: "Usage" -description: "How to implement the Memory Router in your application" -sidebarTitle: "Usage" ---- - -Add unlimited memory to your LLM applications with just a URL change. - -## Prerequisites - -You'll need: -1. A [Supermemory API key](https://console.supermemory.ai) -2. Your LLM provider's API key - -## Basic Setup - - - - **Supermemory API Key:** - 1. Sign up at [console.supermemory.ai](https://console.supermemory.ai) - 2. Navigate to **API Keys** → **Create API Key** - 3. Copy your key - - **Provider API Key:** - - [OpenAI](https://platform.openai.com/api-keys) - - [Anthropic](https://console.anthropic.com/settings/keys) - - [Google Gemini](https://aistudio.google.com/app/apikey) - - [Groq](https://console.groq.com/keys) - - - - Prepend `https://api.supermemory.ai/v3/` to your provider's URL: - - ``` - https://api.supermemory.ai/v3/[PROVIDER_URL] - ``` - - - - Include both API keys in your requests (see examples below) - - - -## Provider URLs - - - -```text OpenAI -https://api.supermemory.ai/v3/https://api.openai.com/v1/ -``` - -```text Anthropic -https://api.supermemory.ai/v3/https://api.anthropic.com/v1/ -``` - -```text Google Gemini -https://api.supermemory.ai/v3/https://generativelanguage.googleapis.com/v1beta/openai/ -``` - -```text Groq -https://api.supermemory.ai/v3/https://api.groq.com/openai/v1/ -``` - - - -## Implementation Examples - - - - ```python - from openai import OpenAI - - client = OpenAI( - api_key="YOUR_OPENAI_API_KEY", - base_url="https://api.supermemory.ai/v3/https://api.openai.com/v1/", - default_headers={ - "x-supermemory-api-key": "YOUR_SUPERMEMORY_API_KEY", - "x-sm-user-id": "user123" # Unique user identifier - } - ) - - # Use as normal - response = client.chat.completions.create( - model="gpt-5", - messages=[ - {"role": "user", "content": "Hello!"} - ] - ) - - print(response.choices[0].message.content) - ``` - - - - ```typescript - 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': 'user123' // Unique user identifier - } - }); - - // Use as normal - const response = await client.chat.completions.create({ - model: 'gpt-5', - messages: [ - { role: 'user', content: 'Hello!' } - ] - }); - - console.log(response.choices[0].message.content); - ``` - - - - ```bash - curl -X POST "https://api.supermemory.ai/v3/https://api.openai.com/v1/chat/completions" \ - -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \ - -H "x-supermemory-api-key: YOUR_SUPERMEMORY_API_KEY" \ - -H "x-sm-user-id: user123" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "gpt-5", - "messages": [{"role": "user", "content": "Hello!"}] - }' - ``` - - - -## Alternative: URL Parameters - -If you can't modify headers, pass authentication via URL parameters: - - - -```python Python -client = OpenAI( - api_key="YOUR_OPENAI_API_KEY", - base_url="https://api.supermemory.ai/v3/https://api.openai.com/v1/chat/completions?userId=user123" -) - -# Then set Supermemory API key as environment variable: -# export SUPERMEMORY_API_KEY="your_key_here" -``` - -```typescript TypeScript -const client = new OpenAI({ - apiKey: process.env.OPENAI_API_KEY, - baseURL: 'https://api.supermemory.ai/v3/https://api.openai.com/v1/chat/completions?userId=user123' -}); - -// Set Supermemory API key as environment variable: -// SUPERMEMORY_API_KEY="your_key_here" -``` - -```bash cURL -curl -X POST "https://api.supermemory.ai/v3/https://api.openai.com/v1/chat/completions?userId=user123" \ - -H "Authorization: Bearer YOUR_OPENAI_API_KEY" \ - -H "x-supermemory-api-key: YOUR_SUPERMEMORY_API_KEY" \ - -H "Content-Type: application/json" \ - -d '{"model": "gpt-5", "messages": [{"role": "user", "content": "Hello!"}]}' -``` - - - -## Conversation Management - -### Managing Conversations - -Use `x-sm-conversation-id` to maintain conversation context across requests: - -```python -# Start a new conversation -response1 = client.chat.completions.create( - model="gpt-5", - messages=[{"role": "user", "content": "My name is Alice"}], - extra_headers={ - "x-sm-conversation-id": "conv_123" - } -) - -# Continue the same conversation later -response2 = client.chat.completions.create( - model="gpt-5", - messages=[{"role": "user", "content": "What's my name?"}], - extra_headers={ - "x-sm-conversation-id": "conv_123" - } -) -# Response will remember "Alice" -``` - -### User Identification - -Always provide a unique user ID to isolate memories between users: - -```python -# Different users have separate memory spaces -client_alice = OpenAI( - api_key="...", - base_url="...", - default_headers={"x-sm-user-id": "alice_123"} -) - -client_bob = OpenAI( - api_key="...", - base_url="...", - default_headers={"x-sm-user-id": "bob_456"} -) -``` diff --git a/apps/docs/memory-router/with-memory-api.mdx b/apps/docs/memory-router/with-memory-api.mdx deleted file mode 100644 index e93705ea..00000000 --- a/apps/docs/memory-router/with-memory-api.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "Use with Memory API" -description: "Combine the Memory Router with Memory API for maximum control" -sidebarTitle: "Use with Memory API" ---- - -The Memory Router and Memory API share the same memory pool. When you use the same `user_id`, memories are automatically shared between both systems. - -## How They Work Together - - -**Key Insight**: Both the Router and API access the same memories when using identical `user_id` values. This enables powerful hybrid implementations. - - -### Shared Memory Pool - -```python -# Memory created via API -from supermemory import Client - -api_client = Client(api_key="YOUR_SUPERMEMORY_KEY") - -# Add memory via API -api_client.add({ - "content": "User prefers Python over JavaScript for backend development", - "user_id": "user123" -}) - -# Later, in your chat application using Router -from openai import OpenAI - -router_client = OpenAI( - api_key="YOUR_OPENAI_KEY", - base_url="https://api.supermemory.ai/v3/https://api.openai.com/v1/", - default_headers={ - "x-supermemory-api-key": "YOUR_SUPERMEMORY_KEY", - "x-sm-user-id": "user123" # Same user_id - } -) - -# Router automatically has access to the API-created memory -response = router_client.chat.completions.create( - model="gpt-5", - messages=[{"role": "user", "content": "What language should I use for my new backend?"}] -) -# Response will consider the Python preference -``` - -## Pre-load Context via API - -Use the API to add documents and context before conversations: - -```python -# Step 1: Load user's documents via API -api_client.add({ - "content": "https://company.com/product-docs.pdf", - "user_id": "support_agent_123", - "metadata": {"type": "product_documentation"} -}) - -# Step 2: Support agent uses chat with Router -router_client = OpenAI( - base_url="https://api.supermemory.ai/v3/https://api.openai.com/v1/", - default_headers={"x-sm-user-id": "support_agent_123"} -) - -# Agent has automatic access to product docs -response = router_client.chat.completions.create( - model="gpt-5", - messages=[{"role": "user", "content": "How does the enterprise pricing work?"}] -) -``` - - -## Best Practices - -### 1. Consistent User IDs - -Always use the same `user_id` format across both systems: - -```python -# ✅ Good - consistent user_id -api_client.add({"user_id": "user_123"}) -router_headers = {"x-sm-user-id": "user_123"} - -# ❌ Bad - inconsistent user_id -api_client.add({"user_id": "user-123"}) -router_headers = {"x-sm-user-id": "user_123"} # Different format! -``` - -### 2. Use Container Tags for Organization - -```python -# API: Add memories with tags -api_client.add({ - "content": "Q3 revenue report", - "user_id": "analyst_1", - "containerTag": "financial_reports" -}) - -# Router: Memories are automatically organized -# The Router will intelligently retrieve from the right containers -``` - -### 3. Leverage Each System's Strengths - -| Use Case | Best Choice | Why | -|----------|------------|-----| -| Chat conversations | Router | Automatic context management | -| Document upload | API | Batch processing, custom IDs | -| Search & filter | API | Advanced query capabilities | -| Quick prototypes | Router | Zero code changes | -| Memory management | API | Full CRUD operations | diff --git a/apps/docs/model-enhancement/context-extender.mdx b/apps/docs/model-enhancement/context-extender.mdx deleted file mode 100644 index a7d7897e..00000000 --- a/apps/docs/model-enhancement/context-extender.mdx +++ /dev/null @@ -1,233 +0,0 @@ ---- -title: "supermemory Infinite Chat" -description: "Build chat applications with unlimited context using supermemory's intelligent proxy" -tag: "BETA" ---- - -import GettingAPIKey from '/snippets/getting-api-key.mdx'; - -supermemory Infinite Chat is a powerful solution that gives your chat applications unlimited contextual memory. It works as a transparent proxy in front of your existing LLM provider, intelligently managing long conversations without requiring any changes to your application logic. - -Infinite Context Diagram - - - - - - No more token limits - conversations can extend indefinitely - - - Transparent proxying with negligible overhead - - - Save up to 70% on token costs for long conversations - - - Works with any OpenAI-compatible endpoint - - - - - -## Getting Started - -To use the Infinite Chat endpoint, you need to: - -### 1. Get a supermemory API key - - - -### 2. Add supermemory in front of any **OpenAI-Compatible** API URL - - - -```typescript Typescript -import OpenAI from "openai"; - -/** - * Initialize the OpenAI client with supermemory proxy - * @param {string} OPENAI_API_KEY - Your OpenAI API key - * @param {string} SUPERMEMORY_API_KEY - Your supermemory API key - * @returns {OpenAI} - Configured OpenAI client - */ -const client = new OpenAI({ - apiKey: process.env.OPENAI_API_KEY, - baseURL: "https://api.supermemory.ai/v3/https://api.openai.com/v1", - headers: { - "x-supermemory-api-key": process.env.SUPERMEMORY_API_KEY, - "x-sm-user-id": "Your_users_id" - }, -}); -``` - -```python Python -import openai -import os - -# Configure the OpenAI client with supermemory proxy -openai.api_base = "https://api.supermemory.ai/v3/https://api.openai.com/v1" -openai.api_key = os.environ.get("OPENAI_API_KEY") # Your regular OpenAI key -openai.default_headers = { - "x-supermemory--api-key": os.environ.get("SUPERMEMORY_API_KEY"), # Your supermemory key -} - -# Create a chat completion with unlimited context -response = openai.ChatCompletion.create( - model="gpt-5-nano", - messages=[{"role": "user", "content": "Your message here"}] -) -``` - - - -## How It Works - - - - All requests pass through supermemory to your chosen LLM provider with zero latency overhead. - - Transparent Proxy Diagram - - - Long conversations are automatically broken down into optimized segments using our proprietary chunking algorithm that preserves semantic coherence. - - - When conversations exceed token limits (20k+), supermemory intelligently retrieves the most relevant context from previous messages. - - - The system intelligently balances token usage, ensuring optimal performance while minimizing costs. - - - -## Performance Benefits - - - Save up to 70% on token costs for long conversations through intelligent context management and caching. - - - - No more 8k/32k/128k token limits - conversations can extend indefinitely with supermemory's advanced retrieval system. - - - - Better context retrieval means more coherent responses even in very long threads, reducing hallucinations and inconsistencies. - - - - The proxy adds negligible latency to your requests, ensuring fast response times for your users. - - -## Pricing - - - -
-
-
-

Free Tier

-

100k tokens stored at no cost

-
-
-

Standard Plan

-

$20/month fixed cost after exceeding free tier

-
-
-

Usage-Based

-

Each thread includes 20k free tokens, then $1 per million tokens thereafter

-
-
-
- - -
- - - - - - - - - - - - - - - - - - - - -
- Feature - - Free - - Standard -
- Tokens Stored - - 100k - - Unlimited -
- Conversations - - 10 - - Unlimited -
-
- - - -## Error Handling - - - supermemory is designed with reliability as the top priority. If any issues occur within the supermemory processing pipeline, the system will automatically fall back to direct forwarding of your request to the LLM provider, ensuring zero downtime for your applications. - - -Each response includes diagnostic headers that provide information about the processing: - -| Header | Description | -| -------------------------------- | ---------------------------------------------------------------------- | -| `x-supermemory-conversation-id` | Unique identifier for the conversation thread | -| `x-supermemory-context-modified` | Indicates whether supermemory modified the context ("true" or "false") | -| `x-supermemory-tokens-processed` | Number of tokens processed in this request | -| `x-supermemory-chunks-created` | Number of new chunks created from this conversation | -| `x-supermemory-chunks-deleted` | Number of chunks removed (if any) | -| `x-supermemory-docs-deleted` | Number of documents removed (if any) | - -If an error occurs, an additional header `x-supermemory-error` will be included with details about what went wrong. Your request will still be processed by the underlying LLM provider even if supermemory encounters an error. - -## Rate Limiting - - - Currently, there are no rate limits specific to supermemory. Your requests are subject only to the rate limits of your underlying LLM provider. - - -## Supported Models - -supermemory works with any OpenAI-compatible API, including: - - - - GPT-3.5, GPT-4, GPT-4o - - - Claude 3 models - - - Any provider with an OpenAI-compatible endpoint - - diff --git a/apps/docs/model-enhancement/getting-started.mdx b/apps/docs/model-enhancement/getting-started.mdx deleted file mode 100644 index 7af3bfab..00000000 --- a/apps/docs/model-enhancement/getting-started.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "Getting Started with Model Enhancement" -sidebarTitle: "Quickstart" -description: "Superpower your LLM in one line" ---- - -import GettingAPIKey from '/snippets/getting-api-key.mdx'; - -## Get your supermemory API key - - - -## Get your LLM provider's API key - -Head to your LLM provider's dashboard and get your API key. - -- [OpenAI](https://platform.openai.com/api-keys) -- [Gemini](https://aistudio.google.com/apikey) -- [Anthropic](https://console.anthropic.com/account/keys) -- [Groq](https://console.groq.com/keys) - -## Choose your endpoint - - - -```bash OpenAI -https://api.supermemory.ai/v3/https://api.openai.com/v1/chat/completions -``` - - -```bash Gemini -https://api.supermemory.ai/v3/https://generativelanguage.googleapis.com/v1beta/openai -``` - - -```bash Anthropic -https://api.supermemory.ai/v3/https://api.anthropic.com/v1 -``` - - -```bash Groq -https://api.supermemory.ai/v3/https://api.groq.com/openai/v1 -``` - - -```bash Other provider -https://api.supermemory.ai/v3/ -``` - - - -## Making your first request - - - -```bash cURL -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_id' \ - -d '{ - "model": "gpt-5", - "messages": [ - {"role": "user", "content": "What is the capital of France?"} - ] - }' -``` - - -``` -``` - - -```typescript TypeScript -import OpenAI from 'openai'; - -const openai = 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': 'your-user-id' - } -}); - -const completion = await openai.chat.completions.create({ - model: "gpt-5", -/// you can also add user here - user: "user", - messages: [ - { role: "user", content: "What is the capital of France?" } - ] -}); - - console.debug(completion.choices[0].message); -``` - - diff --git a/apps/docs/model-enhancement/identifying-users.mdx b/apps/docs/model-enhancement/identifying-users.mdx deleted file mode 100644 index cdc1bbf2..00000000 --- a/apps/docs/model-enhancement/identifying-users.mdx +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: "Identifying Users" -description: "Identifying users in supermemory" ---- - -You can enable built-in cross-conversational memory by sending supermemory a `x-sm-user-id`. - -## How supermemory Identifies Users and conversations - -supermemory will find the user ID in the following places (in order of priority): - -### `x-sm-user-id` header - -You can add a default header of x-sm-user-id with any client and model - -### `user` in body - -For models that support the `user` parameter in the body, such as OpenAI, you can also attach it to the body. - -### `userId` in search params - -You can also add `?userId=xyz` in the URL search parameters, incase the models don't support it. - -## Conversation ID - -If a conversation identifier is provided, You do not need to send the entire array of messages to supermemory. - -```typescript -// if you provide conversation ID, You do not need to send all the messages every single time. supermemory automatically backfills it. -const client = new OpenAI({ - baseURL: -"https://api.supermemory.ai/v3/https://api.openai.com/v1", - defaultHeaders: { - "x-supermemory-api-key": - "SUPERMEMORY_API_KEY", - "x-sm-user-id": `dhravya`, - "x-sm-conversation-id": "conversation-id" - }, -}) - -const messages = [ -{"role" : "user", "text": "SOme long thing"}, -// .... 50 other messages -{"role" : "user", "text": "new message"}, -] - -const client.generateText(messages) - -// Next time, you dont need to send more. -const messages2 = [{"role" : "user", "text": "What did we talk about in this conversation, and the one we did last year?"}] - -const client.generateText(messages2) -``` - -## Implementation Examples - -### Google Gemini - -```typescript -const ai = new GoogleGenAI({ apiKey: "YOUR_API_KEY" }); - -async function main() { - const response = await ai.models.generateContent({ - model: "gemini-2.0-flash", - contents: "Explain how AI works in a few words", - config: { - httpOptions: { - headers: { - 'x-sm-user-id': "user_123" - } - } - }, - }); - console.debug(response.text); -} -``` - -### Anthropic - -```typescript -const anthropic = new Anthropic({ - apiKey: 'YOUR_API_KEY', // defaults to process.env["ANTHROPIC_API_KEY"] -}); - -async function main() { - const msg = await anthropic.messages.create({ - model: "claude-sonnet-4-20250514", - max_tokens: 1024, - messages: [{ role: "user", content: "Hello, Claude" }], - }, { - // Using headers - headers: { - 'x-sm-user-id': "user_123" - } - }); - - console.debug(msg); -} -``` - -### OpenAI - -```typescript -const openai = new OpenAI({ - apiKey: "YOUR_API_KEY" -}); - -async function main() { - const completion = await openai.chat.completions.create({ - messages: [ - { role: "user", content: "Hello, Assistant" } - ], - model: "gpt-5", - user: "user_123" - }); - - console.debug(completion.choices[0].message); -} -``` diff --git a/apps/docs/openai-sdks/usage.mdx b/apps/docs/openai-sdks/usage.mdx deleted file mode 100644 index db2e52e3..00000000 --- a/apps/docs/openai-sdks/usage.mdx +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: "Usage with OpenAI SDKs" ---- - -To use supermemory with the OpenAI SDKs, - -``` -import { memoryToolSchemas } from "@supermemory/tools/openai" -``` diff --git a/apps/docs/overview/why-supermemory.mdx b/apps/docs/overview/why-supermemory.mdx deleted file mode 100644 index c1d651a9..00000000 --- a/apps/docs/overview/why-supermemory.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "Why supermemory?" -description: "Learn the problems and challenges of building a memory layer, and how supermemory solves them!" ---- - -### The problem - -...so you want to build your own memory layer. Let's go through your decision process: - - - - - - Oh no, it's way too expensive. Time to switch. - - Turns out it's painfully slow. Let's try another. - - Great, now it won't scale. Back to square one. - - The maintenance is a nightmare. Need something else. - - - - - - Which model fits your use case - - What are the performance tradeoffs - - How to keep up with new releases - - - - - - - Websites: How do you handle JavaScript? What about rate limits? - - PDFs: OCR keeps failing, text extraction is inconsistent - - Images: Need computer vision models now? - - Audio/Video: Transcription costs add up quickly - - - - - -And in the middle of all this, you're wondering... - -> "When will I actually ship my product?" - -### The solution - -If you're not a fan of reinventing the wheel, you can use supermemory. - - - - - Start for free, scale as you grow - - Simple API, deploy in minutes - - No complex setup or maintenance - - Clear, predictable pricing - - - - Notion, Google Drive, Slack - - Web scraping and PDF processing - - Email and calendar sync - - Custom connector SDK - - - - Enterprise-grade security - - Sub-200ms latency at scale - - Automatic failover and redundancy - - 99.9% uptime guarantee - - - -Stop reinventing the wheel. Focus on building your product while we handle the memory infrastructure. \ No newline at end of file diff --git a/apps/docs/supermemory-mcp/introduction.mdx b/apps/docs/supermemory-mcp/introduction.mdx deleted file mode 100644 index 51f097ed..00000000 --- a/apps/docs/supermemory-mcp/introduction.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: 'About Supermemory MCP' -description: 'Give your AI assistants persistent memory with the Model Context Protocol' ---- - -Supermemory MCP Server 4.0 is a lightweight component that gives AI assistants persistent memory across conversations. It serves as a universal memory layer enabling Large Language Models (LLMs) to maintain context and memories across different applications and sessions, solving the fundamental limitation of AI assistants forgetting everything between conversations. - - - Jump to installation and setup - - -## What Supermemory MCP Does - -**Supermemory MCP** functions as a universal memory system that bridges AI applications through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io). It operates as an **MCP server** that communicates with MCP-compatible clients, storing and retrieving contextual information through the Supermemory API infrastructure. - -When users interact with any connected AI application, the system captures relevant information and makes it available across all other connected platforms through **semantic search and intelligent retrieval**. - -### Supported Platforms - -- **Claude Desktop** - Direct MCP protocol support -- **Cursor IDE** - Global MCP server configuration via `~/.cursor/mcp.json` -- **Windsurf** - Seamless integration for AI-powered development -- **VS Code** - Compatible with AI coding extensions -- **Cline/Roo-Cline** - Full MCP protocol support -- **Any MCP-compatible application** - Universal compatibility through standard protocol - -### Key Features - -- **OAuth Authentication** - Secure login through Supermemory accounts -- **API Key Support** - Alternative authentication for automation and CI/CD -- **Persistent Memory** - Save and recall information across sessions -- **User Profiles** - Auto-generated profiles from stored memories -- **Project Scoping** - Organize memories by project with `x-sm-project` header - -## Core Workflow - -1. User interacts with any MCP-compatible AI client -2. The client connects to `https://mcp.supermemory.ai/mcp` -3. OAuth flow authenticates the user (or API key validates directly) -4. During conversations, relevant information is stored using the `memory` tool -5. When context is needed, the `recall` tool retrieves relevant memories -6. The AI assistant accesses this persistent context regardless of which platform is being used - -## Security and Privacy - -### Authentication Model - -- **OAuth by default** - Secure authentication through Supermemory accounts -- **API key alternative** - Keys start with `sm_` for programmatic access -- **Session isolation** - Complete user data separation per account - -### Privacy Features - -- **Data isolation** - User memories completely separated by account -- **Secure infrastructure** - Built on Cloudflare's enterprise-grade platform -- **Open source** - Full transparency into how your data is handled - - - View the open-source implementation - diff --git a/apps/docs/supermemory-mcp/technology.mdx b/apps/docs/supermemory-mcp/technology.mdx deleted file mode 100644 index 5f64e87d..00000000 --- a/apps/docs/supermemory-mcp/technology.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: 'Technical implementation details' -description: 'Technical implementation details of supermemory MCP' ---- - -The technical architecture prioritizes **simplicity and user experience** while maintaining robust functionality. Built as what the creators describe as "the simplest thing you'll see" - essentially a React Router application making fetch calls to the supermemory API - the entire system was developed and shipped in approximately 5 hours of actual work time. - -### Architecture components - -- **Backend API**: Built on top of the supermemory API (https://api.supermemory.ai/v3) -- **Transport Layer**: Uses Server-Sent Events (SSE) for real-time communication -- **Dynamic Server Generation**: Creates unique MCP server instances for each user via URL path parameters -- **Session Management**: Maintains complete user isolation through unique URLs -- **Infrastructure**: Hosted on Cloudflare using Durable Objects for persistent, long-running connections - -The system leverages **Cloudflare's infrastructure** with CPU-based billing, making it highly efficient since memory connections spend most time waiting between interactions rather than actively processing, resulting in minimal CPU usage despite potentially running for millions of milliseconds. - -## The two main components explained - -### addToSupermemory action - -This component **stores user information, preferences, and behavioral patterns** with sophisticated triggering mechanisms: - -**Trigger methods:** -- **Explicit commands**: Direct user instructions like "remember this" -- **Implicit detection**: Automatic identification of significant user traits, preferences, or patterns during conversations - -**Data types captured:** -- Technical preferences and details (e.g., "My primary programming language is Python") -- Project information and context (e.g., "I'm currently working on a project named 'Apollo'") -- User behaviors and emotional responses -- Personal facts, preferences, and decision-making patterns -- Rich context including technical details and examples - -### searchSupermemory action - -This component **retrieves relevant information** from stored memories using advanced search capabilities: - -**Activation triggers:** -- Explicit user requests for historical information -- Contextual situations where past user choices would be helpful for current decisions -- Automatic context enhancement based on conversation flow - -**Search capabilities:** -- **Semantic matching**: Finds relevant details across related experiences using vector search -- **Pattern recognition**: Identifies behavioral patterns and preferences -- **Cross-session retrieval**: Accesses memories from previous conversations and platforms -- **Intelligent filtering**: Returns most relevant context based on current conversation needs diff --git a/apps/docs/test.py b/apps/docs/test.py deleted file mode 100644 index 85ce6f82..00000000 --- a/apps/docs/test.py +++ /dev/null @@ -1,37 +0,0 @@ -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"]) - -static = "\n".join(profile.profile.static) -dynamic = "\n".join(profile.profile.dynamic) -memories = "\n".join(r.get("memory", "") for r in profile.search_results.results) - -context = f"""Static profile: -{static} - -Dynamic profile: -{dynamic} - -Relevant memories: -{memories}""" - -# 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 deleted file mode 100644 index 8eab02ff..00000000 --- a/apps/docs/test.ts +++ /dev/null @@ -1,42 +0,0 @@ -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, -})