Skip to content

kg ontology

Auto-generated

ontology (onto)

Manage ontologies (knowledge domains). Ontologies are named collections that organize concepts into knowledge domains. Each ontology groups related documents and concepts together, making it easier to organize and query knowledge by topic or project.

Usage: 

kg ontology [options]

Subcommands:

  • list - List all ontologies in the knowledge graph. Shows a table with ontology name, file count, chunk count, and concept count. Use this to get a bird's-eye view of all knowledge domains, verify ingestion results, and understand how knowledge is distributed.
  • info - Get detailed information about a specific ontology. Shows statistics (files, chunks, concepts, evidence, relationships) and lists all source files. Use this to understand ontology composition, verify expected files are present, and troubleshoot ingestion issues.
  • files - List files in a specific ontology with per-file statistics (chunks and concepts). Shows which files contributed most concepts and helps identify files that may need re-ingestion. Original file paths are preserved, though temporary paths may appear for text-based ingestion.
  • create - Create an ontology before ingesting any documents (ADR-200: directed growth). This pre-creates the Ontology graph node with an embedding, making the ontology discoverable in the vector space immediately. Useful for planning knowledge domains before populating them.
  • lifecycle - Change ontology lifecycle state (ADR-200 Phase 2). States: active (normal), pinned (immune to demotion), frozen (read-only — rejects ingest and rename).
  • rename - Rename an ontology while preserving all its data (concepts, sources, relationships). This is a non-destructive operation useful for reorganization, archiving old ontologies, fixing typos, or improving clarity. Atomic transaction ensures all-or-nothing updates. Requires confirmation unless -y flag is used.
  • delete - Delete an ontology and ALL its data (concepts, sources, evidence instances, relationships). This is a DESTRUCTIVE operation that CANNOT BE UNDONE. Use this to remove test data, delete old projects, or free up space. Requires --force flag for confirmation. Consider alternatives: rename to add "Archive" suffix, or export data first (future feature).
  • scores - Show cached annealing scores for an ontology (or all ontologies). Shows mass, coherence, exposure, and protection scores. Use "kg ontology score " to recompute.
  • score - Recompute annealing scores for one ontology. Runs mass, coherence, exposure, and protection scoring and caches results.
  • score-all - Recompute annealing scores for all ontologies. Runs full scoring pipeline and caches results on each Ontology node.
  • candidates - Show top concepts by degree centrality in an ontology. High-degree concepts are potential promotion candidates — they may warrant their own ontology.
  • affinity - Show cross-ontology concept overlap. Identifies which other ontologies share concepts with this one, ranked by affinity score.
  • edges - Show ontology-to-ontology edges (OVERLAPS, SPECIALIZES, GENERALIZES). Derived by annealing cycles or created manually.
  • reassign - Move sources from one ontology to another. Updates s.document and SCOPED_BY edges. Refuses if source ontology is frozen.
  • dissolve - Dissolve an ontology non-destructively. Moves all sources to the target ontology, then removes the Ontology node. Unlike delete, this preserves all data. Refuses if ontology is pinned or frozen.
  • proposals - List annealing proposals generated by the annealing cycle. Proposals are promotion or demotion suggestions for ontologies that require human review before execution.
  • proposal - View or review a specific annealing proposal.
  • anneal - Trigger a annealing cycle. Scores all ontologies, recomputes centroids, identifies candidates, and generates proposals for review. Use --dry-run to preview candidates without generating proposals.

list

List all ontologies in the knowledge graph. Shows a table with ontology name, file count, chunk count, and concept count. Use this to get a bird's-eye view of all knowledge domains, verify ingestion results, and understand how knowledge is distributed.

Usage: 

kg list [options]

info

Get detailed information about a specific ontology. Shows statistics (files, chunks, concepts, evidence, relationships) and lists all source files. Use this to understand ontology composition, verify expected files are present, and troubleshoot ingestion issues.

Usage: 

kg info <name>

Arguments:

  • <name> - Ontology name

files

List files in a specific ontology with per-file statistics (chunks and concepts). Shows which files contributed most concepts and helps identify files that may need re-ingestion. Original file paths are preserved, though temporary paths may appear for text-based ingestion.

Usage: 

kg files <name>

Arguments:

  • <name> - Ontology name

create

Create an ontology before ingesting any documents (ADR-200: directed growth). This pre-creates the Ontology graph node with an embedding, making the ontology discoverable in the vector space immediately. Useful for planning knowledge domains before populating them.

Usage: 

kg create <name>

Arguments:

  • <name> - Ontology name

Options:

Option Description Default
-d, --description <text> What this knowledge domain covers -

lifecycle

Change ontology lifecycle state (ADR-200 Phase 2). States: active (normal), pinned (immune to demotion), frozen (read-only — rejects ingest and rename).

Usage: 

kg lifecycle <name> <state>

Arguments:

  • <name> - Ontology name
  • <state> - Target state: active, pinned, or frozen

rename

Rename an ontology while preserving all its data (concepts, sources, relationships). This is a non-destructive operation useful for reorganization, archiving old ontologies, fixing typos, or improving clarity. Atomic transaction ensures all-or-nothing updates. Requires confirmation unless -y flag is used.

Usage: 

kg rename <old-name> <new-name>

Arguments:

  • <old-name> - Current ontology name
  • <new-name> - New ontology name

Options:

Option Description Default
-y, --yes Skip confirmation prompt -

delete

Delete an ontology and ALL its data (concepts, sources, evidence instances, relationships). This is a DESTRUCTIVE operation that CANNOT BE UNDONE. Use this to remove test data, delete old projects, or free up space. Requires --force flag for confirmation. Consider alternatives: rename to add "Archive" suffix, or export data first (future feature).

Usage: 

kg delete <name>

Arguments:

  • <name> - Ontology name

Options:

Option Description Default
-f, --force Skip confirmation and force deletion -

scores

Show cached annealing scores for an ontology (or all ontologies). Shows mass, coherence, exposure, and protection scores. Use "kg ontology score " to recompute.

Usage: 

kg scores [name]

Arguments:

  • <name> - Ontology name (omit for all)

score

Recompute annealing scores for one ontology. Runs mass, coherence, exposure, and protection scoring and caches results.

Usage: 

kg score <name>

Arguments:

  • <name> - Ontology name

score-all

Recompute annealing scores for all ontologies. Runs full scoring pipeline and caches results on each Ontology node.

Usage: 

kg score-all [options]

candidates

Show top concepts by degree centrality in an ontology. High-degree concepts are potential promotion candidates — they may warrant their own ontology.

Usage: 

kg candidates <name>

Arguments:

  • <name> - Ontology name

Options:

Option Description Default
-l, --limit <n> Max concepts "20"

affinity

Show cross-ontology concept overlap. Identifies which other ontologies share concepts with this one, ranked by affinity score.

Usage: 

kg affinity <name>

Arguments:

  • <name> - Ontology name

Options:

Option Description Default
-l, --limit <n> Max ontologies "10"

edges

Show ontology-to-ontology edges (OVERLAPS, SPECIALIZES, GENERALIZES). Derived by annealing cycles or created manually.

Usage: 

kg edges <name>

Arguments:

  • <name> - Ontology name

reassign

Move sources from one ontology to another. Updates s.document and SCOPED_BY edges. Refuses if source ontology is frozen.

Usage: 

kg reassign <from>

Arguments:

  • <from> - Source ontology name

Options:

Option Description Default
--to <target> Target ontology name -
--source-ids <ids...> Source IDs to move -

dissolve

Dissolve an ontology non-destructively. Moves all sources to the target ontology, then removes the Ontology node. Unlike delete, this preserves all data. Refuses if ontology is pinned or frozen.

Usage: 

kg dissolve <name>

Arguments:

  • <name> - Ontology to dissolve

Options:

Option Description Default
--into <target> Target ontology to receive sources -

proposals

List annealing proposals generated by the annealing cycle. Proposals are promotion or demotion suggestions for ontologies that require human review before execution.

Usage: 

kg proposals [options]

Options:

Option Description Default
--status <status> Filter by status: pending, approved, rejected, expired -
--type <type> Filter by type: promotion, demotion -
--ontology <name> Filter by ontology name -

proposal

View or review a specific annealing proposal.

Usage: 

kg proposal <id>

Arguments:

  • <id> - Proposal ID

Options:

Option Description Default
--approve Approve this proposal -
--reject Reject this proposal -
--notes <notes> Review notes -

anneal

Trigger a annealing cycle. Scores all ontologies, recomputes centroids, identifies candidates, and generates proposals for review. Use --dry-run to preview candidates without generating proposals.

Usage: 

kg anneal [options]

Options:

Option Description Default
--dry-run Preview candidates without generating proposals -
--demotion-threshold <threshold> Protection score below which to consider demotion "0.15"
--promotion-min-degree <degree> Minimum concept degree for promotion candidacy "10"
--max-proposals <count> Maximum proposals per cycle "5"