Engram

L'hippocampe local de la trilogie : une mémoire opérationnelle partagée qui reste explicable, bornée et consolidée vers Datacron après revue humaine.

Français | English

Engram est un serveur MCP local-first qui capture des souvenirs de travail et restitue des capsules compactes, classées selon leur confiance. Dans la trilogie, Datacron est le carnet Markdown durable et la source de vérité, Cortex est le bibliothécaire de documentation large, et Engram est l'hippocampe : il maintient la mémoire opérationnelle entre clients puis propose sa consolidation vers Datacron.

Choisir son parcours

Le reste de ce README est une référence de release. Il n'est pas nécessaire de tout lire pour commencer. Documentation vérifiée avec Engram 2026.0730.02 le 2026-08-13.

Related MCP server: mindmap-mcp-server

Ce qui est en place

Installation

Prérequis :

• Git pour l'installation depuis les sources ;

• Python 3.13 ou plus récent ;

• uv 0.12.1 ou plus récent — exigé, et non simplement conseillé : c'est la première version qui connaît le build 3.14.6, et l'intégration continue épingle uv==0.12.1 sur ses deux legs, Windows et Linux ;

• SQLite 3.51.3 ou plus récent dans le runtime Python.

Le plancher SQLite est dur. Les versions 3.7.0 à 3.51.2 sont affectées par le bug WAL-reset documenté par SQLite. Engram vérifie sqlite3.sqlite_version à l'ouverture et refuse un runtime trop ancien ; le refus nomme engram doctor et l'URL de documentation, qui indiquent tous deux la réparation applicable à la machine devant vous. Voir installation Windows pour installer la DLL SQLite 3.53.x officielle. La page SQLite décrit le bug WAL-reset et publie les binaires 3.53.3.

Identique sous Windows, macOS et Linux :

git clone https://github.com/VBlackJack/Engram.git
cd Engram
uv sync --python 3.14.6
uv run --python 3.14.6 engram init
uv run --python 3.14.6 engram doctor

engram init écrit engram.toml depuis la copie empaquetée dans la distribution : elle fonctionne depuis une installation par wheel comme depuis un checkout, et refuse de remplacer un fichier existant sauf avec --force. engram doctor rapporte ensuite l'interpréteur, le plancher SQLite, la configuration résolue, la base, le verrou, l'endpoint et le fichier de log — chacun avec la commande qui le répare.

Le paquet PyPI n'est pas publié. Avant la publication de cette release GitHub, utilisez le checkout source courant ; après publication, les artefacts wheel/sdist attachés à la release sont aussi utilisables.

Démarrage rapide

uv run --python 3.14.6 engram serve

Le point MCP par défaut est http://127.0.0.1:8377/mcp. Engram refuse toute adresse d'écoute qui n'est pas un literal IP loopback : le serveur n'implémente pas d'authentification réseau.

engram serve dure exactement aussi longtemps que son terminal. Pour garder Engram après une fermeture de session :

Arrêtez le démon depuis n'importe quelle installation avec uv run --python 3.14.6 engram stop, qui lui demande de fermer la base, attend sur le verrou de propriété et rapporte s'il s'est réellement arrêté.

Connectez un client en une commande, avec l'endpoint de votre propre configuration :

uv run --python 3.14.6 engram setup client claude --protocol

Remplacez claude par codex ou gemini. La commande écrit .mcp.json, ~/.codex/config.toml ou ~/.gemini/settings.json en fusionnant au lieu d'écraser, et --protocol ajoute le protocole client dans CLAUDE.md, AGENTS.md ou GEMINI.md. Les blocs exacts à écrire à la main sont dans le guide de mise en place.

Configuration

Engram charge engram.toml. ENGRAM_CONFIG peut sélectionner un autre fichier. Toute clé TOML peut être surchargée par ENGRAM_<SECTION>_<CLE> ; les chemins relatifs sont résolus depuis le dossier du fichier TOML.

Pour une variable de liste, ARGS suit le découpage shell et READ_PATHS/WRITE_PATHS utilisent le séparateur de chemins de l'OS. Le fichier complet et ses valeurs sûres sont dans engram.example.toml ; engram init écrit la même chose depuis la copie empaquetée. Les écritures Datacron restent désactivées si write_paths est vide, même si le processus parent définit DATACRON_WRITE_PATHS. Le transport local par défaut lance datacron mcp serve.

Outils MCP

Kinds acceptés : preference, decision, project_state, fact, episode. Le serveur attribue la provenance ; un client ne peut jamais déclarer lui-même une source human.

Sécurité et vie privée

• Toutes les données, l'index lexical, l'audit et les logs restent locaux.

• Aucun appel à un LLM cloud ni aucune télémétrie n'est implémenté.

• Les candidats d'un client sont quarantainés pour éviter qu'une affirmation non attestée ne devienne la vérité partagée.

• Le nom/version MCP est un espace de noms auto-déclaré, pas une authentification ni une frontière de confidentialité.

• Le mode hybride contacte uniquement l'endpoint d'embeddings explicitement configuré ; FTS est le mode par défaut.

• Les écritures Datacron passent par des allowlists sous _memory/, un chemin canonique déterministe et une relecture exacte.

• L'écoute directe est limitée aux literals IP loopback. Un proxy distant éventuel doit joindre Engram localement et fournir lui-même authentification, TLS et contrôle réseau.

Voir le modèle de sécurité complet.

Commandes CLI

engram --version
engram --debug serve
engram init
engram init --force
engram doctor
engram doctor --json
engram serve
engram stop
engram setup autostart --install
engram setup autostart --status
engram setup autostart --uninstall
engram setup client claude --protocol
engram setup client codex --print
engram setup client gemini --force
engram migrate
engram preflight
engram reindex
engram list --status quarantined
engram list --unclassified
engram classify ENTRY_ID --claim-key "topic/claim"
engram attest "Statement relu" fact user --subject-key "topic/key" --claim-key "topic/claim"
engram supersede --old OLD_ID --new NEW_ID
engram eval --mode both --out local/eval
engram consolidate --plan --out local/consolidation/plan.json
engram consolidate --apply local/consolidation/plan.json
engram consolidate --check-freshness

--config <chemin> est une option globale et se place avant la sous-commande.

Le bloc Codex écrit par cette commande omet délibérément la clé required : OpenAI la définit comme faisant échouer le démarrage de Codex quand le serveur ne peut pas s'initialiser, si bien qu'un courtier de mémoire simplement arrêté emporterait tout l'assistant avec lui.

consolidate --plan reste read-only pour Datacron, mais ancre les propositions immuables dans la base Engram. Éditez uniquement chaque decision du JSON (approve ou reject) avant --apply. Le plan est à usage unique : toute modification d'un autre champ ou toute relecture après apply est refusée et exige un nouveau plan. Un hash Datacron divergent produit stale, conserve le rapport et renvoie le code 6 ; il n'est jamais forcé. Actuellement, un résultat update reste visible avec sa cible et son diff dans le rapport, mais produit toujours skip : Engram ne patche aucune section tant que Datacron ne fournit pas un ancrage d'identité durable indépendamment vérifié. Chaque création cible un seul chemin canonique contenant l'ID candidat. Après une réponse d'écriture ambiguë, un nouveau plan ne réconcilie que le contenu canonique complet identique de ce chemin au lieu de créer un doublon. Arrêter le démon avec engram stop avant migrate, classify, attest, supersede, reindex ou consolidate, puis le redémarrer avant recall. Ces commandes prennent le même verrou OS que le démon et échouent clairement tant qu'il est actif ; list reste disponible via une connexion SQLite read-only. Pour une base existante, effectuer d'abord une sauvegarde SQLite cohérente, arrêter le démon, puis lancer engram preflight. Il garde le verrou writer offline, laisse la base source en lecture seule, copie son snapshot vers un stockage temporaire et y prouve la migration/reconstruction complète avant d'annoncer la compatibilité. Lancer ensuite engram migrate et inventorier engram list --unclassified. Relire chaque préférence, décision ou fait historique et lui attribuer explicitement sa famille avec engram classify ENTRY_ID --claim-key "topic/claim" ; ne jamais inférer ces clés en masse. Les commandes de confiance utilisent [attestation].default_actor, sauf si --actor est fourni. R3 ne tronque jamais les données qui dépassent ses nouveaux plafonds fixes : un preflight en échec nomme la première ligne à relire avec 2026.0730.01 avant de retenter. Si le preflight renvoie vector_rebuild_required: true et que le mode hybride est actif, lancer engram reindex après la migration. SQLite charge d'abord le schéma sous un plafond temporaire de 256 Kio, puis conserve un plafond de 8 Mio par valeur/ligne ; les snapshots de consolidation sont limités explicitement à 4 Mio UTF-8. Le preflight refuse les données historiques incompatibles sans les tronquer.

Les erreurs CLI connues n'affichent aucun traceback par défaut. Le code 2 signale l'usage ou la configuration, 3 une ressource locale indisponible (port, verrou de processus, base ou runtime SQLite), 4 une dépendance externe injoignable (Datacron ou endpoint d'embeddings), 5 une contention transitoire du store et 6 un rapport apply contenant des propositions failed ou stale. Utiliser le flag global --debug avant la commande, ou ENGRAM_DEBUG=1, uniquement pour obtenir un traceback.

Limites actuelles

• Engram ne voit pas passivement les conversations : chaque client doit appeler recall et remember selon le protocole documenté.

• Le transport est HTTP local. Le connecteur distant Claude Desktop exige une URL HTTPS publique ; Claude Code se connecte directement à localhost.

• Le mode hybride est expérimental et dépend d'un endpoint compatible OpenAI local. Il se dégrade explicitement vers FTS si le provider est indisponible ou renvoie un vecteur invalide, ou si le scan exact dépasse les plafonds fixes de candidats, dimensions ou octets. Une couverture vectorielle incomplète marque le rappel incomplet.

• La publication PyPI et la soumission au MCP Registry sont différées. Le manifeste est prêt pour le paquet et son endpoint HTTP local.

• Le FTS reste lexical : ses fallbacks bornés gèrent le bruit, l'ordre des termes et les préfixes, mais pas les paraphrases sans vocabulaire commun. Le rapport d'évaluation mesure séparément ces paraphrases pour éviter de confondre rappel lexical et rappel sémantique.

Documentation

Développement

uv sync --extra dev --python 3.14.6
uv run --python 3.14.6 ruff check .
uv run --python 3.14.6 ruff format --check .
uv run --python 3.14.6 mypy
uv run --python 3.14.6 pytest
uv build --python 3.14.6

Contribuer

Les portillons, les conventions de commit et la règle de miroir FR/EN de la documentation sont décrits dans CONTRIBUTING.md. Une faille se signale en privé, jamais dans une issue publique : voir SECURITY.md, qui décrit aussi le modèle de menace — endpoint en loopback seul, absence d'authentification sur le port, et confiance accordée uniquement par un geste humain.

Licence

Apache License 2.0. Copyright 2026 Julien Bombled. Voir LICENSE et les notices tiers.