Skip to content

Adding nodes to a memory

PortalCLIMCPAPIBeginner~5 min

This guide walks through creating a node in a Hadron memory from the portal — the manual path that complements the MCP tools (hadron_create_node, hadron_create_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's 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.
Object type No Which collection the node belongs to — the structured-storage discriminator, orthogonal to Type. Defaults to None (ordinary node). On a memory with a schema it's a dropdown of the declared collections; on a schema-less memory it's a free-form tag.
Properties No The node's typed fields. Once you pick a declared Object type, this becomes a typed form — one input per declared field, validated before you can save. With no object type (or no schema) it's a free-form JSON editor.

Object type and properties

Picking an Object type turns Properties from a JSON box into a typed form driven by the collection's declared fields, and the node's properties are validated against that collection on save. Set it back to None (ordinary node) and the node leaves the collection.

If a node carries undeclared property keys — say it pre-dates the schema, or the collection was later tightened to strict — the editor shows them with a Remove property control, so you can prune the extras and bring the node into conformance without leaving the page.

On the node detail page, a node in a collection shows its object type and renders its properties as a typed table rather than raw JSON.

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: a Hadron URN is flat — a single colon throughout. hrn:mem:micromentor.org:mmdata has root micromentor.org and memory-slug mmdata; a node at loc review:render-urn inside it becomes hrn:node:micromentor.org:mmdata:review:render-urn. Position is what separates the parts: for a node URN the atom after the root is the memory slug, and everything after it is the loc. See URN composition.

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 isn't the only way in:

  • The hadron CLI: hadron node add (alias node create) creates a node from the terminal or a script — e.g. hadron node add -m <memory> --loc <loc> --name <name> --content -. See the hadron CLI reference.
  • MCP tools: hadron_create_node and hadron_create_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 createNode / updateNode: the underlying mutations the portal, CLI, and MCP tools all call (they replaced the old upsertNode, split into a create-only and an update-only mutation). This is the lowest-level surface — reach for the CLI, MCP, or portal for most work. See the GraphQL API reference.