Knowledge Graph Federation¶

Federate multiple .kg/ directories — local or remote — into a single queryable graph. No database, no API server, no shared infrastructure. Just git clone and cue vet.

How it works¶

Every .kg/ directory is a self-contained CUE package. Federation is the process of loading multiple .kg/ directories and merging their entries into a single index. The merge follows CUE unification semantics:

Scenario	Result
Different IDs	Combined into one namespace
Same ID, compatible content	Unified (set fields merge via union)
Same ID, conflicting content	Error — surfaces the contradiction

The third case is the key property: conflicts are detected at merge time, not silently ignored. If project A says "Use PostgreSQL" and project B says "Use MySQL" for the same decision ID, federation fails with an explicit error message identifying both assertions.

Set-valued fields (related, used_in) merge via union. If project A records used_in: {"project-a": true} and project B records used_in: {"project-b": true} for the same pattern, the federated result is used_in: {"project-a": true, "project-b": true}.

Usage¶

Multiple local directories¶

# Load two .kg/ directories and search across both
kg --dir ~/project-a/.kg --dir ~/project-b/.kg search "PostgreSQL"

# Merge and export combined graph
kg --dir ~/project-a/.kg --dir ~/project-b/.kg graph --dot | dot -Tsvg > federated.svg

# Validate all entries across both directories
kg --dir ~/project-a/.kg --dir ~/project-b/.kg vet

The --dir flag is repeatable. Every command — index, graph, search, serve, tui, lsp, export-static — works with multiple sources.

Discovery¶

Walk a directory tree to find all .kg/ directories:

# Discover all knowledge graphs under ~/projects/
kg fed ~/projects/
# Output:
# Discovered 3 knowledge graph(s):
#   /home/user/projects/api-server/.kg
#   /home/user/projects/web-frontend/.kg
#   /home/user/projects/infra/.kg

# Discover and merge with summary
kg fed --json ~/projects/
# Output:
# Merged: 47 entries
# {"total_decisions": 18, "total_insights": 12, ...}

Discovery looks for .kg/cue.mod/module.cue — the marker that a directory contains a valid CUE-based knowledge graph.

Remote repositories¶

Point --dir at a git URL to clone and load a remote .kg/:

# Clone a repo and load its .kg/ directory
kg --dir https://github.com/org/project.git --dir .kg search "caching"

# Federate local + remote
kg --dir .kg --dir https://github.com/org/other-project.git graph

Remote sources are shallow-cloned to a temp directory, loaded, and cleaned up automatically. The clone is read-only — write operations (add) always target the first --dir (the "primary" directory).

Web explorer with federation¶

# Start the web UI with federated data from three projects
kg --dir ~/api/.kg --dir ~/web/.kg --dir ~/infra/.kg serve --port 8787

The D3.js force-directed graph visualizes entries from all sources in a single view, with kind-based coloring (decisions, insights, patterns, rejected).

Conflict resolution¶

Federation is opinionated: conflicts are errors, not warnings. If two .kg/ directories contain entries with the same ID but different core content, the merge fails:

Error: merge ~/project-b/.kg: conflict: decision "ADR-001" exists in both
graphs with different content

To resolve: 1. Rename the entry in one project if they're genuinely different decisions 2. Align the content if they describe the same decision (CUE unification will succeed once content matches) 3. Add a namespace prefix to IDs if projects need independent ID spaces

This is a deliberate design choice. Silent conflict resolution (last-write-wins, merge heuristics) erases the information that two teams disagree. A type error forces explicit human resolution.

Architecture¶

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│ project-a/  │   │ project-b/  │   │ github.com/ │
│   .kg/      │   │   .kg/      │   │ org/repo    │
└──────┬──────┘   └──────┬──────┘   └──────┬──────┘
       │                 │                  │
       │  ResolveSource  │  ResolveSource   │ git clone --depth=1
       │  (local path)   │  (local path)    │ → temp dir → .kg/
       ▼                 ▼                  ▼
   LoadFromKGDir    LoadFromKGDir     LoadFromKGDir
   (cue export)     (cue export)      (cue export)
       │                 │                  │
       └────────┬────────┘──────────────────┘
                │
            Merge (conflict detection)
                │
                ▼
        ┌───────────────┐
        │ Unified Index │ → search, graph, serve, tui, export
        └───────────────┘

Each .kg/ is loaded independently via cue export . -e _index, producing a JSON index. The Go-level merge replicates CUE's unification semantics: disjoint entries combine, compatible entries merge set fields, conflicting entries error.

Comparison with other approaches¶

vs. ADR tools (adr-tools, Log4brains, MADR)¶

Feature	adr-tools	Log4brains	MADR	quicue-kg
Format	Markdown	Markdown	Markdown	CUE (typed)
Validation	None	Template check	Template check	Full type system
Cross-project	No	No	No	Federation with conflict detection
Relationships	Manual links	Supersedes only	Supersedes only	Typed `related`, `supersedes`, `used_in`
Entry types	Decisions only	Decisions only	Decisions only	Decisions + Insights + Patterns + Rejected
Computed views	No	Static site	No	CUE comprehensions (always in sync)
Schema evolution	N/A	N/A	N/A	Adding required field = every entry must comply
Graph viz	No	No	No	DOT, VizData JSON, D3 web explorer

ADR tools record decisions as markdown files. They're simple and work well for single projects. But they can't validate structure, can't express relationships between entries, and have no concept of cross-project knowledge.

vs. Federated knowledge graphs (SPARQL Federation, OriginTrail DKG, FSKL)¶

Feature	SPARQL Fed.	OriginTrail DKG	quicue-kg
Infrastructure	SPARQL endpoints	Blockchain nodes	None (git)
Query language	SPARQL	SPARQL/DKG API	CUE expressions
Conflict handling	Last-write-wins	Consensus	Type error (explicit)
Schema	OWL ontologies	Schema.org	CUE definitions
Deployment	Servers + triplestore	Blockchain + nodes	`git clone`
Latency	Network-dependent	Consensus-dependent	Local filesystem

Traditional knowledge graph federation requires infrastructure: SPARQL endpoints, triplestore databases, or blockchain consensus. quicue-kg federation is zero-infrastructure — the transport layer is git clone, the merge layer is CUE unification, and the query layer is local computation.

vs. Git-based knowledge management (BMAD-Federated-Knowledge)¶

The BMAD-METHOD project has a similar idea: git-based federated knowledge with priority-based conflict resolution. Key differences:

BMAD uses YAML/Markdown with priority ordering for conflicts. quicue-kg uses CUE with type-error-based conflict detection (no silent resolution).
BMAD targets AI agent workflows. quicue-kg targets architectural knowledge.
BMAD resolves conflicts via priority tiers (local > project > org > community). quicue-kg surfaces conflicts as errors requiring explicit resolution.

What's genuinely novel¶

No existing system combines all three of these properties:

Zero-infrastructure federation — git clone is the transport, cue vet is the merge. No servers, no blockchain, no SPARQL endpoint.
Typed conflict detection — Contradictions surface as build-time type errors, not silent overwrites or priority-based resolution.
Set-valued field union — The struct-as-set idiom ({[string]: true}) gives clean union semantics: which projects use a pattern, which entries are related — these merge automatically and correctly.

The closest analog is CUE itself — CUE unification already has these properties. quicue-kg just applies them to architectural knowledge management.