Search Endpoint

​

Search Memories

curl -X POST https://api.azen.sh/api/v1/memory/search \
  -H "azen-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "outdoor activities",
    "topK": 5
  }'

​

Request Body

​

Response

{
  "status": "success",
  "memories": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "content": "I love hiking in the mountains",
      "metadata": null,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "embedded": true
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001",
      "content": "Rock climbing is my favorite weekend activity",
      "metadata": null,
      "createdAt": "2024-01-14T15:20:00.000Z",
      "embedded": true
    }
  ],
  "rawMatches": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000::0",
      "score": 1.00110459,
      "values": []
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440001::0",
      "score": 0.82,
      "values": []
    }
  ]
}

​

How It Works

1. Query Embedding: Your search query is converted into a vector embedding using the same model used for memory embeddings
2. Vector Search: The query vector is compared against all memory vectors in your organization’s namespace
3. Ranking: Results are ranked by cosine similarity score (higher scores indicate better matches)
4. Decryption: Matched memories are decrypted and returned with their similarity scores

​

Best Practices

• Query Length: Queries don’t need to be exact matches. Natural language queries work well (e.g., “outdoor activities” will match “hiking”, “camping”, etc.)
• Top K Selection: Start with the default topK: 5 and adjust based on your use case. Higher values return more results but may include less relevant matches
• Score Interpretation: Scores typically range from 0 to 1+. Scores above 0.7 generally indicate good semantic similarity
• Empty Results: If no memories are returned, it means either:
  • No memories have been created yet
  • Memories haven’t finished embedding yet (check embedded: false on memories)
  • The query doesn’t semantically match any stored memories