企业官网建设流程全解析

Cherry Studio 内置 Agent 长期记忆机制解析：FACT.md 的设计原则、持久化保障与产品知识边界

【免费下载链接】cherry-studio🍒 Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio

本文以 Cherry Studio 仓库中内置 Agent 的长期记忆文件 FACT.md 为核心，剖析内置「产品反馈」Agent（Cherry Support）跨会话记忆的设计哲学：哪些用户事实值得长期保存、为什么应用更新不会抹掉你的自定义内容、以及为什么 Cherry Studio 的产品知识必须走「当前安装包清单」而非写死在记忆文件里。读完本文，你将理解 Cherry Studio 内置 Agent 记忆体系的职责分层，掌握维护长期记忆的实操规范，并能在二次开发内置 Agent 时正确设计自己的记忆文件。

FACT.md 在 Cherry Studio 内置 Agent 体系中的定位

Cherry Studio 在resources/builtin-agents/目录下内置了两套 Agent，每套都包含同一套「身份三件套」：

• cherry-support/：产品反馈 Agent（Cherry Support），中文名「产品反馈」，定位是答疑解惑、使用帮助、问题排查、反馈整理与提交；
• cherry-assistant/：通用助手 Agent（Cherry 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.)

即跨会话记录三类事实：

1. preferences（偏好）：用户偏好的回复语言、详略程度、命名习惯、工具使用习惯等；
2. environment quirks（环境怪癖）：用户设备或环境中的特殊现象，例如特定代理配置、网络限制、本地模型异常、目录结构习惯等；
3. 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 file"），Agent 在更新 FACT.md 时必须先读取当前内容、在保留既有条目的基础上增量追加，而不是清空重建——「Preserve existing durable content when you rewrite it — add to it, don't 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" }) Provider：mcp__assistant__product_info({ source: "manifest", section: "providers" }) 语言：mcp__assistant__product_info({ source: "manifest", section: "locales" }) Agent / 频道 / 定时任务 / Code CLI：mcp__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/notes），routes.all还包含内部页、参数路由与兼容跳转，不能无条件推荐。

这条机制的价值在于单一事实来源：产品知识随构建生成、随版本演进，Agent 每次回答都以「当前安装包」为准，天然不会因版本升级而过期。在信息优先级上，当前包清单 > 官方文档 > 模型记忆；发生冲突时，清单优先于旧文档与模型记忆。

避免静默过期：为什么不能把产品事实复制进 FACT.md

FACT.md 最后一条给出原因与告诫：

The manifest does not include release history. Do not duplicate product facts here, or they will go stale silently.

两个要点：

1. manifest 不包含发布历史。这一点与仓库结构一致：发布历史由独立数据单独维护（见 release-history.json），product-manifest.json 中只有schemaVersion、package、routes、commands、providers、locales、agents、features等当前版本事实，不承载版本演进信息。
2. 重复复制产品事实会「静默过期」。这是记忆设计中最容易踩的坑：如果 Agent 把「某功能入口在哪」「默认快捷键是什么」写进 FACT.md，那么当新版本改变了路由或快捷键时，FACT.md 里的旧描述不会报错、不会提醒，只会无声地失效——而 Agent 却仍可能优先读取这条「看似权威」的本地记忆，导致答非所问。相比而言，mcp__assistant__product_info每次返回的都是随包生成的最新清单，从机制上杜绝了过期问题。

因此 FACT.md 的维护者应当遵循一条简单的「分流原则」：凡是以当前安装包为事实来源的问题，一律走技能与 MCP 工具查询；只有无法从安装包获得、且跨会话有效的用户级事实，才写入 FACT.md。这正是「长期记忆」与「产品知识」两种数据在生命周期上的本质区别——前者随用户存续，后者随版本迭代。

实操建议：维护高质量 FACT.md 的四个要点

综合上述设计与仓库中的记忆工具语义，实践中维护 FACT.md 可以遵循以下规范：

1. 先读后写，增量合并。由于更新是整文件覆盖，写入前必须先读取现有条目，在保留既有内容的基础上追加或修订，绝不重建清空（依据：memory 工具参考）。
2. 只写跨会话有效的用户事实。偏好、环境怪癖、已解决问题是三类首选；一次性事件应走日志追加（append），而不是长期事实文件。
3. 按「六个月后是否仍重要」筛选。存续性判断是 update（持久事实）与 append（事件日志）的分水岭，也是 FACT.md 内容质量的试金石。
4. 产品问题一律交给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