Skip to content

Explanation

Understanding-oriented background. Read this to deepen your mental model of Hadron, not to complete a task. Grouped by feature area.

Core concepts

  • What is Hadron — what the platform does and who it's for.
  • Entity architecture — entity hierarchy: organizations, agents, memories, apps, and the class/instance (Agent → App) relationship.
  • Agents and Apps — an Agent is the reusable definition, an App is one install of it: who owns each, what every install shares, and what each keeps for itself.
  • Surfaces: MCP, CLI, and the portal — the three ways to work with Hadron, what each is for, and which to reach for — with a capability-by-surface table.
  • Working through an agent — most Hadron tasks are ones you hand to a coding agent rather than type: what that changes about where your attention goes, what to ask for, and the four kinds of task you should still do yourself.

Platform & operations

  • Authorization — how Hadron decides what each person and agent is allowed to do: roles, individual grants, and the guardrails that can only ever take away — in plain language.
  • Subscriptions — how an organization subscribes to a memory or agent it doesn't own, and what the subscription buys.
  • Capability tools — why heavy capabilities like document rendering live in separate stateless sidecar tools instead of the core, with the PDF service as the first worked example.
  • Connections and delegated access — why an agent never gets your mailbox: it gets a scoped, revocable grant on a connection you own, issued to one App install rather than to an Agent, with an operation map that fails closed.
  • The RAG tech stack — why Hadron's vector index uses nomic-embed-text and pgvector — the privacy posture behind the choice, and the two supported embedding-server backends (Ollama and AWS SageMaker) an operator can pick from.
  • Inspecting the vector index with SQL — read a memory's index state directly in Postgres: the two tables, the per-source rows and per-node markers, and aggregate queries that tell backfill-draining from complete.

Memory

  • Understanding memory — what memory is in Hadron, the different types, how it's stored and shared.
  • Structured vs. unstructured memory — Hadron is unstructured by default and structured on opt-in, over one substrate: the database analogy (nodes as rows, objectType as tables, schema as columns, where/sortProperty as WHERE/ORDER BY) and when to reach for a schema.
  • Memory access — how agents and apps gain access to a memory, and what the different access levels mean.
  • What a search covers — which memories a search looks at when you don't say: scopes as lenses that never grant, the MCP ladder, how GraphQL and the CLI differ, and why a general search has no winners.
  • How includes work — how one node shows another's text, what a reader sees when an include can't be shown, and how to read the text as written.
  • Memory ownership and lifecycle — which entity owns each memory in Hadron, and what happens when an Agent, App, or Memory is deleted.
  • Assets vs. References — why uploaded files and citable sources are separate primitives, and when to reach for each.
  • Comments: feedback beside knowledge — why a comment sits beside a node rather than in it: it never changes the node, is never approved or minted, and shows as a warning, never a block.
  • Signed revisions — what it means for a person to sign a node with a passkey: what a signature covers, why only a person can sign, how an agent asks for one, and what each signature state tells a reader.
  • Why email sign-in needs a passkey — why an email link alone no longer signs you in, who is affected, and what the passkey step changes and leaves alone.
  • Attested authorship: who wrote this revision — the authorship and validation stamps on a node: what they record, how they behave when a node changes, and why a stamp is a claim rather than proof. Lists what has not shipped yet.

AI automation

  • How multi-node automations work — the mental model behind multi-node headless runs: a flow is a graph the platform walks, routing lives on edges not in prompts, and extracted facts accumulate in a run envelope that conditions branch on.
  • Edge conditions — when to use deterministic edge conditions vs. LLM-controlled routing, and the model behind the portal's condition builder.
  • Agent inheritance — how an Agent extends a base Agent and inherits everything in its system memory but the boot prompt, read live; why the nearest node wins at a shared loc, why an inherited node keeps its base's address, and why a base with live children can't be retired.

Chatbots

  • Testing a chatbot with personas — why a conversation design needs scripted users rather than manual poking, what pass actually asserts (routing, not quality), and why a failing run needs reading, not just re-running.
  • Fixtures, assertions and verdicts in the portal Tester — what a saved test, its check, a verdict, a baseline and a drift label each claim about one reply, and why a check that could not run is not evaluated rather than a failure.

AI coding

  • CLI vs. MCP for a coding agent — the two ways an agent reaches a Hadron server, compared on the axis that usually decides it: context-window tokens. Plus auth, structured output, and traversal.
  • Product specs and citations — why product rules live in a corpus of permanent citations rather than in code, tickets or a wiki; what a citation buys by never moving; and why the durable-vs-tunable split decides every change.

Agent team

  • Teams, workers, and sessions — why a persona is dressing on an Agent and the named identity is a worker, why a team is an App, the difference between a worker session and a chat session, the chain that traces a merged PR back to its transcript, and why a worker's name is never re-minted.
  • Acting on a holder's instruction — why a worker its holder clearly told to may change a worker's signature, trailer or casting, what the instruction claim is, what is recorded, and what the platform does not check.
  • Team tasks — what a team task is, why it has an owner and a separate assignee, how it moves from backlog to finished, and how the platform raises an alarm when work goes quiet.
  • What wakes a worker — when the platform decides a team worker should be nudged (a mention, a ticker's tick, a task event), what holds a wake back, and why a wake carries counts rather than messages.
  • The action register index — which code sends work to which role task for an App, how each answer is found through the Team Agent's and the asking Agent's chains, the three states, and why an index can come back empty without saying why.
  • Stopping workers — the stop signal a team App uses to stop a worker, a team or a host: what each level does, who may set and lift one, what the shipped CLI does with a stop notice and its limits, and when the server refuses to set one.
  • Channels — the durable, ordered message streams people and agents share; your team chat is one. Who can read a Channel is decided by the memory hosting it, the register that says who takes part grants nobody anything, and unread is worked out rather than stored.

Research notes

Measured findings about how Hadron behaves, with the method and the data, so you can check them or repeat them on your own corpus.

  • What makes a node findable — a controlled experiment on Hadron's own 271-node spec corpus: abstract length barely matters, subject drift decides everything, and a disappointing search result is usually a corpus problem rather than a node problem.