Память 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-совместимой конечной точки эмбеддингов, для которой нет встроенного адаптера провайдера.

OpenAI Codex / ChatGPT OAuth не является учётными данными для эмбеддингов OpenAI Platform. Для эмбеддингов OpenAI используйте профиль аутентификации с ключом OpenAI API, 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 сохранёнными воспоминаниями за один ход агента.

Команды

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

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

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

openclaw ltm query --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",          },        },      },    },  },}

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 (Mac с процессором Intel). На этой платформе при загрузке плагин записывает в журнал, что 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