Skip to content

Building an Agent

PortalMCPIntermediate~20 min

Give an AI assistant its own knowledge and instructions, then make it available to the people and tools that should use it. The setup happens in the portal — creating memories, the agent and its App can't be done by asking an AI tool over MCP — and after that, you and your AI tools use the agent by asking.

What you'll put together:

Your AI tool → App → Agent → Memories → nodes
  • Memories hold the knowledge.
  • The agent bundles memories with a system prompt.
  • An App is an installed copy of the agent: the thing people and tools connect to.

Before you start

  • A Hadron account (hadronmemory.com) and an organization (one is created when you sign up).

Step 1: Create a memory

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

  1. Open Memories in the sidebar and click + Add memory.
  2. Fill in:
  3. Name — e.g. "Engineering Knowledge".
  4. URN — the memory's permanent address; it suggests one from the name.
  5. Memory kind — Organization knowledge for something your team shares, or Personal / Private for yours alone.
  6. Visibility — for organization knowledge: Organization or Public.
  7. Click Add memory.

Adding knowledge

Structured data on nodes

Any node can carry structured JSON in its data field:

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

Edit it on the node's Data tab in the portal, or have your agent set it (hadron_update_node_data merges keys; hadron_update_node with data replaces the whole object).

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. Open Agents in the sidebar and click New Agent. (For a chatbot with its conversations scaffolded, use New Chatbot instead — see Getting started.)
  2. Fill in:
  3. Name — e.g. "Engineering Agent".
  4. URN — suggested from the name.
  5. Description — what the agent is for.
  6. System Prompt — instructions for the model, e.g. "You are a helpful engineering assistant. Always check the knowledge graph before answering."
  7. Visibility — Personal (the default), Organization or Public.
  8. Click Create Agent.

Add memories to the agent

On the agent's page, open the Memories tab:

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

An agent can have several memories — read-only knowledge plus a writable memory for what it learns.

System memory (for chatbot agents)

If your agent uses conversation designs (stages and prompts), choose its Agent system memory — the memory holding those conversation nodes — in the agent's Settings. It can't be changed once set. An agent with a system memory gets a Chatbot Control tab.

File uploads

There is no per-agent upload setting. Once the agent is installed in an App and has a memory attached with read-write access, users can attach files in the App's agent chat; the agent itself doesn't request them. See Upload a file in an agent chat.

Step 3: Install the agent as an App

An App is what people and tools connect to: an installed copy of the agent in your organization, with its own members and keys. Every App is created by installing an agent.

  1. Open Agents in the sidebar, find your agent and click Install on its row (it's on the agent's page too).
  2. The form suggests:
  3. App name — the agent's name.
  4. URN — <your-org-urn>:<agent-slug>; a second install of the same agent gets -2, then -3.
  5. App type — Workstation (for coding agents; the default), Chatbot, Agent, Automation, Cloud or IoT. Choose Chatbot if people will chat with the agent in the portal: other types have no working agent chat, and a Chatbot App has no Client tab.
  6. Click Install. You land on the new App.

The install also licenses the agent to your organization and — depending on the agent's install policy — makes you the App's first owner.

AI configuration

The install doesn't ask for an LLM provider. The App uses the AI configuration its agent or organization provides; to give this App its own, use Settings → AI providers on the App. See Configure your LLM provider.

Step 4: Connect your AI tool

Connect the AI tool you work in to Hadron once, and it can reach the memories you have access to. Its searches cover the memories of the App it's working in, once one is set; ask it to search all your memories when you want everything.

Those pages use sign-in in the browser, with no key to copy.

Setup files from the App

If you'd rather configure a tool with an App key, open the App's Client tab (on Apps that aren't Chatbots): give the key a Name, tick the tools under Include plugins, and click Download setup files (.zip). Your tool then talks to Hadron directly over HTTP with the key. (If you see a Client mode choice, keep Direct: the other mode needs hadron-client, which is retired for now.) Extract it into your project. What's inside depends on the tools you chose: MCP configuration for each tool, and a .hadron/ folder with instructions and settings.

Custom applications (GraphQL API)

For your own app — a web or mobile client, or a server integration — call the GraphQL API directly with an App key:

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

Step 5: Use it

Ask your AI tool about what the agent knows, in plain language:

In the Engineering Knowledge memory, what do we say about how releases are
tagged? Quote the note you're relying on.

It searches the memory, reads the relevant notes and answers from them — and with write access, it can add or update notes when you ask. See Working through an agent for how to ask, and what to check.

  • Coding agents can work in a structured session that records what they did — see Guided sessions.
  • Chatbots are driven through the Chat API: startChat, then one model turn with no user message — the welcome turn — sent to processChatResponse; after that, sendChatMessage and processChatResponse for each user turn. There's no MCP route for a chatbot chat. See the Chat API reference.

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 — searchable like info
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.

  • Entity architecture — how organizations, agents, memories and Apps relate, which is the model this recipe assembles.