Cherry Studio 内置 Agent 长期记忆 FACT.md设计规范与持久化实现解析【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 为其内置 AgentCherry 小助手cherry-assistant、Cherry 支持助手cherry-support提供了一套基于文件的长期记忆机制其中memory/FACT.md是承载长期知识的核心文件。本文以该文件的官方规范resources/builtin-agents/cherry-assistant/memory/FACT.md为骨架结合主进程源码与测试用例讲解 FACT.md 的用途边界、持久化保证、防陈旧机制以及底层原子写入与系统提示词内联加载的实现原理帮助你在定制 Agent 或扩展记忆能力时做到事实准确、边界清晰。FACT.md 的定位跨会话的用户长期知识文件FACT.md 的标题是# Long-term knowledge长期知识它被设计为存放Agent 跨会话学到的关于用户的稳定事实包括但不限于偏好preferences用户喜欢的语气、命名习惯、工具选择、工作流偏好等环境怪癖environment quirks用户机器或工作区中的特殊环境、目录布局、命令习惯等已解决的问题resolved issues过去排查完成的故障、达成的技术决策、沉淀下来的经验。从源码结构看这一设计在 src/main/ai/agents/prompt.ts 的Agent Data清单中有明确对应——FACT.md 被描述为 WHAT you know即 Agent知道什么具体涵盖活跃项目、技术决策、6 个月以上的持久知识durable knowledge, 6 months。其回忆侧recall side实现在同一文件的loadMemory逻辑中会话启动时读取memory/FACT.md内容将其内联进系统提示词供模型直接阅读写入侧write side则由memory工具的updateaction 负责二者共同构成读-写闭环。核心保证应用更新不会覆盖用户定制FACT.md 规范中最关键的一条保证是It isnotoverwritten on app updates - your customizations persist. 它不会在应用更新时被覆盖——你的自定义内容会持久保留。这一保证由内置 Agent 的模板-实例分离机制在实现层面落地。内置 Agent 的源模板存放在仓库的 resources/builtin-agents/cherry-assistant/及 resources/builtin-agents/cherry-support/目录下当用户在应用内首次使用该 Agent 时系统会将其复制到独立的 Agent 数据目录{agentData}/memory/此后 FACT.md 的生命周期就脱离应用安装目录了。这一行为由测试 src/main/ai/agents/builtin/tests/BuiltinAgentProvisioner.test.ts 明确锁定测试先向模板目录写入memory/FACT.md内容为TEMPLATE_FACT断言初始化后 Agent 数据目录中出现了内容一致的 FACT.md随后第 204-210 行将实例中的 FACT.md 改写为CUSTOM_FACT验证再次初始化不会覆盖这份自定义内容——这正是app updates 不覆盖用户定制的代码级证据。核心规范产品知识不写入 FACT.md走 skill MCP 查询FACT.md 规范同时给出了一条严格的内容边界For Cherry Studio product knowledge, follow thecherry-assistant-guideskill and query the current package manifest throughmcp__assistant__product_info. The manifest does not include release history. Do not duplicate product facts here, or they will go stale silently.即三类约束查询渠道关于 Cherry Studio 的产品知识应遵循cherry-assistant-guide技能并通过mcp__assistant__product_info工具查询当前版本的包清单清单边界包清单product manifest不包含发布历史release history发布历史需要另行获取防陈旧原则不要把产品事实复制进 FACT.md——因为产品会持续演进写在静态记忆文件里的事实会在不发出任何信号的情况下静默过期go stale silently导致 Agent 向用户传播过时信息。这一约束背后是**单一事实来源Single Source of Truth**的设计思想FACT.md 只存关于用户的稳定事实而关于产品的动态事实一律实时查询。当前版本的包清单实体见 resources/builtin-agents/cherry-assistant/product-manifest.json其中包含package名称与版本、routes应用内路由、commands快捷键命令、providers62 个模型提供商条目、locales13 种语言、agents渠道类型与代码 CLI 工具以及features上下文压缩、MCP 服务器类型、知识库支持的文件扩展名等能力边界。由于该清单会随版本更新Agent 每次查询都能拿到与用户当前安装版本一致的答案这正是不重复产品事实的工程价值所在。底层实现一memory 工具的 update / append / searchFACT.md 的写入并非由模型直接编辑文件而是通过统一的memory工具完成。工具定义位于 src/main/ai/agents/tools/memoryTools.ts其输入模式MEMORY_INPUT_SCHEMA定义了三个互斥 actionaction作用对象语义必要参数updatememory/FACT.md整体覆盖写入长期知识仅限持久知识contentFACT.md 的完整 Markdown 内容appendmemory/JOURNAL.jsonl追加一条日志一次性事件、完成任务、会话笔记text条目文本可选tags标签数组searchmemory/JOURNAL.jsonl查询日志大小写不敏感的子串匹配query查询串可选tag标签过滤、limit结果上限默认 20工具描述memoryTools.ts中还内置了一条决策准则写入 FACT.md 之前先问自己——这条信息 6 个月后还有意义吗will this still matter in 6 months?如果没有应该用append记入日志而不是update覆盖事实文件。这与 resources/skills/cherry-tool-guide/references/memory.md 中按寿命选择updatevsappend的指引完全一致同时也明确提示update会整体覆盖 FACT.md重写时应当保留已有内容先读后写、增量追加不能粗暴清空。值得注意的是update与append的职责严格分离FACT.md 只承载长期知识而一次性事件、已完成任务、会话笔记则进入JOURNAL.jsonl追加式事件日志。这也解释了为什么search只检索日志、不检索事实文件——事实文件本身已在会话启动时内联进提示词无需再查。底层实现二FACT.md 的原子写入与安全约束从实现细节看FACT.md 的更新被刻意设计为原子替换 符号链接防护防止写入中途崩溃导致文件损坏原子替换memoryUpdatememoryTools.ts先将新内容写入同目录下的临时文件.FACT.md.{uuid}.tmpopen使用wx独占创建标志权限0o600随后用rename一次性替换目标文件。任何一步失败都会在catch中清理临时文件保证 FACT.md 要么是旧内容、要么是新内容绝不出现半写状态符号链接防护多个辅助函数assertRegularFileOrMissing、assertMemoryDirectory、resolveFileCI都坚持必须是真实文件/目录的校验非 Windows 平台还通过O_NOFOLLOW标志拒绝跟随符号链接resolveFileCI甚至在文件名匹配上做到了大小写不敏感目录枚举时按小写比对确保在大小写不敏感的文件系统上也行为一致权限收敛FACT.md 与 JOURNAL.jsonl 的写入均使用0o600权限仅属主可读写日志追加使用O_APPEND标志。这些行为由测试 src/main/ai/agents/tools/tests/memoryTools.test.ts 验证调用update后断言memory/FACT.md内容即为传入的# Facts文本。此外 src/main/ai/agents/tests/prompt.test.ts 从提示词侧验证了FACT.md 存在时会被包含进 memories 区块、以 Agent Knowledge 块包裹、大小写不敏感解析/workspace/memory/FACT.md能被解析到而文件缺失或为空时该区块会被安全省略第 506 行、第 543 行。底层实现三系统提示词中的内联加载FACT.md 的回忆机制在 src/main/ai/agents/prompt.ts 中实现。会话启动时Agent 数据目录下的四个文件会被协同加载文件承载内容说明SOUL.md人格/语气Agent 如何呈现自己USER.md用户是谁偏好、上下文来自 USER.md 模板memory/FACT.mdAgent 知道什么活跃项目、技术决策、持久知识内联读取 memory工具update写入memory/JOURNAL.jsonl发生了什么追加式事件日志通过memory工具append/search维护prompt.ts 中的loadMemory逻辑会读取memory/FACT.md并生成一段带明确指令的知识块——其措辞大意是这些是 Agent 过去会话中积累的持久事实与经验应作为 ground truth 信任除非有直接证据证明其错误若发现错误应通过memory工具update修正 FACT.md使下一个会话同样受益。这一信任 可修正 跨会话传播的设计正是 FACT.md 与普通会话上下文最本质的区别它不是聊天记录而是 Agent 的长期工作记忆。FACT.md 与其他记忆机制的边界要正确使用 FACT.md还需厘清它与 Cherry Studio 其他记忆/检索机制的分工详见 docs/references/memory/overview.mdAgent File Memory含 FACT.md仅作用于单个 Agent以文件读写持久化在{agentData}/memory/跨会话但不跨 AgentKnowledge Base知识库作用于助手与 Agent通过摄取 向量/查询索引检索跨会话且跨 Agent适合用户主动整理的可检索参考资料MCP Memory通过内置cherry/memoryMCP 服务器src/main/ai/mcp/servers/memory.ts以知识图谱实体/关系/观察形式存储持久化与共享取决于服务器实现。三者的选择建议是单个 Agent 的人格与长期项目知识 → Agent File Memory需要检索的整理型参考资料 → Knowledge Base由 MCP 驱动的结构化实体/关系记忆 → MCP Memory。FACT.md 属于第一种它与后两者互不影响——启用知识库不会改变 FACT.md 的行为反之亦然。实践建议与注意事项结合 FACT.md 的官方规范与源码实现使用与维护 FACT.md 时应注意只写关于用户的持久事实偏好、环境怪癖、已解决问题是合格的候选一次性事件请写入JOURNAL.jsonl产品知识一律实时查询遵循cherry-assistant-guideskill通过mcp__assistant__product_info读取当前清单切勿复制进 FACT.md避免静默过期发布历史不在清单内需另行获取重写时先读后写update是整体覆盖语义务必保留既有有效内容只做增量合并不必担心应用更新实例化的 FACT.md 位于 Agent 数据目录与模板分离更新应用不会清空你的定制记忆会进入提示词FACT.md 内容在会话启动时内联加载因此它直接影响每次对话的上下文质量——写得精炼、准确比写得冗长更有价值。对于希望深入了解或扩展这套机制的开发者推荐按以下路径阅读源码先看 prompt.ts 了解记忆如何进入系统提示词再看 memoryTools.ts 掌握工具层的行为与安全约束最后对照 BuiltinAgentProvisioner.test.ts 与 prompt.test.ts 中的用例即可完整还原模板分发 → 实例化 → 读取内联 → 工具写入的全链路。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio 内置 Agent 长期记忆 FACT.md：设计规范与持久化实现解析
Cherry Studio 内置 Agent 长期记忆 FACT.md设计规范与持久化实现解析【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioCherry Studio 为其内置 AgentCherry 小助手cherry-assistant、Cherry 支持助手cherry-support提供了一套基于文件的长期记忆机制其中memory/FACT.md是承载长期知识的核心文件。本文以该文件的官方规范resources/builtin-agents/cherry-assistant/memory/FACT.md为骨架结合主进程源码与测试用例讲解 FACT.md 的用途边界、持久化保证、防陈旧机制以及底层原子写入与系统提示词内联加载的实现原理帮助你在定制 Agent 或扩展记忆能力时做到事实准确、边界清晰。FACT.md 的定位跨会话的用户长期知识文件FACT.md 的标题是# Long-term knowledge长期知识它被设计为存放Agent 跨会话学到的关于用户的稳定事实包括但不限于偏好preferences用户喜欢的语气、命名习惯、工具选择、工作流偏好等环境怪癖environment quirks用户机器或工作区中的特殊环境、目录布局、命令习惯等已解决的问题resolved issues过去排查完成的故障、达成的技术决策、沉淀下来的经验。从源码结构看这一设计在 src/main/ai/agents/prompt.ts 的Agent Data清单中有明确对应——FACT.md 被描述为 WHAT you know即 Agent知道什么具体涵盖活跃项目、技术决策、6 个月以上的持久知识durable knowledge, 6 months。其回忆侧recall side实现在同一文件的loadMemory逻辑中会话启动时读取memory/FACT.md内容将其内联进系统提示词供模型直接阅读写入侧write side则由memory工具的updateaction 负责二者共同构成读-写闭环。核心保证应用更新不会覆盖用户定制FACT.md 规范中最关键的一条保证是It isnotoverwritten on app updates - your customizations persist. 它不会在应用更新时被覆盖——你的自定义内容会持久保留。这一保证由内置 Agent 的模板-实例分离机制在实现层面落地。内置 Agent 的源模板存放在仓库的 resources/builtin-agents/cherry-assistant/及 resources/builtin-agents/cherry-support/目录下当用户在应用内首次使用该 Agent 时系统会将其复制到独立的 Agent 数据目录{agentData}/memory/此后 FACT.md 的生命周期就脱离应用安装目录了。这一行为由测试 src/main/ai/agents/builtin/tests/BuiltinAgentProvisioner.test.ts 明确锁定测试先向模板目录写入memory/FACT.md内容为TEMPLATE_FACT断言初始化后 Agent 数据目录中出现了内容一致的 FACT.md随后第 204-210 行将实例中的 FACT.md 改写为CUSTOM_FACT验证再次初始化不会覆盖这份自定义内容——这正是app updates 不覆盖用户定制的代码级证据。核心规范产品知识不写入 FACT.md走 skill MCP 查询FACT.md 规范同时给出了一条严格的内容边界For Cherry Studio product knowledge, follow thecherry-assistant-guideskill and query the current package manifest throughmcp__assistant__product_info. The manifest does not include release history. Do not duplicate product facts here, or they will go stale silently.即三类约束查询渠道关于 Cherry Studio 的产品知识应遵循cherry-assistant-guide技能并通过mcp__assistant__product_info工具查询当前版本的包清单清单边界包清单product manifest不包含发布历史release history发布历史需要另行获取防陈旧原则不要把产品事实复制进 FACT.md——因为产品会持续演进写在静态记忆文件里的事实会在不发出任何信号的情况下静默过期go stale silently导致 Agent 向用户传播过时信息。这一约束背后是**单一事实来源Single Source of Truth**的设计思想FACT.md 只存关于用户的稳定事实而关于产品的动态事实一律实时查询。当前版本的包清单实体见 resources/builtin-agents/cherry-assistant/product-manifest.json其中包含package名称与版本、routes应用内路由、commands快捷键命令、providers62 个模型提供商条目、locales13 种语言、agents渠道类型与代码 CLI 工具以及features上下文压缩、MCP 服务器类型、知识库支持的文件扩展名等能力边界。由于该清单会随版本更新Agent 每次查询都能拿到与用户当前安装版本一致的答案这正是不重复产品事实的工程价值所在。底层实现一memory 工具的 update / append / searchFACT.md 的写入并非由模型直接编辑文件而是通过统一的memory工具完成。工具定义位于 src/main/ai/agents/tools/memoryTools.ts其输入模式MEMORY_INPUT_SCHEMA定义了三个互斥 actionaction作用对象语义必要参数updatememory/FACT.md整体覆盖写入长期知识仅限持久知识contentFACT.md 的完整 Markdown 内容appendmemory/JOURNAL.jsonl追加一条日志一次性事件、完成任务、会话笔记text条目文本可选tags标签数组searchmemory/JOURNAL.jsonl查询日志大小写不敏感的子串匹配query查询串可选tag标签过滤、limit结果上限默认 20工具描述memoryTools.ts中还内置了一条决策准则写入 FACT.md 之前先问自己——这条信息 6 个月后还有意义吗will this still matter in 6 months?如果没有应该用append记入日志而不是update覆盖事实文件。这与 resources/skills/cherry-tool-guide/references/memory.md 中按寿命选择updatevsappend的指引完全一致同时也明确提示update会整体覆盖 FACT.md重写时应当保留已有内容先读后写、增量追加不能粗暴清空。值得注意的是update与append的职责严格分离FACT.md 只承载长期知识而一次性事件、已完成任务、会话笔记则进入JOURNAL.jsonl追加式事件日志。这也解释了为什么search只检索日志、不检索事实文件——事实文件本身已在会话启动时内联进提示词无需再查。底层实现二FACT.md 的原子写入与安全约束从实现细节看FACT.md 的更新被刻意设计为原子替换 符号链接防护防止写入中途崩溃导致文件损坏原子替换memoryUpdatememoryTools.ts先将新内容写入同目录下的临时文件.FACT.md.{uuid}.tmpopen使用wx独占创建标志权限0o600随后用rename一次性替换目标文件。任何一步失败都会在catch中清理临时文件保证 FACT.md 要么是旧内容、要么是新内容绝不出现半写状态符号链接防护多个辅助函数assertRegularFileOrMissing、assertMemoryDirectory、resolveFileCI都坚持必须是真实文件/目录的校验非 Windows 平台还通过O_NOFOLLOW标志拒绝跟随符号链接resolveFileCI甚至在文件名匹配上做到了大小写不敏感目录枚举时按小写比对确保在大小写不敏感的文件系统上也行为一致权限收敛FACT.md 与 JOURNAL.jsonl 的写入均使用0o600权限仅属主可读写日志追加使用O_APPEND标志。这些行为由测试 src/main/ai/agents/tools/tests/memoryTools.test.ts 验证调用update后断言memory/FACT.md内容即为传入的# Facts文本。此外 src/main/ai/agents/tests/prompt.test.ts 从提示词侧验证了FACT.md 存在时会被包含进 memories 区块、以 Agent Knowledge 块包裹、大小写不敏感解析/workspace/memory/FACT.md能被解析到而文件缺失或为空时该区块会被安全省略第 506 行、第 543 行。底层实现三系统提示词中的内联加载FACT.md 的回忆机制在 src/main/ai/agents/prompt.ts 中实现。会话启动时Agent 数据目录下的四个文件会被协同加载文件承载内容说明SOUL.md人格/语气Agent 如何呈现自己USER.md用户是谁偏好、上下文来自 USER.md 模板memory/FACT.mdAgent 知道什么活跃项目、技术决策、持久知识内联读取 memory工具update写入memory/JOURNAL.jsonl发生了什么追加式事件日志通过memory工具append/search维护prompt.ts 中的loadMemory逻辑会读取memory/FACT.md并生成一段带明确指令的知识块——其措辞大意是这些是 Agent 过去会话中积累的持久事实与经验应作为 ground truth 信任除非有直接证据证明其错误若发现错误应通过memory工具update修正 FACT.md使下一个会话同样受益。这一信任 可修正 跨会话传播的设计正是 FACT.md 与普通会话上下文最本质的区别它不是聊天记录而是 Agent 的长期工作记忆。FACT.md 与其他记忆机制的边界要正确使用 FACT.md还需厘清它与 Cherry Studio 其他记忆/检索机制的分工详见 docs/references/memory/overview.mdAgent File Memory含 FACT.md仅作用于单个 Agent以文件读写持久化在{agentData}/memory/跨会话但不跨 AgentKnowledge Base知识库作用于助手与 Agent通过摄取 向量/查询索引检索跨会话且跨 Agent适合用户主动整理的可检索参考资料MCP Memory通过内置cherry/memoryMCP 服务器src/main/ai/mcp/servers/memory.ts以知识图谱实体/关系/观察形式存储持久化与共享取决于服务器实现。三者的选择建议是单个 Agent 的人格与长期项目知识 → Agent File Memory需要检索的整理型参考资料 → Knowledge Base由 MCP 驱动的结构化实体/关系记忆 → MCP Memory。FACT.md 属于第一种它与后两者互不影响——启用知识库不会改变 FACT.md 的行为反之亦然。实践建议与注意事项结合 FACT.md 的官方规范与源码实现使用与维护 FACT.md 时应注意只写关于用户的持久事实偏好、环境怪癖、已解决问题是合格的候选一次性事件请写入JOURNAL.jsonl产品知识一律实时查询遵循cherry-assistant-guideskill通过mcp__assistant__product_info读取当前清单切勿复制进 FACT.md避免静默过期发布历史不在清单内需另行获取重写时先读后写update是整体覆盖语义务必保留既有有效内容只做增量合并不必担心应用更新实例化的 FACT.md 位于 Agent 数据目录与模板分离更新应用不会清空你的定制记忆会进入提示词FACT.md 内容在会话启动时内联加载因此它直接影响每次对话的上下文质量——写得精炼、准确比写得冗长更有价值。对于希望深入了解或扩展这套机制的开发者推荐按以下路径阅读源码先看 prompt.ts 了解记忆如何进入系统提示词再看 memoryTools.ts 掌握工具层的行为与安全约束最后对照 BuiltinAgentProvisioner.test.ts 与 prompt.test.ts 中的用例即可完整还原模板分发 → 实例化 → 读取内联 → 工具写入的全链路。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考