Skip to content

Use Obsidian to view/edit memory

A Git-backed or exported Hadron memory is a folder of plain Markdown files with YAML frontmatter — nothing proprietary. You can open it in any editor, grep it, diff it, or keep reading it long after you stop using Hadron. Obsidian is a particularly good fit: a synced memory repo is already laid out as an Obsidian-style vault — one note per node, metadata in frontmatter — so it opens with no conversion.

This guide shows how to open a memory's repo as a vault, what the on-disk layout means, and how to make citation-addressed memories (whose files are bare numbers like 04.md) readable in the file explorer.

For how the repo gets to your disk in the first place — authoring it, syncing it into Hadron, and pushing it back out — see Sync a memory from a Git repo. This page picks up once you have the files locally.

Prerequisites

  • Obsidian installed (free for personal use).
  • A local working copy of the memory's repo. You get this either by:
    • cloning the repo you author the memory in, or
    • pulling the branch Hadron wrote with Push to Git — the export path (see Pushing back).

Either way you end up with a folder of Markdown files on disk. That folder is the vault.

No Hadron account is needed to read it — it's just files.

Step 1: Open the folder as a vault

  1. Launch Obsidian.
  2. Click Open folder as vault (from the vault switcher, Open another vault → Open folder as vault).
  3. Select the repo's root folder — the one that contains README.md.
  4. The first time, Obsidian asks you to Trust author and enable plugins. Trust it; the content is your own.

Every .md file is now a note. There is no import step — Obsidian reads the files in place, exactly as Hadron does.

Step 2: Read the layout

Hadron writes one self-contained Markdown file per node. A node's path is its loc — the colon-delimited citation address — with the colons turned into folders:

Node loc File on disk
architecture architecture.md
glossary:stage glossary/stage.md
billing:dunning:020:02 billing/dunning/020/02.md
billing:dunning:020:02:04 billing/dunning/020/02/04.md

A node that has children is written beside its child folder, not inside it — billing/dunning/020/02.md sits next to billing/dunning/020/02/. There is no README.md standing in for a parent node; the only README.md is at the repo root, where it holds the memory's manifest (its URN, name, and description).

What you see in the file explorer depends on how the memory is addressed:

  • A knowledge-base memory uses readable slugs, so the explorer reads naturally: architecture, glossary/stage, decisions/retention-policy.
  • A citation-addressed memory — a product-specs memory, for example — uses numeric locs, because the path is the citation. The files are bare numbers: 00.md, 02.md, 04.md. The human-readable title lives in the frontmatter name key, so in Obsidian's default explorer those notes show as "00 / 02 / 04" — unreadable. Step 3 fixes that.

Each file carries its metadata in frontmatter and its prose in the body:

---
name: Final notice email
id: 019d-7e7c-1f2a-…
description: The last dunning email before a subscription is suspended.
abstract: The final notice goes out three days after the last failed
  charge and links to the hosted payment-update page…
tags: [billing, dunning]
nodes:
  - id: 019d-8a01-44b3-…
    loc: billing:dunning:020:02
    rel: relates-to
---

# Final notice email

The final notice goes out three days after the last failed charge and
links to the hosted payment-update page…

The name key is the title. Edges live inline under nodes: — each entry identifies its target by id, carries the target's loc for readability, and names the relationship in rel.

Step 3: Make numeric nodes readable

For a citation-addressed memory, install the Front Matter Title community plugin. It displays a note's title from a frontmatter key of your choice — in the file explorer, tabs, search, and graph — without renaming the files. Point it at Hadron's name key and 04.md shows as "Final notice email" while staying 04.md on disk, which it must because the path encodes the citation.

  1. Open Settings (the gear, bottom-left) → Community plugins.
  2. If this is a fresh vault, click Turn on community plugins first.
  3. Click Browse, search for Front Matter Title, then Install and Enable.
  4. Open the plugin's options (Community plugins → Front Matter Title → the gear).
  5. Set the Template field — the frontmatter key to read the title from — to {{name}}. It defaults to {{title}}; Hadron uses name.
  6. Enable the surfaces you want to retitle — at least File Explorer.

The explorer now reads as titles:

Default explorer            With Front Matter Title
────────────────            ───────────────────────
└── billing/dunning/020/    └── billing/dunning/020/
    ├── 02.md                   ├── Retry schedule
    ├── 02/                     ├── 02/
    │   └── 04.md               │   └── Final notice email
    └── 03.md                   └── Grace period

Folders keep their numeric names — the plugin retitles notes, not folders — but the leaf notes you actually open are now readable.

Reading nodes and edges

  • Obsidian's Properties view renders the frontmatter as a table: name, description, abstract, tags, and the rest.
  • Edges are the nodes: list. Obsidian shows them as a property but does not draw them in the graph view — they're frontmatter data, not [[wikilinks]], so the graph and backlinks panes stay empty. To follow an edge, read its loc and open that file. For a navigable graph, use the Hadron portal's node browser.

Editing in Obsidian and syncing back

You can edit notes in Obsidian like any Markdown. If the vault is your memory's Git repo, commit and push, then re-sync (the portal's Sync from Git button, or the h-sync-graph MCP tool) to pull the changes into Hadron. A few rules keep the round-trip clean:

  • Keep the name key. A node file with no name is skipped on sync.
  • Don't rename or move files in a citation-addressed memory. The path is the loc — the citation — so renaming 04.md changes the node's address. Rename through Hadron, not in the vault. (Renaming in a slug-addressed memory is also a loc change; the same caution applies, less catastrophically.)
  • Leave id alone. It is the node's stable identity across renames, and edges resolve by it.
  • Don't hand-maintain contentHash or abstractOriginHash. Hadron recomputes them; just don't invent values.
  • Sync is upsert-or-delete. Deleting a file deletes the node on the next sync, and a database node with no file is removed — see What sync does to existing nodes.

If you only ever read in Obsidian, none of this applies — you can't hurt a memory by looking at it.