/sibyl-save - 会话内存同步 + 技能提取 (Sibyl 内存插件)
本文件属于 Sibyl Labs 开放技能集合的一部分。MIT 许可。由 Sibyl Labs, LLC 构建。
这是 Sibyl 内存插件 的一个配套技能。它捕获当前会话中发生的所有内容，并通过插件自身的接口将其注入到插件本地内存数据库（~/.sibyl-memory/memory.db）中，然后将可复用的模式提取为新的技能。
它不会直接写入原始内存文件。所有内存操作都经过插件，因此层级存储、全文索引和免费层限制均得到遵守。由于该插件在每个支持的框架（Claude Code、Codex 以及任何 MCP 主机；Hermes 通过 Python SDK）上公开了相同的 MCP 工具，因此此技能天然地支持多框架。
前提条件
安装并配置 Sibyl 内存插件：
pip install sibyl-memory-cli
sibyl init # 浏览器/钱包激活，写入 ~/.sibyl-memory/
sibyl setup claude-code # 或: codex | hermes (将内存接口接入你的框架)
然后，此技能通过以下两个接口之一与插件通信：
- MCP（Claude Code、Codex、Cursor、任何 MCP 主机）：使用下面的 8 个
memory_*工具。 - Python SDK（Hermes 或任何 Python 代理）：使用
sibyl_memory_client.MemoryClient/sibyl_memory_hermes.SibylMemoryProvider。
插件接口
| 用途 | MCP 工具 | Python SDK |
|---|---|---|
| 保存事实/实体 | memory_remember(category, name, body) | client.set_entity(category, name, body) |
| 召回实体 | memory_recall(category, name) | client.get_entity(category, name) |
| 列出实体 | memory_list(category, limit) | client.list_entities(category) |
| 全文搜索 | memory_search(query, limit, tiers) | client.search(query) |
| 设置状态文档 | memory_set_state(key, body) | client.set_state(key, body) |
| 获取状态文档 | memory_get_state(key) | client.get_state(key) |
| 记录日志事件 | memory_record_event(kind, body, category, name) | client.write_event(...) |
| 归档/遗忘 | memory_forget(category, name, reason) | client.archive_entity(category, name, reason) |
以下示例使用 MCP 名称。在 Hermes 或 Python 代理上，请使用 SDK 列。
层级映射
| 会话内容 | 层级 | 调用 |
|---|---|---|
| 会话指针/摘要/待办事项 | HOT (state) | memory_set_state("session", ...) |
| 排序后的优先级列表 | HOT (state) | memory_set_state("priorities", ...) |
| 会话日志条目 | COLD (journal) | memory_record_event("session_save", ...) |
| 项目/人员/产品 | WARM (entities) | memory_remember(category, name, body) |
| 已关闭/已结束的项目 | ARCHIVE | memory_forget(category, name, reason) |
| 本技能的配置 + 增量标记 | HOT (state) | memory_set_state("sibyl_save:config" / "sibyl_save:last_save", ...) |
模式
- run（默认）：
/sibyl-save、save session、sync memory。将会话上下文注入插件，然后提供技能提取功能。 - setup：
/sibyl-save setup、/sibyl-save config。交互式。构建或编辑配置（存储在插件状态键sibyl_save:config下）。首次使用前运行一次。 - preview（空运行）：
/sibyl-save preview、/sibyl-save --dry-run。运行完整分析并报告所有计划写入的操作。不调用任何会改变数据库的操作。不推进增量标记。
模式: setup (动态配置)
目标：将配置写入插件状态键 sibyl_save:config。交互且简洁。尽可能推断；只询问必要的信息。
- 框架。检测或询问当前框架 (claude-code、codex、cursor、hermes、other)。这将决定阶段 2 写入技能文件的位置。
- 技能输出。新技能写入的位置。Claude Code 默认：
.claude/skills/<name>/SKILL.md。对于其他框架，确认技能位置和格式。存储为skill_output: {dir, format}。 - 优先级。排序列表的状态键（默认为
priorities）和上限。默认上限为 15。硬上限为 30：绝不接受超过 30 的值。超过 30 的列表是积压任务，而不是优先级列表。 - 实体类别。你跟踪的 WARM 类别（默认为
project、person、product）。用户可以添加或删除。 - 额外捕获。可选地指定每次保存时应填充的额外状态键或实体类别（如指标状态文档、联系人类别）。这是一个扩展点。
- 空运行默认设置。切换
dry_run_default（默认为 false）。 - 写入配置。通过
memory_set_state("sibyl_save:config", {...})完成。不要触碰增量标记。
配置格式：参见 examples/sibyl-save-config.example.json。重新运行 setup 会在原地编辑它。
模式: run
阶段 1: 内存同步（进入插件数据库）
步骤 0 - 加载配置和增量
memory_get_state("sibyl_save:config")。如果不存在，切换到 setup。memory_get_state("sibyl_save:last_save") 用于增量锚点（自上次保存以来的变更）。如果 dry_run_default 为 true 且未指定模式，则作为预览运行。
步骤 1 - 读取当前状态
memory_get_state("session")和memory_get_state(<priorities key>)- 对于跟踪的类别，执行
memory_list(category, limit)；对于本次会话中接触到的实体，执行memory_recall/memory_search - 配置中指定的任何额外状态键或类别
步骤 1.5 - 优先级检查与调整
读取优先级状态文档并在原地调整（通过 memory_set_state 写回）。条件及需要的操作：
- COMPLETED（已完成的项仍在列表中）：删除；通过
memory_record_event("priority_closed", {...})记录关闭事件。 - RANK_DRIFT / DUP_RANK（排名不是连续的 1..N，或存在重复排名）：重新编号为 1..N。
- OVER_CAP（条目数超过上限）：将优先级最低的项移至积压状态文档，直到不超过上限。
- STALE_ITEM（超过 14 天未处理）：向用户提示。
- TERMINAL entity（引用的实体已被归档/销毁）：关闭该优先级。
- BROKEN entity ref（指向不存在的实体）：修正为真实的
category/name。
每次写入都强制遵循上限（决不超出 30）。
步骤 2 - 分析会话
回顾自增量锚点以来的对话（若为首次保存则从会话开始）。提取：
- 接触的实体 - 创建、读取或修改的项目、人员、产品
- 采取的动作 - 实际发生的事项，附带标识符
- 做出的决策 - 战略选择及其理由
- 待办事项 - 下次会话要执行的动作，以动词开头（"部署..."、"跟进..."、"验证..."）
- 警告 - 当前风险、阻碍因素、截止日期、险些失误
- 吸取的教训 - 可改进的操作流程（这些将输入阶段 2）
- 额外捕获 - 配置中任何额外状态键/类别的数据
步骤 3 - 注入插件数据库
在 preview 模式下，不调用任何会改变数据库的操作。报告计划的写入（步骤 4）并停止。
- 会话状态 -
memory_set_state("session", { last_session, summary, forward, entities_touched, warnings })。待办事项仅为动作引用，绝不包含余额快照或任何会过时的内容。 - 日志事件 -
memory_record_event("session_save", { evaluated, acted, forward, extra })。每次保存只记录一个事件（设计上为追加模式）。 - 优先级 -
memory_set_state(<priorities key>, { updated, cap, items })，受上限限制。溢出部分移至积压状态文档。 - 实体 - 对于每个有变更的实体，执行
memory_remember(category, name, body)。新实体仅需新的memory_remember调用；插件会为它们建立索引，因此无需维护单独的注册表。 - 已关闭/已结束 -
memory_forget(category, name, reason)。 - 额外捕获 - 应用每个配置的额外状态键/类别。
- 增量标记 -
memory_set_state("sibyl_save:last_save", { ts: <现在> })。预览模式下跳过。
步骤 4 - 报告
简洁摘要：写入的实体、更新的状态文档、日志事件 ID、添加/关闭的优先级、额外捕获以及下次会话的待办事项。在预览模式下，每行都标记为“将”执行，并确认未写入任何内容。
阶段 2: 技能提取 (原生框架)
无论使用何种框架，技能的呈现方式相同：识别、提议、然后以当前框架的原生技能文件形式创建。
步骤 5 - 识别可复用模式
扫描会话中满足以下任意条件的操作：重复（本次会话中多次出现）、周期性（可能再次出现）、多步骤（3 个或更多连续步骤）、非显而易见（值得保留的变通方法）、容易出错（需要清单）。对于每个候选项目，评估名称（简短祈使动词短语）、触发词、参数、复杂性（是否有危险步骤）、频率。
步骤 6 - 提议候选
以一行摘要形式呈现每个候选，包含名称、描述和预估频率。然后询问：“创建这些？或者跳过某些？”
步骤 7 - 创建批准的技能（原生框架）
从配置中读取 skill_output 以确定此框架期望的技能位置和格式。默认值：
| 框架 | 技能位置 | 格式 |
|---|---|---|
| claude-code | .claude/skills/<name>/SKILL.md | YAML 元数据（name, description）+ Markdown 正文 |
| codex | ~/.codex/prompts/<name>.md（在 setup 中确认） | Markdown 提示 |
| cursor | .cursor/ 命令/规则（在 setup 中确认） | 遵循 Cursor 约定 |
| other | 来自 skill_output.dir | 来自 skill_output.format |
对于每个批准的技能，在配置的位置写入文件，包含触发短语、逐步说明、参数描述、任何危险步骤的安全检查以及示例调用。报告文件路径。
不得创建以下技能： 与现有技能重复（先检查技能位置）、过于针对当前会话以至于不会复现、封装单个简单命令、或需要编辑受你操作规则保护的文件（遇到此类情况应提示，而不是自行编辑）。
规则（不可协商）
- 绝不要将实时数据（余额、价格、计数）作为持久化事实存储。捕获引用，而非快照。
- 会话待办事项应为动作导向，且以动词开头。
- 每次保存只记录一个日志事件（追加模式；从不重写历史）。
- 优先级有上限（默认 15，决不超出 30）。超出部分移至积压状态文档。
- 实体通过
category+name进行寻址；让插件作为索引。无需并行注册表。 - 所有内存写入都通过插件接口进行。绝不要直接写入
~/.sibyl-memory/文件或打开memory.db：客户端会处理锁定和免费层限制。 - 将现有技能视为只读。除非明确要求，否则应创建新技能而非在原地编辑。
许可与来源
MIT（参见 LICENSE）。每个 Markdown 文件顶部的水印注释是归属和来源说明，并非使用限制。可使用 node scripts/watermark.mjs verify 验证副本。详情参见 WATERMARK.md。