Entities

Entities represent knowledge graph nodes -- people, organizations, technologies, and other named concepts. Link entities to memories to build a traversable knowledge graph across your agent's memory.

Entity Types

Type	Description
person	A person or individual
organization	A company, team, or group
technology	A programming language, framework, or tool
project	A project or initiative
product	A product or service
location	A physical or virtual location
document	A document, file, or URL
metric	A KPI, measurement, or statistic
event	A meeting, milestone, or occurrence
skill	A capability or competency
concept	An abstract idea or topic
other	Anything that does not fit the above

Type Aliases

The alias place is accepted and automatically mapped to location.

Create Entity

POST /v1/entities

Request Body

Field	Type	Required	Description
name	string	Yes	Entity name (1-255 characters)
entity_type	string	Yes	One of the entity types listed above (also accepts type as an alias)
metadata	object	No	Custom metadata (max 10KB)

Response 201 Created

{
  "object": "entity",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "John Doe",
  "entity_type": "person",
  "metadata": {
    "role": "customer",
    "tier": "premium"
  },
  "memory_count": 0,
  "relationship_count": 0,
  "created_at": "2026-03-17T12:00:00Z",
  "updated_at": "2026-03-17T12:00:00Z"
}

curl

curl -X POST https://api.memoryrelay.net/v1/entities \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "entity_type": "person",
    "metadata": { "role": "customer", "tier": "premium" }
  }'

Python SDK

from memoryrelay import MemoryRelay

client = MemoryRelay(api_key="mem_prod_...")

entity = client.entities.create(
    name="John Doe",
    entity_type="person",
    metadata={"role": "customer", "tier": "premium"},
)
print(entity.id)

---

List Entities

GET /v1/entities

Query Parameters

Parameter	Type	Default	Description
limit	integer	20	Results per page (1-100)
offset	integer	0	Number of results to skip
entity_type	string	--	Filter by entity type

Response

{
  "object": "list",
  "data": [
    {
      "object": "entity",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "John Doe",
      "entity_type": "person",
      "metadata": { "role": "customer" },
      "memory_count": 7,
      "relationship_count": 3,
      "created_at": "2026-03-17T12:00:00Z",
      "updated_at": "2026-03-17T12:00:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null,
  "total_count": 1
}

curl

curl "https://api.memoryrelay.net/v1/entities?entity_type=person&limit=20" \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

entities = client.entities.list(entity_type="person", limit=20)
for entity in entities.data:
    print(f"{entity.name} ({entity.entity_type}): {entity.memory_count} memories")

---

Get Entity

GET /v1/entities/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Entity ID

Response

Returns a single entity object.

curl

curl https://api.memoryrelay.net/v1/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

entity = client.entities.get("550e8400-e29b-41d4-a716-446655440000")
print(f"{entity.name}: {entity.memory_count} linked memories")

---

Update Entity

PATCH /v1/entities/{id}

Path Parameters

Parameter	Type	Description
id	UUID	Entity ID

Request Body

Field	Type	Required	Description
name	string	No	Updated name (1-255 characters)
entity_type	string	No	Updated entity type
metadata	object	No	Updated metadata (merged with existing)

Response

Returns the updated entity object.

curl

curl -X PATCH https://api.memoryrelay.net/v1/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Smith",
    "metadata": { "tier": "enterprise" }
  }'

Python SDK

updated = client.entities.update(
    "550e8400-e29b-41d4-a716-446655440000",
    name="John Smith",
    metadata={"tier": "enterprise"},
)

---

Delete Entity

DELETE /v1/entities/{id}

Soft-delete an entity. Associated memory links are preserved but the entity is excluded from queries.

Path Parameters

Parameter	Type	Description
id	UUID	Entity ID

Response

Returns 204 No Content on success.

curl

curl -X DELETE https://api.memoryrelay.net/v1/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY"

Python SDK

client.entities.delete("550e8400-e29b-41d4-a716-446655440000")

---

Link Entity to Memory

POST /v1/entities/link

Create a connection between an entity and a memory with an optional relationship label. This builds the knowledge graph by associating entities with the memories that reference them.

Request Body

Field	Type	Required	Description
entity_id	UUID	Yes	ID of the entity to link
memory_id	UUID	Yes	ID of the memory to link
relationship	string	No	Relationship label (default: mentioned_in). Examples: mentioned_in, created_by, relates_to, authored_by

Response 201 Created

{
  "entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "relevance_score": 1.0,
  "created_at": "2026-03-17T12:30:00Z"
}

curl

curl -X POST https://api.memoryrelay.net/v1/entities/link \
  -H "Authorization: Bearer $MEMORYRELAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entity_id": "550e8400-e29b-41d4-a716-446655440000",
    "memory_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "relationship": "mentioned_in"
  }'

Python SDK

link = client.entities.link(
    entity_id="550e8400-e29b-41d4-a716-446655440000",
    memory_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    relationship="mentioned_in",
)

Auto-Extraction

When creating memories, set auto_extract_entities: true to automatically identify and link entities from the memory content. This uses NLP to detect names, organizations, technologies, and other entity types.