# SteelMem 🧠⚙️

**Живая векторная память для ИИ-агентов. Подключается как MCP-плагин за минуту — и у любого агента появляется память, которая сама себя актуализирует.**

> Трек «Open Source × AI» · Вайбкодинг ФКН, 25 октября 2026 · команда SteelRework

## Проблема

Память у агентов сегодня — «мешок фактов»: сохранили «планирую поехать на море» — и через полгода агент всё ещё спрашивает, как подготовка к поездке. Устаревшее не вычищается, дубли копятся, противоречия («живу в Казани» / «переехал в Москву») агент разруливать не умеет.

## Решение

SteelMem хранит воспоминания **со статусами во времени** (`ПЛАН → СДЕЛАНО / ОТМЕНЕНО / УСТАРЕЛО`) и добавляет **сонного агента** — фоновый процесс, который пока основной агент «спит», редактирует память:

| Действие | Пример |
|---|---|
| **COMPLETE** | «Планирую поехать на море в июле» + позже «Съездил на море в Сочи» → план помечен выполненным, оба связаны |
| **CANCEL** | «Собираюсь на концерт» + «Передумал идти на концерт» → план отменён |
| **SUPERSEDE** | «Живу в Казани» → «Переехал в Москву»: старое уходит в архив |
| **MERGE** | Дубли склеиваются |
| **STALE** | План висит 60+ дней без новостей → «уточнить у пользователя» |

Каждое изменение пишется в журнал `history` — видно, кто, когда и почему поменял память. Ничего не удаляется молча.

## Быстрый старт

```bash
git clone https://github.com/TimXa/SteelMem.git && cd SteelMem
pip install -e .
steelmem --user demo demo      # загрузить демо-историю
steelmem --user demo sleep     # 💤 сонный агент наводит порядок
steelmem web                   # дашборд: http://localhost:8765
```

## 🌌 Галактика памяти

`steelmem web` → **http://localhost:8765/galaxy** — вся память в 3D: звёзды-воспоминания, близкие по смыслу притягиваются в созвездия, оранжевые нити с частицами — связи, которые проставил сонный агент. Крути мышью, колесо — зум, наведи — прочитать, клик — перелёт к звезде и карточка с историей правок и соседями. Поиск подсвечивает нужные звёзды. Страница сама обновляется каждые 8 секунд — новые воспоминания появляются на лету.

`steelmem galaxy --out galaxy.html` — выгрузить галактику в один автономный HTML, чтобы отправить кому угодно.

Визуализация на [3d-force-graph](https://github.com/vasturiano/3d-force-graph) (MIT).

## 🎙 Любые данные в память

Формат заранее знать не нужно. Кидай что угодно, SteelMem сам разберётся:

```bash
steelmem --user me ingest ./что-угодно --watch    # файл, папка или архив; --watch следит за папкой
cat расшифровка.txt | steelmem --user me ingest -  # текст из stdin / вебхука кулона
steelmem --user me tg ./result.json --me "Имя"     # экспорт Telegram с опциями (--since, --chat, --dry-run)
```

Или перетащи файл в дашборд (`steelmem web`).

| Что кидаешь | Что происходит |
|---|---|
| `.zip` / `.tar` / `.tgz` | распаковывается (с защитой от zip-slip), содержимое разбирается рекурсивно |
| Экспорт Telegram (`result.json`, один чат или все) | разговоры по паузам 30 мин, владелец помечен «Я», пересылки, без дублей при повторной загрузке |
| **Любой другой JSON/JSONL** (Slack, Discord, WhatsApp, ваши выгрузки) | автоматически находятся «ленты» записей с текстом, временем и автором; без лент структура разворачивается в «ключ: значение» |
| txt, md, логи, код, srt, vtt | как текст; строки `[12:30] …` дают время реплик |
| csv / tsv / xlsx | строки как «колонка: значение» |
| eml / mbox, ics, vcf | письма, события календаря, контакты |
| html / xml | теги убираются |
| pdf, docx | текст (pdf: `pip install pypdf`) |
| mp3, wav, m4a, ogg… | расшифровка речи: локально `faster-whisper` или API `/audio/transcriptions` |
| png, jpg… | описание и распознавание текста через модель с vision |
| незнакомое | если это текст, он уходит модели как есть; бинарники пропускаются |

Одно и то же содержимое второй раз не добавляется (даже из другого файла или архива). Один испорченный файл не роняет весь импорт.

**С LLM-ключом (рекомендуется)** жёстких правил нет. Модель сама читает сырой текст, выделяет факты, планы, события, людей, идеи, понимает время («вчера», «в 15:20», «в следующем месяце») и ставит дату. Сонный агент тоже решает моделью: что выполнено, что отменено, что устарело, что дубль. Достаточно одного ключа: `OPENAI_API_KEY` или `OPENROUTER_API_KEY`, либо свой endpoint через `STEELMEM_LLM_BASE_URL` / `STEELMEM_LLM_MODEL` (Ollama, vLLM, российские модели через совместимый прокси).

**Без ключа** работает запасной режим на простых правилах RU/EN. Он годится для демо, но текст режет грубо, поэтому для кулона нужен LLM.

Пайплайн кулона: **микрофон → сервер (Whisper) → текст в папку → `ingest --watch` → память → любой агент читает через MCP, человек смотрит в галактике.**

## 🗺 Apple Embedding Atlas

`pip install 'steelmem[atlas]'` → `steelmem atlas` — вся память на интерактивной карте (кластеры, поиск, фильтры по статусу/типу/дате). `steelmem atlas --export atlas.zip` соберёт автономное приложение, которое можно открыть без Python. Это 2D-карта; 3D-галактика со связями сонного агента — `steelmem web` → `/galaxy`.

## 🔭 Чистые векторы в TensorFlow Embedding Projector

`steelmem projector --out projector` → открыть [projector.tensorflow.org](https://projector.tensorflow.org) → Load → `vectors.tsv` + `metadata.tsv`. PCA, t-SNE и UMAP в 3D, поиск и наведение готовые.

## Подключить как плагин к агенту (MCP)

Claude Desktop / Claude Code / Cursor / Cline — добавь в конфиг MCP-серверов:

```json
{
  "mcpServers": {
    "steelmem": {
      "command": "steelmem",
      "args": ["mcp"],
      "env": { "STEELMEM_USER": "me", "STEELMEM_SLEEP_EVERY": "30" }
    }
  }
}
```

Агент получает инструменты `remember`, `recall`, `forget`, `sleep`, `timeline`. `STEELMEM_SLEEP_EVERY=30` — сонный агент сам просыпается каждые 30 минут.

## Как библиотека

```python
from steelmem import SteelMem

mem = SteelMem()
mem.add("Планирую поехать на море в июле", user_id="vasya")
mem.add("Съездил на море, было круто", user_id="vasya")
mem.sleep(user_id="vasya")
print(mem.context("отпуск", user_id="vasya"))  # готовый блок для system prompt
```

## LLM — по желанию

Без ключей всё работает локально: свои эмбеддинги (char n-граммы, 512 dim) + правила для RU/EN. С LLM качество растёт: реплики разбиваются на атомарные факты, а сонный агент подтверждает связи «план ↔ событие» моделью. Подходит любой OpenAI-совместимый endpoint — OpenAI, Ollama, vLLM, российские модели через совместимый прокси.

```bash
export STEELMEM_LLM_BASE_URL=http://localhost:11434/v1   # например Ollama
export STEELMEM_LLM_MODEL=qwen2.5:7b
export STEELMEM_EMBED_MODEL=nomic-embed-text             # опционально
```

## Архитектура

```
агент ──MCP──► remember / recall ──► SteelMem (SQLite + векторы + статусы + history)
                                          ▲
                     сонный агент ────────┘  COMPLETE · CANCEL · SUPERSEDE · MERGE · STALE
                     (по таймеру / по кнопке / по вызову sleep)
```

- `steelmem/store.py` — хранилище, поиск (косинус + бонус за свежесть, архив скрыт)
- `steelmem/sleep.py` — сонный агент
- `steelmem/rules.py` — классификация план/событие/факт/предпочтение без LLM
- `steelmem/mcp_server.py` — MCP-плагин
- `steelmem/web.py` + `dashboard.html` — REST API и дашборд
- `steelmem/galaxy.py` + `galaxy.html` — 3D-галактика памяти
- `steelmem/ingest.py` — автоиндексация папок и транскриптов

## Чем отличаемся

Идея сонных агентов — из исследований sleep-time compute (Letta, Apache-2.0); подход «память как отдельный слой» — как у Mem0 (Apache-2.0). SteelMem берёт лучшее из обоих, но остаётся крошечным: один `pip install`, SQLite, работает без интернета и без ключей, а у каждого воспоминания есть **жизненный цикл**, а не только вектор.

## Лицензия

Apache-2.0