Graph API

Traverse memory relationships, find paths between memories, and extract contextual subgraphs from your knowledge base.

Updated Oct 6, 2026

Overview

The Graph API enables you to explore the relationships between memories, entities, and facts in your knowledge base. Use it to build contextual understanding, find connections, and power intelligent retrieval for your AI applications.

Use Case: Build context for LLM prompts by traversing related memories, find hidden connections between concepts, or visualize your knowledge graph.

Graph Traversal

Endpoint

POST /graph/traverse

Traverse the knowledge graph from one or more starting points, following relationships up to a specified depth.

Body Parameters

Field	Type	Description
start_ids	string[] (required)	Array of memory UUIDs to start traversal from. 1-10 items.
depth	integer	Maximum hops to traverse. Default: 2, Max: 5.
relationship_types	string[]	Filter by relationship types (e.g., `["related_to", "co_accessed"]`).
direction	string	Traversal direction: `outgoing`, `incoming`, or `both` (default).
min_weight	number	Minimum relationship weight to follow. Default: 0.
max_nodes	integer	Maximum nodes to return. Default: 100, Max: 500.
include_content	boolean	Include memory content in nodes. Default: true.
session_id	string	Scope traversal to memories within this session (plus session-agnostic memories).

Response (200)

Example Response

{
  "nodes": [
    {
      "id": "<memory-uuid>",
      "content": "User prefers dark mode",
      "depth": 0
    },
    {
      "id": "<memory-uuid>",
      "content": "User uses VS Code with dark theme",
      "depth": 1
    }
  ],
  "edges": [
    {
      "source_id": "<memory-uuid>",
      "target_id": "<memory-uuid>",
      "relationship_type": "related_to",
      "weight": 0.85
    }
  ]
}

Contextual Subgraph

Endpoint

POST /graph/context

Combines semantic search with graph traversal to find memories related to a concept and their connections. Perfect for building LLM context.

Body Parameters

Field	Type	Description
query	string (required)	Semantic query used to seed the subgraph.
depth	integer	Hops to traverse from each semantic match. Default: 2, Max: 5.
semantic_limit	integer	Number of semantic matches to start from. Default: 5, Max: 20.
semantic_threshold	number	Minimum similarity for semantic matches. Default: 0.5.
relationship_types	string[]	Filter relationship types to follow during traversal.
max_nodes	integer	Maximum total nodes in the returned subgraph. Default: 50, Max: 200.

Response (200)

Example Response

{
  "nodes": [
    {
      "id": "<memory-uuid>",
      "content": "User prefers dark mode and compact layouts",
      "relevance": 0.95,
      "source": "semantic"
    }
  ],
  "edges": [
    {
      "source_id": "<memory-uuid>",
      "target_id": "<memory-uuid>",
      "relationship_type": "related_to",
      "weight": 0.78
    }
  ]
}

Using Context in LLM Prompts

// Get contextual memories for an LLM prompt
const context = await trix.graph.getContext({
  query: userMessage,
  depth: 2,
  maxNodes: 20
});

// Format for LLM
const contextString = context.nodes
  .map(n => `- ${n.content}`)
  .join('\n');

const prompt = `You are a helpful assistant with access to the user's history.

Relevant context:
${contextString}

User: ${userMessage}`;

Graph Expansion

Endpoint

POST /graph/expand

Discover related memories through multi-hop traversal with optional hybrid scoring. Combines graph structure with semantic, temporal, and behavioral signals.

Body Parameters

Field	Type	Description
seed_memory_ids	string[] (required)	Starting memory IDs to expand from.
max_hops	integer	Maximum traversal depth. Default: 2, Max: 5.
min_weight	number	Minimum relationship strength (0-1). Default: 0.3.
relationship_types	string[]	Filter by relationship types.
direction	string	Traversal direction: `outgoing`, `incoming`, or `both` (default).
include_content	boolean	Include full memory content. Default: true.
apply_hybrid_scoring	boolean	Enable multi-signal ranking (semantic 40%, graph 30%, co-activation 20%, recency 5%, salience 5%). Default: false.

Response (200)

Example Response

{
  "seed_memories": ["<memory-uuid>", "<memory-uuid>"],
  "expanded_memories": [
    {
      "id": "<memory-uuid>",
      "content": "User frequently accesses dark mode settings",
      "content_type": "text",
      "tags": ["ui", "preferences"],
      "created_at": "2026-04-10T10:30:00Z",
      "score": 0.87
    }
  ],
  "relationships": [
    {
      "source_id": "<memory-uuid>",
      "target_id": "<memory-uuid>",
      "relationship_type": "related_to",
      "weight": 0.85
    }
  ],
  "stats": {
    "seed_count": 2,
    "expanded_count": 2,
    "final_count": 2,
    "relationships_found": 2,
    "hops_used": 1
  },
  "scoring": {
    "applied": true,
    "weights": {
      "semantic": 0.4,
      "graph": 0.3,
      "co_activation": 0.2,
      "recency": 0.05,
      "salience": 0.05
    }
  }
}

Using Graph Expansion

// Basic expansion from seed memories
const result = await trix.graph.expand({
  seedMemoryIds: ["mem_abc123", "mem_def456"]
});

console.log(`Found ${result.stats.expandedCount} related memories`);

// Advanced expansion with hybrid scoring
const scoredResult = await trix.graph.expand({
  seedMemoryIds: ["mem_abc123"],
  maxHops: 3,
  minWeight: 0.5,
  relationshipTypes: ["related_to", "co_accessed"],
  applyHybridScoring: true
});

// Sort by score (highest first)
const topMemories = scoredResult.expandedMemories
  .sort((a, b) => (b.score || 0) - (a.score || 0))
  .slice(0, 10);

Tip: Use hybrid scoring when you need to rank expanded memories by relevance. The scoring combines multiple signals: semantic similarity (40%), graph proximity (30%), co-activation strength (20%), recency (5%), and salience (5%).

Find Path

Endpoint

POST /graph/path

Find the shortest path between two memories or entities in the knowledge graph.

Body Parameters

Field	Type	Description
source_id	string (required)	Starting memory UUID.
target_id	string (required)	Target memory UUID.
max_depth	integer	Maximum path length. Default: 4, Max: 6.
relationship_types	string[]	Only follow these relationship types.
session_id	string	Scope path search to memories within this session (plus session-agnostic).

Response (200)

Example Response

{
  "source_id": "<memory-uuid>",
  "target_id": "<memory-uuid>",
  "path": [
    { "id": "<memory-uuid>", "content": "Project uses React for frontend", "content_type": "text", "tags": [] },
    { "id": "<memory-uuid>", "content": "React is a JavaScript library", "content_type": "text", "tags": [] }
  ],
  "relationships": ["related_to"],
  "length": 1
}

Get Neighbors

Endpoint

GET /graph/neighbors/:id

Get memories directly connected to a memory via the graph. Simpler and faster than full traversal.

Path Parameters

Field	Type	Description
id	string (required)	The memory UUID.

Query Parameters

Field	Type	Description
depth	integer	Hops to traverse. Default: 1, Max: 5.
direction	string	Direction: `outgoing`, `incoming`, or `both` (default).
types	string	Comma-separated relationship types to include.
limit	integer	Maximum neighbors to return. Default: 20, Max: 100.
session_id	string	Scope neighbors to memories within this session (plus session-agnostic).

Response (200)

Example Response

{
  "source_id": "<memory-uuid>",
  "neighbors": [
    {
      "id": "<memory-uuid>",
      "content": "User uses VS Code",
      "relationship_type": "related_to",
      "direction": "outgoing",
      "weight": 0.82
    }
  ],
  "count": 1
}

Graph Statistics

Endpoint

GET /graph/stats

Returns aggregate statistics for the account's knowledge graph (memory/relationship counts, type distributions).

Response (200)

Example Response

{
  "total_memories": 1247,
  "total_relationships": 3892,
  "relationship_types": {
    "related_to": 2100,
    "co_accessed": 890,
    "extracted_from": 902
  }
}

Relationship Types

The memory_relationships table stores a free-form relationship_type string. The most common automatically-produced values are:

Type	Description
`related_to`	General semantic relationship between memories
`co_accessed`	Memories accessed together during the same session
`extracted_from`	Produced during memory derivation/enrichment

Applications may create additional relationship types via the Relationships API. Entity-level relationships (person-to-organization, etc.) live on the knowledge-graph side and are queried through /knowledge/entities/:id/relationships.

Common Use Cases

Building RAG Context

Use /graph/context to gather relevant memories for LLM prompts. The API combines semantic search with graph traversal for comprehensive context.

Smart Memory Expansion

Use /graph/expand to discover related memories from seed starting points. With hybrid scoring, you can rank results by combining graph structure, semantic similarity, co-activation patterns, recency, and salience for more relevant results.

Knowledge Exploration

Use /graph/traverse to explore connections starting from a known memory. Great for discovering related information the user didn't explicitly ask about.

Finding Hidden Connections

Use /graph/path to find how two seemingly unrelated concepts are connected. Useful for reasoning and explaining relationships.

Visualizing Knowledge

Use /graph/stats and /graph/traverse to build interactive knowledge graph visualizations in your application.