记忆

MagicFrog 给每段对话一份长期记忆：一棵 Markdown 笔记树，agent 每次会话都会读取，并可在工作推进中更新。记忆组织为五个维度，同一条笔记路径可以同时存在于多个维度——更具体的维度获胜。

五个维度

前四个构成一条覆盖链，从最泛到最具体：account < user < agent < task。同一路径存在于链上多个维度时，合并（生效）视图只保留最具体的那一份。device 在链外：它的条目是绑定这台计算机的独立行，绝不跨机器合并。

agent 与 task 条目可以用 ID 前缀放进命名空间——agent/<agentId>/notes/style.md 只作用于那个 agent，task/<taskId>/notes/progress.md 只作用于那个任务。不带 ID 前缀的路径作用于所有 agent 与任务。

记忆住在哪里

记忆就是磁盘上的纯 Markdown；一个文本编辑器就足以作为记忆客户端。每个条目是一个带最简 frontmatter 的 .md 文件：

---
revision: 3
updated: 2026-10-20T09:12:00.000Z
---
Prefer functional array methods over for loops.

• account、user、agent 与 device 条目位于 MagicFrog 数据目录的 memory/<dimension>/ 下。
• task 条目位于项目内 .magicfrog/memory/。
• revision 随每次写入递增。写入可携带期望 revision；对过期 revision 的写入会失败，而不是静默覆盖。
• device 条目额外记录一个 machine frontmatter 键，把它绑定到写入它的那台计算机；导入时保留该绑定。

旧的三层树零迁移继续可用：遗留的 machine/ 条目按设备记忆读取，遗留的 project/ 目录按任务记忆读取，原地生效。新写入永远落在规范维度上。

层即配置

每个维度都有层（layer）——维度根内部的路径约定。每个维度默认存在两层：

• core（维度根本身），以及
• skills（skills/ 前缀）。

层定义在记忆树旁边的 layers.json 里，不在引擎代码里：为团队或工作流加一层就是改一次配置，新的工作维度从不需要改引擎。

skills 层下的 Markdown 文档可作为技能源被发现，与你的仓库技能和主目录技能并列——写着「如何工作」的记忆笔记会变成可加载的技能。

记忆如何到达 agent

每次会话组装上下文之前，作用域内每个维度的生效视图被渲染进一个 <memory> 块，按最具体优先排序（task、agent、user、account，然后是 device）。记忆变化时，下一次更新替换整个块并明说，所以 agent 不会把旧视图和新视图混用。

会话贡献自己的任务绑定（载体会话的任务 ID）与花名册上所有人的 agent ID，所以每个参与者看到的是该任务的任务维度和自己的 agent 维度——而不是其他人的。

云端漫游

链上四个维度（account、user、agent、task）属于云端 profile 同步面：其可移植树就是跨机器上传下载的内容，每条目的 revision 让写入具备冲突安全。device 条目从不上传——本机记忆留在本机。

要手工搬移记忆，这棵树可导出为一组可移植的 Markdown 文件再导回；带 machine/ 或 project/ 前缀的文件分别落入 device 或 task 维度。