Skip to content

Add a memory to an App

CLIAPIIntermediate~10 min

An App reaches memories through the Agent installed in it. There are two ways to put a memory in that reach:

  • Create a new App-scoped memory — it belongs to the App/Agent pair from birth.
  • Attach an existing free-standing personal or private memory — it keeps its own identity and simply becomes reachable.

Both are hadron CLI commands. For what each memory class means and who owns it, see Memory ownership and lifecycle.

Before you start

  • You're signed in (hadron auth whoami).
  • You have the target App and an Agent installed in that App — both are required, and they're passed together.
  • Permission depends on the class, because the classes mean different things:
    • personal / private — App membership is enough. The memory is your own and you become its owner. Attaching an existing memory is the same.
    • app — org OWNER or ADMIN. An app-class memory is shared deployment data for everyone using the App, so creating one is an admin action; a plain App member gets FORBIDDEN.

Every reference — memory, App, and Agent — accepts an ID, a bare URN, or a prefixed URN. The bare form is the same shape for all three; only the prefixed form differs, by type:

memory   hrn:mem:<root>:<slug>     or  <root>:<slug>   or  the memory's id
app      hrn:app:<root>:<slug>     or  <root>:<slug>   or  the App's id
agent    hrn:agent:<root>:<slug>   or  <root>:<slug>   or  the Agent's id

<root> is an organization domain or a user handle. The legacy :: separator and the urn: scheme are still accepted on input. See URN composition.

1. Create a new App-scoped memory

Pass --app and --agent together, plus a --class and a --name:

hadron memory set \
  --app acme.com:coach \
  --agent acme.com:coach-agent \
  --class app \
  --name "Runbook"

--class accepts three values here:

Class Who it's for Who may create it Use it when
app Shared across everyone using the App org OWNER/ADMIN Collaborative App data — runbooks, shared lists, schedules.
personal The calling user, scoped to this App any App member Per-user records the App writes on your behalf.
private The calling user, not visible to the App owner any App member Sensitive per-user notes.

The example above uses --class app, so it needs org OWNER/ADMIN. If you're a plain App member, use --class personal (or private) — you'll own the result.

App-scoped create rejects --slug

You can't choose the URN slug on this path. App-class URNs are name-derived by the server; personal/private URNs use a per-owner opaque id. (Free-standing create still supports --slug — see the CLI reference.)

The Agent must already be installed in the App; if it isn't, the server returns a typed install error rather than creating anything.

2. Attach an existing free-standing memory

If the memory already exists on its own, bind it instead of copying it:

hadron memory attach acme.com:my-notes \
  --app acme.com:coach \
  --agent acme.com:coach-agent

Three constraints:

  • Only personal or private memories can be attached. Org-shared classes (knowledge, group) reach an App through org membership and subscriptions instead.
  • The memory must be caller-owned — you can't attach someone else's.
  • It must be free-standing (not already App-scoped).

Attaching does not re-address the memory. It keeps its URN, class, and owner — you're widening who can reach it, not moving it. That's the key difference from memory clone / memory extract, which produce a new memory.

The server names each failure mode, so you can act on it rather than guess: UNSUPPORTED_MEMORY_CLASS (not personal/private), MEMORY_ALREADY_APP_SCOPED, APP_UNINSTALLED, AGENT_NOT_INSTALLED, ORGANIZATION_MISMATCH, and FORBIDDEN. Creating has the same shape, plus MEMORY_URN_CONFLICT when the derived name collides.

3. Verify the result

Read the memory back and confirm its class and URN:

hadron memory get acme.com:my-notes --json

For a memory you just created, check that the class matches what you asked for and note the server-assigned URN (you didn't choose the slug). For an attached memory, confirm the URN and class are unchanged from before.

You can also list what you can reach, including memories shared with you:

hadron memory ls --shared-with-me

Which one do I want?

Reach for… When
memory set --app --agent The memory is for this App and doesn't exist yet.
memory attach The memory already exists standalone and should stay itself.
memory clone / extract You want a copy or a subtree carved into a new memory — a different memory, not the same one re-scoped.