Skip to content

Adding nodes to a memory

PortalCLIMCPAPIBeginner~5 min

Add a note, a fact or a document to one of your memories, in the portal, so you and the agents that use the memory can find it later. Each entry is a node: a single item with a name, an address in the memory, and whatever content you give it.

If you're working in an AI tool connected to Hadron, you can also ask it to add the note for you, with the same permissions. One difference: the portal form refuses a loc where a node already exists (it only reuses the loc of a deleted node, bringing that node back with your content), while an agent's tool creates or updates — so if you tell an agent to add a node at an address that's in use, it may change the existing one. The portal is the way to do it by hand, and it's what this page walks through.

Before you start

  • A Hadron account (hadronmemory.com).
  • Write access to the memory. For a personal memory that means you own it or it has been shared with you as a writer; for an App's memory, you need write access as a member of the App.

Step 1: Open the memory

Open My memories in the sidebar, or your organization's Memories, and pick the memory you want to add to.

Step 2: Choose Add node

Open the ⋯ menu (Memory actions) to the right of the memory's tabs and choose Add node. The new-node form opens.

To add the node under an existing one instead, open that node, open its ⋯ menu and choose Add child. It's the same form, with the Loc pre-filled as <parent-loc>:<name-slug> so the new node lands beneath it.

A node's loc is its address within the memory, written as colon-separated segments like review:render-urn.

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.
Abstract No A paragraph-length summary. When the memory's vector index is built from abstracts, this is what semantic search matches, so write it as the questions someone would ask to find this node. Keyword search uses the name, loc, description and tags instead. See What makes a node findable.
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 with this loc already exists. Try a different name or 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. Ask the memory's owner to add you as a writer." — you don't own the memory, it hasn't been shared with you as a writer, and you aren't a member of its App with write access. Ask the owner.

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 on Hadron's MCP server. Use these from an AI agent that has Hadron connected. 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.