MCP Tools
relate_entities
Create directed relationships between entities
Create directed relationships between entities to build a knowledge graph.
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
fromEntity | string | REQUIRED | - | Source entity name (1-200 chars) |
relation | string | REQUIRED | - | Relation type (1-100 chars) |
toEntity | string | REQUIRED | - | Target entity name (1-200 chars) |
fromEntityType | enum | OPTIONAL | inferred | Type of source entity |
toEntityType | enum | OPTIONAL | inferred | Type of target entity |
Common Relation Types
| Relation | Example |
|---|---|
works_at | Ada works_at Acme Corp |
knows | Alice knows Bob |
prefers | User prefers TypeScript |
created | Team created Project Alpha |
part_of | Module part_of System |
related_to | Concept A related_to Concept B |
uses | Project uses PostgreSQL |
manages | Manager manages Team |
Example Request
{
"fromEntity": "Ada",
"relation": "works_at",
"toEntity": "Acme Corp"
}Response
Compact Mode (Default)
When COMPACT_RESPONSES=true (default), responses use short keys to reduce token usage by 40-60%:
{"ok":true,"rel":"550e8400","from":{"id":"550e8401","n":"Ada","t":"person"},"to":{"id":"550e8402","n":"Acme Corp","t":"organization"}}Key mapping: ok=success, rel=relationId, n=name, t=type
Verbose Mode
When COMPACT_RESPONSES=false:
{
"success": true,
"message": "Created relation: Ada works_at Acme Corp",
"relationId": "550e8400-e29b-41d4-a716-446655440000",
"fromEntity": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"name": "Ada",
"type": "person"
},
"toEntity": {
"id": "550e8400-e29b-41d4-a716-446655440002",
"name": "Acme Corp",
"type": "organization"
}
}Auto-Creation
If entities don't exist, they are automatically created:
- Entity types are inferred from context if not provided
- Default type is
conceptif type cannot be inferred - Existing entities keep their original type
Use Cases
Organization Structure
{
"fromEntity": "Ada",
"relation": "works_at",
"toEntity": "Engineering Team",
"fromEntityType": "person",
"toEntityType": "organization"
}Project Dependencies
{
"fromEntity": "Project Alpha",
"relation": "uses",
"toEntity": "PostgreSQL",
"fromEntityType": "project",
"toEntityType": "concept"
}Knowledge Connections
{
"fromEntity": "React",
"relation": "related_to",
"toEntity": "JavaScript"
}Relation Directionality
Relations are directed (from → to):
Ada works_at Acmemeans Ada is the employeeAcme employs Adawould be the inverse
Use query_memory with mode="entity" to see both outgoing and incoming relations.
Duplicate Relations
If the same relation already exists, the existing relation is returned:
{
"success": true,
"message": "Created relation: Ada works_at Acme Corp",
"relationId": "existing-relation-id"
}Errors
| Error | Cause | Fix |
|---|---|---|
| Self-referential relation | fromEntity and toEntity are the same | Use different entity names |
| Invalid entity name | Name exceeds 200 chars or is empty | Provide names between 1-200 chars |
| Invalid relation type | Relation exceeds 100 chars or is empty | Provide relation between 1-100 chars |
| Memory not enabled | ENABLE_MEMORY feature flag is false | Set ENABLE_MEMORY=true |
| Database error | Connection or query failure | Check DB connectivity and logs |