Install

Typed Graph works on desktop and mobile. Pick one:

VS Code extension

Without Obsidian, the Typed Graph extension shows typed backlinks and the graph for the markdown and @lat:/@tg:-annotated code in a workspace, and offers to run tg init. It is published on the VS Code Marketplace and on Open VSX as pavlyshyn.typegraph-vscode.

Settings: typegraph.roots (folders that form the graph, default ["."]), typegraph.ignore (folder names to skip, default ["node_modules"]) and typegraph.fullGraphLimit (most nodes the whole-project graph draws, default 2000).

Commands: TypeGraph: Open Graph shows the active file's neighborhood. TypeGraph: Open Full Graph, or the Whole project toggle in the panel, draws every node and edge, keeping the most connected ones past the limit. TypeGraph: Export Graph as HTML saves a self-contained page that works offline, and TypeGraph: Export Graph as PDF saves a one-page vector PDF with searchable labels and the node and edge counts in its caption. All four are buttons in the Backlinks view title bar, and the two exports are in the panel toolbar. Exports write only the file you pick.

New to typed graphs? Download the demo vault, unzip it and open the folder as a vault (Open folder as vault). The plugin comes preinstalled; turn on community plugins when Obsidian asks, then open Start Here. It uses every feature and includes a hands-on Cypher manual with live examples.

Quick start

  1. Give a note a type: add type: Person to its frontmatter.
  2. Write an edge line: knows:: [[Bob]] {since: 2020}.
  3. Add a query block anywhere:
    ```graph-query
    MATCH (a:Person)-[r:knows]->(b)
    RETURN a, r, b
    ```
  4. Open the explorer with Typed Graph: Open graph view or the ribbon icon.

Edges

An edge is one line in a note; the note is the source.

knows:: [[Bob]]
knows:: [[Carol]] {since: 2018, label: "met at conf"}
-distrusts:: [[Eve]]
+trusts:: [[Bob]]
- works_at:: [[Acme]], [[Initech]] {role: engineer}
PartMeaning
type::Edge type. Graph Link Types lines work unchanged.
- / + prefixSign: −1 or +1 (default +1). weight is an ordinary property.
{…}Properties: numbers, booleans, quoted or bare strings, lists.
{id: "…"}Pins the edge id; otherwise it is source#type#target#n.
headingThe nearest heading above is recorded with the edge.

Lines in code blocks and frontmatter are ignored. Malformed property blocks keep the edge and appear in Show diagnostics. Links to missing notes become faded stub nodes.

Typed nodes

Every note is a node. Frontmatter type becomes its labels; a list gives several:

---
type: [Person, Employee]
age: 40
---

Frontmatter fields, title and path are node properties.

Schema notes

Notes directly in Types/ (configurable) declare types. schema: describes the type named by the note's title, and its body is that type's template:

---
schema:
  properties:
    status: {kind: text, default: active, values: [active, alumni]}
    born: {kind: date, required: true}
    aliases: list
  edges: {knows: Person, worksAt: Company}
  visualization:
    color: "#7c5cff"
    shape: ellipse
    icon: user
    label: name
    edges:
      knows: {color: orange, line: dotted}
---
## Notes

One note can also describe a whole subsystem: several types under schemas: and edge types with their own properties under edgeTypes:.

---
schemas:
  Person: {properties: {email: {required: true}}, edges: {worksAt: Company}}
  Company: {uri: schema:Organization, properties: {founded: date}}
edgeTypes:
  worksAt:
    from: Person
    to: Company
    properties: {since: date, role: {values: [engineer, manager]}}
    visualization: {color: green}
---

The format is an open specification, Typed Graph Schema (TGS) 0.2, with a JSON Schema and conformance examples; 0.1 stays published, and every 0.1 schema note is valid 0.2.

AsciiDoc notes

An .adoc file is a note like a Markdown one. Everything the graph reads hides in a comment or a header attribute, so Asciidoctor renders the file exactly as it would without it.

////
type: Chapter
status: draft
////
= Metagraphs
:tg-pages: 12

// @tg: cites:: [[Pavlyshyn 2024]] {page: 12}
[#definition]
== Definition

A metagraph generalizes a hypergraph.
FormMeaning
leading //// blockYAML properties, as frontmatter; type gives labels. A block that is not YAML is reported.
:tg-key: valueA property with a one-line YAML value. The leading block wins when both set a key.
// @tg: type:: [[X]]A typed edge. A //// block starting with @tg holds one edge per line. Edge syntax outside a comment is not an edge.
anchoringA comment above a heading belongs to that section; elsewhere to the section it sits in. The edge records it as section.
xref:, <<…>>Plain links when link edges are on.
include::An ordered includes edge with leveloffset, tags and lines; a source file include ends at its code node.

A link without an extension matches .md and .adoc notes; when both exist it is reported as ambiguous. Obsidian, VS Code and the sidecar index .adoc files by default (a setting turns it off); tg reads the files matched by notes in .tg/config.json, for example { "notes": ["book/**/*.adoc"] }, which tg init proposes. The OKF export skips AsciiDoc notes. Details are in TGS 0.3.

Edge property embeds

We met in {{edge: Alice -knows-> Bob . since}}.
{{edge: met-2020 . since}}
{{edge: met-2020}}

Find an edge by endpoints and type or by pinned id; . property shows one value, otherwise a small table. Put a sign before the type to require it: --distrusts-> (negative), -+knows-> (positive). Embeds referencing unpinned edges get a diagnostic suggesting an id.

Query blocks

A graph-query block is an optional header, a blank line, then the query.

```graph-query
view: table
columns: who, since
backend: builtin
node.Person: color=#e5484d, shape=hexagon
edge.knows: line=dashed

MATCH (a:Person)-[r:knows]->(b)
RETURN a.title AS who, r.since AS since
```
OptionValues
viewauto (graph when the result has nodes, relationships or paths), table, graph
columnsTable columns to show, in order
heightGraph height in pixels (100–4000)
backendbuiltin or ladybug (needs the sidecar)
codeshow (default) or hide source-code nodes in graph results
forcesInitial layout forces, e.g. center=0.3, repel=12, link=0.6, distance=200, edgeRepel=0.4, labelRepel=0.8, pinOnDrag=true
displaye.g. arrows=true, edgeLabels=true, fade=0.12, nodeSize=0.75, linkSize=0.5, hide=requirement|feature
pinself (default), none, or note names; the first goes to the centre
controlsshow (default), open or hide the graph controls button
node.<Type> / edge.<type>Style overrides for this block

Results refresh live. Graphs larger than the element limit fall back to a table. The gear button's Copy as block options writes the current forces, display and pin lines for you.

Variables and metadata

A block can refer to the note it sits in with {{…}} variables. Each one is replaced by a Cypher literal before the query is parsed, so this block always shows its own note's neighbourhood, wherever you paste it:

```graph-query
MATCH (me {path: {{path}}})-[r]-(x)
WHERE x.status = {{fm.status}}
RETURN me, r, x
```
VariableValue for Projects/Atlas/Plan.md
{{path}}"Projects/Atlas/Plan.md"
{{name}}"Plan.md"
{{title}}"Plan", the file name without extension (frontmatter title is {{fm.title}})
{{folder}}"Projects/Atlas"; "" at the vault root
{{extension}}"md"
{{fm.<key>}}Any frontmatter value (also {{frontmatter.<key>}}; dots walk into maps). Strings are quoted, numbers and booleans plain, lists stay lists.

Unknown names and values that are not literals become null. Nothing is evaluated: write {{fm.budget}} * 2, not {{fm.budget * 2}}. Variables work on both backends.

Every query can also use metadata that Typed Graph adds on its own, with no schema: n.path, n.title, n.stub and every frontmatter key on nodes; type(r), r.sign, r.id and every {property} on edges. The Graph view also binds the parameter $activeFile. The query cheat sheet lists all of it on one page, including the Section, Requirement and code nodes of tg cypher.

openCypher subset

Queries are read-only. CREATE, SET, DELETE, MERGE and REMOVE are rejected. UNWIND, UNION, CALL, CASE and =~ are not in the built-in subset; use backend: ladybug for those.

Styling

Every attribute resolves on its own; the most specific source wins:

  1. Block header (node.Person: color=red)
  2. Schema note visualization
  3. Settings → Type styles / Edge styles
  4. Defaults: a stable color per type; negative edges dashed red with a tee arrow

Node attributes: color, shape (ellipse, rectangle, round-rectangle, diamond, hexagon, triangle, star), icon (Lucide name), label (property shown instead of the title). Edge attributes: color, line (solid, dashed, dotted).

Graph view

Node names

A node is named after its note's file name. Frontmatter title: Billing spec replaces the file name, in the graph and in queries. Frontmatter subtitle: billing keeps the title and adds to it in the graph only, so specs/billing/spec.md shows as spec — billing instead of one of many spec nodes. OpenSpec accepts frontmatter in spec.md and design.md. A type's visualization.label property still wins over both.

This is a separate view. Obsidian's core Graph view is left untouched, because it has no plugin API and patching it breaks on Obsidian updates. It still draws one plain line per linked pair of notes, with no edge types, signs or properties.

Color types in the core Graph view

You can still color nodes by type in the core Graph view, without any plugin code. Open the core Graph view, expand Groups, choose New group, and enter a property search such as [type:Person], then pick a color. Add one group per type. The first matching group wins, so order groups from most to least specific.

The sidecar

An optional headless Node service over a read-only copy of your vault. It powers the Ladybug backend, vector search, GraphRAG and MCP.

npm install && npm run build:sidecar
OBSIGRAPH_VAULT=/path/to/vault OBSIGRAPH_DATA=/path/to/data OBSIGRAPH_TOKEN=change-me \
  node packages/sidecar/dist/server.mjs

Docker: packages/sidecar/Dockerfile and compose.example.yaml mount the vault :ro, run as non-root and publish on host loopback only.

EndpointPurpose
GET /healthLiveness (no token)
GET /statusGraph, mirror and vector state
POST /query{query, params, backend} → {columns, rows}
POST /searchVector search, optional then Cypher with $hits
POST /retrieveGraphRAG retrieve
POST /vectors/rebuildRe-embed after a model change
POST /mcpMCP over streamable HTTP
VariableDefault
OBSIGRAPH_VAULT, OBSIGRAPH_DATA/vault, /data
OBSIGRAPH_TOKEN / OBSIGRAPH_TOKEN_FILErequired (except --stdio)
OBSIGRAPH_HOST, OBSIGRAPH_PORT127.0.0.1, 8765
OBSIGRAPH_POLL_MS0 (set e.g. 5000 on macOS bind mounts)
OBSIGRAPH_LADYBUG, OBSIGRAPH_VECTORSon; set 0 to disable
OBSIGRAPH_EMBED_PROVIDER, _URL, _MODEL, _KEY/_KEY_FILEollama, http://localhost:11434, nomic-embed-text

Ladybug backend

The sidecar mirrors the graph one-way into LadybugDB. Set the sidecar URL and token in plugin settings, then use backend: ladybug in a block. Queries the built-in parser reads are translated so they return the same results. A 52-query conformance suite keeps the two engines in agreement.

Other read Cypher (UNWIND, CASE, UNION, =~) runs on LadybugDB untranslated, against the mirror layout. The result carries a notice saying so. In that layout:

```graph-query
backend: ladybug
view: table

MATCH (p:Node)-[c:contributes]->(proj:Node)
WHERE list_contains(p.labels, "Person")
RETURN p.title AS person, proj.title AS project,
       CASE WHEN c.p_hours_n >= 100 THEN "core" ELSE "helper" END AS involvement
```

Vector search

Notes are chunked by heading with title, type and frontmatter as context; each edge becomes a sentence like Alice (Person) knows Bob (Person) - met at NeurIPS. Embeddings come from local Ollama by default.

POST /search
{"query": "machine learning", "target": "nodes", "k": 5, "types": ["Person"],
 "then": "MATCH (p)-[:works_at]->(c) WHERE id(p) IN $hits RETURN c.title"}

GraphRAG

POST /retrieve
{"question": "Who works with Alice on search?", "k": 5, "depth": 1}

Returns the best chunks of the vector hits and of their graph neighbors (hits first, then by distance), each with path, heading, score and role, plus the connecting edges. Hub expansion is capped and flagged.

MCP for agents

claude mcp add typed-graph \
  -e OBSIGRAPH_VAULT=/path/to/vault -e OBSIGRAPH_DATA=/path/to/data \
  -- node /path/to/packages/sidecar/dist/server.mjs --stdio

Tools: cypher_query, vector_search, graphrag_retrieve — all read-only. Over HTTP use POST /mcp with the bearer token.

Security

CLI: tg

tg works on a lat.md/ folder, the same format as lat.md. Sections can carry typed edges as well as plain links: a line - motivated_by:: [[constraints#GDPR]] {since: 2} after a section's leading paragraph is a named edge with properties in tg cypher, and an ordinary wiki link for lat.md. Install with npm install -g @typedgraph/cli. It finds the project by walking up to the nearest lat.md/ or .tg/ folder; --dir overrides. Exit codes: 0 ok, 1 findings, 2 usage or internal error. --json prints machine-readable output on read commands.

tg check [md|code-refs|index|sections]Validate links (including source files and symbols), @lat: and @tg: references, require-code-mention coverage, directory index files and the 250-character leading-paragraph rule.
tg locate <query>Find sections by id, short id or fuzzy name.
tg section <query>Show a section with its links, what references it and the code that does.
tg refs [--scope md|code|md+code] <query>Sections and code that reference a section.
tg expand <text>Replace [[refs]] in text with full ids and locations.
tg search [--limit n] [--lexical] <query>Lexical ranking by default. With TG_EMBED_PROVIDER=ollama|openai or a key (TG_EMBED_KEY, or LAT_LLM_KEY) it fuses lexical and vector ranks. TG_EMBED_URL and TG_EMBED_MODEL pick the endpoint and model. Vectors are cached in .tg/; tg reindex rebuilds them.
tg cypher [--code off|annotated|all] <query>Read-only openCypher over the section graph: Section nodes (section, title, file, depth, summary), contains and references edges, Requirement and Scenario nodes from spec frameworks, and with --code CodeFile and CodeSymbol nodes; every property is listed in the query cheat sheet. Pattern predicates such as WHERE NOT ()-[:x]->(s) are not supported; use OPTIONAL MATCH with a count.
tg edges [--type t] [--to s] [--file f]List annotation edges from code to sections.
tg gen <target>Print agents.md, claude.md, cursor-rules.md, skill.md or graph-skill.md.
tg init, tg hook, tg mcpSee Agents and hooks.
tg export, tg import, tg schemaSee Export and import.
tg migrate [dir] [--dry-run] [--json] [--infer] [--keep-lat] [--no-setup] [--no-since] [--force]Migrate a lat.md project to an ontology-aware tg project: swap the agent setup (as tg init --migrate), type docs files by their path or SHALL content, turn each plain link whose sentence names a relation into a typed edge line (candidates come from the ontology in Types/; --infer also applies a single candidate without a cue word), add the properties the edge type declares (since from git, strength from MUST or should, level from test paths), and upgrade @lat: comments to @tg: implements:: or verifies::. Writes by default, refuses files with uncommitted changes unless --force, and lists every link left plain with its sentence and candidates; the tg-migrate skill resolves those.
tg ontology [check] [--schema-folder Types] [--json]List the project's ontology: every type in Types/ with its properties and allowed edges, every edge type with its endpoints and properties. check reports typed edges in docs and code whose name is not declared (with a did-you-mean), whose source or target type is not allowed, or whose properties are undeclared or out of range, and exits 1 on findings. Also the MCP tool tg_ontology.
tg validate [--vault dir] [--schema-folder Types] [--only codes] [--ignore codes] [--schema-only] [--frontmatter-edges] [--strict] [--format text|json|sarif]Validate a vault against its schema notes without Obsidian, with the same findings as the plugin's diagnostics list: edge syntax, schema declarations, required properties and edges, edge endpoints, style values and edge embeds. Every finding has a stable code (the TGS diagnostic names, edge-syntax, style, embed). Declaration problems are errors and everything else warnings; exit 1 on errors, or on any finding with --strict. --schema-only checks just the schema notes, --frontmatter-edges reads links in frontmatter properties as edges, and --format sarif writes SARIF 2.1.0 for GitHub code scanning. See CI.
tg okf check [dir]Check any folder against Open Knowledge Format v0.2 conformance: concepts need parseable frontmatter with a string type, index files no frontmatter (except okf_version at the root), log date headings YYYY-MM-DD. Broken links, wikilinks and missing descriptions are warnings. Exit 1 only on errors.

Validating in CI

A GitHub Actions job that fails on schema errors and shows every finding as a code scanning annotation:

- run: npx -y @typedgraph/cli validate --format sarif > tg.sarif || true
- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: tg.sarif }
- run: npx -y @typedgraph/cli validate --strict   # or drop --strict to fail on errors only

For a pre-commit hook, tg validate --schema-only checks only the schema notes and is fast on any vault size.

Annotations in code

Two comment forms link code to docs, in //, # and block comments:

// @lat: [[auth#Token expiry]]                       a plain reference
// @tg: implements:: [[auth#Token expiry]] {since: 2}   a typed edge
// @tg: -contradicts:: [[design#Stateless sessions]]    a negative edge
// @tg: implements:: [[a#X]], tests:: [[b#Y]]           several edges
// @tg: [[a#X]]                                         same as @lat:

@lat: follows lat.md's exact pattern (a // or # comment and one link). @tg: uses the same type:: [[Target]] {props} grammar as notes, so signs, properties and several edges work as they do there. The edge starts at the declaration that follows the comment within three lines (a class member is Class#member); otherwise it belongs to the file and tg check warns. A schema note's edges list gives advisory checks on edge types.

Source links in docs, [[src/server.ts#App#listen]], are checked against the file. Supported: TypeScript and JavaScript (.ts .tsx .js .jsx .mts .cts .mjs .cjs), Python, Go, Rust and C (.c .h). Symbols are found with regex finders, so a file whose strings or braces do not balance, or a class written on one line, is reported as "cannot tell" and never as a missing symbol.

Code in the graph

Source files and symbols can appear as derived CodeFile and CodeSymbol nodes, keyed by path and path#Class#method, with contains edges and the annotation edges. They are built in memory and never written to disk or to your vault.

Agents and hooks

Export and import

In Obsidian, notes under a lat.md/ folder get working [[file#Heading#Sub]] links and show link and section problems in the diagnostics list. Files are not modified.

Settings

Maximum graph elementsAbove this, graphs show as tables.
Maximum path depthCap for unbounded * patterns (default 10).
Default query backend, Sidecar URL, Sidecar tokenFor backend: ladybug.
Schema folder, Show diagnosticsType schemas and the issue counter.
Type styles, Edge stylesJSON style defaults.
Refresh delayDebounce before blocks re-run.
Code in the graph, Code folderShow source symbols as nodes (off, annotated, all) and which vault folder to scan.
AsciiDoc notesIndex .adoc files as notes (on by default).

FAQ

Does it change my notes?

No. The plugin and the sidecar only read notes. Only New typed note and its child, sibling and top-level variants, Create schema note and Import SHACL shapes write files, on request; the import changes only the schema keys of notes in the schema folder.

Do I need Graph Link Types or Dataview?

No. Typed Graph reads the same type:: [[Target]] lines on its own.

Does my vault leave my machine?

Not by default. Embeddings use local Ollama; a hosted endpoint is only used if you configure one.