Datacron

Serveur MCP local pour interroger et maintenir un vault Markdown depuis Claude, Codex, Gemini ou un autre client MCP stdio, sans envoyer tout le vault dans le contexte.

Français | English

À quoi sert Datacron ?

Retrouver le contexte d'un projet, préparer un échange et garder la trace des engagements : Datacron donne à ton assistant accès à une mémoire durable, lisible et modifiable en Markdown. Les notes restent utilisables indépendamment du client choisi.

L'assistant orchestre ces demandes avec les outils disponibles et les droits accordés. Le protocole commun guide la lecture, l'enrichissement des fiches personnes et la vérification des écritures. Une identité ambiguë demande clarification ; une échéance enregistrée ne programme pas de rappel. Découvrir le suivi quotidien.

Commencer : installer · première session · guide utilisateur · référence MCP · vie privée.

Installation

Windows : installeur en un double-clic

Le plus simple sous Windows : télécharge Datacron-Setup.exe depuis la dernière Release, double-clique, et choisis ton vault. Aucun Python, aucun terminal, aucun droit administrateur ; Datacron s'enregistre automatiquement dans tes clients IA. Guide détaillé : Installation sous Windows.

Python : depuis PyPI

python -m pip install datacron
datacron setup

Depuis les sources

Depuis un clone du repo :

python -m pip install -e ".[dev]"

Ou, pour installer seulement l'application :

python -m pip install -e .

Prérequis runtime :

• Python 3.11+
• ripgrep disponible dans le PATH pour search_regex
• un dossier de notes Markdown
• un client MCP stdio pris en charge, par exemple Claude Desktop, Codex CLI ou Gemini CLI

Première session

1. Choisis ton dossier de notes avec l'installeur ou datacron setup.
2. Reconnecte Datacron dans ton client MCP pour charger les outils et les instructions.
3. Demande : « Retrouve les notes de mon projet et résume son état avec les sources. »

Pour les sessions de mémoire, session_context fournit un contexte borné et le protocole commun. prepare_follow_up prépare les mises à jour sourcées ; les outils d'écriture les appliquent selon les permissions. get_follow_up retrouve les dernières révisions structurées. Les anciennes notes en prose restent à consulter ; elles ne sont pas converties automatiquement.

Le serveur travaille localement. Ton client peut transmettre les extraits retournés à son fournisseur de modèle : voir vie privée et sécurité.

Démarrage rapide

Le plus simple - une commande détecte tes clients IA, initialise le vault, l'indexe et enregistre Datacron partout :

datacron setup            # interactif ; ajoute --yes pour tout par défaut

Voir le guide d'installation pour les options (--client, --scope, écriture, durabilité). Ou étape par étape :

datacron init /path/to/vault
datacron index --vault /path/to/vault
datacron status --vault /path/to/vault
datacron mcp install --client claude-desktop --vault /path/to/vault

La sous-commande mcp install ci-dessus est dédiée à Claude Desktop. Pour Codex CLI, Gemini CLI, Antigravity, LM Studio, Cursor et les autres clients, utilise le setup multi-client avec datacron setup --client <identifiant> ou l'auto-détection avec --client all.

Ajouter Datacron à LM Studio

LM Studio 0.3.17+ possède une configuration utilisateur unique et aucun scope projet. La commande recommandée est :

datacron setup --yes --vault "CHEMIN_VAULT" --client lmstudio --scope user

Pour une installation Python où datacron-mcp est dans le PATH, la configuration équivalente en lecture seule peut aussi être importée avec ce deeplink officiel :

Add to LM Studio

Le lien importe cet exemple. Ouvre l'éditeur MCP de LM Studio et remplace les deux placeholders <YOUR_VAULT> avant de démarrer le serveur :

{
  "mcpServers": {
    "datacron": {
      "command": "datacron-mcp",
      "args": [],
      "env": {
        "DATACRON_VAULT_ROOT": "<YOUR_VAULT>",
        "DATACRON_READ_PATHS": "<YOUR_VAULT>",
        "DATACRON_DURABILITY": "best-effort"
      }
    }
  }
}

L'exemple n'active pas les outils d'écriture. Le setup CLI est plus sûr pour les installations packagées, car il écrit automatiquement le vrai chemin de l'exécutable.

Redémarre le ou les clients configurés après l'installation.

Pour lancer le serveur manuellement :

datacron mcp serve --vault /path/to/vault

L'entrée script directe utilisée par l'installateur est aussi disponible :

datacron-mcp

datacron-mcp lit le vault depuis DATACRON_VAULT_ROOT.

Configuration

datacron init crée .datacron/VAULT.yaml. Ce fichier peut porter la configuration vault-local, notamment la query-expansion :

query_expansion:
  supervision: [monitoring]
  sauvegarde: [backup]
  restauration: [restore]
  chiffrement: [encryption]
  sécurité: [security]
  validité: [validity]
  certificat: [certificate]

Variables d'environnement utiles :

Les listes de chemins utilisent le séparateur de l'OS (: sous Unix, ; sous Windows).

Écriture

Les writes sont volontairement OFF par défaut. Sans DATACRON_WRITE_PATHS, les tools d'écriture renvoient une erreur claire et ne créent aucun fichier.

Pour activer l'écriture sur un sous-dossier précis :

$env:DATACRON_VAULT_ROOT = "G:\_DATA"
$env:DATACRON_READ_PATHS = "G:\_DATA"
$env:DATACRON_WRITE_PATHS = "G:\_DATA\_memory"
datacron mcp serve --vault G:\_DATA

datacron setup peut aussi poser l'allowlist au niveau du poste (variable d'environnement utilisateur, opt-in) pour que tous les clients MCP en héritent ; défaut : _memory, _drafts, _journal. Voir le guide d'installation.

Tools d'écriture disponibles :

• create_note_ai : crée une note Markdown typée, sans overwrite.
• append_journal : ajoute une entrée sous un heading d'une note existante.
• set_frontmatter : met à jour les champs de cycle de vie et la liste rejected (options écartées) sans modifier le corps Markdown.
• patch_note_preamble : remplace ou supprime le préambule Markdown avant le premier titre Markdown reconnu (ATX ou Setext), avec contrôle CAS obligatoire.
• patch_note_section : remplace le contenu sous un heading existant avec contrôle CAS.
• delete_note_section : supprime explicitement une section H2-H6 (ATX ou Setext) et son sous-arbre.
• rename_note_section : renomme uniquement le titre d'une section H2-H6 (ATX ou Setext).
• revert_note : restaure les octets exacts d'une version conservée dans l'historique.
• apply_organization_manifest : valide puis applique un bundle local adressé par contenu, après confirmation liée au pré-état exact admis de l'organisation.

Garanties :

• confinement strict des notes dans DATACRON_WRITE_PATHS ; les sources et cibles notes d'un batch d'organisation doivent aussi rester dans le organization.scope live inchangé et passer la politique live d'admission des notes, exclusions comprises
• deux cibles internes sous CAS exact pour un batch d'organisation : .datacron/VAULT.yaml, seulement pour modifier le mapping top-level organization sans changer organization.scope, et .datacron/ulids.json, seulement quand Datacron dérive la migration de clé imposée par un move_replace_exact
• overwrite atomique via fichier temporaire + os.replace
• historique adressé par contenu avant modification d'une note existante
• reconcile() synchrone après un write normal ; la disponibilité immédiate dans la recherche n'est garantie que si cette réconciliation réussit
• audit log local
• pour un manifeste d'organisation : transaction récupérable après crash et remplacement atomique de chaque fichier ; la visibilité simultanée de plusieurs chemins n'est pas garantie

Le mode concurrent multi-machines n'est pas supporté pour les écritures : garde une règle single-writer sur le vault.

Pour apply_organization_manifest, arrête aussi les autres clients et serveurs Datacron pendant la fenêtre de maintenance. Avant l'application, conserve hors du vault une sauvegarde exacte aux octets et vérifiée des notes affectées et du répertoire .datacron complet jusqu'à ce que tous les contrôles post-commit soient verts. Appelle d'abord mode="validate", contrôle les hashes bornés retournés, puis réutilise l'exact confirmation_token avec mode="apply". Le token lie le manifeste et ses payloads, toutes les notes Markdown admises dans organization.scope, la configuration exacte du vault et les sidecars d'identité, ainsi que le rapport projeté. Il ne lie délibérément pas les octets de notes sans rapport situées hors de organization.scope. Toute modification d'un composant authentifié invalide la confirmation avant mutation. history_mode=full est requis dès la validation. Si Datacron dérive un nettoyage de collisions de casse du sidecar, contrôle aussi identity_sidecar_case_canonicalization_count et son SHA-256 content-free avant d'appliquer ; ces deux preuves sont liées au token et conservées dans le reçu durable. Une source existante de replace_exact ou move_replace_exact doit porter son id dans le frontmatter ; une identité disponible uniquement dans le sidecar n'est pas prise en charge par ce schéma v1. Si le batch a déjà atteint son commit durable mais que la réconciliation ou l'oracle planner échoue, la réponse le dit explicitement (committed_index_incomplete ou committed_report_mismatch) et le même appel peut être rejoué avec le même token. Un blocage de batch d'organisation est rapporté par datacron ops inspect avec une raison pending_batch_ et les deux réparations limitées à une note indisponibles ; applique alors le rollback hors ligne complet du guide de santé opérationnelle, sans réparer ni isoler un seul membre.

Fonctions disponibles

Datacron indexe un dossier de notes Markdown, expose un serveur MCP local, puis renvoie au client les notes ou chunks pertinents au lieu d'un dump complet. Le vault reste un dossier Markdown normal : Datacron ajoute seulement un sidecar .datacron/ pour l'index, les logs, les ULID internes, l'historique et le journal d'opérations.

MCP Tools

Lecture

Écriture

Opérationnel

Advisory (expérimental)

Resources MCP :

• datacron://vault/map
• datacron://vault/info
• datacron://policy/active

Recherche

search_text combine plusieurs signaux :

• FTS5/BM25 pour le score lexical de base
• query-expansion FR↔EN configurée dans VAULT.yaml
• re-rank temporel conservateur :
  • une note citée dans le supersedes d'une autre est fortement démotée
  • confidence: low et confidence: needs_verification appliquent une pénalité légère
  • include_superseded=true permet de remonter les notes historiques

search_regex reste littéral : il n'applique ni query-expansion ni re-rank temporel.

recall@5       0.89
recall@10      0.95
recall@20      0.95
MRR            0.73
nDCG@10        0.79
latence p50    57 ms
latence p95    276 ms
payload tokens 90567

Vie privée et sécurité

• Datacron ne fait pas de télémétrie.
• Datacron n'appelle pas de LLM cloud.
• Le client MCP, par exemple Claude, Codex ou Gemini, peut envoyer à son fournisseur les chunks que Datacron lui retourne. Datacron ne lui envoie pas le vault complet.
• Le contenu retourné aux clients est enveloppé dans <vault_content>...</vault_content>.
• Les résultats sont bornés par nombre et par budget token.
• Les accès filesystem sont confinés par DATACRON_READ_PATHS et DATACRON_WRITE_PATHS.
• Les opérations MCP sont auditées dans les logs locaux.

Commandes CLI

datacron setup                      # parcours guidé : init + index + config client
datacron setup --yes                # tout par défaut, sans question
datacron setup --client all --scope both --vault /path/to/vault
datacron setup --protocol           # installe aussi les règles mémoire des clients
datacron protocol install --client all
datacron protocol status --client all --scope user
datacron init /path/to/vault
datacron status --vault /path/to/vault
datacron index --vault /path/to/vault
datacron reindex --vault /path/to/vault
datacron scrub-init --vault /path/to/vault
datacron scrub --vault /path/to/vault
datacron reorganize --vault /path/to/vault --dry-run          # mesure l'organisation, lecture seule
datacron reorganize --vault /path/to/vault --dry-run --json   # rapport machine stable
datacron eval --questions examples/eval-questions.example.yaml --vault /path/to/vault
datacron eval --questions local/golden.yaml --vault /path/to/vault --save-baseline
datacron eval --questions local/golden.yaml --vault /path/to/vault --compare --json
datacron mcp serve --vault /path/to/vault
datacron mcp install --client claude-desktop --vault /path/to/vault  # dédié Claude Desktop
datacron unregister --client all --scope both --vault /path/to/vault
datacron protocol uninstall --client all

Limites actuelles

• Recherche lexicale : pas de recherche vectorielle ni d’embeddings.
• Pas d'agent autonome : le client MCP orchestre.
• Pas de GUI.
• Pas de writes concurrents multi-machines.
• La détection des clients par datacron setup est best-effort (présence d'un dossier de config ou d'un binaire sur le PATH) ; une installation dans un emplacement non standard peut être manquée et se configure alors à la main.

Documentation

Sommaire complet : docs/fr/index.md | English index.

Pour démarrer :

• Guide d'installation et de configuration
• Utiliser Datacron avec Ollama
• Questions fréquentes
• Guide utilisateur
• Mémoire quotidienne, personnes et engagements

Références techniques :

• Conventions du vault (SPEC)
• Organisation du vault
• Architecture et surface publique
• Frontière de sécurité
• Scrubber d'intégrité
• Santé opérationnelle et durabilité
• Contrat de fraîcheur

Développement

La CI exécute les invariants et toute la suite de régression sur Linux/Python 3.12 pour les changements limités aux README, au CHANGELOG et aux pages Markdown de docs/fr/ ou docs/en/. Tout autre changement conserve les six combinaisons Linux/Windows et Python 3.11–3.13. Les publications imposent la matrice complète ; un diff vide ou invérifiable aussi. ShellCheck, l’audit des dépendances et le contrôle obligatoire Quality gate restent actifs dans les deux parcours. La première poussée d’une nouvelle branche utilise également la matrice complète, faute de point de comparaison précédent.

python -m pip install -e ".[dev]"
ruff check .
ruff format --check .
mypy
pytest

Licence

Copyright 2026 Julien Bombled.

Licensed under the Apache License, Version 2.0.

Écritures fiables et contrôles qualité