Retrieving Memories

import Callout from ’../../../components/Callout.astro’;

The Memory API provides several methods for retrieving memories, each optimized for different use cases. This guide will show you how to efficiently fetch and search memories.

Direct Memory Retrieval

To retrieve a specific memory by its ID, send a GET request to the /memory/{id} endpoint:

// Example of retrieving a specific memory by ID
const response = await fetch('https://api.example.com/memory/mem-123456', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const result = await response.json();
console.log(result.memory); // The retrieved memory

Always include the tenant ID in your requests to ensure you're only accessing memories that belong to the correct tenant.

Querying Memories

For more complex retrieval needs, use the /memories/query endpoint to search across your memories:

// Example of querying memories
const response = await fetch('https://api.example.com/memories/query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    tenantId: "tenant-123",
    type: "long-term",
    tags: ["preferences"],
    limit: 10,
    offset: 0
  })
});

const result = await response.json();
console.log(result.memories); // Array of matching memories

Query Parameters

Parameter	Type	Description
tenantId	string	ID of the tenant to query memories for
type	enum	Optional filter by memory type
tags	string[]	Optional filter by tags
source	string	Optional filter by source
fromDate	string	Optional filter for memories created after this date
toDate	string	Optional filter for memories created before this date
limit	number	Maximum number of results to return (default: 50)
offset	number	Number of results to skip (for pagination)

Semantic Search

For long-term and semantic RAG memories, you can perform semantic searches based on content similarity:

// Example of semantic search
const response = await fetch('https://api.example.com/memories/semantic-search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    tenantId: "tenant-123",
    query: "User preferences for dark mode",
    limit: 5,
    minScore: 0.7
  })
});

const result = await response.json();
console.log(result.memories); // Array of semantically similar memories

Semantic search finds memories that are conceptually similar to your query, even if they don't contain the exact same words.

Semantic Search Parameters

Parameter	Type	Description
tenantId	string	ID of the tenant to search memories for
query	string	The search query text
limit	number	Maximum number of results to return (default: 10)
minScore	number	Minimum similarity score (0-1) for results
type	enum	Optional filter by memory type
tags	string[]	Optional filter by tags

Entity-Based Retrieval

To retrieve all memories related to a specific entity, use the /entities/{id}/memories endpoint:

// Example of retrieving memories related to an entity
const response = await fetch('https://api.example.com/entities/person-alice/memories', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const result = await response.json();
console.log(result.memories); // Array of memories related to the entity

This is particularly useful for building context around specific entities in your knowledge graph.

Memory Retrieval Best Practices

To optimize your memory retrieval:

1. Use the right retrieval method for your use case:

   • Direct retrieval for known memory IDs
   • Query for filtering by metadata
   • Semantic search for finding conceptually similar content
   • Entity-based retrieval for building context around entities

2. Limit result sets to improve performance, especially with semantic search

3. Combine retrieval methods for complex scenarios:

   // Example: First find relevant entities, then get their memories
   const entityResponse = await fetch('https://api.example.com/entities/search?q=conference');
   const entities = await entityResponse.json();
   
   // Then get memories for each entity
   const memoryPromises = entities.map(entity =>
     fetch(`https://api.example.com/entities/${entity.id}/memories`)
   );
   const memoryResponses = await Promise.all(memoryPromises);

Semantic search operations require more processing than direct or query-based retrieval. Use them judiciously for best performance.

What to Learn Next

Now that you understand how to retrieve memories, your next steps should be:

1. Next: Entity Management - Master working with entities and their relationships
2. Then: Advanced RAG Techniques - Implement semantic search for better context

Following this sequence will build your knowledge systematically and prepare you for advanced implementation.