Admin

Methods on this page are called as client.admin.<method>(...) where client is either a synchronous Goodmem or asynchronous AsyncGoodmem instance initialized below:

from goodmem import Goodmem
client = Goodmem(base_url='http://localhost:8080', api_key='gm_...')

from goodmem import AsyncGoodmem
client = AsyncGoodmem(base_url='http://localhost:8080', api_key='gm_...')

Request the server to enter drain mode

admin.drain(*, reason: str = None, timeout_sec: int = None, wait_for_quiesce: bool = None) → AdminDrainResponse

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

Parameters:

• reason (str, optional) — Human-readable reason for initiating drain mode.
• timeout_sec (int, format: int32, optional, server default=900) — Maximum seconds to wait for the server to quiesce before returning.
• wait_for_quiesce (bool, optional) — If true, wait for in-flight requests to complete and the server to reach QUIESCED before responding.

Returns:

AdminDrainResponse — Returns the drain status.

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

result = client.admin.drain(timeout_sec=0)
print(f"State: {result.state}, Quiesced: {result.quiesced}")

Transfer GoodMem instance ownership

admin.transfer_instance_ownership(*, new_owner_id: str) → TransferInstanceOwnershipResponse

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.

Parameters:

• new_owner_id (str, format: uuid) — Existing principal UUID that will become the new owner.

Returns:

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

transferred_instance = client.admin.transfer_instance_ownership(
    new_owner_id=principal_id
)

Purge completed background jobs

admin.background_jobs.purge(*, older_than: str, dry_run: bool = None, limit: int = None, statuses: list[PurgeableBackgroundJobStatus] = None) → AdminPurgeJobsResponse

Deletes terminal background jobs older than a retention cutoff.

Parameters:

• older_than (str, format: date-time) — ISO-8601 timestamp cutoff; only terminal jobs older than this instant are eligible.
• dry_run (bool, optional) — If true, report purge counts without deleting any rows.
• limit (int, format: int32, optional) — Maximum number of jobs to purge in this request. Must be >= 0; 0 means no limit.
• statuses (list[PurgeableBackgroundJobStatus], optional) — 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.

Returns:

AdminPurgeJobsResponse — Returns the count of purged jobs.

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

result = client.admin.background_jobs.purge(older_than="2000-01-01T00:00:00Z", dry_run=True)
print(f"Jobs purged: {result.jobs_purged}")

Reload the active license from disk

admin.license.reload() → AdminReloadLicenseResponse

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

Returns:

AdminReloadLicenseResponse — Returns the reloaded license state.

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

result = client.admin.license.reload()
print(f"License status: {result.status}")

Create a RetrieveMemory log policy

admin.retrieve_memory_log_policies.create(*, condition: RetrieveMemoryLogPolicyCondition, display_name: str, active_from: int = None, active_until: int = None, description: str = None, labels: dict[str, str] = None, policy_id: str = None) → RetrieveMemoryLogPolicy

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

Parameters:

• condition (RetrieveMemoryLogPolicyCondition) — Policy match condition.
• display_name (str) — Human-readable policy name.
• active_from (int, format: int64, optional) — Inclusive activation time in milliseconds since epoch.
• active_until (int, format: int64, optional) — Exclusive deactivation time in milliseconds since epoch.
• description (str, optional) — Optional operator description.
• labels (dict[str, str], optional) — Operator labels for listing and administration.
• policy_id (str, format: uuid, optional) — Optional client-provided policy UUID.

Returns:

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

created = client.admin.retrieve_memory_log_policies.create(
    display_name="audit-doc-example",
    condition=RetrieveMemoryLogPolicyCondition(match_all=True),
)
print(f"Created policy: {created.policy_id}")

Delete a RetrieveMemory log policy

admin.retrieve_memory_log_policies.delete(*, id: str, request: DeleteRetrieveMemoryLogPolicyRequest | dict) → RetrieveMemoryLogPolicy

Idempotently tombstones an immutable RetrieveMemory log policy.

Parameters:

• id (str) — The UUID of the policy to delete
• request (DeleteRetrieveMemoryLogPolicyRequest | dict) — Update payload. Pass a DeleteRetrieveMemoryLogPolicyRequest instance or a plain dict (validated automatically).

Returns:

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

tombstoned = client.admin.retrieve_memory_log_policies.delete(
    id=created.policy_id,
    request={"reason": "doc example cleanup"},
)
print(f"Tombstoned policy: {tombstoned.policy_id}")

Get a RetrieveMemory log policy

admin.retrieve_memory_log_policies.get(*, id: str, include_deleted: bool = None) → RetrieveMemoryLogPolicy

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

Parameters:

• id (str) — The UUID of the policy to retrieve
• include_deleted (bool, optional, server default=False) — Whether to include tombstoned policies. Also accepts include_deleted.

Returns:

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

fetched = client.admin.retrieve_memory_log_policies.get(id=created.policy_id)
print(f"Fetched: {fetched.display_name}")

List RetrieveMemory log policies

admin.retrieve_memory_log_policies.list(*, active_at: int = None, include_deleted: bool = None, label: dict[str, str] = None, max_results: int = None, name_filter: str = None, next_token: str = None, sort_by: str = None, sort_order: SortOrder = None) → ListRetrieveMemoryLogPoliciesResponse

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).

Parameters:

• active_at (int, format: int64, optional) — Only return policies active at this millisecond epoch timestamp. Also accepts active_at.
• include_deleted (bool, optional, server default=False) — Whether to include tombstoned policies. Also accepts include_deleted.
• label (dict[str, str], optional) — Filter by label key-value pairs. Label filters accept either label.<key>=<value> or label[key]=value (for example, label.environment=production or label[environment]=production).
• max_results (int, format: int32, optional, server default=50) — Maximum number of policies to return. Also accepts max_results.
• name_filter (str, optional) — Case-insensitive substring filter on policy display names. Also accepts name_filter.
• next_token (str, optional) — Opaque pagination token returned by the previous list response. Also accepts next_token.
• sort_by (str, optional, server default='created_at') — Sort field: created_at, updated_at, or display_name. Also accepts sort_by.
• sort_order (SortOrder, optional, server default='DESCENDING') — Sort order. Also accepts sort_order.

Returns:

Raises:

• APIError — Any other non-2xx HTTP response (base class; exposes status_code and body).

Example

page = client.admin.retrieve_memory_log_policies.list(max_results=10)
for policy in page:
    print(policy.display_name)

Async usage: client.admin exposes the same methods on AsyncGoodmem; use await / async for as needed.

Data Models

All data models are pydantic v2 models. Fields are shown with their Python attribute names; JSON responses use camelCase aliases (e.g., owner_id → ownerId).

AdminDrainResponse

AdminDrainResponse

• state (Literal['STARTING', 'READY', 'DRAINING', 'QUIESCED'], optional) — Lifecycle state reported after the drain request was processed.
• quiesced (bool) — Whether the server has reached the QUIESCED lifecycle state.
• message (str, optional) — Human-readable status message describing the drain outcome.

TransferInstanceOwnershipResponse

The singleton GoodMem instance after its ownership transfer completes.

• instance (GoodMemInstance) — Updated singleton instance and ownership audit metadata.

PurgeableBackgroundJobStatus

String enum: "BACKGROUND_JOB_SUCCEEDED" · "BACKGROUND_JOB_FAILED" · "BACKGROUND_JOB_CANCELED"

AdminPurgeJobsResponse

AdminPurgeJobsResponse

• jobs_purged (int) — Number of background job rows removed, or that would be removed during dry-run.
• attempts_purged (int) — Number of background job attempt rows removed.
• references_purged (int) — Number of background job reference rows removed.
• dry_run (bool) — Whether the purge executed in dry-run mode.

AdminReloadLicenseResponse

AdminReloadLicenseResponse

• status (Optional[Literal['LOADED', 'UNCHANGED', 'FAILED', 'NOT_FOUND']]) — Outcome of the reload attempt, such as LOADED, UNCHANGED, FAILED, or NOT_FOUND.
• message (str) — Human-readable message describing the reload result.
• active_license (ActiveLicenseMetadata, optional) — Metadata for the currently active license after reload, or null if no license is active.

ActiveLicenseMetadata

ActiveLicenseMetadata

• filename (str) — Filename of the active license on disk.
• sha256 (str) — Hex-encoded SHA-256 hash of the active license file.
• size_bytes (int) — Size of the active license file in bytes.
• modified_at (str) — Last modification timestamp of the active license file.

RetrieveMemoryLogPolicyCondition

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

• match_all (bool, optional) — When true, match every authenticated RetrieveMemory request. Must be omitted or false when any_of contains clauses. Defaults to false when omitted.
• any_of (list[RetrieveMemoryLogPolicyConditionClause], optional) — OR clauses used for scoped matching. Required and non-empty when match_all is false or omitted. Must be omitted or empty when match_all 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.

• requestor_user_ids (list[str], optional) — Authenticated requestor user UUID strings.
• api_key_ids (list[str], optional) — API key UUID strings used to authenticate RetrieveMemory requests.
• space_ids (list[str], optional) — Post-permission accessible space UUID strings.
• api_key_label_selectors (dict[str, str], optional) — Exact API-key label selectors that must all match.
• space_label_selectors (dict[str, str], optional) — Exact space label selectors that must match at least one accessible space.

RetrieveMemoryLogPolicy

REST representation of an immutable RetrieveMemory log policy.

• policy_id (str) — Policy UUID.
• display_name (str) — Human-readable policy name.
• description (str, optional) — Optional operator description.
• condition (RetrieveMemoryLogPolicyCondition) — Policy match condition.
• active_from (int) — Inclusive activation time in milliseconds since epoch.
• active_until (int, optional) — Exclusive deactivation time in milliseconds since epoch.
• labels (dict[str, str]) — Operator labels for listing and administration.
• currently_active (bool) — Whether the policy is active at response evaluation time.
• deleted_at (int, optional) — Tombstone time in milliseconds since epoch.
• deleted_by_id (str, optional) — User UUID that tombstoned the policy.
• delete_reason (str, optional) — Optional tombstone reason.
• created_at (int) — Creation time in milliseconds since epoch.
• updated_at (int) — Update time in milliseconds since epoch.
• created_by_id (str) — Creator user UUID.
• updated_by_id (str) — Last-updater user UUID.

DeleteRetrieveMemoryLogPolicyRequest

Optional REST body for tombstoning a RetrieveMemory log policy.

• reason (str, optional) — Optional tombstone reason.

ListRetrieveMemoryLogPoliciesResponse

REST response containing a page of RetrieveMemory log policies.

• policies (list[RetrieveMemoryLogPolicy]) — Policy page.
• next_token (str, optional) — Opaque token for the next page.