Пам’ять LanceDB

memory-lancedb — це офіційний зовнішній plugin, який зберігає довготривалу пам’ять у LanceDB із векторним пошуком. Він може автоматично пригадувати релевантні спогади перед ходом моделі та автоматично зберігати важливі факти після відповіді.

Використовуйте його для локальної векторної бази даних, сумісної з OpenAI кінцевої точки вбудовувань або сховища пам’яті поза стандартним вбудованим бекендом пам’яті.

Встановлення

openclaw plugins install @openclaw/memory-lancedb

Plugin опубліковано в npm; він не входить до складу образу середовища виконання OpenClaw. Під час встановлення додається запис plugin, він вмикається, а plugins.slots.memory перемикається на memory-lancedb. Якщо слотом пам’яті наразі керує інший plugin, його буде вимкнено з попередженням.

Швидкий початок

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

Після зміни конфігурації plugin перезапустіть Gateway, а потім перевірте, чи його завантажено:

openclaw gateway restartopenclaw plugins list

Конфігурація вбудовувань

embedding є обов’язковим і має містити принаймні одне поле. provider за замовчуванням має значення openai; model за замовчуванням має значення text-embedding-3-small.

Існує два шляхи запитів:

• Шлях через адаптер провайдера (за замовчуванням): задайте embedding.provider і не вказуйте embedding.apiKey/embedding.baseUrl. Plugin визначає налаштований профіль автентифікації провайдера, змінну середовища або 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 збереженими спогадами на один хід агента.

Кожен спогад належить одному агенту. Пригадування, виявлення дублікатів, збереження, перегляд списку, необроблені запити та видалення — усі ці операції перевіряють власника перед поверненням або зміненням рядків. Агент із memorySearch.enabled: false (у agents.list[] або через agents.defaults) також не отримує жодного з інструментів memory_recall, memory_store чи memory_forget і не бере участі в автоматичному пригадуванні чи збереженні, навіть коли прапорці рівня plugin 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

Агенти отримують три інструменти від активного plugin пам’яті:

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

Plugin підтримує одну таблицю 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 (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