// 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/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/aiplatform/v1beta1/content.proto";
import "google/cloud/aiplatform/v1beta1/openapi.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.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 = "MemoryBankProto";
option java_package = "com.google.cloud.aiplatform.v1beta1";
option php_namespace = "Google\\Cloud\\AIPlatform\\V1beta1";
option ruby_package = "Google::Cloud::AIPlatform::V1beta1";

// The type of Memory.
enum MemoryType {
  // Represents an unspecified memory type. This value should not be used.
  MEMORY_TYPE_UNSPECIFIED = 0;

  // Indicates belonging to a collection of natural language memories.
  NATURAL_LANGUAGE_COLLECTION = 1;

  // Indicates belonging to a structured profile.
  STRUCTURED_PROFILE = 3;
}

// A memory.
message Memory {
  option (google.api.resource) = {
    type: "aiplatform.googleapis.com/Memory"
    pattern: "projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}/memories/{memory}"
    pattern: "projects/{project}/locations/{location}/memoryBanks/{memory_bank}/memories/{memory}"
    plural: "memories"
    singular: "memory"
  };

  // Represents the structured value of the memory.
  message StructuredContent {
    // Required. Represents the structured value of the memory.
    google.protobuf.Struct data = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. Represents the schema ID for which this structured memory
    // belongs to.
    string schema_id = 2 [(google.api.field_behavior) = REQUIRED];
  }

  // The expiration of the Memory. If not set, the Memory will not be
  // automatically deleted.
  oneof expiration {
    // Optional. Represents the timestamp of when this resource is considered
    // expired. This is *always* provided on output when `expiration` is set on
    // input, regardless of whether `expire_time` or `ttl` was provided.
    google.protobuf.Timestamp expire_time = 13
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Input only. Represents the TTL for this resource. The
    // expiration time is computed: now + TTL.
    google.protobuf.Duration ttl = 14 [(google.api.field_behavior) = OPTIONAL];
  }

  // (Input-only) The expiration of the Memory Revision created as a result of
  // this request. If not set, Memory Bank will defer to
  // `MemoryBankConfig.memory_revision_default_ttl` or the global default, 365
  // days.
  oneof revision_expiration {
    // Optional. Input only. Represents the timestamp of when the revision is
    // considered expired. If not set, the memory revision will be kept until
    // manually deleted.
    google.protobuf.Timestamp revision_expire_time = 16 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.field_behavior) = INPUT_ONLY
    ];

    // Optional. Input only. Represents the TTL for the revision. The expiration
    // time is computed: now + TTL.
    google.protobuf.Duration revision_ttl = 17 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.field_behavior) = INPUT_ONLY
    ];

    // Optional. Input only. Indicates whether no revision will be created for
    // this request.
    bool disable_memory_revisions = 18 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.field_behavior) = INPUT_ONLY
    ];
  }

  // Identifier. Represents the resource name of the Memory.
  // Format:
  // `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}/memories/{memory}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Optional. Represents the display name of the Memory.
  string display_name = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Represents the description of the Memory.
  string description = 3 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Represents the timestamp when this Memory was created.
  google.protobuf.Timestamp create_time = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the timestamp when this Memory was most recently
  // updated.
  google.protobuf.Timestamp update_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Represents semantic knowledge extracted from the source content.
  string fact = 10 [(google.api.field_behavior) = OPTIONAL];

  // Required. Immutable. Represents the scope of the Memory. Memories are
  // isolated within their scope. The scope is defined when creating or
  // generating memories. Scope values cannot contain the wildcard character
  // '*'.
  map<string, string> scope = 11 [(google.api.field_behavior) = REQUIRED];

  // Optional. Represents the Topics of the Memory.
  repeated MemoryTopicId topics = 15 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Input only. Represents the labels to apply to the Memory Revision
  // created as a result of this request.
  map<string, string> revision_labels = 19 [
    (google.api.field_behavior) = OPTIONAL,
    (google.api.field_behavior) = INPUT_ONLY
  ];

  // Optional. Represents user-provided metadata for the Memory. This
  // information was provided when creating, updating, or generating the Memory.
  // It was not generated by Memory Bank.
  map<string, MemoryMetadataValue> metadata = 21
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Represents the type of the memory. If not set, the
  // `NATURAL_LANGUAGE_COLLECTION` type is used. If `STRUCTURED_COLLECTION` or
  // `STRUCTURED_PROFILE` is used, then `structured_data` must be provided.
  MemoryType memory_type = 22 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Represents the structured content of the memory.
  StructuredContent structured_content = 24
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Represents the context of the memory.
  string context = 25 [(google.api.field_behavior) = OPTIONAL];
}

// A memory topic identifier.
// This will be used to label a Memory and to restrict which topics are eligible
// for generation or retrieval.
message MemoryTopicId {
  // Represents a topic identifier.
  oneof topic_id {
    // Optional. Represents the custom memory topic label.
    string custom_memory_topic_label = 1
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Represents the managed memory topic.
    MemoryBankCustomizationConfig.MemoryTopic.ManagedMemoryTopic
        .ManagedTopicEnum managed_memory_topic = 2
        [(google.api.field_behavior) = OPTIONAL];
  }
}

// Represents configuration for organizing natural language memories for a
// particular scope.
message MemoryBankCustomizationConfig {
  // A topic of information that should be extracted from conversations and
  // stored as memories.
  message MemoryTopic {
    // A custom memory topic defined by the developer.
    message CustomMemoryTopic {
      // Required. Represents the label of the topic.
      string label = 1 [(google.api.field_behavior) = REQUIRED];

      // Required. Represents the description of the memory topic. This should
      // explain what information should be extracted for this topic.
      string description = 2 [(google.api.field_behavior) = REQUIRED];
    }

    // A managed memory topic defined by the system.
    message ManagedMemoryTopic {
      // Represents managed topics.
      enum ManagedTopicEnum {
        // Represents an unspecified topic. This value should not be used.
        MANAGED_TOPIC_ENUM_UNSPECIFIED = 0;

        // Represents significant personal information about the User like first
        // names, relationships, hobbies, important dates.
        USER_PERSONAL_INFO = 1;

        // Represents stated or implied likes, dislikes, preferred styles, or
        // patterns.
        USER_PREFERENCES = 2;

        // Represents important milestones or conclusions within the dialogue.
        KEY_CONVERSATION_DETAILS = 3;

        // Represents information that the user explicitly requested to remember
        // or forget.
        EXPLICIT_INSTRUCTIONS = 4;
      }

      // Required. Represents the managed topic.
      ManagedTopicEnum managed_topic_enum = 1
          [(google.api.field_behavior) = REQUIRED];
    }

    // Represents the type of the topic.
    oneof topic_type {
      // A custom memory topic defined by the developer.
      CustomMemoryTopic custom_memory_topic = 3;

      // A managed memory topic defined by Memory Bank.
      ManagedMemoryTopic managed_memory_topic = 4;
    }
  }

  // An example of how to generate memories for a particular scope.
  message GenerateMemoriesExample {
    // A conversation source for the example. This is similar to
    // `DirectContentsSource`.
    message ConversationSource {
      // A single conversation event.
      message Event {
        // Required. Represents the content of the event.
        Content content = 1 [(google.api.field_behavior) = REQUIRED];
      }

      // Optional. Represents the input conversation events for the example.
      repeated Event events = 1 [(google.api.field_behavior) = OPTIONAL];
    }

    // A memory generated by the operation.
    message GeneratedMemory {
      // Required. Represents the fact to generate a memory from.
      string fact = 1 [(google.api.field_behavior) = REQUIRED];

      // Optional. Represents the list of topics that the memory should be
      // associated with. For example, use `custom_memory_topic_label =
      // "jargon"` if the extracted memory is an example of memory extraction
      // for the custom topic `jargon`.
      repeated MemoryTopicId topics = 2
          [(google.api.field_behavior) = OPTIONAL];
    }

    // Represents the input source for the example.
    oneof source {
      // A conversation source for the example.
      ConversationSource conversation_source = 3;
    }

    // Optional. Represents the memories that are expected to be generated from
    // the input conversation. An empty list indicates that no memories are
    // expected to be generated for the input conversation.
    repeated GeneratedMemory generated_memories = 4
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Represents configuration for customizing how memories are consolidated.
  message ConsolidationConfig {
    // Optional. Represents the maximum number of revisions to consider for each
    // candidate memory. If not set, then the default value (1) will be used,
    // which means that only the latest revision will be considered.
    int32 revisions_per_candidate_count = 1
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Optional. Represents the scope keys (i.e. 'user_id') for which to use this
  // config. A request's scope must include all of the provided keys for the
  // config to be used (order does not matter). If empty, then the config will
  // be used for all requests that do not have a more specific config. Only one
  // default config is allowed per Memory Bank.
  repeated string scope_keys = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Represents topics of information that should be extracted from
  // conversations and stored as memories. If not set, then Memory Bank's
  // default topics will be used.
  repeated MemoryTopic memory_topics = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Provides examples of how to generate memories for a particular
  // scope.
  repeated GenerateMemoriesExample generate_memories_examples = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Indicates whether the memories will be generated in the third
  // person (i.e. "The user generates memories with Memory Bank."). By default,
  // the memories will be generated in the first person (i.e. "I generate
  // memories with Memory Bank.")
  bool enable_third_person_memories = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Represents configuration for customizing how memories are
  // consolidated together.
  ConsolidationConfig consolidation_config = 5
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Indicates whether natural language memory generation should be
  // disabled for all requests. By default, natural language memory generation
  // is enabled. Set this to `true` when you only want to generate structured
  // memories.
  bool disable_natural_language_memories = 6
      [(google.api.field_behavior) = OPTIONAL];
}

// Represents configuration for organizing structured memories for a particular
// scope.
message StructuredMemoryConfig {
  // Schema configuration for structured memories.
  message SchemaConfig {
    // Required. Represents the ID of the schema. Must be 1-63 characters, start
    // with a lowercase letter, and consist of lowercase letters, numbers, and
    // hyphens.
    string id = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. Represents the OpenAPI schema of the structured memories. The
    // schema `type` cannot be `ARRAY` when `memory_type` is
    // `STRUCTURED_PROFILE`.
    Schema schema = 2 [(google.api.field_behavior) = REQUIRED];

    // Optional. Represents the type of the structured memories associated with
    // the schema. If not set, then `STRUCTURED_PROFILE` will be used.
    MemoryType memory_type = 3 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Represents the JSON Schema of the structured memories.
    google.protobuf.Value json_schema = 5
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Optional. Represents the scope keys (i.e. 'user_id') for which to use this
  // config. A request's scope must include all of the provided keys for the
  // config to be used (order does not matter). If empty, then the config will
  // be used for all requests that do not have a more specific config. Only one
  // default config is allowed per Memory Bank.
  repeated string scope_keys = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Represents configuration of the structured memories' schemas.
  repeated SchemaConfig schema_configs = 2
      [(google.api.field_behavior) = OPTIONAL];
}

// A revision of a Memory.
message MemoryRevision {
  option (google.api.resource) = {
    type: "aiplatform.googleapis.com/MemoryRevision"
    pattern: "projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}/memories/{memory}/revisions/{memory_revision}"
    pattern: "projects/{project}/locations/{location}/memoryBanks/{memory_bank}/memories/{memory}/revisions/{memory_revision}"
    plural: "memoryRevisions"
    singular: "memoryRevision"
  };

  // Identifier. Represents the resource name of the Memory Revision.
  // Format:
  // `projects/{project}/locations/{location}/reasoningEngines/{reasoning_engine}/memories/{memory}/revisions/{memory_revision}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. Represents the timestamp when this Memory Revision was
  // created.
  google.protobuf.Timestamp create_time = 2
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the timestamp of when this resource is considered
  // expired.
  google.protobuf.Timestamp expire_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the fact of the Memory Revision. This corresponds
  // to the `fact` field of the parent Memory at the time of revision creation.
  string fact = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the labels of the Memory Revision. These labels are
  // applied to the MemoryRevision when it is created based on
  // `GenerateMemoriesRequest.revision_labels`.
  map<string, string> labels = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the extracted memories from the source content
  // before consolidation when the memory was updated via GenerateMemories. This
  // information was used to modify an existing Memory via Consolidation.
  repeated IntermediateExtractedMemory extracted_memories = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the structured value of the memory at the time of
  // revision creation.
  google.protobuf.Struct structured_data = 7
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the context of the Memory Revision. The context may
  // include context from both the historical revisions and the extracted
  // content.
  string context = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// An extracted memory that is the intermediate result before consolidation.
message IntermediateExtractedMemory {
  // Output only. Represents the fact of the extracted memory.
  string fact = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the structured value of the extracted memory.
  google.protobuf.Struct structured_data = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the explanation of why the information was
  // extracted from the source content.
  string context = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Memory metadata.
message MemoryMetadataValue {
  // Represents the value of the metadata.
  oneof value {
    // Represents a string value.
    string string_value = 1;

    // Represents a double value.
    double double_value = 2;

    // Represents a boolean value.
    bool bool_value = 3;

    // Represents a timestamp value. When filtering on timestamp values, only
    // the seconds field will be compared.
    google.protobuf.Timestamp timestamp_value = 4;
  }
}

// A conjunction of filters that will be combined using AND logic.
message MemoryConjunctionFilter {
  // Represents filters that will be combined using AND logic.
  repeated MemoryFilter filters = 1;
}

// Filter to apply when retrieving memories.
message MemoryFilter {
  // Represents the operator to apply to the filter.
  enum Operator {
    // Represents an unspecified operator. Defaults to EQUAL.
    OPERATOR_UNSPECIFIED = 0;

    // Equal to.
    EQUAL = 1;

    // Greater than.
    GREATER_THAN = 2;

    // Less than.
    LESS_THAN = 3;
  }

  // Represents the key of the filter. For example, "author" would apply to
  // `metadata` entries with the key "author".
  string key = 1;

  // Represents the operator to apply to the filter. If not set, then EQUAL
  // will be used.
  Operator op = 2;

  // Represents the value to compare to.
  MemoryMetadataValue value = 3;

  // Indicates whether the filter will be negated.
  bool negate = 4;
}

// Represents configuration for triggering generation.
message MemoryGenerationTriggerConfig {
  // Represents the active rule that determines when to flush the buffer.
  message GenerationTriggerRule {
    // Represents the time based condition that triggers generation.
    oneof time_based_condition {
      // Optional. Specifies to trigger generation if the stream is inactive for
      // the specified duration after the most recent event. The duration must
      // have a minute-level granularity.
      google.protobuf.Duration idle_duration = 1
          [(google.api.field_behavior) = OPTIONAL];

      // Optional. Specifies to trigger generation at a fixed interval. The
      // duration must have a minute-level granularity.
      google.protobuf.Duration fixed_interval = 2
          [(google.api.field_behavior) = OPTIONAL];
    }

    // Specifies how much context to carry over from one generation window into
    // the next, so that memories stay coherent across GenerateMemories calls.
    // Carried-over events do not count toward the trigger rule.
    oneof overlap_window {
      // Optional. Re-include the last N already-processed events in the next
      // window.
      int32 overlap_event_count = 5 [(google.api.field_behavior) = OPTIONAL];
    }

    // Optional. Specifies to trigger generation when the event count reaches
    // this limit.
    int32 event_count = 4 [(google.api.field_behavior) = OPTIONAL];
  }

  // Optional. Represents the active rule that determines when to flush the
  // buffer. If not set, then the stream will be force flushed immediately.
  GenerationTriggerRule generation_rule = 1
      [(google.api.field_behavior) = OPTIONAL];
}

// A memory profile.
message MemoryProfile {
  // Represents the ID of the schema. This ID corresponds to the `schema_id`
  // defined inside the SchemaConfig, under StructuredMemoryCustomizationConfig.
  string schema_id = 1;

  // Represents the profile data.
  google.protobuf.Struct profile = 2;
}