TiM4Rec: An Efficient Sequential Recommendation Model Based on Time-Aware Structured State Space Duality Model

Due to the laboratory regulations, the article has not been officially published before the model source code is not allowed to be published, so the current repository is not complete, but do not worry, we will supplement the complete model code immediately after the article is officially published. You can also first check the performance of the TiM4Rec model by using the training log files we published. 😊

Update: 🎉 TiM4Rec Accepted by Neurocomputing!, We've open-sourced the full model code as promised!

---

如果您想阅读中文版本，请点击README_CN.md 。

1. Introduction

TiM4Rec: An Efficient Sequential Recommendation Model Based on Time-Aware Structured State Space Duality Model
Hao Fan, Mengyi Zhu, Yanrong Hu, Hailin Feng, Zhijie He, Hongjiu Liu, Qingyang Liu
Paper: https://doi.org/10.1016/j.neucom.2025.131270 (⚠️ Limited-Time Free Access: Thanks to Elsevier's share link, the publisher's version is free to read and download until October 12, 2025. Access it here Limited time license)
Preprint: https://arxiv.org/abs/2409.16182

We propose TiM4Rec(Time-aware Mamba For Recommendation), an efficient sequential recommendation model based on Time-aware SSD. We conducted a pioneering exploration of the time-aware enhancement methods of the Mamba architecture in the field of sequential recommendation. Through an in-depth analysis of SSM and SSD, we propose, for the first time, a time-aware enhancement method with linear computational complexity that is applicable to the SSD architecture.

In the following, we will guide you how to use this repository step by step. 🤗

2. Preparation

git clone https://github.com/AlwaysFHao/TiM4Rec.git
cd TiM4Rec/

2.1 Environment Requirements

The following are the main runtime environment dependencies for running the repository：

• cuda 11.8
• python 3.10.14
• pytorch 2.3.0
• recbole 1.2.0
• mamba-ssm 2.2.2
• casual-conv1d 1.2.2 (Since we implemented the casual-conv1d equivalent using 'nn.Conv1d', this entry is optional)
• psutil 6.1.0
• numpy 1.26.4

If you are having trouble installing Mamba, please refer to the installation tutorial we wrote: https://github.com/AlwaysFHao/Mamba-Install.

You can also view detailed environment information in File environment.yaml.

2.2 DataSets

This work utilizes the following four datasets, among which 🎦 MovieLens-1M, 🛒 Amazon-Beauty and 🎮 Steam datasets are provided by RecBole, 📱 KuaiRand dataset is provided by the author of SSD4Rec.

All dataset files can be obtained from the cloud storage: Quark Drive (password: SVzs) / BaiDu Cloud Drive (password: 1296) / Google Drive.

• 🎦 MovieLens-1M: A dataset containing approximately 1 million user ratings for movies, collected from the MovieLens platform.
• 🛒 Amazon-Beauty: The user review dataset collected in the beauty category on the Amazon platform was compiled up to the year 2014.
• 📱 KuaiRand: Acquired from the recommendation logs of the application KuaiShou, the dataset includes millions of interactions involving items that were randomly displayed.
• 🎮 Steam: The dataset collected by Kang et al. (SASRec authors) consists of user ratings from the Steam platform spanning from 2010 to 2018, which has been widely adopted as an evaluation benchmark in prior work.

2.3 Project Structure

In this section, you can learn about our project structure.

You can click on the directory below to expand and view the project structure:

📁 TiM4Rec

• 📁 assert | (Store readme related images)
• 📁 baseline | (The baseline model is covered in the paper)
• 📁 BERT4Rec
• 📜 config.yaml
• 🐍 run.py
• 📁 ...
• 📁 config | (Configuration file for TiM4Rec model)
• 📜 config4beauty_64d.yaml
• 📜 config4kuai_64d.yaml
• 📜 config4movie_64d.yaml
• 📜 config4movie_256d.yaml
• 📁 dataset | (Store dataset files)
• 📁 amazon-beauty
• 📖 amazon-beauty.inter
• 📖 amazon-beauty.item
• 📁 ...
• 📁 log | (Training log file)
• 📁 log_tensorboard | (Training log file of tensorboard)
• 📁 saved | (Saved model weight file)
• 📜 environment.yaml
• 🐍 run.py
• 🐍 ssd.py
• 🐍 test.py
• 🐍 tim4rec.py

You can download files from the cloud storage and put them in the corresponding folder. Quark Drive (password: SVzs) / BaiDu Cloud Drive (password: 1296) / Google Drive.

3. Run

Ok, congratulations 🎇, you have finished all the preparation 👍, let's start training the model! 😄

This section will introduce the training methods of the model.

Note: Since the SSD kernel is implemented with Triton and includes auto-tuning, the model requires a warm-up during the first iteration. Please record the actual runtime of TiM4Rec starting from the second epoch(refer to Mamba2 Author's Answer).

3.1 TiM4Rec

After preparing all the necessary files and runtime environment, please modify the configuration file path in 🐍 run.py in the following format:

config = Config(model=TiM4Rec, config_file_list=['config/config4{dataset_name}_{dim}d.yaml'])

Just run it directly：

python run.py

If you want to continue checkpoint training, you need to add the model weight path to the checkpoint_path configuration item in the corresponding configuration file.

checkpoint_path: saved/model_weight_name.pth

3.2 Baseline(Optional)

You can directly select the baseline model we have organized in the 📁 baseline folder for training, taking SASRec as an example.

cd ./baseline/SASRec
python run.py

3.3 Model testing

If you want to directly test the performance of a specified model weight, you can refer to the method in section 3.1, modify the configuration file name in the 🐍 test.py file and add the checkpoint_path item in the corresponding configuration file, and then perform the test:

python test.py

4. Acknowledgements

Our code implementation is based on the RecBole and Pytorch frameworks, and references the work of Mamba4Rec and Mamba. The replication of the baseline model is referenced from TiSASRec.pytorch and LRURec. In addition, our readme document was written with reference to MISSRec.

5. References

If you find this code useful or use the toolkit in your work, please consider citing:

@article{fan2025tim4rec,
  title = {TiM4Rec: An efficient sequential recommendation model based on time-aware structured state space duality model},
  author = {Hao Fan and Mengyi Zhu and Yanrong Hu and Hailin Feng and Zhijie He and Hongjiu Liu and Qingyang Liu},
  journal = {Neurocomputing},
  volume = {654},
  pages = {131270},
  year = {2025},
  issn = {0925-2312},
  doi = {https://doi.org/10.1016/j.neucom.2025.131270},
  url = {https://www.sciencedirect.com/science/article/pii/S0925231225019423},
  keywords = {Sequential recommendation, State space model (SSM), State space duality (SSD), Mamba, Time-awareness},
}

@misc{fan2024tim4rec,
  title={TiM4Rec: An Efficient Sequential Recommendation Model Based on Time-Aware Structured State Space Duality Model},
  author = {Hao Fan and Mengyi Zhu and Yanrong Hu and Hailin Feng and Zhijie He and Hongjiu Liu and Qingyang Liu},
  journal = {CoRR},
  volume = {abs/2409.16182},
  year = {2024},
  doi = {10.48550/ARXIV.2409.16182},
  eprinttype = {arXiv},
  eprint = {2409.16182},
  timestamp = {Wed, 16 Oct 2024 13:28:37 +0200},
  archivePrefix="arXiv"
}