Архитектура памяти ИИ-агента: чекпоинты и векторные хранилища

Viacheslav Dubrov

2026-02-14 · Обновлено 2026-09-06 · 32 мин · ИИ-агенты

Автоматический перевод Эта статья была автоматически переведена с оригинальной английской версии.

Обновление статьи

Изначально опубликовано 14 февраля 2026 года. Проверено и обновлено 6 сентября 2026 года. В обновлении рассматриваются компактизация контекста, бенчмарки памяти и API хранилищ, а также уточняются различия между рабочим состоянием, чекпоинтами и долгосрочной памятью.

Цикл ризонинга переживает только один запрос, если его состояние не сохраняется за пределами воркера. Без памяти агента агент не сможет продолжить приостановленный план, восстановиться после сбоя или вспомнить предпочтение из предыдущей сессии. В части 1 рассматривался control flow. В этой статье определено, какое состояние требуется каждому следующему ходу и где оно должно храниться.

Для обсуждения горячих чекпоинтов я буду использовать Market Analyst Agent — небольшого агента на LangGraph, который получает рыночные данные и пишет аналитический отчёт. Разделы о холодной векторной памяти и сыром Markdown — независимые иллюстративные дизайны, показывающие расширения, пока не реализованные в текущем проекте. Затем я разберу, когда имеют смысл PostgreSQL, Redis, Qdrant, key-value-хранилища и обычные Markdown-файлы.

Коротко: для паузы и продолжения используйте checkpoint store. Для точных пользовательских фактов — структурированное хранилище; добавляйте vector retrieval только когда формулировки запросов различаются. Используйте файлы, если людям нужно просматривать и редактировать накопленные знания о проекте. Чекпоинт сохраняет состояние; граф и харнесс по-прежнему решают, что с ним делать.

Каждое хранилище ниже читает харнесс — код, который запускает цикл вокруг модели. Именно харнесс решает, какая часть содержимого попадёт в контекстное окно; сами хранилища этого не делают. Эта статья посвящена тому, где состояние находится до того, как харнесс обратится к нему. В частях 3 и 4 рассматривается, что харнесс затем делает с промптом.

Что такое память ИИ-агента?

Память ИИ-агента — это слой состояния, который позволяет агенту сохранять прогресс задачи, извлекать предыдущие знания и обновлять то, что ему известно, между запусками. Дизайн может использовать чекпоинты, семантические или структурированные хранилища и документы, понятные человеку. Выбирайте только те хранилища, которые нужны продукту для восстановления и извлечения информации.

Не начинайте с памяти только потому, что она звучит интеллектуально. Начните с пользовательской проблемы: потеря прогресса, забытое предпочтение, повторное исследование или невозможность повторно использовать соглашение проекта.

Сбои, для которых нужна память

Агент без состояния может ответить на изолированный вопрос, но забывает запрос сразу после завершения вызова. Такой дизайн не подходит, когда продукту нужны следующие сценарии:

• Пауза и продолжение: пользователь начинает исследовательскую задачу, закрывает ноутбук и возвращается на следующий день. Без состояния, сохранённого в чекпоинте, агент начнёт всё заново.
• Согласованность между ходами: в длинном разговоре агент должен помнить, какие инструменты он вызывал, какие данные собрал и какие шаги плана завершил.
• Персонализация: вернувшийся пользователь ожидает, что агент знает его толерантность к риску, предпочитаемую глубину анализа и предыдущие взаимодействия.
• Human-in-the-loop (HITL): агент собирает доказательства и ждёт, пока человек одобрит следующий шаг. Состояние ожидания должно переживать перезапуск процесса.

В Market Analyst Agent из части 1 запрос «Проанализируй NVDA» приводит к созданию плана, пяти вызовам инструментов, сбору данных и черновику отчёта. Когда пользователь отвечает «выглядит хорошо, но добавь анализ конкурентов», чекпоинт восстанавливает план и исследование с последнего завершённого шага. Добавление шага анализа конкурентов потребовало бы дополнительной интерпретации и перепланирования; companion-проект это поведение не реализует. Чекпоинт предоставляет предыдущее состояние, а приложение должно решить, как новый запрос меняет план.

Долгосрочная память решает другую задачу. Если пользователь возвращается через неделю и спрашивает: «Обнови мой анализ NVDA», агенту может понадобиться вспомнить предпочтение консервативных оценок риска и интерес к акциям полупроводниковых компаний. Векторное memory store может извлечь эти факты между сессиями, не запрашивая их повторно.

Примеры реализации ниже используют LangGraph — open-source библиотеку LangChain для построения агентов в виде явных графов состояний; границы хранения, которые она задаёт, обобщаются на любой фреймворк. Представим продолжающийся разговор пользователя «Проанализируй NVDA» как один thread. Каждый запуск графа для ответа или продолжения — это один run внутри этого thread. Пока run активен, контекст модели и локальные переменные программы образуют её рабочую память; после остановки работы они исчезают. LangGraph называет состояние, сохранённое для одного thread, краткосрочной памятью, а факты, доступные другим thread, — долгосрочной памятью. Ниже «thread» и «conversation» означают одно и то же. В части 5 термин «session» используется для долговечного лога одного запуска, поэтому в этой статье он не обозначает разговор.

Таксономия памяти ИИ-агента

Прежде чем переходить к реализации, полезно классифицировать то, что агенту нужно помнить. Фреймворк CoALA — Cognitive Architectures for Language Agents (Sumers, Yao et al., 2023) — широко цитируемая таксономия, основанная на когнитивной науке. В своей статье о контекст-инжиниринге я ввёл области памяти; здесь расширю их до шести категорий:

Рабочая память содержит текущие наблюдения, извлечённые факты и промежуточные результаты активного run. Часть из них находится в переменных приложения; выбранные сообщения и результаты tool call формируют вход модели. Этот вход должен помещаться в контекстное окно модели, тогда как состояние приложения может быть больше и сохраняться между несколькими шагами. Память процесса теряется при сбое, если её явно не сохранить. Остальные уровни поставляют информацию в это рабочее состояние.

Краткосрочная память — это чекпоинт, который LangGraph записывает после каждой единицы выполнения графа — super-step, определяемого в следующем разделе. Эпизодическая и семантическая память сохраняются между thread. Документная память хранит заметки проекта, резюме исследований и выученные соглашения в файлах, которые могут просматривать люди и агенты. Процедурная память включает системные инструкции, определения инструментов и повторно используемые процедуры, которые могут извлекаться для задачи. Сроки жизни в таблице приведены для иллюстрации; хранение определяется политикой приложения, а рабочее состояние может существовать в течение всего активного run.

С точки зрения реализации эти шесть типов сводятся к трём уровням хранения. Краткосрочная память становится горячей памятью — чекпоинтом текущего thread. Эпизодическая и семантическая память становятся холодной памятью — извлечением между thread. Документная память сохраняет накопленные знания о проекте в формате, который можно читать и редактировать напрямую. Рабочая память объединяется с горячим уровнем, поскольку чекпоинты могут сохранять состояние, необходимое для восстановления активного run. Чекпоинт — это не полное внутреннее вычисление модели. Процедуры могут поставляться вместе с агентом либо храниться и извлекаться из файлов или другого хранилища. Эти уровни описывают варианты реализации в этой статье, а не взаимоисключающие типы памяти.

CoALA классифицирует рабочую, эпизодическую, семантическую и процедурную память. В обзоре Memory in the Age of AI Agents память организована вместо этого по форме, функции и динамике; туда входят документы, кодовые базы и повторно используемые workflow. Файлы могут реализовывать несколько таких категорий. В этой статье документная память выделена отдельно, чтобы сделать видимыми её обязанности по хранению и обслуживанию.

Тот же паттерн хранения встречается и в других областях. Minecraft-агент Voyager хранит повторно используемые игровые навыки в виде библиотек кода, а web-агенты выводят повторно используемые workflow браузинга из успешных запусков. К обоим примерам я вернусь позже. Просматриваемые файлы и индексированный retrieval могут сосуществовать: Voyager извлекает программы с помощью эмбеддингов их описаний.

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

В статье Generative Agents (Park et al., 2023) показано, насколько далеко это можно развить: симулированные агенты сохраняли, анализировали и извлекали собственные воспоминания. Его поток памяти ранжировал кандидатов по давности, важности и релевантности — этот дизайн по-прежнему служит полезной точкой отсчёта для retrieval памяти агентов.

Компактизация сохраняет пригодность разговора

Большее контекстное окно не отменяет необходимости выбирать, что должно сохраниться. Современные API могут суммировать старую часть разговора до заполнения окна. Server-side compaction в Claude, всё ещё beta-функция на 2026-09-06, возвращает блок compaction, который последующие запросы используют вместо более раннего содержимого. Это может уменьшить объём работы по суммаризации на стороне клиента, но из резюме может исчезнуть факт, нужный позднее.

Храните авторитетное состояние задачи за пределами такого резюме: завершённые эффекты, одобрения, ссылки на источники и точные пользовательские ограничения. Чекпоинт восстанавливает выполнение; компактизация сокращает контекст модели; долгосрочная память выбирает знания для другого разговора. Тестируйте эти три поведения отдельно. Принудительно запустите компактизацию в середине теста и проверьте, соблюдает ли следующее действие более раннее ограничение. Не используйте сжатую расшифровку как единственную запись того, что было одобрено.

Краткосрочная память агента: checkpoint store

LangGraph сохраняет состояние графа на границах super-step — одного узла или группы узлов, выполнявшихся параллельно. При значении durability="async" по умолчанию следующий шаг может выполняться, пока запись завершается; durability="sync" ожидает завершения сохранения перед продолжением, добавляя латентность записи. Восстановление после сбоя использует последний сохранённый чекпоинт, который не обязательно соответствует самому недавно завершённому шагу. Это основа для pause/resume, отладки с перемоткой во времени и HITL-workflow.

Чекпоинт содержит состояние графа, необходимое для продолжения: AgentState из части 1 — сообщения, идентичность, профиль пользователя, шаги плана, данные исследования и режим выполнения. После HITL-прерывания или перезапуска процесса LangGraph восстанавливает последнее сохранённое состояние и использует метаданные планирования, чтобы выбрать следующий узел. Выполнение продолжается на границе завершённого узла, а не с произвольной строки Python. Сохранённые сведения включают ID и временную метку чекпоинта, версию каждого канала (так LangGraph называет ключ состояния), а также версии каналов, которые уже видел каждый узел. Номер шага — это метаданные чекпоинта. Чекпоинт также отличается от append-only event log или trace; в части 5 эти runtime observability-поверхности разделены явно.

Как работает checkpointing в LangGraph

Интерфейс LangGraph BaseCheckpointSaver прост: put() записывает чекпоинт, get_tuple() читает последний чекпоинт для thread, а list() возвращает историю. Каждый чекпоинт идентифицируется через (thread_id, checkpoint_ns, checkpoint_id), где thread_id определяет разговор, checkpoint_ns отвечает за namespace подграфа, а checkpoint_id является уникальной версией.

Главное решение — какой бэкенд использовать за этим интерфейсом. PostgreSQL и Redis — два распространённых варианта для продакшена.

PostgreSQL против Redis

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

PostgreSQL: надёжный вариант по умолчанию

PostgreSQL — более безопасный вариант по умолчанию для большинства команд. Чекпоинты переживают сбои, вы получаете полную семантику транзакций, а история чекпоинтов упрощает отладку с перемоткой во времени.

Упрощённая версия настройки чекпоинтов из memory/hot.py. Если злоумышленник может записывать чекпоинты, установите LANGGRAPH_STRICT_MSGPACK=true или настройте allowed_msgpack_modules. Это ограничивает десериализацию безопасными или явно объявленными типами; разрешительный вариант по умолчанию предупреждает о незарегистрированных типах, но всё равно разрешает их.

import asyncio
from contextlib import asynccontextmanager

from langchain_core.messages import HumanMessage
from langgraph.checkpoint.postgres.aio import AsyncPostgresSaver

@asynccontextmanager
async def postgres_checkpointer(connection_string: str):
    """Yield a PostgreSQL-backed checkpoint store.

    PostgreSQL gives us ACID guarantees — if a checkpoint write succeeds,
    the state is durable even if the process crashes immediately after.
    `from_conn_string` is itself an async context manager: it owns the
    connection and closes it on exit, so the graph has to run inside it.
    """
    async with AsyncPostgresSaver.from_conn_string(connection_string) as checkpointer:
        # Create the checkpoint tables if they don't exist.
        # This is idempotent — safe to call on every startup.
        await checkpointer.setup()
        yield checkpointer

async def main(authenticated_user_id: str) -> None:
    # The graph lives inside the context manager's scope.
    async with postgres_checkpointer(
        "postgresql://user:pass@localhost:5432/agent_memory"
    ) as checkpointer:
        graph = create_graph(checkpointer=checkpointer)

        # Every invoke/stream call now persists state automatically.
        config = {"configurable": {"thread_id": "user-123-session-1"}}
        result = await graph.ainvoke(
            {"user_id": authenticated_user_id,
             "messages": [HumanMessage(content="Analyze NVDA")]}, config
        )

        # After the server authenticates the approver and validates approval
        # of this exact draft, update the companion's approval field.
        await graph.aupdate_state(config, {"report_approved": True})
        # Continue the static interrupt_before pause; new input starts a new run.
        result = await graph.ainvoke(None, config)

# Local fixture identity. A server supplies this only after authentication.
asyncio.run(main(authenticated_user_id="user-123"))

user_id во входе графа поступает из аутентифицированного серверного контекста; thread_id только находит чекпоинты и не устанавливает identity или права доступа к thread. AsyncPostgresSaver использует пакет langgraph-checkpoint-postgres, который создаёт четыре таблицы: checkpoints (сериализованное состояние), checkpoint_blobs (большие бинарные данные), checkpoint_writes (ожидающие записи для восстановления после сбоя) и checkpoint_migrations (версия схемы). Конкурирующие записи разделяются первичным ключом (thread_id, checkpoint_ns, checkpoint_id) и upsert-операциями, а не блокировками: два воркера в одном thread не повредят данные друг друга, но и координироваться не будут.

Redis: когда боттлнеком становится латентность

Когда латентность чекпоинтов становится боттлнеком, Redis — один из вариантов для восстанавливаемого состояния. Перед выбором Redis вместо PostgreSQL измерьте размер сериализованного состояния, настройки персистентности и конкурентность.

Упрощённая версия настройки чекпоинтов из memory/hot.py:

import asyncio
from contextlib import asynccontextmanager

from langgraph.checkpoint.redis.aio import AsyncRedisSaver

@asynccontextmanager
async def redis_checkpointer(redis_url: str):
    """Yield a Redis-backed checkpoint store.

    Redis keeps checkpoints in memory for low-latency access.
    Durability depends on RDB snapshots, AOF fsync policy, and replication.
    AOF with appendfsync everysec can still lose about one second of writes
    after a crash; enabling AOF alone is not a no-loss guarantee.
    """
    async with AsyncRedisSaver.from_conn_string(redis_url) as checkpointer:
        # Initialize Redis data structures
        await checkpointer.asetup()
        yield checkpointer

async def main() -> None:
    # Same graph API, different backend.
    async with redis_checkpointer("redis://localhost:6379") as checkpointer:
        graph = create_graph(checkpointer=checkpointer)

asyncio.run(main())

AsyncRedisSaver из langgraph-checkpoint-redis сохраняет каждый чекпоинт как отдельный RedisJSON-документ под тем же ключом (thread_id, checkpoint_ns, checkpoint_id), что и Postgres saver. В редизайне v0.1.0 значения чекпоинтов были встроены, а получение по отдельным каналам заменено путём JSON.GET. Это изменение касается извлечения значений, а не каждой операции персистентности; измерения латентности поставщика зависят от его нагрузки. Redis 8.0+ включает RedisJSON и RediSearch по умолчанию — устанавливать дополнительные модули не нужно.

Выбирайте политику персистентности Redis и fsync исходя из допустимого окна потери данных. RDB может потерять записи после последнего снапшота; стандартная политика AOF appendfsync everysec обычно допускает потерю примерно одной секунды. always обменивает латентность записи на более надёжную персистентность, а no оставляет сброс данных операционной системе. Проверяйте восстановление с фактическими настройками диска и репликации.

Для деплоев с ограниченной памятью ShallowRedisSaver хранит только последний чекпоинт каждого thread — без истории, но с минимальным потреблением RAM. Используйте этот вариант, если вам нужны pause/resume, но не нужна отладка с перемоткой во времени.

Когда что использовать

Используйте PostgreSQL, если:

• Нужна полная история чекпоинтов для отладки с перемоткой во времени или воспроизводимого продолжения
• Надёжность обязательна (финансовые сервисы, здравоохранение)
• PostgreSQL уже есть в вашем стеке
• Агент выполняет долгие задачи, и потеря состояния означает часы повторных вычислений
• Нужен единый data store — PostgreSQL с pgvector может быть единым бэкендом для чекпоинтов, долгосрочной памяти и vector search

Используйте Redis, если:

• Латентность чекпоинтов — ваш боттлнек (чат в реальном времени, streaming UX)
• Вы создаёте голосовых ботов или streaming-сценарии, где доступ к чекпоинтам находится на измеряемом критическом пути по задержке
• Нужен горизонтальный скейлинг по множеству независимых thread. Если несколько агентов меняют общее состояние, назначьте владельца этого состояния и координируйте работу за пределами checkpoint saver.
• Сессии краткосрочные, а потеря чекпоинта допускает восстановление
• Вы хотите использовать semantic caching, чтобы сократить повторные вызовы LLM (Redis LangCache кэширует семантически похожие запросы и предотвращает повторные вызовы LLM)

Другие варианты: langgraph-checkpoint-sqlite подходит для локальной разработки и однопроцессных деплоев. Для AWS-native-стеков langgraph-checkpoint-aws предоставляет DynamoDBSaver с автоматическим выносом payload — документированный saver выгружает данные свыше порога 350 KB, если настроен S3 bucket. Этот порог является политикой реализации, а не лимитом DynamoDB в 400 KB для item. Serverless-цены и отсутствие инфраструктуры для управления делают такой вариант привлекательным для деплоев с переменной нагрузкой.

Долгосрочная память: воспоминания между сессиями

Горячая память обслуживает текущий разговор. Долгосрочная память относится к пользователю, который возвращается на следующей неделе: она хранит факты, предпочтения и историю взаимодействий, сохраняющиеся между thread.

LangGraph предоставляет интерфейс Store для памяти между thread через класс BaseStore. Каждый элемент памяти — это пара (namespace, key) с JSON-значением и необязательным векторным эмбеддингом. Namespace обычно кодирует пользователя или организацию: ("user", "user-123", "preferences").

Векторное хранение: семантическое извлечение с Qdrant

Когда агенту нужно вспомнить неструктурированные факты («Что пользователь говорил о сроках своих инвестиций?»), vector search обеспечивает семантическое извлечение. Вместо поиска по точному ключу агент запрашивает данные по смыслу.

Qdrant — специализированная векторная БД на Rust, которая отвечает за хранение эмбеддингов, индексацию (Hierarchical Navigable Small World, или HNSW) и поиск с фильтрами. Подробно HNSW и его компромиссы разобраны в моей статье о ранжировании поиска. Qdrant также предлагает MCP-сервер, который работает как слой семантической памяти — это полезно, если ваш агентный фреймворк поддерживает Model Context Protocol.

Следующий пример — независимый иллюстративный дизайн на Qdrant. Это не упрощённая версия текущего memory/long.py. Текущий проект хранит профили пользователей с точной фильтрацией по user_id и placeholder с нулевым вектором. Полноценная интеграция эмбеддингов остаётся задачей на будущее. Обработчик запроса должен аутентифицировать запрос и создать principal на основе проверенной identity; клиент никогда не передаёт его сам. Фильтр Qdrant определяет область retrieval, а не права доступа.

from qdrant_client import QdrantClient
from qdrant_client.models import (
    PointStruct, Distance, VectorParams, Filter, FieldCondition, MatchValue,
)
import hashlib
import json
from dataclasses import dataclass

@dataclass(frozen=True)
class AuthenticatedPrincipal:
    """Created by the server after authentication, never from request JSON."""
    user_id: str

class UserMemoryStore:
    """Long-term memory backed by Qdrant vector search.

    Stores user facts as embedded vectors for semantic retrieval.
    Each fact is a short natural-language statement about the user.
    """

    def __init__(self, qdrant_url: str, collection_name: str = "user_memory"):
        self.client = QdrantClient(url=qdrant_url)
        self.collection_name = collection_name
        self._ensure_collection()

    def _ensure_collection(self):
        """Create the collection if it doesn't exist."""
        collections = [c.name for c in self.client.get_collections().collections]
        if self.collection_name not in collections:
            self.client.create_collection(
                collection_name=self.collection_name,
                vectors_config=VectorParams(
                    size=1536,  # text-embedding-3-small dimensions
                    distance=Distance.COSINE,
                ),
            )

    def store_fact(
        self, principal: AuthenticatedPrincipal, fact: str, embedding: list[float]
    ):
        """Store a user fact with its embedding."""
        identity = json.dumps([principal.user_id, fact], ensure_ascii=False).encode()
        point_id = hashlib.sha256(identity).hexdigest()[:32]
        self.client.upsert(
            collection_name=self.collection_name,
            points=[PointStruct(
                id=point_id,
                vector=embedding,
                payload={"user_id": principal.user_id, "fact": fact},
            )],
        )

    def recall(
        self,
        principal: AuthenticatedPrincipal,
        query_embedding: list[float],
        top_k: int = 5,
    ):
        """Retrieve the most relevant facts for a user given a query."""
        results = self.client.query_points(
            collection_name=self.collection_name,
            query=query_embedding,
            query_filter=Filter(
                must=[FieldCondition(
                    key="user_id", match=MatchValue(value=principal.user_id)
                )]
            ),
            limit=top_k,
        )
        return [hit.payload["fact"] for hit in results.points]

ID точки хеширует JSON-массив из ID пользователя и факта, поэтому разделители внутри любого из значений не смогут объединить две identity. Например, пользователь a:b с фактом c должен отличаться от пользователя a с фактом b:c. Эти 32 шестнадцатеричных символа соответствуют представлению UUID для ID точки в Qdrant.

Поток состоит из трёх шагов. В этом иллюстративном дизайне LLM извлекает ключевые факты из взаимодействия («у пользователя высокая толерантность к риску», «пользователь интересуется акциями полупроводниковых компаний»). Эти факты превращаются в эмбеддинги и сохраняются в Qdrant. В начале следующего разговора сервер передаёт аутентифицированный principal, а агент запрашивает Qdrant с новым сообщением пользователя, чтобы вспомнить релевантный контекст. Текущий Market Analyst Agent пока не реализует этот поток семантического извлечения и эмбеддингов.

Оценка retrieval: за пределами cosine similarity

Сырая cosine similarity — лишь отправная точка, но production-системам памяти требуется более богатый retrieval. В статье Generative Agents (Park et al., 2023) представлена функция оценки, объединяющая три сигнала:

• Давность: rule-based затухание, при котором более свежие воспоминания получают более высокий балл. Экспоненциальная decay-функция позволяет факту от вчера опередить эквивалентный факт шестимесячной давности.
• Важность: значимость, оценённая LLM по шкале от 1 до 10. «Стоимость портфеля пользователя упала на 40%» получает больший балл, чем «пользователь поздоровался».
• Релевантность: cosine similarity между эмбеддингом запроса и сохранённым фактом.

В статье все три сигнала нормализуются к сопоставимым шкалам перед объединением. Делайте то же перед настройкой весов: иначе необработанная оценка важности 1–10 будет доминировать над сигналом 0–1. Итоговая оценка retrieval — это взвешенная сумма: score = alpha * recency + beta * importance + gamma * relevance. Это не позволяет свежим и важным фактам затеряться под устаревшими, но семантически похожими. Для прототипа финансового анализа я бы начал со значений alpha = 0.3 для давности, beta = 0.2 для важности и gamma = 0.5 для релевантности, поскольку именно текущий запрос обычно определяет, какой из допустимых фактов должен попасть в контекст. В статье Generative Agents использовались равные веса; эти значения — предложенная отправная точка, а не измеренное улучшение. Настройте их по отложенным проверкам recall и качества задачи, прежде чем полагаться на них.

Альтернативы vector search

Vector search мощен, но не всегда является правильным инструментом. Вот когда стоит использовать альтернативы:

Key-value-хранилища хорошо подходят для структурированных данных. Если ваша долгосрочная память — это профиль пользователя: толерантность к риску, инвестиционный горизонт, предпочитаемые секторы, — Redis hash или колонка PostgreSQL JSONB будут проще и быстрее, чем построение и запрос векторов. Используйте vector search, когда память неструктурирована, а формулировка запроса меняется.

Встроенный Store LangGraph предоставляет key-value-интерфейс с namespace и опциональным vector search. API BaseStore прост: put(), get(), search() и delete() с иерархической областью namespace. Доступны три реализации:

• InMemoryStore — для разработки и тестирования (данные теряются при завершении процесса)
• PostgresStore — production-хранилище с персистентностью и полноценными SQL-запросами
• AsyncRedisStore — память между thread с vector search, поддержкой TTL и фильтрацией по метаданным

Конфигурация index включает vector search по сохранённым элементам с настраиваемой embedding model. Для многих сценариев этого встроенного store достаточно, и отдельная векторная БД не нужна.

import asyncio
from langgraph.store.memory import InMemoryStore

# Create a store with vector search enabled
store = InMemoryStore(
    index={
        "dims": 1536,
        "embed": my_embedding_function,  # e.g., OpenAI text-embedding-3-small
    }
)

async def main() -> None:
    # Store a user preference (namespace scopes to user).
    await store.aput(
        namespace=("user", "user-123", "preferences"),
        key="risk-profile",
        value={"risk_tolerance": "high", "horizon": "long-term"},
    )

    # Semantic search across the user's memories.
    # The namespace prefix is positional here — `search`/`asearch` declare it
    # as positional-only `namespace_prefix`, unlike `aput`.
    results = await store.asearch(
        ("user", "user-123"),
        query="What is their investment style?",
        limit=5,
    )

asyncio.run(main())

Выбор стратегии долгосрочной памяти

Начните с key-value, если память структурирована и хорошо определена (профили пользователей, настройки, именованные сущности). Добавляйте vector search, когда нужен семантический retrieval по неструктурированным фактам или формулировка запроса непредсказуемо меняется.

Knowledge graph оправдывает себя, когда важны отношения между сущностями, например: «О каких компаниях спрашивал пользователь, которые являются конкурентами NVDA?» Наиболее интересный недавний проект в этой области — Graphiti от Zep, который строит темпорально-ориентированный граф знаний, отслеживающий, когда факты были истинными, а не только что было истинным. Его временные связи могут сохранять интервалы валидности и значения, вытесненные новыми; однако логика извлечения и обновления по-прежнему определяет, является ли факт актуальным. В статье Zep сообщается о 94,8% точности DMR для оценённой системы Zep на базе Graphiti и GPT-4 Turbo против 94,4% для полного контекста. DMR использует разговоры из 60 сообщений и ограниченную задачу извлечения фактов. Такая небольшая разница не доказывает общего преимущества темпоральных графов.

Проблема — в эксплуатации. Запуск графовой БД нетривиален, а для большинства агентных приложений vector search с фильтрацией по метаданным покрывает те же задачи при меньшей инфраструктуре.

Managed memory-фреймворки, такие как Mem0 и Letta (ранее MemGPT), берут на себя пайплайн извлечения, консолидации и retrieval. Подход Mem0 примечателен: LLM извлекает кандидатов в память, decision engine сравнивает каждый новый факт с существующими записями в vector store, а resolver решает — добавить, обновить, удалить факт или ничего не делать. Это поддерживает память согласованной и избавляет от дубликатов. Letta использует подход операционных систем: агенты управляют собственным контекстным окном с помощью memory management tools, автономно перемещая данные между «core memory» (в контексте) и «archival memory» (вне контекста). Оба фреймворка стоит оценить, если важен быстрый time-to-production и не требуется полный контроль над memory pipeline.

Документная память: картотека агента

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

Это документная память: агент читает и записывает структурированные файлы (Markdown, JSON, YAML) в известную директорию. Никаких эмбеддингов, базы данных или инфраструктуры. Просто файлы на диске, которые и агент, и разработчик могут cat, grep, git diff и редактировать вручную.

В одной vendor-run оценке Letta сообщила о 74,0% точности на LoCoMo — бенчмарке вопросно-ответных задач по длинным разговорам — для агента GPT-4o mini с подключёнными файлами, автоматическими эмбеддингами, семантическим search_files и обязательными правилами использования search tools. Лучшая graph-вариация Mem0 набрала 68,5%. Это результат одного вендора, модели, бенчмарка и харнесса. Он показывает, что интерфейс, работающий с файлами, может хорошо работать в такой конфигурации; он не доказывает, что сырого Markdown или keyword search достаточно. Операционное преимущество отдельно: разработчики могут напрямую читать, редактировать и сравнивать diff сохранённых знаний.

Более длинные контекстные окна также делают чтение целых файлов практичным для некоторых проектных документов. Чанкинг и retrieval по-прежнему подходят для больших корпусов, но короткий файл с соглашениями или handoff часто можно загружать целиком. Выбор зависит от размера документа, точности retrieval, бюджета контекста и того, как часто людям нужно просматривать или редактировать память.

Почему файлы?

Для долгоживущего агентного проекта используйте директорию хорошо организованных заметок, если людям нужен доступный для проверки журнал. Представьте coding agent, который работает над одним проектом несколько недель:

• Он узнаёт, что проект использует Pydantic v2, а не v1
• Он выясняет, что тесты нужно запускать с помощью pytest -x --tb=short
• Он накапливает знания об архитектуре кодовой базы
• Он узнаёт предпочтения разработчика («всегда используй pathlib, никогда os.path»)

Эти факты могут храниться в vector- или key-value-системе. Но здесь файлы лучше использовать по умолчанию, поскольку разработчику нужно читать, редактировать, просматривать и версионировать связанные заметки. Добавляйте keyword или semantic search только тогда, когда этого требуют размер корпуса документов и паттерн запросов. Если агент выучил что-то неправильно, откройте файл и исправьте это.

Claude Code, Cursor и Devin Desktop используют варианты этого паттерна. В примерах ниже показано, как каждый из них хранит и загружает свои файлы.

Реализация file memory store

Реализация намеренно проста. Агент получает четыре операции: записать документ, прочитать документ, перечислить доступные документы и выполнить поиск по документам по ключевому слову.

Ниже приведён независимый иллюстративный file store для сырого Markdown. Это не упрощённая версия текущего memory/document.py. Текущий проект использует DocumentMemory, которому нужны namespace и key; он записывает JSON-конверт, содержащий content, metadata и created_at. В этом примере используется другой дизайн, чтобы показать компромиссы человекочитаемых Markdown-файлов:

from pathlib import Path
import json

class FileMemory:
    """Document memory backed by the local filesystem.

    Stores agent knowledge as human-readable files organized by topic.
    No embeddings, no database — just files that both the agent and
    the developer can read, edit, and version-control.
    """

    def __init__(self, base_dir: str | Path):
        self.base_dir = Path(base_dir).resolve()
        self.base_dir.mkdir(parents=True, exist_ok=True)

    def _resolve_path(self, path: str) -> Path:
        """Return a path inside base_dir, rejecting escapes and symlinks."""
        requested = Path(path)
        if requested.is_absolute() or ".." in requested.parts:
            raise ValueError("path must be relative to base_dir without traversal")
        resolved = (self.base_dir / requested).resolve()
        try:
            resolved.relative_to(self.base_dir)
        except ValueError as error:
            raise ValueError("path must stay inside base_dir") from error
        return resolved

    def write_doc(self, path: str, content: str, metadata: dict | None = None):
        """Write or overwrite a document at the given path.

        Paths are relative to base_dir. Directories are created automatically.
        Metadata (if provided) is stored as a JSON sidecar file.
        """
        full_path = self._resolve_path(path)
        full_path.parent.mkdir(parents=True, exist_ok=True)
        full_path.write_text(content, encoding="utf-8")

        if metadata:
            meta_path = self._resolve_path(
                str(full_path.relative_to(self.base_dir).with_suffix(full_path.suffix + ".meta"))
            )
            meta_path.write_text(json.dumps(metadata, indent=2), encoding="utf-8")

    def read_doc(self, path: str) -> str | None:
        """Read a document by path. Returns None if not found."""
        full_path = self._resolve_path(path)
        if full_path.exists():
            return full_path.read_text(encoding="utf-8")
        return None

    def list_docs(self, pattern: str = "**/*") -> list[str]:
        """List documents matching a glob pattern."""
        self._resolve_path(pattern)
        return [
            str(self._resolve_path(str(p.relative_to(self.base_dir))).relative_to(self.base_dir))
            for p in self.base_dir.glob(pattern)
            if self._resolve_path(str(p.relative_to(self.base_dir))).is_file()
            and not p.name.endswith(".meta")
        ]

    def search_docs(self, query: str, pattern: str = "**/*.md") -> list[dict]:
        """Search documents by keyword. Returns matching files with context.

        This is intentionally simple — grep-style keyword search.
        For semantic search, use a vector store instead.

        # ponytail: linear scan of file bytes; add an index when measured
        # latency, concurrency, or retrieval quality requires it.
        """
        self._resolve_path(pattern)
        results = []
        for path in self.base_dir.glob(pattern):
            path = self._resolve_path(str(path.relative_to(self.base_dir)))
            if not path.is_file() or path.name.endswith(".meta"):
                continue
            content = path.read_text(encoding="utf-8")
            if query.lower() in content.lower():
                # Return the paragraph containing the match for context
                for paragraph in content.split("\n\n"):
                    if query.lower() in paragraph.lower():
                        results.append({
                            "path": str(path.relative_to(self.base_dir)),
                            "match": paragraph.strip()[:500],
                        })
        return results

Вспомогательная функция для путей намеренно используется совместно в операциях чтения, записи и результатах glob: относительные пути всё ещё могут выйти за пределы директории через .. или существующую symbolic link. Этот иллюстративный класс предназначен для доверенной однопользовательской или контролируемой файловой системы. Он проверяет resolved path перед использованием; на враждебной multi-tenant-границе используйте операции без следования по ссылкам, относительные к файловому дескриптору, чтобы изменение файловой системы не могло обойти эту проверку гонкой. После копирования класса запустите следующую небольшую regression-проверку:

from tempfile import TemporaryDirectory

with TemporaryDirectory() as root:
    memory = FileMemory(root)
    memory.write_doc("notes/ok.md", "safe memory")
    assert memory.read_doc("notes/ok.md") == "safe memory"
    assert memory.list_docs() == ["notes/ok.md"]
    assert memory.search_docs("safe")[0]["path"] == "notes/ok.md"

    (Path(root) / "escape").symlink_to(Path(root).parent, target_is_directory=True)
    for operation in (
        lambda: memory.write_doc("../escape.md", "nope"),
        lambda: memory.read_doc("/tmp/escape.md"),
        lambda: memory.read_doc("escape/outside.md"),
        lambda: memory.list_docs("../**/*"),
        lambda: memory.search_docs("safe", "../**/*.md"),
    ):
        try:
            operation()
        except ValueError:
            pass
        else:
            raise AssertionError("FileMemory accepted an escaped path")

Структура директорий

Большая часть ценности документной памяти определяется устройством директории. Вот структуру, которую я использовал бы для исследовательского агента. Market Analyst Agent использует namespace под memory/documents/, но его текущий DocumentMemory записывает каждую запись как JSON-конверт со строкой content, а не как сырой Markdown. Приведённая ниже структура raw Markdown относится к независимому иллюстративному дизайну FileMemory:

.agent-memory/
    README.md                  # What this directory is, for human readers
    PROGRESS.md                # Handoff for the next session: what is done, what is next
    user-profiles/
        user-123.md            # Preferences, history, risk profile
        user-456.md
    research/
        NVDA-2026-02.md        # Research notes from recent analysis
        TSLA-2026-01.md
    conventions/
        analysis-format.md     # How to structure analysis reports
        data-sources.md        # Preferred data sources and API patterns
    learnings/
        common-errors.md       # Mistakes the agent has learned to avoid
        tool-patterns.md       # Effective tool call sequences

В иллюстративном дизайне FileMemory каждый документ является Markdown-файлом, а назначение каждого документа очевидно из его пути. Вы можете git diff всю директорию памяти, чтобы увидеть, чему агент научился за сессию, git revert ошибочное знание или скопировать директорию в другой проект. JSON-конверты текущего проекта сохраняют структуру namespace и key, но не дают такого же опыта работы с diff для сырого Markdown.

Когда использовать document memory, vector или key-value

Три бэкенда памяти обслуживают разные паттерны доступа:

Используйте document memory, если:

• Агент накапливает знания о проекте на протяжении нескольких сессий
• Разработчикам нужно просматривать, редактировать или переопределять то, что агент «знает»
• Знания структурированы как документы (заметки, резюме, соглашения), а не как отдельные факты
• Нужна версионность памяти агента на базе git
• Нулевая инфраструктура — жёсткое требование

Используйте vector stores, если:

• Нужен нечёткий семантический retrieval («найди воспоминания, связанные с X»)
• Формулировка запроса непредсказуемо меняется
• Есть от тысяч до миллионов отдельных фактов

Используйте key-value stores, если:

• Нужны точные и быстрые запросы структурированных данных (профили пользователей, настройки)
• Схема данных хорошо определена

Три хранилища могут сосуществовать, но это не обязательное требование. Текущий Market Analyst Agent использует PostgreSQL checkpoints для горячей памяти, Qdrant для точного хранения профилей пользователей с placeholder-векторами и namespaced JSON-конвертное document store. Варианты семантического retrieval и raw Markdown в этой статье — иллюстративные расширения.

Примеры из реального мира

Этот паттерн уже широко используется в AI-помощниках для программирования:

• Claude Code читает файлы CLAUDE.md из корня проекта и родительских директорий, а для знаний между сессиями поддерживает memory-файл проекта в ~/.claude/projects/. Система памяти состоит из обычных Markdown-файлов, а файлы уровня проекта можно коммитить вместе с кодом.
• Cursor загружает правила проекта из .cursor/rules в виде файлов .mdc — соглашений кодирования, предпочтений фреймворков и архитектурных решений; frontmatter определяет, когда применяется каждое правило.
• Legacy Cascade agent в Devin Desktop читает правила из .devin/rules/; .windsurf/rules/ и расположенный в корне .windsurfrules сохраняются как legacy fallback. Cascade хранит автоматически созданные воспоминания локально для каждого workspace и извлекает их позднее; используемый по умолчанию Devin Local agent для новых вкладок воспоминания не сохраняет.
• Инструмент памяти Anthropic для Claude API — это client-side tool, которым модель управляет через файловые операции — view, create, str_replace, insert, delete и rename — над директорией /memories. Ваше приложение реализует каждую команду, поэтому само решает, где фактически хранятся файлы (локальный диск, S3, база данных).

Файловые варианты хранят знания агента как человекочитаемый текст с явными операциями чтения и записи, и ни одному из них не нужен embedding pipeline. Агент решает, что записать; если текст находится в локальной директории под управлением Git, разработчик может увидеть и отредактировать его в git diff. Если обработчик memory tool Anthropic сопоставляет /memories с S3 или базой данных, возможности просмотра и версионирования зависят от этой реализации.

Декларативные заметки и исполняемые навыки

Знания на основе файлов встречаются и за пределами coding assistants, но формат хранения не говорит, как именно они используются. Voyager хранит повторно используемые программы на JavaScript: агент может выполнять этот код. Основной метод Agent Workflow Memory вместо этого добавляет выведенные web-workflow в контекст промпта как инструкции для последующих действий. Его отдельный эксперимент AWM_AS предоставляет workflow в качестве вызываемых действий. Процедура, описанная в контексте, и исполняемая процедура требуют разных проверок.

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

Та же граница отделяет память от навыков и инструментов. Стандарт Agent Skills использует файлы SKILL.md, чтобы объяснять агенту, как выполнять класс работ; память фиксирует факты, выученные из проекта или предыдущего run. В части 3 проводится соседняя граница между навыком и инструментом. Выбирайте file store для просматриваемого выученного контекста; skill или tool — только когда нужна повторно используемая процедура или capability.

Масштабирование document memory для production

Файловая реализация выше подходит для контролируемой однопользовательской файловой системы. Несколько tenant и конкурентные записи требуют явной модели доступа и координации записи независимо от количества документов.

В приведённом raw store нет координации конкурентных записей, tenant-модели или поискового индекса. Перед заменой оцените эти требования. База данных или object store могут предоставить другие контракты конкурентности и доступа; файлы также можно индексировать.

Три распространённых подхода:

Подход A: гибрид с тонким слоем базы данных

Оставьте файлы для authoring (разработчики редактируют Markdown локально), но в runtime обслуживайте данные из базы. При деплое синхронизируйте файлы со строками PostgreSQL. Агент читает из базы, а не с диска. Это даёт:

• Удобство для разработчиков (редактировать Markdown и коммитить в git)
• Производительность запросов в production (индексированные чтения из базы)
• Чёткое разделение authoring и serving

Подход B: object storage + sidecar с vector index

Храните документы в S3/GCS как объекты, а коллекция Qdrant пусть индексирует их эмбеддинги. Агент запрашивает Qdrant для получения ID релевантных документов, затем получает содержимое из object storage. Это масштабируется горизонтально и поддерживает semantic search, но добавляет сложность: нужно управлять двумя системами, поддерживать embedding pipeline и eventual consistency между store и index.

Подход C: структурированное document store на PostgreSQL (рекомендуется)

Храните документы в строках PostgreSQL JSONB с full-text search (GIN index) и опциональными векторными эмбеддингами (pgvector). Это даёт hybrid search (keyword + semantic), ACID-транзакции и одну операционную систему.

Набросок подхода C. Объединённая оценка выполняет точный scoring по ограниченному tenant-корпусу; approximate nearest-neighbor (ANN) index не используется. Для этого пути pgvector требует прямой сортировки по возрастающему расстоянию с LIMIT. Для большего корпуса отдельно извлекайте ограниченное число keyword- и vector-кандидатов, затем объединяйте их ранги. Это RLS-паттерн, а не готовый application code: database role должна быть доступна только доверенному application server. Сервер аутентифицирует запрос и создаёт principal; он не принимает tenant ID от вызывающей стороны. PostgreSQL RLS затем делает эту область enforceable, даже если в будущем запрос пропустит tenant predicate.

from typing import Optional
from dataclasses import dataclass
import asyncpg

@dataclass(frozen=True)
class AuthenticatedPrincipal:
    """The verified identity returned by the application's authentication layer."""
    tenant_id: str

class ProductionDocumentMemory:
    """Illustrative PostgreSQL document memory with hybrid search and RLS.

    Apply this schema and policy as the table owner during deployment:

        CREATE TABLE documents (
            id SERIAL PRIMARY KEY,
            tenant_id TEXT NOT NULL,
            path TEXT NOT NULL,
            content TEXT NOT NULL,
            metadata JSONB,
            embedding vector(1536),  -- pgvector extension
            ts_vector tsvector GENERATED ALWAYS AS (to_tsvector('english', content)) STORED,
            created_at TIMESTAMPTZ DEFAULT NOW(),
            UNIQUE(tenant_id, path)
        );
        CREATE INDEX ON documents USING GIN(ts_vector);

        ALTER TABLE documents ENABLE ROW LEVEL SECURITY;
        ALTER TABLE documents FORCE ROW LEVEL SECURITY;
        CREATE POLICY tenant_documents ON documents
            USING (tenant_id = current_setting('app.tenant_id', true))
            WITH CHECK (tenant_id = current_setting('app.tenant_id', true));

    `FORCE` also subjects the table owner to the policy. Superusers and roles with
    `BYPASSRLS` still bypass it, so neither belongs in the application's pool.
    """

    def __init__(self, pool: asyncpg.Pool):
        self.pool = pool

    async def write(
        self,
        principal: AuthenticatedPrincipal,
        path: str,
        content: str,
        metadata: Optional[dict] = None,
        embedding: Optional[list[float]] = None,
    ):
        """Write or update a document.

        Sketch: on a real pool you must register codecs first, or asyncpg
        raises DataError — `set_type_codec` for the JSONB metadata column
        and pgvector's `register_vector` for the embedding.
        """
        async with self.pool.acquire() as conn:
            async with conn.transaction():
                # true keeps this trusted context to this transaction only.
                await conn.execute(
                    "SELECT set_config('app.tenant_id', $1, true)", principal.tenant_id
                )
                await conn.execute(
                    """
                    INSERT INTO documents (tenant_id, path, content, metadata, embedding)
                    VALUES ($1, $2, $3, $4, $5)
                    ON CONFLICT (tenant_id, path) DO UPDATE
                    SET content = EXCLUDED.content,
                        metadata = EXCLUDED.metadata,
                        embedding = EXCLUDED.embedding
                    """,
                    principal.tenant_id, path, content, metadata, embedding,
                )

    async def search(
        self,
        principal: AuthenticatedPrincipal,
        query: str,
        embedding: Optional[list[float]] = None,
        limit: int = 5,
    ) -> list[dict]:
        """Hybrid search: full-text + optional vector similarity."""
        async with self.pool.acquire() as conn:
            async with conn.transaction():
                await conn.execute(
                    "SELECT set_config('app.tenant_id', $1, true)", principal.tenant_id
                )
                if embedding:
                    # Hybrid scoring: 0.6 * text relevance + 0.4 * vector similarity
                    rows = await conn.fetch(
                        """
                        SELECT path, content, metadata,
                               (0.6 * ts_rank(ts_vector, plainto_tsquery('english', $1)) +
                                0.4 * COALESCE(1 - (embedding <=> $2), 0)) AS score
                        FROM documents
                        WHERE ts_vector @@ plainto_tsquery('english', $1)
                           OR (embedding <=> $2) < 0.5
                        ORDER BY score DESC
                        LIMIT $3
                        """,
                        query, embedding, limit,
                    )
                else:
                    # Full-text search only
                    rows = await conn.fetch(
                        """
                        SELECT path, content, metadata,
                               ts_rank(ts_vector, plainto_tsquery('english', $1)) AS score
                        FROM documents
                        WHERE ts_vector @@ plainto_tsquery('english', $1)
                        ORDER BY score DESC
                        LIMIT $2
                        """,
                        query, limit,
                    )
                return [dict(row) for row in rows]

set_config(..., true) имеет область действия транзакции, поэтому pooled connection не может сохранить контекст одного tenant для следующего запроса. OR в первой ветви делает поиск гибридным. COALESCE сохраняет в результате документ с совпадением по ключевому слову, но без эмбеддинга, используя его text score; vector similarity он не добавляет. Если оставить только предикат @@, документ, который соответствует смыслу, но не содержит общих с запросом ключевых слов, будет отфильтрован ещё до расчёта оценки — это keyword retrieval с semantic reranking, а не hybrid retrieval. Веса 0.6/0.4 приведены для иллюстрации: text rank и cosine similarity имеют разные шкалы. Нормализуйте их по результатам оценки retrieval или используйте rank fusion, прежде чем трактовать эти веса как относительную важность. Порог расстояния — это настройка: ужесточите его, если vector arm переполняет результаты, или ослабьте, если семантические совпадения не появляются.

Следующая regression-проверка — поведение, которое нужно протестировать на реальной базе после миграций. При tenant-a чтение tenant-b не возвращает строк, а прямая межtenant-вставка завершается ошибкой RLS:

BEGIN;
SELECT set_config('app.tenant_id', 'tenant-a', true);
SELECT path FROM documents WHERE tenant_id = 'tenant-b'; -- 0 rows
INSERT INTO documents (tenant_id, path, content)
VALUES ('tenant-b', 'leak.md', 'must fail'); -- ERROR: row-level security policy
ROLLBACK;

Что вы получаете:

• Hybrid search: сопоставление ключевых слов (GIN index) + семантическое сходство (pgvector), оцениваемые вместе
• Multi-tenancy: identity, полученная сервером, плюс RLS, enforced базой данных
• ACID-гарантии: транзакции на primary коммитятся атомарно; чтения с replica могут отставать
• Единая операционная система: отдельной векторной БД для управления не требуется
• Масштабирование: read replicas могут обслуживать запросы, допускающие устаревшие данные. Нативное партиционирование помогает с pruning и обслуживанием, но не распределяет записи между серверами; для этого нужен явный sharding design. Маршрутизируйте read-after-write пути на primary или измерьте подходящую synchronous policy

Файлы отлично подходят для workflow одного разработчика. Для multi-tenant production структурированное document store на PostgreSQL обычно даёт лучший баланс простоты, производительности и операционной зрелости.

Собираем всё вместе: полная архитектура

Вот как все три уровня памяти могут работать вместе в архитектуре, вдохновлённой Market Analyst Agent. На диаграмме показан иллюстративный поток от запроса пользователя до ответа со всеми активными слоями памяти.

В архитектуре есть три пути памяти:

1. Горячий путь (checkpoint store): LangGraph записывает восстанавливаемое состояние графа в checkpoint store на каждой границе super-step. Когда граф достигает узла interrupt_before (например, узла publish из части 1), выполнение приостанавливается. Пользователь может закрыть приложение, а после возвращения граф продолжит работу из чекпоинта. Runtime event logs и traces — отдельные production-задачи.

2. Холодный путь (long-term store): После выбора маршрута роутером планировщик запрашивает в long-term store релевантный контекст пользователя. Планировщик не может персонализировать план, пока это чтение не завершится. Vector-backed lookup может включать embedding запроса и извлечение из индекса; key-value lookup — нет. Новые факты можно извлечь и сохранить после завершения разговора, поэтому эта запись не задерживает reasoning loop.

3. Документный путь (file store): Во время планирования агент читает соглашения проекта и заметки исследований, необходимые для запроса. Во время выполнения он записывает на диск резюме исследований и выученные паттерны. Эти чтения влияют на текущую задачу, поэтому размер файлов, скорость файловой системы и состояние кэша влияют на время ответа. Кэшируйте только при наличии чётких правил инвалидирования и изоляции tenant. Записи можно выполнять позднее.

Подключение в LangGraph простое: checkpoint store и long-term store передаются при компиляции графа, а document store внедряется как зависимость. Локальный набросок ниже компилирует уже настроенный builder StateGraph, включая узлы, принимающие store. Это расширяет wiring графа; вспомогательные функции create_graph из части 1 и companion-проекта не принимают аргумент store. Используется InMemoryStore, чтобы сохранить компактность фрагмента; reference Docker topology использует Qdrant для той же роли semantic recall.

import asyncio
from langgraph.store.memory import InMemoryStore

# Cold memory: local sketch with vector search
# (The reference Docker topology uses Qdrant for persistent recall.)
memory_store = InMemoryStore(
    index={"dims": 1536, "embed": embedding_function}
)

# Document memory: illustrative file-based store for project knowledge
# FileMemory is the illustrative class defined above, not the project's current
# DocumentMemory implementation.
doc_memory = FileMemory(base_dir=".agent-memory")

async def main() -> None:
    # Hot memory: PostgreSQL for durable checkpoints. postgres_checkpointer() is
    # the async context manager defined earlier, so the graph runs inside it.
    async with postgres_checkpointer(pg_connection_string) as checkpointer:
        # builder is the configured StateGraph for this extended design.
        # The Part 1/companion create_graph helper does not accept store.
        graph = builder.compile(
            checkpointer=checkpointer,
            store=memory_store,
        )
        # ... run the graph here, while the connection is still open

asyncio.run(main())

# The store is accessible inside any node via the store parameter
def planner_node(state: AgentState, *, store: BaseStore) -> dict:
    """Plan with user context from long-term memory."""

    # Recall relevant user facts from vector store.
    # Namespace prefix is positional — see the store example above.
    user_memories = store.search(
        ("user", state.user_id),
        query=state.messages[-1].content,
        limit=5,
    )

    # Load project conventions from document memory
    conventions = doc_memory.read_doc("conventions/analysis-format.md")

    # Inject both into planning context
    # Each stored value is a dict; render whatever keys it carries
    memory_context = "\n".join(str(m.value) for m in user_memories)
    # ... rest of planning logic with personalized context and conventions

Полный поток

В расширенном дизайне выше запрос вернувшегося пользователя «Проанализируй TSLA» может пройти следующий поток. Семантический recall и асинхронное извлечение фактов — предложенные расширения, а не текущее поведение companion-проекта:

1. Загрузка document memory: Когда запускается планировщик, он читает из document store соглашения проекта: предпочтения по формату анализа, предпочитаемые источники данных и паттерны использования инструментов. Они задают базовое поведение для этого плана.

2. Роутер: Роутер классифицирует запрос как DEEP_RESEARCH. В этом примере routing использует сам запрос, а не долгосрочные предпочтения.

3. Cold memory recall + планировщик: Планировщик запрашивает long-term store с сообщением пользователя. Он извлекает: «У пользователя высокая толерантность к риску», «Пользователь предпочитает подробный анализ конкурентов», «Ранее пользователь исследовал NVDA и AMD». Затем он создаёт персонализированный под эти предпочтения пятишаговый исследовательский план. В него входит шаг анализа конкурентов, поскольку история пользователя показывает, что ему это нужно. План соответствует формату из документа с соглашениями.

4. Цикл executor (hot memory): Каждый шаг выполняется по паттерну ReAct из части 1 — думать, действовать, наблюдать; процесс повторяется до завершения шага. LangGraph сохраняет чекпоинт каждого super-step (роутер, планировщик и каждый последовательный шаг executor здесь). Восстановление начинается с последнего сохранённого чекпоинта. Если запись шага 3 завершилась, граф может продолжить с шага 4; при асинхронной персистентности сбой может потребовать повторить уже завершённый шаг.

5. HITL-прерывание: Reporter записывает черновик. Отдельная model session, не имеющая истории run, читает черновик и фиксирует assessment. Затем граф достигает publish, где interrupt_before приостанавливает его независимо от этого assessment. Чекпоинт содержит и черновик, и assessment, поэтому человек просматривает их перед решением о публикации. Через несколько часов граф загружает чекпоинт и следует этому решению.

6. Обновления памяти: После завершения разговора асинхронный процесс извлекает новые факты о пользователе («теперь пользователь отслеживает TSLA», «пользователь одобрил формат отчёта») и сохраняет их в долгосрочном vector store. Агент также записывает резюме исследования в document store (research/TSLA-2026-02) для будущего использования.

Трёхуровневый паттерн чётко разделяет обязанности. Checkpoint store отвечает за надёжность и продолжение; это инфраструктура. Long-term store отвечает за персонализацию; это продуктовая логика. Document store хранит накопленные знания о проекте; это блокнот агента.

Компромиссы и соображения

Память приносит пользу, но добавляет стоимость и сложность:

• Стоимость эмбеддингов: Для каждого факта, сохранённого в векторной БД, нужно сгенерировать эмбеддинг. Hosted embedding provider добавляет API-вызов, специфичную для провайдера стоимость и сетевую латентность; на сентябрь 2026 года OpenAI указывает text-embedding-3-small по цене $0.02 за миллион токенов. Стоимость hosted-модели на один факт незначительна, но она накапливается при тысячах пользователей и сессий. Используйте batch-вызовы к hosted-провайдеру и кэшируйте результаты. Во время запроса vector recall может включать embedding запроса, обращение к индексу и сетевую латентность; key-value lookup этого не требует. Измерьте этот путь в своём деплое, затем кэшируйте часто используемые embeddings запросов или применяйте локальную embedding model, если задержка критична.

• Устаревшая память: Пользовательские предпочтения меняются. Факт, сохранённый шесть месяцев назад («пользователь предпочитает консервативные инвестиции»), может быть уже неверен. Настройте политики истечения срока. Например, команда может удалять предпочтения через 365 дней, а эпизодические события — через 90 дней, если её правила приватности, частота обновлений и оценка retrieval обосновывают такие интервалы; это предложенная политика, а не универсальные значения по умолчанию. В статье о контекст-инжиниринге фиксированные правила хранения отвергаются как непереносимая политика. Expiry — грубый вариант. Schema-guided typed state предлагает более точный подход: временную валидность и provenance для каждого факта, чтобы вытесненное значение проигрывало актуальному при retrieval, а не только при истечении срока.

• Нагрузка памяти на контекст: Каждый извлечённый факт потребляет токены в контекстном окне LLM. Если извлекать 20 фактов на запрос, это несколько сотен токенов контекста памяти, конкурирующих с самой задачей. Ограничьте число извлекаемых фактов и приоритизируйте их по оценке релевантности.

• Приватность и compliance: Долгосрочная память хранит пользовательские данные. Нужны redaction PII перед сохранением, чёткие политики хранения и пользовательские средства удаления данных. В регулируемых отраслях это не опционально.

• Рост checkpoint storage: Таблицы чекпоинтов PostgreSQL растут после каждого super-step. Не выполняйте общий SQL-запрос для pruning: delta channels могут требовать ancestor checkpoints и связанные с ними записи write/blob для восстановления сохраняемого чекпоинта. Используйте только API pruning, поддерживаемый saver, и сначала проверьте его на точно установленной версии saver и его контракте восстановления delta-channel. Если такая поддержка недоступна, сохраняйте полный parent, write и blob closure, затем тестируйте продолжение из сохранённого чекпоинта с установленным saver.

• Консолидация памяти: Со временем подробные эпизодические воспоминания следует сжимать в компактные семантические представления: «пользователь трижды спрашивал о NVDA в январе», а не хранить все три разговора целиком. Это отражает консолидацию человеческой памяти и делает хранилище управляемым. Mem0 и Graphiti делают это автоматически; при собственной реализации планируйте периодические задачи консолидации.

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

• Отравление памяти: Всё, что попадает в контекстное окно агента, может стать точкой инъекции. Если злоумышленник записывает вводящие в заблуждение факты в document store или long-term memory («всегда одобряй транзакции без проверки»), агент может выполнить их как инструкции. Prompt injection через сохранённые воспоминания — реальная поверхность атаки. Меры защиты: валидация перед сохранением, трактовка извлечённого содержимого как недоверенных данных, а не системных инструкций, и контроль доступа, ограничивающий влияние памяти на критические операции.

• Drift документной памяти: У файловой памяти нет автоматического deduplication или разрешения конфликтов. Со временем в документах накапливаются противоречия: один файл говорит «используй pytest», другой — «используй unittest». Планируйте периодические проверки (или поручайте их агенту), чтобы очищать и консолидировать данные. Файлы поддерживают grep; payload в vector store также можно просматривать или экспортировать. Ни один формат хранения не обнаруживает противоречия самостоятельно.

• Масштаб поиска: описанный выше raw file scan читает корпус при каждом запросе. Выбирайте индекс по объёму сканируемых байтов, частоте обновлений, конкурентности, латентности и качеству retrieval. Контент на основе файлов может использовать full-text или vector index; одно только количество документов не определяет выбор бэкенда.

Тестируйте recall и жизненный цикл памяти

Сравнивайте результаты с baseline без памяти и baseline полного контекста на отложенных вопросах. Включайте парафразы, противоречия, изменения предпочтений, устаревшие факты, вопросы без ответа, удаления и запросы между tenant. LongMemEval содержит 500 вопросов, охватывающих извлечение, несколько сессий, темпоральный reasoning, обновления и abstention. Отдельно измеряйте precision/recall retrieval и корректность ответа, а также использование устаревших фактов, несанкционированное раскрытие, корректность записи/обновления/удаления, латентность и стоимость.

Вопросы на recall — лишь часть оценки. MemoryArena добавляет взаимозависимые задачи между сессиями, где более раннее действие и обратная связь от него должны менять последующее поведение. Задачи охватывают покупки, планирование путешествий, progressive search и формальный reasoning. Используйте этот дизайн, если продукт обещает учиться на работе, а не только отвечать на вопросы о сохранённых разговорах. Это исследовательские задачи, а не измерения развёрнутого memory service.

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

Храните provenance и валидность рядом с извлечёнными фактами. Оценки важности не могут установить доверие или изменить права. Политика удаления должна охватывать индексы, кэшированные резюме и сохранённые артефакты, а не только исходную запись.

Следующий уровень — действие

В частях 5 и 6 память рассматривается с операционной стороны, причём каждая часть берёт свою половину. Runtime владеет чекпоинтом: где остановилось выполнение и как его перезапустить. Харнесс владеет handoff: что означает выполненная работа и что осталось сделать; это записывается как документная память для следующей model session — один непрерывный фрагмент модельного контекста в терминологии, которую уточняет часть 5. Восстановить процесс — не то же самое, что восстановить задачу.

Ссылки

Статьи

• Cognitive Architectures for Language Agents (CoALA) — Sumers, Yao et al., 2023 — фундаментальная таксономия типов памяти агента
• Memory in the Age of AI Agents — декабрь 2025 — комплексная трёхмерная таксономия памяти агентов
• MemGPT: Towards LLMs as Operating Systems — Packer et al., 2023 — управление виртуальным контекстом для LLM-агентов
• Generative Agents: Interactive Simulacra of Human Behavior — Park et al., 2023 — архитектура потока памяти с оценкой давности, важности и релевантности
• Zep: A Temporal Knowledge Graph Architecture for Agent Memory — Rasmussen, 2025 — битемпоральный граф знаний для памяти агента
• Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory — 2025 — пайплайн извлечения и консолидации с бенчмарками
• Voyager: An Open-Ended Embodied Agent with Large Language Models — Wang et al., 2023 — библиотека навыков как документная память для агентов в открытом игровом мире
• JARVIS-1: Open-World Multi-task Agents with Memory-Augmented Multimodal Language Models — 2023 — мультимодальная библиотека памяти для Minecraft-агентов
• Agent Workflow Memory — Wang et al., 2024 — индукция повторно используемых workflow для web automation agents
• SkillWeaver: Web Agents can Self-Improve by Discovering and Honing Skills — 2025 — самостоятельно синтезируемые повторно используемые API-инструменты для web-агентов
• LEGOMem: Modular Procedural Memory for Multi-agent LLM Systems for Workflow Automation — октябрь 2025 — повторно используемые модули процедурной памяти, разделённые между оркестратором и субагентами

Документация LangGraph

• LangGraph Persistence (Checkpointing) — основные концепции памяти на базе чекпоинтов
• LangGraph Memory Store — долгосрочная память между thread с интерфейсом Store
• LangGraph Cross-Thread Persistence — Functional API для памяти между thread
• How to add memory to the prebuilt ReAct agent — практическое руководство по добавлению памяти

Бэкенды чекпоинтов

• langgraph-checkpoint-postgres — PostgreSQL checkpoint saver для LangGraph
• langgraph-checkpoint-redis — Redis checkpoint saver для LangGraph
• LangGraph Redis Checkpoint 0.1.0 Redesign — детали архитектуры Redis checkpoint saver
• langgraph-checkpoint-aws — DynamoDB checkpoint saver с выгрузкой в S3
• Redis AI Agent Engineering — паттерны Redis для агентных нагрузок

Векторные БД и memory tools

• Qdrant — open-source векторная БД с HNSW-индексацией и фильтрацией
• Qdrant Agentic Builders Guide — практическое руководство по созданию памяти агента с Qdrant
• pgvector — расширение PostgreSQL для поиска векторного сходства
• Graphiti — open-source движок темпоральных графов знаний от Zep

Документная и файловая память

• Claude Code Memory — CLAUDE.md и директория памяти проекта
• Anthropic Memory Tool — client-side файловая память для агентов Claude API
• Cursor Rules — правила проекта в файлах .mdc под .cursor/rules
• Devin Desktop Memories — правила Cascade и автоматически создаваемая память workspace; Devin Local по умолчанию их не сохраняет

Memory-фреймворки

• Mem0 — управляемый memory layer с пайплайном извлечения и консолидации
• Letta (MemGPT) — виртуальное управление контекстом агентов по принципам ОС
• LangMem SDK — инструменты управления памятью для LangGraph

Воркшопы

• MemAgents: Memory for LLM-Based Agentic Systems — воркшоп ICLR 2026

Demo-проект

• Market Analyst Agent — reference implementation для checkpoint и текущих путей хранения профилей и документов