MemPalace avec Milvus
MemPalace est une couche de mémoire destinée aux agents de codage et aux workflows de développement de longue durée. Elle organise les connaissances du projet en ailes, salles et tiroirs, puis rend le contenu d’origine consultable d’une session à l’autre.
Dans ce tutoriel, nous allons utiliser l’interface CLI de MemPalace pour extraire un sous-ensemble réel de la documentation publique de Milvus et le stocker dans Milvus. Le corpus contient de la documentation sur les analyseurs, les tokeniseurs et les filtres de tokens. Ces pages étroitement liées fournissent suffisamment d’éléments de distraction pour rendre les exemples de recherche pertinents.
L’exemple utilise Milvus Lite ; il s’exécute donc localement, sans Docker ni serveur de base de données distinct. La même configuration MemPalace peut également pointer vers un serveur Milvus ou Zilliz Cloud pour des déploiements partagés.
Prérequis
Installez MemPalace avec ses dépendances Milvus facultatives depuis PyPI. La commande ne spécifie intentionnellement aucune version, de sorte qu’une nouvelle installation installe la dernière version disponible.
uv tool install "mempalace[milvus]"
Vous aurez également besoin de Git pour télécharger le corpus de documentation.
Ce tutoriel utilise le modèle d’embedding local MiniLM de MemPalace ; il ne nécessite donc pas de clé API pour un modèle externe. La première commande d’exploration ou de recherche peut télécharger un petit modèle d’embedding ONNX.
Configurer l’espace de travail
Créez un espace de travail comportant des répertoires distincts pour la documentation et le « palace » :
mkdir -p mempalace-milvus-demo
cd mempalace-milvus-demo
export PALACE_DIR="$PWD/palace"
export DOCS_REPO="$PWD/milvus-docs"
export PROJECT_DIR="$PWD/milvus-analyzer-docs"
export MEMPALACE_EMBEDDING_MODEL="minilm"
export MEMPALACE_EMBEDDING_DEVICE="cpu"
export MEMPALACE_EMBEDDING_THREADS="2"
Nous transmettons ` --backend milvus ` aux commandes MemPalace ci-dessous. Comme aucune URI Milvus distante n’est configurée, MemPalace crée une base de données Milvus Lite locale à l’adresse ` $PALACE_DIR/milvus.db`.
En ce qui concerne l’argument
MilvusClientutilisé par le backend :
- Définir
urisur un chemin local, tel que./milvus.db, est l’option la plus pratique. Cela utilise automatiquement Milvus Lite pour stocker les données localement.- Pour un déploiement à plus grande échelle, vous pouvez utiliser un serveur Milvus et définir l’URI sur son point de terminaison, par exemple
http://localhost:19530.- Pour utiliser Zilliz Cloud, configurez l’URI et le jeton en indiquant respectivement le point de terminaison public et la clé API du cluster.
Télécharger le corpus de documentation Milvus
Le référentiel de documentation de Milvus est bien plus volumineux que ce dont cet exemple a besoin. Utilisez la fonctionnalité « sparse checkout » de Git pour ne télécharger que le répertoire de documentation de l’Analyzer à partir de la branche v3.0.x:
git clone \
--depth 1 \
--filter=blob:none \
--sparse \
--branch v3.0.x \
https://github.com/milvus-io/milvus-docs.git \
"$DOCS_REPO"
git -C "$DOCS_REPO" sparse-checkout set \
site/en/userGuide/schema/analyzer
cp -R \
"$DOCS_REPO/site/en/userGuide/schema/analyzer" \
"$PROJECT_DIR"
Au moment de la rédaction de ce document, ce répertoire contient 31 pages Markdown. Elles comprennent des guides généraux sur Analyzer et trois groupes de pages étroitement liées :
milvus-analyzer-docs/
├── analyzer/ # Built-in language analyzers
├── filter/ # Token filters
├── tokenizer/ # Tokenizers
└── *.md # Analyzer overviews and selection guides
Vérifiez le nombre de pages sources :
find "$PROJECT_DIR" -type f -name "*.md" | wc -l
Résultat de référence :
31
Le nombre exact peut varier à mesure que la branche de documentation de Milvus est mise à jour.
Définir les pièces MemPalace
MemPalace peut détecter des « rooms » lors de l’ mempalace init, mais son processus d’initialisation effectue également une classification heuristique des entités à l’échelle du projet et enregistre les résultats acceptés dans un registre d’entités. Cette étape de classification n’est pas nécessaire pour définir ce corpus de documentation ; nous fournissons donc directement cette petite taxonomie. Au cours de l’exploration, MemPalace peut tout de même associer des métadonnées d’entités heuristiques déterministes et créer des liens internes de type « hallway » ; ces associations ne déterminent pas quelle pièce reçoit un fichier et ne modifient pas les recherches par pièce décrites ci-dessous.
Créez un fichier « $PROJECT_DIR/mempalace.yaml » avec le contenu suivant :
wing: milvus_analyzer_docs
rooms:
- name: analyzer
description: Built-in language analyzers and analyzer selection guides
keywords:
- analyzer
- name: filter
description: Token filters used in analyzer pipelines
keywords:
- filter
- name: tokenizer
description: Tokenizers and language identification
keywords:
- tokenizer
- name: general
description: Analyzer documentation that does not fit another room
keywords: []
L’aile représente l’ensemble du corpus de documentation. Une pièce représente un domaine thématique. MemPalace achemine un fichier en vérifiant d’abord son répertoire, puis son nom de fichier, puis les mots-clés de pièce présents dans son contenu. Un fichier situé sous filter/, par exemple, est directement acheminé vers la pièce « filter ».
Chaque fichier est ensuite divisé en segments de texte qui se chevauchent. Chaque segment devient un tiroir contenant le code Markdown tel quel ainsi que des métadonnées telles que wing, room, source_file, chunk_index et les numéros de ligne de la source. Les « rooms » et les tiroirs restent des métadonnées logiques au sein des collections Milvus de MemPalace ; MemPalace ne crée pas de collection Milvus distincte pour chaque « room ».
Extrayer la documentation dans Milvus
Extraire les données du projet à l’aide du backend Milvus :
mempalace \
--palace "$PALACE_DIR" \
mine "$PROJECT_DIR" \
--backend milvus
Référence de la sortie à partir de l’instantané de documentation validé :
=======================================================
Done.
Files processed: 31
Files skipped (already filed or other): 0
Drawers filed: 473
By room:
filter 16 files
analyzer 8 files
tokenizer 7 files
=======================================================
MemPalace lit le Markdown sans le résumer ni le réécrire, calcule les représentations locales et stocke les tiroirs dans Milvus. Sur l’instantané de documentation testé, 31 fichiers ont généré 473 tiroirs.
Vérifier les pièces résultantes et le nombre de tiroirs :
mempalace --palace "$PALACE_DIR" status --backend milvus
Résultats de référence :
=======================================================
MemPalace Status -- 473 drawers
=======================================================
WING: milvus_analyzer_docs
ROOM: analyzer 212 drawers
ROOM: filter 156 drawers
ROOM: tokenizer 105 drawers
=======================================================
Le nombre exact de « drawers » peut varier lorsque la documentation en amont change, car les pages plus longues génèrent davantage de segments.
Recherche sémantique
Utilisez mempalace search pour récupérer de la documentation en fonction de son sens. La question suivante ne mentionne pas de fichier spécifique ni de fonctionnalité d’Analyzer :
mempalace \
--palace "$PALACE_DIR" \
search "How should I analyze documents that mix several languages?" \
--backend milvus \
--wing milvus_analyzer_docs \
--results 3
Résultats de référence (les scores peuvent varier) :
Results for: "How should I analyze documents that mix several languages?"
Wing: milvus_analyzer_docs
[1] milvus_analyzer_docs / analyzer
Source: multi-language-analyzers.md
Match: cosine_sim=0.334 bm25=2.469
[2] milvus_analyzer_docs / analyzer
Source: multi-language-analyzers.md
[3] milvus_analyzer_docs / analyzer
Source: multi-language-analyzers.md
Lors de l'exécution validée, les trois résultats provenaient tous de multi-language-analyzers.md, même si le corpus contenait également des pages consacrées à des analyseurs, des tokeniseurs et des filtres linguistiques individuels.
Recherche au sein d’une « room »
Les filtres de « room » sont utiles lorsque des concepts apparentés apparaissent dans l’ensemble du corpus. La requête suivante recherche uniquement dans la « room » filter un moyen de faire correspondre des termes équivalents :
mempalace \
--palace "$PALACE_DIR" \
search "How can equivalent terms such as USA and United States match one another?" \
--backend milvus \
--wing milvus_analyzer_docs \
--room filter \
--results 3
Résultats de référence (les scores peuvent varier) :
Results for: "How can equivalent terms such as USA and United States match one another?"
Wing: milvus_analyzer_docs
Room: filter
[1] milvus_analyzer_docs / filter
Source: synonym-filter.md
Match: cosine_sim=0.765 bm25=2.573
[2] milvus_analyzer_docs / filter
Source: stemmer-filter.md
[3] milvus_analyzer_docs / filter
Source: stop-filter.md
Le premier résultat devrait provenir de synonym-filter.md. La contrainte de « room » est appliquée via les métadonnées des tiroirs avant la recherche vectorielle ; les tiroirs de tokenisation et d’analyse linguistique sont donc exclus de cette recherche.
Recherche de termes exacts
L’interface CLI de MemPalace combine la similarité sémantique avec les signaux BM25 lors du classement des candidats à la recherche vectorielle. Les noms exacts de configuration et de fonctionnalités peuvent donc améliorer le classement sans passer à un mode de recherche CLI distinct.
mempalace \
--palace "$PALACE_DIR" \
search "language_identifier tokenizer" \
--backend milvus \
--wing milvus_analyzer_docs \
--room tokenizer \
--results 3
Résultats de référence (les scores peuvent varier) :
Results for: "language_identifier tokenizer"
Wing: milvus_analyzer_docs
Room: tokenizer
[1] milvus_analyzer_docs / tokenizer
Source: language-identifier.md
Match: cosine_sim=0.420 bm25=0.969
[2] milvus_analyzer_docs / tokenizer
Source: language-identifier.md
[3] milvus_analyzer_docs / tokenizer
Source: lindera-tokenizer.md
Les résultats devraient privilégier language-identifier.md, qui documente le tokeniseur language_identifier utilisé pour sélectionner les analyseurs en fonction de la langue détectée.
Inspecter les collections Milvus
MemPalace gère automatiquement son schéma Milvus. Pour vérifier ce qui a été stocké, enregistrez le script suivant sous le nom inspect_milvus.py. Il ouvre la même base de données Milvus Lite, inspecte les collections et compte les tiroirs par pièce :
import os
from collections import Counter
from pymilvus import MilvusClient
client = MilvusClient(uri=os.environ["MEMPALACE_MILVUS_LITE_PATH"])
for collection_name in sorted(client.list_collections()):
stats = client.get_collection_stats(collection_name)
schema = client.describe_collection(collection_name)
fields = [field["name"] for field in schema["fields"]]
print(f"{collection_name}: rows={stats['row_count']}, fields={fields}")
client.load_collection("mempalace_drawers")
rows = client.query(
collection_name="mempalace_drawers",
filter='metadata["wing"] == "milvus_analyzer_docs"',
limit=2000,
output_fields=["metadata"],
)
room_counts = Counter(row["metadata"]["room"] for row in rows)
print("Drawers by room:", dict(sorted(room_counts.items())))
Exécutez le script avec le même ensemble de dépendances facultatives que celui utilisé par l’interface CLI :
export MEMPALACE_MILVUS_LITE_PATH="$PALACE_DIR/milvus.db"
uv run --with "mempalace[milvus]" inspect_milvus.py
Exemple de sortie :
mempalace_closets: rows=74, fields=['id', 'document', 'metadata', 'vector', 'sparse']
mempalace_drawers: rows=473, fields=['id', 'document', 'metadata', 'vector', 'sparse']
Drawers by room: {'analyzer': 212, 'filter': 156, 'tokenizer': 105}
Pour l’instantané de documentation testé, le fichier mempalace_drawers contenait 473 lignes et le fichier mempalace_closets contenait 74 enregistrements de navigation interne. Le nombre de placards et de tiroirs n’a pas besoin de correspondre. Les métadonnées des tiroirs indiquaient 212 tiroirs dans analyzer, 156 dans filter et 105 dans tokenizer.
Cette inspection s’exécute dans un nouveau processus et rouvre la base de données créée par l’interface CLI, ce qui confirme également que les données sont conservées d’une commande à l’autre.
Facultatif : utiliser le serveur Milvus ou Zilliz Cloud
Pour un déploiement partagé, définissez les variables d’environnement de connexion Milvus avant d’exécuter les mêmes commandes de la CLI MemPalace. Ne les définissez pas pour utiliser la base de données Milvus Lite locale indiquée ci-dessus.
Pour le serveur Milvus :
export MEMPALACE_MILVUS_URI="http://localhost:19530"
export MEMPALACE_MILVUS_DB_NAME="default"
export MEMPALACE_MILVUS_NAMESPACE="team-memory"
Pour le cloud Zilliz :
export MEMPALACE_MILVUS_URI="https://your-cluster.api.region.zillizcloud.com"
export MEMPALACE_MILVUS_TOKEN="your-api-key"
export MEMPALACE_MILVUS_DB_NAME="default"
export MEMPALACE_MILVUS_NAMESPACE="team-memory"
Les commandes de bout en bout présentées dans ce tutoriel ont été validées avec Milvus Lite. Les paramètres de serveur et de cloud ci-dessus constituent des configurations de déploiement facultatives et n’étaient pas nécessaires pour la validation locale.
Conclusion
MemPalace offre aux agents un moyen structuré de conserver les connaissances relatives à un projet : une « aile » sépare le corpus, les « salles » définissent le périmètre au niveau des thèmes et les « tiroirs » conservent le texte source d’origine. Dans cet exemple, 31 pages de documentation Milvus étroitement liées deviennent des centaines de tiroirs consultables plutôt que quelques enregistrements manuscrits. Milvus assure le stockage persistant des vecteurs, des données clairsemées, du texte et des métadonnées derrière cette structure.
