Skip to main content
The knowledge graph stores structured relationships between entities, with full bi-temporal tracking.

​
Entities (Nodes)

Entities represent named concepts: people, projects, technologies, organizations, etc. 
{
  "name": "React",
  "summary": "JavaScript UI library by Meta",
  "entityType": "technology"
}
Entity names are embedded as vectors for semantic search via search_graph.

​
Edges (Relationships)

Edges connect two entities with a typed relationship and an optional fact. 
{
  "sourceId": "node_alice",
  "targetId": "node_acme",
  "relation": "works_at",
  "fact": "Alice has been a senior engineer at Acme since 2024"
}
Edge facts are embedded for vector search.

​
Bi-Temporal Model

Edges support bi-temporal tracking:
FieldPurpose
validAtWhen the fact became true in the real world
invalidAtWhen the fact stopped being true
expiredAtWhen the edge was superseded in the system

​
Updating Facts

When a fact changes, update_edge preserves history:
  1. The old edge is invalidated (marked with expiredAt and invalidAt)
  2. A new edge is created with the updated fact and a fresh validAt
The old edge remains in the database for historical queries, but is excluded from active searches.

​
Invalidation

Use invalidate_edge when a relationship ends without replacement: 
"Alice no longer works at Acme" → invalidate_edge(edge_id)

​
Graph Traversal

search_graph combines two search strategies:
  1. Vector search — Find relevant nodes and edges by semantic similarity
  2. Graph traversal — Walk N hops from hit nodes to discover connected entities
The traverseDepth parameter controls traversal:
ValueBehavior
0Vector search only, no traversal
1Include direct neighbors of hit nodes
2Include neighbors of neighbors
Traversed nodes receive a lower score (0.5) than direct vector hits (1.0).