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

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

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

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

Purge completed background jobs

Deletes terminal background jobs older than a retention cutoff.

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

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

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

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

Create a RetrieveMemory log policy

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

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

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

Idempotently tombstones an immutable RetrieveMemory log policy.

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

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

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

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

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

List RetrieveMemory log policies

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

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

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.

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.