Open format · v0.2 · Read + write, tested
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
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 (required) role: text github: url @NodeType Contractor extends: Person contract-end: date (required)
| Marker | Meaning |
|---|---|
field: type (required) | Required — linter warns if absent |
field: type | Optional — documented but not enforced |
extends: Type | Inherit all fields from named type |
@RelType staffed-by from: Project to: Person role: text (required) since: date (required) @RelType depends-on from: Project Service to: Project Service since: date sunset-date: date note: text
The from:/to: fields constrain which node types may appear on each side — list more than one, space-separated, to allow any of them. Relationship properties are just more field lines below from:/to:, same (required) syntax 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 0.2 has a tested Python implementation covering the full spec, both reading and writing. One thing is still ahead: enum constraints in schema.