Memory System Architecture
Relevant source files
The following files were used as context for generating this wiki page:
- Ai-Assistant-v2/auth-service/models/Memory.js
- Ai-Assistant-v2/auth-service/routes/memories.js
- Ai-Assistant-v2/auth-service/services/aiService.js
- backend/services/memory_service.py
- backend/services/memory_extraction_service.py
- backend/modules/memory/routes.py
- Ai-Assistant-v2/auth-service/routes/ai.js
- README.md
The Memory System Architecture is a multi-layered framework designed to provide persistent, context-aware intelligence for the AI Assistant. It facilitates the extraction, storage, and retrieval of factual information from user interactions to enhance the relevance of AI-generated responses. The system operates across a Node.js orchestration layer (Auth Service) and a Python AI service, utilizing MongoDB for persistent storage and vector-based search for similarity retrieval.
The primary scope includes automatic memory extraction from chat history, importance-based ranking, and a retrieval-augmented generation (RAG) flow that injects relevant past facts into new conversation prompts.
Sources: README.md:32-37, Ai-Assistant-v2/auth-service/routes/ai.js:10-18
Core Components and Data Flow
The architecture follows a distributed pattern where the Node.js service manages database transactions and orchestration, while the Python service handles the computational heavy lifting of extraction and similarity scoring.
High-Level Service Interaction
The following diagram illustrates the interaction between the User, the Orchestration Service (Node.js), and the AI Service (Python) during memory operations.
Memory Data Model
The system uses a standardized schema to represent a "Memory" or "Fact". This includes metadata for traceability (source conversation) and scoring for prioritization.
| Field | Type | Description |
|---|---|---|
userId | ObjectId | Reference to the owner of the memory. |
fact | String | The actual content or information extracted. |
importanceScore | Number | Ranking (0.0 to 1.0) of how significant the fact is. |
tags | Array[String] | Categories (e.g., 'preference', 'profile', 'fact'). |
embedding | Array[Number] | Vector representation for similarity search (384-dim). |
sourceConversationId | ObjectId | Reference to the chat where the fact originated. |
Sources: Ai-Assistant-v2/auth-service/models/Memory.js:3-37, backend/app.py:114
Memory Extraction Logic
Memories are extracted either in real-time during a chat or through a batch "training" process. The MemoryExtractionService in the Python backend uses heuristics to identify significant statements.
Extraction Heuristics
The system scans user messages for specific patterns to determine if a fact should be memorized:
- Strong Sentiment: Messages with sentiment scores > 0.5 (e.g., "I love this!").
- Personal Profile: Phrases like "My name is", "I am", or "I'm".
- Preferences: Keywords such as "I like", "I prefer", or "I enjoy".
- Possession/Identity: Use of "is", "my", or "have" (e.g., "My car is red").
- Commands: Directives identified with the 'command' intent.
Sources: backend/services/memory_extraction_service.py:44-90, backend/services/memory_service.py:136-165
Retrieval and Training
The system uses a Retrieval-Augmented Generation (RAG) approach to ensure the AI "remembers" past interactions.
Vector-Based Retrieval
Before generating a response, the Node.js service performs a similarity search.
- Embedding Generation: The user's query is converted into a vector (embedding).
- Similarity Search: The service compares the query vector against stored memory vectors using cosine similarity.
- Context Injection: Top relevant facts (e.g.,
top_k=5) are appended to the AI prompt.
Sources: Ai-Assistant-v2/auth-service/routes/ai.js:250-264, backend/services/memory_service.py:53-112
Training Process
The "Train Memory" feature allows the system to retrospectively analyze the last 5 conversations to find facts it might have missed during real-time processing.
API Endpoints
The memory system is managed via the following key endpoints in the Auth Service (5001) and Python Service (5000).
Node.js Auth Service (v1)
| Method | Endpoint | Description |
|---|---|---|
GET | /api/v1/memories | List all user memories, sorted by importance. |
POST | /api/v1/memories | Manually store a memory. |
POST | /api/v1/memories/train | Extract memories from recent chat history. |
DELETE | /api/v1/memories/:id | Delete a specific memory record. |
GET | /api/v1/memories/count | Get the total number of memories for the user. |
Sources: Ai-Assistant-v2/auth-service/routes/memories.js:6-230, README.md:124-129
Python AI Service
| Method | Endpoint | Description |
|---|---|---|
POST | /extract-memory | Stateless extraction of facts from provided text. |
POST | /embed | Generates a 384-dimension vector for text. |
POST | /similarity | Computes cosine similarity between two vectors. |
Sources: backend/app.py:84-135, README.md:144-149
Implementation Example: Memory Creation
The following snippet demonstrates how a memory is persisted in the Node.js layer after being identified as high-importance.
// From Ai-Assistant-v2/auth-service/routes/ai.js
const memory = new Memory({
userId: req.user.userId,
fact: candidate.fact,
importanceScore: candidate.importanceScore,
tags: candidate.tags || [],
sourceConversationId: conversation._id,
sourceMessageId: conversation.messages[conversation.messages.length - 2]._id
});
await memory.save();
Sources: Ai-Assistant-v2/auth-service/routes/ai.js:80-87
Conclusion
The Memory System provides a persistent "brain" for the AI Assistant, bridging the gap between stateless AI models and personalized user experiences. By combining heuristic extraction in Python with MongoDB storage and vector retrieval in Node.js, the system ensures that relevant user facts—such as names, preferences, and commands—are consistently available to the AI across different conversation sessions.