openchronicle-mcp

OpenChronicle

_{· claude-fable-5 · 2026-08-30 · 详情}

为大模型 Agent 提供的记忆数据库。提供持久化语义记忆和关键词记忆、 项目命名空间、Git 入门，并通过单个 ASGI 进程提供 HTTP REST 和 MCP 服务。运行在你的硬件上。

功能

• 跨会话持久记忆。 保存决策、里程碑和被否决的方案，使其在上下文压缩和新 对话后仍然留存。通过 Reciprocal Rank Fusion 混合全文和语义搜索来检索记忆。
• 项目命名空间。 记忆按项目划分范围，因此一个工作流的上下文不会泄漏到另一个项目。
• Git 入门。 克隆代码库，按相关性对提交进行聚类，并返回可直接用于记忆导入的摘要。 为长期记忆补充现有代码背后的原因。
• 单进程，双传输方式。 FastAPI 同时承载 REST 接口 (/api/v1/*) 和 MCP 可流式传输的 HTTP 传输方式 (/mcp)，并使用同一端口。 单个容器、单个端口映射、单个健康检查。
• 嵌入故障降级。 嵌入提供程序不可用时，搜索会平稳降级为仅使用 FTS5， 并通过 /api/v1/health 和 MCP health 工具显示降级状态。 提供程序恢复后，回填任务会追上进度；静态 /health 端点仍是最简存活探针。
• 可选运行指标。 发布的镜像（自 v3.4.0 起）包含有界 Prometheus 记录器和受保护的 /metrics 端点，默认关闭。在生产环境中启用 OC_METRICS_ENABLED=true 前， 仍须满足性能门槛。参见 指标配置和可选的 本地监控运行手册。
• 架构迁移框架。 使用带保存点原子性的版本化 .sql 迁移。重复运行具有幂等性。未来的架构变更 可作为 NNN_<slug>.sql 文件添加。
• 经验证的在线备份。 使用 SQLite 在线备份 API；每个夜间快照都会附带经过验证的清单，发布到 OC_BACKUP_DIR，验证失败的快照会被隔离。 先备份再执行破坏性操作：vacuum 会在同一作业中先执行备份。完整性检查失败时会触发紧急备份。
• 可选的加密异地副本。 夜间作业使用 age 加密最新快照， 并以仅追加方式复制到任意 rclone 远程端。参见 cloud_backup.md。

不包含的功能

• 不是对话引擎。v3 不包含大模型。可通过 MCP 服务使用 Claude Code、Goose、 Open WebUI 等工具。
• 不是多租户服务。仅供单用户使用。支持通过 OC_API_KEY 使用 Bearer 令牌身份验证，但可选——在可信局域网 部署中默认关闭。何时启用请参阅 docs/configuration/security_posture.md。
• 不是云同步层。数据库保存在你的硬件上。备份写入本地备份目录，也可选择加密后备份到云远程端， 仅作备份用途。未内置跨设备同步功能 (docs/design/0001-cloud-backup.md)。

这是有意为之。

安装

从源码安装：

pip install -e ".[mcp,openai]"
oc init
oc serve

默认情况下，oc serve 绑定到 127.0.0.1:8000。可通过 --host/--port 或 OC_API_HOST/OC_API_PORT 覆盖。

Docker（单容器，适合 NAS）：

docker run --rm \
  -p 8000:8000 \
  -e OC_API_HOST=0.0.0.0 \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config \
  ghcr.io/carldog/openchronicle-mcp:latest

在容器中必须设置 OC_API_HOST=0.0.0.0——应用默认绑定到容器环回地址， 端口映射无法访问该地址。如果要通过 localhost 以外的地址（NAS 主机名、局域网 IP）调用服务，还需设置 OC_MCP_ALLOWED_HOSTS=your-host:*，否则每个请求都会收到 421（参见 env_vars.md）。

对于 NAS 上的 Portainer 堆栈，请使用仓库根目录下的 docker-compose.nas.yml。 首先需要完成三项准备：将 OC_TAG 设置为一个发布标签 （没有 :latest 备用选项）；创建一次数据卷 （docker volume create openchronicle-mcp_oc-data；compose 文件不会 创建该卷，因此卷缺失时部署会失败，而不是以空数据启动）；并创建宿主机导出 目录，且将其所有者设为 uid 1000。文件开头的注释列出了所有变量。

快速入门

# Bootstrap the runtime tree
oc init

# Create a project
PROJECT_ID=$(oc init-project "my-project")

# Save your first memory
oc memory add "Decision: SQLite for storage; AGPL for license" \
    --project-id $PROJECT_ID --tags decision

# Search it
oc memory search "storage decision" --project-id $PROJECT_ID

也可以通过 MCP 执行相同操作——在 Claude Code 中注册该服务：

claude mcp add --scope user --transport http openchronicle \
    http://127.0.0.1:8000/mcp

然后让 Claude 调用 memory_save 和 memory_search。

架构

六边形架构：domain/（纯类型 + 端口）→ application/（用例、 服务）→ infrastructure/（SQLite、嵌入适配器、维护循环）。驱动端适配器位于 interfaces/，承载 HTTP、MCP 和 CLI 接口。

完整结构请参见 docs/architecture/ARCHITECTURE.md。

文档

• docs/architecture/ARCHITECTURE.md — 目录结构、架构、ASGI 设计
• docs/architecture/MAINTENANCE.md — 维护循环 + 降级策略
• docs/cli/commands.md — oc 子命令参考
• docs/configuration/env_vars.md — 环境变量
• docs/configuration/config_files.md — core.json 架构
• docs/configuration/security_posture.md — 安全模型
• docs/integrations/mcp_client_setup.md — 注册 MCP 服务
• docs/integrations/mcp_server_spec.md — MCP 工具接口
• docs/api/STABILITY.md — 版本管理 + 弃用策略
• docs/design/README.md — 提议的设计和对比性仓库评审

开发

uv sync --locked --extra dev --extra mcp --extra openai --extra ollama --extra metrics
pre-commit install
uv run pytest

依赖项锁定在 uv.lock 中，CI 和 Docker 镜像均从该文件安装依赖；在 pyproject.toml 的 [project] 中更改任何内容（包括版本）后，请运行 uv lock。

架构通过测试强制执行：

• tests/test_hexagonal_boundaries.py — domain/application/infrastructure 分层
• tests/test_architectural_posture.py — 核心不依赖 MCP SDK
• tests/test_no_secrets_committed.py、tests/test_no_soft_deprecation.py — 仓库规范

许可证

版权所有 (C) 2025-2026 CarlDog

AGPL-3.0。本程序是自由软件：您可以根据自由软件基金会发布的 GNU Affero 通用公共许可证的条款重新分发和/或修改本程序；许可证版本为第 3 版，或（由您选择）任何更新版本。本程序按“原样”提供，不提供任何担保；详情请参阅许可证。

版权行写在此处，而非 LICENSE 文件中：该文件是 AGPL 原文，其结尾附录中的 <year> <name of author> 占位符是许可证自身关于在源文件中填写哪些内容的说明，并非需要填入内容的空白。编辑这些占位符会修改许可证文本本身。