Memories

package goodmem // import "fury.io/pairsys/goodmem"

Memory CRUD + retrieval (streaming) + file upload + batch ops.

Methods are called as client.Memories().<Method>(ctx, ...) on a *goodmem.Client. Service: MemoriesService.

Index

type MemoriesService
- func (s *MemoriesService) Create
- func (s *MemoriesService) CreateFromFile
- func (s *MemoriesService) CreateFromReader
- func (s *MemoriesService) Retrieve
- func (s *MemoriesService) RetrieveRaw
- func (s *MemoriesService) Get
- func (s *MemoriesService) Content
- func (s *MemoriesService) Pages
- func (s *MemoriesService) PagesImage
- func (s *MemoriesService) List
- func (s *MemoriesService) Delete
- func (s *MemoriesService) BatchCreate
- func (s *MemoriesService) BatchGet
- func (s *MemoriesService) BatchDelete
type JsonBatchMemoryCreationRequest
type JsonMemoryCreationRequest
type BatchMemoryResponse
type BatchMemoryResult
type Memory
type ErrorDetail
type ProcessingHistory
type BackgroundJobSummary
type BackgroundJobAttempt
type BatchMemoryDeletionRequest
type BatchDeleteMemorySelectorRequest
type FilteredDeleteMemorySelectorRequest
type BatchMemoryRetrievalRequest
type MemoryListResponse
type ListMemoryPageImagesResponse
type MemoryPageImage
type RetrieveMemoryRequest
type ContextItem
type SpaceKey
type TokenBudget
type HnswOptions
type PostProcessor
type LoggingOptions
type BinaryContent
type EmbedderWeight
type HnswIterativeScan
type RetrieveMemoryEvent
type ResultSetBoundary
type AbstractReply
type RetrievedItem
type ChunkReference
type MemoryChunkResponse

type MemoriesService

type MemoriesService struct{ … }

Access this service as client.Memories() on a *goodmem.Client. Its methods follow.

func (s *MemoriesService) Create

func (s *MemoriesService) Create(ctx context.Context, req *models.JSONMemoryCreationRequest) (*models.Memory, error)

Create a memory from text content or base64-encoded binary content. Content must be provided via exactly one of originalContent or originalContentB64. When using originalContentB64, contentType is required (the server cannot infer MIME type from base64 bytes). originalContentRef is a metadata pointer (URL) attached to the memory; it does NOT supply content and may accompany originalContent/originalContentB64.

HTTP — POST /v1/memories

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.JSONMemoryCreationRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.Memory, error)

Examples

Example 1:

memory, err := client.Memories().Create(ctx, &models.JSONMemoryCreationRequest{
	SpaceID:         "your-space-id",
	OriginalContent: goodmem.Ptr("GoodMem stores and retrieves vectorized memories for RAG applications."),
	ContentType:     "text/plain",
	Metadata:        map[string]any{"source": "sdk-doc-test"},
})
if err != nil {
	log.Fatal(err)
}
_ = memory

Example 2:

// Read a file and send it as base64-encoded content.
data, err := os.ReadFile("testdata/example.txt")
if err != nil {
	return
}
b64 := base64.StdEncoding.EncodeToString(data)
memory, err := client.Memories().Create(ctx, &models.JSONMemoryCreationRequest{
	SpaceID:            "your-space-id",
	OriginalContentB64: goodmem.Ptr(b64),
	ContentType:        "text/plain",
})
if err != nil {
	log.Fatal(err)
}
_ = memory.MemoryID

Example 3:

b64 := base64.StdEncoding.EncodeToString([]byte("Base64-encoded content."))
memory, err := client.Memories().Create(ctx, &models.JSONMemoryCreationRequest{
	SpaceID:            "your-space-id",
	OriginalContentB64: goodmem.Ptr(b64),
	ContentType:        "text/plain",
})
if err != nil {
	log.Fatal(err)
}
_ = memory.MemoryID

func (s *MemoriesService) CreateFromFile

func (s *MemoriesService) CreateFromFile(ctx context.Context, filePath string, req *models.JSONMemoryCreationRequest) (*models.Memory, error)

Convenience variant: reads filePath from disk, base64-encodes the bytes, infers the content type from the file extension, and POSTs a JSON request.

HTTP — POST /v1/memories

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
filePath (string) — path to a local file. It is read into memory, base64-encoded, and the content type is inferred from the extension.
req (*models.JSONMemoryCreationRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.Memory, error)

Example

resp, err := client.Memories().CreateFromFile(ctx, "/tmp/file.bin", &models.JSONMemoryCreationRequest{ /* required fields */ })
if err != nil {
    log.Fatal(err)
}
_ = resp

func (s *MemoriesService) CreateFromReader

func (s *MemoriesService) CreateFromReader(ctx context.Context, r io.Reader, filename string, req *models.JSONMemoryCreationRequest) (*models.Memory, error)

Convenience variant: streams an arbitrary io.Reader as the multipart file part (via io.Pipe, so a large upload is never fully buffered in memory); filename names the part and, when ContentType is unset, drives MIME inference. Use it for non-file sources — an object-store stream, an HTTP response body, or an in-memory buffer.

HTTP — POST /v1/memories

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
r (io.Reader)
filename (string)
req (*models.JSONMemoryCreationRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.Memory, error)

Example

resp, err := client.Memories().CreateFromReader(ctx, nil, "...", &models.JSONMemoryCreationRequest{ /* required fields */ })
if err != nil {
    log.Fatal(err)
}
_ = resp

func (s *MemoriesService) Retrieve

func (s *MemoriesService) Retrieve(ctx context.Context, message string, opts *RetrieveOptions) (*Stream[models.RetrieveMemoryEvent], error)

Performs a streaming semantic search across one or more memory spaces and returns matching chunks ranked by relevance as well as LLM-postprocessed results (like summarization, question-answering, etc.).

HTTP — POST /v1/memories:retrieve

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
message (string) — the natural-language query.
opts (*RetrieveOptions) — options bag carrying the lookup key(s) / convenience knobs. Set the documented fields; the linked pkg.go.dev page lists them all.

Returns — (*Stream[models.RetrieveMemoryEvent], error)

Examples

Example 1:

stream, err := client.Memories().Retrieve(ctx, "What is GoodMem?", &goodmem.RetrieveOptions{
	SpaceIDs:      []string{"your-space-id"},
	RequestedSize: goodmem.Ptr(int32(5)),
})
if err != nil {
	log.Fatal(err)
}
defer stream.Close()
for event, err := range stream.Events() {
	if err != nil {
		log.Fatal(err)
	}
	if event.RetrievedItem != nil {
		_ = event.RetrievedItem
	}
}

Example 2:

// RetrieveRaw takes a fully-formed request for advanced control.
stream, err := client.Memories().RetrieveRaw(ctx, &models.RetrieveMemoryRequest{
	Message:       "What is GoodMem?",
	SpaceKeys:     []models.SpaceKey{{SpaceID: "your-space-id"}},
	RequestedSize: goodmem.Ptr(int32(5)),
})
if err != nil {
	log.Fatal(err)
}
defer stream.Close()
for event, err := range stream.Events() {
	if err != nil {
		log.Fatal(err)
	}
	_ = event
}

func (s *MemoriesService) RetrieveRaw

func (s *MemoriesService) RetrieveRaw(ctx context.Context, req *models.RetrieveMemoryRequest) (*Stream[models.RetrieveMemoryEvent], error)

Lower-level variant: takes a fully-formed request and returns the raw stream/response without the flat-parameter convenience layer. Use the non-Raw form for the ergonomic call shape.

HTTP — POST /v1/memories:retrieve

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.RetrieveMemoryRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*Stream[models.RetrieveMemoryEvent], error)

Example

stream, err := client.Memories().RetrieveRaw(ctx, &models.RetrieveMemoryRequest{ /* required fields */ })
if err != nil {
    log.Fatal(err)
}
defer stream.Close()
for event, err := range stream.Events() {
    if err != nil {
        log.Fatal(err)
    }
    _ = event
}

func (s *MemoriesService) Get

func (s *MemoriesService) Get(ctx context.Context, id string, params *MemoriesGetParams) (*models.Memory, error)

Retrieves a single memory by its ID. PERMISSION CLARIFICATION: With READ_MEMORY_OWN permission, access is granted if you own the parent space OR if the parent space is public (public_read=true). With READ_MEMORY_ANY permission, you can access any memory regardless of ownership. This is a read-only operation with no side effects and is safe to retry. Returns NOT_FOUND if the memory or its parent space does not exist.

HTTP — GET /v1/memories/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — The UUID of the memory to retrieve
params (*MemoriesGetParams, optional) — typed query parameters; pass nil for an empty filter set. The linked pkg.go.dev page lists every field.

Returns — (*models.Memory, error)

Example

memory, err := client.Memories().Get(ctx, "your-memory-id", nil)
if err != nil {
	log.Fatal(err)
}
_ = memory.ProcessingStatus

func (s *MemoriesService) Content

func (s *MemoriesService) Content(ctx context.Context, id string) ([]byte, error)

Returns the original binary payload for a memory. The response uses the memory's stored content type when available. Returns 404 when the memory does not have inline content; clients can check originalContentRef from the metadata endpoint to locate external content.

HTTP — GET /v1/memories/{id}/content

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — The UUID of the memory to download

Returns — ([]byte, error)

Example

content, err := client.Memories().Content(ctx, "your-memory-id")
if err != nil {
	log.Fatal(err)
}
_ = content // raw bytes

func (s *MemoriesService) Pages

func (s *MemoriesService) Pages(ctx context.Context, id string, params *MemoriesPagesParams) (*Page[models.MemoryPageImage], error)

Lists extracted page-image metadata for a memory with optional filters and pagination.

HTTP — GET /v1/memories/{id}/pages

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — Memory UUID
params (*MemoriesPagesParams, optional) — typed query parameters; pass nil for an empty filter set. The linked pkg.go.dev page lists every field.

Returns — (*Page[models.MemoryPageImage], error)

Example

// Auto-paginate page-image metadata, fetching pages on demand.
pages, err := client.Memories().Pages(ctx, "your-memory-id", nil)
if err != nil {
	log.Fatal(err)
}
for pi, err := range pages.All(ctx) {
	if err != nil {
		log.Fatal(err)
	}
	_ = pi.PageIndex
}

func (s *MemoriesService) PagesImage

func (s *MemoriesService) PagesImage(ctx context.Context, id string, pageIndex string, params *MemoriesPagesImageParams) ([]byte, error)

Downloads inline bytes for one page image. The page index is required. The optional dpi and content type query parameters act as rendition filters; if omitted, the server returns the unique rendition for that page or rejects ambiguous matches.

HTTP — GET /v1/memories/{id}/pages/{pageIndex}/image

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — Memory UUID
pageIndex (string) — 0-based page index
params (*MemoriesPagesImageParams, optional) — typed query parameters; pass nil for an empty filter set. The linked pkg.go.dev page lists every field.

Returns — ([]byte, error)

Example

imageBytes, err := client.Memories().PagesImage(ctx, "your-memory-id", "0", nil)
if err == nil {
	_ = len(imageBytes)
}

func (s *MemoriesService) List

func (s *MemoriesService) List(ctx context.Context, spaceID string, params *MemoriesListParams) (*Page[models.Memory], error)

Lists memories within a given space. Results are paginated; pass the response's nextToken back as a query parameter to fetch subsequent pages.

HTTP — GET /v1/spaces/{spaceId}/memories

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
spaceID (string) — The UUID of the space containing the memories
params (*MemoriesListParams, optional) — typed query parameters; pass nil for an empty filter set. The linked pkg.go.dev page lists every field.

Returns — (*Page[models.Memory], error)

Examples

Example 1:

page, err := client.Memories().List(ctx, "your-space-id", nil)
if err != nil {
	log.Fatal(err)
}
for mem, err := range page.All(ctx) {
	if err != nil {
		log.Fatal(err)
	}
	_ = mem.MemoryID
	_ = mem.ProcessingStatus
}

Example 2:

// First page, then resume from the saved token.
page, err := client.Memories().List(ctx, "your-space-id", &goodmem.MemoriesListParams{MaxResults: goodmem.Ptr(int32(1))})
if err != nil {
	log.Fatal(err)
}
savedToken := page.NextToken()
if savedToken != "" {
	resumed, err := client.Memories().List(ctx, "your-space-id", &goodmem.MemoriesListParams{NextToken: goodmem.Ptr(savedToken)})
	if err != nil {
		log.Fatal(err)
	}
	for mem, err := range resumed.All(ctx) {
		if err != nil {
			log.Fatal(err)
		}
		_ = mem.MemoryID
	}
}

func (s *MemoriesService) Delete

func (s *MemoriesService) Delete(ctx context.Context, id string) error

Permanently deletes a memory and its associated chunks. This operation cannot be undone and immediately removes the memory record from the database. IDEMPOTENCY: This operation is safe to retry - may return NOT_FOUND if the memory was already deleted or never existed. Requires DELETE_MEMORY_OWN permission for memories in spaces you own (or DELETE_MEMORY_ANY for admin users to delete any memory). Side effects include permanent removal of the memory record and all associated chunk data.

HTTP — DELETE /v1/memories/{id}

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
id (string) — The UUID of the memory to delete

Returns — error — nil on success.

Example

err := client.Memories().Delete(ctx, "your-memory-id")
if err != nil {
	log.Fatal(err)
}

func (s *MemoriesService) BatchCreate

func (s *MemoriesService) BatchCreate(ctx context.Context, req *models.JSONBatchMemoryCreationRequest) (*models.BatchMemoryResponse, error)

Create multiple memories in a single batch. Each item in requests follows the same per-call shape as memories.create: provide exactly one of originalContent or originalContentB64; originalContentB64 requires contentType (auto-inferred to text/plain for plain-text originalContent); originalContentRef is a metadata pointer that may accompany the content source. Per-item failures are reported individually and do NOT abort the batch.

HTTP — POST /v1/memories:batchCreate

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.JSONBatchMemoryCreationRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.BatchMemoryResponse, error)

Example

result, err := client.Memories().BatchCreate(ctx, &models.JSONBatchMemoryCreationRequest{
	Requests: []models.JSONMemoryCreationRequest{
		{SpaceID: "your-space-id", OriginalContent: goodmem.Ptr("Batch memory one."), ContentType: "text/plain"},
		{SpaceID: "your-space-id", OriginalContent: goodmem.Ptr("Batch memory two."), ContentType: "text/plain"},
	},
})
if err != nil {
	log.Fatal(err)
}
_ = result

func (s *MemoriesService) BatchGet

func (s *MemoriesService) BatchGet(ctx context.Context, req *models.BatchMemoryRetrievalRequest) (*models.BatchMemoryResponse, error)

Retrieves multiple memories in a single operation, with individual success/failure results.

HTTP — POST /v1/memories:batchGet

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.BatchMemoryRetrievalRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.BatchMemoryResponse, error)

Example

result, err := client.Memories().BatchGet(ctx, &models.BatchMemoryRetrievalRequest{
	MemoryIds: []string{"your-memory-id"},
})
if err != nil {
	log.Fatal(err)
}
for _, r := range result.Results {
	if r.Memory != nil {
		_ = r.Memory.ProcessingStatus
	}
}

func (s *MemoriesService) BatchDelete

func (s *MemoriesService) BatchDelete(ctx context.Context, req *models.BatchMemoryDeletionRequest) (*models.BatchMemoryResponse, error)

Deletes memories using selector entries. Each selector can target either a specific memory ID or a filtered subset scoped to a specific space.

HTTP — POST /v1/memories:batchDelete

Parameters

ctx (context.Context) — carries the deadline and cancellation signal for the call.
req (*models.BatchMemoryDeletionRequest) — the request payload. The linked type documents every field and its JSON wire name.

Returns — (*models.BatchMemoryResponse, error)

Example

result, err := client.Memories().BatchDelete(ctx, &models.BatchMemoryDeletionRequest{
	Requests: []models.BatchDeleteMemorySelectorRequest{
		{MemoryID: goodmem.Ptr("your-memory-id")},
	},
})
if err != nil {
	log.Fatal(err)
}
_ = result.Results

type JsonBatchMemoryCreationRequest

type JsonBatchMemoryCreationRequest struct{ … }

Request body for creating multiple memories via application/json.

Requests ([]models.JsonMemoryCreationRequest, wire requests) — Array of memory creation requests.

type JsonMemoryCreationRequest

type JsonMemoryCreationRequest struct{ … }

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

MemoryID (string, optional, wire memoryId) — 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, wire spaceId) — ID of the space where this memory will be stored
OriginalContent (string, optional, wire originalContent) — Original content as plain text (use either this or originalContentB64)
OriginalContentB64 (string, optional, wire originalContentB64) — Original content as base64-encoded binary data (use either this or originalContent)
OriginalContentRef (string, optional, wire originalContentRef) — Reference to external content location
ContentType (string, wire contentType) — MIME type of the content
Metadata (map[string]any, optional, wire metadata) — Additional metadata for the memory
ChunkingConfig (models.ChunkingConfiguration, optional, wire chunkingConfig) — Chunking strategy for this memory (if not provided, uses space default)
ExtractPageImages (bool, optional, wire extractPageImages) — Optional hint to extract page images for eligible document types (for example, PDFs)
FileField (string, optional, wire fileField) — Optional multipart file field name to bind binary content; required when multiple files are uploaded in a batch multipart request.

type BatchMemoryResponse

type BatchMemoryResponse struct{ … }

Response containing per-item results for a batch memories operation

Results ([]models.BatchMemoryResult, wire results) — Array of per-item results

type BatchMemoryResult

type BatchMemoryResult struct{ … }

Individual item result for a batch memories operation

Success (bool, wire success) — Whether this individual operation succeeded
MemoryID (string, optional, wire memoryId) — Memory ID associated with this result (present for batchGet errors and batchDelete results)
Memory (models.Memory, optional, wire memory) — Created or retrieved memory (present when the operation returns a memory on success)
Error (models.ErrorDetail, optional, wire error) — Error details when success is false

type Memory

type Memory struct{ … }

Memory object containing stored content and metadata

MemoryID (string, wire memoryId) — Unique identifier of the memory
SpaceID (string, wire spaceId) — ID of the space containing this memory
OriginalContent ([]byte, optional, wire originalContent) — Original content (only included if requested)
OriginalContentLength (int64, optional, wire originalContentLength) — Size in bytes of the inline original content
OriginalContentSha256 (string, optional, wire originalContentSha256) — SHA-256 digest of the inline original content, hex encoded
OriginalContentRef (string, optional, wire originalContentRef) — Reference to external content location
ContentType (string, wire contentType) — MIME type of the content
ProcessingStatus (string, wire processingStatus) — Processing status of the memory
PageImageStatus (string, wire pageImageStatus) — Processing status of page-image extraction for this memory
PageImageCount (int32, wire pageImageCount) — Number of extracted page-image renditions linked to this memory
Metadata (map[string]any, optional, wire metadata) — Additional metadata for the memory
CreatedAt (int64, wire createdAt) — Timestamp when the memory was created (milliseconds since epoch)
UpdatedAt (int64, wire updatedAt) — Timestamp when the memory was last updated (milliseconds since epoch)
CreatedByID (string, wire createdById) — ID of the user who created this memory
UpdatedByID (string, wire updatedById) — ID of the user who last updated this memory
ChunkingConfig (models.ChunkingConfiguration, optional, wire chunkingConfig) — Chunking strategy used for this memory
ProcessingHistory (models.ProcessingHistory, optional, wire processingHistory) — Background job processing history associated with this memory

type ErrorDetail

type ErrorDetail struct{ … }

Structured error details for an individual batch operation result

Code (int32, wire code) — Numeric error code (typically an HTTP or gRPC-derived status code)
Message (string, wire message) — Human-readable error message

type ProcessingHistory

type ProcessingHistory struct{ … }

Background job execution history associated with a memory

LatestJob (models.BackgroundJobSummary, optional, wire latestJob) — Summary of the most recent background job
Attempts ([]models.BackgroundJobAttempt, optional, wire attempts) — Attempt-level telemetry captured for the latest job

type BackgroundJobSummary

type BackgroundJobSummary struct{ … }

Summary of the most recent background job execution for a resource

JobID (int64, wire jobId) — Database identifier of the background job
JobType (string, wire jobType) — Logical job type dispatched by the background job framework
Status (string, wire status) — Current status of the background job
Attempts (int32, wire attempts) — Number of attempts started so far
MaxAttempts (int32, wire maxAttempts) — Maximum number of attempts allowed for this job
RunAt (int64, optional, wire runAt) — Timestamp when the job becomes eligible to run (milliseconds since epoch)
LeaseUntil (int64, optional, wire leaseUntil) — Lease expiration timestamp if the job is currently running (milliseconds since epoch)
LockedBy (string, optional, wire lockedBy) — Identifier of the worker currently holding the lease, if any
LastError (string, optional, wire lastError) — Most recent short error message if the job failed
UpdatedAt (int64, optional, wire updatedAt) — Timestamp when the job row was last updated (milliseconds since epoch)

type BackgroundJobAttempt

type BackgroundJobAttempt struct{ … }

Telemetry captured for a single execution attempt of a background job

AttemptID (int64, wire attemptId) — Identifier of the attempt
JobID (int64, wire jobId) — Identifier of the job that owns this attempt
StartedAt (int64, optional, wire startedAt) — Attempt start timestamp (milliseconds since epoch)
FinishedAt (int64, optional, wire finishedAt) — Attempt completion timestamp (milliseconds since epoch)
Ok (bool, optional, wire ok) — Indicates whether the attempt succeeded (null if still running)
WorkerID (string, optional, wire workerId) — Identifier of the worker processing the attempt
StatusMessage (string, optional, wire statusMessage) — Latest status message reported by the worker
ProgressCurrent (int64, wire progressCurrent) — Current progress counter value
ProgressTotal (int64, optional, wire progressTotal) — Total progress target when known
ProgressUnit (string, optional, wire progressUnit) — Unit label associated with the progress counters
ProgressUpdatedAt (int64, optional, wire progressUpdatedAt) — Timestamp when progress was last updated (milliseconds since epoch)
ErrorMessage (string, optional, wire errorMessage) — Short error message recorded when the attempt failed
ErrorStacktrace (string, optional, wire errorStacktrace) — Stack trace captured when the attempt failed, if available

type BatchMemoryDeletionRequest

type BatchMemoryDeletionRequest struct{ … }

Request body for deleting memories using ID and/or filtered selectors

Requests ([]models.BatchDeleteMemorySelectorRequest, wire requests) — Array of delete selectors

type BatchDeleteMemorySelectorRequest

type BatchDeleteMemorySelectorRequest struct{ … }

A single delete selector: either memoryId or filterSelector

MemoryID (string, optional, wire memoryId) — Deletes one specific memory by UUID
FilterSelector (models.FilteredDeleteMemorySelectorRequest, optional, wire filterSelector) — Deletes a filtered set of memories within a specific space

type FilteredDeleteMemorySelectorRequest

type FilteredDeleteMemorySelectorRequest struct{ … }

Filtered selector scoped to a specific space

SpaceID (string, wire spaceId) — Space ID scope for the filtered delete
StatusFilter (string, optional, wire statusFilter) — Optional processing status filter (PENDING, PROCESSING, COMPLETED, FAILED)
Filter (string, optional, wire filter) — Optional metadata filter expression

type BatchMemoryRetrievalRequest

type BatchMemoryRetrievalRequest struct{ … }

Request body for retrieving multiple memories by their IDs

MemoryIds ([]string, wire memoryIds) — Array of memory IDs to retrieve
IncludeContent (bool, optional, wire includeContent) — Whether to include the original content in the response
IncludeProcessingHistory (bool, optional, wire includeProcessingHistory) — Whether to include background job processing history for each memory

type MemoryListResponse

type MemoryListResponse struct{ … }

Response containing a list of memories within a space

Memories ([]models.Memory, wire memories) — Array of memories in the space
NextToken (string, optional, wire nextToken) — Token for retrieving the next page of results

type ListMemoryPageImagesResponse

type ListMemoryPageImagesResponse struct{ … }

Page of memory page-image metadata

PageImages ([]models.MemoryPageImage, wire pageImages) — Page-image metadata rows
NextToken (string, optional, wire nextToken) — Opaque token for retrieving the next page

type MemoryPageImage

type MemoryPageImage struct{ … }

Metadata for one memory page-image rendition

MemoryID (string, wire memoryId) — Memory UUID
PageIndex (int32, wire pageIndex) — 0-based page index
Dpi (int32, wire dpi) — Render DPI
ContentType (string, wire contentType) — Image MIME type
ImageContentLength (int64, optional, wire imageContentLength) — Image byte length
ImageContentSha256 (string, optional, wire imageContentSha256) — Hex-encoded SHA-256 digest of image content
CreatedAt (int64, wire createdAt) — Creation timestamp (milliseconds since epoch)
UpdatedAt (int64, wire updatedAt) — Last update timestamp (milliseconds since epoch)
CreatedByID (string, wire createdById) — Creator user UUID
UpdatedByID (string, wire updatedById) — Last updater user UUID

type RetrieveMemoryRequest

type RetrieveMemoryRequest struct{ … }

Request body for semantic memory retrieval with optional embedder weight overrides.

Message (string, wire message) — Primary query/message for semantic search.
Context ([]models.ContextItem, optional, wire context) — Optional context items (text or binary) to provide additional context for the search.
SpaceKeys ([]models.SpaceKey, wire spaceKeys) — List of spaces to search with optional per-embedder weight overrides.
RequestedSize (int32, optional, wire requestedSize) — Maximum number of memories to retrieve.
OutputBudget (models.TokenBudget, optional, wire outputBudget) — Optional soft cap for generated retrieve replies. When set to a positive token count, chat post-processing uses this value as the LLM completion-token budget.
FetchMemory (bool, optional, wire fetchMemory) — Whether to include streamed memory-definition records in the response. Defaults to true when omitted. These records include memory metadata and audit fields, but omit originalContent unless fetchMemoryContent is true.
FetchMemoryContent (bool, optional, wire fetchMemoryContent) — Whether streamed memory-definition records include originalContent bytes. Requires fetchMemory=true. Defaults to false when omitted.
HNSW (models.HnswOptions, optional, wire hnsw) — Optional request-level HNSW tuning overrides. Advanced usage; available on POST retrieve.
PostProcessor (models.PostProcessor, optional, wire postProcessor) — Optional post-processor configuration to transform retrieval results.
Logging (models.LoggingOptions, optional, wire logging) — Optional durable request logging block for POST retrieve requests. Set logging.enabled=true to opt in, or supply flat scalar logging.callerAttributes to attach if caller opt-in or an admin policy logs the request.

type ContextItem

type ContextItem struct{ … }

Context item with either text or binary content.

Text (string, optional, wire text) — Text content for this context item.
Binary (models.BinaryContent, optional, wire binary) — Binary content for this context item.

type SpaceKey

type SpaceKey struct{ … }

Space configuration for retrieval operations with optional embedder weight overrides.

SpaceID (string, wire spaceId) — The UUID for the space to search.
EmbedderWeights ([]models.EmbedderWeight, optional, wire embedderWeights) — Optional per-embedder weight overrides for this space. If not specified, database defaults are used.
Filter (string, optional, wire filter) — Optional filter expression that must evaluate to true for memories in this space.

type TokenBudget

type TokenBudget struct{ … }

Soft token budget hint for retrieve request processing.

Tokens (int32, wire tokens) — Token count for the budget. Must be positive.

type HnswOptions

type HnswOptions struct{ … }

Optional request-level overrides for pgvector HNSW search settings. Unset fields inherit server defaults.

EfSearch (int32, optional, wire efSearch) — HNSW candidate list size (1..1000).
IterativeScan (models.HnswIterativeScan, optional, wire iterativeScan) — HNSW iterative scan mode. Use POST retrieve for this advanced tuning control.
MaxScanTuples (int32, optional, wire maxScanTuples) — Maximum tuples to scan during iterative filtering (1..2147483647).
ScanMemMultiplier (float64, optional, wire scanMemMultiplier) — Multiplier on work_mem for iterative scanning (1.0..1000.0).

type PostProcessor

type PostProcessor struct{ … }

Post-processor configuration for transforming retrieval results. Custom processors are discovered from installed extensions and must be referenced by their fully qualified factory class name. See https://docs.goodmem.ai/docs/reference/post-processors/chat-post-processor/ for the built-in ChatPostProcessor configuration.

Name (string, wire name) — Fully qualified factory class name of the post-processor to apply.
Config (map[string]any, optional, wire config) — Configuration parameters for the post-processor. Fields depend on the selected processor; see the linked documentation for the built-in ChatPostProcessor schema.

type LoggingOptions

type LoggingOptions struct{ … }

Enabled (bool, optional, wire enabled) — Opts this request in to durable server-side request logging. False or omitted does not opt out of admin policy logging.
CallerAttributes (map[string]any, optional, wire callerAttributes) — Optional flat scalar attributes attached if this request is persisted by caller opt-in or admin policy logging. Supported value types are string, integer, floating-point, and boolean. At most 32 entries are accepted.

type BinaryContent

type BinaryContent struct{ … }

Binary content with MIME type for context items.

ContentType (string, wire contentType) — MIME type of the binary content.
Data (string, wire data) — Base64-encoded binary data.

type EmbedderWeight

type EmbedderWeight struct{ … }

Per-embedder weight override for retrieval operations.

EmbedderID (string, wire embedderId) — The UUID for the embedder.
Weight (float64, wire weight) — The weight to apply to this embedder's results. Can be positive, negative, or zero.

type HnswIterativeScan

type HnswIterativeScan string

Iterative scan modes for HNSW index search.

String enum (type HnswIterativeScan string): "ITERATIVE_SCAN_UNSPECIFIED" · "ITERATIVE_SCAN_OFF" · "ITERATIVE_SCAN_RELAXED_ORDER" · "ITERATIVE_SCAN_STRICT_ORDER"

type RetrieveMemoryEvent

type RetrieveMemoryEvent struct{ … }

Streaming event from memory retrieval operation

ResultSetBoundary (models.ResultSetBoundary, optional, wire resultSetBoundary) — Result set boundary marker (BEGIN/END)
AbstractReply (models.AbstractReply, optional, wire abstractReply) — Generated abstractive reply
RetrievedItem (models.RetrievedItem, optional, wire retrievedItem) — A retrieved memory or chunk
MemoryDefinition (models.Memory, optional, wire memoryDefinition) — Memory object to add to client's memories array
Status (models.GoodMemStatus, optional, wire status) — Warning or non-fatal status with granular codes (operation continues)

type ResultSetBoundary

type ResultSetBoundary struct{ … }

Boundary marker for logical result sets in streaming memory retrieval

ResultSetID (string, wire resultSetId) — Unique identifier for this result set (UUID)
Kind (string, wire kind) — Type of boundary marker
StageName (string, wire stageName) — Free-form label describing the pipeline stage
ExpectedItems (int32, optional, wire expectedItems) — Hint for progress tracking - expected number of items in this result set

type AbstractReply

type AbstractReply struct{ … }

Generated abstractive reply with relevance information

Text (string, wire text) — Generated abstractive reply text
RelevanceScore (float64, wire relevanceScore) — Relevance score for this reply (0.0 to 1.0)
ResultSetID (string, optional, wire resultSetId) — Optional result set ID linking this abstract to a specific result set

type RetrievedItem

type RetrievedItem struct{ … }

A retrieved result that can be either a Memory or MemoryChunk

Memory (models.Memory, optional, wire memory) — Complete memory object (if retrieved)
Chunk (models.ChunkReference, optional, wire chunk) — Reference to a memory chunk (if retrieved)

type ChunkReference

type ChunkReference struct{ … }

Reference to a memory chunk with pointer to its parent memory

ResultSetID (string, wire resultSetId) — Result set ID that produced this chunk
Chunk (models.MemoryChunkResponse, wire chunk) — The memory chunk data
MemoryIndex (int32, wire memoryIndex) — Index of the chunk's memory in the client's memories array
RelevanceScore (float64, wire relevanceScore) — Relevance score for this chunk (0.0 to 1.0)

type MemoryChunkResponse

type MemoryChunkResponse struct{ … }

Memory chunk information

ChunkID (string, wire chunkId) — Unique identifier of the memory chunk
MemoryID (string, wire memoryId) — ID of the memory this chunk belongs to
ChunkSequenceNumber (int32, wire chunkSequenceNumber) — Sequence number of this chunk within the memory
ChunkText (string, wire chunkText) — The text content of this chunk
VectorStatus (string, wire vectorStatus) — Status of vector processing for this chunk
StartOffset (int32, optional, wire startOffset) — Start offset of this chunk in the original content
EndOffset (int32, optional, wire endOffset) — End offset of this chunk in the original content
Metadata (map[string]any, optional, wire metadata) — Additional metadata for the memory chunk
CreatedAt (int64, wire createdAt) — Creation timestamp (milliseconds since epoch)
UpdatedAt (int64, wire updatedAt) — Last update timestamp (milliseconds since epoch)
CreatedByID (string, wire createdById) — ID of the user who created the chunk
UpdatedByID (string, wire updatedById) — ID of the user who last updated the chunk

Memories

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

Equivalent REST call

On this page