Admin

Server lifecycle operations.

Methods on this page are called through client.admin.

client.admin.backgroundJobsPurge

client.admin.backgroundJobsPurge(request: AdminPurgeJobsRequest, requestOptions?: RequestOptions): Promise<AdminPurgeJobsResponseShape>

Deletes terminal background jobs older than a retention cutoff.

HTTP: POST /v1/admin/background-jobs:purge

Parameters

Parameter	Type	Description
`request`	`AdminPurgeJobsRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<AdminPurgeJobsResponseShape>

Example

const purge = await client.admin.backgroundJobsPurge({
  olderThan: "2026-01-01T00:00:00Z",
  dryRun: true,
});
console.log(purge.jobsPurged);

client.admin.drain

client.admin.drain(request: AdminDrainRequest, requestOptions?: RequestOptions): Promise<AdminDrainResponseShape>

Initiates drain mode and optionally waits for the server to quiesce.

HTTP: POST /v1/admin:drain

Parameters

Parameter	Type	Description
`request`	`AdminDrainRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<AdminDrainResponseShape>

Example

const drain = await client.admin.drain({
  reason: "maintenance",
  waitForQuiesce: false,
});
console.log(drain.state);

client.admin.licenseReload

client.admin.licenseReload(requestOptions?: RequestOptions): Promise<AdminReloadLicenseResponseShape>

Triggers the server to reload its license file from the configured directory and returns metadata about the currently active license.

HTTP: POST /v1/admin/license:reload

Parameters

Parameter	Type	Description
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<AdminReloadLicenseResponseShape>

Example

const license = await client.admin.licenseReload();
console.log(license.status);

client.admin.retrieveMemoryLogPoliciesCreate

client.admin.retrieveMemoryLogPoliciesCreate(request: CreateRetrieveMemoryLogPolicyRequest, requestOptions?: RequestOptions): Promise<RetrieveMemoryLogPolicyResponseShape>

Creates an immutable administrative policy that can automatically enable durable RetrieveMemory request logging.

HTTP: POST /v1/admin/retrieve-memory-log-policies

Parameters

Parameter	Type	Description
`request`	`CreateRetrieveMemoryLogPolicyRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<RetrieveMemoryLogPolicyResponseShape>

Example

const policy = await client.admin.retrieveMemoryLogPoliciesCreate({
  displayName: "Log all retrieve requests",
  condition: { matchAll: true },
  labels: { env: "docs" },
});

client.admin.retrieveMemoryLogPoliciesDelete

client.admin.retrieveMemoryLogPoliciesDelete(id: string, request: DeleteRetrieveMemoryLogPolicyRequest, requestOptions?: RequestOptions): Promise<RetrieveMemoryLogPolicyResponseShape>

Idempotently tombstones an immutable RetrieveMemory log policy.

HTTP: DELETE /v1/admin/retrieve-memory-log-policies/{id}

Parameters

Parameter	Type	Description
`id`	`string`	The UUID of the policy to delete
`request`	`DeleteRetrieveMemoryLogPolicyRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<RetrieveMemoryLogPolicyResponseShape>

Example

await client.admin.retrieveMemoryLogPoliciesDelete("your-policy-id", {
  reason: "No longer needed",
});

client.admin.retrieveMemoryLogPoliciesGet

client.admin.retrieveMemoryLogPoliciesGet(id: string, options?: AdminRetrieveMemoryLogPoliciesGetOptions, requestOptions?: RequestOptions): Promise<RetrieveMemoryLogPolicyResponseShape>

Retrieves a live RetrieveMemory log policy by UUID, or a tombstoned policy when includeDeleted is true.

HTTP: GET /v1/admin/retrieve-memory-log-policies/{id}

Parameters

Parameter	Type	Description
`id`	`string`	The UUID of the policy to retrieve
`options`	`AdminRetrieveMemoryLogPoliciesGetOptions` optional	Optional query parameters.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<RetrieveMemoryLogPolicyResponseShape>

Example

const fetchedPolicy = await client.admin.retrieveMemoryLogPoliciesGet("your-policy-id", {
  includeDeleted: false,
});
console.log(fetchedPolicy.displayName);

client.admin.retrieveMemoryLogPoliciesList

client.admin.retrieveMemoryLogPoliciesList(options?: AdminRetrieveMemoryLogPoliciesListOptions, requestOptions?: RequestOptions): Promise<Page<RetrieveMemoryLogPolicyResponseShape>>

Lists RetrieveMemory log policies with optional tombstone, active-time, name, label, sort, and pagination filters. LABEL FILTERS: Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).

HTTP: GET /v1/admin/retrieve-memory-log-policies

Parameters

Parameter	Type	Description
`options`	`AdminRetrieveMemoryLogPoliciesListOptions` optional	Optional query parameters.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<Page<RetrieveMemoryLogPolicyResponseShape>>

Example

for await (const item of await client.admin.retrieveMemoryLogPoliciesList({ maxResults: 10 })) {
  console.log(item.policyId, item.displayName);
}

client.admin.transferInstanceOwnership

client.admin.transferInstanceOwnership(request: TransferOwnershipRequest, requestOptions?: RequestOptions): Promise<TransferInstanceOwnershipResponseShape>

Transfers the singleton GoodMem instance to another active human principal. Only the current instance owner may invoke this operation; ADMIN, MANAGE_ACCESS, and ordinary grants are insufficient. Ownership and the synthetic ROOT assignment move atomically. All ordinary roles, including ADMIN, remain unchanged. No credential is created or returned. After an unknown outcome, read the current owner before retrying.

HTTP: POST /v1/admin:transferInstanceOwnership

Parameters

Parameter	Type	Description
`request`	`TransferOwnershipRequest`	Request body.
`requestOptions`	`RequestOptions` optional	Per-call signal, timeout, or headers.

Returns: Promise<TransferInstanceOwnershipResponseShape>

Example

const transferredInstance = await client.admin.transferInstanceOwnership({
  newOwnerId: principalId,
});

Data Models

Enum Values

PurgeableBackgroundJobStatus

BACKGROUND_JOB_SUCCEEDED, BACKGROUND_JOB_FAILED, BACKGROUND_JOB_CANCELED

Interfaces

ActiveLicenseMetadata

Field	Type	Required	Description
`filename`	`string`	yes	Filename of the active license on disk.
`sha256`	`string`	yes	Hex-encoded SHA-256 hash of the active license file.
`sizeBytes`	`number`	yes	Size of the active license file in bytes.
`modifiedAt`	`string`	yes	Last modification timestamp of the active license file.

AdminDrainRequest

Field	Type	Required	Description
`timeoutSec`	`number \| null`	no	Maximum seconds to wait for the server to quiesce before returning.
`reason`	`string \| null`	no	Human-readable reason for initiating drain mode.
`waitForQuiesce`	`boolean \| null`	no	If true, wait for in-flight requests to complete and the server to reach QUIESCED before responding.

AdminDrainResponse

Field	Type	Required	Description
`state`	`"STARTING" \| "READY" \| "DRAINING" \| "QUIESCED"`	no	Lifecycle state reported after the drain request was processed.
`quiesced`	`boolean`	yes	Whether the server has reached the QUIESCED lifecycle state.
`message`	`string`	no	Human-readable status message describing the drain outcome.

AdminPurgeJobsRequest

Field	Type	Required	Description
`olderThan`	`string`	yes	ISO-8601 timestamp cutoff; only terminal jobs older than this instant are eligible.
`statuses`	`Array<PurgeableBackgroundJobStatus>`	no	Optional terminal background job statuses to target for purging. If omitted, all terminal statuses are eligible. Canonical values are BACKGROUND_JOB_SUCCEEDED, BACKGROUND_JOB_FAILED, and BACKGROUND_JOB_CANCELED. Short aliases SUCCEEDED, FAILED, and CANCELED are also accepted for compatibility.
`dryRun`	`boolean`	no	If true, report purge counts without deleting any rows.
`limit`	`number`	no	Maximum number of jobs to purge in this request. Must be >= 0; 0 means no limit.

AdminPurgeJobsResponse

Field	Type	Required	Description
`jobsPurged`	`number`	yes	Number of background job rows removed, or that would be removed during dry-run.
`attemptsPurged`	`number`	yes	Number of background job attempt rows removed.
`referencesPurged`	`number`	yes	Number of background job reference rows removed.
`dryRun`	`boolean`	yes	Whether the purge executed in dry-run mode.

AdminReloadLicenseResponse

Field	Type	Required	Description
`status`	`"LOADED" \| "UNCHANGED" \| "FAILED" \| "NOT_FOUND"`	yes	Outcome of the reload attempt, such as LOADED, UNCHANGED, FAILED, or NOT_FOUND.
`message`	`string`	yes	Human-readable message describing the reload result.
`activeLicense`	`ActiveLicenseMetadata`	no	Metadata for the currently active license after reload, or null if no license is active.

CreateRetrieveMemoryLogPolicyRequest

REST request for creating an immutable RetrieveMemory log policy.

Field	Type	Required	Description
`policyId`	`string \| null`	no	Optional client-provided policy UUID.
`displayName`	`string`	yes	Human-readable policy name.
`description`	`string \| null`	no	Optional operator description.
`condition`	`RetrieveMemoryLogPolicyCondition`	yes	Policy match condition.
`activeFrom`	`number \| null`	no	Inclusive activation time in milliseconds since epoch.
`activeUntil`	`number \| null`	no	Exclusive deactivation time in milliseconds since epoch.
`labels`	`Record<string, string> \| null`	no	Operator labels for listing and administration.

DeleteRetrieveMemoryLogPolicyRequest

Optional REST body for tombstoning a RetrieveMemory log policy.

Field	Type	Required	Description
`reason`	`string \| null`	no	Optional tombstone reason.

ListRetrieveMemoryLogPoliciesResponse

REST response containing a page of RetrieveMemory log policies.

Field	Type	Required	Description
`policies`	`Array<RetrieveMemoryLogPolicy>`	yes	Policy page.
`nextToken`	`string \| null`	no	Opaque token for the next page.

RetrieveMemoryLogPolicy

REST representation of an immutable RetrieveMemory log policy.

Field	Type	Required	Description
`policyId`	`string`	yes	Policy UUID.
`displayName`	`string`	yes	Human-readable policy name.
`description`	`string \| null`	no	Optional operator description.
`condition`	`RetrieveMemoryLogPolicyCondition`	yes	Policy match condition.
`activeFrom`	`number`	yes	Inclusive activation time in milliseconds since epoch.
`activeUntil`	`number \| null`	no	Exclusive deactivation time in milliseconds since epoch.
`labels`	`Record<string, string>`	yes	Operator labels for listing and administration.
`currentlyActive`	`boolean`	yes	Whether the policy is active at response evaluation time.
`deletedAt`	`number \| null`	no	Tombstone time in milliseconds since epoch.
`deletedById`	`string \| null`	no	User UUID that tombstoned the policy.
`deleteReason`	`string \| null`	no	Optional tombstone reason.
`createdAt`	`number`	yes	Creation time in milliseconds since epoch.
`updatedAt`	`number`	yes	Update time in milliseconds since epoch.
`createdById`	`string`	yes	Creator user UUID.
`updatedById`	`string`	yes	Last-updater user UUID.

RetrieveMemoryLogPolicyCondition

RetrieveMemory log policy condition. Set matchAll=true to match every authenticated RetrieveMemory request and do not provide anyOf clauses. Otherwise, anyOf is required and must contain at least one non-empty scoped clause.

Field	Type	Required	Description
`matchAll`	`boolean \| null`	no	When true, match every authenticated RetrieveMemory request. Must be omitted or false when anyOf contains clauses. Defaults to false when omitted.
`anyOf`	`Array<RetrieveMemoryLogPolicyConditionClause> \| null`	no	OR clauses used for scoped matching. Required and non-empty when matchAll is false or omitted. Must be omitted or empty when matchAll is true. Each clause must include at least one match dimension.

RetrieveMemoryLogPolicyConditionClause

One OR clause in a RetrieveMemory log policy condition. All populated dimensions in the clause must match; clauses are ORed together.

Field	Type	Required	Description
`requestorUserIds`	`Array<string> \| null`	no	Authenticated requestor user UUID strings.
`apiKeyIds`	`Array<string> \| null`	no	API key UUID strings used to authenticate RetrieveMemory requests.
`spaceIds`	`Array<string> \| null`	no	Post-permission accessible space UUID strings.
`apiKeyLabelSelectors`	`Record<string, string> \| null`	no	Exact API-key label selectors that must all match.
`spaceLabelSelectors`	`Record<string, string> \| null`	no	Exact space label selectors that must match at least one accessible space.

TransferInstanceOwnershipResponse

The singleton GoodMem instance after its ownership transfer completes.

Field	Type	Required	Description
`instance`	`GoodMemInstance`	yes	Updated singleton instance and ownership audit metadata.

Response Shapes

Response shape types model values returned by the SDK after forward-compatible unknown enum strings are coerced to null.

ActiveLicenseMetadataResponseShape

Field	Type	Required	Description
`filename`	`string`	yes	Filename of the active license on disk.
`sha256`	`string`	yes	Hex-encoded SHA-256 hash of the active license file.
`sizeBytes`	`number`	yes	Size of the active license file in bytes.
`modifiedAt`	`string`	yes	Last modification timestamp of the active license file.

AdminDrainResponseShape

Field	Type	Required	Description
`state`	`"STARTING" \| "READY" \| "DRAINING" \| "QUIESCED" \| null`	no	Lifecycle state reported after the drain request was processed.
`quiesced`	`boolean`	yes	Whether the server has reached the QUIESCED lifecycle state.
`message`	`string`	no	Human-readable status message describing the drain outcome.

AdminPurgeJobsResponseShape

Field	Type	Required	Description
`jobsPurged`	`number`	yes	Number of background job rows removed, or that would be removed during dry-run.
`attemptsPurged`	`number`	yes	Number of background job attempt rows removed.
`referencesPurged`	`number`	yes	Number of background job reference rows removed.
`dryRun`	`boolean`	yes	Whether the purge executed in dry-run mode.

AdminReloadLicenseResponseShape

Field	Type	Required	Description
`status`	`"LOADED" \| "UNCHANGED" \| "FAILED" \| "NOT_FOUND" \| null`	yes	Outcome of the reload attempt, such as LOADED, UNCHANGED, FAILED, or NOT_FOUND.
`message`	`string`	yes	Human-readable message describing the reload result.
`activeLicense`	`ActiveLicenseMetadataResponseShape`	no	Metadata for the currently active license after reload, or null if no license is active.

ListRetrieveMemoryLogPoliciesResponseShape

Field	Type	Required	Description
`policies`	`Array<RetrieveMemoryLogPolicyResponseShape>`	yes	Policy page.
`nextToken`	`string \| null`	no	Opaque token for the next page.

RetrieveMemoryLogPolicyResponseShape

Field	Type	Required	Description
`policyId`	`string`	yes	Policy UUID.
`displayName`	`string`	yes	Human-readable policy name.
`description`	`string \| null`	no	Optional operator description.
`condition`	`RetrieveMemoryLogPolicyConditionResponseShape`	yes	Policy match condition.
`activeFrom`	`number`	yes	Inclusive activation time in milliseconds since epoch.
`activeUntil`	`number \| null`	no	Exclusive deactivation time in milliseconds since epoch.
`labels`	`Record<string, string>`	yes	Operator labels for listing and administration.
`currentlyActive`	`boolean`	yes	Whether the policy is active at response evaluation time.
`deletedAt`	`number \| null`	no	Tombstone time in milliseconds since epoch.
`deletedById`	`string \| null`	no	User UUID that tombstoned the policy.
`deleteReason`	`string \| null`	no	Optional tombstone reason.
`createdAt`	`number`	yes	Creation time in milliseconds since epoch.
`updatedAt`	`number`	yes	Update time in milliseconds since epoch.
`createdById`	`string`	yes	Creator user UUID.
`updatedById`	`string`	yes	Last-updater user UUID.

RetrieveMemoryLogPolicyConditionResponseShape

Field	Type	Required	Description
`matchAll`	`boolean \| null`	no	When true, match every authenticated RetrieveMemory request. Must be omitted or false when anyOf contains clauses. Defaults to false when omitted.
`anyOf`	`Array<RetrieveMemoryLogPolicyConditionClauseResponseShape> \| null`	no	OR clauses used for scoped matching. Required and non-empty when matchAll is false or omitted. Must be omitted or empty when matchAll is true. Each clause must include at least one match dimension.

RetrieveMemoryLogPolicyConditionClauseResponseShape

Field	Type	Required	Description
`requestorUserIds`	`Array<string> \| null`	no	Authenticated requestor user UUID strings.
`apiKeyIds`	`Array<string> \| null`	no	API key UUID strings used to authenticate RetrieveMemory requests.
`spaceIds`	`Array<string> \| null`	no	Post-permission accessible space UUID strings.
`apiKeyLabelSelectors`	`Record<string, string> \| null`	no	Exact API-key label selectors that must all match.
`spaceLabelSelectors`	`Record<string, string> \| null`	no	Exact space label selectors that must match at least one accessible space.

TransferInstanceOwnershipResponseShape

Field	Type	Required	Description
`instance`	`GoodMemInstanceResponseShape`	yes	Updated singleton instance and ownership audit metadata.

Admin

On this page