Cherry Studio 内置 Agent 长期记忆机制解析FACT.md 的设计原则、持久化保障与产品知识边界【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本文以 Cherry Studio 仓库中内置 Agent 的长期记忆文件 FACT.md 为核心剖析内置「产品反馈」AgentCherry Support跨会话记忆的设计哲学哪些用户事实值得长期保存、为什么应用更新不会抹掉你的自定义内容、以及为什么 Cherry Studio 的产品知识必须走「当前安装包清单」而非写死在记忆文件里。读完本文你将理解 Cherry Studio 内置 Agent 记忆体系的职责分层掌握维护长期记忆的实操规范并能在二次开发内置 Agent 时正确设计自己的记忆文件。FACT.md 在 Cherry Studio 内置 Agent 体系中的定位Cherry Studio 在resources/builtin-agents/目录下内置了两套 Agent每套都包含同一套「身份三件套」cherry-support/产品反馈 AgentCherry Support中文名「产品反馈」定位是答疑解惑、使用帮助、问题排查、反馈整理与提交cherry-assistant/通用助手 AgentCherry Assistant。两套 Agent 各自维护SOUL.md人格与语气、USER.md关于用户的默认交互约定以及memory/FACT.md长期记忆。以 Cherry Support 的 agent.json 为例它声明了type: claude-code、builtin_role: support并挂载了cherry-assistant-guide、faq-collector、cherry-studio-feedback、issue-reporter四个技能。注意 agent-template.json 才是「事实来源」source of truth仓库注释明确指出agent.json由pnpm build:builtin-knowledge生成不要直接编辑生成产物。在这套体系中FACT.md 承担的是用户级长期记忆——它不是产品说明书而是 Agent 在一次次会话中逐渐积累的、关于「你这个用户」的事实库。它与USER.md的分工很清晰USER.md存放的是默认交互约定如「未请求技术解释时先用分步 UI 指导」「根据用户消息中体现的经验水平调整细节」并明确标注这些是 not verified personal facts未经核实的个人事实而 FACT.md 记录的是经过会话验证的持久事实例如偏好、环境怪癖、已解决的问题。长期记忆的职责边界FACT.md 里该写什么FACT.md 的英文注释用三组关键词界定了写入范围This file is for facts you learn about the user across sessions (preferences, environment quirks, resolved issues, etc.)即跨会话记录三类事实preferences偏好用户偏好的回复语言、详略程度、命名习惯、工具使用习惯等environment quirks环境怪癖用户设备或环境中的特殊现象例如特定代理配置、网络限制、本地模型异常、目录结构习惯等resolved issues已解决的问题曾经发生并被解决过的问题及其结论避免未来重复排查。这三类事实的共同特征是跨会话仍然有效。这正好呼应了仓库中 memory 工具参考 给出的判断标准——「六个月后这件事还重要吗」能长期存续的偏好与决策走update覆盖整个持久事实文件一次性事件走append追加到日志。FACT.md 在文件层面就是那个「持久事实文件」而USER.md中的身份与作用域信息则不应被当作个人事实写入见 USER.md产品、Agent、账户、设备和工作区元数据「describe their own scopes; they do not identify the user」。持久化保障应用更新不会覆盖你的自定义FACT.md 中最重要的一条承诺是It isnotoverwritten on app updates - your customizations persist.这是记忆文件与产品知识文件在设计上的根本区别product-manifest.json、agent.json等随构建生成的文件在升级时会被新版本替换而memory/FACT.md是用户数据属于跨会话、跨版本存续的个性化资产。这意味着用户可以放心地把自己的长期偏好交给 Agent 记录不必担心一次应用升级就让 Agent「失忆」。结合 memory 工具参考 的语义还可以推导出配套的维护规范由于update是整文件覆盖updateoverwrites the whole fact fileAgent 在更新 FACT.md 时必须先读取当前内容、在保留既有条目的基础上增量追加而不是清空重建——「Preserve existing durable content when you rewrite it — add to it, dont clobber it」。这条「先读后写、增量合并」的纪律正是 FACT.md 能长期积累而不丢失历史的关键。产品知识不走 FACT.md以当前安装包清单为准FACT.md 接着划出一条严格的边界For Cherry Studio product knowledge, follow thecherry-assistant-guideskill and query the current package manifest throughmcp__assistant__product_info.也就是说凡是涉及 Cherry Studio 产品本身的知识功能、路由、快捷键、Provider、语言、Agent 能力等一律不写入 FACT.md而是通过技能与工具实时查询当前安装包。这条设计在 cherry-assistant-guide/SKILL.md 中被贯彻为第一原则不要凭训练数据、记忆或本文件中的旧描述回答 Cherry Studio 产品问题。每个独立的产品问题都先读取当前安装包信息。查询方式是按 section 读取随当前构建打包生成的 product-manifest.json路由 / 页面入口mcp__assistant__product_info({ source: manifest, section: routes }) 快捷键mcp__assistant__product_info({ source: manifest, section: commands }) Providermcp__assistant__product_info({ source: manifest, section: providers }) 语言mcp__assistant__product_info({ source: manifest, section: locales }) Agent / 频道 / 定时任务 / Code CLImcp__assistant__product_info({ source: manifest, section: agents })不知道该查哪个 section 时先调用不带 section 的紧凑索引只返回当前版本号和可用 section 名称再按需读取对应 section只有问题确实横跨多个 section 时才用section: all避免把整份清单塞进上下文。以当前仓库的 manifest 为例providerssection 记录了随包支持的 62 个 Provider如 OpenAI、Anthropic、Gemini、DeepSeek、Ollama 等routes.primary列出 9 个主导航入口/app/agents、/app/chat、/app/paintings、/app/translate、/app/mini-app、/app/knowledge、/app/files、/app/code、/app/notesroutes.all还包含内部页、参数路由与兼容跳转不能无条件推荐。这条机制的价值在于单一事实来源产品知识随构建生成、随版本演进Agent 每次回答都以「当前安装包」为准天然不会因版本升级而过期。在信息优先级上当前包清单 官方文档 模型记忆发生冲突时清单优先于旧文档与模型记忆。避免静默过期为什么不能把产品事实复制进 FACT.mdFACT.md 最后一条给出原因与告诫The manifest does not include release history. Do not duplicate product facts here, or they will go stale silently.两个要点manifest 不包含发布历史。这一点与仓库结构一致发布历史由独立数据单独维护见 release-history.jsonproduct-manifest.json 中只有schemaVersion、package、routes、commands、providers、locales、agents、features等当前版本事实不承载版本演进信息。重复复制产品事实会「静默过期」。这是记忆设计中最容易踩的坑如果 Agent 把「某功能入口在哪」「默认快捷键是什么」写进 FACT.md那么当新版本改变了路由或快捷键时FACT.md 里的旧描述不会报错、不会提醒只会无声地失效——而 Agent 却仍可能优先读取这条「看似权威」的本地记忆导致答非所问。相比而言mcp__assistant__product_info每次返回的都是随包生成的最新清单从机制上杜绝了过期问题。因此 FACT.md 的维护者应当遵循一条简单的「分流原则」凡是以当前安装包为事实来源的问题一律走技能与 MCP 工具查询只有无法从安装包获得、且跨会话有效的用户级事实才写入 FACT.md。这正是「长期记忆」与「产品知识」两种数据在生命周期上的本质区别——前者随用户存续后者随版本迭代。实操建议维护高质量 FACT.md 的四个要点综合上述设计与仓库中的记忆工具语义实践中维护 FACT.md 可以遵循以下规范先读后写增量合并。由于更新是整文件覆盖写入前必须先读取现有条目在保留既有内容的基础上追加或修订绝不重建清空依据memory 工具参考。只写跨会话有效的用户事实。偏好、环境怪癖、已解决问题是三类首选一次性事件应走日志追加append而不是长期事实文件。按「六个月后是否仍重要」筛选。存续性判断是 update持久事实与 append事件日志的分水岭也是 FACT.md 内容质量的试金石。产品问题一律交给cherry-assistant-guide与mcp__assistant__product_info绝不在 FACT.md 中复制功能、路由、快捷键等产品事实防止静默过期。参考的条目组织方式格式建议非仓库现成模板可以是分组罗列# Long-term knowledge ## Preferences - 用户偏好中文回复技术解释优先给出可验证的步骤 ## Environment quirks - 用户当前网络需走本地代理外连 Provider 偶发超时 ## Resolved issues - 问题 X 已解决原因是配置 Y修复方式为 Z对于想要基于 Cherry Studio 二次开发内置 Agent 的开发者这套设计同样提供了可复制的范式用户记忆与产品知识分离、动态清单与静态事实分离、以「会静默过期」为戒杜绝冗余副本——这三条原则比任何具体格式都更能决定一个 Agent 长期可用的上限。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考