Knowledge Graph

The Knowledge Graph API exposes entities extracted from memories and the relationships between them. Use it to discover people, organizations, places, and concepts mentioned across memories — and to traverse how they connect to each other.

Graph endpoints require the hasKnowledgeGraph entitlement on your plan. All endpoints require memory.read.

Endpoint Overview

Method	Path	Description
GET	/v1/graph/entities	List all entities in the workspace
GET	/v1/graph/entities/:id	Get full details of an entity
GET	/v1/graph/entities/:id/relationships	Get outgoing and incoming relationships of an entity
GET	/v1/graph/search	Semantic search for entities
GET	/v1/graph/traverse	Multi-hop graph traversal from a starting entity
POST	/v1/graph/query	Natural language query over the graph

---

Entity Object

Field	Type	Description
id	string	UUID of the entity
name	string	Canonical entity name
type	string	Entity type: PERSON, ORGANIZATION, PLACE, THING
description	string | null	Short description extracted from memories
metadata	object | null	Additional structured metadata
relationships_count	number	Total number of relationships
related_memories_count	number	Number of memories referencing this entity
created_at	string	ISO 8601 creation timestamp
updated_at	string	ISO 8601 last-update timestamp

---

List Entities

GET/v1/graph/entities

API Key

List all entities in the workspace, paginated

Parameter	Type	Description
user_id	string	Filter entities linked to a specific user
type	string	Filter by entity type: `PERSON`, `ORGANIZATION`, `PLACE`, or `THING`
page	number	Page number, starting at 1 (default: 1)
page_size	number	Results per page, max 100 (default: 20)

curl "https://api.memsolus.com/v1/graph/entities?type=PERSON&page=1" \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "João Silva",
      "type": "PERSON",
      "description": "Software engineer, works at Acme Corp",
      "created_at": "2026-01-10T08:00:00.000Z"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Acme Corp",
      "type": "ORGANIZATION",
      "description": "Technology company focused on SaaS products",
      "created_at": "2026-01-10T08:01:00.000Z"
    }
  ],
  "total": 24,
  "page": 1,
  "page_size": 20
}

---

Get Entity

GET/v1/graph/entities/:id

API Key

Get full details of a single entity

curl https://api.memsolus.com/v1/graph/entities/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "João Silva",
  "type": "PERSON",
  "description": "Software engineer, works at Acme Corp",
  "metadata": { "seniority": "senior", "domain": "backend" },
  "relationships_count": 5,
  "related_memories_count": 12,
  "created_at": "2026-01-10T08:00:00.000Z",
  "updated_at": "2026-01-18T14:30:00.000Z"
}

Returns 404 ENTITY_NOT_FOUND if the entity does not exist or belongs to another workspace.

---

Get Entity Relationships

GET/v1/graph/entities/:id/relationships

API Key

Get all relationships of an entity, grouped into outgoing and incoming

curl https://api.memsolus.com/v1/graph/entities/a1b2c3d4-e5f6-7890-abcd-ef1234567890/relationships \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "entity_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "entity_name": "João Silva",
  "outgoing": [
    {
      "id": "rel-uuid-1",
      "type": "WORKS_AT",
      "weight": 0.95,
      "target": {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "name": "Acme Corp",
        "type": "ORGANIZATION"
      }
    },
    {
      "id": "rel-uuid-2",
      "type": "USES_TECHNOLOGY",
      "weight": 0.87,
      "target": {
        "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
        "name": "TypeScript",
        "type": "THING"
      }
    }
  ],
  "incoming": [
    {
      "id": "rel-uuid-3",
      "type": "MANAGES",
      "weight": 0.78,
      "source": {
        "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
        "name": "Maria Souza",
        "type": "PERSON"
      }
    }
  ]
}

The weight field (0.0–1.0) represents the strength of the relationship as extracted from memories.

---

Search Entities

GET/v1/graph/search

API Key

Semantic search for entities by natural language query

Parameter	Type	Description
queryrequired	string	Natural language search query (max 500 chars)
user_id	string	Filter results by user ID
type	string	Filter by entity type: `PERSON`, `ORGANIZATION`, `PLACE`, or `THING`
limit	number	Maximum results to return, max 50 (default: 10)

curl "https://api.memsolus.com/v1/graph/search?query=backend+engineer+TypeScript&limit=5" \
  -H "X-Api-Key: msk_live_..."

200Success

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "João Silva",
    "type": "PERSON",
    "description": "Software engineer, works at Acme Corp",
    "score": 0.94
  },
  {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "name": "Ana Lima",
    "type": "PERSON",
    "description": "Full-stack developer specializing in TypeScript",
    "score": 0.81
  }
]

The score field (0.0–1.0) indicates semantic similarity to the query.

---

Traverse Graph

GET/v1/graph/traverse

API Key

Walk relationships outward from a starting entity up to 3 hops

Parameter	Type	Description
fromrequired	string (UUID)	UUID of the starting entity
depth	number	Number of hops to traverse: 1–3 (default: 2)
relationship_type	string	Filter traversal to a specific relationship type (e.g., `WORKS_AT`)
entity_type	string	Filter traversal to a specific entity type (e.g., `PERSON`)
limit	number	Maximum number of edges to return, max 100 (default: 50)

curl "https://api.memsolus.com/v1/graph/traverse?from=a1b2c3d4-e5f6-7890-abcd-ef1234567890&depth=2" \
  -H "X-Api-Key: msk_live_..."

200Success

{
  "nodes": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "João Silva", "type": "PERSON" },
    { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Acme Corp", "type": "ORGANIZATION" },
    { "id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "TypeScript", "type": "THING" }
  ],
  "edges": [
    {
      "id": "rel-uuid-1",
      "source": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "target": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "type": "WORKS_AT",
      "weight": 0.95
    },
    {
      "id": "rel-uuid-2",
      "source": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "target": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "type": "USES_TECHNOLOGY",
      "weight": 0.87
    }
  ]
}

Returns 404 ENTITY_NOT_FOUND if the starting entity does not exist or belongs to another workspace.

---

Natural Language Query

POST/v1/graph/query

API Key

Answer a natural language question using the knowledge graph

Parameter	Type	Description
queryrequired	string	Natural language question to answer (max 1000 chars)
user_id	string	Scope the query to a specific user's graph context
limit	number	Maximum number of entities to consider, max 20 (default: 10)

curl -X POST https://api.memsolus.com/v1/graph/query \
  -H "X-Api-Key: msk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What projects is João Silva working on?",
    "user_id": "user-123"
  }'

200Success

{
  "answer": "João Silva is currently working on the Alpha Platform project at Acme Corp.",
  "confidence": 0.88,
  "entities_used": [
    { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "João Silva", "type": "PERSON" },
    { "id": "f6a7b8c9-d0e1-2345-fabc-456789012345", "name": "Alpha Platform", "type": "THING" },
    { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Acme Corp", "type": "ORGANIZATION" }
  ]
}

The confidence field (0.0–1.0) reflects how well the graph data supports the answer. Low confidence answers may be based on limited or indirect relationships.

---

Knowledge

Compiled knowledge entries per user

→

Memories

Raw memories that feed entity extraction

→

SDK Usage

Graph operations via the TypeScript SDK

→