// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.cloud.aiplatform.v1beta1;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/aiplatform/v1beta1/content.proto";
import "google/cloud/aiplatform/v1beta1/memory_bank.proto";
import "google/cloud/aiplatform/v1beta1/operation.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.AIPlatform.V1Beta1";
option go_package = "cloud.google.com/go/aiplatform/apiv1beta1/aiplatformpb;aiplatformpb";
option java_multiple_files = true;
option java_outer_classname = "MemoryBankServiceProto";
option java_package = "com.google.cloud.aiplatform.v1beta1";
option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1";
option ruby_package = "Google::Cloud::AIPlatform::V1beta1";

// A service for managing memories for LLM applications.
service MemoryBankService {
  option (google.api.default_host) = "aiplatform.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform";

  // Create a Memory.
  rpc CreateMemory(CreateMemoryRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*/locations/*/reasoningEngines/*}/memories"
      body: "memory"
      additional_bindings {
        post: "/v1beta1/{parent=reasoningEngines/*}/memories"
        body: "memory"
      }
    };
    option (google.api.method_signature) = "parent,memory,memory_id";
    option (google.longrunning.operation_info) = {
      response_type: "Memory"
      metadata_type: "CreateMemoryOperationMetadata"
    };
  }

  // Get a Memory.
  rpc GetMemory(GetMemoryRequest) returns (Memory) {
    option (google.api.http) = {
      get: "/v1beta1/{name=projects/*/locations/*/reasoningEngines/*/memories/*}"
      additional_bindings {
        get: "/v1beta1/{name=reasoningEngines/*/memories/*}"
      }
    };
    option (google.api.method_signature) = "name";
  }

  // Update a Memory.
  rpc UpdateMemory(UpdateMemoryRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      patch: "/v1beta1/{memory.name=projects/*/locations/*/reasoningEngines/*/memories/*}"
      body: "memory"
      additional_bindings {
        patch: "/v1beta1/{memory.name=reasoningEngines/*/memories/*}"
        body: "memory"
      }
    };
    option (google.api.method_signature) = "memory,update_mask";
    option (google.longrunning.operation_info) = {
      response_type: "Memory"
      metadata_type: "UpdateMemoryOperationMetadata"
    };
  }

  // List Memories.
  rpc ListMemories(ListMemoriesRequest) returns (ListMemoriesResponse) {
    option (google.api.http) = {
      get: "/v1beta1/{parent=projects/*/locations/*/reasoningEngines/*}/memories"
      additional_bindings {
        get: "/v1beta1/{parent=reasoningEngines/*}/memories"
      }
    };
    option (google.api.method_signature) = "parent";
  }

  // Delete a Memory.
  rpc DeleteMemory(DeleteMemoryRequest) returns (google.longrunning.Operation) {
    option (google.api.http) = {
      delete: "/v1beta1/{name=projects/*/locations/*/reasoningEngines/*/memories/*}"
      additional_bindings {
        delete: "/v1beta1/{name=reasoningEngines/*/memories/*}"
      }
    };
    option (google.api.method_signature) = "name";
    option (google.longrunning.operation_info) = {
      response_type: "google.protobuf.Empty"
      metadata_type: "DeleteMemoryOperationMetadata"
    };
  }

  // Generate memories.
  rpc GenerateMemories(GenerateMemoriesRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*/locations/*/reasoningEngines/*}/memories:generate"
      body: "*"
      additional_bindings {
        post: "/v1beta1/{parent=reasoningEngines/*}/memories:generate"
        body: "*"
      }
    };
    option (google.api.method_signature) = "parent";
    option (google.longrunning.operation_info) = {
      response_type: "GenerateMemoriesResponse"
      metadata_type: "GenerateMemoriesOperationMetadata"
    };
  }

  // Retrieve memories.
  rpc RetrieveMemories(RetrieveMemoriesRequest)
      returns (RetrieveMemoriesResponse) {
    option (google.api.http) = {
      post: "/v1beta1/{parent=projects/*/locations/*/reasoningEngines/*}/memories:retrieve"
      body: "*"
      additional_bindings {
        post: "/v1beta1/{parent=reasoningEngines/*}/memories:retrieve"
        body: "*"
      }
    };
    option (google.api.method_signature) = "parent";
  }
}

// Request message for
// [MemoryBankService.CreateMemory][google.cloud.aiplatform.v1beta1.MemoryBankService.CreateMemory].
message CreateMemoryRequest {
  // Required. The resource name of the ReasoningEngine to create the Memory
  // under. Format:
  // `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ReasoningEngine"
    }
  ];

  // Required. The Memory to be created.
  Memory memory = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. The user defined ID to use for memory, which will become the
  // final component of the memory resource name. If not provided, Vertex AI
  // will generate a value for this ID.
  //
  // This value may be up to 63 characters, and valid characters are
  // `[a-z0-9-]`. The first character must be a letter, and the last character
  // must be a letter or number.
  string memory_id = 3 [(google.api.field_behavior) = OPTIONAL];
}

// Details of
// [MemoryBankService.CreateMemory][google.cloud.aiplatform.v1beta1.MemoryBankService.CreateMemory]
// operation.
message CreateMemoryOperationMetadata {
  // The common part of the operation metadata.
  GenericOperationMetadata generic_metadata = 1;
}

// Request message for
// [MemoryBankService.GetMemory][google.cloud.aiplatform.v1beta1.MemoryBankService.GetMemory].
message GetMemoryRequest {
  // Required. The resource name of the Memory.
  // Format:
  // `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}/memories/{memory}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/Memory"
    }
  ];
}

// Request message for
// [MemoryBankService.UpdateMemory][google.cloud.aiplatform.v1beta1.MemoryBankService.UpdateMemory].
message UpdateMemoryRequest {
  // Required. The Memory which replaces the resource on the server.
  Memory memory = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. Mask specifying which fields to update.
  // Supported fields:
  //
  //    * `display_name`
  //    * `description`
  //    * `fact`
  google.protobuf.FieldMask update_mask = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// Details of
// [MemoryBankService.UpdateMemory][google.cloud.aiplatform.v1beta1.MemoryBankService.UpdateMemory]
// operation.
message UpdateMemoryOperationMetadata {
  // The common part of the operation metadata.
  GenericOperationMetadata generic_metadata = 1;
}

// Request message for
// [MemoryBankService.ListMemories][google.cloud.aiplatform.v1beta1.MemoryBankService.ListMemories].
message ListMemoriesRequest {
  // Required. The resource name of the ReasoningEngine to list the Memories
  // under. Format:
  // `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ReasoningEngine"
    }
  ];

  // Optional. The standard list filter.
  // More detail in [AIP-160](https://google.aip.dev/160).
  //
  // Supported fields (equality match only):
  //   * `scope` (as a JSON string)
  string filter = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The standard list page size.
  int32 page_size = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The standard list page token.
  string page_token = 4 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [MemoryBankService.ListMemories][google.cloud.aiplatform.v1beta1.MemoryBankService.ListMemories].
message ListMemoriesResponse {
  // List of Memories in the requested page.
  repeated Memory memories = 1;

  // A token to retrieve the next page of results.
  // Pass to
  // [ListMemoriesRequest.page_token][google.cloud.aiplatform.v1beta1.ListMemoriesRequest.page_token]
  // to obtain that page.
  string next_page_token = 2;
}

// Request message for
// [MemoryBankService.DeleteMemory][google.cloud.aiplatform.v1beta1.MemoryBankService.DeleteMemory].
message DeleteMemoryRequest {
  // Required. The resource name of the Memory to delete.
  // Format:
  // `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}/memories/{memory}`
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/Memory"
    }
  ];
}

// Details of
// [MemoryBankService.DeleteMemory][google.cloud.aiplatform.v1beta1.MemoryBankService.DeleteMemory]
// operation.
message DeleteMemoryOperationMetadata {
  // The common part of the operation metadata.
  GenericOperationMetadata generic_metadata = 1;
}

// Request message for
// [MemoryBankService.GenerateMemories][google.cloud.aiplatform.v1beta1.MemoryBankService.GenerateMemories].
message GenerateMemoriesRequest {
  // Defines an Agent Engine Session from which to generate the memories. If
  // `scope` is not provided, the scope will be extracted from the Session
  // (i.e. {"user_id": sesison.user_id}).
  message VertexSessionSource {
    // Required. The resource name of the Session to generate memories for.
    // Format:
    // `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}/sessions/{session}`
    string session = 1 [
      (google.api.field_behavior) = REQUIRED,
      (google.api.resource_reference) = {
        type: "aiplatform.googleapis.com/Session"
      }
    ];

    // Optional. Time range to define which session events should be used to
    // generate memories. Start time (inclusive) of the time range. If not set,
    // the start time is unbounded.
    google.protobuf.Timestamp start_time = 2
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. End time (exclusive) of the time range. If not set, the end
    // time is unbounded.
    google.protobuf.Timestamp end_time = 3
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Defines a direct source of content from which to generate the memories.
  message DirectContentsSource {
    // A single piece of conversation from which to generate memories.
    message Event {
      // Required. A single piece of content from which to generate memories.
      Content content = 1 [(google.api.field_behavior) = REQUIRED];
    }

    // Required. The source content (i.e. chat history) to generate memories
    // from.
    repeated Event events = 1 [(google.api.field_behavior) = REQUIRED];
  }

  // Defines a direct source of memories that should be uploaded to Memory Bank
  // with consolidation.
  message DirectMemoriesSource {
    // A direct memory to upload to Memory Bank.
    message DirectMemory {
      // Required. The fact to consolidate with existing memories.
      string fact = 1 [(google.api.field_behavior) = REQUIRED];
    }

    // Required. The direct memories to upload to Memory Bank. At most 5 direct
    // memories are allowed per request.
    repeated DirectMemory direct_memories = 1
        [(google.api.field_behavior) = REQUIRED];
  }

  // Source content used to generate memories.
  oneof source {
    // Defines a Vertex Session as the source content from which to generate
    // memories.
    VertexSessionSource vertex_session_source = 2;

    // Defines a direct source of content as the source content from which to
    // generate memories.
    DirectContentsSource direct_contents_source = 3;

    // Defines a direct source of memories that should be uploaded to Memory
    // Bank. This is similar to `CreateMemory`, but it allows for consolidation
    // between these new memories and existing memories for the same scope.
    DirectMemoriesSource direct_memories_source = 9;
  }

  // Required. The resource name of the ReasoningEngine to generate memories
  // for. Format:
  // `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ReasoningEngine"
    }
  ];

  // Optional. If true, generated memories will not be consolidated with
  // existing memories; all generated memories will be added as new memories
  // regardless of whether they are duplicates of or contradictory to existing
  // memories. By default, memory consolidation is enabled.
  bool disable_consolidation = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The scope of the memories that should be generated. Memories will
  // be consolidated across memories with the same scope. Must be provided
  // unless the scope is defined in the source content. If `scope` is provided,
  // it will override the scope defined in the source content. Scope values
  // cannot contain the wildcard character '*'.
  map<string, string> scope = 8 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [MemoryBankService.GenerateMemories][google.cloud.aiplatform.v1beta1.MemoryBankService.GenerateMemories].
message GenerateMemoriesResponse {
  // A memory generated by the operation.
  message GeneratedMemory {
    // Actions that can be performed on a Memory.
    enum Action {
      // Action is unspecified.
      ACTION_UNSPECIFIED = 0;

      // The memory was created.
      CREATED = 1;

      // The memory was updated. The `fact` field may not be updated if the
      // existing fact is still accurate.
      UPDATED = 2;

      // The memory was deleted.
      DELETED = 3;
    }

    // The generated Memory.
    Memory memory = 1;

    // The action that was performed on the Memory.
    Action action = 2;
  }

  // The generated memories.
  repeated GeneratedMemory generated_memories = 1;
}

// Details of
// [MemoryBankService.GenerateMemories][google.cloud.aiplatform.v1beta1.MemoryBankService.GenerateMemories]
// operation.
message GenerateMemoriesOperationMetadata {
  // The common part of the operation metadata.
  GenericOperationMetadata generic_metadata = 1;
}

// Request message for
// [MemoryBankService.RetrieveMemories][google.cloud.aiplatform.v1beta1.MemoryBankService.RetrieveMemories].
message RetrieveMemoriesRequest {
  // Parameters for semantic similarity search based retrieval.
  message SimilaritySearchParams {
    // Required. Query to use for similarity search retrieval. If provided, then
    // the parent ReasoningEngine must have
    // [ReasoningEngineContextSpec.MemoryBankConfig.SimilaritySearchConfig][google.cloud.aiplatform.v1beta1.ReasoningEngineContextSpec.MemoryBankConfig.SimilaritySearchConfig]
    // set.
    string search_query = 1 [(google.api.field_behavior) = REQUIRED];

    // Optional. The maximum number of memories to return.
    // The service may return fewer than this value. If unspecified, at most 3
    // memories will be returned. The maximum value is 100; values above 100
    // will be coerced to 100.
    int32 top_k = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // Parameters for simple (non-similarity search) retrieval.
  message SimpleRetrievalParams {
    // Optional. The maximum number of memories to return.
    // The service may return fewer than this value. If unspecified, at most 3
    // memories will be returned. The maximum value is 100; values above 100
    // will be coerced to 100.
    int32 page_size = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. A page token, received from a previous `RetrieveMemories` call.
    // Provide this to retrieve the subsequent page.
    string page_token = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // Parameters for retrieval.
  oneof retrieval_params {
    // Parameters for semantic similarity search based retrieval.
    SimilaritySearchParams similarity_search_params = 6;

    // Parameters for simple (non-similarity search) retrieval.
    SimpleRetrievalParams simple_retrieval_params = 7;
  }

  // Required. The resource name of the ReasoningEngine to retrieve memories
  // from. Format:
  // `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}`
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "aiplatform.googleapis.com/ReasoningEngine"
    }
  ];

  // Required. The scope of the memories to retrieve. A memory must have
  // exactly the same scope (`Memory.scope`) as the scope provided here to be
  // retrieved (same keys and values). Order does not matter, but it is
  // case-sensitive.
  map<string, string> scope = 8 [(google.api.field_behavior) = REQUIRED];
}

// Response message for
// [MemoryBankService.RetrieveMemories][google.cloud.aiplatform.v1beta1.MemoryBankService.RetrieveMemories].
message RetrieveMemoriesResponse {
  // A retrieved memory.
  message RetrievedMemory {
    // The retrieved Memory.
    Memory memory = 1;

    // The distance between the query and the retrieved Memory. Smaller values
    // indicate more similar memories. This is only set if similarity search was
    // used for retrieval.
    double distance = 2;
  }

  // The retrieved memories.
  repeated RetrievedMemory retrieved_memories = 1;

  // A token that can be sent as `page_token` to retrieve the next page.
  // If this field is omitted, there are no subsequent pages.
  // This token is not set if similarity search was used for retrieval.
  string next_page_token = 2;
}