Docs | Tutorial | Release Notes
build-kg turns any topic into a structured knowledge graph — stored in your own PostgreSQL. One command. Fully automated. Open-source.
v0.3.0 — Generalized knowledge graph builder
- Any-topic support with automatic ontology generation
- Generic profiles with LLM-designed graph structures
- Nullable regulatory fields for non-regulatory domains
- Full release notes →
Three steps. That's it.
# 1. Clone and setup
git clone https://github.com/agtm1199/build-kg.git && cd build-kg && make setup
# 2. Configure your API key
cp .env.example .env # edit .env → set API key + DB password
# 3. Build a knowledge graph
/build-kg kubernetes networkingYour coding agent handles everything autonomously:
→ Generates an ontology (Component, Concept, Configuration)
→ Researches authoritative sources
→ Crawls official documentation
→ Chunks documents by section boundaries
→ Loads to PostgreSQL
→ Parses with LLM into your graph
→ Outputs: queryable knowledge graph in Apache AGE
Building knowledge graphs is hard. The #1 pain point? Ontology design — figuring out the right node types, relationships, and properties for your domain.
Most tools hand you an empty graph database and say "good luck." You spend weeks modeling your domain before you can even start loading data.
build-kg takes the opposite approach. Tell your coding agent what you want a graph about. It designs the ontology, finds the sources, and builds the graph — all in one command. The graph lives in your own PostgreSQL. Open-source, self-hosted, no vendor lock-in.
/build-kg kubernetes networking
/build-kg machine learning optimization algorithms
/build-kg React architecture patterns
/build-kg distributed systems consensus algorithmsExample: "kubernetes networking"
The agent auto-generates this graph structure:
Component "kube-proxy"
| type: proxy, layer: L4
|
+-- USES ----------> Concept: "iptables"
| category: packet filtering
|
+-- CONFIGURES ----> Configuration: "service.spec.type"
default_value: ClusterIP, scope: service
Example: "machine learning optimization"
Different topic, different ontology — auto-generated:
Algorithm "Adam optimizer"
| type: gradient-based, family: adaptive
|
+-- APPLIES -------> Technique: "momentum"
| category: first-order
|
+-- USED_IN -------> Application: "neural network training"
domain: deep learning
🤖 Works with 8 Coding Agent Platforms
build-kg is a skill file, not a CLI tool. It runs inside your coding agent — with native support for 8 platforms:
| Agent | Skill File | Activation |
|---|---|---|
| Claude Code | .claude/skills/build-kg/SKILL.md |
Auto-detected. Type /build-kg <topic> |
| Amazon Kiro | .claude/skills/build-kg/SKILL.md |
Auto-detected (Agent Skills standard). Type /build-kg <topic> |
| Qoder | .claude/skills/build-kg/SKILL.md |
Auto-detected (Agent Skills standard). Type /build-kg <topic> |
| Antigravity | .claude/skills/build-kg/SKILL.md |
Auto-detected (Agent Skills standard). Type /build-kg <topic> |
| OpenAI Codex | AGENTS.md |
Auto-detected. Ask "build a knowledge graph about <topic>" |
| GitHub Copilot | .github/copilot-instructions.md |
Auto-detected. Ask "build a knowledge graph about <topic>" |
| Cursor | .cursor/rules/build-kg.mdc |
Auto-detected. Ask "build a knowledge graph about <topic>" |
| Windsurf | .windsurf/rules/build-kg.md |
Auto-detected. Ask "build a knowledge graph about <topic>" |
All skill files ship with the repo — cloning is all it takes.
🧬 Automatic Ontology Generation
No more weeks of domain modeling. The agent analyzes your topic and generates:
- Node types with meaningful properties
- Relationship types that capture real connections
- A JSON schema the parser uses for structured extraction
🔄 6-Phase Automated Pipeline
Phase 0 Phase 0.5 Phase 1 Phase 2 Phase 3 Phase 4 Phase 5
INIT ONTOLOGY DISCOVER CRAWL CHUNK LOAD PARSE
-------- -------- -------- -------- -------- -------- --------
Set graph Auto-gen WebSearch Crawl4AI Unstructured PostgreSQL Claude Haiku 3.5
name, dirs ontology WebFetch async crawl smart chunks + AGE LLM extraction
Each phase is independently runnable and resumable.
🗄️ Self-Hosted PostgreSQL + Apache AGE
- Graph stored in your own PostgreSQL via Apache AGE extension
- Query with Cypher or SQL — no proprietary query language
- No cloud dependency, no data leaves your machine
- Docker Compose included for zero-config setup
📦 Domain Profiles
Extensible YAML profiles with custom ontologies, prompts, and source templates:
| Profile | Domain | Description |
|---|---|---|
default |
Generic | Any topic — ontology auto-generated by the agent |
Create custom profiles for your domain (pharma, legal, telecom, etc.) — see the docs.
💰 Minimal Cost
The only cost is LLM API calls during parsing. Everything else runs locally.
| Fragments | Sync | Batch (50% off) |
|---|---|---|
| 100 | ~$0.03 | ~$0.015 |
| 1,000 | ~$0.30 | ~$0.15 |
| 5,000 | ~$1.50 | ~$0.75 |
Standard Install
git clone https://github.com/agtm1199/build-kg.git
cd build-kg
make setupcp .env.example .env
# Edit .env → set your API key and DB password
make verifyPrerequisites
- A coding agent: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf, Amazon Kiro, Qoder, or Antigravity
- Docker (for PostgreSQL + Apache AGE)
- Anthropic API key or OpenAI API key (for LLM parsing)
All configuration is via .env file or environment variables:
View all configuration options
| Variable | Default | Description |
|---|---|---|
LLM_PROVIDER |
anthropic |
LLM provider (anthropic or openai) |
ANTHROPIC_API_KEY |
-- | Anthropic API key |
ANTHROPIC_MODEL |
claude-haiku-4-5-20251001 |
Anthropic model for parsing |
OPENAI_API_KEY |
-- | OpenAI API key (if using OpenAI) |
OPENAI_MODEL |
gpt-4o-mini |
OpenAI model for parsing |
DB_HOST |
localhost |
PostgreSQL host |
DB_PORT |
5432 |
PostgreSQL port |
DB_NAME |
buildkg |
Database name |
DB_USER |
buildkg |
Database user |
DB_PASSWORD |
-- | Database password (required) |
AGE_GRAPH_NAME |
knowledge_graph |
Apache AGE graph name |
DOMAIN |
default |
Domain profile name or path |
| Documentation | Complete reference — architecture, configuration, troubleshooting |
| Tutorial | Hands-on guide from setup to querying your first knowledge graph |
| Release Notes | What's new in v0.3.0 |
build-kg-viewer is the visual companion to build-kg — explore your knowledge graphs interactively with AI-powered queries.
# Point build-kg-viewer at your build-kg database and start exploring
git clone https://github.com/agtm1199/build-kg-viewer.git && cd build-kg-viewer
npm run setup && npm startFeatures: 24+ visualization components, AI chat (natural language to Cypher), dark mode, path finder, graph algorithms, and more. Same PostgreSQL database — no data export needed.
- PyPI package (
pip install build-kg) -
Web UI for graph exploration→ build-kg-viewer - Multi-source graphs (combine topics into one graph)
- Incremental updates (add to existing graphs)
- More domain profiles (pharma, legal, finance, telecom)
- Graph enrichment passes (entity resolution, link prediction)
Have an idea? Open an issue or start a discussion.
We welcome contributions of all kinds! See CONTRIBUTING.md for setup instructions.
Ways to contribute:
- Add a domain profile for your area (pharma, environmental, telecom, etc.)
- Improve the pipeline — better chunking, parsing prompts, or graph enrichment
- Build integrations — new agent platforms, visualization tools, export formats
- Report bugs and suggest features via GitHub Issues
This project is licensed under the Apache License 2.0 — see the LICENSE file for details.
If you use build-kg in your project, consider adding a badge:
[](https://github.com/agtm1199/build-kg)If you use build-kg in academic work:
@software{build-kg,
title={build-kg: Open-source Knowledge Graph Builder for AI Agents},
url={https://github.com/agtm1199/build-kg},
license={Apache-2.0},
year={2025}
}If you find build-kg useful, give it a star! It helps others discover the project.
build-kg — turn any topic into a knowledge graph.
Built with ❤️ for the open-source AI community.