AI Memory System
Relevant source files
The following files were used as context for generating this wiki page:The AI Memory System provides Amina with long-term conversational memory, allowing it to recall facts, preferences, and context from past interactions. This system is designed to create more personalized and context-aware conversations by storing and retrieving information about users.
The system uses a hybrid storage architecture, leveraging MongoDB for structured metadata and Upstash Vector for high-speed semantic search. It is primarily managed by the MemoryService, which works in conjunction with the AiResponderService to automatically extract, store, and recall memories during conversations. Users can also manage their memories through dedicated /mina-ai commands.
Architecture
The AI Memory System is composed of several key components that work together to provide a seamless memory function. The core logic is encapsulated in MemoryService, which orchestrates interactions between the AI model (Google Generative AI), the vector database (Upstash), and the metadata store (MongoDB).
Sources: src/services/memoryService.ts, src/database/schemas/AiMemory.ts
High-Level Component Diagram
This diagram illustrates the main components and their interactions within the memory system.
Core Components
| Component | Description | Relevant Files |
|---|---|---|
MemoryService | A singleton class that centralizes all memory-related operations, including extraction, storage, recall, and deletion. It interfaces with external services like Google AI and Upstash. | src/services/memoryService.ts |
AiMemory Schema | The Mongoose schema defining the structure for memory metadata stored in MongoDB. It includes fields for user/guild context, the memory content, importance, and a link to the Upstash vector. | src/database/schemas/AiMemory.ts |
| Upstash Vector | A vector database used to store embeddings of memories. It enables fast and efficient semantic search to find relevant memories based on conversational context. | src/services/memoryService.ts:32-42, package.json:20-20 |
| Google Generative AI | Used for two key tasks: 1. Generating vector embeddings for memories using the embedding-001 model. 2. Extracting structured facts from conversation history using the gemini-flash-latest model. | src/services/memoryService.ts:28-30, src/services/memoryService.ts:60-63, src/services/memoryService.ts:121-124 |
AiResponderService | Integrates the memory system into the AI's response flow. It calls memoryService.recallMemories to fetch context before generating a response and memoryService.extractAndStoreMemories to learn from the interaction afterward. | src/services/aiResponder.ts:401-480, src/services/aiResponder.ts:681-684 |
Data Schema
The ai-memory collection in MongoDB stores the metadata for each memory. The vector representation of the memory is stored separately in Upstash Vector, linked by the vectorId.
Sources: src/database/schemas/AiMemory.ts:5-24
ER Diagram
This diagram shows the entity relationship for an AI Memory.
Field Descriptions
| Field | Type | Description | Constraints |
|---|---|---|---|
userId | String | The Discord user ID the memory belongs to. | required, index |
guildId | String | The Discord guild ID where the memory was created. null for DMs. | index, default: null |
memoryType | String | The category of the memory. | enum: ['user', 'guild', 'topic'], default: 'user' |
key | String | A short, descriptive key for the memory (e.g., "Favorite Color"). | required |
value | String | The value of the memory (e.g., "Blue"). | required |
context | String | A snippet of the conversation that led to the memory's creation. | default: '' |
importance | Number | A score from 1 to 10 indicating the memory's importance. | default: 5, min: 1, max: 10 |
vectorId | String | The unique identifier for the corresponding vector in Upstash. | required, unique |
lastAccessedAt | Date | Timestamp of the last time the memory was recalled. | default: Date.now |
accessCount | Number | How many times the memory has been recalled. | default: 0 |
Sources: src/database/schemas/AiMemory.ts:5-24
Core Processes
The memory system follows two primary workflows: storing new memories and recalling existing ones.
Memory Extraction and Storage
This process occurs after an AI response is generated. The system analyzes the recent conversation to extract and persist new, relevant facts.
This sequence diagram shows the flow of extracting and storing a new memory.
Memory Recall
This process happens when a new message is received that the AI should respond to. The system fetches relevant memories to provide context for the AI's response.
This sequence diagram shows the memory recall process.
Memory Management and Pruning
To prevent unbounded growth and keep the memory store relevant, the system employs several management strategies:
- Per-User Limit: A hard limit of
MAX_MEMORIES_PER_USER(set to 50) is enforced per user, per context (guild or DM). When a new memory is added that exceeds this limit, the oldest, least important memories are automatically deleted from both MongoDB and Upstash. - Automatic Pruning: A
pruneOldMemoriesfunction is available to delete memories that are older than 90 days, have an importance score of 3 or less, and have been accessed 2 or fewer times. - User-Initiated Deletion: Users can delete all their memories at any time.
Sources: src/services/memoryService.ts:24-24, src/services/memoryService.ts:150-169, src/services/memoryService.ts:389-403, src/database/schemas/AiMemory.ts:100-123
User-Facing Features
Users can interact with their memory profile through the /mina-ai command group.
Sources: src/handlers/minaai/memories.ts, src/handlers/minaai/forget-me.ts
Viewing Memories (/mina-ai memories)
The memories command provides an interactive interface for users to view the information Amina has stored about them.
- Main View: Shows a summary of memories, grouped by type (
user,guild,topic), with a preview of the most relevant ones. - Category View: Users can select a category to see a paginated list of all memories within that type.
- DM Export: A "DM Me" button allows the user to receive a private message containing a link to a Pastebin with a full, detailed list of all their memories.
The UI text for these interactions is defined in respMinaAi.json.
Sources: src/handlers/minaai/memories.ts:22-386, src/data/respMinaAi.json:2-33
Forgetting Memories (/mina-ai forget-me)
This feature allows users to exercise their right to be forgotten.
- Confirmation: The user is presented with a confirmation screen explaining that the action is irreversible.
- Deletion: Upon confirmation, the
memoryService.forgetUsermethod is called, which deletes all of the user's memories from both MongoDB and Upstash for the current context (server or DMs). - Ignore Flag: After deletion, the
ignoreMeflag is automatically set totrueon the user's profile, preventing the AI from interacting with them or creating new memories until they toggle it off.
Sources: src/handlers/minaai/forget-me.ts:14-80
Administration & Statistics
Developers can monitor the health and usage of the memory system via a dedicated developer command.
Memory Statistics (/dev mina-ai memory-stats)
The memoryStats command, accessible to developers, provides a high-level overview of the memory system. It calls memoryService.getStats(), which aggregates data from the AiMemory model.
The following statistics are displayed:
- Total number of stored memories.
- Number of unique users with memories.
- Number of unique guilds with memories.
- A breakdown of memories by type.
- A list of the top 10 users by memory count.
- The average importance score across all memories.
- The total number of times memories have been accessed (recalled).
Sources: src/commands/dev/sub/minaAi.ts:289-358, src/services/memoryService.ts:322-387