Vector Embeddings & Search

Relevant source files

The following files were used as context for generating this wiki page:

• Ai-Assistant-v2/auth-service/services/vectorService.js
• Ai-Assistant-v2/auth-service/server.js
• backend/app.py
• Ai-Assistant-v2/auth-service/routes/memories.js
• Ai-Assistant-v2/auth-service/routes/ai.js
• README.md

The Vector Embeddings & Search system is a critical component of the AI Assistant's long-term memory architecture. It enables the platform to transform textual information into high-dimensional numerical vectors (embeddings), allowing for semantic similarity searches rather than simple keyword matching. This system is primarily used to retrieve relevant user "memories" during a conversation to provide contextually aware responses.

The architecture is split between the Node.js Auth & Orchestration Service, which handles memory management and similarity calculations, and the Python AI Service, which generates the actual embeddings using machine learning models.
Sources: README.md:14-43, Ai-Assistant-v2/auth-service/server.js:14-17

System Architecture & Data Flow

The vector search workflow begins when a user sends a message. The system generates an embedding for the query, compares it against stored memory embeddings, and injects the most relevant facts into the AI model's context.

Semantic Search Workflow

The following diagram illustrates how a user query triggers a vector-based memory retrieval process.

Embedding Generation

Embeddings are generated by the Python backend via the EmbeddingService. Each text string is converted into a 384-dimensional vector.

API Endpoint: /embed

The Python service exposes an endpoint to generate vectors for any given text.

Parameter	Type	Description
text	String	The content to be converted into a vector.
Response	JSON	Contains embedding (Array) and dimension (384).

Sources: backend/app.py:118-135, README.md:107

Implementation Detail

The Node.js service consumes this via the VectorService class:

async generateEmbedding(text) {
    try {
        const response = await axios.post(`${PYTHON_AI_URL}/embed`, { text });
        if (response.data.success) {
            return response.data.data.embedding;
        }
        return null;
    } catch (error) {
        console.error('Error generating embedding:', error.message);
        return null;
    }
}

Sources: Ai-Assistant-v2/auth-service/services/vectorService.js:10-23

Similarity Computation

The system uses Cosine Similarity to determine the mathematical "distance" between the user's current query and their stored memories. This calculation is performed in-memory within the Node.js service for retrieval.

Vector Comparison Logic

The similarity score ranges from -1 to 1, where 1 represents identical semantic meaning.

Cosine Similarity Algorithm

The mathematical implementation involves calculating the dot product of two vectors divided by the product of their magnitudes.
Sources: Ai-Assistant-v2/auth-service/services/vectorService.js:56-72

Memory Storage and Retrieval

Memories are stored in MongoDB with their corresponding embedding vectors. When training the memory system, the platform extracts facts from conversations and immediately generates embeddings for them.

Memory Data Model

Field	Type	Description
userId	ObjectId	Owner of the memory.
fact	String	The textual content (e.g., "User likes pizza").
embedding	Array(Number)	The 384-dimensional vector.
importanceScore	Number	Priority of the memory (0.0 to 1.0).
tags	Array(String)	Metadata tags (e.g., "preference", "extracted").

Sources: Ai-Assistant-v2/auth-service/routes/memories.js:77-90, Ai-Assistant-v2/auth-service/routes/ai.js:63-75

Retrieval Logic

During a chat session, the system follows these steps:

1. Embed Query: The user's current message is sent to the Python service for embedding.
2. Fetch Pool: All memories belonging to the user are retrieved from MongoDB.
3. Similarity Search: vectorService.findSimilarMemories is called to find the top 5 most relevant facts.
4. Context Injection: These memories are passed to the AI model to inform its response.

Sources: Ai-Assistant-v2/auth-service/server.js:241-255, Ai-Assistant-v2/auth-service/routes/ai.js:63-75

Training and Manual Management

The vector system supports both manual entry and automated "training" through conversation analysis.

• Manual Storage: Users can store memories via POST /api/v1/memories. The system generates an embedding upon storage.
• Memory Training: The POST /api/v1/memories/train endpoint extracts facts from the last 5 conversations. It uses the Python service to identify facts, then calls vectorService.generateEmbedding before saving them to the database.

Sources: Ai-Assistant-v2/auth-service/routes/memories.js:41-55, Ai-Assistant-v2/auth-service/routes/memories.js:77-105

Conclusion

Vector Embeddings & Search provide the semantic foundation for the AI Assistant's retrieval-augmented generation (RAG) capabilities. By decoupling vector generation (Python) from storage and similarity logic (Node.js), the system maintains a balance between ML performance and application orchestration. This allows the assistant to maintain a persistent, searchable memory that evolves with user interaction.
Sources: README.md:14-25, Ai-Assistant-v2/auth-service/server.js:235-250