Relationship Mapping

Entity graphs and knowledge connections

Relationship mapping automatically extracts entities from your memories and builds a knowledge graph. Query connections between users, products, concepts, and more.

How It Works

When you store memories, the API automatically extracts entities and relationships. You can also explicitly define relationships for more control.

// Automatic extraction (AI-powered)
await memory.store({
  content: "John from Acme Corp purchased the Enterprise plan",
  entityId: "conversation_789"
});
// Automatically creates:
// - Entity: "John" (person)
// - Entity: "Acme Corp" (company)
// - Entity: "Enterprise plan" (product)
// - Relationship: John → belongs_to → Acme Corp
// - Relationship: Acme Corp → purchased → Enterprise plan

// Explicit relationships
await memory.store({
  content: "User prefers email notifications",
  entityId: "user_123",
  relationships: [
    { type: "prefers", target: "notification_email" },
    { type: "belongs_to", target: "team_456" }
  ]
});

Relationship Types

Use predefined relationship types or create custom ones. Consistent naming helps with querying and graph traversal.

Type	Description	Example
`belongs_to`	Hierarchical ownership (user → team)	"user_123" belongs_to "team_456"
`relates_to`	General association	"product_A" relates_to "category_B"
`purchased`	Transaction relationship	"user_123" purchased "product_A"
`viewed`	Interaction tracking	"user_123" viewed "page_home"
`similar_to`	Similarity connections	"product_A" similar_to "product_B"
`mentioned_in`	Reference tracking	"entity_X" mentioned_in "doc_Y"

Creating Relationships

// Create relationships directly
await memory.relationships.create({
  from: "user_123",
  to: "team_456",
  type: "belongs_to",
  metadata: {
    role: "admin",
    joinedAt: "2024-01-15"
  }
});

// Batch create relationships
await memory.relationships.createBatch([
  { from: "user_123", to: "project_A", type: "works_on" },
  { from: "user_123", to: "project_B", type: "works_on" },
  { from: "project_A", to: "team_456", type: "belongs_to" }
]);

// Create bidirectional relationship
await memory.relationships.create({
  from: "user_A",
  to: "user_B",
  type: "collaborates_with",
  bidirectional: true  // Creates both directions
});

Graph Operations

Traverse

Follow relationships from a starting entity to discover connected nodes.

// Find all products a user has interacted with
const graph = await memory.relationships.traverse({
  start: "user_123",
  types: ["purchased", "viewed", "liked"],
  depth: 1
});

Shortest Path

Find the shortest connection between two entities.

// How is user_A connected to user_B?
const path = await memory.relationships.shortestPath({
  from: "user_A",
  to: "user_B",
  maxDepth: 4
});

Neighbors

Get all directly connected entities of specific types.

// Find all teams and projects for a user
const neighbors = await memory.relationships.neighbors({
  entity: "user_123",
  types: ["belongs_to", "works_on"],
  direction: "outgoing"
});

Querying with Relationships

Include relationship context in your memory queries to get richer results.

// Query memories with relationship expansion
const results = await memory.query({
  text: "pricing discussions",

  // Include related entities in results
  includeRelationships: true,
  relationshipDepth: 2,

  // Filter by relationship
  withRelationship: {
    type: "belongs_to",
    target: "team_enterprise"
  },

  limit: 10
});

// Results include relationship context
results.forEach(mem => {
  console.log(mem.content);
  console.log("Related entities:", mem.relationships);
  // [{ type: "mentioned", entity: "Enterprise plan" }, ...]
});

// Query based on graph position
const teamMemories = await memory.query({
  text: "project updates",

  // Find memories from entities connected to this team
  entityGraph: {
    root: "team_456",
    traverseTypes: ["belongs_to", "works_on"],
    direction: "incoming",
    depth: 2
  }
});

Entity Types

Entities are automatically typed when extracted, or you can specify types explicitly.

person

Users, contacts, team members

organization

Companies, teams, departments

product

Products, services, features

location

Cities, addresses, regions

event

Meetings, milestones, dates

concept

Topics, categories, tags

// Explicit entity creation with type
await memory.entities.create({
  id: "acme_corp",
  type: "organization",
  name: "Acme Corporation",
  metadata: {
    industry: "Technology",
    size: "Enterprise"
  }
});

// Query entities by type
const companies = await memory.entities.list({
  type: "organization",
  withRelationships: true
});

Graph Visualization

Export your relationship graph for visualization in tools like Neo4j, Gephi, or custom D3.js visualizations.

// Export graph data
const graphData = await memory.relationships.export({
  format: "cypher",  // or "graphml", "json"
  entities: ["user_*", "team_*"],  // Pattern matching
  relationshipTypes: ["belongs_to", "works_on"]
});

// Returns Cypher statements for Neo4j import
// CREATE (n:User {id: "user_123", ...})
// CREATE (n)-[:BELONGS_TO]->(m)

// JSON export for custom visualization
const jsonGraph = await memory.relationships.export({
  format: "json",
  includeMetadata: true
});
// { nodes: [...], edges: [...] }

Best Practices

✓Use consistent entity IDs across your application (e.g., user_123, team_456)
✓Prefer specific relationship types over generic ones for better queryability
✓Add metadata to relationships for richer context (timestamps, roles, scores)
✓Limit traversal depth to avoid performance issues with deeply connected graphs
✓Use bidirectional relationships sparingly—most relationships are naturally directional

Next Steps

Temporal Awareness Cost Optimization