Я создал agent-memory-state — open-source Python библиотеку для управления персистентной памятью AI агентов. Реализует паттерн state-based memory из OpenAI Cookbook: профиль пользователя, разделение session/global памяти, LLM-консолидация и защитные механизмы.

Проблема: Агенты без памяти — безликие

Каждый раз, начиная новый разговор с AI-ассистентом, он забывает всё. Ваши диетические предпочтения, привычки в путешествиях, рабочий контекст — стёрты. Приходится объяснять одно и то же снова и снова.

Это не просто раздражает — это фундаментальное ограничение. Переход от «отвечать» к «помнить» определяет новый рубеж AI-агентов. Агент, который помнит, становится коллаборатором, а не просто инструментом.

Решение: State-Based Memory

Изучив паттерн персонализации контекста из OpenAI Cookbook, я создал библиотеку, реализующую эту архитектуру:

┌─────────────────────────────────────────────┐
│                MemoryState                   │
├─────────────────────────────────────────────┤
│  profile: {name, email, loyalty_status}     │
│  global_memory: [персистентные заметки]     │
│  session_memory: [заметки текущей сессии]   │
└─────────────────────────────────────────────┘
          ↓ to_system_prompt()
┌─────────────────────────────────────────────┐
│  ---                                        │
│  name: Alice                                │
│  loyalty_status: gold                       │
│  ---                                        │
│                                             │
│  ## User Memory                             │
│  - [dietary] Предпочитает вегетарианское    │
│  - [travel] Обычно бронирует место у прохода│
└─────────────────────────────────────────────┘

Ключевая архитектура

1. State Object

from agent_memory import MemoryState

state = MemoryState(user_id="user_123")
state.profile["name"] = "Alice"
state.profile["loyalty_status"] = "gold"

State содержит:

Profile: Жёсткие факты (имя, email, уровень членства)
Global Memory: Персистентные предпочтения между сессиями
Session Memory: Временные заметки текущего разговора

2. Инъекция памяти

# Генерируем системный промпт с памятью
system_prompt = state.to_system_prompt()

# Или с защитными разделителями
system_prompt = state.to_memory_block()  # Оборачивает в <memory>...</memory>

Формат вывода:

Профиль как YAML frontmatter
Заметки как Markdown список с датами
Сессионные заметки с префиксом [SESSION]

3. Дистилляция памяти

Во время разговора агент захватывает устойчивые предпочтения:

state.add_session_note(
    text="Пользователь предпочитает вегетарианскую еду в поездках",
    keywords=["dietary"],
    confidence=0.9
)

Или используйте как инструмент агента:

from agent_memory import create_save_memory_tool, SAVE_MEMORY_TOOL_SCHEMA

save_memory = create_save_memory_tool(state)
tools = [SAVE_MEMORY_TOOL_SCHEMA]  # Для OpenAI function calling

4. Консолидация памяти

После сессии объединяем session notes в global memory:

from openai import AsyncOpenAI

client = AsyncOpenAI()
await manager.consolidate(state, client)

LLM выполняет:

Дедупликацию: Слияние семантически похожих заметок
Разрешение конфликтов: Новая информация побеждает
Фильтрацию: Отбрасывает сессионные заметки («только для этой поездки»)

Р��альный вывод (Travel Agent Demo):

Пользователь во время разговора:

"Я стал вегетарианцем, учти это для еды"
"Для этой поездки хочу место у окна — посмотреть на Фудзи"

Агент сохраняет обе заметки в session memory. После разговора:

До консолидации (5 заметок):
  - [baggage, short_trip] Для коротких поездок предпочитает без багажа
  - [seat_preference, flight] Обычно предпочитает место у прохода
  - [neighborhood, hotel] Любит центральные районы
  - [dietary] Вегетарианец                                        ← SESSION
  - [seat, flight] Только для этой поездки: хочет окно для Фудзи  ← SESSION

[Consolidation] LLM merge: {'merged': 2, 'discarded': 2, 'total': 3}

После консолидации (3 заметки):
  - [dietary] Предпочитает вегетарианскую еду в поездках          ✅ СОХРАНЕНО
  - [travel, flight] Обычно предпочитает место у прохода          ✅ ОБЪЕДИНЕНО
  - [neighborhood, hotel] Любит центральные районы                ✅ СОХРАНЕНО

❌ "окно только для этой поездки" — корректно отброшено (session-specific)

5. Защитные механизмы (Guardrails)

from agent_memory.guardrails import GuardedMemoryState, GuardrailConfig

config = GuardrailConfig(
    max_note_length=500,
    max_notes_per_user=100,
    block_ssn=True,
    block_credit_card=True,
    block_instructions=True,
)

guarded = GuardedMemoryState(state, config)
guarded.add_session_note("Мой SSN 123-45-6789")  # Вызывает ValueError

Блокирует:

PII паттерны (SSN, кредитные карты, телефоны)
Инъекцию инструкций («игнорируй предыдущие инструкции...»)
Превышение лимитов

Бэкенды хранения

In-Memory (Тестирование)

from agent_memory.storage import InMemoryStorage

manager = MemoryManager(storage=InMemoryStorage())

SQLite (Продакшен)

from agent_memory.storage import SQLiteStorage

manager = MemoryManager(storage=SQLiteStorage("./memory.db"))

Полный пример

from agent_memory import MemoryManager
from agent_memory.storage import SQLiteStorage
from openai import AsyncOpenAI

# Инициализация
manager = MemoryManager(storage=SQLiteStorage("./memory.db"))
state = manager.load_user("alice_123")

# Настройка профиля
state.profile["name"] = "Alice"
state.profile["loyalty_status"] = "gold"

# Формируем системный промпт
base_prompt = "Ты — туристический консьерж."
memory_block = state.to_memory_block()
system_prompt = f"{base_prompt}\n\n{memory_block}"

# Во время разговора — агент вызывает save_memory tool
state.add_session_note(
    text="Вегетарианец — предпочитает вегетарианские блюда",
    keywords=["dietary"],
    confidence=1.0
)

# После разговора — консолидация
client = AsyncOpenAI()
await manager.consolidate(state, client)

# Сохраняем для следующей сессии
manager.save(state)

Когда НЕ использовать память

Не каждому агенту нужна долгосрочная память. Простой тест:

Если агент запомнит что-то из предыдущего взаимодействия, это материально поможет решить задачу лучше или быстрее?

Пропустите память для:

Разовых задач (генерация кода, перевод)
Stateless утилит (калькуляторы, конвертеры)
Высоконагруженных API, где важна латентность

Используйте память для:

Персональных ассистентов
Агентов службы поддержки
Систем обучения/коучинга
Любых агентов с повторяющимися пользователями

Установка

pip install agent-memory-state

# С поддержкой OpenAI (для консолидации)
pip install "agent-memory-state[openai]"

Что дальше

Это v0.1.0 — фундамент. Планируемые фичи:

Vector-based retrieval для больших хранилищ памяти
Decay памяти с деградацией confidence со временем
Мульти-агентный шаринг памяти
Аналитика памяти (что запоминается, как часто используется)

Системы памяти улучшаются через итерации с измерениями, а не через изначальную сложность. Начните просто, оценивайте строго, развивайте осознанно.

Ссылки:

GitHub: https://github.com/molchanovartem/agent-memory
OpenAI Cookbook: Context Personalization

Я реализовал паттерн памяти из OpenAI Cookbook в Python библиотеку