Memory

CRUD & batch RPC surface

Provides services for creating, retrieving, and managing memories.

Authentication: All methods require API key authentication.

Global errors: All RPCs may return DEADLINE_EXCEEDED, CANCELLED, UNAVAILABLE, RESOURCE_EXHAUSTED, INTERNAL.

Permissions model:

*_MEMORY_OWN: Allows operations on memories within spaces owned by the caller.
*_MEMORY_ANY: Allows operations on memories in any space (requires elevated role).

CreateMemory

Creates a new Memory in a specified Space.

	Type
Request	`goodmem.v1.CreateMemoryRequest`
Response	`goodmem.v1.Memory`

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: CREATE_MEMORY_OWN or CREATE_MEMORY_ANY

Side Effects:

Creates a new Memory record with status PENDING
Enqueues a background job to process the memory (chunking and embedding)

Error Codes:

UNAUTHENTICATED: Missing or invalid auth token
PERMISSION_DENIED: Caller lacks permission to create memories in the specified space
INVALID_ARGUMENT: space_id, original_content, or content_type is missing or invalid
NOT_FOUND: The specified space_id does not exist

Idempotency: Not idempotent. Clients should not retry on unknown errors.

GetMemory

Retrieves a single Memory by its ID.

	Type
Request	`goodmem.v1.GetMemoryRequest`
Response	`goodmem.v1.Memory`

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: READ_MEMORY_OWN or READ_MEMORY_ANY

Note: For users with only READ_MEMORY_OWN, access is granted if they own the parent space OR if the parent space is public.

Error Codes:

UNAUTHENTICATED: Missing or invalid auth token
PERMISSION_DENIED: Caller lacks permission to read the memory
INVALID_ARGUMENT: memory_id is invalid
NOT_FOUND: The specified memory or its parent space does not exist

Idempotency: Read-only; safe to retry.

ListMemories

Lists all Memories within a given Space.

	Type
Request	`goodmem.v1.ListMemoriesRequest`
Response	`goodmem.v1.ListMemoriesResponse`

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: LIST_MEMORY_OWN or LIST_MEMORY_ANY

Note: The current server implementation does not support pagination for this RPC. The max_results and next_token fields will be ignored.

Error Codes:

UNAUTHENTICATED: Missing or invalid auth token
PERMISSION_DENIED: Caller lacks permission to list memories in the specified space
INVALID_ARGUMENT: space_id is invalid
NOT_FOUND: The specified space does not exist

Idempotency: Read-only; safe to retry.

DeleteMemory

Permanently deletes a Memory and its associated chunks.

	Type
Request	`goodmem.v1.DeleteMemoryRequest`
Response	`google.protobuf.Empty`

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: DELETE_MEMORY_OWN or DELETE_MEMORY_ANY

Error Codes:

UNAUTHENTICATED: Missing or invalid auth token
PERMISSION_DENIED: Caller lacks permission to delete the memory
INVALID_ARGUMENT: memory_id is invalid
NOT_FOUND: The specified memory does not exist

Idempotency: Safe to retry; may return NOT_FOUND if already deleted.

BatchCreateMemory

Creates multiple Memories in a single request.

This is a partial-success operation. The response will contain a result for each requested creation, indicating either success (with the new Memory) or an error status.

	Type
Request	`goodmem.v1.BatchCreateMemoryRequest`
Response	`goodmem.v1.BatchCreateMemoryResponse`

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: CREATE_MEMORY_OWN or CREATE_MEMORY_ANY

Idempotency: Not idempotent - each call may create new memories.

BatchGetMemory

Retrieves multiple Memories by their IDs in a single request.

This is a partial-success operation. The response will contain a result for each requested memory.

	Type
Request	`goodmem.v1.BatchGetMemoryRequest`
Response	`goodmem.v1.BatchGetMemoryResponse`

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: READ_MEMORY_OWN or READ_MEMORY_ANY

Idempotency: Read-only; safe to retry.

BatchDeleteMemory

Deletes multiple Memories by their IDs in a single request.

This is a partial-success operation. The response will indicate the outcome for each requested deletion.

	Type
Request	`goodmem.v1.BatchDeleteMemoryRequest`
Response	`goodmem.v1.BatchDeleteMemoryResponse`

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: DELETE_MEMORY_OWN or DELETE_MEMORY_ANY

Idempotency: Safe to retry; may return NOT_FOUND for already deleted memories.

RetrieveMemory

Performs a semantic search over one or more Spaces and streams back results.

This is a server-streaming RPC that provides a rich, event-based view of the retrieval process, including ranked chunks, full memory definitions, and optional LLM-generated summaries.

	Type
Request	`goodmem.v1.RetrieveMemoryRequest`
Response	`stream goodmem.v1.RetrieveMemoryEvent`

Auth: gRPC metadata authorization: Bearer <api-key>

Permissions Required: READ_MEMORY_OWN or READ_MEMORY_ANY

Error Codes:

Fails fast with INVALID_ARGUMENT, NOT_FOUND, or PERMISSION_DENIED if any initial validation of the request parameters (e.g., space IDs) fails
During the stream, non-fatal warnings are sent via GoodMemStatus events

Idempotency: Read-only; safe to retry.

Memory & MemoryChunk

A logical “memory” – a unit of content with associated metadata.

This is the primary object clients interact with. It represents the original, unprocessed content. The server processes this content asynchronously to create one or more MemoryChunks with vector embeddings.

Field	Type	Description
`memory_id`	`bytes`	OUTPUT_ONLY; UUID (16 bytes) of the memory.
`space_id`	`bytes`	OUTPUT_ONLY; UUID of the parent space.
`original_content`	`bytes`	WRITE_ONLY; The raw payload of the memory. Not returned in read RPCs unless explicitly requested.
`original_content_ref`	`string`	Optional URI pointing to the external source of the content.
`original_content_length`	`int64`	OUTPUT_ONLY; Size in bytes of original_content when stored inline.
`original_content_sha256`	`bytes`	OUTPUT_ONLY; SHA-256 digest of original_content (binary form).
`content_type`	`string`	REQUIRED; MIME type of the content (e.g., "text/plain", "application/pdf").
`metadata`	`google.protobuf.Struct`	Optional, arbitrary JSON-like metadata associated with the memory.
`chunking_config`	`goodmem.v1.ChunkingConfig`	Optional chunking strategy that overrides the space's default.
`processing_status`	`goodmem.v1.ProcessingStatus`	OUTPUT_ONLY; The current status of the asynchronous processing pipeline.
`processing_history`	`goodmem.v1.ProcessingHistory`	OUTPUT_ONLY; Populated when requested via Get/List flags.
`created_at`	`google.protobuf.Timestamp`	--- Audit --------------------------------------------------------------- OUTPUT_ONLY; Timestamp of creation.
`updated_at`	`google.protobuf.Timestamp`	OUTPUT_ONLY; Timestamp of last update.
`created_by_id`	`bytes`	OUTPUT_ONLY; UUID of the user who created the memory.
`updated_by_id`	`bytes`	OUTPUT_ONLY; UUID of the user who last updated the memory.

MemoryChunk

A single chunk derived from a Memory, paired with its vector embedding. Mostly internal, but exposed for advanced diagnostics.

Field	Type	Description
`chunk_id`	`bytes`	OUTPUT_ONLY; UUID of the chunk.
`memory_id`	`bytes`	OUTPUT_ONLY; UUID of the parent memory.
`chunk_sequence_number`	`int32`	OUTPUT_ONLY; The 0-based position of this chunk within the parent memory.
`chunk_text`	`string`	The text content of the chunk.
`embedding_vector`	`float`	For internal use; not reliably populated in retrieval responses.
`vector_status`	`goodmem.v1.ProcessingStatus`	OUTPUT_ONLY; The generation status of the embedding vector.
`start_offset`	`int32`	OUTPUT_ONLY; Byte offset in UTF-8 of the chunk start in original content.
`end_offset`	`int32`	OUTPUT_ONLY; Byte offset in UTF-8 of the chunk end (exclusive).
`created_at`	`google.protobuf.Timestamp`	--- Audit --------------------------------------------------------------- OUTPUT_ONLY; Timestamp of creation.
`updated_at`	`google.protobuf.Timestamp`	OUTPUT_ONLY; Timestamp of last update.
`created_by_id`	`bytes`	OUTPUT_ONLY; UUID of the user who created the chunk.
`updated_by_id`	`bytes`	OUTPUT_ONLY; UUID of the user who last updated the chunk.

MemoryOrStatus

Helper union for batch RPCs

A union type for batch operations that can return either a Memory or an error Status.

Field	Type	Description
`memory`	`goodmem.v1.Memory`	A successfully retrieved or created Memory.
`status`	`google.rpc.Status`	An error status for a failed operation on a single item.

RetrieveMemoryRequest

RetrieveMemory – request & streaming response

Defines the parameters for a semantic search query.

Field	Type	Description
`message`	`string`	--- Core query parameters ---------------------------------------------- REQUIRED; The user's natural language query or prompt.
`context`	`...rieveMemoryRequest.ContextItem`	Optional; Extra context to provide alongside the query.
`space_ids`	`...RetrieveMemoryRequest.SpaceKey`	REQUIRED; The list of spaces to search within.
`requested_size`	`int32`	The maximum number of results requested.
`output_budget`	`...rieveMemoryRequest.TokenBudget`	--- Soft resource caps -------------------------------------------------- Optional; A hint for the maximum number of tokens in the final reply.
`compute_budget`	`...rieveMemoryRequest.TokenBudget`	Optional; A hint for the overall computational effort.
`fetch_memory`	`bool`	--- Response shaping flags --------------------------------------------- If omitted, defaults to true. If explicitly set to false, `memory_definition` events will not be streamed.
`fetch_memory_content`	`bool`	If true, includes the raw content in streamed `memory_definition` events. Requires `fetch_memory` to be true.
`post_processor`	`...eveMemoryRequest.PostProcessor`	Optional; A post-processor to apply to the results (e.g., for summarization).

RetrieveMemoryRequest.TokenBudget

A hint to the server about the desired token budget for a response.

Field	Type	Description
`tokens`	`uint32`	The desired number of tokens.

RetrieveMemoryRequest.BinaryContent

Represents a piece of binary content provided as context.

Field	Type	Description
`content_type`	`string`	The MIME type of the content.
`data`	`bytes`	The raw binary data.

RetrieveMemoryRequest.ContextItem

A single item of context provided to augment the user's query.

Field	Type	Description
`text`	`string`	Textual context.
`binary`	`...eveMemoryRequest.BinaryContent`	Binary context (e.g., an image).

RetrieveMemoryRequest.PostProcessor

Defines a post-processor to be run on the retrieval results.

Field	Type	Description
`name`	`string`	The fully-qualified class name of the post-processor to run.
`config`	`google.protobuf.Struct`	Optional JSON-like configuration for the post-processor.

RetrieveMemoryRequest.EmbedderWeight

Specifies a custom weight for an embedder during a query.

Field	Type	Description
`embedder_id`	`bytes`	The UUID of the embedder to apply the weight to.
`weight`	`float`	The relevance weight for this embedder.

RetrieveMemoryRequest.SpaceKey

Specifies a space to search in, with optional per-embedder weighting.

Field	Type	Description
`space_id`	`bytes`	REQUIRED; The UUID of the space to search.
`embedder_weights`	`...veMemoryRequest.EmbedderWeight`	Optional; Overrides default weights for embedders in this space.
`filter`	`string`	Optional; Only memories that satisfy this filter expression are included in the results.

RetrieveMemoryEvent

A single event in the streaming response of a RetrieveMemory RPC.

The stream is a sequence of these events. The client is responsible for assembling the final results based on the event types. Events for different result sets may interleave, but within a given result set, the server emits BEGIN → items → END in order.

Field	Type	Description
`result_set_boundary`	`...eMemoryEvent.ResultSetBoundary`	Marks the beginning or end of a logical set of results.
`retrieved_item`	`...rieveMemoryEvent.RetrievedItem`	A single retrieved item, part of a result set.
`abstract_reply`	`...rieveMemoryEvent.AbstractReply`	An LLM-generated summary or answer.
`memory_definition`	`goodmem.v1.Memory`	A full memory definition, provided for client-side caching.
`status`	`goodmem.v1.GoodMemStatus`	A non-fatal warning or status update.

RetrieveMemoryEvent.ResultSetBoundary

Marks the BEGIN or END of a logical result set (e.g., from vector search or reranking).

Every RetrievedItem between a BEGIN and END boundary will share the same result_set_id.

Field	Type	Description
`result_set_id`	`bytes`	A unique UUID for this result set.
`kind`	`...ryEvent.ResultSetBoundary.Kind`	Whether this marks the beginning or end of the set.
`stage_name`	`string`	A human-readable name for the pipeline stage (e.g., "vector-search", "rerank").
`expected_items`	`uint32`	A hint for the total number of items in this set. A value of 0 means the total is not specified.

RetrieveMemoryEvent.AbstractReply

An LLM-generated textual summary or answer based on the retrieved items.

Field	Type	Description
`text`	`string`	The generated text.
`relevance_score`	`double`	The relevance score of the abstract itself.
`result_set_id`	`bytes`	Optional; The result set this abstract was generated from.

RetrieveMemoryEvent.RetrievedItem

A single item retrieved from a search, belonging to a specific result set.

Field	Type	Description
`memory`	`goodmem.v1.Memory`	The server does not use this field in the current implementation. Full memory definitions are sent via the `memory_definition` event.
`chunk`	`...t.RetrievedItem.ChunkReference`	A reference to a specific chunk within a memory.

RetrieveMemoryEvent.RetrievedItem.ChunkReference

A reference to a specific chunk, its relevance score, and a pointer to its parent memory definition within the stream.

Field	Type	Description
`result_set_id`	`bytes`	The ID of the result set this chunk belongs to.
`chunk`	`goodmem.v1.MemoryChunk`	The chunk data itself.
`memory_index`	`int32`	The index of this chunk's parent memory in the client-side cache of `Memory` definitions.
`relevance_score`	`double`	The relevance score of this chunk to the query.

CreateMemoryRequest

Create / Batch-create

Field	Type	Description
`memory_id`	`bytes`	Optional: client-provided UUID (16 bytes); server generates if omitted; returns ALREADY_EXISTS if ID exists
`space_id`	`bytes`	REQUIRED: The UUID of the space to create the memory in.
`original_content`	`bytes`	REQUIRED: The raw content of the memory.
`original_content_ref`	`string`	Optional: A URI pointing to the external source of the content.
`content_type`	`string`	REQUIRED: The MIME type of the content.
`metadata`	`google.protobuf.Struct`	Optional: Arbitrary JSON-like metadata.
`chunking_config`	`goodmem.v1.ChunkingConfig`	Optional; Overrides the default chunking config of the space.

BatchCreateMemoryRequest

Field	Type	Description
`requests`	`goodmem.v1.CreateMemoryRequest`

BatchCreateMemoryResponse

Field	Type	Description
`results`	`goodmem.v1.MemoryOrStatus`

GetMemoryRequest

Get / Batch-get

Field	Type	Description
`memory_id`	`bytes`	REQUIRED; The UUID of the memory to retrieve.
`include_content`	`bool`	If true, the `original_content` field of the memory will be populated.
`include_processing_history`	`bool`	If true, populates the `processing_history` field.

BatchGetMemoryRequest

Field	Type	Description
`memory_ids`	`bytes`	The list of memory UUIDs to retrieve.
`include_content`	`bool`	If true, populates the `original_content` field for all retrieved memories.
`include_processing_history`	`bool`	If true, populates the `processing_history` field for all memories.

BatchGetMemoryResponse

Field	Type	Description
`results`	`goodmem.v1.MemoryOrStatus`

ListMemoriesRequest

List with pagination

Field	Type	Description
`space_id`	`bytes`	REQUIRED; The UUID of the space to list memories from.
`status_filter`	`goodmem.v1.ProcessingStatus`	Optional; Filters memories by their processing status.
`max_results`	`int32`	Optional; The server does not currently support pagination and may ignore this.
`next_token`	`string`	Optional; An opaque token for fetching the next page. Not yet supported.
`sort_by`	`string`	Optional; Field to sort by (e.g., "created_at"). Behavior for unsupported fields is not defined.
`sort_order`	`goodmem.v1.SortOrder`	Optional; The direction to sort (ASCENDING or DESCENDING).
`include_content`	`bool`	Optional; If true, populates the `original_content` field.
`include_processing_history`	`bool`	If true, populates the `processing_history` field for each memory.

ListMemoriesResponse

Field	Type	Description
`memories`	`goodmem.v1.Memory`	A page of memory results.
`next_token`	`string`	An opaque token for fetching the next page. Not yet supported.

ListMemoriesNextPageToken

Internal cursor for ListMemories pagination. Not for client use.

Field	Type	Description
`start`	`int32`	The starting offset for the next page.
`space_id`	`bytes`	The space_id from the original request.
`status_filter`	`goodmem.v1.ProcessingStatus`	The status_filter from the original request.
`sort_by`	`string`	The sort_by field from the original request.
`sort_order`	`goodmem.v1.SortOrder`	The sort_order from the original request.
`requestor_id`	`bytes`	The UUID of the authenticated user for token validation.
`include_content`	`bool`	The include_content flag from the original request.
`include_processing_history`	`bool`	The include_processing_history flag from the original request.

DeleteMemoryRequest

Delete / Batch-delete

Field	Type	Description
`memory_id`	`bytes`	REQUIRED; The UUID of the memory to delete.

BatchDeleteMemoryRequest

Field	Type	Description
`memory_ids`	`bytes`	A list of memory UUIDs to delete.

DeleteResult

The result of a single deletion in a batch operation.

Field	Type	Description
`memory_id`	`bytes`	The UUID of the memory that was targeted for deletion.
`success`	`bool`	Whether the deletion was successful.
`error`	`google.rpc.Status`	If deletion failed, this contains the error details.

BatchDeleteMemoryResponse

Field	Type	Description
`results`	`goodmem.v1.DeleteResult`

Enums

RetrieveMemoryEvent.ResultSetBoundary.Kind

Name	Value	Description
`BEGIN`	0
`END`	1

ProcessingStatus

Common enums

Pipeline status for any process that can be queued, run and finish/fail.

Name	Value	Description
`PROCESSING_STATUS_UNSPECIFIED`	0	The default value. Invalid on writes.
`PENDING`	1	The job is queued and waiting to be processed.
`PROCESSING`	2	The job is actively being processed.
`COMPLETED`	3	The job finished successfully.
`FAILED`	4	The job ended with an error.

Memory

On this page