Présentation

engrim est un moteur de mémoire épisodique universel, conçu pour les interfaces en ligne de commande d’intelligence artificielle. Il stocke les décisions, contraintes et états d’un projet dans une base SQLite locale (≈ 4 000 caractères de mémoire de travail) et permet de basculer entre plusieurs modèles – Gemini 3.8, Claude 3.7 Sonnet, GPT‑4o – sans perdre le contexte architectural. Le projet cite 105 sessions continues sur un système de trading algorithmique de 50 000 lignes, avec zéro régression sur 186 tests unitaires, démontrant la stabilité du mécanisme de persistance.

Le problème ciblé est la dilution d’attention lorsque les fenêtres de contexte dépassent le million de tokens : chaque tour de conversation augmente le coût et le risque d’amnésie. engrim remplace ce phénomène par un stockage curaté, limitant le rechargement de contexte à moins de 1 % de la fenêtre totale.

Architecture technique

Le cœur, version v1.3.0, se compose de trois sous‑modules : les Adapters & Hooks qui interceptent les appels des agents (Antigravity, Claude Code, Cursor/MCP), le Agent Provenance Engine qui consigne l’origine de chaque entrée (origin_agent), et le Hybrid Retrieval & Minder qui fusionne recherche lexicale (SQLite FTS5 bm25) et recherche vectorielle (embeddings statiques model2vec) via un algorithme de reciprocal‑rank fusion. Cette double voie garantit à la fois rapidité de recherche (index FTS5) et pertinence sémantique (cosine similarity).

Le stockage persistant repose sur un fichier ~/.engrim/memory.db contenant quatre tables : Memories (décisions, faits, retours), FTS5 (index texte avec stemmer Porter et triggers), Vector Embeddings (colonnes embedding pré‑calculées) et Flight Recorder Log (tour de dialogue et lignes d’action). La migration non destructive ajoute simplement la colonne origin_agent TEXT lors du premier accès.

Performances et limites

En production, plus de 153 000 tokens de travail ont été condensés en un pack actif de moins de 1 000 tokens, soit une réduction de 99 % du coût de rechargement à chaque redémarrage de session. Les tests montrent zéro perte de contexte lors de changements de modèle, même après plusieurs dizaines de milliers de lignes de code. Cependant, la capacité de mémoire curatée reste bornée à 4 000 caractères ; au‑delà, les agents doivent explicitement « recall » les entrées supplémentaires, ce qui introduit une latence dépendante de la taille de la base SQLite. De plus, les embeddings sont statiques : toute évolution du modèle sous‑jacent nécessite une recomputation manuelle, limitant l’adaptabilité aux nouveaux vecteurs de représentation.

Le moteur repose sur un disque local, ce qui élimine les dépendances cloud mais impose des exigences de sauvegarde et de synchronisation pour les équipes distribuées. Enfin, la fusion hybride, bien que rapide (latence quasi‑nulle), ne garantit pas une couverture sémantique exhaustive lorsqu’une requête dépasse le vocabulaire indexé par bm25 ou les dimensions du vecteur pré‑calculé.

Déploiement et utilisation

L’installation se fait en une ligne :

pip install engrim

Le script engrim setup détecte automatiquement les environnements installés (Antigravity, Claude, Cursor) et crée les hooks nécessaires. Exemple de configuration MCP pour Windsurf :

{
  "mcpServers": {
    "engrim": {
      "command": "engrim",
      "args": ["serve", "--mcp"]
    }
  }
}

Une fois le serveur JSON‑RPC lancé (engrim serve --mcp), les agents communiquent via stdio, tandis que les logs sont redirigés vers stderr. Cette architecture sans dépendance externe facilite le déploiement sur des environnements de production à haute sécurité, où la persistance locale et la traçabilité des décisions sont essentielles.