Skip to content

ChromaDB Storage

For common Agent integration, extraction modes, and tool configuration, see Usage and Configuration.

Use case: Self-hosted ChromaDB or Chroma Cloud with cosine semantic and hybrid memory search

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
import (
    openaiembedder "trpc.group/trpc-go/trpc-agent-go/knowledge/embedder/openai"
    memorychromadb "trpc.group/trpc-go/trpc-agent-go/memory/chromadb"
)

embedder := openaiembedder.New(
    openaiembedder.WithModel("text-embedding-3-small"),
)

chromaService, err := memorychromadb.NewService(
    memorychromadb.WithBaseURL("http://localhost:8000"),
    memorychromadb.WithCollectionName("memories"),
    memorychromadb.WithEmbedder(embedder),
    memorychromadb.WithSoftDelete(true),
)
if err != nil {
    // handle error
}
defer chromaService.Close()

This is a client-server REST adapter, not an embedded Chroma runtime. Start a Chroma server separately, or point WithBaseURL at a remote deployment or Chroma Cloud. Embeddings are generated by the configured tRPC-Agent-Go embedder.Embedder; the adapter does not install or invoke a Chroma server-side embedding function.

For Chroma Cloud, add WithAPIKey; it is sent as X-Chroma-Token. The service resolves the unique tenant and database from the identity endpoint unless they are set explicitly. Bearer and custom-header authentication are available through WithBearerToken and WithHTTPHeaders, primarily for proxies and custom gateways. Custom authentication headers require explicit tenant and database values. Any authenticated or custom-header connection to a non-loopback host must use HTTPS.

Configuration options:

  • Connection: WithBaseURL, WithAPIKey, WithBearerToken, WithHTTPHeaders, WithTenant, WithDatabase, WithHTTPClient, WithTimeout
  • Collection: WithCollectionName, WithAutoCreateCollection, WithIndexDimension, WithEmbedder
  • Retrieval: WithMaxResults, WithSimilarityThreshold, WithHybridCandidateLimit
  • Retention: WithMemoryLimit, WithSoftDelete
  • Auto mode and tools use the same options as other memory backends.

The adapter uses ChromaDB REST API v2 directly and requires an existing HNSW or SPANN index configured with cosine. Records are isolated by schema, application, and user metadata inside one collection. The per-user memory limit is serialized within one service instance; use a distributed lock or sticky routing if multiple instances write the same user concurrently.

Keep these operational constraints in mind:

  • Changing the embedding model requires a new collection or re-embedding every record, even when the old and new models have the same vector dimension.
  • EventTime values and search time bounds must fit in signed 64-bit Unix nanoseconds, from 1677-09-21 through 2262-04-11 UTC. Values outside this range are rejected before a ChromaDB request is made.
  • WithHybridCandidateLimit is the hard cap for the local keyword candidate scan; it is independent of WithMemoryLimit.
  • Capacity checks, ID rotation, and paginated reads are best-effort across multiple service instances because Chroma does not expose transactions or a pagination snapshot token for this workflow.
  • Chroma Cloud currently documents a 128-byte collection-name limit, up to 300 query results, up to 300 records per write, and 10 concurrent reads and 10 concurrent writes per collection. The adapter documents but does not silently clamp these service limits.