Search API

Search Memories

Find memories using semantic similarity.

POST /v1/search

Request Body

Field	Type	Required	Default	Description
query	string	Yes	-	Natural language search query
user_id	string	No	-	Filter by user
agent_id	string	No	-	Filter by agent
limit	int	No	10	Maximum results
threshold	float	No	0.7	Minimum similarity score (0-1)
filters	object	No	-	Metadata filters

Example

curl -X POST https://api.memoid.dev/v1/search 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "query": "What food does the user like?",
    "user_id": "user_123",
    "limit": 5
  }'

Response

{
  "results": [
    {
      "id": "mem_def456",
      "memory": "User loves pizza",
      "score": 0.92,
      "user_id": "user_123",
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "mem_ghi789",
      "memory": "User is vegetarian",
      "score": 0.78,
      "user_id": "user_123",
      "created_at": "2024-01-14T15:00:00Z"
    }
  ]
}

Search Parameters

Query

The search query should be natural language describing what you’re looking for:

{
  "query": "What are the user's hobbies?"
}

More specific queries yield better results:

• Good: “What food allergies does the user have?”
• Less good: “food”

Threshold

Controls the minimum relevance score for results:

Threshold	Use Case
0.9+	Very high precision
0.7-0.9	Balanced (default)
0.5-0.7	Higher recall
Below 0.5	Maximum recall

Filters

Filter by metadata fields:

{
  "query": "preferences",
  "filters": {
    "source": "chat",
    "category": "food"
  }
}

Similarity Scores

Scores indicate semantic similarity:

Score	Interpretation
0.95+	Near-exact match
0.85-0.95	Highly relevant
0.70-0.85	Relevant
0.50-0.70	Somewhat related
Below 0.50	Weak match

Best Practices

1. Be specific — Detailed queries get better results
2. Use appropriate limits — Start small, increase if needed
3. Tune threshold — Adjust based on your precision needs
4. Combine with list — Get both relevant and recent memories