KG-SSOT

KG-SSOT

The trust layer for a company brain: knowledge graphs in plain text where a confirmed claim must cite its source, a decision records what it replaced and what it rests on, and a decision comes back for review when a source it pinned changes.

English | Português (Brasil)

Documentation · Adopt it · The contract · Conformance suite · Changelog · For AI agents

The contract in 40 seconds: a claim without a source is refused, then fixed, queried and gated.

---

Why

A company brain is usually built by piling documents into RAG or GraphRAG. That keeps the data, but not the decisions: who decided what, on which source, and whether that source still holds. Teams, of people or of agents, pile up conclusions such as "the retry is idempotent" or "we decided on three attempts", and on the way they lose three things: the source, the date it was last verified and what depends on it. When the person who decided leaves, the reasoning leaves too.

KG-SSOT treats this as a format problem, not a discipline problem. Knowledge lives in a .kg.yaml graph, versioned next to the code, and a formal contract decides in CI what fails:

• a confirmed or production node without provenance fails (a claim with no recoverable source is declared unverifiable instead);
• a source that is only a placeholder (unknown, n/a, tbd) fails;
• an edge that points nowhere fails, and so does a node with no edges;
• a verification stamp with nothing to check against, a decision with no origin and a production claim backed only by testimony raise warnings.

What it does for a company brain

Business, technical, compliance and design knowledge can live in the same format, in your repository. It plugs in as a Python package or an MCP server, with a JavaScript validator on npm, and the CI gate is one of its uses, not the point. The pins are checked when kg_query or kg_trace.py runs with --root.

Get started in 60 seconds

pip install kg-ssot

the conformance suite against the reference reader, from the installed package

kg-conformance | tail -2

one valid graph and one that fails

kg-validate valid.kg.yaml broken.kg.yaml

Or straight from the repository, with hash-checked dependencies:

git clone https://github.com/marciocar/kg-ssot && cd kg-ssot

python3 -m venv .venv && .venv/bin/pip install --require-hashes -r tools/requirements.txt .venv/bin/python3 -I tools/kg_validate.py \ spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml \ spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml

PASS spec/conformance/fixtures/latest/form/minimal/valid-minimal.kg.yaml

FAIL spec/conformance/fixtures/latest/form/minimal/bad-node-missing-label.kg.yaml MUST form.required.node.label ×1 · 2 files; 1 pass the MUST; 0 with a SHOULD warning (kg-contract-v4.schema.json + kg-contract-v4.should.schema.json)

The tools print in English by default and in Brazilian Portuguese when your locale is pt_BR (or KG_SSOT_LANG=pt-BR). Codes, exit codes and JSON keys never change with the language; only the human text does.

Install

A node, inside

- id: C_RETRY_SAFE

node_type: claim plane: PROD status: confirmed impact: 4 confidence: 0.8 label: The payment retry is idempotent. verified_at: "2026-10-01" verified_against: tests/payment_retry_test.py provenance: source: tests/payment_retry_test.py locator: test_retry_is_idempotent method: "measurement: integration test in CI"

The label is the claim, short. The provenance says where it came from and how: one of five method classes, measurement, reading, judges, derived or testimony. The stamp says when it was verified and against what. Since contract v4.16 these English names are the canonical form; the Portuguese medição, leitura, juízes, derivado and testemunho are still accepted as aliases, with no warning.

Use it from an AI agent

The reference MCP server gives a model the contract and a store: it validates a graph, writes only what passes, reads, lists, queries with every edge resolved to the label on the other end, and shows history. Read-only tools are annotated as such, so a client can skip confirmation for them.

kg-mcp --root ./graphs          # stdio, for Claude Desktop, Claude Code and other MCP clients

kg_schema_help returns the current contract, a minimal passing example and the fixes for the most common codes, so a model can write a passing graph on the first try. llms.txt indexes the documentation for agents, and llms-full.txt has all of it in one file.

The agent skill. skills/kg-ssot/ is an Agent Skills skill that teaches a coding agent to write, fix, validate and query graphs with these tools, in .kg.yaml and .kg.json. In a pre-registered test, an agent with the skill reached the same result with 45% of the output tokens and 54% of the tool calls.

npx skills add marciocar/kg-ssot -s kg-ssot     # Claude Code, Codex and other clients that read Agent Skills

In Claude Code, it also comes as a plugin: /plugin marketplace add marciocar/kg-ssot, then /plugin install kg-ssot@kg-ssot.

How it works

flowchart LR

subgraph product["Product (one tag kg-ssot-vX.Y.Z)"] C["Contract JSON Schema MUST + SHOULD

• integrity rules"] S["Conformance suite

512 cases as plain data"] R["Reference reader kg_validate.py"] S -- "every reader passes" --> R C --> R end subgraph adopter["Adopter repository"] V["vendor/kg-ssot

• sha256 stamp"] G["kg_gate.py in CI

per-graph ratchet"] K["the team's .kg.yaml"] V --> G K --> G end product -- "kg_vendor.py update --tag" --> V G -- "nothing gets worse: a new graph passes, debt only shrinks" --> PR["PR approved"]

1. The contract is JSON Schema 2020-12 at two levels: MUST fails, SHOULD warns. The rules a schema cannot express (unique ids, existing edge ends, orphan nodes) are part of it.
2. The suite is the compatibility proof: each case is a real YAML file with the expected verdict and codes, and a reader passes only if it emits exactly the same codes.
3. The kit brings the contract to a repository by tag, with a stamp that fails local edits, and runs the per-graph ratchet in CI: what already failed becomes named debt, a new graph has to pass, and the debt only shrinks.

Features

| Two formats, one model | .kg.yaml to write and review in a diff, and .kg.json for runtime use (an app, a server), read by a JSON parser u