{
  "markdown": "# Datacron\n\n> Local MCP server to query and maintain a Markdown vault from Claude, Codex, Gemini, or\n> another stdio MCP client, without sending the whole vault into the context.\n\n<!-- mcp-name: io.github.VBlackJack/datacron -->\n\n[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![Python: 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue)](pyproject.toml)\n[![MCP: local stdio](https://img.shields.io/badge/MCP-local_stdio-purple)](#mcp-tools)\n[![CI](https://github.com/VBlackJack/datacron/actions/workflows/ci.yml/badge.svg)](https://github.com/VBlackJack/datacron/actions/workflows/ci.yml)\n\n**English** | [Français](README.fr.md)\n\n## What can you do with Datacron?\n\nRecover project context, prepare for a conversation, and keep track of commitments.\nDatacron gives your assistant durable memory in readable, editable Markdown. Your notes\nremain usable independently of the client you choose.\n\n| Need | Example request to your assistant |\n|---|---|\n| Resume a project | \"Where did we leave off? Find the decisions and next actions.\" |\n| Prepare a meeting | \"Summarize our recent conversations and open points, with sources.\" |\n| Remember a person | \"Who is this person, how have we interacted, and what should we follow up on?\" |\n| Track objectives | \"Find the commitments and achievements relevant to my next review.\" |\n| Preserve a reliable record | \"Save this decision, link it to the project, and verify that it was stored.\" |\n\nThe assistant orchestrates these requests using the available tools and granted permissions.\nA shared protocol guides reading, people updates, and write verification. Ambiguous identities\nrequire clarification; storing a deadline does not schedule a reminder.\n[Explore daily follow-up](docs/en/memory-discipline.md).\n\n**Start here:** [install](#installation) · [first session](#first-session) ·\n[user guide](docs/en/user-guide.md) · [MCP reference](#mcp-tools) ·\n[privacy](#privacy-and-security).\n\n## Installation\n\n### Windows: one double-click installer\n\nThe easiest way on Windows: download `Datacron-Setup.exe` from the\n[latest Release](https://github.com/VBlackJack/datacron/releases/latest), double-click it,\nand pick your vault. No Python, no terminal, no administrator rights; Datacron registers\nitself with your AI clients automatically. Full guide:\n[Windows installation](docs/en/installation-windows.md).\n\n### Python: from PyPI\n\n```bash\npython -m pip install datacron\ndatacron setup\n```\n\n### From source\n\nFrom a clone of the repository:\n\n```bash\npython -m pip install -e \".[dev]\"\n```\n\nOr, to install only the application:\n\n```bash\npython -m pip install -e .\n```\n\nRuntime prerequisites:\n\n- Python 3.11+\n- `ripgrep` available on the `PATH` for `search_regex`\n- a folder of Markdown notes\n- a supported stdio MCP client, such as Claude Desktop, Codex CLI, or Gemini CLI\n\n## First session\n\n1. Choose your notes folder with the installer or `datacron setup`.\n2. Reconnect Datacron in your MCP client to load the tools and instructions.\n3. Ask: \"Find the notes for my project and summarize its status with sources.\"\n\nFor memory sessions, `session_context` returns bounded context and the shared protocol.\n`prepare_follow_up` prepares sourced updates; existing writers apply them according to\npermissions. `get_follow_up` retrieves the latest structured revisions. Existing prose notes\nremain readable and are not automatically converted.\n\nThe server operates locally. Your client may send returned excerpts to its model provider;\nsee [privacy and security](#privacy-and-security).\n\n## Quick start\n\nThe easy path - one command detects your AI clients, initializes the vault, indexes it, and\nregisters Datacron everywhere:\n\n```bash\ndatacron setup            # interactive; add --yes for all defaults\n```\n\nSee the [installation guide](docs/en/setup.md) for options (`--client`, `--scope`, writing,\ndurability). Or step by step:\n\n```bash\ndatacron init /path/to/vault\ndatacron index --vault /path/to/vault\ndatacron status --vault /path/to/vault\ndatacron mcp install --client claude-desktop --vault /path/to/vault\n```\n\nThe `mcp install` subcommand above is dedicated to Claude Desktop. For Codex CLI, Gemini CLI,\nAntigravity, LM Studio, Cursor, and the other clients, use multi-client setup with\n`datacron setup --client <identifier>` or auto-detection with `--client all`.\n\n### Add to LM Studio\n\nLM Studio 0.3.17+ has one user configuration and no project scope. The preferred command is:\n\n```bash\ndatacron setup --yes --vault \"VAULT_PATH\" --client lmstudio --scope user\n```\n\nFor a Python installation where `datacron-mcp` is on `PATH`, the equivalent read-only\nconfiguration can also be imported with this official deeplink:\n\n[Add to LM Studio](lmstudio://add_mcp?name=datacron&config=eyJjb21tYW5kIjoiZGF0YWNyb24tbWNwIiwiYXJncyI6W10sImVudiI6eyJEQVRBQ1JPTl9WQVVMVF9ST09UIjoiPFlPVVJfVkFVTFQ%2BIiwiREFUQUNST05fUkVBRF9QQVRIUyI6IjxZT1VSX1ZBVUxUPiIsIkRBVEFDUk9OX0RVUkFCSUxJVFkiOiJiZXN0LWVmZm9ydCJ9fQ%3D%3D)\n\nThe link imports this example. Open LM Studio's MCP editor and replace both\n`<YOUR_VAULT>` placeholders before starting the server:\n\n```json\n{\n  \"mcpServers\": {\n    \"datacron\": {\n      \"command\": \"datacron-mcp\",\n      \"args\": [],\n      \"env\": {\n        \"DATACRON_VAULT_ROOT\": \"<YOUR_VAULT>\",\n        \"DATACRON_READ_PATHS\": \"<YOUR_VAULT>\",\n        \"DATACRON_DURABILITY\": \"best-effort\"\n      }\n    }\n  }\n}\n```\n\nThe example does not enable write tools. CLI setup is safer for packaged installations\nbecause it writes the actual executable path automatically.\n\nRestart the configured client or clients after installation.\n\nTo run the server manually:\n\n```bash\ndatacron mcp serve --vault /path/to/vault\n```\n\nThe direct script entry used by the installer is also available:\n\n```bash\ndatacron-mcp\n```\n\n`datacron-mcp` reads the vault from `DATACRON_VAULT_ROOT`.\n\n## Configuration\n\n`datacron init` creates `.datacron/VAULT.yaml`. That file can carry vault-local\nconfiguration, notably query expansion:\n\n```yaml\nquery_expansion:\n  supervision: [monitoring]\n  sauvegarde: [backup]\n  restauration: [restore]\n  chiffrement: [encryption]\n  sécurité: [security]\n  validité: [validity]\n  certificat: [certificate]\n```\n\nUseful environment variables:\n\n| Variable | Default | Role |\n|---|---:|---|\n| `DATACRON_VAULT_ROOT` | unset | fallback after `--vault`; the current directory is accepted only when it contains `.datacron/VAULT.yaml` |\n| `DATACRON_READ_PATHS` | empty | read allowlist; client setup sets it to the vault |\n| `DATACRON_WRITE_PATHS` | empty | write allowlist; empty = write tools disabled |\n| `DATACRON_MAX_RESULT_COUNT` | `20` | maximum number of results returned |\n| `DATACRON_MAX_RESULT_TOKENS` | `8000` | token budget for search results |\n| `DATACRON_REPAIR_MIN_INTERVAL_SECONDS` | `30` | minimum interval between repair-on-read sweeps; `0` = every read |\n| `DATACRON_GET_NOTE_MAX_TOKENS` | `25000` | budget for `get_note(format=\"full\")` |\n| `DATACRON_CHUNK_MAX_TOKENS` | `1024` | target maximum chunk size |\n| `DATACRON_RIPGREP_PATH` | `rg` | ripgrep binary |\n\nPath lists use the OS separator (`:` on Unix, `;` on Windows).\n\n## Writing\n\nWrites are deliberately OFF by default. Without `DATACRON_WRITE_PATHS`, write tools return a\nclear error and create no file.\n\nTo enable writing to a specific subfolder:\n\n```powershell\n$env:DATACRON_VAULT_ROOT = \"G:\\_DATA\"\n$env:DATACRON_READ_PATHS = \"G:\\_DATA\"\n$env:DATACRON_WRITE_PATHS = \"G:\\_DATA\\_memory\"\ndatacron mcp serve --vault G:\\_DATA\n```\n\n`datacron setup` can also apply the allowlist machine-wide (user environment\nvariable, opt-in) so every MCP client inherits it; default: `_memory`, `_drafts`,\n`_journal`. See the [setup guide](docs/en/setup.md).\n\nAvailable write tools:\n\n- `create_note_ai`: creates a typed Markdown note, without overwrite.\n- `append_journal`: adds an entry under a heading of an existing note.\n- `set_frontmatter`: updates lifecycle fields and the `rejected` options list without modifying the Markdown body.\n- `patch_note_preamble`: replaces or removes the Markdown preamble before the first recognized Markdown heading (ATX or Setext), with mandatory CAS control.\n- `patch_note_section`: replaces the content under an existing heading with CAS control.\n- `delete_note_section`: explicitly deletes an H2-H6 section (ATX or Setext) and its subtree.\n- `rename_note_section`: renames only the title of an H2-H6 section (ATX or Setext).\n- `revert_note`: restores the exact bytes of a version kept in history.\n- `apply_organization_manifest`: validates and then applies a local content-addressed bundle\n  after confirmation bound to the exact admitted organization pre-state.\n\nGuarantees:\n\n- strict note confinement within `DATACRON_WRITE_PATHS`; organization-batch note sources and\n  targets must also stay inside the unchanged live `organization.scope` and pass the live\n  note-admission policy, including exclusions\n- two internal exact-CAS targets for an organization batch: `.datacron/VAULT.yaml`, only to change\n  the top-level `organization` mapping without changing `organization.scope`, and\n  `.datacron/ulids.json`, only when Datacron derives the key migration required by a\n  `move_replace_exact`\n- atomic overwrite via temporary file + `os.replace`\n- content-addressed history before modifying an existing note\n- synchronous `reconcile()` after a normal write; immediate searchability is guaranteed only when\n  reconciliation succeeds\n- local audit log\n- for an organization manifest: crash-consistent recovery and atomic replacement of each file;\n  simultaneous visibility across several paths is not guaranteed\n\nConcurrent multi-machine mode is not supported for writes: keep a single-writer rule on the\nvault.\n\nFor `apply_organization_manifest`, also stop every other Datacron client and server during the\nmaintenance window. Before applying, keep a verified byte-exact backup outside the vault of the\naffected notes and the complete `.datacron` directory until every post-commit check is green. Call\n`mode=\"validate\"` first, review the bounded hashes it returns, then reuse\nthe exact `confirmation_token` with `mode=\"apply\"`. The token binds the manifest and payloads, all\nadmitted Markdown notes inside `organization.scope`, the exact vault configuration and identity\nsidecars, and the projected report. It deliberately does not bind unrelated note bytes outside\n`organization.scope`. A change to any authenticated component invalidates the confirmation before\nmutation. `history_mode=full` is required at validation time. If Datacron derives identity-sidecar\ncase-collision cleanup, also review `identity_sidecar_case_canonicalization_count` and its\ncontent-free SHA-256 before applying; both proofs are token-bound and retained in the durable\nreceipt.\nAn existing `replace_exact` or `move_replace_exact` source must carry its `id` in frontmatter; an\nidentity available only from the sidecar is unsupported by this v1 schema. If the batch is already\ndurably committed but index reconciliation or the planner oracle fails, the response says so\nexplicitly (`committed_index_incomplete` or `committed_report_mismatch`) and the same call can be\nretried with the same token.\nAn organization-batch blocker is reported by `datacron ops inspect` with a `pending_batch_` reason\nand both single-note repair actions unavailable; use the full offline rollback procedure in the\noperational-health guide rather than repairing or quarantining one member.\n\n## Available capabilities\n\nDatacron indexes a folder of Markdown notes, exposes a local MCP server, then returns the\nrelevant notes or chunks to the client instead of a full dump. The vault stays an ordinary\nMarkdown folder: Datacron only adds a `.datacron/` sidecar for the index, logs, internal\nULIDs, history, and the operation journal.\n\n| Surface | Current state |\n|---|---|\n| Vault reading | `list_notes`, `get_note`, resources `datacron://vault/map`, `vault/info`, `policy/active` |\n| Search | SQLite FTS5/BM25, FR↔EN query expansion, temporal re-rank, `ripgrep` via `search_regex` |\n| Local graph | Wikilinks and backlinks via `get_backlinks` |\n| Writing | 8 confined note tools + 1 organization batch, journaled and disabled by default without `DATACRON_WRITE_PATHS` |\n| MCP transport | Python MCP SDK v2 through `MCPServer`, local stdio only; modern `2026-07-28` protocol and legacy `2025-11-25` compatibility, with no HTTP listener |\n| Index | `datacron index` incremental, `datacron reindex` full, conditional repair on read |\n| Organization | Optional `organization` block in `VAULT.yaml`; `datacron reorganize --dry-run` measures the gap read-only, `apply_organization_manifest` applies |\n| Evaluation | `datacron eval` over the real MCP pipeline: recall@k, MRR, nDCG, freshness, latency, and payload tokens |\n| Guided setup | `datacron setup`: init + index + MCP registration in one command |\n| Clients | Auto-detect and register via `datacron setup --client all`: Claude Desktop, Claude Code, Cursor, Gemini CLI, Antigravity, LM Studio, Codex CLI, Windsurf, VS Code |\n| Daily memory | `session_context`, `prepare_follow_up`, `get_follow_up`: bounded context, sourced follow-up, and structured state |\n| Memory protocol | Shared versioned server/client contract; `protocol status` checks distribution, not model behavior |\n| Distribution | Windows installer (`Datacron-Setup.exe`), standalone executable (PyInstaller) with no Python required, or installation from source |\n\n## MCP Tools\n\n### Reading\n\n| Tool | Description |\n|---|---|\n| `session_context` | Bounded session context and versioned common protocol. |\n| `prepare_follow_up` | Prepare sourced follow-up plans without writing. |\n| `get_follow_up` | Latest structured follow-up revisions with snapshot-bound pagination. |\n| `list_notes` | returns a paginated list, filterable by folder, tags, and frontmatter key/value pairs, with ULID, title, tags, aliases, and dates |\n| `get_note` | reads a note by ULID, chunk id, or relative path, as paginated content, chunk, or heading outline |\n| `search_text` | runs a BM25 search on the FTS5 index with ranked snippets and stale notes demoted by default |\n| `search_regex` | runs a regex search via ripgrep and resolves the found lines to indexed chunks |\n| `get_backlinks` | returns chunks whose wikilinks target a ULID or a resolved alias |\n\n### Writing\n\n| Tool | Description |\n|---|---|\n| `create_note_ai` | creates a new typed `_memory` note, confined to allowed paths, without overwrite and with a durable journal |\n| `append_journal` | adds a Markdown entry under a heading, with confinement, exact history, and atomic write |\n| `set_frontmatter` | updates only the lifecycle fields, the `rejected` list, and the `updated` date, preserving the Markdown body |\n| `patch_note_preamble` | replaces or removes the preamble before the first recognized Markdown heading (ATX or Setext), with mandatory CAS and suffix preservation |\n| `patch_note_section` | replaces the content of an existing heading with CAS, exact history, and preservation of other sections |\n| `delete_note_section` | explicitly deletes an H2-H6 section (ATX or Setext) and its subtree, with optional CAS and exact history |\n| `rename_note_section` | renames the title of an H2-H6 section (ATX or Setext) without modifying its content or subtree |\n| `revert_note` | restores a note from its content-addressed history; the operation stays durable, reversible, and audited |\n| `apply_organization_manifest` | validates a local content-addressed bundle containing at least one exact note operation and/or an exact `organization` configuration replacement, then applies its declared members and any required derived ULID-sidecar migration under CAS; application is journaled and crash-consistent |\n\n### Operational\n\n| Tool | Description |\n|---|---|\n| `get_health` | returns the real state of index freshness, integrity, checksum, durability, and invariants |\n| `get_note_history` | lists the committed operation metadata of a note without reading historical content or modifying the journal |\n| `audit_query` | queries operation metadata by period, tool, or note without modifying the journal or the vault |\n\n### Advisory (experimental)\n\n| Tool | Description |\n|---|---|\n| `contradiction_scan` | live, deterministic, bounded scan of contradictions/refinements between sections; proposes and confirms an explicit CAS call read-only, without ever writing automatically |\n\nMCP resources:\n\n- `datacron://vault/map`\n- `datacron://vault/info`\n- `datacron://policy/active`\n\n## Search\n\n`search_text` combines several signals:\n\n- FTS5/BM25 for the base lexical score\n- FR↔EN query expansion configured in `VAULT.yaml`\n- conservative temporal re-rank:\n  - a note referenced in another note's `supersedes` is strongly demoted\n  - `confidence: low` and `confidence: needs_verification` apply a light penalty\n  - `include_superseded=true` brings historical notes back up\n\n`search_regex` stays literal: it applies neither query expansion nor temporal re-rank.\n\n<details>\n<summary>Historical search measurements - July 17, 2026</summary>\n\nThese measurements cover 19 questions and one configuration. They are not a benchmark of\nthe current release or a guarantee for another vault.\n\nLocal measurement of the `tool/impl` pipeline actually received by the agent, 19 questions,\n8k-token / 20-result configuration, July 17, 2026:\n\n```text\nrecall@5       0.89\nrecall@10      0.95\nrecall@20      0.95\nMRR            0.73\nnDCG@10        0.79\nlatency p50    57 ms\nlatency p95    276 ms\npayload tokens 90567\n```\n\nOn this historical set, tool-level recall@5 matched the BM25 store. Use `datacron eval`\nwith a suitable question set to measure behavior on your own notes.\n\n</details>\n\n## Privacy and security\n\n- Datacron does no telemetry.\n- Datacron calls no cloud LLM.\n- The MCP client, for example Claude, Codex, or Gemini, may send the chunks that Datacron\n  returns to its provider. Datacron does not send it the full vault.\n- Content returned to clients is wrapped in `<vault_content>...</vault_content>`.\n- Results are bounded by count and by token budget.\n- Filesystem access is confined by `DATACRON_READ_PATHS` and `DATACRON_WRITE_PATHS`.\n- MCP operations are audited in the local logs.\n\n## CLI commands\n\n```bash\ndatacron setup                      # guided path: init + index + client config\ndatacron setup --yes                # all defaults, no prompts\ndatacron setup --client all --scope both --vault /path/to/vault\ndatacron setup --protocol           # also install client memory rules\ndatacron protocol install --client all\ndatacron protocol status --client all --scope user\ndatacron init /path/to/vault\ndatacron status --vault /path/to/vault\ndatacron index --vault /path/to/vault\ndatacron reindex --vault /path/to/vault\ndatacron scrub-init --vault /path/to/vault\ndatacron scrub --vault /path/to/vault\ndatacron reorganize --vault /path/to/vault --dry-run          # measure organization, read-only\ndatacron reorganize --vault /path/to/vault --dry-run --json   # stable machine-readable report\ndatacron eval --questions examples/eval-questions.example.yaml --vault /path/to/vault\ndatacron eval --questions local/golden.yaml --vault /path/to/vault --save-baseline\ndatacron eval --questions local/golden.yaml --vault /path/to/vault --compare --json\ndatacron mcp serve --vault /path/to/vault\ndatacron mcp install --client claude-desktop --vault /path/to/vault  # Claude Desktop only\ndatacron unregister --client all --scope both --vault /path/to/vault\ndatacron protocol uninstall --client all\n```\n\n## Current limitations\n\n- Lexical search only: no vector search or embeddings.\n- No autonomous agent: the MCP client orchestrates.\n- No GUI.\n- No concurrent multi-machine writes.\n- Client detection in `datacron setup` is best-effort (a config directory or a binary on the\n  `PATH`); an install in a non-standard location may be missed and can then be configured by\n  hand.\n\n## Documentation\n\nFull index: [docs/en/index.md](docs/en/index.md) | [Index français](docs/fr/index.md).\n\nTo get started:\n\n- [Installation and configuration guide](docs/en/setup.md)\n- [Use Datacron with Ollama](docs/en/ollama.md)\n- [Frequently asked questions](docs/en/faq.md)\n- [User guide](docs/en/user-guide.md)\n- [Daily memory, people, and commitments](docs/en/memory-discipline.md)\n\nTechnical references:\n\n- [Vault conventions (SPEC)](docs/en/spec.md)\n- [Vault organization](docs/en/organization.md)\n- [Architecture and public surface](docs/en/architecture.md)\n- [Security boundary](docs/en/security-boundary.md)\n- [Integrity scrubber](docs/en/integrity-scrubber.md)\n- [Operational health and durability](docs/en/operational-health.md)\n- [Freshness contract](docs/en/freshness-contract-v1.md)\n\n## Development\n\nCI runs the invariants and the entire regression suite on Linux/Python 3.12 for changes limited to the READMEs, CHANGELOG, and Markdown pages under `docs/fr/` or `docs/en/`. All other changes retain the six Linux/Windows and Python 3.11-3.13 combinations. Publications require the full matrix, as do empty or unverifiable diffs. ShellCheck, the dependency audit, and the required `Quality gate` remain active in both paths. The first push of a new branch also uses the full matrix because no previous comparison point is available.\n\n```bash\npython -m pip install -e \".[dev]\"\nruff check .\nruff format --check .\nmypy\npytest\n```\n\n## License\n\nCopyright 2026 Julien Bombled.\n\nLicensed under the [Apache License, Version 2.0](LICENSE).\n\n[Reliable writes and quality gates](docs/en/improvements.md)\n",
  "bytes": 21458,
  "sha": "6a9c5a56c8049aa0d0cab25e2a8b700c66de23f37113d9039ab2b536cbc6074c",
  "repo_slug": "vblackjack/datacron",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_vblackjack_datacron_a7869155/readme"
}