This page is generated from the GraphQL SDL in hadron-server/src/api/graphql/schema/typeDefs.ts.
To refresh it, run npm run docs:graphql from the root of this repo.
Convention: ID or URN
Across the GraphQL API, fields that take an entity reference (memoryId, agentId, appId, orgId, or id on an entity-keyed op) accept either the entity's database ID or its URN. URNs may be passed bare (e.g. acme:family-mealplan) or with the optional canonical hrn:<type>: prefix (e.g. hrn:memory:acme::family-mealplan); the legacy urn:<type>: prefix is also accepted on input. All shapes resolve to the same entity, with identical authorization and behavior. The closing line of every in-scope field's description — "Accepts the entity's ID or URN." — calls out which fields participate.
# These two queries are equivalent:query{memory(id:"cm5x...kqp"){name}}query{memory(id:"acme:family-mealplan"){name}}
Resolve a fully-qualified, \`hrn::\`-prefixed Hadron URN (legacy \`urn:\` scheme also accepted) to the ids
needed to reach its canonical page. Returns null when the URN is
unresolvable (not found) OR the caller lacks access. Unlike the dedicated
per-kind queries — which throw \`Forbidden\` on no-access — this query
deliberately collapses both not-found and no-access to null, so a
redirect resolver can 404 uniformly without disclosing which case it was.
Per-kind access uses the SAME authorization rules as the dedicated
queries (memory/org/agent: org membership; app: org ADMIN; node:
memoryAccessFilter), only with the throw replaced by a null return.
The \`hrn::\` prefix (legacy \`urn::\` also accepted) is the
dispatch key — bare URNs without a type prefix are ambiguous across kinds
(\`org::slug\` could be a memory or an agent) and resolve to null.
Scope to a single memory, addressed by ID or fully-qualified URN
(007-entity-id-or-urn dispatch via resolveMemoryRef). Intersected
with the caller's access filter — scoping to an inaccessible
memory yields [], and an unknown ref throws NOT_FOUND. Added for
the hadron-cli \`node ls --memory\` surface; mirrors the
usageEvents(memoryId:) filter (#249).
Vector/hybrid-aware search over a memory. Keyword-only callers should
keep using the legacy 'nodes' query — nodeSearch is the
vector-aware entrypoint per spec 033 contract.
mode defaults to vector (the vector-aware entrypoint design — the
MCP h-find-nodes tool defaults to keyword for backward-compat,
a deliberate divergence between the two surfaces). expand (graph
neighbor depth 0..3, default 0) and granularity:chunk (passage
retrieval, vector-mode only) are both fully live.
Access control: same memory-read gate as the keyword nodes query —
the raw-SQL similarity query is scoped to memories the caller can
read, never cross-memory.
005-agent-subscription FR-022: list all AgentSubscriptions for an
Agent. Authorized for ADMIN/OWNER of the Agent's owning org.
Accepts the entity's ID or URN.
025-oauth-for-mcp FR-004: list the calling User's API keys (active
+ revoked, createdAt DESC). Powers Phase 3's portal revocation UI
(SC-006). Rejected with UNAUTHENTICATED for AppKey-resolved
callers (no user in context). PR-137 review delta D5 — Query
not present in PR 137.
Agent AI config (org ADMIN) — returns the decrypted API key so the
portal backend can make LLM calls on behalf of the user.
036-ai-service-config: registry-backed (the Agent's config named
'default'). Prefer resolveAIConfig for new callers.
Accepts the entity's ID or URN.
036-ai-service-config: masked list of the AI configs owned by one
entity. Never returns key material — only hasApiKey + apiKeyPreview.
Auth: platform ADMIN/OWNER for HADRON_SERVER owners; org ADMIN of
the owning org for ORGANIZATION / APP / AGENT owners.
ownerId accepts the entity's ID or URN (HADRON_SERVER: ID only).
036-ai-service-config: resolve a config name for an execution context
and return the DECRYPTED credentials (privileged; successor to
agentAIConfig/appAIConfig).
Walk: App -> Agent -> Org (of the App, else of the Agent) ->
HadronServer; disabled configs are skipped. When name is omitted,
'default' is resolved. When an explicit name misses, resolution falls
back to 'default'; if that also misses, errors with
NoAiConfigAvailableError. Consumers (webhooks, scheduled tasks, the
portal chatbot) reference configs by name only — pass the name plus
the execution context, never credentials.
Auth: org ADMIN of the effective context org, or platform
ADMIN/OWNER (required when no app/agent context is given).
appId/agentId accept the entity's ID or URN.
036-ai-service-config: the MASKED set of configs RESOLVABLE in an
execution context — every distinct config name a chat in this context
could select. Populates a config picker in the chatbot UI.
Same walk as resolveAIConfig (App -> Agent -> Org (of the App, else of
the Agent) -> HadronServer), but returns ALL names instead of resolving
one: configs are deduped by name with the innermost owner winning, so
each entry is the row resolveAIConfig would return for that name. Only
the Agent named here contributes — sibling Agents installed in the same
App are not consulted. Disabled configs are skipped. Never returns key
material (hasApiKey + apiKeyPreview only).
Auth: scoped to one App's chat context. A non-admin caller MUST pass an
appId, be a member of that App, and (when an agentId is given) the Agent
must be installed in that App. Because the result is masked (no key
material), App membership — not org admin — is the bar, unlike
resolveAIConfig and the aiServiceConfigs management list. Platform
ADMIN/OWNER are always allowed and may omit appId.
appId/agentId accept the entity's ID or URN.
v2 (spec 006) — memory-addressed listing. Returns assets for a
specific memory; caller must have read access. The replacement
for agentAssets in the v2 surface.
Accepts the entity's ID or URN.
App key management — revoke all active keys for an App and mint a
fresh one. (See createAppKey / revokeAppKey / deleteApp below.)
Accepts the entity's ID or URN.
Create a memory in an organization. Accepts the entity's ID or URN
for orgId.
Defaults to knowledge-class with ORGANIZATION visibility. Pass
memoryClass: group + visibility: GROUP for a group-class memory
(023-app-shape US4; the caller is auto-added as the first owner),
or memoryClass: personal | private for an owner-only memory the
caller owns (spec 034 — free-standing, no app/agent; the caller
must be a member of the org container). system- and app-class
memories are NOT created here — they auto-provision via
Agent.systemMemoryId / the App install path.
'knowledge' (default), 'group', or the owner-only 'personal' /
'private' (spec 034). 'system' and 'app' are rejected — they
auto-provision via different code paths.
Update a Memory.
Accepts the entity's ID or URN.
Spec 033 FR-026: enabling \`vectorIndexEnabled\` on an \`isEncrypted\` memory
requires \`acknowledgeVectorInversionRisk: true\` in the same call. Without
the flag, an \`EncryptedVectorIndexNotAcknowledgedError\` is thrown carrying
the full four-point disclosure on \`error.disclosure\` (single source of
truth in \`FR_026_DISCLOSURE\` — see \`src/lib/entityRef/errors.ts\`). On a
non-encrypted memory the flag is a no-op.
Clone a Memory into a new Memory (same org) named \`name\`.
Accepts the source's ID or URN. Copies the Memory row plus all live
Nodes, Edges, and PendingEdges; references to the source memory's URN
inside node content/abstract (canonical and legacy spellings) are
rewritten to the clone's URN. Vector-index config carries over and the
clone's nodes are stamped for re-embedding.
NOT copied: version history, subscriptions, shares, group members
(the caller is bootstrapped as a group clone's first owner), sessions,
licenses, log entries, assets, and git-sync config (the clone starts
DB-only).
Authorization mirrors deleteMemory: personal/private → owner only;
knowledge/group → org ADMIN. system/app-class sources and encrypted
memories are rejected.
Start a chat session (creates chat nodes, loads conversation, returns
compiled prompt). When called by a JWT user, the chat is created in
that user's personal memory for the agent (provisioned lazily if
needed).
Accepts the entity's ID or URN.
Update an Agent's AI provider config. Key is encrypted at rest.
036-ai-service-config: upserts the Agent's registry config named
'default'. Prefer createAiServiceConfig/updateAiServiceConfig for
new callers.
Accepts the entity's ID or URN.
036-ai-service-config: create a named AI config on an owner entity.
apiKey semantics: omitted = stored without a key (unusable for
execution until one is set); non-empty = encrypted at rest with a
masked preview. Name must be 1-64 lower-case [a-z0-9_-], unique per
owner. provider must be a known provider; params are validated per
provider.
Auth: as aiServiceConfigs. ownerId accepts ID or URN
(HADRON_SERVER: ID only).
036-ai-service-config: update a named AI config. All fields optional.
apiKey semantics: omitted = keep the stored key; empty string =
clear it; non-empty = replace (encrypted, preview recomputed).
Auth: admin rights on the owning entity (as aiServiceConfigs).
036-ai-service-config: delete a named AI config (hard delete; the
resolution walk simply no longer finds it).
Auth: admin rights on the owning entity (as aiServiceConfigs).
Install an Agent into an organization, creating an App that deploys it.
Auto-provisions an AgentOrgGrant for (orgId, agentId) on first install,
and adds the caller as an AppMember with role 'owner'. Required
AgentImports cascade automatically; optional imports cascade only when
their id appears in installOptional.
009-install-agent-flow: the cross-org install restriction (FR-009) is
enforced at the portal — the Install affordance is hidden for Agents
not owned by the calling org. The server still auto-provisions grants
on first install (preserved from 008); a hard server-side cross-org
gate is reserved for the marketplace spec.
Accepts the entity's ID or URN.
The Agent this App deploys. Required as of 009-install-agent-flow:
every App must reference an Agent. The server itself accepts any
Agent the caller can resolve and auto-provisions an AgentOrgGrant
(008 behavior preserved); the portal's install flow restricts the
affordance to Agents owned by the caller org. A hard server-side
cross-org gate is reserved for the marketplace spec.
008-agent-installation: optional dep Agent ids to cascade-install.
Required imports of the parent Agent always cascade; optional imports
install only when their id appears here. Pass [] (or omit) to skip
all optional deps. v1 accepts ID or URN.
Install an Agent into an App (023-app-shape US1). Creates an AppAgent
row joining the two. An App can have multiple Agents installed; one
credential addresses all of them.
Rejects with code DUPLICATE_APP_AGENT when the Agent is already
installed in the App.
Accepts the entity's ID or URN for both appId and agentId. Optional
trainingMode flag updates the per-App training flag (applies to
every installed Agent — training mode is per-App, not per-Agent,
per spec 023 FR-001).
Uninstall an Agent from an App. Deletes the AppAgent row. The Agent's
per-(App, Agent, *) memories are NOT cascade-deleted (spec 023 FR-005);
they persist as orphans and become reachable again if the same Agent
is later reinstalled.
Idempotent — succeeds whether or not the AppAgent row exists.
Accepts the entity's ID or URN.
Idempotent UPSERT of an AppMember row. Per spec 008-agent-installation
FR-004 / FR-016. The role MUST be a value present in the parent
Agent's installationPolicy.memberRoles. Creating a new member is
rejected if the App's current member count meets or exceeds the
Agent's installationPolicy.maxMembers. Updating an existing member's
role does NOT trigger the maxMembers check.
Accepts the entity's ID or URN.
Delete an AppMember row. Idempotent (no-op when the row doesn't exist).
Personal-class memory at (appId, userId) is retained as an orphan per
FR-015 — re-attaches automatically if the user later rejoins the same
App.
Accepts the entity's ID or URN.
023-app-shape US2 — user-level install. The currently-logged-in user
joins the App as an AppMember. NO OrgMember check (spec 023 FR-009)
so this works for B2C / consumer / therapy use cases where the
end-user is not in the App's operator org.
Role defaults to the first value in the Agent's
installationPolicy.memberRoles (the conventional "guest" or "owner"
slot). Idempotent — if the user is already an AppMember of the App,
the existing row is returned.
Error codes (GraphQLError extensions.code, Error.name style):
- UNAUTHENTICATED — no logged-in user in context.
- AppNotFoundError — the App does not exist or is soft-deleted.
- AppUninstalledError — the App is in the spec-021 soft-uninstall
lifecycle phase.
- OrphanAppError — the App has no installed Agents (so there's
no Agent.installationPolicy to consult).
- NoMemberRolesError — the primary Agent's
installation_policy.memberRoles is empty, so joinApp can't
pick a default role.
- MaxMembersExceededError — the Agent's maxMembers limit is hit.
- InvalidRoleError — the picked default role isn't accepted by
the Agent's policy (rare; would indicate a policy update
race).
Accepts the entity's ID or URN.
023-app-shape US2 — user-level uninstall. The currently-logged-in user
leaves an App. Idempotent (no-op when not a member). The user's
personal-class Memory at (appId, userId) is NOT cascade-deleted
per spec 008 FR-015 — it re-attaches if the user later re-joins.
Accepts the entity's ID or URN.
023-app-shape US3 — asymmetric cross-user grant on a personal-class
Memory. The principal (memory.userId) grants a grantee read or
write access. Used for the per-pairing pattern (Alice's
paired-with-Mentor-A memory is distinct from her
paired-with-Mentor-B memory; each gets its own MemoryShare).
Upsert semantics: re-calling with a different role on an existing
(memoryId, granteeId) pair updates the role rather than throwing.
For v1 the caller MUST be the principal themselves (memory.userId
=== ctx.userId). The Agent-mediated path (App backend acting on
the principal's behalf via MCP) is supported by the access-control
predicate but not by this GraphQL surface — see the deferred
policy discussion linked from joinApp.ts.
Error codes (extensions.code, Error.name style):
- UNAUTHENTICATED — no logged-in user in context.
- FORBIDDEN — caller is not the Memory's principal. The
caller-authority guard runs first and deliberately does not
differentiate between "memory doesn't exist", "memory is not
personal-class", and "caller isn't the principal" — all three
return FORBIDDEN so memory metadata isn't leaked to
non-principals.
- MemoryShareGranteeMissingError — granteeId doesn't resolve to
an existing User. Only reachable when the caller passes the
principal guard.
- InvalidMemoryClassForShareError / MemoryNotFoundForShareError —
defined on the controller for completeness; functionally
unreachable via this GraphQL mutation in v1 because the
caller-authority guard short-circuits to FORBIDDEN first.
023-app-shape US3 — revoke a MemoryShare. Per FR-022, revocation
takes effect on the next read (there's no "deactivated" state;
just a row delete). Idempotent.
Caller-authority rule matches createMemoryShare.
023-app-shape US3 — change the role on an existing MemoryShare.
Throws MemoryShareNotFoundError if the (memoryId, granteeId) row
doesn't exist — use createMemoryShare to upsert.
Caller-authority rule matches createMemoryShare.
023-app-shape US4 — add a team member to a group-class Memory.
Idempotent on the (memoryId, userId) PK: re-calling with a
different role upserts the role.
The caller MUST be an owner of the Memory (role = owner). The
bootstrap case is handled by createMemory itself, which adds the
creator as the first owner of a newly-created group memory.
Error codes (extensions.code, Error.name style):
- UNAUTHENTICATED — no logged-in user in context.
- FORBIDDEN — caller is not an owner of the memory. (Uniform
for missing-memory / wrong-class / not-an-owner cases, by
the same don't-leak-metadata rule as MemoryShare mutations.)
- InvalidMemoryClassForMemberError — memory is not group-class
(only reachable from non-GraphQL callers in v1 — the
caller-authority guard short-circuits to FORBIDDEN first).
- MemoryMemberUserMissingError — the userId doesn't resolve.
- LastOwnerProtectedError (FR-038) — reachable via the
idempotent upsert path when the call would demote an
existing sole owner to reader/writer.
023-app-shape US4 — change the role on an existing team member.
Throws MemoryMemberNotFoundError when the row doesn't exist;
use addMemoryMember to upsert. Throws LastOwnerProtectedError
(FR-038) when demoting the sole remaining owner.
Caller-authority rule matches addMemoryMember.
Error codes (extensions.code, Error.name style):
- UNAUTHENTICATED — no logged-in user in context.
- FORBIDDEN — caller is not an owner of a live group memory.
- MemoryNotFoundForMemberError — memory absent or soft-deleted
(only reachable from non-GraphQL callers in v1 — the guard
short-circuits to FORBIDDEN first).
- InvalidMemoryClassForMemberError — memory is not group-class
(same; guard short-circuits to FORBIDDEN first).
- MemoryMemberNotFoundError — no row at (memoryId, userId).
- LastOwnerProtectedError (FR-038) — would demote the sole owner.
023-app-shape US4 — remove a team member. Idempotent. Removing
the LAST owner is rejected with LastOwnerProtectedError (FR-038)
— group memories must always have ≥1 owner; the path to fully
empty one is to delete the Memory.
Removing the last non-owner does NOT delete the Memory (FR-031);
the row persists with its remaining owner(s).
Caller-authority: either an owner of the Memory, or the member
being removed (self-removal).
Publish a dependency edge from a parent Agent to an imported Agent
(008-agent-installation FR-005). v1 supports 1-level imports only:
the imported Agent must not itself be a parent of any other import.
Authorization: ADMIN/OWNER of the parent Agent's owning org. The
parent's owning org MUST hold an active AgentOrgGrant for the
imported Agent — bundling requires the same kind of license that
installation does.
Accepts the entity's ID or URN for both Agent ids.
Delete a dependency edge between two Agents. Idempotent (no-op when
the row doesn't exist). Apps that already installed the imported
Agent are unaffected; removing the import only stops *future*
parent installs from cascading the dep.
Accepts the entity's ID or URN.
025-oauth-for-mcp FR-004: mint a new user-scoped API key for the
calling User. Returns the raw key exactly once (the server stores
only the SHA-256 hash). Rejected with UNAUTHENTICATED for AppKey-
resolved callers (no user in context). Per Clarifications, label
is optional (portal defaults to a placeholder when omitted).
025-oauth-for-mcp FR-004: revoke a user-scoped API key owned by
the calling User. Returns the updated UserApiKey so the portal
can render the new revokedAt without a refetch (PR-137 review
delta D3 — was Boolean). Idempotent for already-revoked keys;
rejected with FORBIDDEN if the key belongs to another user;
NOT_FOUND if id does not exist; UNAUTHENTICATED for AppKey-
resolved callers.
005-agent-subscription FR-023 + FR-028 + FR-029: revoke a user's
AgentSubscription. Authorized for ADMIN/OWNER of the Agent's owning
org. Side effect: empty personal Memory of (user, agent) is hard-
deleted; non-empty is retained with userMemoryOfAgentId preserved.
Accepts the entity's ID or URN (agentId).
Link an anonymous memory to a real user (converts session memory
ownership). Providing dataKey encrypts the memory in place atomically
with the link.
Accepts the entity's ID or URN.
Convert an existing plaintext memory to an encrypted one. The caller
provides the data key; all existing node content/data is re-written
as ciphertext in a single transaction.
Accepts the entity's ID or URN.
Apps that have this Agent installed (via the AppAgent join). After
spec 023-app-shape, an App can install multiple Agents; this list
contains every App where THIS Agent is one of the installed ones.
Resolvable to ADMIN/OWNER of the Agent's owning org; non-admins
see an empty list.
023-app-shape: the AppAgent join rows where this Agent is installed.
Use App.appAgents to get the join rows from the App side. Resolvable
to ADMIN/OWNER of the Agent's owning org.
036-ai-service-config: a named AI service configuration (masked
management view — never carries key material beyond the preview).
Owned by exactly one of HadronServer / Organization / App / Agent.
Resolution walks App -> Agent -> Org (of the App) -> HadronServer and
returns the first ENABLED config with the requested name. Well-known
fallback name: 'default' (conventional extras: 'fast', 'frontier').
Name is unique per owner.
Spec 021 US1: the R2 canonical install URN combining the App's
identity with its installed Agent's author-org and slug. Format is
hrn:agent::::::.
Two orgs installing same-slug agents from different authors produce
distinct URNs that differ at the author-org segment, enabling
audit-log entries to identify each install unambiguously without a
PK disambiguator. Returns null when the App has no agent attached
(orphan apps from the 008 cutover; new apps require an agentId per
009).
023-app-shape US1: Agents installed in this App, via the AppAgent
N:M join. Multiple Agents can be installed; one App credential
routes to all of them via the URN supplied in the request.
023-app-shape: convenience that returns every installed Agent
(equivalent to App.appAgents.map(aa => aa.agent)). Previously was
a soft-deprecated single-element synthesis; now returns the FULL
multi-Agent set per spec 023 US1.
023-app-shape US1: the App↔Agent N:M join. Reintroduced after spec 008
collapsed it; per FR-003 it carries NO role column (system memory is
read-only to every App) and per FR-001 it carries NO trainingMode
column (training mode is per-App, on App.trainingMode).
023-app-shape US2: true when this User is an AppMember of the App
but NOT an OrgMember of the App's owning Organization. Derived at
query time from the absence of an OrgMember row (per spec 023
FR-011 — no appOnly column is added to the AppMember table).
Unlocks the B2C / therapy / consumer use cases where end-users
use an App without joining the operator's org.
Integer-as-string OR the sentinel 'unlimited'. GraphQL does not have an
Int|String union; clients parse: parseInt(maxMembers) succeeds for
integer values; 'unlimited' is the sentinel.
Return shape for the joinApp mutation (023-app-shape US2). The
AppMember row is included so callers can read its derived
isOrgExternal flag without a re-query.
Return shape for the leaveApp mutation (023-app-shape US2). The
user's personal-class Memory at (appId, userId) is NOT
cascade-deleted (spec 008 FR-015 orphan retention); it re-attaches
if the user later re-joins the same App.
Spec 033 US2 — force the fixed-size chunking strategy, bypassing the
structure-aware default. Useful when the content's heading structure
is unreliable (e.g. transcripts, machine-generated reports).
Spec 033 FR-026 — timestamp at which the memory owner accepted the
encrypted-memory vector-inversion disclosure. Set when the caller
passes acknowledgeVectorInversionRisk: true on updateMemory for an
isEncrypted: true memory enabling vectorIndexEnabled for the first
time. The portal surfaces this readback so the user can confirm
when they accepted the tradeoff (the disclosure text is the
FR_026_DISCLOSURE constant in src/lib/entityRef/errors.ts).
Survives a revoke + re-enable cycle (never cleared). Null for
unencrypted memories and for encrypted memories where the index
was never enabled.
023-app-shape US3: cross-user grants on this memory. Non-empty
only when class = personal (FR-018). Includes grantee + role for
each row. Visible only to the principal (memory.userId) and to
ADMIN/OWNER of the memory's owning org.
023-app-shape US4: team membership rows on this memory. Non-empty
only when class = group (FR-027). Visible to any current member
(any role) and to ADMIN/OWNER of the memory's owning org.
023-app-shape US4: symmetric team-membership row for group-class
memory. The "Company Brain" model — multiple users collaboratively
read/write a shared memory, governance by role, no single owner
on the Memory itself.
023-app-shape US3: asymmetric cross-user grant on a personal-class
Memory. The principal (memory.userId) grants a grantee read/write
access. Used for per-pairing isolation patterns (e.g., Alice's
personal Memory paired-with-Mentor-A is distinct from her
paired-with-Mentor-B Memory, each with its own MemoryShare).
The principal of the Memory (Memory.userId). Per spec 023 FR-019
this is always the principal, even when an App backend made the
API call on the principal's behalf — that actor is recorded in
createdBy instead.
Paragraph-length summary of this node. Opt-in on h-read-node via the contentScope parameter. h-find-nodes preview surfacing ships in spec 031 US2 — not yet live. Never surfaced in h-list-nodes. Cap is 2000 characters; longer values are rejected with NodeAbstractTooLongError. Empty + whitespace-only values normalize to null. Spec 031.
Spec 032 — fingerprint of the content value at the time abstract was authored. SHA-256 of plaintext content, truncated to 8 hex chars. Compared at read time against computeContentHash(node.content) to detect staleness; when the two values differ AND abstractOriginHash is non-null, the abstract may not reflect current content. System-managed; never settable via NodeInput.
Spec 033 FR-006/FR-007 — set when this node needs (re-)embedding;
cleared on success. The single work signal the embedding worker
drains. Operational state (never versioned on NodeVersion). The
portal renders this as a subtle "embedding…" badge so a user who
just edited isn't confused that their change "didn't take" in
search yet. System-managed.
Spec 033 FR-009 — set when an embed attempt failed (record, not a
work signal). Transient failures keep embeddingPendingAt set for
retry; permanent failures clear it. The portal renders this as a
red badge with the embeddingError message inline so users with an
empty index can distinguish "nothing matched" from "every embed
failed". System-managed.
Spec 033 — last embed error message (diagnosability; also surfaced
by h-validate). Common values: encrypted-no-plaintext (#206),
embedding-endpoint-unreachable, dimension-mismatch. Null when no
failure has been recorded since the most recent success or revoke.
System-managed.
Spec 033 — attempt counter for backoff / give-up. Resets to 0 on
success or revoke. Surfaced for ops diagnostics (a node stuck at a
high attempt count likely needs operator attention). System-managed.
Envelope for nodeSearch — carries the ranked nodes plus structured
flags surfacing degraded / no-index outcomes that the MCP path emits
inline. Spec 033.
reason: set when the query could not run as requested (e.g.
'no_vector_index' on a non-indexed memory with mode:vector); nodes
is empty in that case.
degraded: set when the query ran but at reduced fidelity (e.g.
'no_vector_index' on a hybrid query that fell back to keyword-only);
nodes still carries usable hits.
Spec 033 US2 — populated when the query specified granularity:chunk on a
content-chunk-bearing memory. Each entry is a passage (chunk text +
character offsets + chunk index + parent node URN), ranked by best
similarity. Empty list when granularity:node (default) — the ranked
nodes are in \`nodes\`.
Spec 033 US2 — one matching chunk from a content-chunk vector index.
Carries the locator metadata a RAG consumer needs for context-stuffing:
span text, character offset within the parent node, chunk index, and
the parent node's URN.
036-ai-service-config: privileged resolution result. Carries the
DECRYPTED key — only returned by resolveAIConfig (org ADMIN of the
effective context org, or platform ADMIN/OWNER); successor to
agentAIConfig / appAIConfig.
Return shape for the uninstallAgentFromApp mutation. The Agent's
per-(App, Agent, *) memories are NOT cascade-deleted (spec 023 FR-005);
they persist as orphans on the now-removed AppAgent edge.
Result of resolving a Hadron URN to the ids a client needs to navigate to
the resource's canonical page. Powers the portal's /app/u/ redirect
route (hadron-portal#262).
`kind` is the URN's type segment: memory | node | agent | org | app.
`id` is the resolved entity's primary id. `memoryId` is set only for
nodes (their owning memory), `organizationId` only for apps (their owning
org) — both are the extra ids those resources' canonical routes require.
Memory reference. Accepts the entity's ID (CUID / 32-char hex) or its
URN (per spec 007 ID-or-URN dispatch). URN inputs MUST be fully
qualified (org:memory) per spec 022 — relative-form URNs are
rejected as GraphQL errors with extensions.code "URN_NOT_QUALIFIED".
Reference to the target node. Accepts a node ID, a full URN
(hrn:node:::), a memory-prefixed loc
(:), or a short loc resolved within the source
node's memory.
Memory reference. Accepts the entity's ID (CUID / 32-char hex) or its
URN (per spec 007 ID-or-URN dispatch). URN inputs MUST be fully
qualified (org:memory) per spec 022 — relative-form URNs are
rejected as GraphQL errors with extensions.code "URN_NOT_QUALIFIED".
Paragraph-length summary of this node — see Node.abstract for the surfacing contract (h-read-node opt-in via contentScope; h-find-nodes preview ships in US2). Optional. Omit to preserve; null to clear; string to replace. Empty + whitespace-only normalize to null. Cap is 2000 characters.
Agent reference. Accepts the entity's ID (CUID / 32-char hex) or its
URN (per spec 007 ID-or-URN dispatch). URN inputs MUST be fully
qualified (org:agent) per spec 022 — relative-form URNs are rejected
as GraphQL errors with extensions.code "URN_NOT_QUALIFIED".
023-app-shape US4: team-shared memory with symmetric membership.
Governed by a list of MemoryMember rows (each with reader/writer/
owner role) — no single owner field on Memory. Closes the
Company Brain gap that wasn't covered by the four legacy classes.
private
Single-owner, owner-only memory — no MemoryShare path (not
shareable), no ADMIN/OWNER bypass. Spec 034 (hadron-server #242)
made it user-creatable via createMemory: free-standing (no
app/agent) or app-scoped. May opt into encrypt-at-rest
(the private CLASS marks it; visibility is NULL), but the encryption
implementation itself is a deferred follow-up — do NOT rely on
at-rest encryption for secret material yet.
023-app-shape US4: role on a MemoryMember row. Symmetric team
membership for group-class memory.
- reader: read access.
- writer: read + write (the member can add/edit/delete nodes
within the memory).
- owner: read + write + management — add/remove other members,
change roles, delete the Memory itself. Subject to the
last-owner protection rule (FR-038): the platform refuses
to remove or demote the sole remaining owner; the path to
fully empty a group memory is to delete it.
023-app-shape US3: role on a MemoryShare row. Asymmetric grant
for personal-class memory.
- reader: read access only.
- writer: read + write (the grantee can add/edit/delete nodes
within the memory).
035-visibility-enum-cleanup: meaningful only for knowledge
(PUBLIC/ORGANIZATION) and group (GROUP); null otherwise. PERSONAL/PRIVATE
were dropped — privacy is the personal/private memory CLASS now.
Value
Description
PUBLIC
ORGANIZATION
GROUP
023-app-shape US4: team-shared visibility. Bound bidirectionally
to MemoryClass.group by the chk_memory_group_visibility CHECK
constraint — a memory has class=group iff visibility=GROUP.
The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.
The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.