Память LanceDB

memory-lancedb — это официальный внешний плагин, который хранит долгосрочную память в LanceDB с векторным поиском. Он может автоматически извлекать релевантные воспоминания перед ходом модели и автоматически сохранять важные факты после ответа.

Используйте его для локальной векторной базы данных, OpenAI-совместимой конечной точки эмбеддингов или хранилища памяти вне стандартного встроенного бэкенда памяти.

Установка

openclaw plugins install @openclaw/memory-lancedb

Плагин опубликован в npm; он не входит в состав образа среды выполнения OpenClaw. При установке добавляется запись плагина, плагин включается, а plugins.slots.memory переключается на memory-lancedb. Если слот памяти в данный момент занят другим плагином, тот плагин отключается с предупреждением.

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

{  plugins: {    slots: {      memory: "memory-lancedb",    },    entries: {      "memory-lancedb": {        enabled: true,        config: {          embedding: {            provider: "openai",            model: "text-embedding-3-small",          },          autoRecall: true,          autoCapture: false,        },      },    },  },}

После изменения конфигурации плагина перезапустите Gateway, затем убедитесь, что он загрузился:

openclaw gateway restartopenclaw plugins list

Конфигурация эмбеддингов

embedding обязателен и должен содержать хотя бы одно поле. Значение provider по умолчанию — openai; значение model по умолчанию — text-embedding-3-small.

Существует два пути выполнения запросов:

• Путь через адаптер провайдера (по умолчанию): задайте embedding.provider и не указывайте embedding.apiKey/embedding.baseUrl. Плагин разрешает настроенный профиль аутентификации провайдера, переменную среды или models.providers.<provider>.apiKey через те же адаптеры эмбеддингов памяти, которые использует memory-core. Этот путь предназначен для github-copilot, ollama и любого другого встроенного провайдера с поддержкой эмбеддингов.
• Путь через прямой OpenAI-совместимый клиент: оставьте embedding.provider незаданным (или "openai") и задайте embedding.apiKey вместе с embedding.baseUrl. Используйте этот вариант для необработанной OpenAI-совместимой конечной точки эмбеддингов, для которой нет встроенного адаптера провайдера.

OAuth OpenAI Codex / ChatGPT не является учетными данными для эмбеддингов OpenAI Platform. Для эмбеддингов OpenAI используйте профиль аутентификации с ключом API OpenAI, OPENAI_API_KEY или models.providers.openai.apiKey. Пользователям только с OAuth следует выбрать другого провайдера с поддержкой эмбеддингов, например github-copilot или ollama.

{  plugins: {    entries: {      "memory-lancedb": {        enabled: true,        config: {          embedding: {            provider: "github-copilot",            model: "text-embedding-3-small",          },        },      },    },  },}

Некоторые OpenAI-совместимые конечные точки эмбеддингов отклоняют параметр encoding_format; другие игнорируют его и всегда возвращают number[]. memory-lancedb не включает encoding_format в запросы и принимает ответы как в виде массива чисел с плавающей точкой, так и в виде закодированных в base64 значений float32, поэтому обе формы ответа работают без дополнительной конфигурации.

Размерности

В OpenClaw встроены размерности только для text-embedding-3-small (1536) и text-embedding-3-large (3072). Для любой другой модели необходимо явно задать embedding.dimensions, чтобы LanceDB могла создать векторный столбец, например для ZhiPu embedding-3 с 2048 размерностями:

{  plugins: {    entries: {      "memory-lancedb": {        enabled: true,        config: {          embedding: {            apiKey: "${ZHIPU_API_KEY}",            baseUrl: "https://open.bigmodel.cn/api/paas/v4",            model: "embedding-3",            dimensions: 2048,          },        },      },    },  },}

Эмбеддинги Ollama

Используйте путь через встроенный адаптер провайдера Ollama (embedding.provider: "ollama"). Он вызывает нативную конечную точку Ollama /api/embed и применяет те же правила аутентификации и базового URL, что и провайдер Ollama.

{  plugins: {    slots: {      memory: "memory-lancedb",    },    entries: {      "memory-lancedb": {        enabled: true,        config: {          embedding: {            provider: "ollama",            baseUrl: "http://127.0.0.1:11434",            model: "mxbai-embed-large",            dimensions: 1024,          },          recallMaxChars: 400,          autoRecall: true,          autoCapture: false,        },      },    },  },}

mxbai-embed-large отсутствует во встроенной таблице размерностей, поэтому dimensions обязателен. Для небольших локальных моделей эмбеддингов уменьшите recallMaxChars, если локальный сервер возвращает ошибки длины контекста.

Ограничения извлечения и сохранения

recallMaxChars ограничивает запрос автоматического извлечения before_prompt_build, инструмент memory_recall, путь запроса memory_forget и openclaw ltm search. Автоматическое извлечение создаёт эмбеддинг последнего сообщения пользователя в ходе и использует полный промпт только при отсутствии сообщения пользователя, благодаря чему метаданные канала и крупные блоки промпта не попадают в запрос эмбеддингов.

captureMaxChars определяет, достаточно ли короткое сообщение пользователя из события agent_end текущего хода, чтобы рассматривать его для автоматического сохранения; на запросы извлечения эта настройка не влияет.

customTriggers добавляет буквальные фразы автоматического сохранения без регулярных выражений. Встроенные триггеры охватывают распространённые фразы о памяти на английском, чешском, китайском, японском и корейском языках (remember, prefer, 记住, 覚えて, 기억해 и аналогичные).

Автоматическое сохранение также отклоняет текст, похожий на метаданные конверта или транспорта, полезную нагрузку для инъекции промпта или уже внедрённый контекст <relevant-memories>, и ограничивает количество сохраняемых воспоминаний до 3 за ход агента.

Каждое воспоминание принадлежит одному агенту. При извлечении, обнаружении дубликатов, сохранении, получении списка, необработанных запросах и удалении владелец всегда проверяется до возврата или изменения строк. Агент с memorySearch.enabled: false (в agents.list[] или через agents.defaults) также не получает ни одного из инструментов memory_recall, memory_store или memory_forget и не участвует в автоматическом извлечении или сохранении, даже если флаги уровня плагина autoRecall/autoCapture включены.

Команды

memory-lancedb регистрирует пространство имён CLI ltm при установке (а не только когда он занимает активный слот памяти):

openclaw ltm list [--agent <id>] [--limit <n>] [--order-by-created-at]openclaw ltm search <query> [--agent <id>] [--limit <n>]openclaw ltm stats [--agent <id>]

ltm query выполняет невекторный запрос непосредственно к таблице LanceDB:

openclaw ltm query --agent research --cols id,text,createdAt --limit 20openclaw ltm query --filter "category = 'preference'" --order-by createdAt:desc

Агенты получают три инструмента от активного плагина памяти:

• memory_recall: векторный поиск по сохранённым воспоминаниям.
• memory_store: сохранение факта, предпочтения, решения или сущности (отклоняет текст, похожий на полезную нагрузку для инъекции промпта; пропускает почти дублирующиеся записи).
• memory_forget: удаление по memoryId или по query (автоматически удаляет единственное совпадение с оценкой выше 90%, в противном случае выводит идентификаторы кандидатов для уточнения).

Хранилище

По умолчанию данные LanceDB сохраняются в ~/.openclaw/memory/lancedb. Переопределите путь с помощью dbPath:

{  plugins: {    entries: {      "memory-lancedb": {        enabled: true,        config: {          dbPath: "~/.openclaw/memory/lancedb",          embedding: {            apiKey: "${OPENAI_API_KEY}",            model: "text-embedding-3-small",          },        },      },    },  },}

Плагин использует одну таблицу LanceDB и сохраняет в каждой строке нормализованного владельца-агента. Это граница хранилища, а не фильтр после поиска: принадлежность агенту применяется до векторного ранжирования и включается в предикаты получения списка, запроса, подсчёта и удаления. ltm query --filter принимает одно проверенное сравнение по публичным выходным столбцам. Хранилище формирует это сравнение отдельно от обязательного предиката владельца, поэтому фильтр не может расширить запрос на другого агента.

В базах данных, созданных до введения принадлежности отдельным агентам, отсутствуют надёжные сведения о происхождении строк. При обновлении openclaw doctor --fix однократно назначает эти устаревшие строки настроенному агенту по умолчанию. Доступ во время выполнения блокируется до завершения этой миграции; другие агенты никогда не наследуют старые общие строки.

storageOptions принимает строковые пары ключ/значение для бэкендов хранилища LanceDB (например, S3-совместимого объектного хранилища) и поддерживает подстановку ${ENV_VAR}:

{  plugins: {    entries: {      "memory-lancedb": {        enabled: true,        config: {          dbPath: "s3://memory-bucket/openclaw",          storageOptions: {            access_key: "${AWS_ACCESS_KEY_ID}",            secret_key: "${AWS_SECRET_ACCESS_KEY}",            endpoint: "${AWS_ENDPOINT_URL}",          },          embedding: {            apiKey: "${OPENAI_API_KEY}",            model: "text-embedding-3-small",          },        },      },    },  },}

Зависимости среды выполнения и поддержка платформ

memory-lancedb зависит от нативного пакета @lancedb/lancedb, за который отвечает пакет плагина (а не основной дистрибутив OpenClaw). При запуске Gateway зависимости плагина не восстанавливаются; если нативная зависимость отсутствует или не загружается, переустановите или обновите пакет плагина и перезапустите Gateway.

@lancedb/lancedb не публикует нативную сборку для darwin-x64 (Intel Mac). На этой платформе при загрузке плагин записывает в журнал сообщение о недоступности LanceDB; используйте стандартный бэкенд памяти, запустите Gateway на поддерживаемой платформе или архитектуре либо отключите memory-lancedb.

Устранение неполадок

Длина входных данных превышает длину контекста

Модель эмбеддингов отклонила запрос на извлечение:

memory-lancedb: сбой извлечения: Ошибка: 400 длина входных данных превышает длину контекста

Уменьшите recallMaxChars, затем перезапустите Gateway:

{  plugins: {    entries: {      "memory-lancedb": {        config: {          recallMaxChars: 400,        },      },    },  },}

Для Ollama также убедитесь, что сервер эмбеддингов доступен с хоста Gateway через его нативную конечную точку для эмбеддингов:

curl http://127.0.0.1:11434/api/embed \  -H "Content-Type: application/json" \  -d '{"model":"mxbai-embed-large","input":"hello"}'

Неподдерживаемая модель эмбеддингов

Без embedding.dimensions известны только встроенные размерности эмбеддингов OpenAI (text-embedding-3-small, text-embedding-3-large). Для любой другой модели задайте embedding.dimensions равным размеру вектора, сообщаемому этой моделью.

Плагин загружается, но воспоминания не появляются

Убедитесь, что plugins.slots.memory указывает на memory-lancedb, затем выполните:

openclaw ltm statsopenclaw ltm search "recent preference"

Если autoCapture отключён, плагин по-прежнему извлекает существующие воспоминания, но не сохраняет новые автоматически. Используйте инструмент memory_store или включите autoCapture.

См. также

• Обзор памяти
• Active Memory
• Поиск в памяти
• Вики памяти
• Ollama