OpenChronicle 完全指南：开源本地 AI 记忆系统如何让 Agent 拥有持久大脑

OpenChronicle 完全指南：开源本地 AI 记忆系统如何让 Agent 拥有持久大脑

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

OpenChronicle是一个开源、本地优先的 AI Agent 记忆系统：它在你的 Mac 上后台运行，自动捕获你正在做什么（屏幕内容、应用、窗口），再交给 LLM 压缩成可读的 Markdown 记忆文件，并通过 MCP 工具接口让 Claude Code、Codex、opencode 等任意工具型 Agent 随时查询。简单说，它就是给 AI 装上一块持久大脑，而且所有数据都留在本机。

为什么 Agent 需要持久记忆？

你大概都有过这样的体验：每次开新的 AI 对话，都要重新告诉它"我在做什么项目、偏好什么、刚才聊到哪了"。Agent 一关对话就失忆，而你的工作上下文——正在写的项目、定下的决策、常用工具、相关的人——恰恰是最该被记住的。

OpenChronicle 的思路是：

• 🧠Local-first：记忆全部存在你自己的机器上（Markdown + SQLite），不上传
• 🌐模型无关：本地 Ollama、LM Studio、OpenAI、Anthropic 等任何 LiteLLM 兼容提供商都能用
• 🔧工具友好：任何能调用工具的 Agent 都能接，不绑定单一协议
• 🔍可检查：记忆就是磁盘上的 Markdown，随时可 grep、可 diff、可手改
• 📜开源：MIT 协议，解析器、记忆逻辑、集成方式都可以改

详细设计见 docs/architecture.md。

一键安装：两步跑起来

⚠️ 当前版本仅支持macOS 13+，需要 Xcode Command Line Tools（xcode-select --install安装）。

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

然后启动并查看状态：

openchronicle start # 后台启动守护进程 openchronicle status # 查看运行状态与模型配置 openchronicle pause # 暂停捕获（写代码累了/开会时） openchronicle resume # 恢复捕获 openchronicle stop # 停止

几个实用命令：

openchronicle capture-once # 手动抓一帧屏幕上下文，验证采集正常 openchronicle timeline list # 查看已生成的一分钟时间线块 openchronicle rebuild-index # 重建本地 SQLite 全文索引

配置存放在~/.openchronicle/config.toml，运行时参数全部集中在这一个文件，可用openchronicle config随时查看解析结果。

它如何工作：五步流水线

OpenChronicle 只有一条确定性管线（无模式切换），核心逻辑在 src/openchronicle/daemon.py 中编排：

为什么不用截图 OCR 而是"AX 优先"？因为结构化的无障碍树文本成本更低、意图捕捉更准、记忆更干净——它天然包含你在输入什么、当前 URL、聚焦的输入框；截图只是辅助信号，保留给未来的视觉模型路径。

你得到的记忆：人也能读的 Markdown

所有记忆落在~/.openchronicle/memory/，每个实体一个文件，前缀即分类：

两个让"记忆可信"的细节：

• Supersede-not-delete（覆盖不删除）：事实变了，旧条目打删除线并标注指向新条目，完整时间线永不丢失
• 压缩有护栏：文件变大触发压缩时，正则事实保留检查会拒绝任何丢失超 5% 名词短语的改写，坏压缩绝不会悄悄吃掉信息

完整格式规范见 docs/memory-format.md。

最快接入你的 Agent：MCP 一步搞定

守护进程在http://127.0.0.1:8742/mcp常驻一个只读 MCP 服务器，各客户端有一条 install 命令：

openchronicle install claude-code # Claude Code openchronicle install claude-desktop # Claude Desktop openchronicle install codex # Codex CLI / IDE openchronicle install opencode # opencode

接入后，Agent 获得两层记忆工具：

• 压缩记忆层：list_memories/read_memory/search（BM25 全文检索）/recent_activity
• 原始屏幕层：current_context（你现在在干嘛）/search_captures（搜屏幕上出现过的词）/read_recent_capture（回溯到具体某一分钟的屏幕内容）

典型效果：问它"我下午两点在改什么文件"，它能直接查回那一刻的原始捕获。更多客户端配置见 docs/mcp.md。

配置模型：云端或全本地

所有 LLM 阶段走 LiteLLM，在config.toml的[models.*]中按阶段配置。分档是省钱关键——timeline 每分钟跑一次（配小模型即可），classifier 负责事实提炼（要配强模型）：

[models.default] model = "gpt-5.4-nano" api_key_env = "OPENAI_API_KEY"

想完全本地？指向 Ollama 即可，无任何云依赖：

[models.default] model = "ollama/llama3.1:8b" base_url = "http://localhost:11434" api_key_env = ""

改完配置openchronicle stop && openchronicle start即可，status会对每个阶段的模型做连通性探测，密钥错误当场暴露而不是几小时后才炸。完整参数说明见 docs/config.md。

常见问题速查

• 捕获刷屏 / 没捕获到内容：优先检查ax_depth（Electron 应用如 VS Code、Claude Desktop 需要 100，别低于 20），详见 docs/capture.md
• 想清空记忆：openchronicle clean memory（确认后清空 memory/ 与 FTS 表），配置文件不受影响
• 手改了 Markdown：跑openchronicle rebuild-index重建索引即可
• 更多排查：docs/troubleshooting.md

谁适合用它？

如果你在跑 Claude Code、Codex 这类编码 Agent，又希望它"记得你"——记住你的项目、你的偏好、你正在读的那篇文档——OpenChronicle 目前就是开源界最完整的答案：捕获、压缩、提炼、检索全链路打通，且每一步产物（capture-buffer 的 JSON、时间线块、记忆 Markdown、SQLite 索引）你都能直接打开检查。项目仍处 alpha 阶段，特别欢迎为浏览器、终端、Slack、Notion 等应用贡献解析器。

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