agentsclimarketplace

Vault keeper zy

Skill Freedomzyi/vault-keeper-zy

🤖 AI 驱动的 Obsidian 知识库自动化管家 · Zettelkasten + PARA + 渐进摘要 · 零手动维护

Install
npx -y skills add Freedomzyi/vault-keeper-zy

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

  • no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
  • 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

AI托管Obsidian知识库Skill：自动同步+卡片生命周期+健康检查，HEARTBEAT解耦

SKILL.md

9.2 KB, as published. Nobody here has run it

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       # 知识卡片必填；对话记录不填
---

标签体系

标签含义图谱颜色
#小龙虾小龙虾产出🔴 红色
#CodexCodex 产出🟣 紫色
#马维斯马维斯产出🟡 黄色
#WorkBuddyWorkBuddy 产出🟢 绿色
无标签用户直接产出⚪ 白色
#工作门店运营/绩效等—
#个人用户个人偏好—
#决策有明确结论的选择—
#技术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

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.