<div align="center">

<img alt="logo simplemem" src="https://github.com/user-attachments/assets/6ea54ad1-e007-442c-99d7-1174b10d1fec" width="450">

<div align="center">

## Bộ Nhớ Dài Hạn Hiệu Quả cho Các Tác Nhân LLM — Văn Bản & Đa Phương Thức

<small>Lưu trữ, nén và truy xuất bộ nhớ dài hạn với khả năng nén ngữ nghĩa không mất dữ liệu. Nay hỗ trợ đa phương thức bao gồm văn bản, hình ảnh, âm thanh & video.</small>

</div>

<p><b>Hoạt động với bất kỳ nền tảng AI nào hỗ trợ MCP (bộ nhớ văn bản) hoặc tích hợp Python (đa phương thức đầy đủ)</b></p>

<table>
<tr>

<td align="center" width="100">
  <a href="https://www.anthropic.com/claude">
    <img src="https://cdn.simpleicons.org/claude/D97757" width="48" height="48" alt="Claude Desktop" />
  </a><br/>
  <sub>
    <a href="https://www.anthropic.com/claude"><b>Claude Desktop</b></a>
  </sub>
</td>

<td align="center" width="100">
  <a href="https://cursor.com">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://cdn.simpleicons.org/cursor/FFFFFF">
      <img src="https://cdn.simpleicons.org/cursor/000000" width="48" height="48" alt="Cursor" />
    </picture>
  </a><br/>
  <sub>
    <a href="https://cursor.com"><b>Cursor</b></a>
  </sub>
</td>

<td align="center" width="100">
  <a href="https://lmstudio.ai">
    <img src="https://github.com/lmstudio-ai.png?size=200" width="48" height="48" alt="LM Studio" />
  </a><br/>
  <sub>
    <a href="https://lmstudio.ai"><b>LM Studio</b></a>
  </sub>
</td>

<td align="center" width="100">
  <a href="https://cherry-ai.com">
    <img src="https://github.com/CherryHQ.png?size=200" width="48" height="48" alt="Cherry Studio" />
  </a><br/>
  <sub>
    <a href="https://cherry-ai.com"><b>Cherry Studio</b></a>
  </sub>
</td>

<td align="center" width="100">
  <a href="https://pypi.org/project/simplemem/">
    <img src="https://cdn.simpleicons.org/pypi/3775A9" width="48" height="48" alt="PyPI" />
  </a><br/>
  <sub>
    <a href="https://pypi.org/project/simplemem/"><b>Gói PyPI</b></a>
  </sub>
</td>

<td align="center" width="100">
  <sub><b>+ Bất kỳ<br/>MCP Client</b></sub>
</td>

</tr>
</table>

<div align="center">

<br/>

[🇨🇳 中文](./README.zh-CN.md) •
[🇯🇵 日本語](./README.ja.md) •
[🇰🇷 한국어](./README.ko.md) •
[🇪🇸 Español](./README.es.md) •
[🇫🇷 Français](./README.fr.md) •
[🇩🇪 Deutsch](./README.de.md) •
[🇧🇷 Português](./README.pt-br.md)<br/>
[🇷🇺 Русский](./README.ru.md) •
[🇸🇦 العربية](./README.ar.md) •
[🇮🇹 Italiano](./README.it.md) •
**🇻🇳 Tiếng Việt** •
[🇹🇷 Türkçe](./README.tr.md) •
[🇬🇧 English](../../README.md)

<br/>

[![Trang Dự Án](https://img.shields.io/badge/🎬_DEMO_TƯƠNG_TÁC-Truy_Cập_Website-FF6B6B?style=for-the-badge&labelColor=FF6B6B&color=4ECDC4&logoColor=white)](https://aiming-lab.github.io/SimpleMem-Page)

<p align="center">
  <a href="https://arxiv.org/abs/2601.02553"><img src="https://img.shields.io/badge/arXiv-2601.02553-b31b1b?style=flat&labelColor=555" alt="arXiv"></a>
  <a href="https://github.com/aiming-lab/SimpleMem"><img src="https://img.shields.io/badge/github-SimpleMem-181717?style=flat&labelColor=555&logo=github&logoColor=white" alt="GitHub"></a>
  <a href="../../LICENSE"><img src="https://img.shields.io/github/license/aiming-lab/SimpleMem?style=flat&label=license&labelColor=555&color=2EA44F" alt="Giấy phép"></a>
  <a href="https://github.com/aiming-lab/SimpleMem/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat&labelColor=555" alt="Chào đón PR"></a>
  <br/>
  <a href="https://pypi.org/project/simplemem/"><img src="https://img.shields.io/pypi/v/simplemem?style=flat&label=pypi&labelColor=555&color=3775A9&logo=pypi&logoColor=white" alt="PyPI"></a>
  <a href="https://pypi.org/project/simplemem/"><img src="https://img.shields.io/pypi/pyversions/simplemem?style=flat&label=python&labelColor=555&color=3775A9&logo=python&logoColor=white" alt="Python"></a>
  <a href="https://mcp.simplemem.cloud"><img src="https://img.shields.io/badge/MCP-mcp.simplemem.cloud-14B8A6?style=flat&labelColor=555" alt="MCP Server"></a>
  <a href="https://github.com/aiming-lab/SimpleMem"><img src="https://img.shields.io/badge/Claude_Skills-supported-FFB000?style=flat&labelColor=555" alt="Claude Skills"></a>
  <br/>
  <a href="https://discord.gg/KA2zC32M"><img src="https://img.shields.io/badge/Discord-Join_Chat-5865F2?style=flat&labelColor=555&logo=discord&logoColor=white" alt="Discord"></a>
  <a href="../../fig/wechat_logo3.JPG"><img src="https://img.shields.io/badge/WeChat-Group-07C160?style=flat&labelColor=555&logo=wechat&logoColor=white" alt="WeChat"></a>
</p>

<br/>

[🚀 Bắt Đầu Nhanh](#-bắt-đầu-nhanh) • [🌟 Tổng Quan](#-tổng-quan) • [📦 Cài Đặt](#-cài-đặt) • [🔌 MCP Server](#-mcp-server-bộ-nhớ-văn-bản) • [📊 Tái Tạo](#-tái-tạo-kết-quả-bài-báo) • [📝 Trích Dẫn](#-trích-dẫn)

</div>

</div>

<br/>

## 🔥 Tin Tức

- **[05/21/2026]** 📦 **Gói `simplemem` thống nhất — một lần import, tự động định tuyến!** SimpleMem, Omni-SimpleMem và EvolveMem nay nằm trong một gói duy nhất. `from simplemem import SimpleMem` tự động chọn backend văn bản hoặc đa phương thức dựa trên phương thức đầu tiên bạn gọi, và `simplemem.optimize(...)` khai thác vòng lặp tự tiến hóa của EvolveMem. Cài đặt chỉ một bước với `pip install -e .`.
- **[05/14/2026]** 🧬 **EvolveMem (v3.0) — Bộ Nhớ Tự Tiến Hóa qua AutoResearch!** Hạ tầng truy xuất nay tự tiến hóa thông qua chẩn đoán vòng kín do LLM điều khiển. Trên LoCoMo, EvolveMem vượt trội hơn baseline mạnh nhất **+25.7% tương đối**; trên MemBench, **+18.9% tương đối**. Hệ thống khám phá các chiều truy xuất hoàn toàn mới không có trong thiết kế ban đầu. [Xem EvolveMem →](../../EvolveMem/)
- **[04/02/2026]** 🧠 **Omni-SimpleMem (v2.0) — Bộ Nhớ Đa Phương Thức Đã Ra Đời!** SimpleMem nay hỗ trợ bộ nhớ **văn bản, hình ảnh, âm thanh & video**. Đạt **SOTA mới trên LoCoMo (F1=0.613, +47%)** và **Mem-Gallery (F1=0.810, +51%)** so với kết quả tốt nhất trước đây. [Xem Omni-SimpleMem →](../../OmniSimpleMem/)
- **[02/09/2026]** 🚀 **Bộ Nhớ Xuyên Phiên — Vượt trội hơn Claude-Mem tới 64%!** [Xem Tài Liệu Bộ Nhớ Xuyên Phiên →](cross/README.md)
- **[01/20/2026]** 📦 **SimpleMem nay có mặt trên PyPI!** Cài đặt qua `pip install simplemem`. [Xem Hướng Dẫn Sử Dụng Gói →](../PACKAGE_USAGE.md)
- **[01/14/2026]** 🎉 **SimpleMem MCP Server đã HOẠT ĐỘNG!** Được lưu trữ trên đám mây tại [mcp.simplemem.cloud](https://mcp.simplemem.cloud). [Xem Tài Liệu MCP →](../../MCP/README.md)
- **[01/05/2026]** Bài báo SimpleMem đã được công bố trên [arXiv](https://arxiv.org/abs/2601.02553)!

---

## 📑 Mục Lục

- [🚀 Bắt Đầu Nhanh](#-bắt-đầu-nhanh)
- [🌟 Tổng Quan](#-tổng-quan)
- [📦 Cài Đặt](#-cài-đặt)
- [🐳 Docker](#-chạy-với-docker)
- [🔌 MCP Server](#-mcp-server-bộ-nhớ-văn-bản)
- [📊 Tái Tạo Kết Quả Bài Báo](#-tái-tạo-kết-quả-bài-báo)
- [🗺️ Lộ Trình](#️-lộ-trình)
- [📝 Trích Dẫn](#-trích-dẫn)

---

## 🚀 Bắt Đầu Nhanh

### 🧠 Hiểu Quy Trình Cơ Bản

Ở cấp độ tổng quan, SimpleMem hoạt động như một hệ thống bộ nhớ dài hạn cho các tác nhân dựa trên LLM. Quy trình bao gồm ba bước đơn giản:

1. **Lưu trữ thông tin** – Các đoạn hội thoại hoặc sự kiện được xử lý và chuyển đổi thành các đơn vị bộ nhớ có cấu trúc, nguyên tử.
2. **Lập chỉ mục bộ nhớ** – Các bộ nhớ đã lưu được tổ chức bằng nhúng ngữ nghĩa và siêu dữ liệu có cấu trúc.
3. **Truy xuất bộ nhớ liên quan** – Khi có một truy vấn, SimpleMem lấy ra thông tin được lưu trữ liên quan nhất dựa trên ý nghĩa thay vì từ khóa.

Thiết kế này cho phép các tác nhân LLM duy trì ngữ cảnh, gọi lại thông tin quá khứ một cách hiệu quả và tránh xử lý lặp đi lặp lại lịch sử dư thừa.

### 🎓 Cách Sử Dụng Cơ Bản

SimpleMem được đóng gói dưới dạng một gói `simplemem` duy nhất. Mặc định `mode="auto"` **tự động phát hiện** backend cần sử dụng dựa trên những gì bạn gọi — không cần cấu hình thủ công:

```python
from simplemem import SimpleMem

mem = SimpleMem()  # mode="auto" — backend chosen by first call
```

Phương thức đầu tiên bạn gọi sẽ quyết định backend:

| Lệnh gọi đầu tiên | Backend được chọn | Lý do |
|:--|:--|:--|
| `add_dialogue()` | **Văn bản** (SimpleMem) | API dựa trên hội thoại → chế độ văn bản |
| `add_text()` / `add_image()` / `add_audio()` / `add_video()` | **Omni** (Omni-SimpleMem) | API đa phương thức → chế độ omni |

<table>
<tr>
<td width="50%">

**📝 Auto → Văn bản** (đầu vào thuần văn bản)

```python
from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_dialogue() → text backend auto-selected
mem.add_dialogue(
    "Alice",
    "Bob, let's meet at Starbucks tomorrow at 2pm",
    "2025-11-15T14:30:00",
)
mem.add_dialogue(
    "Bob",
    "Sure, I'll bring the market analysis report",
    "2025-11-15T14:31:00",
)
mem.finalize()

answer = mem.ask("When and where will Alice and Bob meet?")
# → "16 November 2025 at 2:00 PM at Starbucks"
```

</td>
<td width="50%">

**🧠 Auto → Omni** (đầu vào đa phương thức)

```python
from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_image() → omni backend auto-selected
mem.add_text(
    "User loves hiking in the Rocky Mountains.",
    tags=["session_id:D1"],
)
mem.add_image("photo.jpg", tags=["session_id:D1"])
mem.add_audio("voice_note.wav", tags=["session_id:D1"])

result = mem.query("What does the user enjoy?", top_k=5)
for item in result.items:
    print(item["summary"])

mem.close()
```

</td>
</tr>
</table>

> **💡 Mẹo**: Chế độ Auto chọn backend nhẹ nhất phù hợp với dữ liệu của bạn. Bạn vẫn có thể dùng `mode="text"` hoặc `mode="omni"` một cách tường minh nếu muốn.

---

### 🧬 Nâng Cao: Tối Ưu Cấu Hình Truy Xuất

Tinh chỉnh các siêu tham số truy xuất ngoại tuyến trên tập dev của bạn, sau đó triển khai `Config` thu được để suy luận. Đây là một lớp bọc mỏng xung quanh vòng lặp tự tiến hóa của EvolveMem:

```python
import simplemem
from simplemem import SimpleMem, load_config

# mem is a finalized SimpleMem instance with memories already built
dev_questions = [
    ("When is the meeting?", "2pm tomorrow at Starbucks"),
    ("What should Bob prepare?", "market analysis report"),
]
config = simplemem.optimize(mem, dev_questions, max_rounds=3)
config.save("my_config.json")

# Later, deploy with the optimized config
config = load_config("my_config.json")
mem = SimpleMem(config=config)
```

> EvolveMem chạy một chu kỳ Đánh Giá → Chẩn Đoán → Đề Xuất → Bảo Vệ do LLM điều khiển trên các câu hỏi dev của bạn, điều chỉnh các cờ truy xuất toàn cục (top_k, chế độ hợp nhất, xác minh câu trả lời, số vòng phản ánh, ...). Để xem phiên bản độc lập đầy đủ với các bộ điều hợp benchmark và ghi đè theo từng danh mục, xem [`EvolveMem/`](../../EvolveMem/).

---

### 🚄 Nâng Cao: Xử Lý Song Song

Để xử lý hội thoại quy mô lớn, bật chế độ song song:

```python
from simplemem import create

mem = create(
    mode="text",
    clear_db=True,
    enable_parallel_processing=True,  # ⚡ Parallel memory building
    max_parallel_workers=8,
    enable_parallel_retrieval=True,   # 🔍 Parallel query execution
    max_retrieval_workers=4
)
```

> **💡 Mẹo Chuyên Gia**: Xử lý song song giảm đáng kể độ trễ cho các thao tác hàng loạt!

---

## 🌟 Tổng Quan

**SimpleMem** là một bộ nhớ thống nhất cho các tác nhân LLM, được xây dựng trên một nguyên tắc: lưu trữ bộ nhớ *ngữ nghĩa không mất dữ liệu* với mật độ thông tin cao, để tác nhân gọi lại được nhiều hơn trong khi tiêu tốn ít token hơn nhiều. Gói này tập hợp ba công trình cùng chia sẻ nguyên tắc này nhưng giải quyết các phần khác nhau của vấn đề.

### 📝 SimpleMem: lõi hiệu quả (văn bản)

Hầu hết các hệ thống bộ nhớ đều buộc phải chấp nhận một sự đánh đổi tệ hại. Chúng hoặc tích lũy bị động lịch sử tương tác thô (dư thừa, tốn nhiều token) hoặc chạy các vòng lặp suy luận tốn kém để lọc nhiễu (chậm, tốn chi phí). SimpleMem thay vào đó nén các tương tác qua một quy trình ba giai đoạn:

| Giai đoạn | Chức năng |
|:--|:--|
| **1. Nén Có Cấu Trúc Ngữ Nghĩa** | Chắt lọc các tương tác phi cấu trúc thành các đơn vị bộ nhớ nhỏ gọn (các sự kiện tự chứa với tham chiếu đã được giải quyết và nhãn thời gian tuyệt đối), mỗi đơn vị được lập chỉ mục qua nhiều góc nhìn bổ sung nhau để truy xuất linh hoạt. |
| **2. Tổng Hợp Ngữ Nghĩa Trực Tuyến** | Hợp nhất ngữ cảnh liên quan trong một phiên thành các biểu diễn trừu tượng thống nhất, loại bỏ dư thừa khi xây dựng bộ nhớ thay vì tại thời điểm truy vấn. |
| **3. Lập Kế Hoạch Truy Xuất Nhận Thức Ý Định** | Suy luận ý định tìm kiếm đằng sau một truy vấn để quyết định *nên* truy xuất gì và lắp ráp một ngữ cảnh chính xác, nhỏ gọn. |

Trên benchmark LoCoMo, điều này mang lại mức cải thiện F1 trung bình 26.4% so với các hệ thống trước, đồng thời giảm mức tiêu thụ token tại thời điểm suy luận khoảng 30 lần. Chi tiết cơ chế (các lớp chỉ mục lai, ví dụ nén, lập kế hoạch truy xuất): [**Bộ nhớ văn bản SimpleMem →**](../text-memory.md).

### 🧠 Omni-SimpleMem: bộ nhớ đa phương thức (văn bản, hình ảnh, âm thanh, video)

Omni-SimpleMem mở rộng triết lý nén-trước cho bốn phương thức, được xây dựng trên ba nguyên tắc: **Tiếp Nhận Có Chọn Lọc** (lọc dựa trên entropy theo từng phương thức), **Truy Xuất Lũy Tiến** (FAISS + BM25 lai với mở rộng ngân sách token theo kim tự tháp), và **Tăng Cường Đồ Thị Tri Thức** (suy luận đa chặng xuyên phương thức). Thay vì được thiết kế thủ công, kiến trúc của nó được *khám phá* bởi một quy trình nghiên cứu tự động đã chạy khoảng 50 thí nghiệm trên hai benchmark, chẩn đoán các chế độ thất bại, đề xuất các thay đổi kiến trúc, và thậm chí sửa các lỗi đường ống dữ liệu mà không có sự can thiệp của con người trong vòng lặp bên trong. Đáng chú ý, các bản vá lỗi và thay đổi kiến trúc mỗi loại đóng góp nhiều hơn tất cả việc điều chỉnh siêu tham số cộng lại, đưa hệ thống từ baseline ngây thơ đến trạng thái nghệ thuật trên cả LoCoMo và Mem-Gallery. Tài liệu đầy đủ: [**Omni-SimpleMem →**](../../OmniSimpleMem/).

### 🧬 EvolveMem: truy xuất tự tiến hóa

EvolveMem giải quyết một điểm mù được chia sẻ bởi hầu hết mọi hệ thống bộ nhớ: nội dung được lưu trữ tiến hóa, nhưng cơ chế *truy xuất* (hàm tính điểm, chiến lược hợp nhất, chính sách tạo câu trả lời) vẫn bị đóng băng sau khi triển khai. EvolveMem chạy một quy trình AutoResearch vòng kín (**Đánh Giá → Chẩn Đoán → Đề Xuất → Bảo Vệ → Lặp Lại**) trong đó một LLM chẩn đoán các lỗi theo từng câu hỏi và đề xuất các thay đổi cấu hình, được bảo vệ bởi tính năng tự động khôi phục khi có hồi quy và khuyến khích khám phá trong giai đoạn trì trệ. Nó khám phá các chiều truy xuất mới (phân rã truy vấn, hoán đổi thực thể, xác minh câu trả lời) không có trong thiết kế ban đầu, cải thiện LoCoMo 25.7% tương đối so với baseline mạnh nhất, và các cấu hình đã tiến hóa của nó chuyển giao tích cực giữa các benchmark. Tài liệu đầy đủ: [**EvolveMem →**](../../EvolveMem/).

### Cách chúng phối hợp với nhau

`from simplemem import SimpleMem` cung cấp cho bạn lõi văn bản với định tuyến tự động đến backend đa phương thức, và `simplemem.optimize(...)` khai thác EvolveMem để điều chỉnh truy xuất theo dữ liệu của riêng bạn. Một gói, một mô hình tư duy: nén không mất dữ liệu, truy xuất theo ý định, và để hệ thống liên tục tự cải thiện.

---

## 📦 Cài Đặt

### 📝 Lưu Ý Cho Người Dùng Lần Đầu

- Đảm bảo bạn đang dùng **Python 3.10+ trong môi trường đang hoạt động**, không chỉ cài đặt toàn cục.
- Khóa API tương thích OpenAI phải được cấu hình **trước khi chạy bất kỳ thao tác xây dựng hoặc truy xuất bộ nhớ nào**, nếu không khởi tạo có thể thất bại.
- Khi sử dụng các nhà cung cấp không phải OpenAI (ví dụ: Qwen hoặc Azure OpenAI), hãy xác minh cả tên model và `OPENAI_BASE_URL` trong `config.py`.
- Đối với các tập dữ liệu hội thoại lớn, bật xử lý song song có thể giảm đáng kể thời gian xây dựng bộ nhớ.

### 📋 Yêu Cầu

- 🐍 Python 3.10+
- 🔑 API tương thích OpenAI (OpenAI, Qwen, Azure OpenAI, v.v.)

### 🛠️ Cài Đặt

```bash
# 📥 Clone repository
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem

# 📦 Install dependencies (pinned versions)
pip install -r requirements.txt

# — OR — install as an editable package
pip install -e .                  # default: text + multimodal + evolver
pip install -e ".[server]"        # + MCP / HTTP server (mcp, fastapi, ...)
pip install -e ".[all]"           # everything, including dev tools

# ⚙️ Configure API settings
cp config.py.example config.py
# Edit config.py with your API key and preferences
```

### ⚙️ Ví Dụ Cấu Hình

```python
# config.py
OPENAI_API_KEY = "your-api-key"
OPENAI_BASE_URL = None  # or custom endpoint for Qwen/Azure

LLM_MODEL = "gpt-4.1-mini"
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B"  # State-of-the-art retrieval
```

---

## 🐳 Chạy Với Docker

**MCP Server** có thể được chạy trong Docker để có môi trường nhất quán và cách ly. Dữ liệu (LanceDB và cơ sở dữ liệu người dùng) được lưu trữ bền vững trong một volume trên máy chủ.

### Điều Kiện Tiên Quyết

- [Docker](https://docs.docker.com/get-docker/) và [Docker Compose](https://docs.docker.com/compose/install/)

### Chạy Nhanh

```bash
# From the repository root
docker compose up -d
```

- **Giao diện Web:** http://localhost:8000/
- **REST API:** http://localhost:8000/api/
- **MCP (SSE):** http://localhost:8000/mcp/sse?token=&lt;TOKEN&gt;

Dữ liệu được lưu trong `./data` trên máy chủ (được tạo tự động).

### Cấu Hình Tùy Chỉnh

1. Sao chép mẫu môi trường và chỉnh sửa:
   ```bash
   cp .env.example .env
   # Edit .env: set JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, model URLs, etc.
   ```
2. Chạy với tệp env:
   ```bash
   docker compose --env-file .env up -d
   ```

### Sử Dụng Ollama Trên Máy Chủ

Khi `LLM_PROVIDER=ollama` và Ollama chạy trên máy của bạn (không phải trong Docker), hãy đặt trong `.env`:

```bash
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
```

Trên Linux, `host.docker.internal` được bật tự động qua tệp Compose.

### Các Lệnh Hữu Ích

```bash
docker compose logs -f simplemem   # Follow logs
docker compose down                 # Stop and remove containers
```

> 📖 Để tự lưu trữ MCP server (Docker hoặc bare metal), xem [Tài Liệu MCP](../../MCP/README.md).

---

## 🔌 MCP Server *(bộ nhớ văn bản)*

SimpleMem có sẵn dưới dạng **dịch vụ bộ nhớ được lưu trữ trên đám mây** thông qua Model Context Protocol (MCP), cho phép tích hợp liền mạch với các trợ lý AI như Claude Desktop, Cursor và các MCP client tương thích khác.

**🌐 Dịch Vụ Đám Mây**: [mcp.simplemem.cloud](https://mcp.simplemem.cloud) — hoặc tự lưu trữ MCP server cục bộ bằng [Docker](#-chạy-với-docker).

### Tính Năng Chính

| Tính năng | Mô tả |
|---------|-------------|
| **Streamable HTTP** | Giao thức MCP 2025-03-26 với JSON-RPC 2.0 |
| **Cô Lập Đa Tenant** | Bảng dữ liệu theo từng người dùng với xác thực token |
| **Truy Xuất Lai** | Tìm kiếm ngữ nghĩa + khớp từ khóa + lọc siêu dữ liệu |
| **Tối Ưu Cho Sản Xuất** | Thời gian phản hồi nhanh hơn với tích hợp OpenRouter |

### Cấu Hình Nhanh

```json
{
  "mcpServers": {
    "simplemem": {
      "url": "https://mcp.simplemem.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}
```

> 📖 Để xem hướng dẫn cài đặt chi tiết và hướng dẫn tự lưu trữ, xem [Tài Liệu MCP](../../MCP/README.md)

---

## 📊 Tái Tạo Kết Quả Bài Báo

Tái tạo các số liệu LoCoMo / MemBench / Mem-Gallery từ các bài báo. Mỗi trụ cột có bộ chạy benchmark riêng trong thư mục riêng của nó. Cài đặt các gói benchmark trước: `pip install -e ".[benchmark]"`.

### 📝 SimpleMem (văn bản) — LoCoMo

Chạy từ thư mục gốc của repository:

```bash
python test_locomo10.py                       # full LoCoMo benchmark
python test_locomo10.py --num-samples 5       # quick subset
python test_locomo10.py --result-file my_results.json
```

### 🧬 EvolveMem — tự tiến hóa + LoCoMo / MemBench

Chạy từ thư mục `EvolveMem/` (xem [`EvolveMem/README.md`](../../EvolveMem/README.md)):

```bash
cd EvolveMem
python run_evolution.py --data data/locomo10.json --max-rounds 7
python run_benchmark.py locomo --sample 0 --initial weak --max-rounds 3
python run_benchmark.py membench --agent FirstAgent --max-rounds 3
```

### 🧠 Omni-SimpleMem — LoCoMo / Mem-Gallery

Chạy từ thư mục `OmniSimpleMem/` (xem [`OmniSimpleMem/README.md`](../../OmniSimpleMem/README.md)):

```bash
cd OmniSimpleMem
python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o
```

---

## 🗺️ Lộ Trình

Khả năng hiện tại theo kênh tích hợp:

| Khả năng | Python (`pip install`) | MCP server (Claude Desktop, Cursor, ...) |
|:--|:--:|:--:|
| Bộ nhớ văn bản | ✅ | ✅ |
| Đa phương thức (hình ảnh / âm thanh / video) | ✅ | ⬜ đang lên kế hoạch |
| Truy xuất tự tiến hóa `optimize()` | ✅ | ⬜ đang lên kế hoạch |

Công việc đã lên kế hoạch để thu hẹp khoảng cách (MCP server là dịch vụ văn bản đa tenant độc lập; đây là các tính năng thực sự, không phải bản sửa lỗi tài liệu):

- [ ] **Đa phương thức qua MCP.** Thêm các công cụ `memory_add_image` / `memory_add_audio` / `memory_add_video`. Cần một đường dẫn tải tệp lên (base64 hoặc URL, vì MCP không thể truyền đường dẫn tệp cục bộ), điều chỉnh đa tenant của backend lưu trữ Omni-SimpleMem, và khả năng truy cập model thị giác/âm thanh phía máy chủ.
- [ ] **EvolveMem qua MCP.** Hiển thị `optimize()` như một công cụ MCP. Khả thi hơn so với đa phương thức (văn bản vào, cấu hình JSON ra, không cần truyền tệp), nhưng bộ truy xuất MCP hiện tại chỉ hỗ trợ `semantic_top_k` / `keyword_top_k` trong số ~10 chiều mà EvolveMem tiến hóa. Cần mở rộng bộ truy xuất MCP để hỗ trợ các nút điều chỉnh còn lại (structured top_k, chế độ/trọng số hợp nhất, hoán đổi thực thể, phân rã truy vấn, xác minh câu trả lời), bộ điều hợp để chạy vòng lặp tiến hóa trên bộ nhớ đã lưu của tenant, lưu trữ cấu hình theo từng tenant, và thực thi bất đồng bộ (vòng lặp tốn nhiều tài nguyên LLM và sẽ hết thời gian với yêu cầu đồng bộ).
- [ ] **Docker** tự động kế thừa cả hai tính năng khi MCP server hỗ trợ chúng (thêm các phụ thuộc đa phương thức vào image và một volume lưu trữ Omni).

Để có đa phương thức đầy đủ và truy xuất tự tiến hóa ngay hôm nay, hãy sử dụng API Python (xem [Bắt Đầu Nhanh](#-bắt-đầu-nhanh)).

---

## 📝 Trích Dẫn

Nếu bạn sử dụng SimpleMem trong nghiên cứu của mình, vui lòng trích dẫn:

```bibtex
@article{simplemem2026,
  title={SimpleMem: Efficient Lifelong Memory for LLM Agents},
  author={Liu, Jiaqi and Su, Yaofeng and Xia, Peng and Zhou, Yiyang and Han, Siwei and  Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu},
  journal={arXiv preprint arXiv:2601.02553},
  year={2026},
  url={https://arxiv.org/abs/2601.02553}
}
```

```bibtex
@article{evolvemem2026,
  title={EvolveMem: Self-Evolving Memory Architecture via AutoResearch for LLM Agents},
  author={Liu, Jiaqi and Ye, Xinyu and Xia, Peng and Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu},
  journal={arXiv preprint arXiv:2605.13941},
  year={2026},
  url={https://arxiv.org/abs/2605.13941}
}
```

```bibtex
@article{omnisimplemem2026,
  title   = {Omni-SimpleMem: Autoresearch-Guided Discovery of Lifelong Multimodal Agent Memory},
  author  = {Liu, Jiaqi and Ling, Zipeng and Qiu, Shi and Liu, Yanqing and Han, Siwei and Xia, Peng and Tu, Haoqin and Zheng, Zeyu and Xie, Cihang and Fleming, Charles and Ding, Mingyu and Yao, Huaxiu},
  journal = {arXiv preprint arXiv:2604.01007},
  year    = {2026},
}
```

---

## 📄 Giấy Phép

Dự án này được cấp phép theo **Giấy Phép MIT** - xem tệp [LICENSE](../../LICENSE) để biết chi tiết.

---

## 🙏 Lời Cảm Ơn

Chúng tôi xin cảm ơn các dự án và nhóm sau:

- 🔍 **Mô Hình Nhúng**: [Qwen3-Embedding](https://github.com/QwenLM/Qwen) - Hiệu năng truy xuất tiên tiến nhất
- 🗄️ **Cơ Sở Dữ Liệu Vector**: [LanceDB](https://lancedb.com/) - Lưu trữ dạng cột hiệu năng cao
- 📊 **Benchmark**: [LoCoMo](https://github.com/snap-research/locomo) - Khung đánh giá bộ nhớ ngữ cảnh dài
