Skip to main content
Cortex automatically builds a knowledge graph from your content, extracting entities and their relationships to help your AI understand not just individual pieces of information, but how everything connects. This means your AI can provide richer, more contextual answers by understanding the web of relationships in your data.

​
What is a Knowledge Graph?

A knowledge graph is a network of entities (people, organizations, projects, products, concepts) and the relationships between them. Instead of treating each document as isolated text, Cortex understands the underlying structure of your information. Think of it this way: Semantic search finds documents that mention similar concepts. A knowledge graph understands how those concepts actually relate. When you search for “Project Phoenix budget”, semantic search finds documents containing those semantics. The knowledge graph knows that Sarah Chen leads Project Phoenix, which depends on the Authentication Service, was approved by the Engineering VP, and has a Q2 deadline—providing rich relational context that flat search simply cannot capture. Knowledge Graph

​
How It Works

​
Automatic Entity Extraction

When you upload content to Cortex, our system automatically:
  1. Identifies entities in your documents (people, organizations, projects, products, technical terms, etc.)
  2. Extracts relationships between entities with rich contextual information
  3. Builds a connected graph that captures how everything relates
  4. Updates dynamically as you add more content
All of this happens automatically—no manual tagging or configuration required.
Zero Configuration Required: Knowledge graphs are built automatically for all content you upload. There’s nothing to set up or configure.

​
Intelligent Entity Disambiguation

Cortex automatically resolves entity ambiguity using contextual understanding. Consider the name “Mercury”—it could refer to a team member’s name, a customer company, a project codename, or the chemical element. Cortex disambiguates entities by analyzing:
  • Surrounding context: What’s being discussed when the entity is mentioned
  • Source type: Whether it’s from an email, document, meeting note, or support ticket
  • Unique identifiers: Email addresses, employee IDs, URLs, or other identifiers that definitively identify entities
  • Relationship patterns: Who interacts with this entity and in what capacity
This contextual intelligence ensures that “Mercury” the team member is never confused with “Mercury” the customer company or “Mercury” the project, even if all appear across your documents.

​
Cross-Source Entity Linking

Cortex automatically connects entities across different sources when they share matching identifiers or appear in similar contexts: Automatic Connection Examples:
  • If two documents mention “John Smith” and both reference the email [email protected], Cortex merges them into one entity
  • If a Slack conversation and a project document both discuss “Project Phoenix” with consistent context, they’re automatically linked
  • When multiple sources reference the same customer ID or employee number, all information is unified under one entity
Pro Tip: Including unique identifiers in your content (email addresses, employee IDs, ticket numbers, URLs) helps Cortex connect entities more accurately. The more specific your identifiers, the better the entity linking.
Closing the Semantic Gap: Traditional vector search understands meaning but not structure. It can find similar content but cannot tell you that Document A’s “critical bug” is the same issue mentioned in Document B’s support ticket, or that three different teams are working on related aspects of the same project. Knowledge graphs bridge this gap by understanding actual relationships, not just semantic similarity—enabling your AI to reason about connections that pure semantic search would miss. Closing the Semantic Gap

​
Entity Types

Cortex recognizes various entity types including:
  • People: Team members, customers, stakeholders
  • Organizations: Companies, departments, teams
  • Projects: Initiatives, products, features
  • Technical Terms: APIs, error codes, system components
  • Concepts: Business processes, methodologies, frameworks
Each entity is tracked with:
  • Name: The entity’s identifier
  • Type: What kind of entity it is
  • Namespace: Contextual categorization (e.g., “employees”, “projects”, “customers”)
  • Relationships: Connections to other entities with detailed context

​
Relationship Context

For every relationship between entities, Cortex captures:
  • The relationship type: “works for”, “reports to”, “depends on”, “caused by”
  • Rich context: Detailed information about how and why entities are related
  • Source references: Which documents contain evidence of this relationship
  • Temporal details: Time-based information like “last week” or “in 2023”

​
Automatic Availability

Available Everywhere: Knowledge graph context is automatically included in all search and retrieval responses. You don’t need to make special API calls.
Every time you use Cortex’s search or question-answering endpoints, the knowledge graph works behind the scenes to enhance results with relevant entity relationships.

​
How to Use Graph Context

​
In Search Results

When you search for information, Cortex automatically enhances results with graph context: What you get in each search result:
  • chunks[].graph_triplet_ids: IDs linking to specific triplets in graph_relations.chunk_triplets
  • graph_relations.entity_paths: Multi-hop paths connecting entities from your query—often provides complete context for complex questions
  • graph_relations.chunk_triplets: Individual triplets mapped by ID, referenced from each chunk
{
  "chunks": [
    {
      "chunk_uuid": "doc_a1b2c3d4e5f6...",
      "chunk_content": "Sarah Chen founded Acme Corp in 2019 after leaving her role at TechGiant.",
      "source_title": "company-history.md",
      "relevancy_score": 0.85,
      "graph_triplet_ids": ["g_0"]
    },
    {
      "chunk_uuid": "doc_x7y8z9a0b1c2...",
      "chunk_content": "Marcus Johnson joined as CTO and leads the Platform team, reporting directly to Sarah.",
      "source_title": "org-structure.md",
      "relevancy_score": 0.72,
      "graph_triplet_ids": ["g_1", "g_2"]
    }
  ],
  "graph_relations": {
    "entity_paths": [
      {
        "combined_context": "Sarah Chen is the founder and CEO of Acme Corp. | Marcus Johnson serves as CTO at Acme Corp. | Marcus reports directly to Sarah Chen.",
        "triplets": [
          {
            "source": {"name": "Sarah Chen", "type": "PERSON", "namespace": "employees"},
            "target": {"name": "Acme Corp", "type": "ORGANIZATION"},
            "relation": {"canonical_predicate": "FOUNDER_OF", "context": "Sarah Chen founded Acme Corp in 2019."}
          },
          {
            "source": {"name": "Marcus Johnson", "type": "PERSON", "namespace": "employees"},
            "target": {"name": "Acme Corp", "type": "ORGANIZATION"},
            "relation": {"canonical_predicate": "WORKS_AT", "context": "Marcus Johnson is the CTO at Acme Corp."}
          },
          {
            "source": {"name": "Marcus Johnson", "type": "PERSON"},
            "target": {"name": "Sarah Chen", "type": "PERSON"},
            "relation": {"canonical_predicate": "REPORTS_TO", "context": "Marcus reports directly to Sarah."}
          }
        ],
        "relevancy_score": 0.78
      }
    ],
    "chunk_triplets": {
      "g_0": {
        "source": {"name": "Sarah Chen", "type": "PERSON"},
        "target": {"name": "Acme Corp", "type": "ORGANIZATION"},
        "relation": {"canonical_predicate": "FOUNDER_OF", "context": "Sarah Chen founded Acme Corp in 2019 after leaving TechGiant."},
        "relevancy_score": 0.85
      },
      "g_1": {
        "source": {"name": "Marcus Johnson", "type": "PERSON"},
        "target": {"name": "Acme Corp", "type": "ORGANIZATION"},
        "relation": {"canonical_predicate": "WORKS_AT", "context": "Marcus Johnson is the CTO at Acme Corp."},
        "relevancy_score": 0.72
      },
      "g_2": {
        "source": {"name": "Marcus Johnson", "type": "PERSON"},
        "target": {"name": "Sarah Chen", "type": "PERSON"},
        "relation": {"canonical_predicate": "REPORTS_TO", "context": "Marcus reports directly to Sarah as CTO."},
        "relevancy_score": 0.68
      }
    }
  }
}

​
Understanding the Response Structure

​
Entity Paths (graph_relations.entity_paths)

Multi-hop paths connecting entities from your query. Each path contains a combined_context summarizing the full relationship chain—this often provides all the context you need for complex, multi-hop questions. When to use: For questions like “How is X related to Y?” or “Who works with the founder?”—the combined_context gives you a ready-to-use summary.

​
Chunk Triplets (graph_relations.chunk_triplets)

A mapping of triplet IDs to individual entity relationships. Each chunk references its triplets via graph_triplet_ids. When to use: When building context per-chunk for your LLM. Use a Set to track seen triplet IDs and avoid duplicating context across chunks.

​
Practical Applications

​
Building Context for Your LLM

When passing the response to an LLM, use a Set to deduplicate triplet context across chunks:
  • JavaScript
  • Python
const response = await cortex.search.retrieve({
  query: "Who reports to Sarah?",
  tenant_id: "acme-corp",
  max_chunks: 10
});

const { chunks, graph_relations } = response;
const seenTriplets = new Set();
let context = "";

// Build per-chunk context with deduplicated triplets
for (const chunk of chunks) {
  context += `\n---\n${chunk.chunk_content}\n`;
  
  for (const tripletId of chunk.graph_triplet_ids || []) {
    if (seenTriplets.has(tripletId)) continue;
    seenTriplets.add(tripletId);
    
    const triplet = graph_relations?.chunk_triplets?.[tripletId];
    if (triplet) {
      context += `[${triplet.source.name}] → ${triplet.relation.canonical_predicate} → [${triplet.target.name}]: ${triplet.relation.context}\n`;
    }
  }
}

// Add entity paths for multi-hop context
for (const path of graph_relations?.entity_paths || []) {
  const startEntity = path.triplets[0]?.source.name;
  const endEntity = path.triplets[path.triplets.length - 1]?.target.name;
  context += `\n[Path: ${startEntity} → ${endEntity}]\n${path.combined_context}\n`;
}

​
Quick Access to Multi-Hop Context

For complex questions, entity_paths often provides everything you need:
  • JavaScript
  • Python
// entity_paths gives you pre-computed multi-hop context
const paths = response.graph_relations?.entity_paths || [];

for (const path of paths) {
  // combined_context has the full relationship chain summarized
  console.log(path.combined_context);
  
  // Or extract start/end entities if needed
  const start = path.triplets[0]?.source;
  const end = path.triplets[path.triplets.length - 1]?.target;
  console.log(`${start?.name} (${start?.type}) → ... → ${end?.name} (${end?.type})`);
}

​
Key Benefits

  1. Deeper Understanding: Your AI doesn’t just match keywords—it understands how concepts, people, and projects relate to each other.
  2. Richer Context: Every answer is informed by the broader context of relationships, not just isolated facts.
  3. Better Relevance: Search results include not just matching documents, but related entities that provide additional useful context.
  4. Automatic Maintenance: The graph updates as you add content, maintaining an always-current view of your information landscape.
  5. Privacy & Isolation: Each tenant’s knowledge graph is completely isolated, ensuring data privacy and security.

​
Use Cases

  1. Customer Support: Understand relationships between error codes, affected systems, and past solutions to provide faster, more accurate support.
  2. Sales Enablement: Connect prospects with relevant case studies, team members, and product capabilities based on relationship patterns.
  3. Research & Discovery: Help users explore connections between research papers, authors, methodologies, and findings.
  4. Project Management: Track relationships between team members, projects, dependencies, and deliverables automatically.
  5. Onboarding: Help new team members understand organizational structure, project relationships, and key stakeholders.

​
Best Practices

​
Make the Most of Graph Context

For search results:
  • Use chunk_triplets via graph_triplet_ids to show entities mentioned in each chunk
  • Display relationship information to help users understand context at a glance
For AI-generated answers:
  • Use entity_paths.combined_context for multi-hop questions—it’s often all you need
  • Deduplicate chunk_triplets with a Set when building per-chunk context
For UX features:
  • Create “related entities” sidebars using triplet data
  • Build navigation features that follow relationship links
  • Use entity mentions to create automatic cross-references

​
Understanding Graph Quality

The knowledge graph gets smarter as you add more content:
  • More documents = More complete relationship networks
  • Detailed content = Richer relationship context
  • Clear writing = Better entity extraction accuracy

​
Privacy Considerations

  • Knowledge graphs are tenant-isolated by default
  • Each tenant’s graph only contains entities from their own content
  • Sub-tenants can have their own scoped graphs for additional organization

​
Getting Started

Knowledge graphs work automatically—just start using Cortex’s search and retrieval endpoints:
  1. Upload your content using any Knowledge Ingestion endpoint
  2. Use Search or Q&A via Search or Q&A endpoints
  3. Access graph context in graph_relations.entity_paths and graph_relations.chunk_triplets
  4. Enhance your UI by displaying entity relationships alongside results
That’s it! The knowledge graph is built and maintained automatically behind the scenes.

​
Technical Details

For developers interested in the underlying structure:Each relationship in the graph stores multiple “evidences” from different documents, allowing the system to:
  • Track how relationships evolve over time
  • Provide multiple sources for each connection
  • Weight relationships based on frequency and relevance
  • Update relationships as new information arrives

​
FAQ

  1. Do I need to enable knowledge graphs?
    No, they’re automatically built for all content and included in all retrieval responses.
  2. Can I customize entity extraction?
    The system uses advanced AI models optimized for accuracy. Custom extraction rules aren’t currently exposed, but the system handles most use cases automatically.
  3. How do I see all entities in my graph?
    Use the search endpoints with entity names to explore relationships. A dedicated graph visualization interface may be available in the future.
  4. Does this work with AI memories?
    Yes! AI memories are also processed through the knowledge graph, helping your AI understand relationships in user-specific context.
  5. What if entity extraction makes mistakes?
    The system uses multiple evidences to validate relationships. As you add more content, accuracy improves naturally.
  6. How is this different from vector search?
    Vector search finds semantically similar content. Knowledge graphs understand explicit relationships. Cortex uses both together for optimal results.