Memoria LanceDB

memory-lancedb es un plugin externo oficial que almacena memoria a largo plazo en LanceDB con búsqueda vectorial. Puede recuperar automáticamente recuerdos relevantes antes de un turno del modelo y capturar automáticamente hechos importantes después de una respuesta.

Úselo para una base de datos vectorial local, un endpoint de embeddings compatible con OpenAI o un almacén de memoria fuera del backend de memoria integrado predeterminado.

Instalación

openclaw plugins install @openclaw/memory-lancedb

El plugin se publica en npm; no está incluido en la imagen de ejecución de OpenClaw. Al instalarlo, se escribe la entrada del plugin, se habilita y se cambia plugins.slots.memory a memory-lancedb. Si actualmente otro plugin ocupa la ranura de memoria, se deshabilita con una advertencia.

Inicio rápido

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

Reinicie el Gateway después de cambiar la configuración del plugin y, a continuación, compruebe que se haya cargado:

openclaw gateway restartopenclaw plugins list

Configuración de embeddings

embedding es obligatorio y debe incluir al menos un campo. El valor predeterminado de provider es openai; el de model es text-embedding-3-small.

Existen dos rutas de solicitud:

• Ruta del adaptador del proveedor (predeterminada): establezca embedding.provider y omita embedding.apiKey/embedding.baseUrl. El plugin resuelve el perfil de autenticación configurado del proveedor, la variable de entorno o models.providers.<provider>.apiKey mediante los mismos adaptadores de embeddings de memoria que utiliza memory-core. Esta es la ruta para github-copilot, ollama y cualquier otro proveedor incluido que admita embeddings.
• Ruta directa del cliente compatible con OpenAI: deje embedding.provider sin establecer (o como "openai") y establezca embedding.apiKey junto con embedding.baseUrl. Utilice esta opción para un endpoint de embeddings compatible con OpenAI que no tenga un adaptador de proveedor incluido.

OAuth de OpenAI Codex / ChatGPT no es una credencial de embeddings de la plataforma OpenAI. Para los embeddings de OpenAI, utilice un perfil de autenticación con clave de API de OpenAI, OPENAI_API_KEY o models.providers.openai.apiKey. Los usuarios que solo dispongan de OAuth deben elegir otro proveedor compatible con embeddings, como github-copilot u ollama.

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

Algunos endpoints de embeddings compatibles con OpenAI rechazan el parámetro encoding_format; otros lo ignoran y siempre devuelven number[]. memory-lancedb omite encoding_format en las solicitudes y acepta respuestas de matrices de números de coma flotante o float32 codificadas en base64, por lo que ambos formatos de respuesta funcionan sin configuración.

Dimensiones

OpenClaw solo tiene dimensiones integradas para text-embedding-3-small (1536) y text-embedding-3-large (3072). Cualquier otro modelo necesita un valor explícito de embedding.dimensions para que LanceDB pueda crear la columna vectorial; por ejemplo, ZhiPu embedding-3 con 2048 dimensiones:

{  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,          },        },      },    },  },}

Embeddings de Ollama

Utilice la ruta del adaptador del proveedor Ollama incluido (embedding.provider: "ollama"). Esta llama al endpoint nativo /api/embed de Ollama y sigue las mismas reglas de autenticación y URL base que el proveedor 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 no está en la tabla de dimensiones integrada, por lo que dimensions es obligatorio. Para modelos locales de embeddings pequeños, reduzca recallMaxChars si el servidor local devuelve errores de longitud de contexto.

Límites de recuperación y captura

recallMaxChars limita la consulta de recuperación automática de before_prompt_build, la herramienta memory_recall, la ruta de consulta de memory_forget y openclaw ltm search. La recuperación automática genera el embedding del último mensaje del usuario del turno y solo recurre al prompt completo cuando no hay ningún mensaje del usuario, lo que excluye los metadatos del canal y los bloques de prompt grandes de la solicitud de embeddings.

captureMaxChars determina si un mensaje del usuario del evento agent_end del turno es lo bastante corto como para considerarlo para la captura automática; no afecta a las consultas de recuperación.

customTriggers añade frases literales de captura automática sin expresiones regulares. Los activadores integrados abarcan frases habituales de memoria en inglés, checo, chino, japonés y coreano (remember, prefer, 记住, 覚えて, 기억해 y similares).

La captura automática también rechaza el texto que parece contener metadatos de envoltura o transporte, cargas de inyección de prompt o contexto <relevant-memories> ya inyectado, y establece un máximo de 3 recuerdos capturados por turno del agente.

Comandos

memory-lancedb registra el espacio de nombres ltm de la CLI siempre que está instalado (no solo cuando ocupa la ranura de memoria activa):

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

ltm query ejecuta una consulta no vectorial directamente en la tabla de LanceDB:

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

Los agentes reciben tres herramientas del plugin de memoria activo:

• memory_recall: búsqueda vectorial en los recuerdos almacenados.
• memory_store: guarda un hecho, una preferencia, una decisión o una entidad (rechaza texto que parezca una carga de inyección de prompt; omite los elementos almacenados casi duplicados).
• memory_forget: elimina por memoryId o por query (elimina automáticamente una única coincidencia con una puntuación superior al 90 %; de lo contrario, muestra los Id. candidatos para desambiguar).

Almacenamiento

Los datos de LanceDB se almacenan de forma predeterminada en ~/.openclaw/memory/lancedb. Sobrescriba esta ubicación con dbPath:

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

storageOptions acepta pares clave/valor de cadena para backends de almacenamiento de LanceDB (p. ej., almacenamiento de objetos compatible con S3) y admite la expansión de ${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",          },        },      },    },  },}

Dependencias de ejecución y compatibilidad con plataformas

memory-lancedb depende del paquete nativo @lancedb/lancedb, que pertenece al paquete del plugin (no a la distribución principal de OpenClaw). El inicio del Gateway no repara las dependencias del plugin; si falta la dependencia nativa o no se puede cargar, reinstale o actualice el paquete del plugin y reinicie el Gateway.

@lancedb/lancedb no publica una compilación nativa para darwin-x64 (Mac Intel). En esa plataforma, el plugin registra durante la carga que LanceDB no está disponible; utilice el backend de memoria predeterminado, ejecute el Gateway en una plataforma o arquitectura compatible, o deshabilite memory-lancedb.

Solución de problemas

La longitud de la entrada supera la longitud del contexto

El modelo de embeddings rechazó la consulta de recuperación:

memory-lancedb: recall failed: Error: 400 the input length exceeds the context length

Reduzca recallMaxChars y, a continuación, reinicie el Gateway:

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

Para Ollama, compruebe también que se pueda acceder al servidor de embeddings desde el host del Gateway mediante su endpoint nativo de embeddings:

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

Modelo de embeddings no compatible

Sin embedding.dimensions, solo se conocen las dimensiones integradas de los embeddings de OpenAI (text-embedding-3-small, text-embedding-3-large). Para cualquier otro modelo, establezca embedding.dimensions en el tamaño vectorial que indique el modelo.

El plugin se carga, pero no aparece ningún recuerdo

Confirma que plugins.slots.memory apunte a memory-lancedb y, a continuación, ejecuta:

openclaw ltm statsopenclaw ltm search "recent preference"

Si autoCapture está deshabilitado, el plugin sigue recuperando los recuerdos existentes, pero no almacena nuevos automáticamente. Usa la herramienta memory_store o habilita autoCapture.

Contenido relacionado

• Descripción general de la memoria
• Active Memory
• Búsqueda en la memoria
• Wiki de memoria
• Ollama