---
read_when:
    - Вы настраиваете плагин memory-lancedb
    - Вам нужна долговременная память на базе LanceDB с автоматическим извлечением или автоматическим сохранением
    - Вы используете локальные эмбеддинги, совместимые с OpenAI, например Ollama
sidebarTitle: Memory LanceDB
summary: Настройте официальный внешний плагин памяти LanceDB, включая локальные эмбеддинги, совместимые с Ollama
title: Память LanceDB
x-i18n:
    generated_at: "2026-07-13T20:03:12Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 24
    provider: openai
    source_hash: cdcf5ef7b7fbb8bf6055363d86782cfa36df193fc724406dba06c1380fd9f434
    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`. Если слотом памяти уже владеет
другой плагин, он отключается с предупреждением.

<Note>
Сопутствующие плагины, такие как `memory-wiki`, могут работать параллельно с `memory-lancedb`,
но активным слотом памяти одновременно владеет только один плагин.
</Note>

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

```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.<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`.

```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`, `记住`, `覚えて`, `기억해` и аналогичные).

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

## Команды

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

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

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

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

| Флаг                              | По умолчанию                           | Примечания                                                                                                                               |
| --------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `--cols <columns>`                | `id,text,importance,category,createdAt` | Разделённый запятыми список разрешённых столбцов.                                                                                         |
| `--filter <condition>`            | нет                                    | Условие WHERE в стиле SQL. Максимум 200 символов; разрешены только буквенно-цифровые символы, `_-`, пробелы и `='"<>!.,()%*`. |
| `--limit <n>`                     | `10`                                    | Положительное целое число.                                                                                                               |
| `--order-by <column>:<asc\|desc>` | нет                                    | Сортировка выполняется в памяти после применения фильтра; столбец сортировки автоматически добавляется в проекцию и удаляется из вывода, если он не был запрошен. |

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

- `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",
          },
        },
      },
    },
  },
}
```

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