How-to

Build a knowledge graph

Create typed temporal links, traverse them, and see what links into a page.

GigaBrain’s links table holds typed, temporal cross-references between pages. This recipe shows how to create them at the CLI, traverse them, and use temporal validity to capture relationships that change over time.

Create a typed link

gbrain link people/alice companies/river-ai \
  --relationship founder_of \
  --valid-from 2024-01-15 \
  --db ~/brain.db

Both ends must already exist as pages. --relationship is free-form; conventions like founder_of, mentions, supersedes, manages are common. --valid-from and --valid-until are optional ISO-8601 dates.

If you omit --relationship, it defaults to related.

Wiki-style links inside the body

[[other-page]] syntax in a page body is parsed at write/import time into links rows with source_kind = 'wiki_link'. Programmatic links (the gbrain link CLI or brain_link MCP tool) carry source_kind = 'programmatic'. Both are returned by links and backlinks.

Close an interval

Alice leaves RiverAI. Don’t delete the link — close it:

gbrain links people/alice --db ~/brain.db   # find the link_id
gbrain link-close <LINK_ID> --valid-until 2026-04-01 --db ~/brain.db

The link still exists in the database; subsequent traversal with --temporal current excludes it, but --temporal all keeps it.

List outbound and inbound links

gbrain links people/alice --db ~/brain.db                    # outbound
gbrain backlinks companies/river-ai --db ~/brain.db          # inbound
gbrain links people/alice --temporal all --db ~/brain.db     # include closed intervals

Traverse the neighbourhood

gbrain graph people/alice --depth 2 --db ~/brain.db

Returns a JSON object with nodes and edges for an N-hop BFS from the seed slug. --temporal current (default) honors valid_from/valid_until; --temporal all traverses everything.

gbrain graph people/alice --depth 2 --temporal all --db ~/brain.db

Remove a link

gbrain unlink people/alice companies/river-ai --db ~/brain.db
gbrain unlink people/alice companies/river-ai --relationship founder_of --db ~/brain.db

Without --relationship, every edge between the two pages is removed. With it, only that specific edge.

We recommend link-close over unlink when the relationship was real but ended — the historical record is what makes graph traversal useful over time.

Useful relationships to standardize

There’s no enforced taxonomy, but these are common:

Relationship	Meaning
`founder_of`, `employed_by`, `joined`, `left`	Person ↔ Company
`mentions`, `cites`, `references`	Page ↔ Page (lightweight)
`supersedes`, `superseded_by`	Decision ↔ Decision
`manages`, `reports_to`	Person ↔ Person
`partnered_with`, `acquired`, `acquired_by`	Company ↔ Company
`commits_to`, `committed_by`	Person ↔ Commitment

Pick a small vocabulary and stick to it; the temporal fields encode the when, the relationship encodes the what.

See it via MCP

For agents, the same surface lives at:

brain_link — create
brain_link_close — close interval
brain_backlinks — inbound
brain_graph — traverse

See the MCP tool reference for parameters.

Tips

Temporal links over deletion. Closed intervals are queryable history; deleted links are gone.
Use valid_from/valid_until aggressively. They cost nothing and unlock “who was at RiverAI in April 2026?” queries.
Run gbrain validate --links. Detects dangling endpoints (e.g. when a page was renamed and a link wasn’t updated).