Language · Reference

Syntax Reference.

Complete reference for all KGL syntax primitives. A .kgl file is plain text — no required tooling to read or write it.

Node declaration

syntax
@Type Name

Declares a node. Everything below it — fields, tags, links, body — belongs to this node until the next @Type declaration or end of file.

Type is capitalised and semantic: @Person, @Project, @Service, @Decision, @Place.

Name is the node's identifier within the file. Use it in fragment links from other files: → people/alice.kgl#Alice Nguyen.

Multi-type nodes

syntax
@Type|Type Name

Both types apply simultaneously. Order matters: the first type is primary. A query for either type will match the node.

examples
@Person|Contractor Ravi Mehta
@Place|Landmark Uluru

Fields

syntax
key: value
key: "value with spaces or punctuation"

Any key, freeform value. No required fields unless a schema defines them. Field names are lowercase, hyphen-separated by convention.

Field types (for schema use)

Types are hints for tooling and schema validation — not enforced at parse time.

TypeDescription
textAny string
dateISO 8601 date: 2024-11-01
urlA URL
booltrue or false
numberInteger or decimal

Tags

syntax
#tag #another-tag

Tags are for clustering and discovery. Multiple tags per node, space-separated. A linter or query tool can filter nodes by tag.

example
#backend #python #team-platform

Links connect nodes across files. They are the core feature of KGL.

syntax
→ path/to/file.kgl
→ path/to/file.kgl#Node Name

A strong relationship. Signals to a reader (human or AI): follow this link to fully understand the current node.

The #Node Name fragment pins the link to a specific node inside a multi-node file.

syntax
~> path/to/file.kgl

A weak relationship. Background context — relevant, but not required reading to understand the current node.

Named relationship

syntax
[relationship-name] → path/to/file.kgl

A hard link with a typed edge. The label describes how the two nodes relate.

examples
[reports-to] → people/bob.kgl#Bob Chen
[depends-on] → services/legacy-api.kgl
[mentors]    → people/diana.kgl#Diana Park

Multi-type relationship

syntax
[rel|rel] → path/to/file.kgl

Both labels apply simultaneously — not "either/or". Use when a relationship genuinely carries two meanings.

example
[depends-on|replaces] → services/legacy-search.kgl

Relationship properties

example
[employs] → people/alice.kgl#Alice Nguyen
    role: lead engineer
    since: 2024-11-01
    note: "day-to-day lead, not line manager"

Indented lines immediately following any link are properties of that relationship. They are scoped to the relationship, not the node. The scope ends at the next non-indented line.

This applies to all link types — hard, soft, and named.

Free text body

syntax
---
Prose goes here.

The --- separator marks the start of a free text body. Everything after it is plain prose — not parsed as fields or links. Use it for context, nuance, and notes that structured fields can't capture.

The body applies to the most recent @Type node.

Comments

syntax
# This is a comment

Lines starting with # that are not tags are comments. By convention, place a comment at the top of every file identifying its path and purpose.

convention
# people/alice.kgl
# AI note: follow → links for full context on each relationship.

Multiple nodes in one file

A single .kgl file can contain multiple nodes. Each @Type declaration starts a new node.

people/alice.kgl
# people/alice.kgl

@Person Alice Nguyen
role: Senior Engineer
→ projects/search-revamp.kgl


@Person|Contractor Ravi Mehta
role: Backend Engineer
contract-end: 2025-03-31
→ projects/search-revamp.kgl

Group tightly related nodes in one file (a person and their skills, a team and its members). Keep loosely related nodes in separate files.

Conventions

ConventionRecommendation
File nameslowercase-hyphenated.kgl
Folder nameslowercase/ — used as namespaces
Node namesTitle Case
Field keyslowercase-hyphenated
Relationship labelslowercase-hyphenated
Tags#lowercase
Comment at topAlways include file path and a brief note

Complete example

projects/search-revamp.kgl
# projects/search-revamp.kgl
# AI note: follow → links for full context. ~> links are background reading.

@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
~> planning/q3-roadmap.kgl#Search

---
Replacing legacy full-text search with a vector-based approach.
Phase 1: indexing pipeline. Phase 2: query rewrite. Phase 3: UI rollout.

Quick reference

@Type Name
Node declaration. Capitalised type, freeform name. Everything below belongs to this node until the next @Type.
@Type|Type Name
Multi-type node. Both types apply. First type is primary.
→ file.kgl
Hard link. Strong relationship. Follow to fully understand the current node.
→ file.kgl#Name
Fragment link. Hard link to a specific named node inside a multi-node file.
~> file.kgl
Soft link. Weak relationship. Background context — fetch only when depth is needed.
[rel] → file.kgl
Named relationship. Hard link with a typed edge. Indented lines below are relationship properties.
[rel|rel] → file.kgl
Multi-type relationship. Both labels apply simultaneously.
key: value
Relationship property. Indented under a link. Scoped to that relationship only.
key: value
Node field. Any key, freeform value.
#tag
Tag. For clustering and discovery.
---
Body separator. Everything after is free prose.
Next Schema →