Engram

L'hippocampe local de la trilogie : une memoire operationnelle partagee qui reste explicable, bornee et consolidee vers Datacron apres revue humaine.

Francais | English

Engram est un serveur MCP local-first qui capture des souvenirs de travail et restitue des capsules compactes, classees selon leur confiance. Dans la trilogie, Datacron est le carnet Markdown durable et la source de verite, Cortex est le bibliothecaire de documentation large, et Engram est l'hippocampe : il maintient la memoire operationnelle entre clients puis propose sa consolidation vers Datacron.

Choisir son parcours

Le reste de ce README est une reference de release. Il n'est pas necessaire de tout lire pour commencer. Documentation verifiee avec Engram 2026.0730.02 le 2026-07-30.

Related MCP server: mindmap-mcp-server

Ce qui est en place

Installation

Prerequis :

• Git pour l'installation depuis les sources ;

• Python 3.13 ou plus recent ;

• uv 0.12.1 ou plus recent recommande ;

• SQLite 3.51.3 ou plus recent dans le runtime Python.

Le plancher SQLite est dur. Les versions 3.7.0 a 3.51.2 sont affectees par le bug WAL-reset documente par SQLite. Engram verifie sqlite3.sqlite_version a l'ouverture et refuse un runtime trop ancien. Voir installation Windows pour installer la DLL SQLite 3.53.x officielle. La page SQLite decrit le bug WAL-reset et publie les binaires 3.53.3.

git clone https://github.com/VBlackJack/Engram.git
cd Engram
uv sync --python 3.14.6
uv run --python 3.14.6 python -c "import sqlite3; print(sqlite3.sqlite_version)"
if (Test-Path -LiteralPath "engram.toml") { throw "Existing Engram configuration: stop" }
if (Test-Path -LiteralPath "engram.db") { throw "Existing Engram database: stop" }
Copy-Item engram.example.toml engram.toml -ErrorAction Stop

Le paquet PyPI n'est pas publie. Avant la publication de cette release GitHub, utilisez le checkout source courant ; apres publication, les artefacts wheel/sdist attaches a la release sont aussi utilisables.

Demarrage rapide

uv run --python 3.14.6 engram serve

Le point MCP par defaut est http://127.0.0.1:8377/mcp. Engram refuse toute adresse d'ecoute qui n'est pas un literal IP loopback : le serveur n'implemente pas d'authentification reseau.

Ajoutez ensuite ce serveur a Claude Code, Codex ou Gemini, puis installez le protocole client. Les blocs de configuration exacts sont dans le guide de mise en place.

Configuration

Engram charge engram.toml. ENGRAM_CONFIG peut selectionner un autre fichier. Toute cle TOML peut etre surchargee par ENGRAM_<SECTION>_<CLE> ; les chemins relatifs sont resolus depuis le dossier du fichier TOML.

Pour une variable de liste, ARGS suit le decoupage shell et READ_PATHS/WRITE_PATHS utilisent le separateur de chemins de l'OS. Le fichier complet et ses valeurs sures sont dans engram.example.toml. Les ecritures Datacron restent desactivees si write_paths est vide, meme si le processus parent definit DATACRON_WRITE_PATHS. Le transport local par defaut lance datacron mcp serve.

Outils MCP

Kinds acceptes : preference, decision, project_state, fact, episode. Le serveur attribue la provenance ; un client ne peut jamais declarer lui-meme une source human.

Securite et vie privee

• Toutes les donnees, l'index lexical, l'audit et les logs restent locaux.

• Aucun appel a un LLM cloud ni aucune telemetrie n'est implemente.

• Les candidats d'un client sont quarantaines pour eviter qu'une affirmation non attestee ne devienne la verite partagee.

• Le nom/version MCP est un espace de noms auto-declare, pas une authentification ni une frontiere de confidentialite.

• Le mode hybride contacte uniquement l'endpoint d'embeddings explicitement configure ; FTS est le mode par defaut.

• Les ecritures Datacron passent par des allowlists sous _memory/, un chemin canonique deterministe et une relecture exacte.

• L'ecoute directe est limitee aux literals IP loopback. Un proxy distant eventuel doit joindre Engram localement et fournir lui-meme authentification, TLS et controle reseau.

Voir le modele de securite complet.

Commandes CLI

engram --version
engram --debug serve
engram serve
engram migrate
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

consolidate --plan reste read-only pour Datacron, mais ancre les propositions immuables dans la base Engram. Editez uniquement chaque decision du JSON (approve ou reject) avant --apply. Le plan est a usage unique : toute modification d'un autre champ ou toute relecture apres apply est refusee et exige un nouveau plan. Un hash Datacron divergent produit stale, conserve le rapport et renvoie le code 6 ; il n'est jamais force. Actuellement, un resultat 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'identite durable independamment verifie. Chaque creation cible un seul chemin canonique contenant l'ID candidat. Apres une reponse d'ecriture ambigue, un nouveau plan ne reconcilie que le contenu canonique complet identique de ce chemin au lieu de creer un doublon. Arreter le daemon avant migrate, classify, attest, supersede, reindex ou consolidate, puis le redemarrer avant recall. Ces commandes prennent le meme verrou OS que le daemon et echouent 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 coherente, arreter le daemon, 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 complete avant d'annoncer la compatibilite. Lancer ensuite engram migrate et inventorier engram list --unclassified. Relire chaque preference, decision ou fait historique et lui attribuer explicitement sa famille avec engram classify ENTRY_ID --claim-key "topic/claim" ; ne jamais inferer ces cles en masse. Les commandes de confiance utilisent [attestation].default_actor, sauf si --actor est fourni. R3 ne tronque jamais les donnees qui depassent ses nouveaux plafonds fixes : un preflight en echec nomme la premiere ligne a 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 apres la migration. SQLite charge d'abord le schema sous un plafond temporaire de 256 Kio, puis conserve un plafond de 8 Mio par valeur/ligne ; les snapshots de consolidation sont limites explicitement a 4 Mio UTF-8. Le preflight refuse les donnees historiques incompatibles sans les tronquer.

Les erreurs CLI connues n'affichent aucun traceback par defaut. Le code 2 signale l'usage ou la configuration, 3 une ressource locale indisponible (port, verrou de processus, base ou runtime SQLite), 4 une dependance 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 documente.

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

• Le mode hybride est experimental et depend d'un endpoint compatible OpenAI local. Il se degrade explicitement vers FTS si le provider est indisponible ou renvoie un vecteur invalide, ou si le scan exact depasse les plafonds fixes de candidats, dimensions ou octets. Une couverture vectorielle incomplete marque le rappel incomplet.

• La publication PyPI et la soumission au MCP Registry sont differees. Le manifeste est pret pour le paquet et son endpoint HTTP local.

• Le FTS reste lexical : ses fallbacks bornes gerent le bruit, l'ordre des termes et les prefixes, mais pas les paraphrases sans vocabulaire commun. Le rapport d'evaluation mesure separement ces paraphrases pour eviter de confondre rappel lexical et rappel semantique.

Documentation

Developpement

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

Licence

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