Typed Graph

Why

Obsidian links say that two notes are related, not how. Typed Graph lets one line say how:

---
type: Person
---
knows:: [[Bob]] {since: 2020, label: "met at NeurIPS"}
works_at:: [[Acme]]
-distrusts:: [[Mallory]]

Then you can ask the vault questions in openCypher, inside any note:

```graph-query
MATCH (p:Person)-[c:contributes]->(proj:Project)
RETURN p.title AS person, proj.title AS project, c.hours AS hours
ORDER BY hours DESC
```

Features

• Typed, signed edges with properties. type:: [[Target]] {props} works like Graph Link Types, so your existing lines keep working. A - prefix makes an edge negative, and edges can have stable or pinned ids.
• Typed nodes and schema notes. Frontmatter type gives a note its labels. A note in Types/ declares a type's properties, allowed edges, template and look.
• openCypher queries. MATCH, OPTIONAL MATCH, WITH, aggregates, variable-length paths and path variables. Queries are read-only and errors are clear.
• Graph or table, live. Results render as a labeled, styled graph or a table, and refresh as you edit.
• Graph view. A full-pane explorer that follows the active note, expands neighbors and explains where each style comes from. Frontmatter subtitle: billing draws specs/billing/spec.md as spec — billing, so notes that share a file name stay apart. It is a separate view. Obsidian's core Graph view is left unchanged, but you can color types there yourself with groups such as [type:Person] (see the docs).
• AsciiDoc notes. .adoc files are typed notes too: properties in a leading //// block or :tg-*: attributes, edges in // @tg: cites:: [[Source]] comments, so Asciidoctor renders the file exactly as before. See the docs.
• Edge embeds. {{edge: Alice -knows-> Bob . since}} shows an edge's property inside your prose.
• Optional sidecar. A LadybugDB mirror for full Cypher, local vector search (Ollama), GraphRAG with citations, and an MCP server for agents.

The screenshots come from the live demo, which runs the plugin's own query engine, schema styling and renderer in your browser.

Install

• Community plugins (recommended): open Typed Graph in Obsidian, or go to Settings → Community plugins → Browse, search for Typed Graph, then install and enable it. Directory page: community.obsidian.md/plugins/typed-graph.
• BRAT, for beta builds: install Obsidian42 - BRAT, run Add a beta plugin, and enter Volland/typedgraph.
• Manually: download main.js, manifest.json and styles.css from the latest release into <vault>/.obsidian/plugins/typed-graph/, reload Obsidian, and enable the plugin.

The plugin works on desktop and mobile, and it never modifies your notes.

Quick start

1. Add type: Person to a note's frontmatter.
2. Write an edge line such as knows:: [[Bob]] {since: 2020}.
3. Add a graph-query block with MATCH (a:Person)-[r:knows]->(b) RETURN a, r, b.
4. Run Typed Graph: Open graph view to explore.

Try the demo vault: download typed-graph-demo-vault.zip, unzip it and open the folder as a vault. The plugin is preinstalled. Open Start Here for a tour and a hands-on Cypher manual. From a clone, npm run example:install builds the plugin into example/ instead.

The full guide covers edge syntax, schema notes, styling precedence, the Cypher subset, embeds and settings: typedgraph.org/docs.html.

CLI: tg

@typedgraph/cli is a standalone command line, a drop-in replacement for lat.md that also links code into the typed graph. It reads the same lat.md/ folder and gives the same check verdicts (a test compares it with lat check on real projects).

npx @typedgraph/cli init            # set up: pick agents, parts and docs folder in a terminal, then it writes
npx @typedgraph/cli init --dry-run  # only print the diff of what it would change
tg check                            # links, code refs, annotations, index files, section structure
tg search "how are edges signed"    # lexical by default; hybrid with TG_EMBED_PROVIDER or a key
tg section "edge-syntax#Sign"
tg cypher "MATCH (s:Section)-[:references]->(t:Section) RETURN s.title, t.title LIMIT 5"
tg export ./out --vault ~/vault     # vault notes to a lat.md folder (lossy, with a report)
tg import ../project/lat.md         # adopt a lat.md folder (--mount to symlink)

Code points at docs with // @lat: [[section]] (a plain link) or a typed edge, // @tg: implements:: [[auth#Login]] {since: 2}. tg mcp serves the same commands to agents over MCP. In Obsidian, Code in the graph (settings or the Graph view dropdown) shows annotated symbols as nodes without writing anything to the vault. Design: lat.md/cli.md.

For agents: the sidecar

packages/sidecar is a headless service over a read-only copy of your vault. It needs no Obsidian. It offers REST, an MCP server, a LadybugDB mirror, local vector search and GraphRAG.

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

The MCP tools are cypher_query, vector_search and graphrag_retrieve, all read-only. For REST endpoints, Docker and environment variables, see the sidecar docs.

Development

packages/core     edge parser, graph model, schemas, styles, openCypher engine, embeddings (no Obsidian APIs)
packages/plugin   the Obsidian plugin
packages/sidecar  headless REST + MCP service, LadybugDB mirror, vector index, conformance suite
site/             the website and live demo (GitHub Pages)
lat.md/           architecture and test specs (lat.md)
openspec/         specs and archived changes (OpenSpec)

npm install
npm run verify                      # typecheck + tests + lat check
OBSIGRAPH_OUT="<vault>/.obsidian/plugins/typed-graph" npm run build   # build the plugin into a vault
npm run site:build && npx serve site                                 # preview the website

Releasing

1. Run npm run version:bump -- 0.5.0. This updates manifest.json, versions.json and every package version.
2. Commit, then run git tag 0.5.0 && git push origin 0.5.0. The tag has no v prefix.
3. The Release plugin workflow typechecks, tests, builds, and attaches main.js, manifest.json and styles.css to the GitHub release.

Submitting to the Obsidian community directory

Obsidian takes submissions through its web directory, not through pull requests. community-plugins.json in obsidianmd/obsidian-releases is only a mirror of it.

1. Sign in at community.obsidian.md with your Obsidian account, and link your GitHub account to prove you own the repo.
2. Add the plugin from the Volland/typedgraph repository. The directory reads README.md, LICENSE and the root manifest.json, and installs from the GitHub release tagged with the manifest version.
3. An automated review runs. To fix anything it reports, update the repo and publish a new release with a higher version (npm run version:bump, then push the tag).

License

MIT © Volodymyr Pavlyshyn. Not affiliated with Obsidian or LadybugDB.