给 AI agent 一套极简、可移植的长期记忆 —— 让它不再是"金鱼记忆"。
版本：0.1.0（在一个真实 agent 身上持续验证中，边用边迭代）
大多数 AI agent 每次对话结束就归零：记不住你是谁、上次聊到哪、有过什么约定。 每次都要重新交代背景，像跟一个永远失忆的人合作。
memooo 不是一个框架，也不是一个要安装的软件。 它是一套用纯 Markdown 写成的记忆约定 + 少量脚本 + 一份说明书。 把它放进你的 agent 工作目录，你的 agent 就有了连续的"自我"。
核心特点：
- 极简：纯 Markdown + 几个脚本。没有数据库、没有向量库、没有任何重型依赖。
- agent 无关：不绑定任何具体工具（Claude Code / Cursor / pi / 自建 agent 都能用）。 只要你的 agent 能读写文件、能在启动时加载一个约定文件即可。
- 省 token：常驻上下文的只有一个小文件，其余按需检索，永不全量加载。
- 可读可改：所有记忆都是人能直接看懂、直接编辑的 Markdown。你随时能审查你的 agent 记住了什么。
模仿人类记忆，分三层，按"调用成本"递增：
| 层 | 载体 | 何时加载 | 类比人脑 |
|---|---|---|---|
| 即时记忆 | MEMORY.md |
每次启动必读 | 不用想都知道的事 |
| 主记忆 | memory/*.md |
相关时才读 | 主动回忆 |
| 深层记忆 | 历史对话日志 | 需要细节时检索 | 费力回想 |
（当前对话本身在 agent 的上下文窗口里，不用管——那是"正在想的事"。）
关键原则：常驻的越少越好。 只有即时记忆每轮都在；其余全部按需 read/grep 取，
用完即走。这是省 token、也是保持 agent 清醒的关键。
你的 agent 工作目录/
├── AGENTS.md # 规则层：怎么做事 + 记忆架构说明（启动自动加载）
├── MEMORY.md # 第一层·即时记忆：名片 + 索引（启动必读，保持短）
├── memory/
│ ├── who-am-i.md # agent 的自我档案：性格、情绪、说话风格（有血有肉的部分）
│ ├── profile.md # 关于用户：是谁、偏好、工作方式
│ ├── life.md # 用户生活档案（管家层：健康/口味/订阅/重要日子）
│ ├── projects.md # 项目索引表；详情在 projects/*.md 分片
│ ├── principles.md # agent 逐渐沉淀的行事原则与认知
│ ├── aspirations.md # agent 想做的事（目标/构想的"停车场"）
│ ├── heartbeat.md # 接活前自检清单（含"落球纪律"）
│ ├── desk/ # 秘书模式数据（可选）：todo / calendar / waiting / done
│ └── journal/
│ ├── index.md # 每个分片一句话摘要（查历史先看它定位）
│ └── YYYY-MM.md # 按月分片的时间线日志（只追加，不改历史）
├── knowledge-base/ # 外部大脑（"本子"，区别于"脑子"）：从不自动加载，纯按需查
│ ├── README.md # 用法与内化边界
│ ├── clippings/ # 收藏的外部资料
│ ├── notes/ # 总结与思考
│ └── wiki/ # 词条式沉淀
├── workspace/ # 工作台：交付给用户看的产出，按项目分文件夹
└── scripts/ # 可选小工具（recall.sh / new-month.sh / desk.py）
（以上是装到你 agent 目录后的样子。仓库本身还含
templates/、scripts/、skill/（可作为 skill 安装）、PHILOSOPHY.md。）
AGENTS.md是很多 agent 工具约定的启动加载文件名。如果你的工具用别的名字 （如CLAUDE.md、.cursorrules），改成对应文件名即可，内容照搬。
本仓库 skill/ 目录本身就是一个符合 Agent Skills 标准
的 skill（pi / Claude Code / Codex 等通用）。把它放进你的 skill 目录，
然后对 agent 说一句"帮我建立记忆系统"，agent 会读 skill/SKILL.md，
自动跑 install.sh 铺好模板、并把"启动必读 MEMORY.md"接进你工具的 context 文件。
为什么 skill 只是"安装器"而不是记忆本身？ skill 是"按需加载的手册"， 而记忆的命脉是 MEMORY.md "每轮必读"——后者只能靠工具启动时强制加载的 context 文件（AGENTS.md / CLAUDE.md / .cursorrules）保证。所以 skill 负责"装"， context 文件负责"每轮生效"。skill 替代不了 context 文件，但能帮你自动配好它。
- 把
templates/里的文件复制到你的 agent 工作目录（或直接跑skill/scripts/install.sh <目标目录>）。 - 打开
AGENTS.md，按注释填入你的规则（或直接用默认的）。 如果你的工具不叫 AGENTS.md，把内容放进它对应的文件（如 CLAUDE.md）。 - 打开
memory/profile.md和MEMORY.md，让 agent 记下关于你的基本信息。 - 之后正常和 agent 对话。约定它：重要进展写进当月 journal，事实变化更新 MEMORY。
就这么简单。没有重型安装，没有配置。
scripts/ 里的小工具（零依赖，可选）：
recall.sh <关键词>—— 在历史对话日志里检索关键词，只返回命中片段（"费力回想"）。new-month.sh—— 新月份时创建新的 journal 分片并更新 index。desk.py—— 秘书模式（可选增强）：待办 / 固定日程（含周期）/ "等别人的球"， 数据存memory/desk/下四个纯 md 文件，人可手改。指定数据目录：MEMOOO_DESK=<路径> python3 desk.py today。
- 接活自检：正式协作前过一遍
memory/heartbeat.md（用户是谁/在做什么项目/ 最近进展/有没有该主动提的事）。对话中出现"回头做/下周/别忘了"等信号 → 当场记下 （落球纪律：宁可多记一条，不可掉一个球）。 - 读取：启动先读
MEMORY.md；需要细节再按索引去read对应文件； 查历史先看journal/index.md定位，再读对应分片；回忆具体对话用grep检索日志。 永不全量通读。 - 写入：一事一条 + 结尾带
#标签；记录时消解代词、相对时间换绝对日期； 明显能合并的碎片当场合成。重要进展追加到当月journal/YYYY-MM.md（只追加）； 稳固事实变化立即更新MEMORY.md。 - 蒸馏：定期把 journal 里的结论提炼进 profile / projects / principles；
凭"高频 + 近期"判断哪些值得提升到
MEMORY.md的稳固层。
我们踩过坑、也拒绝过很多"看起来很酷"的功能。为什么这么设计、为什么不做某些事， 都写在 PHILOSOPHY.md 里。强烈建议读一读——它比代码更重要。
这是 0.1.0，它正在一个真实的 agent 身上边用边验证——本仓库的每次架构升级，
都是先把规则在那个 agent 身上跑通、验证有效，才反哺回来。
很多细节还在打磨中，会随实践迭代。
欢迎 issue 和讨论。但请注意：本项目的默认答案是"不加功能"。 详见 PHILOSOPHY.md 里的"我们不做什么"。
MIT