Datacron

# Datacron

> Local MCP server to query and maintain a Markdown vault from Claude, Codex, Gemini, or
> another stdio MCP client, without sending the whole vault into the context.

<!-- mcp-name: io.github.VBlackJack/datacron -->

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python: 3.11+](https://img.shields.io/badge/Python-3.11%2B-blue)](pyproject.toml)
[![MCP: local stdio](https://img.shields.io/badge/MCP-local_stdio-purple)](#mcp-tools)
[![CI](https://github.com/VBlackJack/datacron/actions/workflows/ci.yml/badge.svg)](https://github.com/VBlackJack/datacron/actions/workflows/ci.yml)

**English** | [Français](README.fr.md)

## What can you do with Datacron?

Recover project context, prepare for a conversation, and keep track of commitments.
Datacron gives your assistant durable memory in readable, editable Markdown. Your notes
remain usable independently of the client you choose.

| Need | Example request to your assistant |
|---|---|
| Resume a project | "Where did we leave off? Find the decisions and next actions." |
| Prepare a meeting | "Summarize our recent conversations and open points, with sources." |
| Remember a person | "Who is this person, how have we interacted, and what should we follow up on?" |
| Track objectives | "Find the commitments and achievements relevant to my next review." |
| Preserve a reliable record | "Save this decision, link it to the project, and verify that it was stored." |

The assistant orchestrates these requests using the available tools and granted permissions.
A shared protocol guides reading, people updates, and write verification. Ambiguous identities
require clarification; storing a deadline does not schedule a reminder.
[Explore daily follow-up](docs/en/memory-discipline.md).

**Start here:** [install](#installation) · [first session](#first-session) ·
[user guide](docs/en/user-guide.md) · [MCP reference](#mcp-tools) ·
[privacy](#privacy-and-security).

## Installation

### Windows: one double-click installer

The easiest way on Windows: download `Datacron-Setup.exe` from the
[latest Release](https://github.com/VBlackJack/datacron/releases/latest), double-click it,
and pick your vault. No Python, no terminal, no administrator rights; Datacron registers
itself with your AI clients automatically. Full guide:
[Windows installation](docs/en/installation-windows.md).

### Python: from PyPI

```bash
python -m pip install datacron
datacron setup
```

### From source

From a clone of the repository:

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

Or, to install only the application:

```bash
python -m pip install -e .
```

Runtime prerequisites:

- Python 3.11+
- `ripgrep` available on the `PATH` for `search_regex`
- a folder of Markdown notes
- a supported stdio MCP client, such as Claude Desktop, Codex CLI, or Gemini CLI

## First session

1. Choose your notes folder with the installer or `datacron setup`.
2. Reconnect Datacron in your MCP client to load the tools and instructions.
3. Ask: "Find the notes for my project and summarize its status with sources."

For memory sessions, `session_context` returns bounded context and the shared protocol.
`prepare_follow_up` prepares sourced updates; existing writers apply them according to
permissions. `get_follow_up` retrieves the latest structured revisions. Existing prose notes
remain readable and are not automatically converted.

The server operates locally. Your client may send returned excerpts to its model provider;
see [privacy and security](#privacy-and-security).

## Quick start

The easy path - one command detects your AI clients, initializes the vault, indexes it, and
registers Datacron everywhere:

```bash
datacron setup            # interactive; add --yes for all defaults
```

See the [installation guide](docs/en/setup.md) for options (`--client`, `--scope`, writing,
durability). Or step by step:

```bash
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
```

The `mcp install` subcommand above is dedicated to Claude Desktop. For Codex CLI, Gemini CLI,
Antigravity, LM Studio, Cursor, and the other clients, use multi-client setup with
`datacron setup --client <identifier>` or auto-detection with `--client all`.

### Add to LM Studio

LM Studio 0.3.17+ has one user configuration and no project scope. The preferred command is:

```bash
datacron setup --yes --vault "VAULT_PATH" --client lmstudio --scope user
```

For a Python installation where `datacron-mcp` is on `PATH`, the equivalent read-only
configuration can also be imported with this official deeplink:

[Add to LM Studio](lmstudio://add_mcp?name=datacron&config=eyJjb21tYW5kIjoiZGF0YWNyb24tbWNwIiwiYXJncyI6W10sImVudiI6eyJEQVRBQ1JPTl9WQVVMVF9ST09UIjoiPFlPVVJfVkFVTFQ%2BIiwiREFUQUNST05fUkVBRF9QQVRIUyI6IjxZT1VSX1ZBVUxUPiIsIkRBVEFDUk9OX0RVUkFCSUxJVFkiOiJiZXN0LWVmZm9ydCJ9fQ%3D%3D)

The link imports this example. Open LM Studio's MCP editor and replace both
`<YOUR_VAULT>` placeholders before starting the server:

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

The example does not enable write tools. CLI setup is safer for packaged installations
because it writes the actual executable path automatically.

Restart the configured client or clients after installation.

To run the server manually:

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

The direct script entry used by the installer is also available:

```bash
datacron-mcp
```

`datacron-mcp` reads the vault from `DATACRON_VAULT_ROOT`.

## Configuration

`datacron init` creates `.datacron/VAULT.yaml`. That file can carry vault-local
configuration, notably query expansion:

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

Useful environment variables:

| Variable | Default | Role |
|---|---:|---|
| `DATACRON_VAULT_ROOT` | unset | fallback after `--vault`; the current directory is accepted only when it contains `.datacron/VAULT.yaml` |
| `DATACRON_READ_PATHS` | empty | read allowlist; client setup sets it to the vault |
| `DATACRON_WRITE_PATHS` | empty | write allowlist; empty = write tools disabled |
| `DATACRON_MAX_RESULT_COUNT` | `20` | maximum number of results returned |
| `DATACRON_MAX_RESULT_TOKENS` | `8000` | token budget for search results |
| `DATACRON_REPAIR_MIN_INTERVAL_SECONDS` | `30` | minimum interval between repair-on-read sweeps; `0` = every read |
| `DATACRON_GET_NOTE_MAX_TOKENS` | `25000` | budget for `get_note(format="full")` |
| `DATACRON_CHUNK_MAX_TOKENS` | `1024` | target maximum chunk size |
| `DATACRON_RIPGREP_PATH` | `rg` | ripgrep binary |

Path lists use the OS separator (`:` on Unix, `;` on Windows).

## Writing

Writes are deliberately OFF by default. Without `DATACRON_WRITE_PATHS`, write tools return a
clear error and create no file.

To enable writing to a specific subfolder:

```powershell
$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` can also apply the allowlist machine-wide (user environment
variable, opt-in) so every MCP client inherits it; default: `_memory`, `_drafts`,
`_journal`. See the [setup guide](docs/en/setup.md).

Available write tools:

- `create_note_ai`: creates a typed Markdown note, without overwrite.
- `append_journal`: adds an entry under a heading of an existing note.
- `set_frontmatter`: updates lifecycle fields and the `rejected` options list without modifying the Markdown body.
- `patch_note_preamble`: replaces or removes the Markdown preamble before the first recognized Markdown heading (ATX or Setext), with mandatory CAS control.
- `patch_note_section`: replaces the content under an existing heading with CAS control.
- `delete_note_section`: explicitly deletes an H2-H6 section (ATX or Setext) and its subtree.
- `rename_note_section`: renames only the title of an H2-H6 section (ATX or Setext).
- `revert_note`: restores the exact bytes of a version kept in history.
- `apply_organization_manifest`: validates and then applies a local content-addressed bundle
  after confirmation bound to the exact admitted organization pre-state.

Guarantees:

- strict note confinement within `DATACRON_WRITE_PATHS`; organization-batch note sources and
  targets must also stay inside the unchanged live `organization.scope` and pass the live
  note-admission policy, including exclusions
- two internal exact-CAS targets for an organization batch: `.datacron/VAULT.yaml`, only to change
  the top-level `organization` mapping without changing `organization.scope`, and
  `.datacron/ulids.json`, only when Datacron derives the key migration required by a
  `move_replace_exact`
- atomic overwrite via temporary file + `os.replace`
- content-addressed history before modifying an existing note
- synchronous `reconcile()` after a normal write; immediate searchability is guaranteed only when
  reconciliation succeeds
- local audit log
- for an organization manifest: crash-consistent recovery and atomic replacement of each file;
  simultaneous visibility across several paths is not guaranteed

Concurrent multi-machine mode is not supported for writes: keep a single-writer rule on the
vault.

For `apply_organization_manifest`, also stop every other Datacron client and server during the
maintenance window. Before applying, keep a verified byte-exact backup outside the vault of the
affected notes and the complete `.datacron` directory until every post-commit check is green. Call
`mode="validate"` first, review