MemoryOS 0.0.1__tar.gz → 0.1.12__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of MemoryOS might be problematic. Click here for more details.

Files changed (120) hide show
  1. memoryos-0.1.12/PKG-INFO +257 -0
  2. memoryos-0.1.12/README.md +225 -0
  3. {memoryos-0.0.1 → memoryos-0.1.12}/pyproject.toml +39 -6
  4. memoryos-0.1.12/src/memos/__init__.py +20 -0
  5. memoryos-0.1.12/src/memos/api/start_api.py +420 -0
  6. memoryos-0.1.12/src/memos/chunkers/__init__.py +4 -0
  7. memoryos-0.1.12/src/memos/chunkers/base.py +24 -0
  8. memoryos-0.1.12/src/memos/chunkers/factory.py +22 -0
  9. memoryos-0.1.12/src/memos/chunkers/sentence_chunker.py +35 -0
  10. memoryos-0.1.12/src/memos/configs/__init__.py +0 -0
  11. memoryos-0.1.12/src/memos/configs/base.py +82 -0
  12. memoryos-0.1.12/src/memos/configs/chunker.py +45 -0
  13. memoryos-0.1.12/src/memos/configs/embedder.py +53 -0
  14. memoryos-0.1.12/src/memos/configs/graph_db.py +45 -0
  15. memoryos-0.1.12/src/memos/configs/llm.py +71 -0
  16. memoryos-0.1.12/src/memos/configs/mem_chat.py +81 -0
  17. memoryos-0.1.12/src/memos/configs/mem_cube.py +89 -0
  18. memoryos-0.1.12/src/memos/configs/mem_os.py +70 -0
  19. memoryos-0.1.12/src/memos/configs/mem_reader.py +53 -0
  20. memoryos-0.1.12/src/memos/configs/mem_scheduler.py +78 -0
  21. memoryos-0.1.12/src/memos/configs/memory.py +190 -0
  22. memoryos-0.1.12/src/memos/configs/parser.py +38 -0
  23. memoryos-0.1.12/src/memos/configs/utils.py +8 -0
  24. memoryos-0.1.12/src/memos/configs/vec_db.py +64 -0
  25. memoryos-0.1.12/src/memos/deprecation.py +262 -0
  26. memoryos-0.1.12/src/memos/embedders/__init__.py +0 -0
  27. memoryos-0.1.12/src/memos/embedders/base.py +15 -0
  28. memoryos-0.1.12/src/memos/embedders/factory.py +23 -0
  29. memoryos-0.1.12/src/memos/embedders/ollama.py +74 -0
  30. memoryos-0.1.12/src/memos/embedders/sentence_transformer.py +40 -0
  31. memoryos-0.1.12/src/memos/exceptions.py +30 -0
  32. memoryos-0.1.12/src/memos/graph_dbs/__init__.py +0 -0
  33. memoryos-0.1.12/src/memos/graph_dbs/base.py +215 -0
  34. memoryos-0.1.12/src/memos/graph_dbs/factory.py +21 -0
  35. memoryos-0.1.12/src/memos/graph_dbs/neo4j.py +827 -0
  36. memoryos-0.1.12/src/memos/hello_world.py +97 -0
  37. memoryos-0.1.12/src/memos/llms/__init__.py +0 -0
  38. memoryos-0.1.12/src/memos/llms/base.py +16 -0
  39. memoryos-0.1.12/src/memos/llms/factory.py +25 -0
  40. memoryos-0.1.12/src/memos/llms/hf.py +231 -0
  41. memoryos-0.1.12/src/memos/llms/ollama.py +82 -0
  42. memoryos-0.1.12/src/memos/llms/openai.py +34 -0
  43. memoryos-0.1.12/src/memos/llms/utils.py +14 -0
  44. memoryos-0.1.12/src/memos/log.py +78 -0
  45. memoryos-0.1.12/src/memos/mem_chat/__init__.py +0 -0
  46. memoryos-0.1.12/src/memos/mem_chat/base.py +30 -0
  47. memoryos-0.1.12/src/memos/mem_chat/factory.py +21 -0
  48. memoryos-0.1.12/src/memos/mem_chat/simple.py +200 -0
  49. memoryos-0.1.12/src/memos/mem_cube/__init__.py +0 -0
  50. memoryos-0.1.12/src/memos/mem_cube/base.py +29 -0
  51. memoryos-0.1.12/src/memos/mem_cube/general.py +146 -0
  52. memoryos-0.1.12/src/memos/mem_cube/utils.py +24 -0
  53. memoryos-0.1.12/src/memos/mem_os/client.py +5 -0
  54. memoryos-0.1.12/src/memos/mem_os/core.py +819 -0
  55. memoryos-0.1.12/src/memos/mem_os/main.py +12 -0
  56. memoryos-0.1.12/src/memos/mem_os/product.py +89 -0
  57. memoryos-0.1.12/src/memos/mem_reader/__init__.py +0 -0
  58. memoryos-0.1.12/src/memos/mem_reader/base.py +27 -0
  59. memoryos-0.1.12/src/memos/mem_reader/factory.py +21 -0
  60. memoryos-0.1.12/src/memos/mem_reader/memory.py +298 -0
  61. memoryos-0.1.12/src/memos/mem_reader/simple_struct.py +241 -0
  62. memoryos-0.1.12/src/memos/mem_scheduler/__init__.py +0 -0
  63. memoryos-0.1.12/src/memos/mem_scheduler/base_scheduler.py +164 -0
  64. memoryos-0.1.12/src/memos/mem_scheduler/general_scheduler.py +305 -0
  65. memoryos-0.1.12/src/memos/mem_scheduler/modules/__init__.py +0 -0
  66. memoryos-0.1.12/src/memos/mem_scheduler/modules/base.py +74 -0
  67. memoryos-0.1.12/src/memos/mem_scheduler/modules/dispatcher.py +103 -0
  68. memoryos-0.1.12/src/memos/mem_scheduler/modules/monitor.py +82 -0
  69. memoryos-0.1.12/src/memos/mem_scheduler/modules/redis_service.py +146 -0
  70. memoryos-0.1.12/src/memos/mem_scheduler/modules/retriever.py +41 -0
  71. memoryos-0.1.12/src/memos/mem_scheduler/modules/schemas.py +146 -0
  72. memoryos-0.1.12/src/memos/mem_scheduler/scheduler_factory.py +21 -0
  73. memoryos-0.1.12/src/memos/mem_scheduler/utils.py +26 -0
  74. memoryos-0.1.12/src/memos/mem_user/user_manager.py +478 -0
  75. memoryos-0.1.12/src/memos/memories/__init__.py +0 -0
  76. memoryos-0.1.12/src/memos/memories/activation/__init__.py +0 -0
  77. memoryos-0.1.12/src/memos/memories/activation/base.py +42 -0
  78. memoryos-0.1.12/src/memos/memories/activation/item.py +25 -0
  79. memoryos-0.1.12/src/memos/memories/activation/kv.py +232 -0
  80. memoryos-0.1.12/src/memos/memories/base.py +19 -0
  81. memoryos-0.1.12/src/memos/memories/factory.py +34 -0
  82. memoryos-0.1.12/src/memos/memories/parametric/__init__.py +0 -0
  83. memoryos-0.1.12/src/memos/memories/parametric/base.py +19 -0
  84. memoryos-0.1.12/src/memos/memories/parametric/item.py +11 -0
  85. memoryos-0.1.12/src/memos/memories/parametric/lora.py +41 -0
  86. memoryos-0.1.12/src/memos/memories/textual/__init__.py +0 -0
  87. memoryos-0.1.12/src/memos/memories/textual/base.py +89 -0
  88. memoryos-0.1.12/src/memos/memories/textual/general.py +286 -0
  89. memoryos-0.1.12/src/memos/memories/textual/item.py +167 -0
  90. memoryos-0.1.12/src/memos/memories/textual/naive.py +185 -0
  91. memoryos-0.1.12/src/memos/memories/textual/tree.py +289 -0
  92. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/__init__.py +0 -0
  93. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/organize/__init__.py +0 -0
  94. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/organize/manager.py +305 -0
  95. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/retrieve/__init__.py +0 -0
  96. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/retrieve/reasoner.py +64 -0
  97. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/retrieve/recall.py +158 -0
  98. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/retrieve/reranker.py +111 -0
  99. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/retrieve/retrieval_mid_structs.py +13 -0
  100. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/retrieve/searcher.py +166 -0
  101. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/retrieve/task_goal_parser.py +68 -0
  102. memoryos-0.1.12/src/memos/memories/textual/tree_text_memory/retrieve/utils.py +48 -0
  103. memoryos-0.1.12/src/memos/parsers/__init__.py +0 -0
  104. memoryos-0.1.12/src/memos/parsers/base.py +15 -0
  105. memoryos-0.1.12/src/memos/parsers/factory.py +19 -0
  106. memoryos-0.1.12/src/memos/parsers/markitdown.py +22 -0
  107. memoryos-0.1.12/src/memos/settings.py +8 -0
  108. memoryos-0.1.12/src/memos/templates/__init__.py +0 -0
  109. memoryos-0.1.12/src/memos/templates/mem_reader_prompts.py +98 -0
  110. memoryos-0.1.12/src/memos/templates/mem_scheduler_prompts.py +65 -0
  111. memoryos-0.1.12/src/memos/types.py +55 -0
  112. memoryos-0.1.12/src/memos/vec_dbs/__init__.py +0 -0
  113. memoryos-0.1.12/src/memos/vec_dbs/base.py +105 -0
  114. memoryos-0.1.12/src/memos/vec_dbs/factory.py +21 -0
  115. memoryos-0.1.12/src/memos/vec_dbs/item.py +43 -0
  116. memoryos-0.1.12/src/memos/vec_dbs/qdrant.py +292 -0
  117. memoryos-0.0.1/PKG-INFO +0 -53
  118. memoryos-0.0.1/README.md +0 -25
  119. memoryos-0.0.1/src/memos/__init__.py +0 -1
  120. {memoryos-0.0.1 → memoryos-0.1.12}/LICENSE +0 -0
@@ -0,0 +1,257 @@
1
+ Metadata-Version: 2.3
2
+ Name: MemoryOS
3
+ Version: 0.1.12
4
+ Summary: Intelligence Begins with Memory
5
+ License: Apache-2.0
6
+ Keywords: memory,llm,language model,memoryOS,agent
7
+ Author: MemTensor
8
+ Author-email: lizy@memtensor.cn
9
+ Requires-Python: >=3.10,<4.0
10
+ Classifier: License :: OSI Approved :: Apache Software License
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3.10
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Requires-Dist: accelerate (>=1.7.0,<2.0.0)
17
+ Requires-Dist: chonkie (>=1.0.7,<2.0.0)
18
+ Requires-Dist: fastapi[all] (>=0.115.12,<0.116.0)
19
+ Requires-Dist: markitdown[docx,pdf,pptx,xls,xlsx] (>=0.1.1,<0.2.0)
20
+ Requires-Dist: neo4j (>=5.28.1,<6.0.0)
21
+ Requires-Dist: ollama (>=0.4.8,<0.5.0)
22
+ Requires-Dist: openai (>=1.77.0,<2.0.0)
23
+ Requires-Dist: qdrant-client (>=1.14.2,<2.0.0)
24
+ Requires-Dist: redis (>=6.2.0,<7.0.0)
25
+ Requires-Dist: sentence-transformers (>=4.1.0,<5.0.0)
26
+ Requires-Dist: sqlalchemy (>=2.0.41,<3.0.0)
27
+ Requires-Dist: tenacity (>=9.1.2,<10.0.0)
28
+ Requires-Dist: transformers (>=4.51.3,<5.0.0)
29
+ Project-URL: Repository, https://github.com/MemTensor/MemOS
30
+ Description-Content-Type: text/markdown
31
+
32
+ <div align="center">
33
+ <a href="https://memos.openmem.net/">
34
+ <img src="docs/assets/banner_new.gif" alt="MemOS Banner">
35
+ </a>
36
+
37
+
38
+
39
+ <h1 align="center">
40
+ <img src="docs/assets/memos_logo.png" alt="MemOS Logo" width="50"/> MemOS 1.0: 星河 (Stellar) <img src="https://img.shields.io/badge/status-Preview-blue" alt="Preview Badge"/>
41
+ </h1>
42
+
43
+ <p>
44
+ <a href="https://www.memtensor.com.cn/">
45
+ <img alt="Static Badge" src="https://img.shields.io/badge/Maintained_by-MemTensor-blue">
46
+ </a>
47
+ <a href="https://pypi.org/project/MemoryOS">
48
+ <img src="https://img.shields.io/pypi/v/MemoryOS?label=pypi%20package" alt="PyPI Version">
49
+ </a>
50
+ <a href="https://pypi.org/project/MemoryOS">
51
+ <img src="https://img.shields.io/pypi/pyversions/MemoryOS.svg" alt="Supported Python versions">
52
+ </a>
53
+ <a href="https://memos.openmem.net/docs/home">
54
+ <img src="https://img.shields.io/badge/Documentation-view-blue.svg" alt="Documentation">
55
+ </a>
56
+ <a href="https://arxiv.org/abs/2505.22101">
57
+ <img src="https://img.shields.io/badge/arXiv-2505.22101-b31b1b.svg" alt="ArXiv Paper">
58
+ </a>
59
+ <a href="https://github.com/MemTensor/MemOS/discussions">
60
+ <img src="https://img.shields.io/badge/GitHub-Discussions-181717.svg?logo=github" alt="GitHub Discussions">
61
+ </a>
62
+ <a href="https://discord.gg/Txbx3gebZR">
63
+ <img src="https://img.shields.io/badge/Discord-join%20chat-7289DA.svg?logo=discord" alt="Discord">
64
+ </a>
65
+ <a href="docs/assets/memos-wechat-group.png">
66
+ <img src="https://img.shields.io/badge/WeChat-Group-07C160.svg?logo=wechat" alt="WeChat Group">
67
+ </a>
68
+ <a href="https://opensource.org/license/apache-2-0/">
69
+ <img src="https://img.shields.io/badge/License-Apache_2.0-green.svg?logo=apache" alt="License">
70
+ </a>
71
+ </p>
72
+ </div>
73
+
74
+ ---
75
+
76
+ <a href="https://memos.openmem.net/">
77
+ <img src="docs/assets/SOTA_Score.jpg" alt="SOTA SCORE">
78
+ </a>
79
+
80
+
81
+ **MemOS** is an operating system for Large Language Models (LLMs) that enhances them with long-term memory capabilities. It allows LLMs to store, retrieve, and manage information, enabling more context-aware, consistent, and personalized interactions.
82
+
83
+ - **Website**: <a href="https://memos.openmem.net/" target="_blank">https://memos.openmem.net/</a>
84
+ - **Documentation**: <a href="https://memos.openmem.net/docs/home" target="_blank">https://memos.openmem.net/docs/home</a>
85
+ - **API Reference**: <a href="https://memos.openmem.net/docs/api/info" target="_blank">https://memos.openmem.net/docs/api/info</a>
86
+ - **Source Code**: <a href="https://github.com/MemTensor/MemOS" target="_blank">https://github.com/MemTensor/MemOS</a>
87
+
88
+ ## 📈 Performance Benchmark
89
+
90
+ MemOS demonstrates significant improvements over baseline memory solutions in multiple reasoning tasks.
91
+
92
+ | Model | Avg. Score | Multi-Hop | Open Domain | Single-Hop | Temporal Reasoning |
93
+ |-------------|------------|-----------|-------------|------------|---------------------|
94
+ | **OpenAI** | 0.5275 | 0.6028 | 0.3299 | 0.6183 | 0.2825 |
95
+ | **MemOS** | **0.7331** | **0.6430** | **0.5521** | **0.7844** | **0.7321** |
96
+ | **Improvement** | **+38.98%** | **+6.67%** | **+67.35%** | **+26.86%** | **+159.15%** |
97
+
98
+ > 💡 **Temporal reasoning accuracy improved by 159% compared to the OpenAI baseline.**
99
+
100
+
101
+
102
+ ### Details of End-to-End Evaluation on LOCOMO
103
+
104
+ > [!NOTE]
105
+ > Comparison of LLM Judge Scores across five major tasks in the LOCOMO benchmark. Each bar shows the mean evaluation score judged by LLMs for a given method-task pair, with standard deviation as error bars. MemOS-0630 consistently outperforms baseline methods (LangMem, Zep, OpenAI, Mem0) across all task types, especially in multi-hop and temporal reasoning scenarios.
106
+
107
+ <a href="https://memos.openmem.net/">
108
+ <img src="docs/assets/score_all_end2end.jpg" alt="END2END SCORE">
109
+ </a>
110
+
111
+
112
+
113
+
114
+ ## ✨ Key Features
115
+
116
+ - **🧠 Memory-Augmented Generation (MAG)**: Provides a unified API for memory operations, integrating with LLMs to enhance chat and reasoning with contextual memory retrieval.
117
+ - **📦 Modular Memory Architecture (MemCube)**: A flexible and modular architecture that allows for easy integration and management of different memory types.
118
+ - **💾 Multiple Memory Types**:
119
+ - **Textual Memory**: For storing and retrieving unstructured or structured text knowledge.
120
+ - **Activation Memory**: Caches key-value pairs (`KVCacheMemory`) to accelerate LLM inference and context reuse.
121
+ - **Parametric Memory**: Stores model adaptation parameters (e.g., LoRA weights).
122
+ - **🔌 Extensible**: Easily extend and customize memory modules, data sources, and LLM integrations.
123
+
124
+ ## 🚀 Getting Started
125
+
126
+ Here's a quick example of how to create a **`MemCube`**, load it from a directory, access its memories, and save it.
127
+
128
+ ```python
129
+ from memos.mem_cube.general import GeneralMemCube
130
+
131
+ # Initialize a MemCube from a local directory
132
+ mem_cube = GeneralMemCube.init_from_dir("examples/data/mem_cube_2")
133
+
134
+ # Access and print all memories
135
+ print("--- Textual Memories ---")
136
+ for item in mem_cube.text_mem.get_all():
137
+ print(item)
138
+
139
+ print("\n--- Activation Memories ---")
140
+ for item in mem_cube.act_mem.get_all():
141
+ print(item)
142
+
143
+ # Save the MemCube to a new directory
144
+ mem_cube.dump("tmp/mem_cube")
145
+ ```
146
+
147
+ What about **`MOS`** (Memory Operating System)? It's a higher-level orchestration layer that manages multiple MemCubes and provides a unified API for memory operations. Here's a quick example of how to use MOS:
148
+
149
+ ```python
150
+ from memos.configs.mem_os import MOSConfig
151
+ from memos.mem_os.main import MOS
152
+
153
+
154
+ # init MOS
155
+ mos_config = MOSConfig.from_json_file("examples/data/config/simple_memos_config.json")
156
+ memory = MOS(mos_config)
157
+
158
+ # create user
159
+ user_id = "b41a34d5-5cae-4b46-8c49-d03794d206f5"
160
+ memory.create_user(user_id=user_id)
161
+
162
+ # register cube for user
163
+ memory.register_mem_cube("examples/data/mem_cube_2", user_id=user_id)
164
+
165
+ # add memory for user
166
+ memory.add(
167
+ messages=[
168
+ {"role": "user", "content": "I like playing football."},
169
+ {"role": "assistant", "content": "I like playing football too."},
170
+ ],
171
+ user_id=user_id,
172
+ )
173
+
174
+ # Later, when you want to retrieve memory for user
175
+ retrieved_memories = memory.search(query="What do you like?", user_id=user_id)
176
+ # output text_memories: I like playing football, act_memories, para_memories
177
+ print(f"text_memories: {retrieved_memories['text_mem']}")
178
+ ```
179
+
180
+ For more detailed examples, please check out the [`examples`](./examples) directory.
181
+
182
+ ## 📦 Installation
183
+
184
+ > [!WARNING]
185
+ > Currently, MemOS primarily supports Linux platforms. You may encounter issues on Windows and macOS temporarily.
186
+
187
+ ### Install via pip
188
+
189
+ ```bash
190
+ pip install MemoryOS
191
+ ```
192
+
193
+ ### Development Install
194
+
195
+ To contribute to MemOS, clone the repository and install it in editable mode:
196
+
197
+ ```bash
198
+ git clone https://github.com/MemTensor/MemOS.git
199
+ cd MemOS
200
+ make install
201
+ ```
202
+
203
+ ### Optional Dependencies
204
+
205
+ #### Ollama Support
206
+
207
+ To use MemOS with [Ollama](https://ollama.com/), first install the Ollama CLI:
208
+ ```bash
209
+ curl -fsSL https://ollama.com/install.sh | sh
210
+ ```
211
+
212
+ #### Transformers Support
213
+
214
+ To use functionalities based on the `transformers` library, ensure you have [PyTorch](https://pytorch.org/get-started/locally/) installed (CUDA version recommended for GPU acceleration).
215
+
216
+ ## 💬 Community & Support
217
+
218
+ Join our community to ask questions, share your projects, and connect with other developers.
219
+
220
+ - **GitHub Issues**: Report bugs or request features in our <a href="https://github.com/MemTensor/MemOS/issues" target="_blank">GitHub Issues</a>.
221
+ - **GitHub Pull Requests**: Contribute code improvements via <a href="https://github.com/MemTensor/MemOS/pulls" target="_blank">Pull Requests</a>.
222
+ - **GitHub Discussions**: Participate in our <a href="https://github.com/MemTensor/MemOS/discussions" target="_blank">GitHub Discussions</a> to ask questions or share ideas.
223
+ - **Discord**: Join our <a href="https://discord.gg/Txbx3gebZR" target="_blank">Discord Server</a>.
224
+ - **WeChat**: Scan the QR code to join our WeChat group.
225
+
226
+ <img src="docs/assets/qr-code.png" alt="QR Code" width="600">
227
+
228
+ ## 📜 Citation
229
+
230
+ If you use MemOS in your research, please cite our paper:
231
+
232
+ ```bibtex
233
+ @article{li2025memos,
234
+ title={MemOS: An Operating System for Memory-Augmented Generation (MAG) in Large Language Models},
235
+ author={Li, Zhiyu and Song, Shichao and Wang, Hanyu and Niu, Simin and Chen, Ding and Yang, Jiawei and Xi, Chenyang and Lai, Huayi and Zhao, Jihao and Wang, Yezhaohui and others},
236
+ journal={arXiv preprint arXiv:2505.22101},
237
+ year={2025}
238
+ }
239
+ ```
240
+
241
+ ## 🙌 Contributing
242
+
243
+ We welcome contributions from the community! Please read our [contribution guidelines](./docs/contribution/overview.md) to get started.
244
+
245
+ ## 📄 License
246
+
247
+ MemOS is licensed under the [Apache 2.0 License](./LICENSE).
248
+
249
+ ## 📰 News
250
+
251
+ Stay up to date with the latest MemOS announcements, releases, and community highlights.
252
+
253
+ - **2025-07-07** – 🎉 *MemOS 1.0 (Stellar) Preview Release*: A SOTA Memory OS for LLMs is now open-sourced.
254
+ - **2025-05-28** – 🎉 *Short Paper Uploaded*: [MemOS: An Operating System for Memory-Augmented Generation (MAG) in Large Language Models](https://arxiv.org/abs/2505.22101) was published on arXiv.
255
+ - **2024-07-04** – 🎉 *Memory3 Model Released at WAIC 2024*: The new memory-layered architecture model was unveiled at the 2024 World Artificial Intelligence Conference.
256
+ - **2024-07-01** – 🎉 *Memory3 Paper Released*: [Memory3: Language Modeling with Explicit Memory](https://arxiv.org/abs/2407.01178) introduces the new approach to structured memory in LLMs.
257
+
@@ -0,0 +1,225 @@
1
+ <div align="center">
2
+ <a href="https://memos.openmem.net/">
3
+ <img src="docs/assets/banner_new.gif" alt="MemOS Banner">
4
+ </a>
5
+
6
+
7
+
8
+ <h1 align="center">
9
+ <img src="docs/assets/memos_logo.png" alt="MemOS Logo" width="50"/> MemOS 1.0: 星河 (Stellar) <img src="https://img.shields.io/badge/status-Preview-blue" alt="Preview Badge"/>
10
+ </h1>
11
+
12
+ <p>
13
+ <a href="https://www.memtensor.com.cn/">
14
+ <img alt="Static Badge" src="https://img.shields.io/badge/Maintained_by-MemTensor-blue">
15
+ </a>
16
+ <a href="https://pypi.org/project/MemoryOS">
17
+ <img src="https://img.shields.io/pypi/v/MemoryOS?label=pypi%20package" alt="PyPI Version">
18
+ </a>
19
+ <a href="https://pypi.org/project/MemoryOS">
20
+ <img src="https://img.shields.io/pypi/pyversions/MemoryOS.svg" alt="Supported Python versions">
21
+ </a>
22
+ <a href="https://memos.openmem.net/docs/home">
23
+ <img src="https://img.shields.io/badge/Documentation-view-blue.svg" alt="Documentation">
24
+ </a>
25
+ <a href="https://arxiv.org/abs/2505.22101">
26
+ <img src="https://img.shields.io/badge/arXiv-2505.22101-b31b1b.svg" alt="ArXiv Paper">
27
+ </a>
28
+ <a href="https://github.com/MemTensor/MemOS/discussions">
29
+ <img src="https://img.shields.io/badge/GitHub-Discussions-181717.svg?logo=github" alt="GitHub Discussions">
30
+ </a>
31
+ <a href="https://discord.gg/Txbx3gebZR">
32
+ <img src="https://img.shields.io/badge/Discord-join%20chat-7289DA.svg?logo=discord" alt="Discord">
33
+ </a>
34
+ <a href="docs/assets/memos-wechat-group.png">
35
+ <img src="https://img.shields.io/badge/WeChat-Group-07C160.svg?logo=wechat" alt="WeChat Group">
36
+ </a>
37
+ <a href="https://opensource.org/license/apache-2-0/">
38
+ <img src="https://img.shields.io/badge/License-Apache_2.0-green.svg?logo=apache" alt="License">
39
+ </a>
40
+ </p>
41
+ </div>
42
+
43
+ ---
44
+
45
+ <a href="https://memos.openmem.net/">
46
+ <img src="docs/assets/SOTA_Score.jpg" alt="SOTA SCORE">
47
+ </a>
48
+
49
+
50
+ **MemOS** is an operating system for Large Language Models (LLMs) that enhances them with long-term memory capabilities. It allows LLMs to store, retrieve, and manage information, enabling more context-aware, consistent, and personalized interactions.
51
+
52
+ - **Website**: <a href="https://memos.openmem.net/" target="_blank">https://memos.openmem.net/</a>
53
+ - **Documentation**: <a href="https://memos.openmem.net/docs/home" target="_blank">https://memos.openmem.net/docs/home</a>
54
+ - **API Reference**: <a href="https://memos.openmem.net/docs/api/info" target="_blank">https://memos.openmem.net/docs/api/info</a>
55
+ - **Source Code**: <a href="https://github.com/MemTensor/MemOS" target="_blank">https://github.com/MemTensor/MemOS</a>
56
+
57
+ ## 📈 Performance Benchmark
58
+
59
+ MemOS demonstrates significant improvements over baseline memory solutions in multiple reasoning tasks.
60
+
61
+ | Model | Avg. Score | Multi-Hop | Open Domain | Single-Hop | Temporal Reasoning |
62
+ |-------------|------------|-----------|-------------|------------|---------------------|
63
+ | **OpenAI** | 0.5275 | 0.6028 | 0.3299 | 0.6183 | 0.2825 |
64
+ | **MemOS** | **0.7331** | **0.6430** | **0.5521** | **0.7844** | **0.7321** |
65
+ | **Improvement** | **+38.98%** | **+6.67%** | **+67.35%** | **+26.86%** | **+159.15%** |
66
+
67
+ > 💡 **Temporal reasoning accuracy improved by 159% compared to the OpenAI baseline.**
68
+
69
+
70
+
71
+ ### Details of End-to-End Evaluation on LOCOMO
72
+
73
+ > [!NOTE]
74
+ > Comparison of LLM Judge Scores across five major tasks in the LOCOMO benchmark. Each bar shows the mean evaluation score judged by LLMs for a given method-task pair, with standard deviation as error bars. MemOS-0630 consistently outperforms baseline methods (LangMem, Zep, OpenAI, Mem0) across all task types, especially in multi-hop and temporal reasoning scenarios.
75
+
76
+ <a href="https://memos.openmem.net/">
77
+ <img src="docs/assets/score_all_end2end.jpg" alt="END2END SCORE">
78
+ </a>
79
+
80
+
81
+
82
+
83
+ ## ✨ Key Features
84
+
85
+ - **🧠 Memory-Augmented Generation (MAG)**: Provides a unified API for memory operations, integrating with LLMs to enhance chat and reasoning with contextual memory retrieval.
86
+ - **📦 Modular Memory Architecture (MemCube)**: A flexible and modular architecture that allows for easy integration and management of different memory types.
87
+ - **💾 Multiple Memory Types**:
88
+ - **Textual Memory**: For storing and retrieving unstructured or structured text knowledge.
89
+ - **Activation Memory**: Caches key-value pairs (`KVCacheMemory`) to accelerate LLM inference and context reuse.
90
+ - **Parametric Memory**: Stores model adaptation parameters (e.g., LoRA weights).
91
+ - **🔌 Extensible**: Easily extend and customize memory modules, data sources, and LLM integrations.
92
+
93
+ ## 🚀 Getting Started
94
+
95
+ Here's a quick example of how to create a **`MemCube`**, load it from a directory, access its memories, and save it.
96
+
97
+ ```python
98
+ from memos.mem_cube.general import GeneralMemCube
99
+
100
+ # Initialize a MemCube from a local directory
101
+ mem_cube = GeneralMemCube.init_from_dir("examples/data/mem_cube_2")
102
+
103
+ # Access and print all memories
104
+ print("--- Textual Memories ---")
105
+ for item in mem_cube.text_mem.get_all():
106
+ print(item)
107
+
108
+ print("\n--- Activation Memories ---")
109
+ for item in mem_cube.act_mem.get_all():
110
+ print(item)
111
+
112
+ # Save the MemCube to a new directory
113
+ mem_cube.dump("tmp/mem_cube")
114
+ ```
115
+
116
+ What about **`MOS`** (Memory Operating System)? It's a higher-level orchestration layer that manages multiple MemCubes and provides a unified API for memory operations. Here's a quick example of how to use MOS:
117
+
118
+ ```python
119
+ from memos.configs.mem_os import MOSConfig
120
+ from memos.mem_os.main import MOS
121
+
122
+
123
+ # init MOS
124
+ mos_config = MOSConfig.from_json_file("examples/data/config/simple_memos_config.json")
125
+ memory = MOS(mos_config)
126
+
127
+ # create user
128
+ user_id = "b41a34d5-5cae-4b46-8c49-d03794d206f5"
129
+ memory.create_user(user_id=user_id)
130
+
131
+ # register cube for user
132
+ memory.register_mem_cube("examples/data/mem_cube_2", user_id=user_id)
133
+
134
+ # add memory for user
135
+ memory.add(
136
+ messages=[
137
+ {"role": "user", "content": "I like playing football."},
138
+ {"role": "assistant", "content": "I like playing football too."},
139
+ ],
140
+ user_id=user_id,
141
+ )
142
+
143
+ # Later, when you want to retrieve memory for user
144
+ retrieved_memories = memory.search(query="What do you like?", user_id=user_id)
145
+ # output text_memories: I like playing football, act_memories, para_memories
146
+ print(f"text_memories: {retrieved_memories['text_mem']}")
147
+ ```
148
+
149
+ For more detailed examples, please check out the [`examples`](./examples) directory.
150
+
151
+ ## 📦 Installation
152
+
153
+ > [!WARNING]
154
+ > Currently, MemOS primarily supports Linux platforms. You may encounter issues on Windows and macOS temporarily.
155
+
156
+ ### Install via pip
157
+
158
+ ```bash
159
+ pip install MemoryOS
160
+ ```
161
+
162
+ ### Development Install
163
+
164
+ To contribute to MemOS, clone the repository and install it in editable mode:
165
+
166
+ ```bash
167
+ git clone https://github.com/MemTensor/MemOS.git
168
+ cd MemOS
169
+ make install
170
+ ```
171
+
172
+ ### Optional Dependencies
173
+
174
+ #### Ollama Support
175
+
176
+ To use MemOS with [Ollama](https://ollama.com/), first install the Ollama CLI:
177
+ ```bash
178
+ curl -fsSL https://ollama.com/install.sh | sh
179
+ ```
180
+
181
+ #### Transformers Support
182
+
183
+ To use functionalities based on the `transformers` library, ensure you have [PyTorch](https://pytorch.org/get-started/locally/) installed (CUDA version recommended for GPU acceleration).
184
+
185
+ ## 💬 Community & Support
186
+
187
+ Join our community to ask questions, share your projects, and connect with other developers.
188
+
189
+ - **GitHub Issues**: Report bugs or request features in our <a href="https://github.com/MemTensor/MemOS/issues" target="_blank">GitHub Issues</a>.
190
+ - **GitHub Pull Requests**: Contribute code improvements via <a href="https://github.com/MemTensor/MemOS/pulls" target="_blank">Pull Requests</a>.
191
+ - **GitHub Discussions**: Participate in our <a href="https://github.com/MemTensor/MemOS/discussions" target="_blank">GitHub Discussions</a> to ask questions or share ideas.
192
+ - **Discord**: Join our <a href="https://discord.gg/Txbx3gebZR" target="_blank">Discord Server</a>.
193
+ - **WeChat**: Scan the QR code to join our WeChat group.
194
+
195
+ <img src="docs/assets/qr-code.png" alt="QR Code" width="600">
196
+
197
+ ## 📜 Citation
198
+
199
+ If you use MemOS in your research, please cite our paper:
200
+
201
+ ```bibtex
202
+ @article{li2025memos,
203
+ title={MemOS: An Operating System for Memory-Augmented Generation (MAG) in Large Language Models},
204
+ author={Li, Zhiyu and Song, Shichao and Wang, Hanyu and Niu, Simin and Chen, Ding and Yang, Jiawei and Xi, Chenyang and Lai, Huayi and Zhao, Jihao and Wang, Yezhaohui and others},
205
+ journal={arXiv preprint arXiv:2505.22101},
206
+ year={2025}
207
+ }
208
+ ```
209
+
210
+ ## 🙌 Contributing
211
+
212
+ We welcome contributions from the community! Please read our [contribution guidelines](./docs/contribution/overview.md) to get started.
213
+
214
+ ## 📄 License
215
+
216
+ MemOS is licensed under the [Apache 2.0 License](./LICENSE).
217
+
218
+ ## 📰 News
219
+
220
+ Stay up to date with the latest MemOS announcements, releases, and community highlights.
221
+
222
+ - **2025-07-07** – 🎉 *MemOS 1.0 (Stellar) Preview Release*: A SOTA Memory OS for LLMs is now open-sourced.
223
+ - **2025-05-28** – 🎉 *Short Paper Uploaded*: [MemOS: An Operating System for Memory-Augmented Generation (MAG) in Large Language Models](https://arxiv.org/abs/2505.22101) was published on arXiv.
224
+ - **2024-07-04** – 🎉 *Memory3 Model Released at WAIC 2024*: The new memory-layered architecture model was unveiled at the 2024 World Artificial Intelligence Conference.
225
+ - **2024-07-01** – 🎉 *Memory3 Paper Released*: [Memory3: Language Modeling with Explicit Memory](https://arxiv.org/abs/2407.01178) introduces the new approach to structured memory in LLMs.
@@ -2,10 +2,10 @@
2
2
 
3
3
  [tool.poetry]
4
4
  name = "MemoryOS"
5
- version = "0.0.1"
6
- description = "Empowering language models with memory."
5
+ version = "0.1.12"
6
+ description = "Intelligence Begins with Memory"
7
7
  license = "Apache-2.0"
8
- authors = ["MemoryTensor <lizy@memtensor.cn>"]
8
+ authors = ["MemTensor <lizy@memtensor.cn>"]
9
9
  readme = "README.md"
10
10
  repository = "https://github.com/MemTensor/MemOS"
11
11
  keywords = ["memory", "llm", "language model", "memoryOS", "agent"]
@@ -13,15 +13,44 @@ packages = [{include = "memos", from = "src"}]
13
13
 
14
14
  [tool.poetry.dependencies]
15
15
  python = "^3.10"
16
- pytest = "^8.3.5"
17
- pre-commit = "^4.2.0"
18
- ruff = "^0.11.8"
19
16
  openai = "^1.77.0"
20
17
  ollama = "^0.4.8"
21
18
  qdrant-client = "^1.14.2"
22
19
  transformers = "^4.51.3"
23
20
  markitdown = {extras = ["docx", "pdf", "pptx", "xls", "xlsx"], version = "^0.1.1"}
24
21
  chonkie = "^1.0.7"
22
+ tenacity = "^9.1.2"
23
+ neo4j = "^5.28.1"
24
+ accelerate = "^1.7.0"
25
+ fastapi = {extras = ["all"], version = "^0.115.12"}
26
+ sentence-transformers = "^4.1.0"
27
+ sqlalchemy = "^2.0.41"
28
+ redis = "^6.2.0"
29
+
30
+ [tool.poetry.group.dev]
31
+ optional = false
32
+
33
+ [tool.poetry.group.dev.dependencies]
34
+ pre-commit = "^4.2.0"
35
+ ruff = "^0.11.8"
36
+
37
+ [tool.poetry.group.test]
38
+ optional = false
39
+
40
+ [tool.poetry.group.test.dependencies]
41
+ pytest = "^8.3.5"
42
+ pytest-asyncio = "^0.23.5"
43
+
44
+ [tool.poetry.group.eval]
45
+ optional = true
46
+
47
+ [tool.poetry.group.eval.dependencies]
48
+ dotenv = "^0.9.9"
49
+ mem0ai = "^0.1.109"
50
+ zep-cloud = "^2.15.0"
51
+ rouge-score = "^0.1.2"
52
+ nltk = "^3.9.1"
53
+ bert-score = "^0.3.13"
25
54
 
26
55
  [[tool.poetry.source]]
27
56
  name = "mirrors"
@@ -39,7 +68,11 @@ build-backend = "poetry.core.masonry.api"
39
68
  # Testing related
40
69
 
41
70
  [tool.pytest.ini_options]
71
+ asyncio_mode = "auto"
42
72
  pythonpath = "src"
73
+ filterwarnings = [
74
+ "ignore::DeprecationWarning:qdrant_client.*",
75
+ ]
43
76
 
44
77
 
45
78
  # Linting related
@@ -0,0 +1,20 @@
1
+ __version__ = "0.1.12"
2
+
3
+ from memos.configs.mem_cube import GeneralMemCubeConfig
4
+ from memos.configs.mem_os import MOSConfig
5
+ from memos.configs.mem_scheduler import SchedulerConfigFactory
6
+ from memos.mem_cube.general import GeneralMemCube
7
+ from memos.mem_os.main import MOS
8
+ from memos.mem_scheduler.general_scheduler import GeneralScheduler
9
+ from memos.mem_scheduler.scheduler_factory import SchedulerFactory
10
+
11
+
12
+ __all__ = [
13
+ "MOS",
14
+ "GeneralMemCube",
15
+ "GeneralMemCubeConfig",
16
+ "GeneralScheduler",
17
+ "MOSConfig",
18
+ "SchedulerConfigFactory",
19
+ "SchedulerFactory",
20
+ ]