Skip to content

Adding nodes to a memory

This guide walks through creating a node in a Hadron memory from the portal — the manual path that complements the MCP tools (h-add-node, h-add-parent-node) and the Git-sync flow.

Overview

A node is a single addressable item inside a memory. Every node has a loc (its address within the memory, written as colon-separated segments like review:render-urn), a name (display label), a type, and optional description, content, tags, and edges. The portal exposes two entry points for adding one:

  • "+ New node" in the memory's tab row — adds a top-level node, or any node whose parent loc you type by hand.
  • "+ Add child" on a node detail page — adds a node directly under the one you're viewing, with the parent loc pre-populated.

Both lead to the same form. The difference is just where the parent defaults from.

Prerequisites

  • Write access to the target memory. If the memory is class=personal, only its owner can add nodes; class=app memories require an AppMember row with write access.
  • A Hadron account (hadronmemory.com).

Step 1: Open the memory

Browse to Organizations → your org → Memories → the memory you want to add to. The header shows the memory's URN; the Memory tab opens the graph/node browser.

Step 2: Click "+ New node"

The button sits to the right of the Memory / Settings tab row. On click, you land on the new-node form at /app/orgs/<id>/memories/<gid>/nodes/new.

If you wanted to add the new node as a child of an existing node instead, open that node first and use "+ Add child" in its header. The form is the same, but the Loc field is pre-populated with <parent-loc>:<auto-slug> so the new node lands as a child.

Step 3: Fill the form

The form has five fields:

Field Required Notes
Name Yes The display label. Free-form text.
Loc (address) Yes The node's address within the memory. Auto-derives from the name as a slug; you can edit it freely. After your first manual edit, name changes don't overwrite your loc.
Type Yes info (default) or record. The advanced types system and reference appear after toggling Show advanced types — most users don't need them. The portal form is a deliberate subset of the broader nodeType set (e.g., abstract exists for agent-generated summaries — see Building an agent — but is not user-authorable).
Description No Short summary. Plain text.
Content No Free-form body. Markdown is rendered when displayed.

A live URN preview shows the canonical URN that will be created (hrn:node:<org>::<memory-slug>::<loc> — for example, hrn:node:micromentor.org::mmdata::review:render-urn). This is the same form that copies to your clipboard, pastes into GitHub issues, and round-trips through Hadron's tooling.

URN form note: hierarchy levels in a Hadron URN are separated by :: (double colon); identifiers within a single level use a single :. So hrn:memory:micromentor.org::mmdata has org micromentor.org and memory-slug mmdata; a node at loc review:render-urn inside it becomes hrn:node:micromentor.org::mmdata::review:render-urn. The loc segment itself keeps the single-colon separator for path depth within the memory.

Loc rules

Each colon-separated segment must contain only letters, digits, hyphens, and underscores. Segments separated by colons: review:render-urn is a node at depth 2; review is the parent; render-urn is the leaf. Path-style slashes get auto-converted to colons; punctuation outside the allowed set is stripped.

When the loc auto-slugifies

Typing Sort imports in the Name field auto-fills the Loc as sort-imports. Adding under a parent of review auto-fills as review:sort-imports. If a node already exists at that loc, the suffix -2, -3, ... is appended until a free slot is found — purely a UX convenience for the pre-fill; the server is the authoritative collision detector at submit time.

Step 4: Submit

Click Create node. On success, the form redirects to the new node's detail page where you can edit content, add edges, or attach assets.

Common errors and what they mean

The form surfaces typed errors with friendly copy:

  • "A node already exists at this loc." — you picked a loc that's already taken in this memory. Adjust the name or loc and retry. Soft-deleted nodes at the same loc are treated as not existing — submitting will resurrect them with your new content.
  • "Loc segments may only contain letters, digits, hyphens, and underscores." — your loc has whitespace, punctuation, or other disallowed characters. Edit it and resubmit.
  • "You don't have write access to this memory." — your account isn't an AppMember (or the memory's owner, for personal memories). Ask the owner to add you.

Other ways to add nodes

The portal form is one of three paths into a memory:

  • MCP tools: h-add-node and h-add-parent-node exposed by hadron-client. Use these from an AI agent that has Hadron MCP configured. The same authorization gate applies.
  • Git sync: point a memory at a GitHub repo. Nodes are YAML + Markdown files; commits push automatically. See Building an agent for the setup.
  • GraphQL upsertNode: the underlying mutation the portal and MCP tools both call. Direct programmatic use is internal-quality per Constitution Invariant 11 — no external stability promise yet.