shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 开发与工程API Key 暂未确认

save-memory

保存记忆到本地 MemOS 记忆引擎并立即评分。当用户明确要求「记住/保存/记一下」，或任务产出重要结论/解决方案/踩坑解法，或发生重要配置变更时触发；写入成功后紧接着给该记忆打分。

person作者: MerlinShiehhubgithub
open_in_new仓库download下载资源包

保存记忆（save-memory）

把一条值得长期保留的事实/结论写入本地记忆索引（AgentMemHub 内置 rag 引擎）。写入成功即完成： 价值分由来源初始分起步（importance 档位：high 0.8 / normal 0.6 / low 0.4）， 之后随真实使用（👍/👎 反馈）演化。

触发约束（最高优先）

用户主动提醒加入记忆时，必须立即触发本 Skill——包括但不限于「记一下」「记住这个」 「保存一下这个处理方式」「这个值得记」「以后遇到还按这个来」等任何明确或隐含的保存意图。 此类请求不经任务收尾自查、不打折、不延后：当轮就走完 探活 → memory_save。 （任务产出可复用结论时的自动触发，见下方「生效前提」的 AGENTS.md 硬规则。）

生效前提（安装后必须配置，二者缺一不可）

本 Skill 不是放进 skills 目录就能自动运转，它依赖两个前提：

前提 1：AGENTS.md 硬规则（触发保障）

Skill 的触发依赖模型自觉，实践证明长对话/高负载下会漏触发。安装本 Skill 后， 必须把下面这条硬规则添加进当前项目的 AGENTS.md，或当前 Agent Harness 的 全局指令文件（如 ~/.zcode/AGENTS.md、~/.config/opencode/AGENTS.md、~/.qwen/QWEN.md）：

记忆保存纪律（硬性规则）：任务收尾时自查：本次是否产出可复用结论 （问题解决步骤 / 踩坑解法 / 架构决策 / 关键配置变更）？命中即必须走 save-memory 流程（memory_stats 探活 → memory_save）， 只写 Agent 本地会话记忆不算完成。

没有这条规则，Skill 只是"能力"而非"义务"，会在最需要它的时候被遗忘。

前提 2：agentmemhub MCP 服务（强绑定，执行保障）

本 Skill 与 agentmemhub MCP 服务强相关、强绑定：写入、评分、检索全部经由 其 MCP 工具完成，Skill 自身不含任何存储实现，也没有降级路径—— MCP 未配置或不可见时，本 Skill 完全无法执行（此时应提醒用户配置，而不是改用 其它方式保存）。MCP 服务信息见下表。

绑定的 MCP 服务

本 Skill 不自带任何存储实现，所有读写经由 agentmemhub MCP server 完成：

| 项 | 值 | |---|---| | MCP server 名 | agentmemhub | | 提供工具 | memory_stats · memory_save · memory_score · memory_search · memory_recent | | 服务源码 / 安装 | https://github.com/MerlinShieh/AgentMemHub | | stdio 启动 | python -m agentmemhub mcp | | HTTP 常驻启动 | python -m agentmemhub mcp --http --port 9100 | | 底层引擎 | AgentMemHub 内置 agentmemhub.rag（进程内直调，无独立服务/端口/鉴权） |

引擎与 MCP 的启停归用户管理，本 Skill 只读写、不启停。

在 harness 里这些工具叫什么（排查「工具不可见」的关键）

上表列的是 MCP server 的原始工具名。多数 harness 会把它们命名空间化后再 暴露给模型，常见形式是 mcp__<serverName>__<原名>：

| 原始名 | harness 中常见的公开名 | |---|---| | memory_stats | mcp__agentmemhub__memory_stats | | memory_save | mcp__agentmemhub__memory_save | | memory_search | mcp__agentmemhub__memory_search |

排查「看不到工具」时必须按前缀找：只搜 memory_save 会得出「MCP 没配上」的 错误结论，而工具其实早已挂好——实测踩过这个坑：误判十余轮去查配置/解析/日志， 最后发现只是名字带了 mcp__<serverName>__ 前缀。正确做法是先列出本会话可用 工具、按 agentmemhub 或 mcp__ 过滤，再判断是否真的缺失。

处理逻辑归属（本 Skill 为什么这么"薄"）

本 Skill 仓库刻意只做行为协议（何时保存、按什么顺序保存+评分）， 不含任何评分/量化实现——找逻辑请到绑定的两个上游仓库去：

| 环节 | 实现位置 | 职责 | |---|---|---| | 何时保存 | 本仓库 SKILL.md + AGENTS.md 硬规则 | 触发纪律（说明书，零代码） | | 引擎预检 | 本仓库 scripts/check_engine.py | 唯一脚本：探活（读 AgentMemHub 配置判断后端与就绪态） | | 写入/评分转发 | AgentMemHub 仓库 agentmemhub/mcp_server.py（_save/_score） | 把 MCP 工具调用翻译成引擎 API（feedback 极性分 + 已评清单 + r_task 同步） | | LLM 批量评估 | AgentMemHub 仓库 agentmemhub/scoring.py（CLI agentmemhub score） | 三轴评估出极性（入口已隐藏，当前不生效） | | 量化计算 | agentmemhub/rag/（内置引擎，memstore.put_feedback） | 收到 feedback 后立即重算 value / r_human / priority（写入侧做确定性聚合，打分策略在 AgentMemHub 侧） |

解耦边界：Skill 仓库=行为协议，AgentMemHub=适配层，agentmemhub.rag=计算引擎。

调用前检查（必做，顺序执行）

  1. Harness 限制检查：先读当前项目根的 AGENTS.md 与当前 Agent Harness 的 用户级全局指令（如 ~/.zcode/AGENTS.md、~/.config/opencode/AGENTS.md、 ~/.qwen/QWEN.md），确认其中没有与本 Skill 冲突的约束 （例如「禁止自动写入外部服务」「只允许使用内置记忆」「本会话不落盘」等）。 冲突时以 Harness 限制为准，跳过本流程并告知用户原因。
  2. MCP 可用性：本会话必须能看到上表所列的 agentmemhub 工具； 缺失则提醒用户在当前 harness 中配置 agentmemhub MCP server 后停止，不硬写。
  3. 引擎探活：调用 memory_stats；不可用时按返回的提示处理—— 内置 rag 引擎无守护进程，"启动引擎"即"建立索引"：在 AgentMemHub 项目内跑 python -m agentmemhub sync（采集 + 向量化写入），之后即可读写。 也可先在终端跑本仓库的预检脚本：python scripts/check_engine.py。

使用步骤

1. 写入记忆

调用 MCP 工具 memory_save，content 写一条自包含的结论： 包含背景一句话 + 结论/做法，例如： 「【运维】XX 项目嵌入模型为 bge-small-zh-v1.5（随仓库分发）；换用更大模型时 用 scripts/fetch_model.py 下载并在 agentmemhub.yaml 的 rag.models 注册。」

可选：用 importance 顺手给个档位。 这一步用你当前的推理直接判断即可—— 比事后外挂模型批量评分更准，也不额外花任何成本：

| 档位 | 起始分 | 什么时候用 | |---|---|---| | high | 0.8 | 技术沉淀、踩坑解法、架构决策、关键配置变更；用户明确要求记住的 | | normal | 0.6 | 一般结论（默认，不传就是这个）| | low | 0.4 | 临时性、局部细节、很快会过时的 |

两点约束：

  • 档位只定起点，之后仍由真实使用（👍/👎 反馈）演化，不是终身标签；
  • 别滥用 high——若什么都标 high，档位就失去区分度，与「写后即评」被废除 是同一个道理。拿不准就用默认的 normal。

memory_save 成功返回 id=<trace_id>；若返回「写入未生效/失败」，直接告知用户 （无需评分，因为记忆没落库）。

可选：note 写一句话意图（例：note="记录这次踩坑的根因"）。只进审计日志， 不影响存储与检索——"做了什么"由服务端自动记，"为什么"只有你知道。见「操作留痕」节。

2. 写入即完成（不自动评分，2026-09-11 起）

memory_save 成功返回 id=<trace_id> 后本 skill 流程结束——不要紧接着调 memory_score 打 positive：

  • 价值分起点由来源决定（Agent 主动写入 0.6），之后由真实使用演化 （面板 👍/👎 反馈）；
  • 写后自动打 positive 会让同一意图被计两次（0.6 → 顶格 1.0），全部记忆 挤在同一分值、丧失区分度（2026-09-11 实测定案，用户确认废除）；
  • 例外：用户明确说「这条很重要/以后优先用」时，才调 memory_score 打 positive，或建议用户在面板 ⭐ 加权（锁定不衰减）。

importance 与 memory_score 的区别（别混淆）： importance 是写入时对起点的判断——可选、一次性、不进反馈账本； memory_score 是事后对实际效果的确认——按需、计入反馈聚合、会重算 value。 所以「给档位」不等于「评分」，本节的不自动评分规则依然成立。

3. 批量评分（已下架，勿再推荐）

python -m agentmemhub score 的入口已在控制台/面板隐藏、当前不生效 （实测多为 neutral/全跳过）——不要再建议用户跑它。

操作留痕（审计日志，不需要你手动写）

每一次 MCP 记忆调用都已由服务端自动记录。 你不需要、也不应该手动追加日志—— 这条路刻意不依赖模型自觉：长对话/高负载下"记得写日志"必然漏，而审计的价值 全在完整性（漏一条，就无法区分"没做"和"没记"）。记录点在 MCP server 的工具 分发层，stdio 与 Streamable HTTP 两种传输都覆盖，与调用方是否记得无关。

| 项 | 值 | |---|---| | 文件 | AgentMemHub 程序根 logs/mcp.log（JSONL，一行一条，只追加） | | 每次调用 | 两条：phase=call（工具/参数/时刻）与 phase=result（成败/耗时/结果摘要），以 call_id 关联 | | 记录内容 | 工具名、参数摘要、结果摘要、耗时、成败、agent 标识 | | 不记录 | 正文全文（已在记忆库；凭结果里的 trace_id 可回查） |

你能补的是"为什么"：memory_save / memory_search / memory_score 都带一个 可选的 note 参数，写一句话意图即可（例：note="排查用户说的召回异常"）。 它只进审计日志，不参与检索与存储。服务端记"做了什么"，note 补"为什么"。

查询（在 AgentMemHub 程序根执行）：

python scripts/mcp_log.py                     # 最近 20 次调用
python scripts/mcp_log.py --tool memory_save  # 只看写入
python scripts/mcp_log.py --failed            # 只看失败/无响应
python scripts/mcp_log.py --grep 关键词        # 搜参数/结果/意图
python scripts/mcp_log.py --call <call_id>    # 某次调用全貌

--failed 里若出现"只见 call 不见 result"的记录，代表那次调用发起了却没有返回 （超时或进程中断）——这是审计刻意保留的信息，不要当成噪音。

检索怎么触发（不是本 skill 的职责）

检索与保存无关：需要历史经验时直接调用 MCP 工具 memory_search（模型自触发）—— 例如新任务开始、用户问的问题疑似以前解决过、要复用某段配置/结论时。

注意事项

  • 不要保存一次性/临时内容（如本次具体的修复文件名列表）；保存「结论 + 关键步骤」。
  • 同一条结论措辞不同可能重复入库（引擎按内容幂等，但表述差异会生成新 id）； 保存前如不确定可先 memory_search 同名话题，命中高度相似就跳过。
  • 引擎离线时 memory_save/memory_score 会明确报错（isError），按报错提示处理即可。