Skip to main content

Searching Memories

Memsolus provides three search modes you can choose from depending on your use case. All modes support filtering by user, agent, categories, and priority.

Search Modes​

hybrid (default)​

Combines semantic understanding with keyword matching to deliver the best results across most queries. Use this mode when you are not sure which other mode to pick — it is optimized for general-purpose retrieval.

const results = await client.memories.search({
  query: 'preferred programming language',
  userId: 'user_123',
  mode: 'hybrid',
});

semantic​

Searches by meaning rather than exact words. Finds memories that are conceptually related to your query, even if they use completely different phrasing.

Use semantic search when you want to find similar ideas or when the exact wording is unpredictable.

const results = await client.memories.search({
  query: 'what tools does the user prefer?',
  userId: 'user_123',
  mode: 'semantic',
});

keyword​

Searches for exact terms and phrases. Useful when you need to find a specific name, ID, or phrase that must appear verbatim.

const results = await client.memories.search({
  query: 'NestJS',
  userId: 'user_123',
  mode: 'keyword',
});

Available Filters​

You can combine any of these filters with any search mode:

FilterTypeDescription
user_idstringReturn only memories for this user
agent_idstringReturn only memories created by this agent
session_idstringReturn only memories from this session
categoriesstring[]Return only memories with these categories
priorityenumFilter by LOW, MEDIUM, or HIGH
curl -X POST https://api.memsolus.com/v1/memories/search \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "preferred tools",
    "user_id": "user_123",
    "categories": ["tech_stack", "preferences"],
    "priority": "HIGH",
    "mode": "hybrid"
  }'

How Results Are Ranked​

Search results are ranked by a combination of three factors:

  • Relevance — how closely the memory matches the query
  • Recency — more recently created memories rank slightly higher
  • Priority — HIGH priority memories surface before MEDIUM and LOW

The balance between these factors is automatically adjusted based on the nature of your query. You do not need to tune weights manually.

Search Feedback​

You can submit feedback on individual search results to help improve future rankings. Feedback is optional but improves result quality over time.

await client.memories.feedback('mem_abc123', {
  rating: 'POSITIVE', // POSITIVE, NEGATIVE, or NEUTRAL
});
curl -X POST https://api.memsolus.com/v1/memories/mem_abc123/feedback \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "rating": "POSITIVE" }'

Full Example​

import { Memsolus } from '@memsolus/sdk';

const client = new Memsolus({ apiKey: 'msk_live_...' });

const results = await client.memories.search({
  query: 'What does the user think about remote work?',
  userId: 'user_123',
  mode: 'semantic',
  categories: ['preferences', 'work_context'],
  limit: 5,
});

for (const memory of results.data) {
  console.log(memory.content, memory.score);
}