## Эффективная долгосрочная память для агентов LLM — текст и мультимодальность
Храните, сжимайте и извлекайте долгосрочные воспоминания с семантически сжатием без потерь. Теперь с поддержкой мультимодальности: текст, изображения, аудио и видео.
Работает с любой платформой ИИ, поддерживающей MCP (текстовая память) или Python-интеграцию (полная мультимодальность)
|
**📝 Auto → Text** (только текстовый ввод)
```python
from simplemem import SimpleMem
mem = SimpleMem() # auto mode
# add_dialogue() → автоматически выбирается текстовый бэкенд
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"
```
|
**🧠 Auto → Omni** (мультимодальный ввод)
```python
from simplemem import SimpleMem
mem = SimpleMem() # auto mode
# add_image() → автоматически выбирается omni-бэкенд
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()
```
|
> **💡 Совет**: Режим Auto выбирает наиболее лёгкий бэкенд, подходящий для ваших данных. При желании вы можете явно указать `mode="text"` или `mode="omni"`.
---
### 🧬 Расширенные возможности: оптимизация конфигурации поиска
Настройте гиперпараметры поиска офлайн на своей девелоперской выборке, затем разверните полученный `Config` для инференса. Это тонкая обёртка вокруг цикла самоэволюции EvolveMem:
```python
import simplemem
from simplemem import SimpleMem, load_config
# mem — финализированный экземпляр SimpleMem с уже построенными воспоминаниями
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")
# Позже разверните с оптимизированным конфигом
config = load_config("my_config.json")
mem = SimpleMem(config=config)
```
> EvolveMem запускает LLM-управляемый цикл Evaluate → Diagnose → Propose → Guard на ваших девелоперских вопросах, корректируя глобальные флаги поиска (top_k, режим слияния, верификация ответов, раунды рефлексии, ...). Для полной автономной версии с адаптерами бенчмарков и переопределениями по категориям см. [`EvolveMem/`](../../EvolveMem/).
---
### 🚄 Расширенные возможности: параллельная обработка
Для масштабной обработки диалогов включите параллельный режим:
```python
from simplemem import create
mem = create(
mode="text",
clear_db=True,
enable_parallel_processing=True, # ⚡ Параллельное построение памяти
max_parallel_workers=8,
enable_parallel_retrieval=True, # 🔍 Параллельное выполнение запросов
max_retrieval_workers=4
)
```
> **💡 Профессиональный совет**: Параллельная обработка существенно снижает задержку для пакетных операций!
---
## 🌟 Обзор
**SimpleMem** — унифицированный стек памяти для агентов LLM, построенный на одном принципе: хранить *семантически сжатую без потерь* память при высокой информационной плотности, чтобы агент вспоминал больше, тратя значительно меньше токенов. Пакет объединяет три работы, разделяющие этот принцип, но решающие разные части проблемы.
### 📝 SimpleMem: ядро эффективности (текст)
Большинство систем памяти вынуждают идти на плохой компромисс. Они либо пассивно накапливают необработанную историю взаимодействий (избыточно, требует много токенов), либо запускают дорогостоящие циклы рассуждений для фильтрации шума (медленно, затратно). SimpleMem вместо этого сжимает взаимодействия через трёхэтапный конвейер:
| Этап | Что делает |
|:--|:--|
| **1. Семантическое структурированное сжатие** | Перегоняет неструктурированные взаимодействия в компактные единицы памяти (самодостаточные факты с разрешёнными кореференциями и абсолютными временными метками), каждая из которых индексируется через несколько взаимодополняющих представлений для гибкого поиска. |
| **2. Онлайн-семантический синтез** | Объединяет связанный контекст внутри сессии в единые абстрактные представления, устраняя избыточность в процессе построения памяти, а не во время запроса. |
| **3. Планирование поиска с учётом намерения** | Определяет поисковое намерение запроса, чтобы решить *что* извлечь и собрать точный, компактный контекст. |
На бенчмарке LoCoMo это обеспечивает прирост среднего F1 на 26,4% по сравнению с предыдущими системами при сокращении потребления токенов во время инференса примерно в 30 раз. Детали механизма (слои гибридного индекса, примеры сжатия, планирование поиска): [**Текстовая память SimpleMem →**](../text-memory.md).
### 🧠 Omni-SimpleMem: мультимодальная память (текст, изображения, аудио, видео)
Omni-SimpleMem распространяет философию «сжатие прежде всего» на четыре модальности, основываясь на трёх принципах: **Избирательное поглощение** (энтропийная фильтрация по модальности), **Прогрессивный поиск** (гибридные FAISS + BM25 с пирамидальным расширением бюджета токенов) и **Дополнение графом знаний** (многошаговое кросс-модальное рассуждение). Архитектура была не разработана вручную, а *открыта* автономным исследовательским конвейером, проведшим около 50 экспериментов на двух бенчмарках, диагностируя режимы отказов, предлагая архитектурные изменения и даже исправляя баги в конвейере данных без участия человека во внутреннем цикле. Примечательно, что исправления багов и архитектурные изменения в совокупности дали больший вклад, чем весь подбор гиперпараметров, выведя систему с наивной базовой линии до состояния искусства на LoCoMo и Mem-Gallery. Полная документация: [**Omni-SimpleMem →**](../../OmniSimpleMem/).
### 🧬 EvolveMem: самоэволюционирующий поиск
EvolveMem закрывает слепое пятно, присущее почти каждой системе памяти: хранимое содержимое эволюционирует, но *механизм поиска* (функции оценки, стратегии слияния, политики генерации ответов) остаётся замороженным после развёртывания. EvolveMem запускает замкнутый процесс AutoResearch (**Evaluate → Diagnose → Propose → Guard → Repeat**), в котором LLM диагностирует ошибки по каждому вопросу и предлагает изменения конфигурации, защищённые автоматическим откатом при регрессии и стимулами к исследованию при стагнации. Система обнаруживает новые измерения поиска (декомпозиция запросов, замена сущностей, верификация ответов), отсутствовавшие в исходном дизайне, улучшает LoCoMo на 25,7% в относительном выражении по сравнению с сильнейшей базовой линией, а эволюционированные конфигурации положительно переносятся между бенчмарками. Полная документация: [**EvolveMem →**](../../EvolveMem/).
### Как они сочетаются
`from simplemem import SimpleMem` даёт текстовое ядро с автоматической маршрутизацией к мультимодальному бэкенду, а `simplemem.optimize(...)` задействует EvolveMem для настройки поиска под ваши данные. Один пакет, одна ментальная модель: сжимай без потерь, ищи по намерению, и пусть система продолжает самосовершенствоваться.
---
## 📦 Установка
### 📝 Примечания для новых пользователей
- Убедитесь, что используете **Python 3.10+ в активной среде**, а не только в глобальной установке.
- API-ключ, совместимый с OpenAI, должен быть настроен **до запуска любого построения памяти или поиска**, иначе инициализация может завершиться ошибкой.
- При использовании провайдеров, отличных от OpenAI (например, Qwen или Azure OpenAI), проверьте название модели и `OPENAI_BASE_URL` в `config.py`.
- Для больших наборов диалогов включение параллельной обработки может значительно сократить время построения памяти.
### 📋 Требования
- 🐍 Python 3.10+
- 🔑 API, совместимый с OpenAI (OpenAI, Qwen, Azure OpenAI и др.)
### 🛠️ Настройка
```bash
# 📥 Клонировать репозиторий
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem
# 📦 Установить зависимости (фиксированные версии)
pip install -r requirements.txt
# — ИЛИ — установить как редактируемый пакет
pip install -e . # по умолчанию: текст + мультимодальность + evolver
pip install -e ".[server]" # + MCP / HTTP server (mcp, fastapi, ...)
pip install -e ".[all]" # всё, включая инструменты разработки
# ⚙️ Настроить параметры API
cp config.py.example config.py
# Отредактируйте config.py: укажите ваш API-ключ и настройки
```
### ⚙️ Пример конфигурации
```python
# config.py
OPENAI_API_KEY = "your-api-key"
OPENAI_BASE_URL = None # или кастомный endpoint для Qwen/Azure
LLM_MODEL = "gpt-4.1-mini"
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B" # Передовая производительность поиска
```
---
## 🐳 Запуск с Docker
**MCP Server** можно запустить в Docker для обеспечения согласованной изолированной среды. Данные (LanceDB и пользовательская БД) сохраняются в томе хоста.
### Предварительные требования
- [Docker](https://docs.docker.com/get-docker/) и [Docker Compose](https://docs.docker.com/compose/install/)
### Быстрый запуск
```bash
# Из корня репозитория
docker compose up -d
```
- **Веб-интерфейс:** http://localhost:8000/
- **REST API:** http://localhost:8000/api/
- **MCP (SSE):** http://localhost:8000/mcp/sse?token=<TOKEN>
Данные хранятся в `./data` на хосте (создаётся автоматически).
### Пользовательская конфигурация
1. Скопируйте шаблон окружения и отредактируйте его:
```bash
cp .env.example .env
# Отредактируйте .env: установите JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, URL моделей и т.д.
```
2. Запустите с файлом окружения:
```bash
docker compose --env-file .env up -d
```
### Использование Ollama на хосте
Когда `LLM_PROVIDER=ollama` и Ollama запущена на вашей машине (не в Docker), укажите в `.env`:
```bash
LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1
```
На Linux `host.docker.internal` включается автоматически через файл Compose.
### Полезные команды
```bash
docker compose logs -f simplemem # Следить за логами
docker compose down # Остановить и удалить контейнеры
```
> 📖 Для самостоятельного хостинга MCP server (Docker или голый металл) см. [Документацию MCP](../../MCP/README.md).
---
## 🔌 MCP Server *(текстовая память)*
SimpleMem доступен как **облачный сервис памяти** через Model Context Protocol (MCP), обеспечивая бесшовную интеграцию с ИИ-ассистентами, такими как Claude Desktop, Cursor и другими MCP-совместимыми клиентами.
**🌐 Облачный сервис**: [mcp.simplemem.cloud](https://mcp.simplemem.cloud) — или разверните MCP server локально с помощью [Docker](#-запуск-с-docker).
### Ключевые возможности
| Возможность | Описание |
|---------|-------------|
| **Streamable HTTP** | Протокол MCP 2025-03-26 с JSON-RPC 2.0 |
| **Мультитенантная изоляция** | Отдельные таблицы данных для каждого пользователя с токен-аутентификацией |
| **Гибридный поиск** | Семантический поиск + поиск по ключевым словам + фильтрация по метаданным |
| **Оптимизация для продакшена** | Более быстрое время отклика с интеграцией OpenRouter |
### Быстрая настройка
```json
{
"mcpServers": {
"simplemem": {
"url": "https://mcp.simplemem.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
```
> 📖 Подробные инструкции по настройке и руководство по самохостингу см. в [Документации MCP](../../MCP/README.md)
---
## 📊 Воспроизведение результатов статьи
Воспроизведите числа LoCoMo / MemBench / Mem-Gallery из статей. У каждой составляющей есть свой запускатель бенчмарка в собственной директории. Сначала установите дополнительные зависимости для бенчмарков: `pip install -e ".[benchmark]"`.
### 📝 SimpleMem (текст) — LoCoMo
Запуск из корня репозитория:
```bash
python test_locomo10.py # полный бенчмарк LoCoMo
python test_locomo10.py --num-samples 5 # быстрая подвыборка
python test_locomo10.py --result-file my_results.json
```
### 🧬 EvolveMem — самоэволюция + LoCoMo / MemBench
Запуск из директории `EvolveMem/` (см. [`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
Запуск из директории `OmniSimpleMem/` (см. [`OmniSimpleMem/README.md`](../../OmniSimpleMem/README.md)):
```bash
cd OmniSimpleMem
python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o
```
---
## 🗺️ Дорожная карта
Текущие возможности по каналу интеграции:
| Возможность | Python (`pip install`) | MCP server (Claude Desktop, Cursor, ...) |
|:--|:--:|:--:|
| Текстовая память | ✅ | ✅ |
| Мультимодальность (изображения / аудио / видео) | ✅ | ⬜ планируется |
| Самоэволюционирующий поиск `optimize()` | ✅ | ⬜ планируется |
Запланированные работы для устранения разрыва (MCP server — это автономный мультитенантный текстовый сервис; это реальные функции, а не правки документации):
- [ ] **Мультимодальность через MCP.** Добавить инструменты `memory_add_image` / `memory_add_audio` / `memory_add_video`. Требуется путь загрузки файлов (base64 или URL, поскольку MCP не может передавать локальные пути к файлам), мультитенантная адаптация бэкенда хранения Omni-SimpleMem и серверный доступ к моделям зрения/аудио.
- [ ] **EvolveMem через MCP.** Открыть `optimize()` как инструмент MCP. Более реализуемо, чем мультимодальность (текст на входе, JSON-конфиг на выходе, без транспортировки файлов), но текущий MCP-ретривер поддерживает только `semantic_top_k` / `keyword_top_k` из ~10 измерений, которые эволюционирует EvolveMem. Требует расширения MCP-ретривера для поддержки оставшихся параметров (structured top_k, режим/веса слияния, замена сущностей, декомпозиция запросов, верификация ответов), адаптера для запуска цикла эволюции на сохранённых воспоминаниях арендатора, персистентности конфигурации для каждого арендатора и асинхронного выполнения (цикл тяжёл в части LLM и превысит тайм-аут синхронного запроса).
- [ ] **Docker** автоматически наследует оба улучшения, как только MCP server их поддержит (добавить мультимодальные зависимости в образ и том хранилища Omni).
Для полной мультимодальности и самоэволюционирующего поиска сегодня используйте Python API (см. [Быстрый старт](#-быстрый-старт)).
---
## 📝 Цитирование
Если вы используете SimpleMem в своих исследованиях, пожалуйста, цитируйте:
```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},
}
```
---
## 📄 Лицензия
Этот проект распространяется под лицензией **MIT** — подробности в файле [LICENSE](../../LICENSE).
---
## 🙏 Благодарности
Мы хотели бы поблагодарить следующие проекты и команды:
- 🔍 **Модель эмбеддингов**: [Qwen3-Embedding](https://github.com/QwenLM/Qwen) — передовая производительность поиска
- 🗄️ **Векторная база данных**: [LanceDB](https://lancedb.com/) — высокопроизводительное колоночное хранилище
- 📊 **Бенчмарк**: [LoCoMo](https://github.com/snap-research/locomo) — фреймворк оценки памяти с длинным контекстом
