Vault keeper zy

vault-keeper-ZY

AI 自动维护的 Obsidian 知识库 Skill。融合 Zettelkasten + PARA + Progressive Summarization + Karpathy 五层记忆方法论。

设计原则

1. skill 只做 vault 内部操作，跨 agent 协调留在 HEARTBEAT
2. 幂等设计，重复执行不产生重复内容
3. 零配置理想，但提供配置入口
4. 失败不中断，单项失败不影响后续流程

边界定义

vault-keeper-ZY 负责（纯 vault 内部）

• 对话记录写入 + 更新
• 知识卡片创建/更新/生命周期管理
• 渐进式摘要（Layer 1→2→3→4）
• MOC（对话总览）自动维护
• 标签索引自动维护
• vault 统计更新
• 健康检查（断链/孤儿/过期/待办/重复）

HEARTBEAT.md 保留（跨 agent 协调）

• 触发时机的决策（启动补偿/心跳/结束信号）
• Codex 内容扫描 + WorkBuddy 扫描
• 灵魂备份 + 兜底检查
• 踩坑日志扫描
• 月度知识库分析（提炼 Skill/教程/SOP）
• .learnings 检查 + promote

目录结构

Vault/
├── 对话总览.md              ← MOC 索引，skill 自动维护
├── 对话记录/                ← Layer 3：原始对话摘要
│   └── YYYY-MM-DD 主题.md
├── 知识卡片/                ← Layer 2：原子化知识点
│   └── 主题名.md
├── 待办追踪/                ← 行动层
│   └── 待办事项.md
├── 日常笔记/                ← 🔒 只读，不碰
├── 收件箱/                  ← 用户随手记，心跳时处理
├── 参考资料/                ← 外部资料归档
├── 项目中心/                ← 长期项目管理
└── 模板/                    ← 笔记模板

笔记规范

YAML Frontmatter

---
date: YYYY-MM-DD          # 创建日期
tags: [标签1, 标签2]       # 必须打标签，含产出者标签
aliases: [别名]            # 可选
status: active|review|stale|archived   # 必填
expires: YYYY-MM-DD       # 知识卡片必填；对话记录不填
---

标签体系

标签	含义	图谱颜色
#小龙虾	小龙虾产出	🔴 红色
#Codex	Codex 产出	🟣 紫色
#马维斯	马维斯产出	🟡 黄色
#WorkBuddy	WorkBuddy 产出	🟢 绿色
无标签	用户直接产出	⚪ 白色
#工作	门店运营/绩效等	—
#个人	用户个人偏好	—
#决策	有明确结论的选择	—
#技术	AI 工具/系统配置	—
#生活	日常闲聊	—
#MOC	索引页	—
#待办	待办事项	—

卡片归属规则

• 用户主动投喂文件/文档 → 无标签（白色产出）
• 用户给链接让深挖 → 挖到的算 AI 本人产出，加对应标签

命名规范

• 对话记录: YYYY-MM-DD 主题关键词.md（2~3个关键词串联，≤40字）
• 知识卡片: 以主题命名，≤20字

链接规范

• 对话→卡片：用 [[知识卡片/主题名]]
• 卡片→对话：用 （见 [[对话记录/YYYY-MM-DD]]）
• 卡片→卡片：用 [[知识卡片/相关主题]]
• MOC 索引按月分组

知识卡片质量标准

• ✅ 必须有 YAML frontmatter（tags 必填）
• ✅ 必须有 ## 相关 段落，至少 2~3 个 [[双向链接]]
• ✅ 内容以结论/决策为导向，不是流水账
• ✅ 引用对话来源
• ❌ 禁止空壳卡片
• ❌ 禁止全盘复制对话原文

知识生命周期管理

status 状态机：
创建时 → active（在用）
        ↓ expires 到期
        → stale（待审核）
        ↓ 用户审核
        ├── 更新续期 + 重置 expires → active
        ├── 仍可用但需复查 → review
        └── 确认无用 → archived（保留文件但降低搜索权重）

自动归档条件（基于文件 mtime）：
- 文件最后修改时间距今 ≥180 天 → 标记 stale，写入健康报告
- 被新卡片明确替代
- 用户确认淘汰
⚠️ 禁止自动删除任何卡片——归档只改 status，不删文件
⚠️ 判断逻辑：读取知识卡片目录下所有 .md 文件 mtime，与当前时间比较

同步规则

触发时机（由 HEARTBEAT 调用，skill 不关心何时触发）

条件	优先级	说明
🟢 启动补偿	补漏	网关启动后首次收到消息
🟡 心跳定期	常规	每次心跳结束时
🔴 结束信号	即时	用户说结束语

增量写入

1. 基于 lastSeq 增量抓取新会话
2. 话题识别：提取话题 → 决策 → 待办 → 知识点
3. 当日已有对话文件 → 追加新话题，不重写旧内容
4. 尚无 → 新建，含 YAML frontmatter

卡片创建规则

• 同一主题被 ≥3 次对话提及 或 有明确决策/结论 → 创建知识卡片
• 已有卡片 → 追加更新，标注 updated 时间
• 单次最多创建 5 张新卡片（防止话题泛滥）
• 已有同类内容 → 互补追加，不另起炉灶（查重）

反重复机制

1. 写入前 wiki_search / memory_search 确认无重复
2. 发现同类内容 → 在原卡片上互补追加，标注补充人
3. 入库后追加一行到 系统/入库更新日志.md

健康检查

每周

1. 断链检测：扫描所有 [[链接]] 是否指向存在的文件
2. 孤儿笔记：找出零反向链接的知识卡片
3. 重复检测：相似主题标记潜在合并
4. 过期检测：检查 mtime，7天内到期标 ⏳，≥180天未修改标 ❌ stale
5. 待办清理：已完成标删除线，30天不动归档
6. MOC 一致性检查
7. 报告写入 系统/健康报告 YYYY-MM-DD.md

每月（第一个周一）

• 知识合并建议、过期处理、项目复盘、标签审查

每季度（第一个周一）

• 知识结构审查、目录健康、标签体系审查、MEMORY 质量审查

Hook 挂载点

Hook	触发	返回值
on-heartbeat-end	每次心跳结束	{synced: bool, errors: string[]}
on-session-end	结束信号触发	{synced: bool}
on-startup	网关启动	{ok: bool}

HEARTBEAT 检查返回值中的 errors 数组，非空则记录告警，不阻塞后续流程。

状态文件

位置：memory/vault-keeper-state.json

{
  "lastSeq": 174,
  "lastSyncDate": "2026-06-28",
  "nextHealthCheck": "2026-07-05",
  "lastHealthReport": "2026-06-28"
}

错误处理

错误场景	处理方式
vault 目录不存在	跳过同步，记录 error，不下次心跳重试直到目录创建
YAML frontmatter 解析失败	跳过该文件，继续其他操作，error 写日志
单个文件写入失败	不中断流程，记录 error
会话历史 API 超时	等下次心跳重试，不丢 lastSeq

安装

# 1. 拷贝 skill 到 OpenClaw 的 skills 目录
cp -r vault-keeper-zy ~/.openclaw/skills/

# 2. 在 HEARTBEAT.md 的任务列表中注册 hook 调用点
# 3. 重启 OpenClaw gateway

依赖

• OpenClaw v2026.6+
• 工具：sessions_history, wiki_search, wiki_get, wiki_apply, wiki_lint
• Obsidian 知识库目录（通过环境变量或配置文件指定）

许可证

MIT

🔧 执行层 — Python 工具箱

确定性操作通过 scripts/vault_tools.py 执行，AI 负责语义层（话题识别、内容创作），脚本负责机械层。

安装依赖

pip install pyyaml  # 可选，内置解析器已覆盖常规场景

命令一览

命令	功能
python scripts/vault_tools.py validate <vault>	YAML frontmatter 校验
python scripts/vault_tools.py broken-links <vault>	[[wikilink]] 断链检测
python scripts/vault_tools.py orphans <vault>	零反向链接卡片检测
python scripts/vault_tools.py duplicates <vault>	相似文件名/内容检测
python scripts/vault_tools.py expired <vault>	过期 + 长期未改卡片检测
python scripts/vault_tools.py moc <vault>	生成/更新 对话总览.md
python scripts/vault_tools.py stats <vault>	生成 vault 统计.md
python scripts/vault_tools.py health <vault>	运行完整健康检查，生成报告
python scripts/vault_tools.py template card <title>	输出知识卡片 YAML 模板
python scripts/vault_tools.py template conversation <date> <title>	输出对话记录模板

AI 与脚本分工

层面	谁负责	说明
话题识别	AI	从会话中提取话题、决策、待办
内容创作	AI	写摘要、提炼知识点
文件写入	AI	用 write/file_write 写 md 文件
YAML 校验	脚本	确定性检查 frontmatter 合规
断链/孤儿/重复	脚本	可靠的静态分析
MOC 更新	脚本	从文件系统自动生成索引
过期检测	脚本	mtime + expires 字段检查
健康报告	脚本	聚合所有检查结果

Hook 实现映射

on-heartbeat-end → AI 执行同步 + python vault_tools.py health
on-session-end   → AI 执行同步 + python vault_tools.py validate
on-startup       → AI 执行 python vault_tools.py validate

许可证

MIT