Cherry Studio 内存机制全解析Agent 文件记忆、知识库与 MCP Memory 的选型与实现【免费下载链接】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 为 Agent 提供了三套相互独立、可并存的记忆机制以SOUL.md/USER.md/FACT.md/JOURNAL.jsonl为核心的 Agent 文件记忆Agent File Memory、面向助手与 Agent 的知识库Knowledge Base以及基于内置cherry/memoryMCP 服务器的图记忆MCP Memory。三者在服务对象、持久化方式和存储位置上完全不同启用其一不会影响其他。本文以 docs/references/memory/overview.md 为骨架结合仓库源码逐层剖析每一套机制的内部实现并说明 v1 时代全局记忆Global Memory为何被移除、v2 中应当用什么替代。三种记忆机制总览Cherry Studio 目前提供三套不同的记忆机制它们各自的适用对象、持久化方式与存储位置可归纳为下表记忆类型适用对象持久化方式存储位置跨会话跨 AgentAgent 文件记忆Agent File MemoryAgent文件读写SOUL.md/USER.md/FACT.md/JOURNAL.jsonlAgent 数据目录{agentData}/memory/是否按 Agent 隔离知识库Knowledge Base助手 Agent索引化检索摄入 向量/查询索引知识库目录是是MCP 记忆MCP MemoryAgentMCP 协议内置cherry/memory服务器MCP 服务器memory.json知识图谱是取决于服务器实现三者的核心差异在于为谁服务与如何落盘Agent 文件记忆以普通文件形式把记忆存放在单个 Agent 自己的数据目录里只对该 Agent 可见知识库是用户主动整理的文档集合任何助手与 Agent 都可以通过知识检索工具查询MCP 记忆通过 MCP 协议把实体/关系/观察entities / relations / observations写入memory.json知识图谱是否共享取决于 MCP 服务器的具体实现。关于 v1 全局记忆Global MemoryCherry Studio v1.x 曾存在第四套机制——Global Memory一个位于设置中的开关配置键feature.memory.enabled开启后模型会自动从助手对话中提取持久性事实并在后续助手会话中回忆这些事实。该功能在v2 中被移除对应 upstream issue #14250移除理由是其搭建过程复杂而产出质量不足以抵消带来的开销。因此 v2 的设置中刻意不再提供 Global Memory 开关且目前没有替代它的新功能。如果你在 v1 中依赖 Global Memory迁移建议如下对 Agent改用Agent 文件记忆——它通过USER.md承担同样的记住用户信息职责且按 Agent 隔离作用域对助手Assistant把持久性事实写进助手的系统提示词prompt或在知识库中人工维护直到后续新功能落地。机制一Agent 文件记忆仅 Agent 可用四类记忆文件的职责划分Agent 的数据目录下有四类文件承载身份与记忆跨工作区、跨会话生效文件职责更新方式{agentData}/SOUL.mdHOW——Agent 如何呈现自己名称、个性、语气、沟通风格未配置 Agent 系统提示词时还充当角色定义Read Edit 工具{agentData}/USER.mdWHO——用户是谁姓名、偏好、时区、个人上下文Read Edit 工具{agentData}/memory/FACT.mdWHAT——活跃项目、技术决策、持久知识6 个月以上内联读取 mcp__agent-memory__memory的 update 动作{agentData}/memory/JOURNAL.jsonlWHEN——一次性事件、会话笔记追加型日志仅限mcp__agent-memory__memory工具append / search 动作这套文件布局与使用规则直接由 src/main/ai/agents/prompt.ts 中的memoriesTemplate模板写入 Agent 的系统提示词。模板还内置了关键规则当前工作目录是会话工作区session workspace不是 Agent 数据目录读写SOUL.md/USER.md必须使用提示词中给出的绝对路径每个文件职责唯一禁止在不同文件间重复信息SOUL.md与USER.md会被加载进上下文需要更新时直接读取/编辑FACT.md也会被内联加载但只能通过mcp__agent-memory__memoryaction: update更新JOURNAL.jsonl不会被加载进上下文只能通过mcp__agent-memory__memory追加条目或搜索历史事件禁止直接读写该文件文件名大小写不敏感。记忆如何被加载进系统提示词从 PromptBuilder 的实现可以看到两条加载路径buildMemoriesSectionsrc/main/ai/agents/prompt.ts会话开始时加载SOUL.md、USER.md与FACT.md三个文件的内容分别包裹进soul、user、facts标签内拼接到系统提示词中文件不存在时对应段落自动省略。buildFactsSectionsrc/main/ai/agents/prompt.ts专门加载memory/FACT.md生成 ## Agent Knowledge 段落这是跨会话学习闭环的回忆侧——Agent 通过mcp__agent-memory__memory的 update 动作写入持久知识下一会话开始时被加载回来例如之前失败的参数形态、项目约定、用户的纠错。值得注意的安全设计readCachedFilesrc/main/ai/agents/prompt.ts会拒绝符号链接、校验文件必须位于期望的根目录内、并以 mtime 为基础做 30 分钟 TTL 的内容缓存防止路径逃逸与频繁磁盘 IO。此外Agent 首次启动时若检测到尚未完成引导bootstrap会注入引导指令要求 Agent 在SOUL.md与USER.md的精确绝对路径写入人设与用户画像文件见 src/main/ai/agents/prompt.ts 与 src/main/ai/agents/bootstrap.ts。底层实现memory 工具的三个动作Agent 对 FACT/JOURNAL 的自主更新通过mcp__agent-memory__memory工具完成其核心实现位于 src/main/ai/agents/tools/memoryTools.ts。工具输入模式定义如下// MEMORY_INPUT_SCHEMA节选见 memoryTools.ts#L60-L81 { action: update | append | search, // 必填 content: string, // FACT.md 的完整 Markdown 内容update 必填 text: string, // 日志条目文本append 必填 tags: string[], // 日志条目标签append 可选 query: string, // 搜索关键词——大小写不敏感的子串匹配search 用 tag: string, // 按标签过滤search 可选 limit: number // 最大返回条数默认 20search 用 }三个动作的底层语义update写 FACT.md将content整体覆盖写入memory/FACT.md。实现采用原子替换先写入临时文件.FACT.md.uuid.tmp权限 0o600写完后rename到目标路径任何失败都会清理临时文件并抛出ToolErrormemoryTools.ts。工具描述明确要求 Agent 写 FACT 前自问这条知识 6 个月后还重要吗不重要就改用 append。append追加日志以追加模式打开memory/JOURNAL.jsonl每行追加一个 JSON 对象{ts: ISO时间戳, tags: [], text: ...}memoryTools.ts。search检索日志逐行解析JOURNAL.jsonl按 tag 精确匹配、query 大小写不敏感子串匹配过滤取最近limit条倒序返回遇到损坏行会跳过并告警日志不存在时返回 No journal entries found.memoryTools.ts。安全方面该模块对符号链接做了严格防御withNoFollow在非 Windows 平台为文件打开加上O_NOFOLLOW标志resolveFileCI与assertMemoryDirectory均拒绝符号链接文件/目录防止记忆文件被软链到目录外memoryTools.ts。agent-memory MCP 服务器的接入方式mcp__agent-memory__memory之所以带mcp__agent-memory前缀是因为该工具通过一个内置 MCP 服务器暴露src/main/ai/mcp/servers/agentMemory.ts 用createNeutralToolMcpServer把上述memoryTool包装成名称为agent-memory、版本1.0.0的 MCP 服务器并绑定当前 Agent 的agentId与agentDataPath。由 src/main/ai/runtime/agentMcpServers.ts 可知agent-memory与cherry-tools、skills、mcp-manager一起作为主机工具默认注入到每一个Agent 的 MCP 服务器集合中且通过 allowlist 自动预批准无需逐次确认见 src/main/ai/runtime/claudeCode/settingsBuilder.ts 与 src/main/ai/toolApproval/builtinToolPolicy.ts。单元测试 src/main/ai/mcp/servers/tests/agentMemory.test.ts 完整覆盖了该服务器的行为契约可作反向验证仅暴露memory一个工具update原子写入 FACT.md 且不留.tmp残留文件append 与 search 支持按 tag 过滤返回最近条目倒序日志文件不存在时返回稳定提示update 缺 content、append 缺 text 均报错所属 Agent 被删除后getAgent返回 null拒绝一切记忆访问非 Windows 平台下FACT.md、JOURNAL.jsonl 为符号链接或 memory 目录为符号链接时全部拒绝操作。机制二知识库助手 Agent 均可使用知识库是用户主动整理的文档集合每个库拥有独立的摄入ingestion与检索索引。与 Agent 文件记忆最大的不同是知识库的检索不是自动的——模型必须主动选择调用知识检索工具knowledge lookup tools才会命中任何助手与 Agent 都能查询同一个库因此它是三套机制中唯一天然跨 Agent 共享的参考记忆。知识库的完整体系SQLite 承载的库与条目状态、知识库自有源文件、按库派生的索引、持久化摄入任务、渲染进程 IPC 与 Agent 检索工具见 docs/references/knowledge/其中 knowledge-service.md 介绍当前后端形态operation-guards.md 说明addItems/deleteItems/reindexItems的守卫与恢复语义workflow-architecture.md 讲解基于 JobManager 的持久化任务调度与崩溃语义。机制三MCP 记忆基于cherry/memory知识图谱服务器结构与存储位置内置的cherry/memoryMCP 服务器实现于 src/main/ai/mcp/servers/memory.ts它以memory.json知识图谱文件为存储介质图谱由三类元素构成{ entities: [ { name: Alice, entityType: person, observations: [prefers tea] } ], relations: [ { from: Alice, to: Cherry Studio, relationType: uses } ] }memory.json的默认路径由配置键feature.mcp.memory_file决定在 src/main/core/paths/pathRegistry.ts 中注册为CHERRY_HOME/config/memory.json并属于需要自动确保存在的路径shouldAutoEnsure返回 true见 pathRegistry.test.ts。构造函数也支持通过环境变量传入路径如MEMORY_FILE_PATH见 mcpTransport.test.ts相对路径会基于当前工作目录解析为绝对路径。图谱管理器的实现要点KnowledgeGraphManagermemory.ts在内存中维护entitiesMap与relations字符串化 Set并负责磁盘持久化初始化确保目录存在文件不存在时写入空图谱{entities: [], relations: []}加载时若 JSON 解析失败损坏记录错误并以空图谱重建文件一致性文件读写由async-mutex的 Mutex 串行化避免并发写损坏readGraph返回深拷贝防止外部篡改内部状态约束createRelations要求关系两端实体必须已存在否则跳过并告警addObservations对不存在的实体直接抛McpErrordeleteEntities会级联删除涉及这些实体的关系检索searchNodes对实体名、类型与观察内容做大小写不敏感子串匹配只返回两端实体都在结果中的关系openNodes按名称精确取出实体及其连接关系。服务器暴露 9 个 MCP 工具create_entities、create_relations、add_observations、delete_entities、delete_observations、delete_relations、read_graph、search_nodes、open_nodes。Agent 通过 MCP 协议调用这些工具读写记忆持久化与共享行为取决于服务器实现——内置服务器将图谱写入本地memory.json因此同一图谱文件内的记忆对使用该服务器的会话共享。如何选择三套机制的适用场景单个 Agent 的人设与长期项目知识→Agent 文件记忆。SOUL.md管身份、USER.md管用户画像、FACT.md管跨会话的持久事实全部按 Agent 隔离随 Agent 数据目录跨工作区携带需要检索的用户整理型参考材料→知识库。可被助手与 Agent 共同查询适合沉淀团队文档、手册等结构化程度低但可搜索的内容由 MCP 驱动的结构化实体/关系记忆→MCP 记忆。适合需要以图谱形式表达人—事—物之间关系的场景且可通过更换 MCP 服务器实现不同的持久化与共享策略。最后再次强调这三套机制相互独立、互不影响启用任何一个都不会自动启用或干扰其他记忆而 v1 的全局记忆开关在 v2 已彻底移除v2 没有也不计划提供等价开关——Agent 场景请使用 Agent 文件记忆助手场景请把持久事实固化到提示词或知识库中。延伸阅读记忆体系入口docs/references/memory/README.md记忆机制对比与选型docs/references/memory/overview.mdAgent 提示词组装与记忆加载src/main/ai/agents/prompt.tsmemory 工具实现src/main/ai/agents/tools/memoryTools.tsagent-memory MCP 服务器src/main/ai/mcp/servers/agentMemory.ts 与测试 src/main/ai/mcp/servers/tests/agentMemory.test.tscherry/memory知识图谱服务器src/main/ai/mcp/servers/memory.tsmemory.json默认路径注册src/main/core/paths/pathRegistry.ts知识库参考文档docs/references/knowledge/【免费下载链接】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），仅供参考