Chroma Vector Database Sync
Relevant source files
The following files were used as context for generating this wiki page:
The Chroma Vector Database Sync is a core service within Claude-mem that provides real-time semantic search capabilities. It functions by automatically synchronizing observations, session summaries, and user prompts from the primary SQLite storage into a ChromaDB instance via the Model Context Protocol (MCP). This system enables the AI to perform intelligent context retrieval using vector embeddings rather than relying solely on keyword-based lookups.
The service is designed with a "fail-fast" philosophy: it operates without fallbacks, meaning that if the Chroma server is unavailable, the synchronization process fails. This ensures data integrity and predictable behavior within the search pipeline. The integration is essential for features like the mem-search skill, which uses hybrid semantic and keyword search to provide persistent memory across sessions.
Sources: src/services/sync/ChromaSync.ts:7-14, CLAUDE.md:21-21, README.md:144-144
Architecture and Components
The synchronization system is built around the ChromaSync class, which manages the lifecycle of the connection to the Chroma MCP server. It handles everything from establishing the initial connection using the uvx Python tool to creating project-specific collections and formatting data into granular vector documents.
Connection Management
The service uses a StdioClientTransport to communicate with the Chroma MCP server. It specifically attempts to use a persistent client type and stores data in a dedicated directory within the user's home folder (~/.claude-mem/vector-db).
The diagram above illustrates the connection lifecycle managed by the ensureConnection and ensureCollection methods.
Sources: src/services/sync/ChromaSync.ts:79-115, src/services/sync/ChromaSync.ts:133-162
Key Classes and Interfaces
| Component | Description |
|---|---|
ChromaSync | The primary service class responsible for connecting to Chroma and performing CRUD operations. |
ChromaDocument | Interface defining the structure of a vector document, including ID, text content, and metadata. |
StoredObservation | The internal representation of memory observations retrieved from SQLite for synchronization. |
StoredSummary | The internal representation of session summaries for synchronization. |
StoredUserPrompt | The representation of user queries captured during a session. |
Sources: src/services/sync/ChromaSync.ts:24-76
Data Transformation and Granularity
To maximize semantic retrieval accuracy, the system employs a "granular approach" to document creation. Rather than storing a single large document for an observation or summary, it splits different semantic fields into separate vector documents.
Observation Mapping
When an observation is synced, it is decomposed into multiple Chroma documents based on its internal fields:
- Narrative: Stored as a
narrativefield type. - Facts: Each individual fact in the JSON array is stored as a separate document with a
fact_index. - Concepts: Stored within the metadata of related documents.
- Legacy Text: Included as a
textfield type if present.
Sources: src/services/sync/ChromaSync.ts:168-215
Metadata Schema
All documents shared a common base of metadata to allow for efficient filtering during search:
| Field | Type | Description |
|---|---|---|
sqlite_id | number | The primary key from the SQLite database. |
doc_type | string | Either observation, session_summary, or user_prompt. |
project | string | The name of the project/repository. |
memory_session_id | string | The unique ID of the Claude session. |
field_type | string | The specific part of the data (e.g., fact, learned, request). |
Sources: src/services/sync/ChromaSync.ts:180-210, src/services/sync/ChromaSync.ts:223-230
Synchronization Workflows
The system supports both real-time synchronization of new events and a "smart backfill" process for existing data.
Real-time Sync
Real-time sync occurs within the SDKAgent loop. As the agent parses XML responses from Claude, it simultaneously stores them in SQLite and calls ChromaSync to update the vector database.
This sequence demonstrates the fire-and-forget synchronization pattern used during active sessions to avoid blocking the main agent loop.
Sources: src/services/worker/SDKAgent.ts:291-325, src/services/sync/ChromaSync.ts:286-310
Smart Backfill
The ensureBackfilled method is used to reconcile Chroma with SQLite. It performs a metadata-only fetch of all IDs currently in Chroma to determine which SQLite records are missing, then syncs them in batches of 100.
Sources: src/services/sync/ChromaSync.ts:439-556
Semantic Search Orchestration
The SearchManager utilizes Chroma as the primary entry point for queries involving text content. It follows a hybrid search logic where Chroma provides the semantic candidates, which are then hydrated and filtered using SQLite.
Search Logic Flow
- Chroma Query: Search Chroma for the top 100 semantic matches.
- Recency Filtering: Filter results to a 90-day window (
RECENCY_WINDOW_DAYS = 90). - Type Categorization: Sort IDs into observations, sessions, or prompts.
- SQLite Hydration: Fetch full records from SQLite using the filtered IDs and apply additional metadata filters (e.g., specific file paths or concepts).
Sources: src/services/worker/SearchManager.ts:83-145
Search Configuration
| Parameter | Default | Description |
|---|---|---|
BATCH_SIZE | 100 | Number of documents sent to Chroma in a single MCP call. |
RECENCY_WINDOW_DAYS | 90 | The cutoff period for semantic search results. |
limit (Query) | 20 | Default number of results returned by the search manager. |
Sources: src/services/sync/ChromaSync.ts:76, src/services/worker/SearchManager.ts:17-18
Implementation Details
Configuration and Environment
The service relies on uv to manage the Python environment required for Chroma. It uses Python 3.13 by default to avoid compatibility issues with onnxruntime. On Windows, it attempts to hide the console window to prevent PowerShell popups.
// src/services/sync/ChromaSync.ts:90-106
const transportOptions: any = {
command: 'uvx',
args: [
'--python', pythonVersion,
'chroma-mcp',
'--client-type', 'persistent',
'--data-dir', this.VECTOR_DB_DIR
],
stderr: 'ignore'
};
Sources: src/services/sync/ChromaSync.ts:90-112
Search Query Parameters
The queryChroma method translates internal search requests into MCP chroma_query_documents tool calls.
// src/services/sync/ChromaSync.ts:581-587
const arguments_obj = {
collection_name: this.collectionName,
query_texts: [query],
n_results: limit,
include: ['documents', 'metadatas', 'distances'],
where: whereStringified
};
Sources: src/services/sync/ChromaSync.ts:581-587
Conclusion
Chroma Vector Database Sync provides the semantic foundation for Claude-mem's persistent memory. By decomposing complex observations into granular vector documents and maintaining a strict synchronization link with the primary SQLite store, it enables high-accuracy retrieval of past work context. Its integration within the search pipeline, featuring 90-day recency windows and hybrid metadata filtering, ensures that the AI receives the most relevant and timely information for every query.