MemScheduler: The Scheduler for Memory Organization

MemScheduler is a concurrent memory management system parallel running with the MemOS system, which coordinates memory operations between working memory, long-term memory, and activation memory in AI systems. It handles memory retrieval, updates, and compaction through event-driven scheduling.
This system is particularly suited for conversational agents and reasoning systems requiring dynamic memory management.

Key Features

🚀 Concurrent operation with MemOS system
🧠 Multi-memory coordination (Working/Long-Term/User memory)
⚡ Event-driven scheduling for memory operations
🔍 Efficient retrieval of relevant memory items
📊 Comprehensive monitoring of memory usage
📝 Detailed logging for debugging and analysis

Memory Scheduler Architecture

The MemScheduler system is structured around several key components:

Message Handling: Processes incoming messages through a dispatcher with labeled handlers
Memory Management: Manages different memory types (Working, Long-Term, User)
Retrieval System: Efficiently retrieves relevant memory items based on context
Monitoring: Tracks memory usage, frequencies, and triggers updates
Dispatcher (Router): Trigger different memory reorganization strategies by checking messages from MemOS systems.
Logging: Maintains logs of memory operations for debugging and analysis

Message Processing

The scheduler processes messages through a dispatcher with dedicated handlers:

Message Types

Message Type	Handler Method	Description
`QUERY_LABEL`	`_query_message_consume`	Handles user queries and triggers retrieval
`ANSWER_LABEL`	`_answer_message_consume`	Processes answers and updates memory usage

Schedule Message Structure

The scheduler processes messages from its queue using the following format:

ScheduleMessageItem:

Field	Type	Description
`item_id`	`str`	UUID (auto-generated) for unique identification
`user_id`	`str`	Identifier for the associated user
`mem_cube_id`	`str`	Identifier for the memory cube
`label`	`str`	Message label (e.g., `QUERY_LABEL`, `ANSWER_LABEL`)
`mem_cube`	`GeneralMemCube｜str`	Memory cube object or reference
`content`	`str`	Message content
`timestamp`	`datetime`	Time when the message was submitted

Meanwhile the scheduler will send the scheduling messages by following structures.

ScheduleLogForWebItem:

Field	Type	Description	Default Value
`item_id`	`str`	Unique log entry identifier (UUIDv4)	Auto-generated (`uuid4()`)
`user_id`	`str`	Associated user identifier	(Required)
`mem_cube_id`	`str`	Linked memory cube ID	(Required)
`label`	`str`	Log category identifier	(Required)
`from_memory_type`	`str`	Source memory partition Possible values: - `"LongTermMemory"` - `"UserMemory"` - `"WorkingMemory"`	(Required)
`to_memory_type`	`str`	Destination memory partition	(Required)
`log_content`	`str`	Detailed log message	(Required)
`current_memory_sizes`	`MemorySizes`	Current memory utilization	DEFAULT_MEMORY_SIZES = { "long_term_memory_size": -1, "user_memory_size": -1, "working_memory_size": -1, "transformed_act_memory_size": -1 }
`memory_capacities`	`MemoryCapacities`	Memory partition limits	DEFAULT_MEMORY_CAPACITIES = { "long_term_memory_capacity": 10000, "user_memory_capacity": 10000, "working_memory_capacity": 20, "transformed_act_memory_capacity": -1 }
`timestamp`	`datetime`	Log creation time	Auto-set (`datetime.now`)

Execution Example

examples/mem_scheduler/schedule_w_memos.py is a demonstration script showcasing how to utilize the MemScheduler module. It illustrates memory management and retrieval within conversational contexts.

Code Functionality Overview

This script demonstrates two methods for initializing and using the memory scheduler:

Automatic Initialization: Configures the scheduler via configuration files
Manual Initialization: Explicitly creates and configures scheduler components

The script simulates a pet-related conversation between a user and an assistant, demonstrating how memory scheduler manages conversation history and retrieves relevant information.

MemReader

This guide walks you through how to use the SimpleStructMemReader to extract structured memories from conversations and documents using LLMs and embedding models. It is ideal for building memory-aware conversational AI, knowledge bases, and semantic search systems.

LLMs and Embeddings

A practical guide to configuring and using Large Language Models (LLM) and Embedders in MemOS.