Mémoire LanceDB

memory-lancedb est un Plugin externe officiel qui stocke la mémoire à long terme dans LanceDB avec une recherche vectorielle. Il peut rappeler automatiquement les souvenirs pertinents avant le tour d’un modèle et capturer automatiquement les faits importants après une réponse.

Utilisez-le pour une base de données vectorielle locale, un point de terminaison d’embeddings compatible avec OpenAI ou un magasin de mémoire distinct du moteur de mémoire intégré par défaut.

Installation

openclaw plugins install @openclaw/memory-lancedb

Le Plugin est publié sur npm ; il n’est pas inclus dans l’image d’exécution d’OpenClaw. Son installation écrit l’entrée du Plugin, l’active et définit plugins.slots.memory sur memory-lancedb. Si un autre Plugin occupe actuellement l’emplacement mémoire, celui-ci est désactivé avec un avertissement.

Démarrage rapide

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

Redémarrez le Gateway après avoir modifié la configuration du Plugin, puis vérifiez qu’il a été chargé :

openclaw gateway restartopenclaw plugins list

Configuration des embeddings

embedding est obligatoire et doit inclure au moins un champ. provider vaut par défaut openai ; model vaut par défaut text-embedding-3-small.

Deux chemins de requête sont disponibles :

• Chemin de l’adaptateur de fournisseur (par défaut) : définissez embedding.provider et omettez embedding.apiKey/embedding.baseUrl. Le Plugin résout le profil d’authentification configuré du fournisseur, la variable d’environnement ou models.providers.<provider>.apiKey au moyen des mêmes adaptateurs d’embeddings de mémoire que ceux utilisés par memory-core. Ce chemin convient à github-copilot, ollama et à tout autre fournisseur inclus prenant en charge les embeddings.
• Chemin direct du client compatible avec OpenAI : laissez embedding.provider non défini (ou défini sur "openai") et définissez embedding.apiKey ainsi que embedding.baseUrl. Utilisez ce chemin pour un point de terminaison d’embeddings brut compatible avec OpenAI qui ne dispose d’aucun adaptateur de fournisseur inclus.

L’OAuth d’OpenAI Codex / ChatGPT n’est pas un identifiant d’accès aux embeddings de la plateforme OpenAI. Pour les embeddings OpenAI, utilisez un profil d’authentification avec une clé API OpenAI, OPENAI_API_KEY ou models.providers.openai.apiKey. Les utilisateurs disposant uniquement d’OAuth doivent choisir un autre fournisseur prenant en charge les embeddings, tel que github-copilot ou ollama.

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

Certains points de terminaison d’embeddings compatibles avec OpenAI refusent le paramètre encoding_format ; d’autres l’ignorent et renvoient toujours number[]. memory-lancedb omet encoding_format dans les requêtes et accepte les réponses sous forme de tableaux de nombres à virgule flottante ou de valeurs float32 encodées en base64 ; les deux formats de réponse fonctionnent donc sans configuration.

Dimensions

OpenClaw possède une dimension intégrée uniquement pour text-embedding-3-small (1536) et text-embedding-3-large (3072). Tout autre modèle nécessite une valeur explicite pour embedding.dimensions afin que LanceDB puisse créer la colonne vectorielle, par exemple ZhiPu embedding-3 avec 2048 dimensions :

{  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 Ollama

Utilisez le chemin de l’adaptateur du fournisseur Ollama inclus (embedding.provider: "ollama"). Il appelle le point de terminaison natif /api/embed d’Ollama et suit les mêmes règles d’authentification et d’URL de base que le fournisseur 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 ne figure pas dans le tableau intégré des dimensions ; dimensions est donc obligatoire. Pour les petits modèles d’embeddings locaux, réduisez recallMaxChars si le serveur local renvoie des erreurs de longueur de contexte.

Limites de rappel et de capture

recallMaxChars limite la requête de rappel automatique before_prompt_build, l’outil memory_recall, le chemin de requête memory_forget et openclaw ltm search. Le rappel automatique génère l’embedding du dernier message utilisateur du tour et utilise l’invite complète uniquement lorsqu’aucun message utilisateur n’est présent, ce qui exclut les métadonnées du canal et les grands blocs d’invite de la requête d’embedding.

captureMaxChars détermine si un message utilisateur provenant de l’événement agent_end du tour est suffisamment court pour être pris en compte par la capture automatique ; il n’affecte pas les requêtes de rappel.

customTriggers ajoute des expressions littérales de capture automatique sans expression régulière. Les déclencheurs intégrés couvrent les expressions courantes liées à la mémoire en anglais, en tchèque, en chinois, en japonais et en coréen (remember, prefer, 记住, 覚えて, 기억해 et expressions similaires).

La capture automatique rejette également les textes qui ressemblent à des métadonnées d’enveloppe ou de transport, à des charges utiles d’injection d’invite ou à un contexte <relevant-memories> déjà injecté, et limite la capture à 3 souvenirs par tour d’agent.

Commandes

memory-lancedb enregistre l’espace de noms CLI ltm chaque fois qu’il est installé (et pas uniquement lorsqu’il occupe l’emplacement mémoire actif) :

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

ltm query exécute une requête non vectorielle directement sur la table LanceDB :

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

Les agents obtiennent trois outils du Plugin de mémoire actif :

• memory_recall : recherche vectorielle dans les souvenirs stockés.
• memory_store : enregistre un fait, une préférence, une décision ou une entité (rejette le texte qui ressemble à une charge utile d’injection d’invite ; ignore les enregistrements presque identiques).
• memory_forget : supprime par memoryId ou par query (supprime automatiquement une correspondance unique dont le score dépasse 90 %, sinon répertorie les identifiants candidats pour lever l’ambiguïté).

Stockage

Les données LanceDB sont stockées par défaut dans ~/.openclaw/memory/lancedb. Remplacez ce chemin avec dbPath :

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

storageOptions accepte des paires clé/valeur de chaînes pour les moteurs de stockage LanceDB (par exemple, un stockage d’objets compatible avec S3) et prend en charge l’expansion 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",          },        },      },    },  },}

Dépendances d’exécution et prise en charge des plateformes

memory-lancedb dépend du paquet natif @lancedb/lancedb, détenu par le paquet du Plugin (et non par la distribution principale d’OpenClaw). Le démarrage du Gateway ne répare pas les dépendances du Plugin ; si la dépendance native est absente ou ne peut pas être chargée, réinstallez ou mettez à jour le paquet du Plugin, puis redémarrez le Gateway.

@lancedb/lancedb ne publie pas de version native pour darwin-x64 (Mac Intel). Sur cette plateforme, le Plugin indique dans les journaux que LanceDB est indisponible lors du chargement ; utilisez le moteur de mémoire par défaut, exécutez le Gateway sur une plateforme ou une architecture prise en charge, ou désactivez memory-lancedb.

Résolution des problèmes

La longueur de l’entrée dépasse la longueur du contexte

Le modèle d’embedding a rejeté la requête de rappel :

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

Réduisez recallMaxChars, puis redémarrez le Gateway :

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

Pour Ollama, vérifiez également que le serveur d’embeddings est accessible depuis l’hôte du Gateway au moyen de son point de terminaison d’embedding natif :

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

Modèle d’embedding non pris en charge

Sans embedding.dimensions, seules les dimensions d’embeddings OpenAI intégrées sont connues (text-embedding-3-small, text-embedding-3-large). Pour tout autre modèle, définissez embedding.dimensions sur la taille de vecteur indiquée par ce modèle.

Le Plugin se charge, mais aucun souvenir n’apparaît

Confirmez que plugins.slots.memory pointe vers memory-lancedb, puis exécutez :

openclaw ltm statsopenclaw ltm search "recent preference"

Si autoCapture est désactivé, le plugin récupère toujours les souvenirs existants, mais n’en stocke pas automatiquement de nouveaux. Utilisez l’outil memory_store ou activez autoCapture.

Pages connexes

• Présentation de la mémoire
• Active Memory
• Recherche dans la mémoire
• Wiki de la mémoire
• Ollama