企业官网建设流程全解析

OpenChronicle 开发者指南：3 大方向助你为 AI Agent 记忆生态贡献开源力量

【免费下载链接】OpenChronicle项目地址: https://gitcode.com/gh_mirrors/op/OpenChronicle

OpenChronicle 是一个开源、本地优先的AI Agent 记忆层项目：它把你在 Mac 屏幕上的真实工作上下文，压缩沉淀为可检查、可检索的 Markdown 记忆，并经由 MCP 工具开放给任何会调用工具的 LLM Agent。如果你关心本地记忆、个人 AI 记忆或开放上下文基础设施，这是一份帮你快速上手的开源贡献指南。

为什么需要开源的 AI Agent 记忆层

大多数 Agent 产品"失忆"：每次对话从零开始，不知道你是谁、在做什么项目、偏好什么。OpenChronicle 的答案是：

• 🖥️事件驱动捕获：通过 macOS 辅助功能（AX）事件感知你正在看的窗口、正在输入的内容
• 📝本地可检查：记忆就是磁盘上的 Markdown 文件 + 本地 SQLite 全文索引，随时grep、diff、手改
• 🔌模型无关：Ollama、LM Studio、OpenAI、Anthropic 等任何 LiteLLM 兼容服务都能用
• 🧩面向所有 Agent：不绑定单一协议或应用，MCP 客户端是今天支持最好的路径

项目状态：v0.1.0 · 仅支持 macOS · 早期 Alpha · MIT 许可

整体架构是一条"确定性漏斗"：捕获 → 时间线归一化 → 会话压缩 → 分类提取长期事实。详见 docs/architecture.md。

5 分钟搭好 OpenChronicle 开发环境

贡献前先让项目跑起来。要求macOS 13+和 Xcode 命令行工具（xcode-select --install）。

git clone https://gitcode.com/gh_mirrors/op/OpenChronicle cd OpenChronicle bash install.sh

首次运行openchronicle status会在~/.openchronicle/config.toml生成带默认值的配置。之后用openchronicle start启动守护进程、openchronicle capture-once冒烟测试捕获链路。

开发侧只需三条命令：

uv sync --all-extras uv run pytest uv run ruff check

📌 提示：status会探测每个 LLM 阶段的服务商连通性，配置写错时第一次就能发现，不会几小时后在 writer 里静默失败。配置细节见 docs/config.md。

方向一：贡献更好的上下文解析器（Capture 层）

这是官方最想要的帮助之一：为浏览器、终端、编辑器、Slack、Notion、Cursor、Linear、Figma 等具体应用补充专门的解析与归一化规则，让记忆更准、更省 token。

💡一个真实的坑：Electron 应用（VS Code、Slack、Notion 等）把用户内容嵌套在 20–60 层深的树里，默认ax_depth = 100正是为此调出来的——调低到 8 时连侧边栏都看不全。这类"应用特异性"问题正是解析器贡献的空间。完整说明见 docs/capture.md。

方向二：改进记忆管理（Writer / Session 层）

第二大赛道是记忆本身的质量：会话切分、长期事实提取、压缩、覆盖（supersede）与合并逻辑、检索质量。

• ✂️会话切分：三条规则（空闲硬切 5 分钟 / 单应用软切 3 分钟 / 2 小时超时）定义在 src/openchronicle/session/manager.py，规则动机见 docs/session.md
• 🗂️S2 reducer：把时间线块压成event-YYYY-MM-DD.md条目，实现在 src/openchronicle/writer/session_reducer.py
• 🏷️Classifier：通过工具调用循环（read / search / append / create / supersede / commit）把"持久事实"分门别类写进user-*.md、project-*.md等文件，核心在 src/openchronicle/writer/classifier.py 与 src/openchronicle/writer/tools.py
• 🗜️Compact：文件膨胀后的保事实压缩，失守即拒收，见 src/openchronicle/writer/compact.py
• 📜提示词本身也是贡献面：四个 LLM 阶段的行为由 src/openchronicle/prompts/ 下的 session_reduce.md、classifier.md、compact.md 和 schema.md 定义

记忆文件格式（含"只覆盖不删除"的 supersede 语义）详见 docs/memory-format.md，两级 LLM 流水线的触发模型详见 docs/writer.md。

方向三：接入更多 Agent（MCP 集成）

第三大方向：让更多 MCP 客户端、IDE Agent、编码助手用上这套本地记忆。守护进程内置一个只读 MCP 服务器（默认127.0.0.1:8742/mcp），暴露 8 个工具，工具面定义在 src/openchronicle/mcp/server.py：

你可以做的事情：

• 🧰新增客户端安装命令：现有openchronicle install claude-code / codex / opencode / claude-desktop都是幂等的注册入口，为新 Agent 框架补一个install目标是低门槛好起点
• 📄补充集成文档：docs/mcp.md 已覆盖 Claude Code、Codex、Cursor、ChatGPT Desktop 与通用mcpServersJSON，缺哪个客户端就补哪篇
• 🔍改进检索质量：原始捕获的 FTS 侧读辅助在 src/openchronicle/mcp/captures.py

提交第一个 PR：测试与代码风格

项目对质量把关很直接：

1. 改动后跑uv run pytest（测试集中在 tests/ 目录，如 test_session_reducer.py、test_mcp_tools.py）
2. 跑uv run ruff check，行宽 100，规则集见 pyproject.toml
3. 涉及配置项的改动，同步更新 docs/config.md
4. 涉及记忆行为的改动，用openchronicle writer run手动验证一轮，日志在~/.openchronicle/logs/下按组件分文件

遇到问题先看 docs/troubleshooting.md——它收集了权限、编译、索引漂移等常见故障。

快速上手清单

本地优先的 AI Agent 记忆还处在早期，每一次贡献——无论是修一个 Electron 应用的解析、调一条会话切分参数，还是接入一个新的 MCP 客户端——都会直接塑造这个生态的形状。现在就是最好的参与时机。

【免费下载链接】OpenChronicle项目地址: https://gitcode.com/gh_mirrors/op/OpenChronicle