Память ИИ-агента с Redis: как запоминать пользователей

Память ИИ-агента с Redis позволяет вашему приложению сохранять контекст между вызовами модели и загружать его при возвращении того же пользователя. Модель видит этот контекст в своем следующем запросе. Redis хранит данные; ваше приложение решает, что сохранять, извлекать и забывать.

В этом руководстве небольшой помощник на Python запоминает, что Алиса предпочитает вегетарианские блюда. Мы останавливаем один процесс Python, запускаем другой с новым идентификатором сессии и просим его вспомнить ее предпочтения. Боб получает отдельный профиль. Команда забывания удаляет активные записи Алисы в Redis.

Вы можете запустить пример локально, а затем подключить тот же код к Managed Redis в Lizard. Он использует стандартные команды Redis Hash и List, поэтому для этого руководства не требуются векторный индекс, RedisJSON или фреймворк для агентов.

Протестировано 25 сентября 2026 года: Python 3.12.10, Redis 8.8.0, redis-py==5.2.1 и четыре реальных вызова к openai/gpt-4.1-mini через OpenRouter. Все 16 проверок пройдены. Тест охватывал отдельные процессы приложения и сессии на локальном экземпляре Redis. Он не охватывал размещенный экземпляр, параллельные запросы или восстановление после сбоя Redis.

Что должен помнить ИИ-агент?

Начните с двух типов данных. Им нужны разные ключи и правила хранения.

Профиль принадлежит пользователю, поэтому новая сессия может его прочитать. История разговора принадлежит одному пользователю и одной сессии. Запуск второй сессии не копирует стенограмму первой сессии.

Это различие имеет значение, когда агент отвечает на вопрос «Что ты обо мне знаешь?». Недавнее сообщение может исчезнуть из ограниченного списка истории. Сохраненное предпочтение имеет свой собственный срок хранения. Ни то, ни другое не должно оставаться в контексте модели вечно.

Redis также предлагает отдельный сервис Redis Agent Memory service. В этом руководстве создается небольшой слой памяти в коде приложения с использованием подключения к Redis. Оно не использует этот сервис или его функции автоматического извлечения.

1. Настройка демо

Вам понадобится Python 3.10 или новее, одноразовый экземпляр Redis и API-ключ OpenRouter. Используйте выдуманные предпочтения во время тестирования: сохраненный профиль и выбранные сообщения чата отправляются провайдеру модели при каждом вызове.

Скачайте полную, проверенную программу и установите ее единственную зависимость Python:

mkdir redis-memory-demo
cd redis-memory-demo
python3 -m venv .venv
. .venv/bin/activate
python -m pip install redis==5.2.1
curl -fsSLo memory_agent.py \
  https://lizard.build/blog-examples/redis-agent-memory/memory_agent.py

Для локального теста запустите Redis в отдельном терминале. Эта команда привязывает его к loopback на порту 6387; оставьте этот терминал открытым:

redis-server --bind 127.0.0.1 --port 6387 --save "" --appendonly no

Этот локальный процесс Redis намеренно сделан одноразовым. Его данные остаются доступными при завершении работы приложения Python, но остановка Redis приводит к потере этих данных. В тесте ниже перезапускается приложение, а не база данных.

Создайте приватный файл .env в каталоге демо с помощью вашего редактора:

REDIS_URL=redis://127.0.0.1:6387/0
OPENROUTER_API_KEY=replace-with-your-key
OPENROUTER_MODEL=openai/gpt-4.1-mini

Не добавляйте .env в Git. Ограничьте доступ и загрузите его в текущую оболочку:

chmod 600 .env
set -a
. ./.env
set +a

Пример вызывает OpenRouter Chat Completions API. Redis выполняет те же операции чтения и записи в память, если вы замените вызов модели на другого провайдера.

2. Выделите каждому пользователю и сессии свои ключи

Программа создает ключи вроде этих:

agentmem:v1:{alice}:profile
agentmem:v1:{alice}:session:session-1
agentmem:v1:{alice}:session:session-2
agentmem:v1:{bob}:profile

Префикс версии дает будущим форматам данных отдельное пространство имен. Идентификатор пользователя разделяет профили. Идентификатор сессии разделяет разговоры. Фигурные скобки — это хеш-тег Redis; они сохраняют ключи одного пользователя в одном хеш-слоте, если вы позже будете использовать Redis Cluster. В этом руководстве тестируется один экземпляр Redis.

Демо проверяет идентификаторы перед созданием ключей. В веб-приложении получайте идентификатор пользователя из аутентифицированной сессии сервера. Не принимайте идентификатор другого пользователя из тела запроса и не считайте его доказательством личности. Сами по себе имена ключей Redis не контролируют, кто может получить доступ к данным пользователя.

3. Сохранение явного предпочтения

Сохраните выбор Алисы:

python memory_agent.py remember --user alice --preference vegetarian

Команда выводит Preference saved. Внутри она записывает поле в Redis Hash и устанавливает срок действия профиля в транзакции:

with client.pipeline(transaction=True) as tx:
    tx.hset(profile, mapping={"dietary_preference": preference})
    tx.expire(profile, 30 * 24 * 60 * 60)
    tx.execute()

Допустимыми значениями являются только vegetarian, vegan и no_preference. Эта небольшая схема делает пример простым для изучения. Модель не может записывать произвольные утверждения в профиль. В реальном продукте кнопка «Запомнить это» может выполнять такую же проверенную запись после подтверждения пользователем.

Это руководство не выводит предпочтения из каждого сообщения чата. Для изменения или исправления предпочтения используется та же явная команда, которая перезаписывает это поле и обновляет его 30-дневный TTL.

4. Загрузка памяти перед вызовом модели

Попросите помощника вспомнить сохраненный выбор:

python memory_agent.py chat --user alice --session session-1 \
  --message "What dietary preference have I saved?"

В нашем тесте модель ответила:

Your saved dietary preference is vegetarian.

При каждом вызове приложение читает профиль пользователя и недавние сообщения текущей сессии. Оно формирует запрос к модели в следующем порядке:

1. Инструкции, определяющие задачу помощника.
2. Сообщение с данными, содержащее допустимое сохраненное предпочтение.
3. Недавние сообщения пользователя и помощника из этой сессии.
4. Новый вопрос пользователя.

У модели нет прямых учетных данных Redis или общего инструмента базы данных. Она получает только выбранный контекст. После успешного ответа приложение сохраняет новые сообщения пользователя и помощника вместе:

with client.pipeline(transaction=True) as tx:
    tx.rpush(history, *rows)
    tx.ltrim(history, -20, -1)
    tx.expire(history, 24 * 60 * 60)
    tx.execute()

Каждый обмен добавляет два сообщения, поэтому список хранит последние десять полных обменов. Приложение также ограничивает каждое сообщение 2000 символами. Одно только количество сообщений не ограничило бы размер контекста, если бы одно сообщение могло содержать целую книгу.

В этом примере чтение памяти не продлевает срок ее действия. Записи в профиль обновляют TTL профиля; завершенные обмены в чате обновляют TTL сессии. См. справочник Redis EXPIRE, чтобы узнать, как срок действия взаимодействует с обновлениями.

5. Запуск нового процесса и новой сессии

Каждая команда CLI запускает и завершает свой собственный процесс Python. Выполните вторую команду чата с другим идентификатором сессии:

python memory_agent.py chat --user alice --session session-2 \
  --message "What dietary preference have I saved?"

Модель снова вернула Your saved dietary preference is vegetarian. Новая сессия началась без сообщений из первого разговора. Ее запрос содержал общий профиль пользователя, чего было достаточно для ответа.

Изучите записи, которые читает приложение:

python memory_agent.py inspect --user alice --session session-2

Вы должны увидеть профиль с dietary_preference и историю с вопросом пользователя и ответом помощника из этой сессии. Этот процесс не меняет веса модели и не создаёт у неё постоянную внутреннюю память. Приложение предоставляет сохраненный контекст при каждом запросе.

6. Проверка разделения пользователей и забывания

Сначала изучите контекст другого пользователя:

python memory_agent.py inspect --user bob --session session-1

Для нового профиля Боба результат такой:

{
  "profile": {},
  "history": []
}

В ответ на тот же вопрос помощник Боба выдал Your dietary preference is unknown. в нашем тесте. Пустой контекст — это детерминированная проверка изоляции; формулировки модели могут различаться.

Затем остановите любые запросы для Алисы и удалите ее активную память в Redis:

python memory_agent.py forget-user --user alice
python memory_agent.py inspect --user alice --session session-1
python memory_agent.py inspect --user alice --session session-2

Обе проверки должны вернуть пустые профили и истории. Команда сканирует только проверенный префикс ключа Алисы и удаляет совпадающие ключи. Она не трогает ключи Боба.

Для развернутого приложения блокируйте новые записи для этого пользователя во время выполнения удаления. Иначе ответ, который завершится во время сканирования, может воссоздать сессию. Удаление ключей Redis также не удаляет журналы провайдера, резервные копии или записи в другой базе данных; этим хранилищам нужны собственные правила хранения и удаления.

Что мы проверили

Скрипт проверки запускает новый процесс Redis на доступном порту loopback. Он никогда не подключается к существующей базе данных. Его сохраненные результаты фиксируют версии, границы теста и четыре ответа модели.

Скрипт выполнил 16 проверок. Эти результаты показывают, что чтение и запись в примере работают так, как описано. Они не гарантируют доступность в рабочей среде или восстановление данных.

Подключение примера к Managed Redis

После локального теста создайте отдельный экземпляр Redis для вашего проекта. В связанном проекте Lizard выполните:

lizard add redis

Для развернутого сервиса с именем api задайте ссылку на подключение и выполните повторное развертывание:

lizard secrets set REDIS_URL='${{redis.REDIS_URL}}' --service api
lizard redeploy --service api

Эти команды предполагают, что сервис уже существует и у него настроен API-ключ модели. Они подключают этот сервис к Redis; само демо CLI не является HTTP-сервером. Следуйте руководству по подключению Managed Redis для настройки переменных окружения и доступа с вашего компьютера.

Вы можете изучить ключи демо в браузере Redis на панели управления. Храните учетные данные Redis на сервере и используйте приватное подключение или проверенный TLS, когда ваш провайдер предоставляет его. Обычный URL redis:// не добавляет транспортное шифрование.

Решите, какие воспоминания должны пережить потерю данных

То, что память переживает перезапуск приложения, не означает, что она переживет любой сбой Redis. Срок действия, вытеснение ключей, настройки сохранения и резервные копии — все это имеет значение.

Managed Redis в настоящее время документирует политику вытеснения allkeys-lru: нехватка памяти может удалить любой ключ, включая профиль, чей TTL еще не истек. Для предпочтений, которые вы не можете позволить себе потерять, храните исходную запись в Managed Postgres и используйте Redis для недавнего контекста или копии, которую можно восстановить. Изучите руководство по хранению и восстановлению перед выбором политики хранения.

Перед добавлением веб-API

CLI делает пример небольшим. Общему приложению также требуются:

• Проверки аутентификации и владения. Получайте идентификаторы пользователей на сервере и проверяйте, что каждая сессия принадлежит этому пользователю.
• Один активный обмен на сессию. Ставьте в очередь или блокируйте полную последовательность чтение → вызов модели → запись. Одна только финальная транзакция Redis не помешает двум вызовам модели прочитать один и тот же старый контекст.
• Ограничения объёма памяти. Ограничьте поля профиля, размер сообщения, длину истории и количество сессий. Отслеживайте память Redis и вытеснения.
• Политика при сбоях Redis. Явно отклоняйте запрос или предлагайте режим без сохранения состояния. Никогда не утверждайте, что предпочтение было сохранено, если запись не удалась.
• Отделение полномочий от запомненного текста. Сохраненное сообщение может содержать враждебные инструкции. Храните разрешения и решения по инструментам в коде приложения; системный промпт не является границей контроля доступа.

Частые вопросы

Нужна ли мне векторная база данных для памяти ИИ-агента?

Вы можете загрузить явные предпочтения известного пользователя и недавние сообщения по ключу, как это делает данный пример. Векторный поиск становится полезным, когда приложение должно находить релевантные факты в гораздо большем наборе воспоминаний. Это добавляет эмбеддинги, настройку индекса и тесты извлечения.

Заставляет ли Redis агента помнить вечно?

Хранение зависит от TTL, вытеснения, сохранения и записей вашего приложения. Этот пример намеренно ограничивает срок действия данных. Храните долговечные записи в другом месте, если их потеря сломает продукт.

Это RAG или семантический кэш?

Этот пример извлекает сохраненный контекст одного пользователя. RAG обычно извлекает релевантный исходный материал, чтобы помочь ответить на вопрос. Семантический кэш повторно использует предыдущий ответ для похожего запроса. Они могут использовать общую инфраструктуру Redis, но им нужны разные модели данных и тесты.

Могу ли я использовать LangGraph позже?

Да. LangGraph предлагает контрольные точки для состояния разговора и хранилища для памяти между диалогами. Его интеграция с Redis имеет свои собственные требования; изучите документацию пакета LangGraph Redis перед заменой этого простого клиента на бэкенд фреймворка.

Добавьте агенту память, которую можно проверить

Начните с одного явно сохранённого факта, отдельной истории сессии и проверки чтения данных из нового процесса. Добавьте срок действия, проверки владения и способ забывания, прежде чем добавлять автоматическое извлечение или векторный поиск.

Создайте Managed Redis для общего контекста приложения. Если вашему агенту также нужно запрашивать структурированные данные проекта, руководство по Postgres MCP описывает это подключение с отдельной ролью читателя базы данных.