Skip to main content

Best Practices

  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
To search through your memories, send a POST request to /search: 
curl https://api.supermemory.ai/v3/search?q=machine+learning+concepts&limit=10 \
  --request GET \
  --header 'Authorization: Bearer SUPERMEMORY_API_KEY'
The API will return relevant matches with their similarity scores: 
{
  "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

{
  "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: 
{
  "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: 
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
    }
  }'
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.