Вопрос

openclaw memory: четыре файла, которые агент помнит

Из чего собрана память OpenClaw, что грузится в контекст, как работает поиск и когда чистить MEMORY.md.

· 6 мин чтения

Коротко

  • Память OpenClaw — это четыре файла в workspace агента: USER.md, MEMORY.md, memory/*.md и DREAMS.md; скрытого состояния нет.
  • USER.md и MEMORY.md попадают в старт сессии; дневные заметки доступны через memory_search и подтягиваются на голый /new или /reset.
  • memory_search по умолчанию гибридный (BM25 плюс эмбеддинги, MMR сверху), провайдер OpenAI; для офлайна — локальный llama.cpp, около 0,3 ГБ.
  • Провайдеры памяти: builtin на SQLite, Honcho, LanceDB-плагин; встроенный подходит большинству, остальные ставятся плагином.

Сверено с документацией OpenClaw 2026.10.2, 12 октября 2026.

Память OpenClaw — это просто Markdown-файлы в workspace агента (по умолчанию ~/.openclaw/workspace), плюс локальный индекс в SQLite. Скрытого состояния модель не имеет: что не записали на диск, то пропало. Чтобы агент что-то запомнил, достаточно сказать «запомни, что я предпочитаю TypeScript». Он сам положит заметку в подходящий файл.

Четыре слоя памяти и что попадает в контекст

В workspace четыре файла, связанных с памятью. USER.md (опционально) — это стабильный профиль пользователя: предпочтения, стиль общения, активные проекты; пишется директивами с датой наблюдения и меткой active/superseded.

MEMORY.md — компактный курируемый слой для долговечных фактов и принятых решений, не сырой транскрипт и не архив. Дневные заметки memory/YYYY-MM-DD.md (или со слагом, например для сессионной памяти) — рабочий слой: детали, наблюдения, сводки сессии. DREAMS.md (опционально) хранит дневник сводок dreaming для ручного разбора.

Дневные заметки индексируются и доступны через memory_search и memory_get, но в промпт на каждом ходу не подгружаются. Сегодняшняя и вчерашняя подтягиваются автоматически на голый /new или /reset.

Если MEMORY.md перерастает бюджет стартовой загрузки, OpenClaw режет только копию, попадающую в контекст. Это сигнал перенести детали в memory/*.md, оставить в MEMORY.md только сводку или поднять лимиты. Посмотреть сырой и инжектируемый размер вместе со статусом обрезки позволяют /context list, /context detail и openclaw doctor.

Что агент пишет сам, а что задаёте вручную

Полезное из дневных заметок переносится в MEMORY.md стандартным sweep. Сгенерированные инструкции workspace поощряют агента записывать долговечные факты по ходу работы, а консолидацию берёт на себя dreaming. Стандартный промпт heartbeat никакого обслуживания памяти сам не делает.

Документация просит фиксировать в таких заметках: требования к подтверждению, временные ограничения, передачи в другую сессию или поток, условия истечения, момент, когда безопасно действовать, источник или владельца доверия и чего агенту делать не следует. Простой пример: «API-миграция проектируется в другой сессии; пока план не ляжет, здесь только входные данные для дизайна, код не править».

Для точных напоминаний по времени и периодических задач в OpenClaw есть cron, а не память. Документация подчёркивает: память хранит контекст подтверждения, но политику не применяет. Жёсткие операционные ограничения задаются через настройки подтверждений, песочницу и запланированные задачи.

Импорт из Codex, Claude Code и Hermes идёт через Control UI: Settings → Import Memory, либо командой import memory в чате после онбординга. Импорты складываются отдельно и в стартовый MEMORY.md не сливаются.

Как искать по истории

memory_search запускает два пути параллельно и объединяет их: BM25 по словам (то́чные ID, строки ошибок, ключи конфига) и векторный поиск по эмбеддингам для близких по смыслу формулировок. Точные пути и базнеймы ранжируются выше частичных совпадений, но сниппеты и BM25 по-прежнему идут по содержимому.

Затем работает детерминированный скоринг «hybrid relevance × recency decay × importance multiplier», после — MMR-переупорядочивание для снижения дубликатов (лямбда 0.7, Jaccard по токенам сниппета). Дневные заметки с датой и слагом получают 30-дневный период полураспада, а MEMORY.md, USER.md и бездатовые файлы под memory/ сохраняют вес навсегда. По умолчанию провайдер эмбеддингов OpenAI (text-embedding-3-small), если задан OPENAI_API_KEY или ключ в models.providers.openai.apiKey.

Переключить провайдера можно одним блоком:

Для офлайна без API-ключа есть управляемый провайдер llama.cpp, размер модели около 0,3 ГБ. Сначала поставьте плагин, затем один раз выберите llama.cpp в интерактивной настройке (openclaw onboard): OpenClaw сам установит llama-server и скачает модель эмбеддингов.

openclaw plugins install @openclaw/llama-cpp-provider
{
  memory: {
    search: {
      provider: "local",
      fallback: "none",
      local: {
        modelPath: "~/.openclaw/models/llama.cpp/hf_ggml-org_embeddinggemma-300m-qat-Q8_0.gguf",
      },
    },
  },
}

provider: "none" сознательно отключает эмбеддинги и оставляет только FTS. Если явно указан провайдер вроде openai, gemini или ollama и он недоступен, memory_search сообщает, что память недоступна, и не откатывается молча на FTS. У local, а также при незаданном провайдере или "auto" откат на поиск по ключевым словам есть. Асимметричные input_type (query/document) для OpenAI-совместимых эндпоинтов задаются через queryInputType и documentInputType.

Поиск по самим сессионным транскриптам включается отдельно: experimental.sessionMemory: true и "sessions" в sources (по умолчанию ["memory"]). Для точных полнотекстовых выдержек из истории есть sessions_search плюс sessions_history с sessionKey, messageId и sessionId.

Чистка и удаление

Индекс живёт в SQLite на агента: ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. В этой же базе лежат сессии и транскрипты, поэтому удалять её или файлы -wal/-shm ради сброса памяти нельзя. Для чистого сброса индекса есть openclaw memory reset --agent <id>, после него запустите openclaw memory index --agent <id>. Каждый чанк хранит происхождение отдельно от Markdown: класс источника (владелец, агент, недоверенный источник, системный), вид сессии, время наблюдения и опциональный ключ замещения.

Управляется это через openclaw memory. Базовые флаги:

openclaw memory status [--agent <id>] [--deep] [--index] [--fix]
openclaw memory index [--agent <id>] [--force] [--verbose]

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

openclaw memory status --deep --agent <id>
openclaw memory index --force --agent <id>
openclaw memory status --agent <id>

Частые ошибки

  • Путать «нет провайдера эмбеддингов» и «вообще нет поиска»: без эмбеддингов работает чистый BM25, но при явном провайдере его падение видно как недоступность памяти, а не тихий FTS-режим.
  • Рассчитывать на дневные заметки как на контекст на каждом ходу: они не подгружаются в стартовую загрузку, в автозагрузке появляются только сегодняшняя и вчерашняя, остальное — через memory_search.
  • Ждать, что heartbeat сам почистит память: стандартный промпт обслуживание памяти не делает, нужна сводка dreaming или ручная правка MEMORY.md.
  • Тянуть в MEMORY.md сырой транскрипт, пока стартовый бюджет не начнёт резать файл: детали лучше держать в memory/*.md, а в MEMORY.md оставлять сводку.