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
Users	`client.users`	User lookup
Admin	`client.admin`	Server lifecycle operations
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, 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, 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, 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`	`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>`
`users`	`get`	`client.users.get(options?: UsersGetOptions, requestOptions?: RequestOptions): Promise<UserResponseShape>`	`Promise<UserResponseShape>`
`users`	`me`	`client.users.me(requestOptions?: RequestOptions): Promise<UserResponseShape>`	`Promise<UserResponseShape>`
`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>>`
`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`	`list`	`client.apikeys.list(requestOptions?: RequestOptions): Promise<Array<ApiKeyResponseShape>>`	`Promise<Array<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

LengthMeasurement

CHARACTER_COUNT, TOKEN_COUNT, CUSTOM

Modality

TEXT, IMAGE, AUDIO, VIDEO

ProviderType

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

SeparatorKeepStrategy

KEEP_NONE, KEEP_START, KEEP_END

SortOrder

ASCENDING, DESCENDING, SORT_ORDER_UNSPECIFIED

Interfaces

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

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

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

Response Shapes

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

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

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

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