knowledge-graph

knowledge-graph

Build and query knowledge graphs using saige/knowledge.

Quick Start

import (
    "github.com/urmzd/saige/rag/knowledge"
    "github.com/urmzd/saige/postgres"
    "github.com/urmzd/saige/agent/provider/ollama"
)

// Connect to PostgreSQL (requires pgvector extension).
pool, _ := postgres.NewPool(ctx, postgres.Config{URL: "postgres://localhost:5432/mydb"})
postgres.RunMigrations(ctx, pool, postgres.MigrationOptions{})

client, _ := ollama.NewClient(ollama.Config{Host: "http://localhost:11434", Model: "qwen3.5:4b", EmbeddingModel: "nomic-embed-text"})
graph, _ := knowledge.New(knowledge.Config{},
    knowledge.WithPostgres(pool),
    knowledge.WithExtractor(knowledge.NewOllamaExtractor(client)),
    knowledge.WithEmbedder(knowledge.NewOllamaEmbedder(client)),
)
defer graph.Close(ctx)

// Ingest
graph.IngestEpisode(ctx, &knowledge.EpisodeInput{
    Name: "notes", Body: "Alice presented the roadmap.", Source: "meeting",
})

// Search
facts, _ := graph.SearchFacts(ctx, "roadmap")

Key Operations

Method	Purpose
IngestEpisode	Extract entities/relations from text and store them
SearchFacts	Full-text search on relation facts
GetEntity	Retrieve a single entity by ID
GetNode	Get a node with its neighborhood (depth N)
GetGraph	Full graph snapshot for visualization
ApplyOntology	Constrain entity/relation types

Ontology

graph.ApplyOntology(ctx, &knowledge.Ontology{
    EntityTypes:   []knowledge.EntityTypeDef{{Name: "Person", Description: "A human"}},
    RelationTypes: []knowledge.RelationTypeDef{{Name: "works_on", SourceType: "Person", TargetType: "Project"}},
})

The ontology is passed to the extractor, which is asked to use its types. Extracted types that match an ontology type ignoring case and punctuation are rewritten to the ontology's spelling; other types are kept as extracted. Build the graph with knowledge.WithStrictOntology() to drop entities and relations whose type is not in the ontology.

Agent Tool Bindings

import "github.com/urmzd/saige/rag/knowledge/tool"

tools := tool.NewTools(graph, tool.WithGroupID(tenantID))
// kg_search, kg_ingest, both bound to one graph group the model cannot change

In a RAG pipeline, rag.WithGraphNamespace(tenantID) sets the group documents are ingested into and the graph retriever searches.

CLI

saige knowledge search --backend kg --db "$SAIGE_KG_DB" --query "Who presented?"
saige knowledge ingest --backend kg --db "$SAIGE_KG_DB" --name "meeting" --text "Alice presented the roadmap."
saige knowledge graph export  --db "$SAIGE_KG_DB"
saige knowledge graph neighbors   --db "$SAIGE_KG_DB" --id <entity-uuid> --depth 2