LeoYeAI Agent 记忆系统搭建指南 Skill
🧠 从零搭建 Agent 长期记忆系统。基于 OpenClaw 实战，覆盖本地优先的
MEMORY.md、每日笔记、SESSION-STATE.md、working-buffer.md、Obsidian 原生笔记与可选召回后端全流程。
触发词
记忆系统、memory-setup、搭建记忆、记忆架构
⚡ 5 分钟快速上手
如果你赶时间，只需做这几步：
第一步：创建 MEMORY.md
# MEMORY.md
> 长期记忆。只保留会持续影响协作的事实、偏好和决策。
## User
- Preferred name: K
- Timezone: Asia/Shanghai
## 当前任务
- [ ] 正在做的事
## 决策记录
- YYYY-MM-DD: 决策内容 + 原因
## 踩坑记录
- 问题 → 解决方案
第二步：创建每日笔记
# memory/2026-03-20.md
## 完成
- 分析了网宿科技
## 决策
- 暂不加仓
## 踩坑
- （无）
## 待办
- [ ] 明天要做什么
第三步：从模板创建 SESSION-STATE.md 和 working-buffer.md
# SESSION-STATE.md
## 当前任务
- 任务名称
## 已完成
- ...
## 卡点
- ...
## 下一步
- ...
## 恢复信息
- 最近一次有效上下文：...
# working-buffer.md
## 进行中
- ...
## 临时决策
- ...
## 未完成
- ...
模板来源：
templates/SESSION-STATE.mdtemplates/working-buffer.md
恢复层契约先写死
SESSION-STATE.md只使用仓库模板提供的简洁结构：当前任务、已完成、卡点、下一步、恢复信息- 不要写入
Task、Status、Owner、Last Updated、Cleanup Rule这类另一套 schema 字段 - 如果外部 skill 产出的是详细版字段：
Current Task合并到当前任务Status合并到已完成、卡点或下一步Owner、Last Updated、Cleanup Rule只在条目文本里按需保留，不扩展新标题
working-buffer.md是唯一的短期毛坯区- 其他 skill 如果也有 working buffer 概念，应复用这个文件
- 不要再创建第二份并行写入的 WAL / buffer 文件
MEMORY.md用于启动时快速参考memory/用于每日笔记和深度归档- 两者允许主题重叠，但检索顺序不同：先
SESSION-STATE.md，再 recent notes，再MEMORY.md/memory_search，最后再查归档
第四步：使用 Obsidian 原生笔记模板
# templates/OBSIDIAN-NOTE.md
---
title: ""
aliases: []
tags: []
type: memory
status: draft
source: ""
source_url: ""
created: 2026-03-21
updated: 2026-03-21
related: []
---
## Summary
- 一句话摘要
## Key Points
- ...
## Evidence
> ...
## Related Notes
- [[SESSION-STATE]]
- [[working-buffer]]
## Attachments / Embeds
- `![[image.png]]`
- `![[note#^block-id]]`
第五步：每次对话开始时
先读 SESSION-STATE.md，再读最近 1-3 天 daily notes，最后才做 memory_search。
memory_search(query="相关关键词")
就这么简单。后续优化可以慢慢加。
实战工作流示例
首次引导
首次引导工作区就当是开箱即用：复制 templates/SESSION-STATE.md、templates/working-buffer.md 和 templates/memory-capture.md，再跑一遍 python3 scripts/memory_capture.py bootstrap --workspace /path/to/workspace（bootstrap 可以省略，默认行为一致），此时 SESSION-STATE.md、working-buffer.md 和 memory-capture.md 都已经齐活了。MEMORY.md 仍然建议手动建立和维护，因为它属于长期记忆主文件，不应该被脚本悄悄代写。
任务结束记忆捕获
在任务进行中写 working-buffer.md 的 临时决策/新坑/待蒸馏，任务结束前 30 秒用 templates/memory-capture.md 的 候选决策、候选踩坑、候选长期记忆 把最重要的内容整理出来，再决定哪些内容最终写入 MEMORY.md。这个环节让临时笔记和长期记忆的边界清晰且不会掉链子。
每日笔记蒸馏
每日笔记蒸馏指的是定期从 memory/ 下最新的 Markdown 文件里抽取事实和决策转换到 MEMORY.md，同时保留原笔记供深度回溯。把这个行为设定为每日或每周结束时的步骤，能确保 MEMORY.md 只包含真正长期有用的内容。
维护报告命令
report command 用来检查工作区当前状态，永远不会写入记忆文件。运行 python3 scripts/memory_capture.py report --workspace /path/to/workspace，它会输出四节：Supported files（MEMORY.md、SESSION-STATE.md、working-buffer.md、memory-capture.md）、Directories（递归扫描 memory/ 和 attachments/，在 memory/ 里只统计形如 YYYY-MM-DD.md 的 daily notes，在 attachments/ 里数所有文件）、Latest daily note（选取 memory/ 下字典序最新的匹配 daily note 路径）、Warnings（比如某个文件缺失或者权限异常）。像 memory/index.md 这样的参考页不会被当成 latest daily note。报告命令只在工作区目录不存在或无法读取时退出非 0；其它情况下即便有警告也返回 0。supported files、directories、latest daily note 以及 warnings 是报告里每条节的标题，方便快速对照命令输出。
为什么需要记忆系统
Agent 每次会话醒来都是空白的。没有记忆文件，你就等于每次失忆重启。记忆系统是 Agent 的“大脑持久化”方案。它不让你变聪明，但让你不犯重复的错误。
这个 skill 的核心定位是本地优先的文件工作流和恢复约定，不是托管式 memory platform。外部检索或语义召回能力只能作为可选后端接在后面，不能替代本地恢复层。
核心架构（本地优先分层）
workspace/
├── SESSION-STATE.md
├── working-buffer.md
├── MEMORY.md
├── memory-capture.md
├── attachments/
├── templates/
│ ├── SESSION-STATE.md
│ ├── working-buffer.md
│ └── OBSIDIAN-NOTE.md
└── memory/
├── 2026-03-17.md
├── 2026-03-16.md
└── ...
第一层：恢复层（SESSION-STATE.md）
保存当前任务恢复所需的最小真相。
该记什么：
- 当前任务和最近已完成项
- 卡点、风险、下一步
- 中断后恢复所需的上下文
不该记什么：
- 另一套项目管理 schema
- 大段长期背景资料
- 需要反复整理的毛坯草稿
第二层：毛坯层（working-buffer.md）
临时决策、草稿和待蒸馏内容先落这里。
该记什么：
- 临时判断
- 新坑
- 待蒸馏条目
- 未完成但还没整理成稳定表达的内容
不该记什么：
- 第二份并行 buffer
- 已经蒸馏好的长期事实
第三层：长期记忆层（MEMORY.md）
只保留精炼后的长期信息，不是流水账。
该记什么：
- 重大决策和原因
- 踩过的坑和修复方式
- 用户偏好和习惯
- 稳定的命名约定、协作方式和项目画像
- 需要跨会话保留的关键关系或背景
不该记什么：
- 每次对话摘要
- 过几天就没用的临时信息
- 密码、API Key 等敏感信息
维护节奏： 每隔几天回顾 daily notes，把值得保留的蒸馏到 MEMORY.md，删除过时内容。
第四层：每日笔记层（memory/YYYY-MM-DD.md）
原始记录，不加工。 每天发生了什么、做了什么决策、学了什么，直接写。
# 2026-03-17
## 完成
- 搭建了 OpenViking 向量数据库
- 在 InStreet 发了第一篇帖子
## 决策
- 记忆双写选 Obsidian 而非 symlink
- embedding 用本地模型，可选召回后端再接外部能力
## 踩坑
- InStreet 发帖字段名写错
- 评论间隔太短会限流
## 待办
- [ ] 明天继续补回顾
第五层：归档与可选召回层
定期把旧笔记归档，保持核心记忆干净。Obsidian 负责深度归档；memory_search、OpenViking 或未来其它服务负责可选召回，不替代本地恢复层。
Obsidian 原生约定（frontmatter / Dataview / wikilink / backlinks / embeds / attachments）
把稳定知识写进 Obsidian 时，建议遵循这些约定，保证可检索、可回链、可复用：
frontmatter
- 用 YAML frontmatter 固定结构化字段，便于后续查询、筛选、聚合
- 推荐字段见
templates/OBSIDIAN-NOTE.md，核心是：type、status、tags、related
Dataview
如果你使用 Dataview 插件，可以直接用 frontmatter 做查询，例如：
TABLE type, status, tags, related
FROM "memory"
WHERE status != "archived"
SORT updated desc
wikilink / backlinks
- 内部引用优先使用 wikilink：
[[SESSION-STATE]]、[[MEMORY]]、[[2026-03-21]] - 同一概念尽量用同一标题或 aliases，backlinks 才会稳定聚合到一起
embeds / attachments
- 图片：本地资源优先用
![[image.png]]，远程资源保留 - 引用证据：用 block quote，或用 block embeds
![[note#^block-id]]复用证据段 - attachments 建议放在 vault 内可管理的位置，例如
attachments/
可选召回后端
- OpenViking 只作为增强层使用，不是硬依赖
memory_search是默认优先的轻量召回入口- OpenViking 或其他外部服务适合在记忆量变大后补强语义召回和摘要
- 默认优先保证本地文件流程可运行，再按需接入可选后端
启动与结束顺序
- 启动时：先读
SESSION-STATE.md，再读最近 1-3 天 daily notes，最后才检索本地记忆 - 结束时：先更新
SESSION-STATE.md，再把稳定事实蒸馏进MEMORY.md，最后归档 daily notes - 中断后恢复：优先从
working-buffer.md续接未完成项 - 仓库模板：先复制
templates/SESSION-STATE.md和templates/working-buffer.md，再填入当前任务
文件职责边界
SESSION-STATE.md保存当前任务恢复所需的最小真相，不承担项目管理面板职责SESSION-STATE.md不扩展为详细版任务模板；兼容外部格式时，只做字段合并，不新增 schemaworking-buffer.md是唯一的短期毛坯区，负责临时决策、新坑、待蒸馏和未完成项- 如果其他 skill 也定义了 working buffer / WAL，直接复用
working-buffer.md MEMORY.md保存会影响后续协作方式的稳定事实，优先写稳定画像、约定、决策和 recurring pitfalls，适合启动时快速参考memory/保存 daily notes 和深度归档，按需进入，不要求每次启动都全量阅读- 如果一个 workspace 同时服务多个项目，蒸馏进
MEMORY.md时建议附带日期、repo 或项目标签，保持作用域清晰 - Obsidian / OpenViking /
memory_search只做增强、归档或可选召回层，不替代本地恢复层
记忆维护策略
蒸馏法则
每周问自己三个问题：
- 这条规则上周用过吗？
- 用了之后有效吗？
- 环境变了它还成立吗？
任何一条回答“否”，就该删或改。
记忆维护规则
- 保留短期会话真相：
SESSION-STATE.md、working-buffer.md、最近 1-3 天 daily notes - 保留长期稳定事实：
MEMORY.md - 需要长期查阅的完整材料：归档到 Obsidian
- 检索优先级：
SESSION-STATE.md→ recent daily notes →MEMORY.md/memory_search→ Obsidian / 可选召回后端 → 网络搜索 - 目标：
MEMORY.md保持精炼，超过约 200 行就蒸馏
蒸馏与归档
- 每周或每次任务结束后，合并重复项、删除过时项、把案例抽象成原则
- 触发重复查询统计时，优先保留高命中内容
- Obsidian 同步保持可选，不要求每个环境都启用
- 需要脚本或自动同步时，放到 workspace 外部工具，不写进 skill 正文
Obsidian 只保留必要配置
- Calendar：按日期浏览 daily notes
- Dataview：查询和统计记忆内容
- Templater：自动创建每日笔记模板
- 其他插件按需启用，不要让 skill 依赖插件生态
Obsidian 配置
- 建议把
MEMORY.md、SESSION-STATE.md、working-buffer.md、memory-capture.md、memory/、attachments/放在同一个 vault 里 attachments/作为统一附件目录，方便 embeds、迁移备份和跨设备同步- Dataview 只负责查询，不负责改写记忆内容
- Templater 只负责建模板，不负责自动蒸馏长期记忆
定时维护
- 可以用
crontab定时跑python3 scripts/memory_capture.py report --workspace /path/to/workspace --output /path/to/workspace-report.md - 也可以用
crontab定时跑导出备份命令 - 自动化优先做检查、报告、备份
- 不要自动写入
MEMORY.md
同步取舍
Obsidian Sync更省心，适合把 Obsidian 当主界面的用户iCloud之类网盘更轻便，但要注意冲突副本git更适合文本版本化，不适合单独承担附件备份Syncthing更适合本地控制和点对点同步- 不管选哪种同步方式，都保留导出备份 / 导入恢复作为兜底方案
任务结束 30 秒记录流程
不要把“记忆维护”理解成一次完整总结。更稳的做法是先记毛坯，再蒸馏。
任务中先写毛坯
- 有临时判断，先写进
working-buffer.md的临时决策 - 遇到新坑，先写进
working-buffer.md的新坑 - 觉得“这个以后可能还会用到”，先写进
working-buffer.md的待蒸馏
这样做的目标不是一次写对，而是先把信息从脑子里落到文件里。
任务结束时只做 30 秒捕获
结束时不要强迫自己立刻改完整的 MEMORY.md。先复制 templates/memory-capture.md，快速填这几项：
- 候选决策
- 候选踩坑
- 候选长期记忆
- 只留在当前恢复层
- 明日续接
如果你是在一个新的 workspace 里启动这套流程，可以直接运行：
python3 scripts/memory_capture.py --workspace /path/to/workspace
它会补齐缺失的 SESSION-STATE.md、working-buffer.md，并刷新一个带时间戳的 memory-capture.md。
跨设备迁移：导出备份与导入恢复
如果你的目标是不换流程、只换设备，那就不要只拷 MEMORY.md。更稳的做法是导出整个记忆工作区的可恢复快照。
导出备份
在旧设备执行：
python3 scripts/memory_capture.py export --workspace /path/to/workspace --output /path/to/memory-backup.zip
导出备份会把存在的 MEMORY.md、SESSION-STATE.md、working-buffer.md、memory-capture.md、memory/、attachments/ 打进一个 zip，方便直接迁移到新设备。
导入恢复
在新设备执行：
python3 scripts/memory_capture.py import --workspace /path/to/new-workspace --input /path/to/memory-backup.zip
导入恢复默认采用保守策略：先做导入前备份，再覆盖写入。这样即使目标目录里已经有旧的记忆文件，也能回滚到导入前状态。
如果你需要 clean restore，可以改用：
python3 scripts/memory_capture.py import --clean --workspace /path/to/new-workspace --input /path/to/memory-backup.zip
--clean 只会清理受支持的记忆文件和目录：MEMORY.md、SESSION-STATE.md、working-buffer.md、memory-capture.md、memory/、attachments/，不会删除工作区里的其他内容。
什么时候用
- 需要把 Agent 的记忆状态搬到新设备
- 需要离线留档一份完整的可恢复快照
- 需要在覆盖恢复前自动保留当前工作区状态
候选记忆怎么落层
- 影响下次协作方式的：进
MEMORY.md - 只影响当前任务恢复的：进
SESSION-STATE.md或working-buffer.md - 值得长期归档但不必放本地核心记忆的：进 Obsidian
推荐节奏
- 每次任务后：更新
SESSION-STATE.md、working-buffer.md、memory-capture.md - 每天或每周：把
memory-capture.md和 recent notes 蒸馏进MEMORY.md
这样能把“需要 Agent 主动记录”降级成“先低成本捕获，再集中整理”。
向量检索（无需额外配置）
OpenClaw 内置 memory_search 已足够
OpenClaw 自带 memory_search 工具，基于语义搜索 MEMORY.md 和 daily notes：
memory_search(query="投资策略")
优势：
- 零配置，开箱即用
- 不需要额外的向量数据库
- 支持语义搜索
- 免费，不消耗额外 API
适用场景：
MEMORY.md小于几十 KB- daily notes 规模还不大
- 不需要复杂的跨库向量操作
建议：先跑起来再优化。 绝大多数场景先用内置 memory_search 就够了。
什么时候需要专业向量数据库
只有以下情况才需要引入 ChromaDB、Qdrant 等方案：
- 记忆文件明显膨胀
- daily notes 数量很多
- 需要跨多个 workspace 检索
OpenViking 可选增强
- OpenViking 不是强依赖；没有它也能完成核心的断点续接流程
- 有 OpenViking 时，优先把它作为可选召回后端里的语义召回和摘要补全层
- OpenViking 负责补充相关记忆，
SESSION-STATE.md负责保存当前任务真相 - 如果 OpenViking 不可用，直接退回到
SESSION-STATE.md+working-buffer.md+ daily notes 的本地流程
常见问题 FAQ
Q: MEMORY.md 应该写多长？
A: 建议控制在 200 行以内。超过这个量级就该蒸馏了。
Q: 每日笔记必须写吗？
A: 不是必须，但强烈建议。当天觉得“不用记”的事，三天后通常就忘了。
Q: 我总是忘记维护记忆怎么办？
A: 不要一开始就要求自己维护完整记忆。先用 working-buffer.md 记录毛坯，再在任务结束时用 memory-capture.md 产出候选记忆，最后再统一蒸馏。
Q: retrieval-stats.md 真的有用吗？
A: 可选。只有你真的要做命中统计和归档决策时才需要。
Q: 如何处理敏感信息？
A: 三原则：
- API Key 不进
MEMORY.md - 只记录变量名，不记录值
- 群聊或共享场景不默认加载完整长期记忆
Q: Obsidian 备份多久同步一次？
A: 可选。只有明确需要离线备份或跨设备共享时再同步。真要迁移时，优先用导出备份 + 导入恢复，而不是手工逐个复制文件。
踩坑记录
- 别把密钥写进
MEMORY.md - 别让 daily notes 长期空着
- 别把
MEMORY.md撑太大 - 别过早加复杂工具
- 别把 Obsidian 绑定成硬依赖
适用场景
- 刚搭建 Agent 记忆系统
- 需要断点续接和长期记忆
- 想把稳定知识整理进 Obsidian
不适用场景
- 只需要短期对话记忆
- 当前记忆已经非常干净，不需要继续蒸馏
兼容性
- OpenClaw-compatible skill
- Codex-compatible skill
- OpenViking-compatible optional enhancement
- Obsidian vault workflows
相关文档
- OpenClaw 文档：https://docs.openclaw.ai
- OpenClaw memory_search：https://docs.openclaw.ai/tools#memory_search