Entity Management

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

The Memory API provides powerful capabilities for managing entities and their relationships. This guide will show you how to create, retrieve, and work with entities in your knowledge graph.

What are Entities?

Entities represent distinct objects, concepts, people, places, or any other discrete elements in your knowledge domain. They form the nodes in your knowledge graph and can be connected through relationships.

Entities allow you to organize memories around specific subjects, making it easier to build context and retrieve relevant information.

Creating Entities

To create a new entity, send a POST request to the /entities endpoint:

// Example of creating an entity
const response = await fetch('https://api.example.com/entities', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    tenantId: "tenant-123",
    type: "person",
    name: "Alice Smith",
    properties: {
      age: 32,
      occupation: "Software Engineer",
      interests: ["AI", "Machine Learning", "Hiking"]
    }
  })
});

const result = await response.json();
console.log(result.entity.id); // The unique ID of the created entity

Required Parameters

Parameter	Type	Description
tenantId	string	ID of the tenant this entity belongs to
type	string	The type of entity (e.g., “person”, “place”, “concept”)
name	string	A human-readable name for the entity

Optional Parameters

Parameter	Type	Description
properties	object	Additional properties specific to this entity
aliases	string[]	Alternative names or identifiers for this entity
metadata	object	Additional metadata for the entity

Retrieving Entities

To retrieve a specific entity by its ID:

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

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

Searching for Entities

To search for entities based on various criteria:

// Example of searching for entities
const response = await fetch('https://api.example.com/entities/search', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    tenantId: "tenant-123",
    type: "person",
    query: "Alice",
    limit: 10
  })
});

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

Search Parameters

Parameter	Type	Description
tenantId	string	ID of the tenant to search entities for
type	string	Optional filter by entity type
query	string	Search query to match against entity names and aliases
limit	number	Maximum number of results to return (default: 20)

Creating Relationships

Relationships connect entities to each other, forming the edges in your knowledge graph. To create a relationship:

// Example of creating a relationship between entities
const response = await fetch('https://api.example.com/relationships', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    tenantId: "tenant-123",
    sourceId: "ent-alice",
    targetId: "ent-bob",
    type: "KNOWS",
    properties: {
      since: "2023-01-01",
      strength: "strong"
    }
  })
});

const result = await response.json();
console.log(result.relationship.id); // The unique ID of the created relationship

Required Parameters for Relationships

Parameter	Type	Description
tenantId	string	ID of the tenant this relationship belongs to
sourceId	string	ID of the source entity
targetId	string	ID of the target entity
type	string	The type of relationship (e.g., “KNOWS”, “LOCATED_IN”)

Retrieving Entity Relationships

To retrieve all relationships for a specific entity:

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

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

Entity-Memory Connections

Entities can be connected to memories by including entityIds when creating a memory:

// Example of creating a memory with entity connections
const response = await fetch('https://api.example.com/memory', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_API_KEY'
  },
  body: JSON.stringify({
    tenantId: "tenant-123",
    content: "Alice mentioned she's working on a new AI project.",
    type: "long-term",
    entityIds: ["ent-alice", "ent-ai-project"]
  })
});

This automatically establishes connections between the memory and the specified entities.

Best Practices for Entity Management

1. Use consistent entity types across your application to maintain a clean knowledge graph

2. Create meaningful relationships that accurately represent how entities are connected

3. Use entity IDs in memories to build a rich network of interconnected information

4. Keep entity properties focused on attributes that don’t change frequently

5. Use aliases for entities that might be referred to by different names

When designing your entity model, think about the types of questions you'll want to answer with your knowledge graph. This will help you determine which entities and relationships to create.

What to Learn Next

Now that you understand how to work with entities and their relationships, your next step should be:

1. Next: Advanced RAG Techniques - Implement semantic search for better context

Following this sequence will complete your knowledge of the Memory API and prepare you for advanced implementation.