agentmemoryep

type AgentMemorySvc interface {
	ListMemories(ctx context.Context, req *ListMemoriesRequest) (*apiresource.List[apiresource.AgentMemory], *apierror.APIError)
	GetMemory(ctx context.Context, req *RetrieveMemoryRequest) (*apiresource.AgentMemory, *apierror.APIError)
	CreateMemory(ctx context.Context, req *CreateMemoryRequest) (*apiresource.AgentMemory, *apierror.APIError)
	UpdateMemory(ctx context.Context, req *UpdateMemoryRequest) (*apiresource.AgentMemory, *apierror.APIError)
	DeleteMemory(ctx context.Context, req *DeleteMemoryRequest) (*apiresource.EmptyResource, *apierror.APIError)
}

type AgentMemorySvcConfig struct {
	// AgentClient (required) is the agent-service gRPC client.
	AgentClient pb.AgentServiceClient
}

type CreateMemoryEndpoint struct{}

type CreateMemoryRequest struct {
	// The kind of information this memory holds, used to group related memories.
	//
	// - `preference`: how someone likes things done, such as a customer who always wants express shipping.
	// - `fact`: a durable detail worth remembering about the account or one of its records, such as a customer's typical order size.
	// - `instruction`: standing guidance for agents to follow, such as always confirming freight before issuing an order.
	Category constants.AgentMemoryCategory `json:"category" validate:"required"`
	// The information to remember, written as plain text for an agent to read.
	Content string `json:"content" validate:"required"`
	// Arbitrary metadata as JSON.
	Metadata json.RawMessage `json:"metadata,omitzero"`
	// Type of platform record this memory is scoped to (e.g. `customer`, `product`).
	//
	// Provide together with `entity_id` to scope the memory to a specific record; omit both for a memory that is not tied to any particular record.
	EntityType field.Optional[string] `json:"entity_type,omitzero" validate:"omitempty,max=255"`
	// ID of the platform record this memory is scoped to.
	//
	// Provide together with `entity_type`.
	EntityID field.Optional[string] `json:"entity_id,omitzero" validate:"omitempty"`
	// Relative importance from `0` to `1` in increments of `0.1`, used to prioritize which memories the agent recalls.
	//
	// An agent takes in only a limited number of memories per run and recalls the highest-importance ones first, so a memory created without an importance is stored at `0` and is the first to be left out.
	Importance field.Optional[float64] `json:"importance,omitzero" validate:"omitempty,min=0,max=1,multiple_of=0.1"`
	// When this memory should stop being used, as an ISO 8601 timestamp (e.g. `2026-01-02T15:04:05Z`).
	//
	// Past this time the memory is no longer recalled by agents and is omitted from list results, but it is not deleted. Omit it for a memory that should be used indefinitely.
	ExpiresAt field.Optional[string] `json:"expires_at,omitzero"`
}

type DeleteMemoryEndpoint struct{}

type DeleteMemoryRequest struct {
	// Memory ID.
	ID string `path:"id" validate:"required"`
}

type ListMemoriesEndpoint struct{}

type ListMemoriesRequest struct {
	apiresource.PaginationRequest
	// Filter to memories with this exact category (e.g. `preference`, `fact`).
	Category *constants.AgentMemoryCategory `query:"category"`
	// Filter to memories scoped to this entity type (e.g. `customer`, `product`).
	EntityType *string `query:"entity_type"`
}

type RetrieveMemoryEndpoint struct{}

type RetrieveMemoryRequest struct {
	// Memory ID.
	ID string `path:"id" validate:"required"`
}

type UpdateMemoryEndpoint struct{}

type UpdateMemoryRequest struct {
	// Memory ID.
	ID string `path:"id" validate:"required"`
	// The kind of information this memory holds, used to group related memories.
	//
	// - `preference`: how someone likes things done, such as a customer who always wants express shipping.
	// - `fact`: a durable detail worth remembering about the account or one of its records, such as a customer's typical order size.
	// - `instruction`: standing guidance for agents to follow, such as always confirming freight before issuing an order.
	Category field.Optional[constants.AgentMemoryCategory] `json:"category,omitzero"`
	// The information to remember, written as plain text for an agent to read.
	Content field.Optional[string] `json:"content,omitzero"`
	// Arbitrary metadata as JSON.
	//
	// Replaces the stored metadata outright rather than merging into it.
	Metadata json.RawMessage `json:"metadata,omitzero"`
	// Type of platform record this memory is scoped to (e.g. `customer`, `product`).
	//
	// Provide together with `entity_id` to scope the memory to a specific record; send `null` (on either entity field) to unscope the memory.
	EntityType field.Clearable[string] `json:"entity_type,omitzero" validate:"omitempty,max=255"`
	// ID of the platform record this memory is scoped to.
	//
	// Provide together with `entity_type`; send `null` to unscope the memory.
	EntityID field.Clearable[string] `json:"entity_id,omitzero" validate:"omitempty"`
	// Relative importance from `0` to `1` in increments of `0.1`, used to prioritize which memories the agent recalls.
	//
	// An agent takes in only a limited number of memories per run and recalls the highest-importance ones first.
	Importance field.Optional[float64] `json:"importance,omitzero" validate:"omitempty,min=0,max=1,multiple_of=0.1"`
	// When this memory should stop being used, as an ISO 8601 timestamp (e.g. `2026-01-02T15:04:05Z`).
	//
	// Past this time the memory is no longer recalled by agents and is omitted from list results, but it is not deleted. Send `null` so the memory is used indefinitely.
	ExpiresAt field.Clearable[string] `json:"expires_at,omitzero"`
}