--- read_when: - Вы настраиваете плагин memory-lancedb - Вам нужна долговременная память на базе LanceDB с автоматическим извлечением или сохранением данных. - Вы используете локальные эмбеддинги, совместимые с OpenAI, например Ollama sidebarTitle: Memory LanceDB summary: Настройте официальный внешний плагин памяти LanceDB, включая локальные встраивания, совместимые с Ollama title: Память LanceDB x-i18n: generated_at: "2026-07-16T16:40:13Z" model: gpt-5.6 postprocess_version: locale-links-v1 prompt_version: 32 provider: openai source_hash: 786b511da4fbfd90f4c3e5be5a1aeddf5daa59036247552bd671f4bab89319f6 source_path: plugins/memory-lancedb.md workflow: 16 --- `memory-lancedb` — это официальный внешний плагин, который хранит долгосрочную память в LanceDB с векторным поиском. Он может автоматически извлекать релевантные воспоминания перед ходом модели и автоматически сохранять важные факты после ответа. Используйте его для локальной векторной базы данных, OpenAI-совместимой конечной точки эмбеддингов или хранилища памяти вне стандартного встроенного бэкенда памяти. ## Установка ```bash openclaw plugins install @openclaw/memory-lancedb ``` Плагин опубликован в npm; он не входит в состав образа среды выполнения OpenClaw. При установке добавляется запись плагина, плагин включается, а `plugins.slots.memory` переключается на `memory-lancedb`. Если слот памяти в данный момент занят другим плагином, тот плагин отключается с предупреждением. Сопутствующие плагины, такие как `memory-wiki`, могут работать одновременно с `memory-lancedb`, но активный слот памяти в каждый момент времени может принадлежать только одному плагину. ## Быстрый старт ```json5 { plugins: { slots: { memory: "memory-lancedb", }, entries: { "memory-lancedb": { enabled: true, config: { embedding: { provider: "openai", model: "text-embedding-3-small", }, autoRecall: true, autoCapture: false, }, }, }, }, } ``` После изменения конфигурации плагина перезапустите Gateway, затем убедитесь, что он загрузился: ```bash openclaw gateway restart openclaw plugins list ``` ## Конфигурация эмбеддингов `embedding` обязателен и должен содержать хотя бы одно поле. Значение `provider` по умолчанию — `openai`; значение `model` по умолчанию — `text-embedding-3-small`. | Поле | Тип | Примечания | | ---------------------- | ------------- | ------------------------------------------------------------------------ | | `embedding.provider` | строка | Идентификатор адаптера, например `openai`, `github-copilot`, `ollama`. По умолчанию `openai`. | | `embedding.model` | строка | По умолчанию `text-embedding-3-small`. | | `embedding.apiKey` | строка | Необязательно; поддерживает подстановку `${ENV_VAR}`. | | `embedding.baseUrl` | строка | Необязательно; поддерживает подстановку `${ENV_VAR}`. | | `embedding.dimensions` | целое число (>=1) | Обязательно для моделей, отсутствующих во встроенной таблице (см. ниже). | Существует два пути выполнения запросов: - **Путь через адаптер провайдера** (по умолчанию): задайте `embedding.provider` и не указывайте `embedding.apiKey`/`embedding.baseUrl`. Плагин разрешает настроенный профиль аутентификации провайдера, переменную среды или `models.providers..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`. ```json5 { 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 размерностями: ```json5 { 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](/ru/providers/ollama). ```json5 { 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` | `1000` | 100-10000 | Текст, отправляемый API эмбеддингов для извлечения. | | `captureMaxChars` | `500` | 100-10000 | Допустимая для автоматического сохранения длина сообщения. | | `customTriggers` | `[]` | 0-50 элементов, каждый <=100 символов | Буквальные фразы, при наличии которых сообщение рассматривается для автоматического сохранения. | `recallMaxChars` ограничивает запрос автоматического извлечения `before_prompt_build`, инструмент `memory_recall`, путь запроса `memory_forget` и `openclaw ltm search`. Автоматическое извлечение создаёт эмбеддинг последнего сообщения пользователя в ходе и использует полный промпт только при отсутствии сообщения пользователя, благодаря чему метаданные канала и крупные блоки промпта не попадают в запрос эмбеддингов. `captureMaxChars` определяет, достаточно ли короткое сообщение пользователя из события `agent_end` текущего хода, чтобы рассматривать его для автоматического сохранения; на запросы извлечения эта настройка не влияет. `customTriggers` добавляет буквальные фразы автоматического сохранения без регулярных выражений. Встроенные триггеры охватывают распространённые фразы о памяти на английском, чешском, китайском, японском и корейском языках (`remember`, `prefer`, `记住`, `覚えて`, `기억해` и аналогичные). Автоматическое сохранение также отклоняет текст, похожий на метаданные конверта или транспорта, полезную нагрузку для инъекции промпта или уже внедрённый контекст ``, и ограничивает количество сохраняемых воспоминаний до 3 за ход агента. Каждое воспоминание принадлежит одному агенту. При извлечении, обнаружении дубликатов, сохранении, получении списка, необработанных запросах и удалении владелец всегда проверяется до возврата или изменения строк. Агент с `memorySearch.enabled: false` (в `agents.list[]` или через `agents.defaults`) также не получает ни одного из инструментов `memory_recall`, `memory_store` или `memory_forget` и не участвует в автоматическом извлечении или сохранении, даже если флаги уровня плагина `autoRecall`/`autoCapture` включены. ## Команды `memory-lancedb` регистрирует пространство имён CLI `ltm` при установке (а не только когда он занимает активный слот памяти): ```bash openclaw ltm list [--agent ] [--limit ] [--order-by-created-at] openclaw ltm search [--agent ] [--limit ] openclaw ltm stats [--agent ] ``` `ltm query` выполняет невекторный запрос непосредственно к таблице LanceDB: ```bash openclaw ltm query --agent research --cols id,text,createdAt --limit 20 openclaw ltm query --filter "category = 'preference'" --order-by createdAt:desc ``` | Флаг | По умолчанию | Примечания | | --------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `--agent ` | настроенный агент по умолчанию | Выбирает приватное пространство имён агента. Доступен для `list`, `search`, `query` и `stats`. | | `--cols ` | `id,text,importance,category,createdAt` | Разделённый запятыми список разрешённых столбцов. | | `--filter ` | нет | Одно сравнение по выходному столбцу, например `category = 'preference'` или `importance >= 0.8`. Строковые значения должны быть заключены в кавычки. | | `--limit ` | `10` | Положительное целое число. | | `--order-by :` | нет | Сортировка в памяти после применения фильтра; столбец сортировки автоматически добавляется в проекцию и удаляется из вывода, если он не был запрошен. | Агенты получают три инструмента от активного плагина памяти: - `memory_recall`: векторный поиск по сохранённым воспоминаниям. - `memory_store`: сохранение факта, предпочтения, решения или сущности (отклоняет текст, похожий на полезную нагрузку для инъекции промпта; пропускает почти дублирующиеся записи). - `memory_forget`: удаление по `memoryId` или по `query` (автоматически удаляет единственное совпадение с оценкой выше 90%, в противном случае выводит идентификаторы кандидатов для уточнения). ## Хранилище По умолчанию данные LanceDB сохраняются в `~/.openclaw/memory/lancedb`. Переопределите путь с помощью `dbPath`: ```json5 { 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}`: ```json5 { 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`. ## Устранение неполадок ### Длина входных данных превышает длину контекста Модель эмбеддингов отклонила запрос на извлечение: ```text memory-lancedb: сбой извлечения: Ошибка: 400 длина входных данных превышает длину контекста ``` Уменьшите `recallMaxChars`, затем перезапустите Gateway: ```json5 { plugins: { entries: { "memory-lancedb": { config: { recallMaxChars: 400, }, }, }, }, } ``` Для Ollama также убедитесь, что сервер эмбеддингов доступен с хоста Gateway через его нативную конечную точку для эмбеддингов: ```bash 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`, затем выполните: ```bash openclaw ltm stats openclaw ltm search "recent preference" ``` Если `autoCapture` отключён, плагин по-прежнему извлекает существующие воспоминания, но не сохраняет новые автоматически. Используйте инструмент `memory_store` или включите `autoCapture`. ## См. также - [Обзор памяти](/ru/concepts/memory) - [Active Memory](/ru/concepts/active-memory) - [Поиск в памяти](/ru/concepts/memory-search) - [Вики памяти](/ru/plugins/memory-wiki) - [Ollama](/ru/providers/ollama)