Skip to content

Memory access

Hadron is a multi-tenant memory platform. Multiple organizations, agents, apps, and end users share the same server, and the platform — not the calling app — decides who can read and write each piece of memory. This page explains how those decisions are made.

If you're new, start with Understanding Memory for what memory is, then Subscriptions for the App↔Agent and User↔Agent concepts, then come back here for how the gates compose.

The six memory classes

Every Memory row carries a class field — one of six values: system, app, knowledge, personal, group and private. Each class is governed by a different entity, with different access semantics. The class tells you which entity governs the memory. It does not, on its own, tell you who may read it: the audience comes from the access rules this page and the App memory map link to.

Class Purpose Governed by Strict ownership?
system The Agent's own definition: conversation designs, prompts, partials, topics. The Agent's "brain." Read-only from any App context (008-agent-installation R-10), with one carve-out: an App's install memory, the customization of an installed Agent that belongs to that one App, which the App's managers write and its participants read (see Install memory). An Agent's own system memory is edited in the Agent's ownership surface, not through any App. No
app Records the App writes through the Agent — chat history, extracted facts, generated artifacts. Scoped per install. Memory.app_id ties the memory to one App; it is required for this class. Per Agent.memoryProvisioning.appMemory: 'shared' keys on (app_id, agent_id); 'user' keys on (app_id, agent_id, user_id). Which of that App's people or sessions can read a given app-class memory depends on its role within the App — see below. No
knowledge Reference content the Agent reads from. Domain articles, lookup tables, training material. Read-mostly. Per-Agent (not per-install) — same Agent shared across two installs sees the same knowledge memory. AgentMemoryItem.role per-attached-memory (read or read-write). No
personal Per-user records: a single user's chat history, preferences, private notes. Keyed on (app_id, user_id) — privacy-isolated across installs of the same Agent. A user can also create one directly, free-standing, belonging to no App. AgentSubscription(user, app.agent_id) AND Memory.app_id = app.id for the App-keyed write path. Yes — Memory.userId only.
group Team-shared memory with no single owner, shared symmetrically among its members. Explicit MemoryMember rows with reader, writer or owner roles, not a single user: Memory.userId is always empty for this class. Its visibility is GROUP. May be attached to an App, or free-standing. No — governed by membership
private A single owner's most private memory. A user can create one directly, free-standing, or it can be scoped to an App like a personal memory. Memory.userId only. Unlike personal, it has no share path at all. It is the only class that may opt into encryption (see Private, encrypted memories). Yes — Memory.userId only.

The last column matters. Four of the six classes follow their own governing rules — ADMIN/OWNER bypasses, org-level memberships, cross-org subscriptions, or explicit group membership. The other two (personal and private) do not. A user's personal or private memory is theirs alone. Org admins of the Agent's owning org cannot read it. Org admins of the user's personal org cannot read it. Even platform-level OWNER cannot read it. Nobody reaches it by virtue of a role.

The one way another person reads a personal memory is if its owner deliberately hands it to them — a memory share, a per-user reader/writer grant that only the owner (the memory's principal) can create. That's not a bypass of strict ownership; it's the owner exercising it. private memories can't be shared at all. See Share a memory with someone.

The app class names a tenancy, not an audience. An App owns several kinds of app-class memory, and they do not share readers: the team space shared per App-and-Agent pairing, a Worker's own working memory, and a session's scratch or per-user memory. Knowing that a memory is app-class tells you which App it belongs to, never who within that App may read it. Check the memory's role before assuming an audience.

Adding a memory of its own to an App

An App, whether organization-owned or user-owned, can get one more memory for its people to read and write. For an organization's App this works even when the Agent installed in it belongs to a different organization. An admin of the App's organization adds it, or the owner of a user-owned App; the Agent's owning organization gains no access to it. This is a new, free-standing app-class memory, not part of the Agent and not made through it.

It is not any of the other App-related memories on this page. It is not the Agent's system memory (read-only from the App) and not the App's install memory (the App's customization of that Agent). It is also not the team space shared per App-and-Agent pairing, a Worker's own working memory, or a person's personal or private memory scoped to the App. It carries no Agent selection of its own, and the existing "tenancy, not an audience" rule above still holds for those other app-class memories.

Who can add one. A person acting as themselves:

  • on an organization's App: an ADMIN or OWNER of the App's organization. That is the same organization-role gate other org-management operations use, so a platform administrator is also admitted, as they are elsewhere; this is the platform role, separate from the organization role.
  • on a user-owned App: its owner, and only its owner. The platform-administrator admission above does not apply here.

These callers are refused, even when the person behind them could do it:

  • an App key
  • a worker session, including one bound after the connection opened
  • a headless run
  • an impersonation session

When it works. The App must have at least one Agent installed. It can be organization-owned or user-owned.

What it creates. A new memory whose name sets its slug, with its own root node. Its audience is the App's participants (who counts), who read and write it. An existing memory cannot be attached through this operation: attaching a free-standing personal or private memory to an App is a different action, described in Add a memory to an App.

Refusals.

Code Meaning
FORBIDDEN On an organization's App, the caller is neither an ADMIN or OWNER of the App's organization nor a platform ADMIN or OWNER. On a user-owned App, the caller is not its owner. Or the caller is one of the refused principals above. A hidden App is not confirmed by the message: a stranger, and an unknown or deleted App, get the same answer.
AGENT_NOT_INSTALLED The App has no live Agent installed.
BAD_USER_INPUT The name is empty.

The installation and the caller's authority are checked again inside the transaction that creates the memory, so an Agent being uninstalled, or a membership revoked, while the request is in flight cannot leave a memory behind. This page does not promise a single order in which the refusals are checked.

Where to do it. The three routes below do the same thing and follow the rules above; none of them can attach an existing memory.

  • In the portal. Open the App, choose its Memory tab, and find App memories. Fill in Name (required) and, if you like, Description, then choose Create memory. The new memory's name appears as a link, with its URN beneath it, and the memory shows in the App's memory table. The form shows only if you are an ADMIN or OWNER of the App's organization.
  • With the CLI. Run hadron memory set --app <app> --class app --name "<name>", with the App as an id or URN. Leave out --agent: with --agent the command makes a memory for that installed Agent instead. --short, --description and --tag are optional, and there is no --slug, since the server names the memory. Run it as yourself, not with an App key. See hadron memory set --help.
  • Through the API. Call the GraphQL mutation createAppMemory or the MCP tool hadron_create_app_memory. For the exact inputs see GraphQL schema and MCP tools.

The governing rule is spec cor:acl:010:01.

Install memory: the one system memory an App writes

When an App wants to change how an installed Agent behaves for that App alone, the change is kept in the App's install memory: a system-class memory for one App and Agent pair. The Agent's own system memory is never touched, and no other App sees the change. The install memory is created the first time a manager writes to it. Reading it creates nothing.

Its audience differs from every other class, and it changes when the App is deleted:

Act While the App is live After the App is deleted
Read the nodes The App's participants Nobody
See that the memory exists Participants and managers Managers only
Write Managers, while the Agent is still installed Nobody
Delete Managers Managers

"Managers" means the App's owner, its OWNER members, and org and platform admins. An App key and a run are never admitted at all. An impersonated session can read the way the impersonated person's participation allows, but it is never treated as a manager, so it cannot write or delete. Nothing running on the App's behalf can rewrite its own customization. The memory stays class: system; the response field isInstallMemory is true. To customize an Agent, see Customize an installed Agent for your App.

For a personal App's install of a non-PUBLIC organization Agent, the Read the nodes row is narrower: only App participants who are current members of the Agent's organization may read, and only while the App owner's licence holds. The same reader narrowing applies to the Agent's system memory through that install. The table's write statement does not cover this case. See Use your organization's Agent in a personal App.

The App memory map

An App reaches memories of several shapes, and the same class can cover more than one of them. This map lists every shape, so you can tell which one you are looking at. It states what each shape is and where its App id comes from. Who may read or write each one is not copied here. That is the access rule, spec cor:acl:010:01, and a class or an App id never works it out for you.

There is no precedence between ordinary memories. Two memories may hold the same loc, and those are two different nodes with two different URNs. Nothing merges, shadows or overrides between them.

# Shape What it is App id
1 app: team space The memory shared per App-and-Agent pairing: team chat, worklog. Required
2 app: a Worker's own working memory A Worker's casting-scoped memory. Handoffs live here. It does not have the team space's audience. Required
3 app: session scratch A session's scratch memory. Required
4 app: per-user The intended shape when an Agent declares memoryProvisioning.appMemory as 'user': keyed with the user. The server does not provision it yet, so setting 'user' does not give you a per-user memory today. Required
5 app: free-standing App-owned memory Made by createAppMemory (hadron_create_app_memory), with no Agent selection. It is not rows 1 to 4, the install memory or a personal or private memory. Its audience is the App's participants under the access rule, which is a separate row from the team space. See Adding a memory of its own to an App for how to make one. Required
6 system: the Agent's own memory The Agent's definition. Edited in the Agent's ownership surface. Never
7 system: an install memory One App's customization of an installed Agent (isInstallMemory is true). Its audience is the table in Install memory. Carries the App's id
8 knowledge, personal, private As described in the class table above. Optional: set when provisioned inside an App, absent when free-standing
9 group A membership-governed team memory. Allowed, but not offered yet. How an App-scoped group memory is governed is still undecided, and this page says no more than that

Nine rows are nine shapes, not nine classes: rows 1 to 5 are all app, rows 6 and 7 are both system.

Install memory replaces only when a boot prompt is compiled. An install-memory node replaces the Agent's node when a boot prompt is compiled, never on an ordinary node read. Compiled prompts are served without a deployment switch; licence, approval and other serving refusals still apply.

The four-gate cross-org chain

A real call from an App to a Memory crosses up to four organization boundaries. Each boundary has a gate. All gates must clear, in order. Failure at any gate denies the call with a typed error indicating which layer fired.

                                 ┌──────────────┐
        ┌──────────────┐         │   OrgD       │
        │   OrgA       │         │ (knowledge   │
        │  (App)       │         │  publisher)  │
        │              │         │  ┌────────┐  │
        │  ┌────────┐  │         │  │ Memory │  │
        │  │  App   │  │         │  └────────┘  │
        │  └───┬────┘  │         └──────────────┘
        └──────┼───────┘                ▲
               │  ┌──────────────┐      │
               │  │   OrgB       │      │
               │  │  (Agent)     │      │
               │  │              │      │
               │  │  ┌────────┐  │      │
               └──┼─→│ Agent  │──┼──────┘
                  │  │   │    │  │
                  │  │ system │  │
                  │  │ memory │  │
                  │  └────────┘  │
                  └──────────────┘
                       ▲
                       │
          ┌────────────┴────────────────┐
          │  personal-{user}            │
          │  (User's personal org)      │
          │                             │
          │   ┌────────────┐            │
          │   │ Memory:    │            │
          │   │ personal   │            │
          │   │ (User-     │            │
          │   │  owned)    │            │
          │   └────────────┘            │
          └─────────────────────────────┘

The gates, in evaluation order:

Gate 1 — App ↔ Agent

Predicate: App.agent_id IS NOT NULL AND Agent.visibility allows the App's organization. Cross-org installs additionally require an active AgentOrgGrant(App.organization_id, App.agent_id). Same-org installs auto-pass even without the grant row.

Agent.visibility values:

  • PUBLIC — any org can install this Agent (subject to having an active AgentOrgGrant).
  • ORGANIZATION — an organization App can install this Agent only in the Agent's owning organization. A person can also install it into their own personal App while they are a current member of that organization and hold an active subscription; see Use your organization's Agent in a personal App. (This is the common case for internal chatbots — e.g., Juno is ORGANIZATION-visible inside Micromentor.)
  • PERSONAL — only the Agent's creator. (Agent.visibility is its own AgentVisibility enum; the creator-only value is PERSONAL, not PRIVATE — that word is reserved for the memory private class.)

Failure: denied at the App↔Agent layer.

Gate 2 — Agent ↔ Memory

For knowledge-class memories (the cross-org case): AgentMemoryItem(agent, memory) exists; Memory.visibility allows the Agent's organization; if cross-org, MemorySubscription(orgB, memory) exists and any required MemoryLicense is valid.

For system-class memory: always co-org with the Agent (it's the Agent's own design). Access is implicit; the gate just confirms memory.id = agent.systemMemoryId. The exception is an App's install memory, which has no place in this gate: it belongs to one App and has its own audience (below).

For app-class memory: keyed on (app_id, agent_id) (or (app_id, agent_id, user_id) for per-user-app-memory Agents). The gate checks memory.app_id = app.id.

Failure: denied at the Agent↔Memory layer.

Gate 3 — User ↔ Agent (personal-class only)

Predicate: AgentSubscription(user, app.agent_id) exists AND is active (activated, not revoked, not expired) AND Memory.app_id = app.id.

This gate fires only when the call touches a personal-class memory. For other classes, it's a no-op.

The Memory.app_id = app.id half is what gives multi-install isolation: Mike's personal memory at Juno-on-MicroMentor lives at (microMentorAppId, mike.id); his personal memory at Juno-on-Company-X lives at (companyXAppId, mike.id). A session through one App is denied access to the other's data even though both Apps deploy the same Juno Agent.

Failure: denied at the User↔Agent layer. The Agent has no permission to write to this user's personal memory through this call.

Gate 4 — Effective role

Predicate: the most-restrictive composition of all relevant role values:

  • AgentMemoryItem.role (caps per-attached-memory writes)
  • MemorySubscription.role (caps cross-org writes)

(Pre-008 also included AppAgent.role. That's gone — system memory is universally read-only from any App, so no role-based cap exists at the App↔Agent layer.)

For personal and private memories, the strict-ownership rule from §"The six memory classes" also applies: even an ADMIN/OWNER who would otherwise satisfy the previous gates cannot read a personal/private memory they do not own. (Ownership is keyed on the memory class via Memory.userId; their visibility is null.)

Failure: read may succeed, but write is downgraded to denial.

Concrete example: the Juno chatbot

Juno is a chatbot Agent owned by Micromentor (visibility = ORGANIZATION). End user Alice signs up to Micromentor as an OrgMember and starts a Juno conversation.

Gate Predicate Status
1 App-keyed call from Micromentor's Juno frontend App; App.agent_id = juno.id; Agent.visibility = ORGANIZATION and the App is in Micromentor (same-org install auto-passes) ✅
2 Juno's writes are personal-class for Alice — M.class = personal. Memory at (juno-app.id, alice.id). ✅
3 AgentSubscription(alice, juno) was auto-provisioned on Alice's first message and is active. Memory.app_id = juno-app.id matches the calling App's id. ✅
4 Strict ownership: M.userId = alice and ctx.userId = alice — match. Effective role is read-write through the subscription. ✅

The call succeeds. Now suppose a Micromentor ADMIN (call them Bob) tries to read Alice's Juno memory through the portal:

Gate Predicate Status
1 Bob is JWT-authenticated, not App-keyed. Gate 1 doesn't fire (no App in the call). n/a
Strict ownership M.class = personal, M.userId = alice, ctx.userId = bob. ❌

Bob's read is denied. Even though he's an org ADMIN of Juno's owning organization. Even though he could see every other knowledge memory in Micromentor. personal (and private) memories are strictly owner-only — no role gets Bob in.

The only door is Alice's to open: she could grant Bob a memory share on that personal memory, and he'd read it as a grantee, not as an admin. She can't do that for a private memory, which is unshareable by design.

Why this matters

The four-gate chain plus strict ownership is not paranoia — it's the trust boundary Hadron promises to chatbot operators and their end users.

  • A chatbot operator's customers can give the bot personal context (medical history, financial details, private notes) knowing that the operator's own employees cannot read it.
  • An employee leaving the operator org (and losing their org membership) doesn't auto-cancel any customer's AgentSubscription; the customer's data stays accessible to them.
  • A bug in the chatbot frontend that "remembers the wrong user" cannot accidentally serve Bob's personal memory to Alice; the personal-memory access path requires the call to come on behalf of userId = bob AND for Memory.userId = bob.
  • Memory ownership flows down to the end user — they hold the keys, not the org that provisioned the chatbot.

These guarantees cost a few extra database lookups per call (well within the existing access-resolution budget). They are non-negotiable.

What if a gate evaluation looks wrong?

The effective access for any (user, memory) pair — and the grant that confers it — is queryable directly with hadron access check <user> <memory-urn>, which reads the server's authoritative resolver rather than re-deriving the gates by hand.

Common debugging shapes:

Symptom Likely gate Check
App-keyed call denied; nothing user-related involved Gate 1 Is App.agent_id non-null? Is Agent.visibility compatible with the App's org? For cross-org installs, is the AgentOrgGrant(App.organization_id, App.agent_id) active?
App-keyed call to a knowledge memory denied; cross-org Gate 2 Is there a MemorySubscription from the Agent's org to the memory's org? Is any required MemoryLicense valid?
App-keyed call to a personal memory denied Gate 3 Is AgentSubscription(user, agent) active? Does Memory.app_id match the calling App's id? (A common cause: the user has personal memory in a sibling install of the same Agent — those are isolated.)
Read succeeds but write fails Gate 4 What's the most-restrictive role in the composition? Often AgentMemoryItem.role = read capping a write.
User can read their own personal memory directly but not through the Agent Gate 3 (revoked) Is the AgentSubscription revoked? The Agent is denied; the user is fine.

What's next

  • Entity architecture — the entity hierarchy, and the class/instance relationship that motivates the per-install isolation in gate 3
  • Subscriptions — the AgentOrgGrant (Org↔Agent) and AgentSubscription (User↔Agent) entities in detail
  • Understanding Memory — what each memory class actually contains
  • User profile visibility — which of another user's profile fields you can see, and how user search is scoped