Skip to content

Comment on a node

PortalMCPAPIBeginner~5 min

When something in Hadron looks wrong or out of date, you can say so right next to it without changing it. Your comment shows up for everyone who reads that node, people and agents alike, while the node keeps its text, its revision and its approval. Someone who owns the content can then answer you, fix the node, and mark your feedback resolved.

There is nothing to install. If your agent is connected to Hadron, you comment by asking, or you can do it in the portal by opening the node's Discussion tab. You need write access to the node's memory.

Leave a comment

Tell your agent which node and what's wrong:

"In Hadron, leave a comment on the "Runbook: payment retries" node: the retry count is out of date — we retry 5 times now, not 3."

The agent finds the node, adds your comment, and tells you it's posted. It often quotes the passage you mean, too. The node itself isn't changed: it still says 3 until someone edits it.

You can only have one open thread per node. If you already have one there, the agent is told so and can reply in that thread instead.

See what feedback a node has

"Is there any feedback on the "Runbook: payment retries" node in Hadron?"

The agent lists each thread with who wrote it, when, whether it's open or resolved, and its replies. It also tells you whether the comment was written about the node's current revision or an older one. A deleted first comment that still has replies is listed as "deleted", with no text, above its replies (the listing may still call that thread open, but it doesn't count as one).

A thread shows its first 200 replies, oldest first, and says how many more there are. Those later replies can't be listed: paging a discussion pages its threads, not the replies inside one. If you know a later reply's URN, the agent can read that one reply.

You don't always have to ask. When an agent reads a node that has comments, it sees a one-line count of open and resolved threads and can mention it to you. It treats the comments as reader feedback, not as part of the node, and won't take a commenter's claim as fact without checking.

Search the feedback

An ordinary search returns content, not comments. To search what people have said about your content, ask for comments:

"Search the comments in our Hadron memories for anything about retries."

The agent searches comments only and tells you which node each one is about, who wrote it, and whether its thread is open. Ask for "content and comments" when you want both in one search.

Answer and resolve feedback

"Reply to the open comment on the "Runbook: payment retries" node in Hadron: "Agreed, I'll update the runbook." Then mark that thread resolved."

Anyone who can write to the memory can reply, and resolve or reopen a thread. It doesn't have to be the person who started it. Replying to a resolved thread is allowed and doesn't reopen it; ask to reopen it if you want it open again.

A thread whose first comment was deleted but still has replies (a stub, see below) is read-only: it takes no reply, no resolve and no reopen. Start a new thread to say more.

Resolving a thread doesn't fix the node. Ask for that edit separately, the way you'd edit any node.

Change or delete a comment

"Edit my comment on the "Runbook: payment retries" node in Hadron so it says we retry 6 times, not 5."

"Delete my comment on the "Runbook: payment retries" node in Hadron."

Only the author can edit a comment. The edit replaces the text: Hadron keeps no history of earlier versions. It records who edited and when (the portal shows that as "(edited)"), and it doesn't notify anyone who already replied. Resolving or reopening a thread doesn't mark it as edited.

The author can delete a comment, and so can a memory manager (the memory's owner, or an owner or admin of the organization it belongs to, or a platform admin) for anyone's comment. What remains depends on the comment:

  • A reply, or a first comment nobody has replied to, is gone. No one sees it any more.
  • A first comment that still has replies stays as a stub: it shows that a comment was deleted, without its text, so the replies keep their context. The stub disappears when its last reply is deleted.

Deleting a comment doesn't count as resolving it, and a deleted comment no longer counts as an open thread, so you can start a new one.

Do it in the portal

Open the node in the portal and choose the Discussion tab next to Content. A badge on the tab counts the node's discussions and turns amber while one is open, and an amber open discussion label sits under the node's name on every tab. Only memories that take comments show the tab.

  • Start one. Type in the box under "Start a discussion about revision N" and choose Post. The node's approval doesn't change: it still reads approved at the same revision.
  • Reply. Choose Reply under a comment, write, and choose Reply again.
  • Resolve or reopen. Choose Resolve on a thread, or Reopen on a resolved one. Anyone who can write to the memory may.
  • Edit your own. Choose Edit, change the text and Save. A comment that was edited carries an "(edited)" label; resolving it doesn't add one.
  • Delete. Choose Delete comment on your own comment (or on anyone's, if you manage the memory) and confirm. It disappears, unless replies still need its context: then a stub reading "Deleted comment." remains, and the replies stay.
  • Older feedback is labelled. A thread written before the node was edited reads "On revision 1, not the text shown here".
  • If you already have an open thread on the node, the tab tells you to reply there, or resolve or delete it, before starting another.

If you can read the memory but not write to it, the tab shows the discussion and says "Writing in it needs write access to this memory."

A memory manager also sees Delete discussion on a thread, which asks for a reason and removes the whole thread for everyone. It leaves the node untouched. There is no Hide.

In lists and before a mint. In the memory's node list, a node with open threads carries an "open discussion" label. Choose Memory actions, then Mint nodes, and the check lists nodes with open discussions as a warning: "They don't block minting, but read them before you mint." Approve all nodes says the same: approving doesn't resolve a discussion.

What a comment never does

  • It never changes the node. Not its content, its revision number, its approval or its mint state.
  • It never blocks approval or minting. Open threads show up as a warning, never as a stop.
  • It grants nothing. Being able to comment gives no right to edit, approve or mint.
  • It isn't everywhere. You can comment in app, knowledge, personal and group memories, not in private or system memories.

Comments: feedback beside knowledge explains why comments work this way.

Move or merge a node that has comments

Comments follow their node. If you move a node to another memory, or merge one memory into another, the node's comment threads move with it. You don't have to do anything for that.

Two cases are refused instead:

Refusal What it means What to do
COMMENT_MOVE_UNCOMMENTABLE The destination is a private or system memory, which takes no comments, and the node (or one under it) has live comment threads. The refusal lists each node and how many comments it has. Ask a memory admin to delete those threads first, or pick a different destination.
COMMENT_MERGE_FOLDS_THREADS A merge would combine a commented node into another node at the same address, and the commented node would disappear. A comment can't move to a different node. Ask a memory admin to delete those threads, or rename one of the two nodes so they no longer collide, then merge again.

A refusal usually arrives before anything changes. A memory merge works in batches, though, so if someone comments on a node that would be folded while the merge is running, the refusal can come after earlier batches have already committed. Then the error also carries partialMerge, with what was applied and how to finish. The source memory is never deleted by a refused merge: remove the blocker and run the same merge again.

These are GraphQL error codes (extensions.code); the merge refusals come from mergeMemories, and from mergeNodes when you ask it to delete the source node. A mergeNodes that keeps the source is not refused, because the source and its comments stay where they are. Deleting a thread is a memory-admin operation (deleteCommentThread) that agents don't get; see Under the hood. Threads an admin has already deleted don't block a move or a merge.

If something goes wrong

What your agent reports What it means What to do
comment_open_thread_exists You already have an open thread on this node. The refusal names it (threadId). Reply in that thread, or resolve or delete it first.
comment_forbidden You can read the memory but not write to it. Ask a memory admin for write access.
comment_memory_not_commentable The node is in a private or system memory. Comments aren't available there.
comment_target_not_found The node doesn't exist, or you can't read it. The two look the same on purpose. Check the node's name or URN, and your access.
comment_not_found The comment doesn't exist, or you can't read it. Check its URN or id, and your access.
comment_target_is_comment You tried to comment on a comment. Reply in its thread instead.
comment_body_invalid The text is empty, over 20,000 characters, or the quote is over 2,000. The refusal names the field. Shorten or fill in the text.
comment_anchor_revision_invalid or comment_anchor_revision_unavailable The revision you named isn't one the node has, or its text is no longer kept. Leave the revision out to comment on the current one.
comment_not_author You asked to edit someone else's comment, or to delete one when you're neither its author nor a memory manager. Reply to it instead, or ask the author or a manager.
comment_deleted The comment, or the first comment of its thread, was deleted and only a stub remains. Start a new thread.
comment_not_top_level You asked to resolve or reopen a reply. Name the thread's first comment (the refusal gives its threadRootId).
comment_thread_state The thread is already resolved (or already open). Nothing to do.
comment_impersonation_refused You're signed in as someone else through impersonation, which can't write comments. Sign in as yourself.
node_write_conflict The comment changed since the agent read it. Ask again; the agent re-reads it.

Under the hood

Comments-only search is hadron_find_nodes with nodeKind: COMMENTS (or ALL for both; the default, CONTENT, leaves comments out). Your agent uses eight MCP tools besides: hadron_list_comments, hadron_get_comment, hadron_create_comment, hadron_reply_to_comment, hadron_edit_comment, hadron_delete_comment, hadron_resolve_comment_thread and hadron_reopen_comment_thread. Their arguments are in MCP tools: Comments.

The same operations are GraphQL queries and mutations (commentThreads, comment, createComment, replyToComment, editComment, deleteComment, resolveCommentThread, reopenCommentThread), plus deleteCommentThread, a memory-admin operation that agents don't get. A comment's editedAt and editedBy say when and by whom its text was last edited, and deleted marks a stub. A node's commentSummary field gives its open and resolved thread counts. See the GraphQL API reference.

The hadron CLI has a hadron comment group, and hadron search --comments-only for comments-only search. They are merged in the CLI's source, but not yet in a released build: the latest release, v0.20.0 (5 October), predates them. Until the next release, a terminal user works in GraphQL, or builds the CLI from its main branch.

hadron comment list <node> [--state OPEN,RESOLVED] [--limit N] [--offset N]
hadron comment get <comment>
hadron comment create <node> --body "..." [--quote "..."] [--anchor-revision N]
hadron comment reply <comment> --body "..."
hadron comment edit <comment> --expected-revision N [--body "..."] [--quote "..."]
hadron comment delete <comment> --expected-revision N [--yes]
hadron comment resolve <thread-root> --expected-revision N [--reopen]

A node or comment is a URN, an id, or a bare loc with -m <memory>. --body-file <path> reads the text from a file. --expected-revision is the comment's own revision (the one the last read or write printed), not the node's. delete asks for confirmation in a terminal; pass --yes in a script. A refused write exits non-zero. comment get shows a deleted stub as deleted, and an edited comment prints Edited: <time> by <who>. There is no hide or retract.

Who the author is. If you started a worker session, the comment is authored by that worker. Otherwise it's authored by you, together with the agent that wrote it on your behalf when the server can tell.