Skip to content

Graphiti Integration

Aletheia uses Graphiti as its core knowledge graph engine. This page explains how Aletheia integrates with Graphiti.

What is Graphiti?

Graphiti is a knowledge graph library that:

  • Extracts entities and relationships from text using LLMs
  • Stores data in graph databases (Neo4j, FalkorDB)
  • Provides semantic and graph-based search
  • Supports entity resolution and deduplication

Adding Episodes

Aletheia uses graphiti.add_episode() to ingest content:

from graphiti_core import Graphiti
from graphiti_core.search.search_config import SearchConfig

# Initialize Graphiti
graphiti = Graphiti(
    graph_driver=graph_driver,
    llm_client=llm_client,
    embedder=embedder,
)

# Add content to graph
await graphiti.add_episode(
    name="record-123",
    episode_body=markdown_text,
    group_id="my_graph",
    entity_types={"Person": PersonModel},
    edge_types={"KNOWS": KnowsModel},
)

Searching

Aletheia uses Graphiti's search API for retrieval:

from graphiti_core.search.search_config import (
    SearchConfig,
    NodeSearchConfig,
    EdgeSearchConfig,
    NodeSearchMethod,
    EdgeSearchMethod,
    NodeReranker,
    EdgeReranker,
)

results = await graphiti.search_(
    query="Who founded the company?",
    config=SearchConfig(
        node_config=NodeSearchConfig(
            search_methods=[
                NodeSearchMethod.cosine_similarity,
                NodeSearchMethod.bfs,
            ],
            reranker=NodeReranker.rrf,
        ),
        edge_config=EdgeSearchConfig(
            search_methods=[
                EdgeSearchMethod.cosine_similarity,
                EdgeSearchMethod.bfs,
            ],
            reranker=EdgeReranker.rrf,
        ),
        limit=15,
    ),
    group_ids=["my_graph"],
)

Search Methods

Method Description
cosine_similarity Semantic similarity search
bfs Breadth-first graph traversal
keyword Keyword-based search
Method Description
cosine_similarity Semantic similarity search
bfs Breadth-first graph traversal from matching nodes

Reranking

Reranker Description
rrf Reciprocal Rank Fusion - combines multiple search results
none No reranking

Graphiti supports hierarchical community clustering:

# Build communities
communities, edges = await graphiti.build_communities(
    group_ids=["my_graph"]
)

# Search with communities
results = await graphiti.search_(
    query="What organizations are related?",
    config=SearchConfig(...),
    group_ids=["my_graph"],
)

Entity Types

You can provide Pydantic models for entity extraction:

from pydantic import BaseModel

class PersonModel(BaseModel):
    name: str
    aliases: list[str] = []
    nationality: str | None = None

entity_types = {"Person": PersonModel}

Edge Types

Similarly for relationships:

class SanctionModel(BaseModel):
    authority: str
    date: str | None = None
    program: str | None = None

edge_types = {"SANCTION": SanctionModel}

Learn More