Skip to content

quicue-kg

Software projects lose knowledge. Decisions get re-litigated because nobody remembers the rationale. Failed approaches get retried because the rejection was never recorded. Patterns spread without anyone tracking where they're used. The institutional memory lives in someone's head, and when they leave, it leaves with them.

quicue-kg puts that knowledge in your git repo as typed CUE data. The type system does the enforcing — every rejected approach must record an alternative, every insight must cite evidence, every decision must state consequences. Validation is cue vet. No database, no server, no wiki.

kg init
kg add rejected --approach "SQLite" \
    --reason "Concurrent writes fail under load" \
    --alternative "PostgreSQL with connection pooling"
kg vet
kg search "SQLite"

That generates .kg/ entries like this:

package kg

import "quicue.ca/kg/core@v0"

r001: core.#Rejected & {
    id:          "REJ-001"
    approach:    "SQLite"
    reason:      "Concurrent writes fail under load"
    date:        "2026-02-16"
    alternative: "PostgreSQL with connection pooling"
}

CUE validates this at build time. Missing alternative? Type error. Empty reason? Type error. Malformed ID? Type error.

What's different

Knowledge conflicts are type errors. Two teams federate their .kg/ directories. Both have an entry for ADR-003 but disagree on the status. CUE unification fails. The contradiction surfaces at build time, not in a meeting six months later. There is no silent last-write-wins.

Every rejection must redirect. The alternative field on #Rejected is required, not optional. A rejection without a redirect is a conversation that loops — "we tried that" with no forward path. This constraint turns dead ends into signposts.

People are their own lexicographers. The four core types (#Decision, #Insight, #Rejected, #Pattern) are open CUE structs. Add cost_estimate, team, sprint, whatever your project needs. The framework validates the parts it knows about and leaves the rest alone.

Federation without infrastructure. Merge knowledge across repos with kg --dir ~/api/.kg --dir ~/web/.kg search "caching". The transport is git clone. The conflict detector is the CUE type checker. No SPARQL endpoint, no shared database.

Schema evolution is a quality ratchet. Add a required field to #Decision and every existing entry without it becomes a validation error. Knowledge quality only goes up.

The four types

Type ID What it captures
#Decision ADR-001 Architecture decisions — status lifecycle, mandatory rationale, consequences
#Insight INSIGHT-001 Validated discoveries — evidence, confidence, discovery method
#Rejected REJ-001 Failed approaches — reason, required alternative
#Pattern by name Reusable solutions — cross-project usage tracking via struct-as-set

There are also extension types for project identity, multi-repo topology, and data pipeline provenance, and aggregation types for computed summaries and lint checks.

Entries automatically export as PROV-O provenance graphs, DCAT catalog entries, and Web Annotations via CUE comprehensions — no separate export step, no drift.

Install

go build -o kg ./cmd/kg

kg init sets up the CUE schema imports. For using the schemas without the CLI, see the technical reference.

CLI

kg init                 Scaffold .kg/ directory
kg add <type>           Create entry (decision|insight|pattern|rejected)
kg vet                  Validate via cue vet
kg search <query>       Full-text search across all entries
kg index [--full]       Export summary or full index as JSON
kg graph [--dot]        Relationship graph (D3 JSON or Graphviz DOT)

Every command accepts --dir (repeatable, supports git URLs). Remote repos are shallow-cloned.

There's also kg serve (web explorer with D3.js graph), kg tui (terminal UI, vim keys), kg lsp (editor hover + completion), kg fed (discover and federate .kg/ directories), kg lint, kg settle, and kg export-static.

Reference

Apache-2.0