Skip to content

Building an Agent

This guide walks through creating a Hadron agent from scratch — setting up memories, exposing the agent through an app, and configuring the app for use with AI tools.

Overview

An Agent in Hadron is a named configuration that bundles one or more Memories. Clients reach an agent through an App — the unit that holds the API keys callers use and lists the agents it exposes. The composition chain is:

Client → App → Agent → Memory → Nodes

Prerequisites

  • A Hadron account (hadronmemory.com)
  • An organization (created automatically on signup)
  • Node.js 20+ (for hadron-client, if using MCP)

Step 1: Create a Memory

A memory is a knowledge graph — the container for your nodes.

  1. Go to Organizations → your org → Memories → + Add memory
  2. Fill in:
  3. Name: e.g. "Engineering Knowledge"
  4. URN slug: e.g. "engineering" (becomes your-org.com:engineering)
  5. Visibility: Private, Organization, or Public
  6. Click Create

Adding knowledge

You can add nodes to your memory in three ways:

  • Portal: Browse to your memory → Memory tab → Graph or Nodes view. Use the node detail page to create and edit nodes.
  • MCP tools: Connect an AI agent and use h-add-node, h-add-parent-node, h-update-node to build knowledge interactively.
  • Git sync: Point the memory at a GitHub repo. Nodes are YAML + Markdown files synced automatically.

Structured data on nodes

Any node can carry structured JSON data in its data field:

{
  "family_size": 4,
  "dietary_restrictions": ["gluten-free"],
  "location": "Portland, OR"
}

Set data via the portal (Settings tab → Data section) or via h-set-data.

Template variables

Node content can include Mustache templates:

Welcome, {{name}}! You live in {{location}}.

Variables resolve from the node's data, a default data node at the memory root, or other nodes' data (e.g. {{settings.theme}}). For the full resolution rules, partials, escaping, and missing-variable behavior, see Mustache template syntax.

Step 2: Create an Agent

  1. Go to Organizations → your org → Agents → + Add agent
  2. Fill in:
  3. Name: e.g. "Engineering Agent"
  4. Description: What this agent is for
  5. System Prompt: Instructions for the LLM (e.g. "You are a helpful engineering assistant. Always check the knowledge graph before answering.")
  6. Visibility: Private or Organization
  7. Click Create Agent

Add memories to the agent

On the agent detail page → Settings tab → Memories section:

  1. Select a memory from the dropdown
  2. Choose access: Read or Read/Write
  3. Click Add

An agent can have multiple memories — read-only knowledge bases plus a writable memory for saving session data and learnings.

System memory (for chatbot agents)

If your agent uses conversation designs (stages, prompts), set the System Memory ID to the memory containing your conversation nodes.

Optional capabilities

Once an App is connected (Step 3) and shares the agent's URN, the Capabilities section appears in the Settings tab. Each capability is opt-in:

  • Allow this agent to ask users for uploads — enables the asset-upload tool so the agent can prompt users for files (PDFs, images, scanned documents) and read them back later. See Allow your agent to ask for uploads.

Step 3: Install your Agent into your organization

An App is what your client connects to. It holds the API keys and represents the deployment of an Agent in an organization. As of 009, every App is created by installing an Agent — there is no standalone "create blank App" flow anymore.

This is the org-level install. There's also a user-level install (end users joining an existing App as members) that uses the same "Install" word in the UI but a different API call. See Installing an Agent — what "install" means at each level for the disambiguation if you've seen the second one elsewhere and wondered how it relates.

  1. From your org dashboard, click Manage in the Agents section (or navigate to Agents in the org menu).
  2. Find the Agent you just built and click Install on its row. (You can also reach the Install action from the Agent detail page.)
  3. The install form pre-fills:
  4. Name — defaults to the Agent's name; edit if you want.
  5. URN — defaults to <your-org-urn>:<agent-slug>. If you've already installed this Agent into this org and want a second install with a different key, surfaces, or membership, the suffix -2 (then -3, …) is added so the URN stays unique. Multi-install in the same org is supported but uncommon; the typical flow installs once.
  6. App type — Workstation (for coding agents), Chatbot, Agent, Automation, Cloud, or IoT. Defaults to Workstation.
  7. Click Install. You land on the new App's manage page.

The install also wires up everything the App needs: an AgentOrgGrant (your org's license to deploy this Agent) is auto-provisioned, and you're added as the App's first member with role owner.

What about AI configuration?

The install form deliberately does not ask for AI provider/model/key. Your App inherits whatever the Agent author configured at the Agent level. If you need a per-App override (different model, different key, different provider), set it from the App manage page → Settings → AI configuration after the install completes.

Download client configuration

On the app detail page → Client tab:

  1. Enter a name for your app key
  2. Select which AI tools you use (Claude Code, Cursor, etc.)
  3. Click Download setup files (.zip)
  4. Extract into your project root

The zip contains: - .mcp.json — MCP server configuration - .hadron/ — config, instructions, and optional plugin

Step 4: Connect your AI tool

Hadron exposes three integration shapes. Pick by how your AI tool reaches out, not by the languages your app uses.

Integration When to use it Tradeoff
MCP stdio (hadron-client subprocess) Your AI tool launches MCP servers as a local subprocess. Includes Claude Code (with hooks/guided sessions), Cursor, Cline, Codex CLI, Windsurf, Antigravity. Local proxy on the user's machine; needs hadron-client installed. Best DX for coding agents — adds session hooks, plugin scripts.
HTTP MCP (direct to srv.hadronmemory.com/mcp) Your AI tool supports remote MCP servers natively, or you don't want a local proxy. Works with Claude Desktop and any host that speaks streamable HTTP MCP. No subprocess, no plugin hooks. The tool talks directly to Hadron with a Bearer token; nothing is intercepted client-side.
GraphQL (srv.hadronmemory.com/graphql) You're not using MCP at all — Flutter app, web app, mobile client, server-to-server integration, batch jobs. No tool-calling abstraction; you wire individual queries/mutations yourself. Maximum control, full surface area available.

The three are interchangeable in capability — the same operations are exposed through each (read/write nodes, start/send/process chats, sessions, etc.). The choice is just about how the calls travel.

Claude Code (stdio mode)

The .mcp.json file tells Claude Code to launch hadron-client as a subprocess:

{
  "mcpServers": {
    "hadron": {
      "command": "hadron-client",
      "args": ["stdio"],
      "env": { "HADRON_CLIENT_KEY": "your-key-here" }
    }
  }
}

Verify: in Claude Code, type /mcp — you should see "hadron" listed.

Direct HTTP connection

For tools that support HTTP MCP servers:

{
  "mcpServers": {
    "hadron": {
      "type": "http",
      "url": "https://srv.hadronmemory.com/mcp",
      "headers": {
        "Authorization": "Bearer your-key-here"
      }
    }
  }
}

Custom applications (GraphQL API)

For Flutter apps, web apps, or custom integrations, use the GraphQL API directly:

POST https://srv.hadronmemory.com/graphql
Authorization: Bearer your-key-here
Content-Type: application/json

Step 5: Use it

Your AI agent now has access to the knowledge in your memories. It can:

  • Read knowledge: h-read-node, h-find-nodes, h-list-nodes
  • Write knowledge: h-add-node, h-update-node
  • Store data: h-set-data, h-get-data
  • Run guided sessions: h-start-session at guided level
  • Start chats: h-start-chat for conversational agents

Guided sessions (for coding agents)

At guided level, the agent follows a 6-phase protocol:

  1. Task definition → h-save-session-task
  2. Information gathering → h-read-node
  3. Implementation plan → h-save-plan
  4. Performing work
  5. Memory update → update/create knowledge nodes
  6. Summary & quality check → h-end-session

See hadron-client docs/guided-sessions.md for details.

Chat API (for conversational agents)

For chatbot applications, use the Chat API:

  1. startChat(agentId, userId) → get compiled prompt + tool schema
  2. Send to LLM → get structured response
  3. processChatResponse(chatId, response) → extract data, transition stage
  4. Repeat

See the Chat API spec for details.

Node types

Every node has a nodeType. Use the right one for your content:

Type Use for
info Knowledge, specs, guides (default)
abstract Summaries, TL;DRs — searched first
reference External sources (papers, URLs, legislation)
record Chat messages, session logs — hidden by default
system Conversation designs, prompts — hidden from search

For full semantics, search behavior, and guidance on the close calls (info vs. abstract, info vs. reference), see the Node types reference.