Search Memories

Find relevant memories using semantic search

POST https://api.memchat.io/v1/memories/search

cURL

curl -X POST "https://api.memchat.io/v1/memories/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What does the user do for work?",
    "limit": 5,
    "categories": ["career"],
    "rerank": true
  }'

Success Response

{
  "user_bio": "Senior Software Engineer at Google specializing in machine learning infrastructure with 8+ years of experience. Passionate about hiking, photography, and sustainable living.",
  "memories": [
    {
      "id": "mem_abc123",
      "memory": "Works as a Senior Software Engineer at Google on ML infrastructure team",
      "categories": ["career"],
      "type": "semantic",
      "vector_distance": 0.15,
      "rerank_score": 0.95,
      "source": "chat",
      "created_at": "2024-03-20T10:00:00Z",
      "updated_at": "2024-03-20T10:00:00Z",
      "agent_id": "career-advisor-bot",
      "thread_id": "conversation-2024-001"
    },
    {
      "id": "mem_def456",
      "memory": "Recently promoted to Senior Software Engineer, leads team of 5 engineers",
      "categories": ["career"],
      "type": "episodic",
      "vector_distance": 0.22,
      "rerank_score": 0.88,
      "source": "chat",
      "created_at": "2024-03-20T09:30:00Z", 
      "updated_at": "2024-03-20T09:30:00Z",
      "agent_id": "career-advisor-bot",
      "thread_id": "conversation-2024-001"
    },
    {
      "id": "mem_ghi789",
      "memory": "Has 8+ years of experience in software engineering",
      "categories": ["career"],
      "type": "semantic",
      "vector_distance": 0.28,
      "rerank_score": 0.82,
      "source": "integration",
      "created_at": "2024-03-19T15:20:00Z",
      "updated_at": "2024-03-19T15:20:00Z",
      "agent_id": "linkedin-integration",
      "thread_id": "integration-linkedin-001"
    }
  ]
}

Search for relevant memories using natural language queries. MemSync uses semantic search with vector embeddings to find memories that match the meaning and context of your query, not just keywords.

Authentication

X-API-Key · string · required

Your MemSync API key for authentication

Request Body

query · string · required

Natural language search query (e.g., “What does the user do for work?”)

limit · integer · default: "10"

Maximum number of memories to return (1-100)

categories · array

Filter results to specific memory categories

Show Available Categories

• identity - Personal information and background
• career - Work, profession, and career goals
• interests - Hobbies and recreational activities
• relationships - Social connections and family
• health - Wellness, fitness, and medical information
• finance - Financial goals, budgets, and investments
• learning - Education, skills, and knowledge acquisition
• travel - Travel experiences and plans
• productivity - Work habits and organizational systems
• private - Sensitive personal information

rerank · boolean · default: "false"

Enable reranking for improved search quality (recommended for complex queries)

include_bio · boolean · default: "true"

Include user bio in the response

agent_id · string

Filter results to memories from a specific agent

thread_id · string

Filter results to memories from a specific conversation thread

Response

user_bio · string

Auto-generated biographical summary of the user

memories · array

Array of relevant memories matching the search query

Show Memory Object

id · string

Unique identifier for the memory

memory · string

The extracted memory content

categories · array

Categories assigned to this memory

type · string

Memory type: “semantic” (lasting facts) or “episodic” (time-bound events)

vector_distance · number

Semantic similarity score (lower = more similar, 0.0-1.0)

rerank_score · number

Reranking relevance score when reranking is enabled (higher = more relevant, 0.0-1.0)

source · string

Source of the memory (e.g., “chat”, “integration”)

created_at · string

ISO 8601 timestamp when the memory was created

updated_at · string

ISO 8601 timestamp when the memory was last updated

agent_id · string

Identifier of the agent that created this memory

thread_id · string

Conversation thread where this memory originated

cURL

curl -X POST "https://api.memchat.io/v1/memories/search" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What does the user do for work?",
    "limit": 5,
    "categories": ["career"],
    "rerank": true
  }'

Success Response

{
  "user_bio": "Senior Software Engineer at Google specializing in machine learning infrastructure with 8+ years of experience. Passionate about hiking, photography, and sustainable living.",
  "memories": [
    {
      "id": "mem_abc123",
      "memory": "Works as a Senior Software Engineer at Google on ML infrastructure team",
      "categories": ["career"],
      "type": "semantic",
      "vector_distance": 0.15,
      "rerank_score": 0.95,
      "source": "chat",
      "created_at": "2024-03-20T10:00:00Z",
      "updated_at": "2024-03-20T10:00:00Z",
      "agent_id": "career-advisor-bot",
      "thread_id": "conversation-2024-001"
    },
    {
      "id": "mem_def456",
      "memory": "Recently promoted to Senior Software Engineer, leads team of 5 engineers",
      "categories": ["career"],
      "type": "episodic",
      "vector_distance": 0.22,
      "rerank_score": 0.88,
      "source": "chat",
      "created_at": "2024-03-20T09:30:00Z", 
      "updated_at": "2024-03-20T09:30:00Z",
      "agent_id": "career-advisor-bot",
      "thread_id": "conversation-2024-001"
    },
    {
      "id": "mem_ghi789",
      "memory": "Has 8+ years of experience in software engineering",
      "categories": ["career"],
      "type": "semantic",
      "vector_distance": 0.28,
      "rerank_score": 0.82,
      "source": "integration",
      "created_at": "2024-03-19T15:20:00Z",
      "updated_at": "2024-03-19T15:20:00Z",
      "agent_id": "linkedin-integration",
      "thread_id": "integration-linkedin-001"
    }
  ]
}

Query Examples

Basic Queries

Work Information

# Find career and work-related information
response = requests.post(url, headers=headers, json={
    "query": "What does the user do for work?",
    "categories": ["career"],
    "limit": 10
})

Advanced Queries

Contextual Search

# Search with conversation context
response = requests.post(url, headers=headers, json={
    "query": "What would help the user with their career goals?",
    "categories": ["career", "learning"],
    "rerank": True,
    "limit": 10
})

Understanding Search Results

Vector Distance

The vector_distance indicates semantic similarity:

• 0.0-0.3: Highly relevant and closely related
• 0.3-0.6: Moderately relevant
• 0.6-1.0: Less relevant, may be tangentially related

Rerank Score

When rerank: true is enabled, the rerank_score provides enhanced relevance:

• 0.8-1.0: Excellent match for the query
• 0.6-0.8: Good match with clear relevance
• 0.4-0.6: Fair match, some relevance
• 0.0-0.4: Weak match, limited relevance

Result Ordering

Results are ordered by relevance:

1. With reranking: Ordered by rerank_score (descending)
2. Without reranking: Ordered by vector_distance (ascending)

Best Practices

Query Optimization

Use Natural Language

Write queries as natural questions rather than keywords

# ✅ Good
"What technical skills does the user have?"

# ❌ Less effective  
"skills technical programming"

Be Specific

Specific queries often yield better results than generic ones

# ✅ Better
"What programming languages is the user learning?"

# ❌ Too generic
"user learning"

Use Categories

Filter by categories for more targeted results

# For work-related queries
{"query": "user responsibilities", "categories": ["career"]}

# For personal interests
{"query": "user hobbies", "categories": ["interests"]}

Enable Reranking

Use reranking for complex or important queries

# For nuanced queries
{
    "query": "How does the user balance work and personal life?",
    "rerank": True,
    "categories": ["career", "health", "relationships"]
}

Performance Tips

• Appropriate Limits: Use reasonable limits (5-15 for most use cases)
• Category Filtering: Reduce search space with relevant categories
• Caching: Cache frequent queries to improve response times
• Batch Processing: Group related searches when possible

Common Use Cases

Personalized Responses

def get_context_for_response(user_message):
    context_search = {
        "query": f"What's relevant to helping with: {user_message}",
        "limit": 8,
        "rerank": True
    }
    
    response = requests.post(search_url, headers=headers, json=context_search)
    memories = response.json()['memories']
    
    return [m['memory'] for m in memories]

User Analysis

def analyze_user_interests():
    searches = [
        {"query": "What is the user passionate about?", "categories": ["interests"]},
        {"query": "What is the user learning?", "categories": ["learning"]},
        {"query": "What are the user's goals?", "categories": ["career", "health"]}
    ]
    
    analysis = {}
    for search in searches:
        response = requests.post(search_url, headers=headers, json=search)
        analysis[search['query']] = response.json()['memories']
    
    return analysis

Content Recommendations

def get_content_recommendations():
    interests_search = {
        "query": "What topics interest the user?",
        "categories": ["interests", "learning"],
        "limit": 10
    }
    
    response = requests.post(search_url, headers=headers, json=interests_search)
    memories = response.json()['memories']
    
    # Extract topics for content recommendation
    topics = extract_topics_from_memories(memories)
    return generate_content_suggestions(topics)

Rate Limiting

Search endpoints have enhanced rate limiting:

• 50 requests per minute per authenticated user
• Complex queries with reranking may take slightly longer
• Consider implementing client-side caching for frequent queries

Error Codes

Error Code	Description
VALIDATION_ERROR	Invalid request format or parameters
AUTHENTICATION_ERROR	Invalid or missing API key
RATE_LIMIT_EXCEEDED	Too many search requests
NO_MEMORIES_FOUND	No memories exist for the user

Next Steps

Store Memories

Learn how to add memories to search from

User Profiles

Get comprehensive user profiles and insights

Memory Categories

Understand how to use categories effectively

Search Best Practices

Learn advanced search techniques and strategies