Package com.tnsai.annotations

Annotation Interface VectorMemory

@Documented @Retention(RUNTIME) @Target(TYPE) public @interface VectorMemory
Configures vector memory for an Agent class.

When applied to an Agent class, this annotation enables automatic VectorMemoryStore configuration with the specified provider and settings.

Supported Providers

  • inmemory — bundled cosine store (default)
  • qdrant / pgvector — require a VectorStoreProvider on the classpath; unknown names fail agent initialization instead of silently using TF-IDF
  • milvus — not shipped; register your own provider or use inmemory

Usage Examples

Basic usage (in-memory): 


 @VectorMemory(collection = "agent-memories")
 public class SmartAgent extends Agent { }

With Qdrant: 


 @VectorMemory(
     provider = "qdrant",
     collection = "agent-memories",
     host = "localhost",
     port = 6334
 )
 public class SmartAgent extends Agent { }

With environment-based configuration: 


 @VectorMemory(
     provider = "qdrant",
     collection = "agent-memories",
     hostEnv = "QDRANT_HOST",
     portEnv = "QDRANT_PORT"
 )
 public class SmartAgent extends Agent { }

Embedding Configuration

The embedding service is configured via embeddingProvider() and embeddingModel(). Supported embedding providers:

  • openai - OpenAI text-embedding models
  • ollama - Local Ollama embedding models
Author:
TnsAI Team
See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    collection
    The collection/table name for storing vectors.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    int
    circuitBreakerThreshold
    Circuit breaker failure threshold.
    int
    dimension
    The embedding dimension.
    String
    embeddingApiKeyEnv
    Environment variable name for the embedding API key.
    String
    embeddingModel
    The embedding model to use.
    String
    embeddingProvider
    The embedding provider to use.
    String
    host
    The host for the vector store (for remote providers).
    String
    hostEnv
    Environment variable name for the host.
    int
    maxRetries
    Maximum retry attempts for failed operations.
    int
    port
    The port for the vector store (for remote providers).
    String
    portEnv
    Environment variable name for the port.
    String
    provider
    The vector store provider to use.
    boolean
    resilient
    Whether to enable resilience features (retry + circuit breaker).

  • Element Details

    • provider

      String provider
      The vector store provider to use.

      Supported values: inmemory (bundled). qdrant, pgvector and any other name require a registered VectorStoreProvider. Missing SPI fails loudly.

      Returns:
      provider name (default: inmemory)
      Default:
      "inmemory"

    • collection

      String collection
      The collection/table name for storing vectors.
      Returns:
      collection name (required)

    • dimension

      int dimension
      The embedding dimension.

      Common values:

      • 1536 - OpenAI text-embedding-3-small
      • 3072 - OpenAI text-embedding-3-large
      • 768 - nomic-embed-text (Ollama)
      Returns:
      dimension (default: 1536 for OpenAI)
      Default:
      1536

    • host

      String host
      The host for the vector store (for remote providers).
      Returns:
      host address (default: localhost)
      Default:
      "localhost"

    • port

      int port
      The port for the vector store (for remote providers).

      Default ports:

      • Qdrant: 6334
      • Milvus: 19530
      • PostgreSQL: 5432
      Returns:
      port number (default: 6334 for Qdrant)
      Default:
      6334

    • hostEnv

      String hostEnv
      Environment variable name for the host.

      If set, overrides host().

      Returns:
      environment variable name
      Default:
      ""

    • portEnv

      String portEnv
      Environment variable name for the port.

      If set, overrides port().

      Returns:
      environment variable name
      Default:
      ""

    • embeddingProvider

      String embeddingProvider
      The embedding provider to use.

      Supported values: openai, ollama

      Returns:
      embedding provider name (default: openai)
      Default:
      "openai"

    • embeddingModel

      String embeddingModel
      The embedding model to use.

      Examples:

      • OpenAI: text-embedding-3-small, text-embedding-3-large
      • Ollama: nomic-embed-text, mxbai-embed-large
      Returns:
      model name (default: text-embedding-3-small)
      Default:
      "text-embedding-3-small"

    • embeddingApiKeyEnv

      String embeddingApiKeyEnv
      Environment variable name for the embedding API key.

      Default: OPENAI_API_KEY for OpenAI provider.

      Returns:
      environment variable name for API key
      Default:
      "OPENAI_API_KEY"

    • resilient

      boolean resilient
      Whether to enable resilience features (retry + circuit breaker).
      Returns:
      true to enable resilience (default: true)
      Default:
      true

    • maxRetries

      int maxRetries
      Maximum retry attempts for failed operations.
      Returns:
      max retries (default: 3)
      Default:
      3

    • circuitBreakerThreshold

      int circuitBreakerThreshold
      Circuit breaker failure threshold.

      Number of consecutive failures before opening the circuit.

      Returns:
      failure threshold (default: 5)
      Default:
      5