datacron

Datacron

本地 MCP 服务，可通过 Claude、Codex、Gemini 或其他 stdio MCP 客户端查询和维护 Markdown 知识库，无需将整个知识库发送到上下文中。

English | Français

Datacron 可以做什么？

恢复项目上下文、为对话做准备，并跟踪承诺事项。 Datacron 为你的助手提供持久记忆，以便于阅读和编辑的 Markdown 格式保存。无论你选择哪个客户端，这些笔记都能独立使用。

离线资料库： 构建可供 Obsidian 或其他本地阅读器浏览的 Markdown 资料库，其中包含主页和主题索引。 在更改源知识库之前，先审阅建议的改写、拆分和归档。 请参阅离线资料库指南和 2026.0913.02 版发布说明。

助手会使用可用工具和已授予的权限来协调处理这些请求。 一套通用协议指导信息读取、人员信息更新和写入验证。身份不明确时需要先澄清；保存截止日期并不会安排提醒。 了解日常跟进。

从这里开始： 安装 · 首次会话 · 用户指南 · MCP 参考 · 隐私。

安装

Windows：双击安装程序

在 Windows 上最简单的方式：从最新版本下载 Datacron-Setup.exe，双击运行， 然后选择你的知识库。无需安装 Python，无需使用终端，也无需管理员权限；Datacron 会自动向你的 AI 客户端注册自身。完整指南： Windows 安装。

Python：从 PyPI 安装

python -m pip install datacron
datacron setup

从源代码安装

从克隆的代码仓库开始：

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

或者，仅安装应用程序：

python -m pip install -e .

运行时先决条件：

• Python 3.11+
• PATH 中需提供 ripgrep，供 search_regex 使用；如果没有该程序，此工具会改为扫描已编入索引的分块正文，但速度较慢
• 一个包含 Markdown 笔记的文件夹
• 受支持的 stdio MCP 客户端，例如 Claude Desktop、Codex CLI 或 Gemini CLI

首次会话

1. 使用安装程序或 datacron setup 选择笔记文件夹。
2. 在 MCP 客户端中重新连接 Datacron，以加载工具和说明。Claude Desktop 聊天不会显示服务说明：将 setup 输出的会话启动行粘贴到 Claude 偏好设置中（参见设置）。
3. 询问：“查找我项目的笔记，并引用来源总结其状态。”

对于记忆会话，session_context 会返回有界上下文和共享协议。 prepare_follow_up 会准备带来源的更新；现有写入器会根据权限应用这些更新。 get_follow_up 会检索最新的结构化修订。现有的文字笔记仍可读取，不会自动转换。

服务在本地运行。客户端可能会将返回的摘录发送给其模型提供商； 请参阅隐私与安全。

有关缓存会话约定、归档排序、可恢复的写入跟踪和对话评估，请参阅 日常工作流改进。

快速开始

简单的方法——一条命令即可检测你的 AI 客户端、初始化知识库、为其建立索引，并在所有客户端中注册 Datacron：

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

有关可选项（--client、--scope、写入、持久性），请参阅安装指南。也可以按步骤操作：

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

上面的 mcp install 子命令专用于 Claude Desktop。对于 Codex CLI、Gemini CLI、 Antigravity、LM Studio、Cursor 和其他客户端，请使用多客户端设置 datacron setup --client <identifier>，或使用 --client all 自动检测。

添加到 LM Studio

LM Studio 0.3.17+ 只有一个用户配置，且没有项目范围。推荐使用以下命令：

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

如果是 Python 安装，且 datacron-mcp 位于 PATH 中，也可以通过此官方深层链接导入等效的只读配置：

添加到 LM Studio

此链接会导入以下示例。启动服务前，打开 LM Studio 的 MCP 编辑器并替换两个 <YOUR_VAULT> 占位符：

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

此示例不会启用写入工具。对于打包安装，CLI 设置更安全，因为它会自动写入实际的可执行文件路径。

安装后，重启已配置的客户端。

要手动运行服务：

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

安装程序使用的直接脚本入口也可用：

datacron-mcp

datacron-mcp 会从 DATACRON_VAULT_ROOT 读取知识库。

配置

datacron init 会创建 .datacron/VAULT.yaml。此文件可承载知识库本地配置，尤其是查询扩展：

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

常用环境变量：

路径列表使用操作系统分隔符（Unix 上为 :，Windows 上为 ;）。

写入

默认情况下，写入功能有意关闭。未设置 DATACRON_WRITE_PATHS 时，写入工具会返回明确错误，且不会创建任何文件。

若要启用对特定子文件夹的写入：

$env:DATACRON_VAULT_ROOT = "C:\Notes"
$env:DATACRON_READ_PATHS = "C:\Notes"
$env:DATACRON_WRITE_PATHS = "C:\Notes\_memory"
datacron mcp serve --vault C:\Notes

datacron setup 也可以在整台机器范围内应用允许列表（选择启用的用户环境变量），使所有 MCP 客户端都继承该设置；默认值：_memory、_drafts、_journal。请参阅设置指南。

可用的写入工具：

• create_note_ai：创建类型化 Markdown 笔记，不覆盖已有内容。
• append_journal：在现有笔记的标题下添加条目。
• set_frontmatter：更新生命周期字段、rejected 选项列表和单调递增的 last_id 计数器，不修改 Markdown 正文。
• patch_note_preamble：替换或移除第一个可识别的 Markdown 标题（ATX 或 Setext）之前的 Markdown 前言，并强制要求 CAS 控制。
• patch_note_section：通过 CAS 控制替换现有标题下的内容。
• delete_note_section：显式删除一个 H2-H6 章节（ATX 或 Setext）及其子树。
• rename_note_section：仅重命名一个 H2-H6 章节（ATX 或 Setext）的标题。
• move_note_section：预览或提交笔记内精确的 H2-H6 子树移动，并强制要求 CAS。
• revert_note：恢复历史记录中某个版本的精确字节内容。
• apply_organization_manifest：验证本地内容寻址包，然后在确认与获准的组织操作前状态精确绑定后应用该包。

保障：

• 严格限制笔记只能位于 DATACRON_WRITE_PATHS 中；组织批次的笔记源和目标也必须位于未变更的实时 organization.scope 内，并通过实时笔记准入策略（包括排除项）
• 组织批次的两个内部精确 CAS 目标：.datacron/VAULT.yaml，仅用于更改顶层 organization 映射，不得更改 organization.scope；以及 .datacron/ulids.json，仅当 Datacron 根据 move_replace_exact 推导出需要迁移键时才可更改
• 通过临时文件 + os.replace 原子覆盖
• 修改现有笔记前，先写入内容寻址的历史记录
• 正常写入后同步执行 reconcile()；只有在协调成功时，才能保证立即可搜索
• 本地审计日志
• 对于组织清单：支持崩溃一致性恢复和逐个文件原子替换；不保证多个路径同时可见

不支持多机并发写入模式：请在知识库上保持单写入者规则。

对于 apply_organization_manifest，还应在维护窗口期间停止所有其他 Datacron 客户端和服务。应用前，请在知识库外保留受影响笔记和完整 .datacron 目录经过验证、逐字节精确的备份，直到所有提交后检查均通过。先调用 mode="validate"，检查其返回的有限范围哈希，然后在 mode="apply" 中重用完全相同的 confirmation_token。该令牌绑定清单和载荷、organization.scope 内所有获准的 Markdown 笔记、确切的知识库配置和身份侧车文件，以及投影报告。它有意不绑定 organization.scope 外无关笔记的字节内容。任何经过认证的组件发生变化，都会在修改前使确认失效。验证时必须使用 history_mode=full。如果 Datacron 推导出身份侧车的大小写冲突清理，还应在应用前检查 identity_sidecar_case_canonicalization_count 及其不含内容的 SHA-256；这两项证明均绑定到令牌，并保留在持久化回执中。 现有的 replace_exact 或 move_replace_exact 源必须在 frontmatter 中携带其 id；仅能从侧车获取的身份不受此 v1 架构支持。如果批次已持久提交，但索引协调或规划器预言机失败，响应会明确说明（committed_index_incomplete 或 committed_report_mismatch），并可使用相同令牌重试同一调用。 组织批次阻塞项会通过 datacron ops inspect 报告，原因中包含 pending_batch_，且两种单笔记修复操作均不可用；请使用 operational-health 指南中的完整离线回滚流程，而不要修复或隔离其中单个成员。

可用功能

Datacron 会为 Markdown 笔记文件夹建立索引，并公开一个本地 MCP 服务，然后向客户端返回相关笔记或片段，而不是完整转储。知识库仍是普通的 Markdown 文件夹：Datacron 只会添加 .datacron/ 旁置目录，用于存放索引、日志、内部 ULID、历史记录和操作日志。唯一例外是项目级别的 datacron setup，它属于默认行为：该命令还会将每个检测到的客户端的项目配置写入知识库根目录，例如 .mcp.json、.cursor/mcp.json、.gemini/settings.json、.agents/mcp_config.json、.codex/config.toml 或 .vscode/mcp.json。这些文件包含机器本地的绝对路径，因此同步知识库时也会将它们同步到每台机器。传入 --scope user 可避免在知识库中写入这些文件。

MCP 工具

下表列出了标准配置（23 个工具）。对于更适合从精简列表中选择工具的助手，DATACRON_TOOL_PROFILE=essential 会改为注册 5 个工具：remember、recall、what_changed、get_note 和 get_health。请参阅精简工具配置。

阅读

写入

运维

建议（实验性）

MCP 资源：

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

搜索

search_text 会综合多种信号：

• 使用 FTS5/BM25 计算基础词法分数
• 笔记标题和标题层级的权重高于分块正文，因此主题相关笔记的排名会高于仅仅提及该主题的笔记
• 使用 VAULT.yaml 中配置的 FR↔EN 查询扩展
• 保守的时间重排：
  • 如果一篇笔记的 supersedes 被另一篇笔记引用，其排名会大幅降低
  • confidence: low 和 confidence: needs_verification 会受到轻微惩罚
  • include_superseded=true 会让历史笔记重新进入排名
• 可选范围：folder、tags 和 frontmatter 会按照与 list_notes 相同的语义缩小搜索笔记的范围；响应会回显实际应用的筛选条件
• 可选分组：group_by_note=true 会保留每篇笔记中排名最高的分块，并报告该笔记有多少个分块匹配；在评估语料库上，这会将返回的令牌数减少约 40％

search_regex 保持字面匹配：它既不应用查询扩展，也不进行时间重排。

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

隐私与安全

• Datacron 不进行遥测。
• Datacron 不调用云端大模型。
• MCP 客户端（例如 Claude、Codex 或 Gemini）可能会将 Datacron 返回的分块发送给其提供方。Datacron 不会将整个知识库发送给它。
• 返回给客户端的内容会包装在 <vault_content>...</vault_content> 中。
• 结果数量和令牌预算均有限制。
• 文件系统访问受 DATACRON_READ_PATHS 和 DATACRON_WRITE_PATHS 限制。
• MCP 操作会记录在本地日志中。

CLI 命令

datacron companion                  # launch the local graphical control panel (127.0.0.1)
datacron setup                      # guided path: init + index + client config
datacron setup --yes                # all defaults, no prompts
datacron setup --client all --scope both --vault /path/to/vault
datacron setup --vault /path/to/docs --memory-vault /path/to/memory  # Dual-Vault setup
datacron migrate-memory --vault /path/to/docs --memory-vault /path/to/memory
datacron graph-health --vault /path/to/vault --json
datacron compact-memory --vault /path/to/vault --older-than-days 30 --dry-run
datacron compact-memory --vault /path/to/vault --older-than-days 30 --apply
datacron config get --vault /path/to/vault --json
datacron config set --vault /path/to/vault --expected-hash sha256:... --values-json '{"excluded_folders":[".git"]}'
datacron setup --protocol           # also install client memory rules
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          # measure organization, read-only
datacron reorganize --vault /path/to/vault --dry-run --json   # stable machine-readable report
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  # Claude Desktop only
datacron unregister --client all --scope both --vault /path/to/vault
datacron protocol uninstall --client all

当前限制

• 仅支持词法搜索：不支持向量搜索或嵌入。
• 没有自主 Agent：由 MCP 客户端负责编排。
• 不支持多台机器并发写入。
• datacron setup 对客户端的检测仅尽力而为（依据配置目录或 PATH 中的二进制文件）；可能无法检测到安装在非标准位置的客户端，之后可以手动配置。

文档

完整索引：docs/en/index.md | 法语索引。

快速入门：

• 安装和配置指南
• 将 Datacron 与 Ollama 配合使用
• 常见问题
• 用户指南
• 离线资料库和笔记整理
• 日常记忆、人物和承诺
• 基本工具配置

技术参考：

• Vault 约定（SPEC）
• Vault 组织方式
• 读取和重组笔记章节
• 架构和公共接口
• 安全边界
• 完整性检查器
• 运行状况和持久性
• 新鲜度约定

开发

对于仅涉及 README、CHANGELOG 以及 docs/fr/ 或 docs/en/ 下 Markdown 页面变更的情况，CI 会在 Linux/Python 3.12 上运行不变量检查和完整回归测试套件。其他所有变更仍会覆盖 Linux/Windows 和 Python 3.11-3.13 的六种组合。发布需要运行完整矩阵，空差异或无法验证的差异也同样如此。ShellCheck、依赖项审计和必需的 Quality gate 在这两种路径中都会保持启用。新分支的首次推送也会运行完整矩阵，因为没有可用的先前比较点。

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

许可证

版权所有 2026 Julien Bombled。

根据 Apache License, Version 2.0 授权。

可靠写入和质量门禁