TypeScript SDK

Installation

npm install @pairsystems/goodmem

Client

import { Goodmem } from "@pairsystems/goodmem";

const client = new Goodmem({
  baseUrl: "http://localhost:8080",
  apiKey: process.env.GOODMEM_API_KEY,
});

The TypeScript SDK exposes generated namespace clients on client.<namespace>.

Namespace	Accessor	Description
Embedders	`client.embedders`	Embedder management
Rerankers	`client.rerankers`	Reranker management
LLMs	`client.llms`	LLM management
Spaces	`client.spaces`	Memory space management
Memories	`client.memories`	Memory CRUD, retrieval, and batch operations
OCR	`client.ocr`	Document text extraction
System	`client.system`	Server info and initialization
Instance	`client.instance`	Singleton instance identity and ownership
Users	`client.users`	User lookup
Service Identities	`client.service_identities`	Production service identity lifecycle
User Enrollments	`client.user_enrollments`	One-time human-user enrollment completion
Admin	`client.admin`	Server lifecycle operations
Access Policy	`client.access_policy`	Direct grants and scoped role assignments
API Keys	`client.apikeys`	API key lifecycle management
Ping	`client.ping`	Endpoint health probes

Methods

Namespace	Method	Signature	Returns
`embedders`	`create`	`client.embedders.create(request: EmbeddersCreateRequest, requestOptions?: ProviderApiKeyOptions): Promise<EmbedderResponseShape>`	`Promise<EmbedderResponseShape>`
`embedders`	`delete`	`client.embedders.delete(id: string, requestOptions?: RequestOptions): Promise<void>`	`Promise<void>`
`embedders`	`get`	`client.embedders.get(id: string, options?: EmbeddersGetOptions, requestOptions?: RequestOptions): Promise<EmbedderResponseShape>`	`Promise<EmbedderResponseShape>`
`embedders`	`list`	`client.embedders.list(options?: EmbeddersListOptions, requestOptions?: RequestOptions): Promise<Array<EmbedderResponseShape>>`	`Promise<Array<EmbedderResponseShape>>`
`embedders`	`update`	`client.embedders.update(id: string, request: UpdateEmbedderRequest, requestOptions?: RequestOptions): Promise<EmbedderResponseShape>`	`Promise<EmbedderResponseShape>`
`rerankers`	`create`	`client.rerankers.create(request: RerankersCreateRequest, requestOptions?: ProviderApiKeyOptions): Promise<RerankerResponseShape>`	`Promise<RerankerResponseShape>`
`rerankers`	`delete`	`client.rerankers.delete(id: string, requestOptions?: RequestOptions): Promise<void>`	`Promise<void>`
`rerankers`	`get`	`client.rerankers.get(id: string, options?: RerankersGetOptions, requestOptions?: RequestOptions): Promise<RerankerResponseShape>`	`Promise<RerankerResponseShape>`
`rerankers`	`list`	`client.rerankers.list(options?: RerankersListOptions, requestOptions?: RequestOptions): Promise<Array<RerankerResponseShape>>`	`Promise<Array<RerankerResponseShape>>`
`rerankers`	`update`	`client.rerankers.update(id: string, request: UpdateRerankerRequest, requestOptions?: RequestOptions): Promise<RerankerResponseShape>`	`Promise<RerankerResponseShape>`
`llms`	`create`	`client.llms.create(request: LlmsCreateRequest, requestOptions?: ProviderApiKeyOptions): Promise<CreateLLMResponseShape>`	`Promise<CreateLLMResponseShape>`
`llms`	`delete`	`client.llms.delete(id: string, requestOptions?: RequestOptions): Promise<void>`	`Promise<void>`
`llms`	`get`	`client.llms.get(id: string, options?: LlmsGetOptions, requestOptions?: RequestOptions): Promise<LLMResponseShape>`	`Promise<LLMResponseShape>`
`llms`	`list`	`client.llms.list(options?: LlmsListOptions, requestOptions?: RequestOptions): Promise<Array<LLMResponseShape>>`	`Promise<Array<LLMResponseShape>>`
`llms`	`update`	`client.llms.update(id: string, request: LLMUpdateRequest, requestOptions?: RequestOptions): Promise<LLMResponseShape>`	`Promise<LLMResponseShape>`
`spaces`	`create`	`client.spaces.create(request: SpaceCreationRequest, requestOptions?: RequestOptions): Promise<SpaceResponseShape>`	`Promise<SpaceResponseShape>`
`spaces`	`delete`	`client.spaces.delete(id: string, requestOptions?: RequestOptions): Promise<void>`	`Promise<void>`
`spaces`	`get`	`client.spaces.get(id: string, requestOptions?: RequestOptions): Promise<SpaceResponseShape>`	`Promise<SpaceResponseShape>`
`spaces`	`list`	`client.spaces.list(options?: SpacesListOptions, requestOptions?: RequestOptions): Promise<Page<SpaceResponseShape>>`	`Promise<Page<SpaceResponseShape>>`
`spaces`	`transferOwnership`	`client.spaces.transferOwnership(id: string, request: TransferOwnershipRequest, requestOptions?: RequestOptions): Promise<TransferSpaceOwnershipResponseShape>`	`Promise<TransferSpaceOwnershipResponseShape>`
`spaces`	`update`	`client.spaces.update(id: string, request: UpdateSpaceRequest, requestOptions?: RequestOptions): Promise<SpaceResponseShape>`	`Promise<SpaceResponseShape>`
`memories`	`batchCreate`	`client.memories.batchCreate(request: JsonBatchMemoryCreationRequest, requestOptions?: RequestOptions): Promise<BatchMemoryResponseShape>`	`Promise<BatchMemoryResponseShape>`
`memories`	`batchDelete`	`client.memories.batchDelete(request: BatchMemoryDeletionRequest, requestOptions?: RequestOptions): Promise<BatchMemoryResponseShape>`	`Promise<BatchMemoryResponseShape>`
`memories`	`batchGet`	`client.memories.batchGet(request: BatchMemoryRetrievalRequest, requestOptions?: RequestOptions): Promise<BatchMemoryResponseShape>`	`Promise<BatchMemoryResponseShape>`
`memories`	`content`	`client.memories.content(id: string, requestOptions?: RequestOptions): Promise<Uint8Array>`	`Promise<Uint8Array>`
`memories`	`create`	`client.memories.create(request: JsonMemoryCreationRequest, requestOptions?: RequestOptions): Promise<MemoryResponseShape>`	`Promise<MemoryResponseShape>`
`memories`	`delete`	`client.memories.delete(id: string, requestOptions?: RequestOptions): Promise<void>`	`Promise<void>`
`memories`	`get`	`client.memories.get(id: string, options?: MemoriesGetOptions, requestOptions?: RequestOptions): Promise<MemoryResponseShape>`	`Promise<MemoryResponseShape>`
`memories`	`list`	`client.memories.list(spaceId: string, options?: MemoriesListOptions, requestOptions?: RequestOptions): Promise<Page<MemoryResponseShape>>`	`Promise<Page<MemoryResponseShape>>`
`memories`	`pages`	`client.memories.pages(id: string, options?: MemoriesPagesOptions, requestOptions?: RequestOptions): Promise<Page<MemoryPageImageResponseShape>>`	`Promise<Page<MemoryPageImageResponseShape>>`
`memories`	`pagesImage`	`client.memories.pagesImage(id: string, pageIndex: number, options?: MemoriesPagesImageOptions, requestOptions?: RequestOptions): Promise<Uint8Array>`	`Promise<Uint8Array>`
`memories`	`retrieve`	`client.memories.retrieve(request: MemoriesRetrieveParams, requestOptions?: RequestOptions): AsyncIterable<RetrieveMemoryEventResponseShape>`	`AsyncIterable<RetrieveMemoryEventResponseShape>`
`ocr`	`document`	`client.ocr.document(request: OcrDocumentRequest, requestOptions?: RequestOptions): Promise<OcrDocumentResponseShape>`	`Promise<OcrDocumentResponseShape>`
`system`	`info`	`client.system.info(requestOptions?: RequestOptions): Promise<SystemInfoResponseShape>`	`Promise<SystemInfoResponseShape>`
`system`	`init`	`client.system.init(requestOptions?: RequestOptions): Promise<SystemInitResponseShape>`	`Promise<SystemInitResponseShape>`
`instance`	`get`	`client.instance.get(requestOptions?: RequestOptions): Promise<GoodMemInstanceResponseShape>`	`Promise<GoodMemInstanceResponseShape>`
`users`	`create`	`client.users.create(request: CreateUserRequest, requestOptions?: RequestOptions): Promise<UserResponseShape>`	`Promise<UserResponseShape>`
`users`	`createEnrollment`	`client.users.createEnrollment(userId: string, request: CreateUserEnrollmentRequest, requestOptions?: RequestOptions): Promise<CreateUserEnrollmentResponseShape>`	`Promise<CreateUserEnrollmentResponseShape>`
`users`	`delete`	`client.users.delete(id: string, requestOptions?: RequestOptions): Promise<void>`	`Promise<void>`
`users`	`get`	`client.users.get(options?: UsersGetOptions, requestOptions?: RequestOptions): Promise<UserResponseShape>`	`Promise<UserResponseShape>`
`users`	`getByUsername`	`client.users.getByUsername(username: string, options?: UsersGetByUsernameOptions, requestOptions?: RequestOptions): Promise<UserResponseShape>`	`Promise<UserResponseShape>`
`users`	`getEnrollment`	`client.users.getEnrollment(userId: string, enrollmentId: string, requestOptions?: RequestOptions): Promise<UserEnrollmentResponseShape>`	`Promise<UserEnrollmentResponseShape>`
`users`	`list`	`client.users.list(options?: UsersListOptions, requestOptions?: RequestOptions): Promise<Page<UserResponseShape>>`	`Promise<Page<UserResponseShape>>`
`users`	`listEnrollments`	`client.users.listEnrollments(userId: string, options?: UsersListEnrollmentsOptions, requestOptions?: RequestOptions): Promise<Page<UserEnrollmentResponseShape>>`	`Promise<Page<UserEnrollmentResponseShape>>`
`users`	`me`	`client.users.me(requestOptions?: RequestOptions): Promise<UserResponseShape>`	`Promise<UserResponseShape>`
`users`	`revokeEnrollment`	`client.users.revokeEnrollment(userId: string, enrollmentId: string, requestOptions?: RequestOptions): Promise<void>`	`Promise<void>`
`users`	`update`	`client.users.update(id: string, request: UpdateUserRequest, requestOptions?: RequestOptions): Promise<UserResponseShape>`	`Promise<UserResponseShape>`
`service_identities`	`create`	`client.service_identities.create(request: CreateServiceIdentityRequest, requestOptions?: RequestOptions): Promise<ServiceIdentityResponseShape>`	`Promise<ServiceIdentityResponseShape>`
`service_identities`	`delete`	`client.service_identities.delete(id: string, requestOptions?: RequestOptions): Promise<void>`	`Promise<void>`
`service_identities`	`get`	`client.service_identities.get(id: string, options?: ServiceIdentitiesGetOptions, requestOptions?: RequestOptions): Promise<ServiceIdentityResponseShape>`	`Promise<ServiceIdentityResponseShape>`
`service_identities`	`list`	`client.service_identities.list(options?: ServiceIdentitiesListOptions, requestOptions?: RequestOptions): Promise<Page<ServiceIdentityResponseShape>>`	`Promise<Page<ServiceIdentityResponseShape>>`
`service_identities`	`transferOwnership`	`client.service_identities.transferOwnership(id: string, request: TransferOwnershipRequest, requestOptions?: RequestOptions): Promise<TransferServiceIdentityOwnershipResponseShape>`	`Promise<TransferServiceIdentityOwnershipResponseShape>`
`service_identities`	`update`	`client.service_identities.update(id: string, request: UpdateServiceIdentityRequest, requestOptions?: RequestOptions): Promise<ServiceIdentityResponseShape>`	`Promise<ServiceIdentityResponseShape>`
`user_enrollments`	`complete`	`client.user_enrollments.complete(request: CompleteUserEnrollmentRequest, requestOptions?: RequestOptions): Promise<CompleteUserEnrollmentResponseShape>`	`Promise<CompleteUserEnrollmentResponseShape>`
`admin`	`backgroundJobsPurge`	`client.admin.backgroundJobsPurge(request: AdminPurgeJobsRequest, requestOptions?: RequestOptions): Promise<AdminPurgeJobsResponseShape>`	`Promise<AdminPurgeJobsResponseShape>`
`admin`	`drain`	`client.admin.drain(request: AdminDrainRequest, requestOptions?: RequestOptions): Promise<AdminDrainResponseShape>`	`Promise<AdminDrainResponseShape>`
`admin`	`licenseReload`	`client.admin.licenseReload(requestOptions?: RequestOptions): Promise<AdminReloadLicenseResponseShape>`	`Promise<AdminReloadLicenseResponseShape>`
`admin`	`retrieveMemoryLogPoliciesCreate`	`client.admin.retrieveMemoryLogPoliciesCreate(request: CreateRetrieveMemoryLogPolicyRequest, requestOptions?: RequestOptions): Promise<RetrieveMemoryLogPolicyResponseShape>`	`Promise<RetrieveMemoryLogPolicyResponseShape>`
`admin`	`retrieveMemoryLogPoliciesDelete`	`client.admin.retrieveMemoryLogPoliciesDelete(id: string, request: DeleteRetrieveMemoryLogPolicyRequest, requestOptions?: RequestOptions): Promise<RetrieveMemoryLogPolicyResponseShape>`	`Promise<RetrieveMemoryLogPolicyResponseShape>`
`admin`	`retrieveMemoryLogPoliciesGet`	`client.admin.retrieveMemoryLogPoliciesGet(id: string, options?: AdminRetrieveMemoryLogPoliciesGetOptions, requestOptions?: RequestOptions): Promise<RetrieveMemoryLogPolicyResponseShape>`	`Promise<RetrieveMemoryLogPolicyResponseShape>`
`admin`	`retrieveMemoryLogPoliciesList`	`client.admin.retrieveMemoryLogPoliciesList(options?: AdminRetrieveMemoryLogPoliciesListOptions, requestOptions?: RequestOptions): Promise<Page<RetrieveMemoryLogPolicyResponseShape>>`	`Promise<Page<RetrieveMemoryLogPolicyResponseShape>>`
`admin`	`transferInstanceOwnership`	`client.admin.transferInstanceOwnership(request: TransferOwnershipRequest, requestOptions?: RequestOptions): Promise<TransferInstanceOwnershipResponseShape>`	`Promise<TransferInstanceOwnershipResponseShape>`
`access_policy`	`check`	`client.access_policy.check(request: CheckAuthorizationsRequest, requestOptions?: RequestOptions): Promise<CheckAuthorizationsResponseShape>`	`Promise<CheckAuthorizationsResponseShape>`
`access_policy`	`grantsCreate`	`client.access_policy.grantsCreate(request: CreateAuthorizationGrantRequest, requestOptions?: RequestOptions): Promise<AuthorizationGrantResponseShape>`	`Promise<AuthorizationGrantResponseShape>`
`access_policy`	`grantsDelete`	`client.access_policy.grantsDelete(id: string, requestOptions?: RequestOptions): Promise<AuthorizationGrantResponseShape>`	`Promise<AuthorizationGrantResponseShape>`
`access_policy`	`grantsGet`	`client.access_policy.grantsGet(id: string, options?: AccessPolicyGrantsGetOptions, requestOptions?: RequestOptions): Promise<AuthorizationGrantResponseShape>`	`Promise<AuthorizationGrantResponseShape>`
`access_policy`	`grantsList`	`client.access_policy.grantsList(options?: AccessPolicyGrantsListOptions, requestOptions?: RequestOptions): Promise<Page<AuthorizationGrantResponseShape>>`	`Promise<Page<AuthorizationGrantResponseShape>>`
`access_policy`	`roleAssignmentsCreate`	`client.access_policy.roleAssignmentsCreate(request: AssignRoleRequest, requestOptions?: RequestOptions): Promise<RoleAssignmentResponseShape>`	`Promise<RoleAssignmentResponseShape>`
`access_policy`	`roleAssignmentsDelete`	`client.access_policy.roleAssignmentsDelete(id: string, requestOptions?: RequestOptions): Promise<RoleAssignmentResponseShape>`	`Promise<RoleAssignmentResponseShape>`
`access_policy`	`roleAssignmentsGet`	`client.access_policy.roleAssignmentsGet(id: string, options?: AccessPolicyRoleAssignmentsGetOptions, requestOptions?: RequestOptions): Promise<RoleAssignmentResponseShape>`	`Promise<RoleAssignmentResponseShape>`
`access_policy`	`roleAssignmentsList`	`client.access_policy.roleAssignmentsList(options?: AccessPolicyRoleAssignmentsListOptions, requestOptions?: RequestOptions): Promise<Page<RoleAssignmentResponseShape>>`	`Promise<Page<RoleAssignmentResponseShape>>`
`apikeys`	`create`	`client.apikeys.create(request: CreateApiKeyRequest, requestOptions?: RequestOptions): Promise<CreateApiKeyResponseShape>`	`Promise<CreateApiKeyResponseShape>`
`apikeys`	`delete`	`client.apikeys.delete(id: string, requestOptions?: RequestOptions): Promise<void>`	`Promise<void>`
`apikeys`	`get`	`client.apikeys.get(id: string, requestOptions?: RequestOptions): Promise<ApiKeyResponseShape>`	`Promise<ApiKeyResponseShape>`
`apikeys`	`list`	`client.apikeys.list(options?: ApikeysListOptions, requestOptions?: RequestOptions): Promise<Page<ApiKeyResponseShape>>`	`Promise<Page<ApiKeyResponseShape>>`
`apikeys`	`update`	`client.apikeys.update(id: string, request: UpdateApiKeyRequest, requestOptions?: RequestOptions): Promise<ApiKeyResponseShape>`	`Promise<ApiKeyResponseShape>`
`ping`	`once`	`client.ping.once(request: PingOnceRequest, requestOptions?: RequestOptions): Promise<PingResultResponseShape>`	`Promise<PingResultResponseShape>`
`ping`	`stream`	`client.ping.stream(request: PingStreamParams, requestOptions?: RequestOptions): AsyncIterable<PingEventResponseShape>`	`AsyncIterable<PingEventResponseShape>`

Errors

All HTTP failures raise APIError subclasses. Transport failures raise NetworkError; malformed JSON or NDJSON responses raise ParseError.

Error	Meaning
`GoodMemError`	Base class for SDK errors.
`NetworkError`	Transport failures, including mid-stream read failures.
`ParseError`	JSON and NDJSON response parse failures.
`APIError`	Generic HTTP error; exposes `statusCode`, `body`, and `response`.
`BadRequestError`	HTTP 400.
`AuthenticationError`	HTTP 401.
`PermissionDeniedError`	HTTP 403.
`NotFoundError`	HTTP 404.
`ConflictError`	HTTP 409.
`UnprocessableEntityError`	HTTP 422.
`RateLimitError`	HTTP 429; exposes `retryAfter` when the header is present.
`InternalServerError`	HTTP 5xx.

try {
  await client.memories.get("missing-memory-id");
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Memory not found");
  }
}

Data Models

Enum Values

CredentialKind

CREDENTIAL_KIND_UNSPECIFIED, CREDENTIAL_KIND_API_KEY, CREDENTIAL_KIND_GCP_ADC

DashScopeApiDialect

UNSPECIFIED, EMBEDDING_NATIVE_TEXT, EMBEDDING_NATIVE_CONTENTS, LLM_NATIVE_TEXT, LLM_NATIVE_MULTIMODAL, RERANK_NATIVE_NESTED, OPENAI_COMPATIBLE, RERANK_COMPATIBLE_FLAT

LengthMeasurement

CHARACTER_COUNT, TOKEN_COUNT, CUSTOM

CREATE_USER, READ_USER, UPDATE_USER, DELETE_USER, LIST_USER, MANAGE_USER_ENROLLMENT, CREATE_SERVICE_IDENTITY, READ_SERVICE_IDENTITY, UPDATE_SERVICE_IDENTITY, DELETE_SERVICE_IDENTITY, LIST_SERVICE_IDENTITY, CREATE_SPACE, READ_SPACE, UPDATE_SPACE, DELETE_SPACE, LIST_SPACE, CREATE_API_KEY, READ_API_KEY, UPDATE_API_KEY, DELETE_API_KEY, LIST_API_KEY, CREATE_EMBEDDER, READ_EMBEDDER, UPDATE_EMBEDDER, DELETE_EMBEDDER, LIST_EMBEDDER, PING_EMBEDDER, EXECUTE_EMBEDDER, READ_EMBEDDER_CREDENTIALS, CREATE_RERANKER, READ_RERANKER, UPDATE_RERANKER, DELETE_RERANKER, LIST_RERANKER, PING_RERANKER, EXECUTE_RERANKER, READ_RERANKER_CREDENTIALS, CREATE_LLM, READ_LLM, UPDATE_LLM, DELETE_LLM, LIST_LLM, PING_LLM, EXECUTE_LLM, READ_LLM_CREDENTIALS, PROXY_INFERENCE_TARGET, OCR_DOCUMENT, CREATE_MEMORY, READ_MEMORY, DELETE_MEMORY, LIST_MEMORY, CREATE_EXTENSION, READ_EXTENSION, UPDATE_EXTENSION, DELETE_EXTENSION, LIST_EXTENSION, DOWNLOAD_EXTENSION, READ_INSTANCE, TRANSFER_INSTANCE_OWNERSHIP, TRANSFER_RESOURCE_OWNERSHIP, RELOAD_LICENSE, DRAIN_SERVER, PURGE_BACKGROUND_JOBS, CREATE_RETRIEVE_MEMORY_LOG_POLICY, READ_RETRIEVE_MEMORY_LOG_POLICY, LIST_RETRIEVE_MEMORY_LOG_POLICY, DELETE_RETRIEVE_MEMORY_LOG_POLICY, MANAGE_ACCESS

ProviderType

OPENAI, VLLM, TEI, LLAMA_CPP, VOYAGE, COHERE, JINA, DASHSCOPE, GEMINI

ResourceKind

INSTANCE, USER, SERVICE_IDENTITY, SPACE, API_KEY, EMBEDDER, RERANKER, LLM, MEMORY, EXTENSION, RETRIEVE_MEMORY_LOG_POLICY

Selector

ANY, OWN, EXACT, DIRECT_MEMBERS_OF

SeparatorKeepStrategy

KEEP_NONE, KEEP_START, KEEP_END

SortOrder

ASCENDING, DESCENDING, SORT_ORDER_UNSPECIFIED

Interfaces

AccessPolicyRule

One operation, selector, and optional assigned resource.

Field	Type	Required	Description
`operation`	`Operation`	yes	Protected operation.
`selector`	`Selector`	yes	Resource-selection semantics.
`assignedResource`	`AccessPolicyTarget \| null`	no	Required exactly for EXACT and DIRECT_MEMBERS_OF selectors.

AccessPolicyTarget

A typed access-policy target. resourceId is omitted for INSTANCE and required otherwise.

Field	Type	Required	Description
`kind`	`ResourceKind`	yes	Concrete target kind.
`resourceId`	`string \| null`	no	Concrete resource UUID; omitted for the singleton INSTANCE target.

ApiKeyAuth

Configuration for classic API-key authentication.

Field	Type	Required	Description
`inlineSecret`	`string \| null`	no	Secret stored directly in GoodMem (mutually exclusive with secretRef)
`secretRef`	`SecretReference \| null`	no	Reference to an external secret manager entry (mutually exclusive with inlineSecret)
`headerName`	`string \| null`	no	Desired HTTP header to carry the credential (defaults to Authorization)
`prefix`	`string \| null`	no	Optional prefix prepended to the secret (e.g., "Bearer ")

ApiKeyResponse

API key metadata without sensitive information.

Field	Type	Required	Description
`apiKeyId`	`string`	yes	Unique identifier for the API key.
`subjectPrincipalId`	`string`	yes	Principal authenticated by this API key.
`ownerPrincipalId`	`string`	yes	Principal that administratively owns this API key.
`authorityMode`	`ApiKeyAuthorityMode`	yes	Immutable authority derivation mode.
`ceiling`	`Array<AccessPolicyRule> \| null`	no	Complete immutable issuance ceiling; omitted only when ceilingOmitted is true.
`ceilingOmitted`	`boolean`	yes	True only when a BASIC list projection intentionally omitted the immutable ceiling.
`keyPrefix`	`string`	yes	First few characters of the key for display/identification purposes.
`status`	`"ACTIVE" \| "INACTIVE"`	yes	Compatibility usability status. ACTIVE means USABLE; INACTIVE combines NOT_YET_VALID, EXPIRED, and REVOKED.
`lifecycleState`	`"NOT_YET_VALID" \| "USABLE" \| "EXPIRED" \| "REVOKED"`	yes	Precise lifecycle state at the response evaluation instant.
`labels`	`Record<string, string>`	yes	User-defined labels for organization and filtering.
`expiresAt`	`number \| null`	no	Expiration timestamp in milliseconds since epoch. If not provided, the key does not expire.
`validFrom`	`number`	yes	Inclusive activation time in milliseconds since epoch.
`revokedAt`	`number \| null`	no	Permanent revocation time in milliseconds since epoch.
`revokedById`	`string \| null`	no	Exact audit actor UUID that revoked this key.
`lastUsedAt`	`number \| null`	no	Last time this API key was used, in milliseconds since epoch.
`createdAt`	`number`	yes	When the API key was created, in milliseconds since epoch.
`updatedAt`	`number`	yes	When the API key was last updated, in milliseconds since epoch.
`createdById`	`string`	yes	Exact principal or API-key actor that created this API key.
`updatedById`	`string`	yes	Exact principal or API-key actor that last updated this API key.

ChunkingConfiguration

Configuration for text chunking strategy used when processing content. Exactly one of none, recursive, or sentence must be provided.

Field	Type	Required	Description
`none`	`NoChunkingConfiguration \| null`	no	No chunking strategy - preserve original content as single unit
`recursive`	`RecursiveChunkingConfiguration \| null`	no	Recursive hierarchical chunking strategy with configurable separators
`sentence`	`SentenceChunkingConfiguration \| null`	no	Sentence-based chunking strategy with language detection

EndpointAuthentication

Structured credential payload describing how GoodMem should authenticate with an upstream provider.

Field	Type	Required	Description
`kind`	`CredentialKind`	yes	Selected credential strategy
`apiKey`	`ApiKeyAuth \| null`	no	Configuration when kind is CREDENTIAL_KIND_API_KEY
`gcpAdc`	`GcpAdcAuth \| null`	no	Configuration when kind is CREDENTIAL_KIND_GCP_ADC
`labels`	`Record<string, string> \| null`	no	Optional annotations to aid operators (e.g., "owner=vertex")

GcpAdcAuth

Configuration for Google Application Default Credentials (ADC).

Field	Type	Required	Description
`scopes`	`Array<string> \| null`	no	Additional OAuth scopes. Empty list falls back to the default cloud-platform scope.
`quotaProjectId`	`string \| null`	no	Optional quota project used for billing

GoodMemInstance

The singleton GoodMem instance and its ownership audit metadata.

Field	Type	Required	Description
`instanceId`	`string`	yes	Durable UUID of the singleton GoodMem instance.
`ownerId`	`string`	yes	Current human owner principal UUID.
`createdAt`	`number`	yes	Initialization timestamp in milliseconds since the Unix epoch.
`updatedAt`	`number`	yes	Most recent ownership-transfer timestamp in milliseconds since the Unix epoch.
`createdById`	`string`	yes	Principal or API-key actor UUID that initialized the instance.
`updatedById`	`string`	yes	Principal or API-key actor UUID that last transferred ownership.

GoodMemStatus

Warning or non-fatal status with granular codes (operation continues)

Field	Type	Required	Description
`code`	"GOODMEM_STATUS_CODE_UNSPECIFIED" \| "INVALID_ARGUMENT" \| "NOT_FOUND" \| "PERMISSION_DENIED" \| "FAILED_PRECONDITION" \| "EMBEDDER_FAILED" \| "EMBEDDER_UNAVAILABLE" \| "EMBEDDER_TIMEOUT" \| "VECTOR_SEARCH_FAILED" \| "VECTOR_SEARCH_PARTIAL" \| "VECTOR_SEARCH_TIMEOUT" \| "SPACE_INACCESSIBLE" \| "SPACE_NOT_FOUND" \| "SPACE_NO_EMBEDDERS" \| "CHUNK_NOT_FOUND" \| "MEMORY_LOAD_FAILED" \| "MEMORY_CONTENT_UNAVAILABLE" \| "RERANKING_FAILED" \| "SUMMARIZATION_FAILED" \| "SUMMARIZATION_TIMEOUT" \| "RATE_LIMITED" \| "RESOURCE_EXHAUSTED" \| "CONFIGURATION_ERROR" \| "LLM_CAPABILITY_INFERRED" \| "FEATURE_DISABLED"	yes	Status code for the warning or informational message
`message`	`string`	yes	Human-readable status message
`details`	`Record<string, string> \| null`	no	Additional contextual details

MemoryCreationRequest

Request body for creating a new Memory. A Memory represents content stored in a space.

Field	Type	Required	Description
`memoryId`	`string \| null`	no	Optional client-provided UUID for the memory. If omitted, the server generates one. Returns ALREADY_EXISTS if the ID is already in use.
`spaceId`	`string`	yes	ID of the space where this memory will be stored
`originalContent`	`string \| null`	no	Original content as plain text (use either this or originalContentB64)
`originalContentB64`	`string \| null`	no	Original content as base64-encoded binary data (use either this or originalContent)
`originalContentRef`	`string \| null`	no	Reference to external content location
`contentType`	`string`	yes	MIME type of the content
`metadata`	`Record<string, unknown> \| null`	no	Additional metadata for the memory. A top-level textual title is an optional document-title hint for embedding providers that support one; blank or non-string titles are ignored. Later metadata edits do not automatically re-embed existing chunks.
`chunkingConfig`	`ChunkingConfiguration \| null`	no	Chunking strategy for this memory (if not provided, uses space default)
`extractPageImages`	`boolean \| null`	no	Optional hint to extract page images for eligible document types (for example, PDFs)
`fileField`	`string \| null`	no	Optional multipart file field name to bind binary content; required when multiple files are uploaded in a batch multipart request.

NoChunkingConfiguration

No chunking strategy - preserves original content as a single unit

No fields.

RecursiveChunkingConfiguration

Recursive hierarchical chunking strategy with configurable separators and overlap

Field	Type	Required	Description
`chunkSize`	`number`	yes	Maximum size of a chunk (should be ≤ context window)
`chunkOverlap`	`number`	yes	Sliding overlap between chunks
`separators`	`Array<string> \| null`	no	Hierarchical separator list (order = preference)
`keepStrategy`	`SeparatorKeepStrategy`	yes	How to handle separators after splitting. KEEP_NONE is deprecated and behaves as KEEP_END.
`separatorIsRegex`	`boolean \| null`	no	Whether separators are regex patterns
`lengthMeasurement`	`LengthMeasurement`	yes	How to measure chunk length

SecretReference

Field	Type	Required	Description
`uri`	`string`	yes	URI identifying where the secret can be resolved (e.g., vault://, env://)
`hints`	`Record<string, string> \| null`	no	Optional metadata to help resolvers decode the secret (e.g., {"encoding":"base64"})

SentenceChunkingConfiguration

Sentence-based chunking strategy with language detection support

Field	Type	Required	Description
`maxChunkSize`	`number`	yes	Maximum size of a chunk
`minChunkSize`	`number`	yes	Minimum size before creating a new chunk
`enableLanguageDetection`	`boolean \| null`	no	Whether to detect language for better segmentation
`lengthMeasurement`	`LengthMeasurement`	yes	How to measure chunk length

SystemInitRequest

Request for initializing the system. No parameters required.

No fields.

TransferOwnershipRequest

Names the principal that will become the resource owner.

Field	Type	Required	Description
`newOwnerId`	`string`	yes	Existing principal UUID that will become the new owner.

Response Shapes

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

AccessPolicyRuleResponseShape

Field	Type	Required	Description
`operation`	`Operation \| null`	yes	Protected operation.
`selector`	`Selector \| null`	yes	Resource-selection semantics.
`assignedResource`	`AccessPolicyTargetResponseShape \| null`	no	Required exactly for EXACT and DIRECT_MEMBERS_OF selectors.

AccessPolicyTargetResponseShape

Field	Type	Required	Description
`kind`	`ResourceKind \| null`	yes	Concrete target kind.
`resourceId`	`string \| null`	no	Concrete resource UUID; omitted for the singleton INSTANCE target.

ApiKeyAuthResponseShape

Type constraint: ApiKeyAuthResponseShape = RequireExactlyOne<ApiKeyAuthResponseShapeBase, "inlineSecret" \| "secretRef">

Field	Type	Required	Description
`inlineSecret`	`string \| null`	no	Secret stored directly in GoodMem (mutually exclusive with secretRef)
`secretRef`	`SecretReferenceResponseShape \| null`	no	Reference to an external secret manager entry (mutually exclusive with inlineSecret)
`headerName`	`string \| null`	no	Desired HTTP header to carry the credential (defaults to Authorization)
`prefix`	`string \| null`	no	Optional prefix prepended to the secret (e.g., "Bearer ")

ApiKeyResponseShape

Field	Type	Required	Description
`apiKeyId`	`string`	yes	Unique identifier for the API key.
`subjectPrincipalId`	`string`	yes	Principal authenticated by this API key.
`ownerPrincipalId`	`string`	yes	Principal that administratively owns this API key.
`authorityMode`	`ApiKeyAuthorityMode \| null`	yes	Immutable authority derivation mode.
`ceiling`	`Array<AccessPolicyRuleResponseShape> \| null`	no	Complete immutable issuance ceiling; omitted only when ceilingOmitted is true.
`ceilingOmitted`	`boolean`	yes	True only when a BASIC list projection intentionally omitted the immutable ceiling.
`keyPrefix`	`string`	yes	First few characters of the key for display/identification purposes.
`status`	`"ACTIVE" \| "INACTIVE" \| null`	yes	Compatibility usability status. ACTIVE means USABLE; INACTIVE combines NOT_YET_VALID, EXPIRED, and REVOKED.
`lifecycleState`	`"NOT_YET_VALID" \| "USABLE" \| "EXPIRED" \| "REVOKED" \| null`	yes	Precise lifecycle state at the response evaluation instant.
`labels`	`Record<string, string>`	yes	User-defined labels for organization and filtering.
`expiresAt`	`number \| null`	no	Expiration timestamp in milliseconds since epoch. If not provided, the key does not expire.
`validFrom`	`number`	yes	Inclusive activation time in milliseconds since epoch.
`revokedAt`	`number \| null`	no	Permanent revocation time in milliseconds since epoch.
`revokedById`	`string \| null`	no	Exact audit actor UUID that revoked this key.
`lastUsedAt`	`number \| null`	no	Last time this API key was used, in milliseconds since epoch.
`createdAt`	`number`	yes	When the API key was created, in milliseconds since epoch.
`updatedAt`	`number`	yes	When the API key was last updated, in milliseconds since epoch.
`createdById`	`string`	yes	Exact principal or API-key actor that created this API key.
`updatedById`	`string`	yes	Exact principal or API-key actor that last updated this API key.

ChunkingConfigurationResponseShape

Type constraint: ChunkingConfigurationResponseShape = RequireExactlyOne<ChunkingConfigurationResponseShapeBase, "none" \| "recursive" \| "sentence">

Field	Type	Required	Description
`none`	`NoChunkingConfigurationResponseShape \| null`	no	No chunking strategy - preserve original content as single unit
`recursive`	`RecursiveChunkingConfigurationResponseShape \| null`	no	Recursive hierarchical chunking strategy with configurable separators
`sentence`	`SentenceChunkingConfigurationResponseShape \| null`	no	Sentence-based chunking strategy with language detection

EndpointAuthenticationResponseShape

Type constraint: discriminated union on kind with response-shaped credential payloads; kind: null is allowed for unknown server enum values.

Field	Type	Required	Description
`kind`	`CredentialKind \| null`	yes	Selected credential strategy
`apiKey`	`ApiKeyAuthResponseShape \| null`	no	Configuration when kind is CREDENTIAL_KIND_API_KEY
`gcpAdc`	`GcpAdcAuthResponseShape \| null`	no	Configuration when kind is CREDENTIAL_KIND_GCP_ADC
`labels`	`Record<string, string> \| null`	no	Optional annotations to aid operators (e.g., "owner=vertex")

GcpAdcAuthResponseShape

Field	Type	Required	Description
`scopes`	`Array<string> \| null`	no	Additional OAuth scopes. Empty list falls back to the default cloud-platform scope.
`quotaProjectId`	`string \| null`	no	Optional quota project used for billing

GoodMemInstanceResponseShape

Field	Type	Required	Description
`instanceId`	`string`	yes	Durable UUID of the singleton GoodMem instance.
`ownerId`	`string`	yes	Current human owner principal UUID.
`createdAt`	`number`	yes	Initialization timestamp in milliseconds since the Unix epoch.
`updatedAt`	`number`	yes	Most recent ownership-transfer timestamp in milliseconds since the Unix epoch.
`createdById`	`string`	yes	Principal or API-key actor UUID that initialized the instance.
`updatedById`	`string`	yes	Principal or API-key actor UUID that last transferred ownership.

GoodMemStatusResponseShape

Field	Type	Required	Description
`code`	"GOODMEM_STATUS_CODE_UNSPECIFIED" \| "INVALID_ARGUMENT" \| "NOT_FOUND" \| "PERMISSION_DENIED" \| "FAILED_PRECONDITION" \| "EMBEDDER_FAILED" \| "EMBEDDER_UNAVAILABLE" \| "EMBEDDER_TIMEOUT" \| "VECTOR_SEARCH_FAILED" \| "VECTOR_SEARCH_PARTIAL" \| "VECTOR_SEARCH_TIMEOUT" \| "SPACE_INACCESSIBLE" \| "SPACE_NOT_FOUND" \| "SPACE_NO_EMBEDDERS" \| "CHUNK_NOT_FOUND" \| "MEMORY_LOAD_FAILED" \| "MEMORY_CONTENT_UNAVAILABLE" \| "RERANKING_FAILED" \| "SUMMARIZATION_FAILED" \| "SUMMARIZATION_TIMEOUT" \| "RATE_LIMITED" \| "RESOURCE_EXHAUSTED" \| "CONFIGURATION_ERROR" \| "LLM_CAPABILITY_INFERRED" \| "FEATURE_DISABLED" \| null	yes	Status code for the warning or informational message
`message`	`string`	yes	Human-readable status message
`details`	`Record<string, string> \| null`	no	Additional contextual details

NoChunkingConfigurationResponseShape

No fields.

RecursiveChunkingConfigurationResponseShape

Field	Type	Required	Description
`chunkSize`	`number`	yes	Maximum size of a chunk (should be ≤ context window)
`chunkOverlap`	`number`	yes	Sliding overlap between chunks
`separators`	`Array<string> \| null`	no	Hierarchical separator list (order = preference)
`keepStrategy`	`SeparatorKeepStrategy \| null`	yes	How to handle separators after splitting. KEEP_NONE is deprecated and behaves as KEEP_END.
`separatorIsRegex`	`boolean \| null`	no	Whether separators are regex patterns
`lengthMeasurement`	`LengthMeasurement \| null`	yes	How to measure chunk length

SecretReferenceResponseShape

Field	Type	Required	Description
`uri`	`string`	yes	URI identifying where the secret can be resolved (e.g., vault://, env://)
`hints`	`Record<string, string> \| null`	no	Optional metadata to help resolvers decode the secret (e.g., {"encoding":"base64"})

SentenceChunkingConfigurationResponseShape

Field	Type	Required	Description
`maxChunkSize`	`number`	yes	Maximum size of a chunk
`minChunkSize`	`number`	yes	Minimum size before creating a new chunk
`enableLanguageDetection`	`boolean \| null`	no	Whether to detect language for better segmentation
`lengthMeasurement`	`LengthMeasurement \| null`	yes	How to measure chunk length

TypeScript SDK

On this page