Open format · v0.1 · Alpha
A plain-text file format for building knowledge graphs on the file system. Relationships are first-class citizens. No database. No graph engine. Just files.
# projects/search-revamp.kgl @Project Search Revamp status: in-progress deadline: 2025-08-01 #search #q3 #vector [owned-by] → people/bob.kgl#Bob Chen since: 2024-09-01 [depends-on|replaces] → services/legacy-search.kgl sunset-date: 2025-08-01 note: "vector index must be live before deprecation" [staffed-by] → people/alice.kgl#Alice Nguyen role: lead engineer since: 2024-11-01 ~> decisions/search-engine-choice.kgl # background reading
Get started
KGL ships as a zero-dependency Python library on PyPI and as a VS Code extension on the Marketplace. Both are free and open source.
PyPI · requires Python 3.10+
.kgl files to typed Python dataclasseskgl CLI — parse, lint, query, graphFull API reference in the Parser API docs.
Marketplace · requires kgl Python package
.kgl filesInstallation guide in the VS Code docs. The extension requires the kgl Python package to be installed in the active interpreter.
Motivation
Existing formats optimise for data (JSON, CSV) or documents (Markdown, XML). Neither treats how things connect as structural. KGL is built around the idea that relationships deserve as much structure as the nodes they link.
Hard links (→) and soft links (~>) signal traversal intent directly in the file. An AI reading a KGL file knows immediately what to follow and what is background context.
@Person, @Project, @Service. Types are semantic and machine-readable. A node can carry multiple types: @Person|Contractor.
Every edge has a label and optional typed properties. [depends-on|replaces] with a sunset-date is a relationship that carries its own data.
Folders are namespaces. Files are nodes. No database, no server. Query with grep. Traverse with any file-reading tool. Version with git.
Specification
@Type.A single .kgl file can contain multiple nodes. Each @Type declaration starts a new node. Group tightly related nodes (a person and their skills); keep loosely related nodes in separate files.
# people/alice.kgl @Person Alice Nguyen joined: 2021-03-15 #backend #python [mentors] → people/diana.kgl#Diana Park started: 2023-06 focus: "backend systems and code review" → projects/search-revamp.kgl ~> teams/platform.kgl @Person|Contractor Ravi Mehta joined: 2024-06-01 contract-end: 2025-03-31 [reports-to] → people/alice.kgl#Alice Nguyen note: "day-to-day lead, not official manager" → projects/search-revamp.kgl
Schema layer
Schema files define node types, required fields, and allowed relationships. Violation is a warning, not an error — files without required fields are valid KGL. Add schema validation when your graph matures.
Schema lookup for any .kgl file: local _schema.kgl first, then walk up to root. First definition of a type wins. Local schemas extend the root; they don't replace it.
@NodeType Person joined!: date role?: text github?: url @NodeType Contractor extends: Person contract-end!: date
| Marker | Meaning |
|---|---|
field!: | Required — linter warns if absent |
field?: | Optional — documented but not enforced |
extends: | Inherit all fields from named type |
@RelType staffed-by from: Project → Person role!: text since!: date @RelType depends-on from: Project|Service → Project|Service since?: date sunset-date?: date note?: text
The from: field constrains which node types may appear on each side. Both sides support type unions. Relationship properties use the same !/? markers as node fields.
@Person Charlie Watts # ⚠ missing required field 'joined' (root _schema.kgl · @NodeType Person) # ⚠ missing required field 'team' (people/_schema.kgl · @NodeType Person) [depends-on] → people/diana.kgl#Diana Park # ⚠ type mismatch: 'depends-on' expects Project|Service → Project|Service # source is @Person — relationship not allowed here [staffed-by] → projects/search-revamp.kgl # ⚠ missing required property 'role' on relationship 'staffed-by' # ⚠ missing required property 'since' on relationship 'staffed-by'
Documentation
All primitives, field types, link semantics, naming conventions, and a complete example.
_schema.kgl files, node type definitions, relationship rules, inheritance, and linter warnings.
parse, lint, query, graph, and schema commands with flags and output format options.
Syntax highlighting, linter squiggles, autocomplete, go-to-definition, and hover tooltips.
parse_file, parse_string, and the RawNode / RawLink / ParseResult data structures.
Three-stage pipeline: file loader, link resolver, and ResolvedGraph with edge ID hashing.
In-memory query engine, supported syntax phases, CLI usage, and architecture.
Traversal prompt templates, PromptTemplates Python API, and graph-aware query assistant.
Status
KGL v0.1 is alpha. The spec and core tooling are complete. The Python library is on PyPI and the VS Code extension is on the Marketplace.