GoodMemAdmin
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);
}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. |
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. |