GoodMemBackground Job
Background Job service API reference
Messages
ProcessingHistory
Historical information about a background job that processes a domain entity.
| Field | Type | Description |
|---|---|---|
latest_job | ...oodmem.v1.BackgroundJobSummary | Details about the most recent job execution. |
attempts | ...oodmem.v1.BackgroundJobAttempt | Attempt-level telemetry in reverse-chronological order. |
BackgroundJobSummary
Summary of a background job's current execution state.
| Field | Type | Description |
|---|---|---|
job_id | int64 | The numeric identifier of the background job. |
job_type | string | The job type (matches bg_job.job_type). |
status | goodmem.v1.BackgroundJobStatus | Current state of the job. |
attempts | int32 | Number of attempts started so far. |
max_attempts | int32 | Maximum allowed attempts for this job. |
run_at | google.protobuf.Timestamp | When the job becomes eligible to run again. |
lease_until | google.protobuf.Timestamp | Lease expiration if currently running; unset if no active lease. |
locked_by | string | Worker currently holding the lease, if any. |
last_error | string | Short error message from the last failure, if any. |
updated_at | google.protobuf.Timestamp | Last time the job row was updated. |
failure_stage | ...mem.v1.DocumentProcessingStage | Latest attempt's failure stage for this memory; absent if unknown or unrelated. |
BackgroundJobAttempt
Per-attempt telemetry captured while a background job runs.
| Field | Type | Description |
|---|---|---|
attempt_id | int64 | The numeric identifier of the attempt. |
job_id | int64 | Owning background job identifier. |
started_at | google.protobuf.Timestamp | When the attempt started. |
finished_at | google.protobuf.Timestamp | When the attempt finished, if applicable. |
ok | bool | True if the attempt succeeded, false if failed, unset if running. |
worker_id | string | The worker processing the attempt. |
status_message | string | Latest status message reported by the worker. |
progress_current | int64 | The current progress value. |
progress_total | int64 | Total progress target, if known. |
progress_unit | string | Unit label for progress metrics (e.g., "pages"). |
progress_updated_at | google.protobuf.Timestamp | When progress fields were last updated. |
error_message | string | Short error message for failures. |
error_stacktrace | string | Captured stack trace for failures, possibly truncated. |
failure_stage | ...mem.v1.DocumentProcessingStage | Failure stage for this memory; absent if unknown or another memory failed. |
Enums
BackgroundJobStatus
Execution state of a background job within the GoodMem job framework.
| Name | Value | Description |
|---|---|---|
BACKGROUND_JOB_STATUS_UNSPECIFIED | 0 | The default value. Invalid on writes. |
BACKGROUND_JOB_PENDING | 1 | Eligible to run but not yet leased. |
BACKGROUND_JOB_RUNNING | 2 | Currently running with an active lease. |
BACKGROUND_JOB_SUCCEEDED | 3 | Finished successfully. |
BACKGROUND_JOB_FAILED | 4 | Exhausted retries or failed permanently. |
BACKGROUND_JOB_CANCELED | 5 | Explicitly canceled or expired. |
DocumentProcessingStage
Operation in which document processing failed. Captured at the operation boundary, independently of human-readable progress/error messages and retry policy.
| Name | Value | Description |
|---|---|---|
DOCUMENT_PROCESSING_STAGE_UNSPECIFIED | 0 | Unknown; not emitted as a known failure stage. |
DOCUMENT_PROCESSING_STAGE_LOADING_MEMORY | 1 | Acquire the database connection and load the memory. |
DOCUMENT_PROCESSING_STAGE_PREPARING_DOCUMENT | 2 | Resolve configuration/embedders and clear prior chunk state. |
DOCUMENT_PROCESSING_STAGE_EXTRACTING_CONTENT | 3 | Extract content and split it into chunks. |
DOCUMENT_PROCESSING_STAGE_STORING_CHUNKS | 4 | Persist extracted chunks. |
DOCUMENT_PROCESSING_STAGE_GENERATING_EMBEDDINGS | 5 | Generate and validate embedding results. |
DOCUMENT_PROCESSING_STAGE_STORING_EMBEDDINGS | 6 | Persist embeddings and their associated state. |
DOCUMENT_PROCESSING_STAGE_GENERATING_PAGE_IMAGES | 7 | Render page images; does not change which rendering failures are fatal. |
DOCUMENT_PROCESSING_STAGE_STORING_PAGE_IMAGES | 8 | Persist page images and their processing state. |
DOCUMENT_PROCESSING_STAGE_FINALIZING_MEMORY | 9 | Mark memory processing complete. |