Memory Extraction & Training
Relevant source files
The following files were used as context for generating this wiki page:
The Memory Extraction & Training system is a core component designed to transform transient conversation messages into persistent, structured facts known as "memories." This system enables the AI Assistant to maintain long-term context about users, such as their preferences, personal details, and past commands. The process involves identifying significant information during real-time chat or through bulk "training" sessions that analyze historical dialogue.
Sources: README.md, backend/services/memory_extraction_service.py:1-10, Ai-Assistant-v2/auth-service/routes/ai.js:10-20
Memory Architecture & Data Models
The system operates across a dual-service architecture. The Node.js Auth Service manages the persistent storage of memories in MongoDB, including vector embeddings for similarity search. The Python AI Service performs the stateless logic of extracting facts from text using natural language processing and heuristics.
Memory Data Structure
Memories are stored with metadata to support retrieval ranking and source attribution.
| Field | Type | Description |
|---|---|---|
userId | ObjectId | Reference to the owner of the memory. |
fact | String | The actual content or statement extracted. |
importanceScore | Number | A value (0.0 to 1.0) indicating the relevance or strength of the fact. |
tags | Array[String] | Categories such as 'preference', 'profile', or 'sentiment'. |
embedding | Array[Number] | Vector representation (384-dim) for similarity search. |
sourceConversationId | ObjectId | Reference to the conversation where the fact was found. |
Sources: Ai-Assistant-v2/auth-service/models/Memory.js:3-38, backend/services/memory_service.py:20-30
Memory Extraction Logic
The extraction process utilizes a stateless MemoryExtractionService in the Python backend. It scans user messages for specific linguistic patterns and metadata (like intent or sentiment) to generate "memory candidates."
Extraction Heuristics
The service identifies facts based on several criteria:
- Personal Info: Keywords like "my name is" or "I am" trigger high-importance (0.9) profile tags.
- Preferences: Phrases like "I like" or "I prefer" are tagged as preferences with medium importance (0.7).
- Linguistic Heuristics: Presence of "is," "my," or "have" suggests potential factual statements (0.6).
- Sentiment-Driven: Statements with high absolute sentiment scores (> 0.5) are extracted to capture user feelings.
- Intent-Driven: If a message is classified as a 'command', it is stored as an action-oriented memory (0.8).
Sources: backend/services/memory_extraction_service.py:35-85
Extraction Flow
The following diagram illustrates how a user message is processed into a candidate memory.
Training System
"Training" refers to the process of batch-processing recent conversation history to find and store new memories that were not captured during real-time interaction.
Training Workflow
- Context Retrieval: The system fetches the last 5 conversations for the authenticated user.
- Aggregation: All user messages are concatenated into a single text block.
- Remote Extraction: The text is sent to the Python Service's
/extract-memoryendpoint. - Deduplication & Embedding: For each candidate returned, the system checks if a similar fact already exists in MongoDB. If new, it generates a vector embedding via
vectorServiceand saves the memory.
Sources: Ai-Assistant-v2/auth-service/routes/memories.js:75-125, backend/services/memory_service.py:145-170
Training Sequence
The interaction between the Auth Service and AI Service during a training session is shown below:
Memory Retrieval & Reasoning
Once stored, memories are used to provide context for future AI responses. This is handled by a combination of vector similarity and scoring.
Retrieval Process
The system uses the MemoryService (Python) or vectorService (Node) to find relevant facts:
- Query Vectorization: The current user message is converted into an embedding.
- Similarity Calculation: A cosine similarity check is performed against the user's stored memory embeddings.
- Keyword Fallback: If vector similarity is low, a simple keyword overlap check boosts scores for memories containing exact words from the query.
- Context Injection: The top relevant memories are injected into the AI prompt to guide the response.
Sources: backend/services/memory_service.py:48-95, backend/modules/memory/reasoning.py:6-20
Memory Ranking
Memories are ranked based on a combination of their initial importance score and their relevance to the current query.
| Component | Logic | Source |
|---|---|---|
| Initial Score | Based on extraction heuristics (e.g., Profile = 0.9). | memory_extraction_service.py |
| Similarity Score | Cosine similarity between query and memory embedding. | memory_service.py |
| Manual Override | Users can update importance via PUT /api/v1/memories/:id. | memories.js |
Sources: Ai-Assistant-v2/auth-service/routes/memories.js:144-175, backend/services/memory_service.py:100-110
Conclusion
The Memory Extraction & Training module creates a persistent "personality" for the assistant by grounding AI responses in user-specific facts. By combining automated extraction heuristics during chat with proactive training cycles, the system ensures that the knowledge base grows organically with every interaction. This structured memory is then retrieved using vector-based reasoning to ensure the AI remains contextually aware over long periods.