Cherry Studio 内置 Agent 的长期记忆机制深入解析 FACT.md 的设计与实现【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本指南聚焦 Cherry Studio 内置 AgentCherry Assistant 与 Cherry Support的跨会话长期记忆文件memory/FACT.md说明它的职责边界、持久化保证、写入与回读机制以及它和JOURNAL.jsonl、产品清单manifest之间的分工。读完本文你将理解内置 Agent 记忆目录的完整文件布局掌握哪些信息该写入 FACT.md、哪些信息必须走memory工具或查询 manifest并能从源码层面验证这套机制的实现原理。FACT.md 是什么在 Cherry Studio 的 Agent 数据目录中memory/FACT.md被定义为Long-term knowledge长期知识文件其唯一用途是存放跨会话学习到的关于用户的稳定事实例如用户偏好preferences环境特性environment quirks已解决的问题resolved issues。该文件的头部注释对此做了明确声明This file is for facts you learn about the user across sessions (preferences, environment quirks, resolved issues, etc.). It isnotoverwritten on app updates - your customizations persist.即它不会在应用升级时被覆盖用户的自定义内容会一直保留。这也是 FACT.md 与一般缓存/临时文件最本质的区别——它属于“用户数据”而非“产品数据”。当前仓库中两个内置 Agent 均携带同构的 FACT.md 模板cherry-assistant 的 FACT.mdcherry-support 的 FACT.md两者内容完全一致说明 FACT.md 是内置 Agent 的通用记忆契约而非某个 Agent 的专属配置。记忆目录的完整布局四类文件的职责分工从 PromptBuilder 的源码注释 可以完整还原 Agent 数据目录的文件布局文件语义用途更新方式SOUL.md你是谁HOW名字、性格、语气、沟通风格未配置 System Prompt 时的角色定义Read Edit 工具直接编辑USER.md用户是谁WHO姓名、偏好、时区、个人上下文Read Edit 工具直接编辑memory/FACT.md你知道什么WHAT活跃项目、技术决策、持久知识6 个月以上仍有效仅通过memory工具update动作写入memory/JOURNAL.jsonl何时发生了什么WHEN一次性事件、会话笔记追加式日志仅通过memory工具append/search这套布局的核心原则是每个文件有独占职责禁止跨文件重复信息。其中 FACT.md 与 JOURNAL.jsonl 的区别尤其关键FACT.md存放“6 个月后仍然重要的知识”由memory工具的update动作整体覆盖写JOURNAL.jsonl存放“一次性事件、已完成任务、会话笔记”由memory工具的append动作逐条追加且不加载进上下文需要时通过search查询。memory工具的描述里有一条非常实用的判据Before writing to FACT.md, ask: will this still matter in 6 months? If not, use append instead.写 FACT.md 之前先问自己这件事 6 个月后还重要吗如果否就用 append 写入日志。为什么 FACT.md 不会被应用更新覆盖这一保证并非凭空承诺而是由“内置 Agent 预置provisioning”机制的实现决定的。内置 Agent 的模板目录与用户数据目录是分离的模板存放在feature.agents.builtin路径下即仓库中的 resources/builtin-agents 目录用户实例化后产生的实际数据SOUL.md、USER.md、memory/ 等位于独立的 Agent 数据目录。builtinAgentDefinition.ts中通过getBuiltinAgentTemplateDirectory读取模板、loadBuiltinAgentDefinition解析 agent.json预置过程只负责初始化模板文件并不会在应用升级时重新覆盖已经存在的用户数据文件。这一点与 FACT.md 中 not overwritten on app updates 的声明相互印证——升级流程只同步产品侧模板尊重用户侧的既有记忆。产品知识不入 FACT.md与 manifest 的分工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-guideskill通过 MCP 工具mcp__assistant__product_info查询当前安装包的产品清单manifestmanifest 不包含版本发布历史不要把产品事实复制到 FACT.md否则它们会在没有提示的情况下悄悄过期go stale silently。这一设计背后是“单一事实来源single source of truth”原则产品事实由安装包内的 manifest 动态提供会随版本更新而自动刷新FACT.md 是用户记忆一旦写入产品事实就会与安装包脱节造成“记忆与现状不符”的陈旧问题。同理builtinAgentDefinition.ts中也有类似的设计意图内置 Agent 的展示/搜索描述由 i18n 拥有agent.builtin.cherry_assistant.description而不是在 bundle 中复制一份因为 bundle 副本会成为“易漂移的第二个事实来源”。结合内置 Agent 的职责来看cherry-support产品反馈 Agent的指令明确要求“产品回答必须以当前安装包为准”见 cherry-support 的 agent.json这正是 FACT.md 要求查询 manifest 的落地场景。写入机制memory 工具的 update/append/searchFACT.md 的写入不是通过普通文件编辑而是必须经过memory工具。该工具定义在 src/main/ai/agents/tools/memoryTools.ts输入 schema 支持三种动作参数类型说明actionstring必填update整体覆盖 FACT.md仅持久知识append追加 JOURNAL 日志条目search查询日志contentstringFACT.md 的完整 Markdown 内容update必填textstring日志条目文本append必填tagsstring[]日志条目标签可选项用于appendquerystring搜索词——大小写不敏感的子串匹配用于searchtagstring按标签过滤可选用于searchlimitinteger最大返回条数默认 20用于searchupdate原子化覆盖 FACT.mdmemoryUpdate的实现值得关注memoryTools.ts#L113-L139校验content必须为非空字符串解析memory目录并定位FACT.md大小写不敏感匹配在同一目录下创建临时文件.FACT.md.uuid.tmp以0o600权限写入新内容再次校验目录与目标文件均为“真实文件且非符号链接”通过rename(tmpPath, factPath)原子替换。这种“先写临时文件再 rename”的流程保证了即使在写入中途发生异常也不会留下半截损坏的 FACT.md异常路径中临时文件会被清理。同时withNoFollow在非 Windows 平台加入O_NOFOLLOW标志配合lstat检查isSymbolicLink()从安全角度拒绝了符号链接指向文件——防止记忆文件被链接到任意路径。测试用例 memoryTools.test.ts#L46-L54 验证了update的原子写入调用后 FACT.md 内容精确等于传入的content且返回Memory updated.。append追加式事件日志memoryAppend使用O_APPEND | O_CREAT | O_WRONLY打开JOURNAL.jsonl同样拒绝符号链接将形如{ ts: ISO 时间戳, tags: [...], text: ... }的 JSON 对象追加为一行。该文件采用JSONLJSON Lines格式天然支持追加与逐行解析。search日志检索memorySearch对每行执行JSON.parse按query大小写不敏感子串与tag精确匹配过滤最后取最后limit条并逆序返回即最新的在前。损坏的行会被跳过并记录 warning。测试 memoryTools.test.ts#L56-L64 验证了“追加三条、按 tag 搜索后返回最新优先”的行为[v2, v1]。安全护栏memory工具还包含多项路径安全校验getAgentDataPath通过agentService.getAgent校验 Agent 存在性并用assertAgentDataDirectory强制解析后的路径必须与上下文中的agentDataPath完全一致路径不匹配抛InternalErrormemory目录必须是“真实目录且非符号链接”文件名解析使用大小写不敏感匹配跨平台一致体验。这些逻辑均有测试覆盖例如 memoryTools.test.ts#L78-L83 验证了路径不匹配时抛错。回读机制FACT.md 如何进入 Agent 上下文记忆不仅要“写得进”还要“读得出”。FACT.md 的回读由 PromptBuilder 负责包含两条路径Memories 区块buildMemoriesSection始终生成## Memories小节加载 SOUL.md / USER.md / FACT.md 的内容分别包裹在soul、user、facts标签中Agent Knowledge 区块buildFactsSection专门回读memory/FACT.md生成## Agent Knowledge小节并把内容放入facts.../facts。源码注释将其描述为“跨会话学习回路的回忆侧recall side”agents write durable knowledge to FACT.md viamcp__agent-memory__memoryactionupdate, and this method loads it back into the system prompt at the start of the next session so the agent remembers what it learned.Agent 通过memory工具的 update 动作把持久知识写入 FACT.md下一次会话开始时本方法把它重新加载进系统提示让 Agent 记住它学到的东西——例如之前失败的参数形状、项目约定、用户的纠正。该区块还明确要求 Agent 把 FACT.md 内容当作 ground truth基准事实除非有直接证据表明其错误此时应通过memory工具update更新 FACT.md使后续会话同样受益。这构成了一个完整的学习闭环会话中沉淀 → 写入 FACT.md → 下个会话回读 → 纠错后再写入。此外readCachedFile实现了基于 mtime 的缓存TTL 30 分钟并对文件做了真实文件校验拒绝符号链接、路径越界校验realpath 后必须位于期望根目录内回读路径同样具备安全防护。写入准则速查综合 FACT.md 模板、memory工具说明与 PromptBuilder 的实现可归纳出以下可执行的判据信息类型是否写入 FACT.md正确去向用户偏好、环境特性、已解决问题✅ 是memory工具update6 个月后仍重要的技术决策/项目知识✅ 是memory工具update一次性事件、已完成任务、会话笔记❌ 否memory工具append到 JOURNAL.jsonlCherry Studio 产品知识功能、概念、限制❌ 否cherry-assistant-guideskill mcp__assistant__product_info查询 manifest产品发布历史❌ 否manifest 也不包含不写入记忆直接面向用户说明在 Cherry Support 场景中的实际意义本文开头提到的 FACT.md 来自 cherry-support 的模板。作为内置的“产品反馈”Agent其职责为答疑解惑、使用帮助、问题排查、反馈整理见 agent.json它面对的是大量重复出现的用户环境问题——某用户的代理配置、某平台的特有行为、某个已排查过的报错。这些正是 FACT.md 的典型适用场景跨会话记住“这位用户的网络环境”“上次排查到一半的问题状态”“用户偏好的沟通方式”从而让下一次对话无需从零开始。而“Cherry Studio 产品知识必须查 manifest”的约束则确保 Support Agent 的回答始终跟随当前安装包版本不会因为 FACT.md 里残留的旧知识而给出过时指引——这与 src/main/ai/agents/tools/memoryTools.ts 中“update 覆盖写 不重复产品事实”的设计互为表里。总结FACT.md 是 Cherry Studio 内置 Agent 长期记忆体系的核心文件它通过与 SOUL.md人格、USER.md用户画像、JOURNAL.jsonl事件日志的职责切分以及“产品事实查 manifest、用户事实写 FACT.md”的边界约定实现了三个关键保证跨会话持久、应用升级不丢失、永不陈旧。其写入路径memory工具与回读路径PromptBuilder均经过源码级安全校验符号链接拒绝、路径越界检查、原子替换、mtime 缓存并有完整的单元测试支撑。对开发者而言这套设计是一份可复用的“Agent 长期记忆”参考实现用独占文件划分记忆类型、用专用工具封装写入契约、用动态数据源取代静态复制从而避免知识过期。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio 内置 Agent 的长期记忆机制：深入解析 FACT.md 的设计与实现
Cherry Studio 内置 Agent 的长期记忆机制深入解析 FACT.md 的设计与实现【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本指南聚焦 Cherry Studio 内置 AgentCherry Assistant 与 Cherry Support的跨会话长期记忆文件memory/FACT.md说明它的职责边界、持久化保证、写入与回读机制以及它和JOURNAL.jsonl、产品清单manifest之间的分工。读完本文你将理解内置 Agent 记忆目录的完整文件布局掌握哪些信息该写入 FACT.md、哪些信息必须走memory工具或查询 manifest并能从源码层面验证这套机制的实现原理。FACT.md 是什么在 Cherry Studio 的 Agent 数据目录中memory/FACT.md被定义为Long-term knowledge长期知识文件其唯一用途是存放跨会话学习到的关于用户的稳定事实例如用户偏好preferences环境特性environment quirks已解决的问题resolved issues。该文件的头部注释对此做了明确声明This file is for facts you learn about the user across sessions (preferences, environment quirks, resolved issues, etc.). It isnotoverwritten on app updates - your customizations persist.即它不会在应用升级时被覆盖用户的自定义内容会一直保留。这也是 FACT.md 与一般缓存/临时文件最本质的区别——它属于“用户数据”而非“产品数据”。当前仓库中两个内置 Agent 均携带同构的 FACT.md 模板cherry-assistant 的 FACT.mdcherry-support 的 FACT.md两者内容完全一致说明 FACT.md 是内置 Agent 的通用记忆契约而非某个 Agent 的专属配置。记忆目录的完整布局四类文件的职责分工从 PromptBuilder 的源码注释 可以完整还原 Agent 数据目录的文件布局文件语义用途更新方式SOUL.md你是谁HOW名字、性格、语气、沟通风格未配置 System Prompt 时的角色定义Read Edit 工具直接编辑USER.md用户是谁WHO姓名、偏好、时区、个人上下文Read Edit 工具直接编辑memory/FACT.md你知道什么WHAT活跃项目、技术决策、持久知识6 个月以上仍有效仅通过memory工具update动作写入memory/JOURNAL.jsonl何时发生了什么WHEN一次性事件、会话笔记追加式日志仅通过memory工具append/search这套布局的核心原则是每个文件有独占职责禁止跨文件重复信息。其中 FACT.md 与 JOURNAL.jsonl 的区别尤其关键FACT.md存放“6 个月后仍然重要的知识”由memory工具的update动作整体覆盖写JOURNAL.jsonl存放“一次性事件、已完成任务、会话笔记”由memory工具的append动作逐条追加且不加载进上下文需要时通过search查询。memory工具的描述里有一条非常实用的判据Before writing to FACT.md, ask: will this still matter in 6 months? If not, use append instead.写 FACT.md 之前先问自己这件事 6 个月后还重要吗如果否就用 append 写入日志。为什么 FACT.md 不会被应用更新覆盖这一保证并非凭空承诺而是由“内置 Agent 预置provisioning”机制的实现决定的。内置 Agent 的模板目录与用户数据目录是分离的模板存放在feature.agents.builtin路径下即仓库中的 resources/builtin-agents 目录用户实例化后产生的实际数据SOUL.md、USER.md、memory/ 等位于独立的 Agent 数据目录。builtinAgentDefinition.ts中通过getBuiltinAgentTemplateDirectory读取模板、loadBuiltinAgentDefinition解析 agent.json预置过程只负责初始化模板文件并不会在应用升级时重新覆盖已经存在的用户数据文件。这一点与 FACT.md 中 not overwritten on app updates 的声明相互印证——升级流程只同步产品侧模板尊重用户侧的既有记忆。产品知识不入 FACT.md与 manifest 的分工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-guideskill通过 MCP 工具mcp__assistant__product_info查询当前安装包的产品清单manifestmanifest 不包含版本发布历史不要把产品事实复制到 FACT.md否则它们会在没有提示的情况下悄悄过期go stale silently。这一设计背后是“单一事实来源single source of truth”原则产品事实由安装包内的 manifest 动态提供会随版本更新而自动刷新FACT.md 是用户记忆一旦写入产品事实就会与安装包脱节造成“记忆与现状不符”的陈旧问题。同理builtinAgentDefinition.ts中也有类似的设计意图内置 Agent 的展示/搜索描述由 i18n 拥有agent.builtin.cherry_assistant.description而不是在 bundle 中复制一份因为 bundle 副本会成为“易漂移的第二个事实来源”。结合内置 Agent 的职责来看cherry-support产品反馈 Agent的指令明确要求“产品回答必须以当前安装包为准”见 cherry-support 的 agent.json这正是 FACT.md 要求查询 manifest 的落地场景。写入机制memory 工具的 update/append/searchFACT.md 的写入不是通过普通文件编辑而是必须经过memory工具。该工具定义在 src/main/ai/agents/tools/memoryTools.ts输入 schema 支持三种动作参数类型说明actionstring必填update整体覆盖 FACT.md仅持久知识append追加 JOURNAL 日志条目search查询日志contentstringFACT.md 的完整 Markdown 内容update必填textstring日志条目文本append必填tagsstring[]日志条目标签可选项用于appendquerystring搜索词——大小写不敏感的子串匹配用于searchtagstring按标签过滤可选用于searchlimitinteger最大返回条数默认 20用于searchupdate原子化覆盖 FACT.mdmemoryUpdate的实现值得关注memoryTools.ts#L113-L139校验content必须为非空字符串解析memory目录并定位FACT.md大小写不敏感匹配在同一目录下创建临时文件.FACT.md.uuid.tmp以0o600权限写入新内容再次校验目录与目标文件均为“真实文件且非符号链接”通过rename(tmpPath, factPath)原子替换。这种“先写临时文件再 rename”的流程保证了即使在写入中途发生异常也不会留下半截损坏的 FACT.md异常路径中临时文件会被清理。同时withNoFollow在非 Windows 平台加入O_NOFOLLOW标志配合lstat检查isSymbolicLink()从安全角度拒绝了符号链接指向文件——防止记忆文件被链接到任意路径。测试用例 memoryTools.test.ts#L46-L54 验证了update的原子写入调用后 FACT.md 内容精确等于传入的content且返回Memory updated.。append追加式事件日志memoryAppend使用O_APPEND | O_CREAT | O_WRONLY打开JOURNAL.jsonl同样拒绝符号链接将形如{ ts: ISO 时间戳, tags: [...], text: ... }的 JSON 对象追加为一行。该文件采用JSONLJSON Lines格式天然支持追加与逐行解析。search日志检索memorySearch对每行执行JSON.parse按query大小写不敏感子串与tag精确匹配过滤最后取最后limit条并逆序返回即最新的在前。损坏的行会被跳过并记录 warning。测试 memoryTools.test.ts#L56-L64 验证了“追加三条、按 tag 搜索后返回最新优先”的行为[v2, v1]。安全护栏memory工具还包含多项路径安全校验getAgentDataPath通过agentService.getAgent校验 Agent 存在性并用assertAgentDataDirectory强制解析后的路径必须与上下文中的agentDataPath完全一致路径不匹配抛InternalErrormemory目录必须是“真实目录且非符号链接”文件名解析使用大小写不敏感匹配跨平台一致体验。这些逻辑均有测试覆盖例如 memoryTools.test.ts#L78-L83 验证了路径不匹配时抛错。回读机制FACT.md 如何进入 Agent 上下文记忆不仅要“写得进”还要“读得出”。FACT.md 的回读由 PromptBuilder 负责包含两条路径Memories 区块buildMemoriesSection始终生成## Memories小节加载 SOUL.md / USER.md / FACT.md 的内容分别包裹在soul、user、facts标签中Agent Knowledge 区块buildFactsSection专门回读memory/FACT.md生成## Agent Knowledge小节并把内容放入facts.../facts。源码注释将其描述为“跨会话学习回路的回忆侧recall side”agents write durable knowledge to FACT.md viamcp__agent-memory__memoryactionupdate, and this method loads it back into the system prompt at the start of the next session so the agent remembers what it learned.Agent 通过memory工具的 update 动作把持久知识写入 FACT.md下一次会话开始时本方法把它重新加载进系统提示让 Agent 记住它学到的东西——例如之前失败的参数形状、项目约定、用户的纠正。该区块还明确要求 Agent 把 FACT.md 内容当作 ground truth基准事实除非有直接证据表明其错误此时应通过memory工具update更新 FACT.md使后续会话同样受益。这构成了一个完整的学习闭环会话中沉淀 → 写入 FACT.md → 下个会话回读 → 纠错后再写入。此外readCachedFile实现了基于 mtime 的缓存TTL 30 分钟并对文件做了真实文件校验拒绝符号链接、路径越界校验realpath 后必须位于期望根目录内回读路径同样具备安全防护。写入准则速查综合 FACT.md 模板、memory工具说明与 PromptBuilder 的实现可归纳出以下可执行的判据信息类型是否写入 FACT.md正确去向用户偏好、环境特性、已解决问题✅ 是memory工具update6 个月后仍重要的技术决策/项目知识✅ 是memory工具update一次性事件、已完成任务、会话笔记❌ 否memory工具append到 JOURNAL.jsonlCherry Studio 产品知识功能、概念、限制❌ 否cherry-assistant-guideskill mcp__assistant__product_info查询 manifest产品发布历史❌ 否manifest 也不包含不写入记忆直接面向用户说明在 Cherry Support 场景中的实际意义本文开头提到的 FACT.md 来自 cherry-support 的模板。作为内置的“产品反馈”Agent其职责为答疑解惑、使用帮助、问题排查、反馈整理见 agent.json它面对的是大量重复出现的用户环境问题——某用户的代理配置、某平台的特有行为、某个已排查过的报错。这些正是 FACT.md 的典型适用场景跨会话记住“这位用户的网络环境”“上次排查到一半的问题状态”“用户偏好的沟通方式”从而让下一次对话无需从零开始。而“Cherry Studio 产品知识必须查 manifest”的约束则确保 Support Agent 的回答始终跟随当前安装包版本不会因为 FACT.md 里残留的旧知识而给出过时指引——这与 src/main/ai/agents/tools/memoryTools.ts 中“update 覆盖写 不重复产品事实”的设计互为表里。总结FACT.md 是 Cherry Studio 内置 Agent 长期记忆体系的核心文件它通过与 SOUL.md人格、USER.md用户画像、JOURNAL.jsonl事件日志的职责切分以及“产品事实查 manifest、用户事实写 FACT.md”的边界约定实现了三个关键保证跨会话持久、应用升级不丢失、永不陈旧。其写入路径memory工具与回读路径PromptBuilder均经过源码级安全校验符号链接拒绝、路径越界检查、原子替换、mtime 缓存并有完整的单元测试支撑。对开发者而言这套设计是一份可复用的“Agent 长期记忆”参考实现用独占文件划分记忆类型、用专用工具封装写入契约、用动态数据源取代静态复制从而避免知识过期。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考