前言¶

做多轮 Agent 时，常见做法是把对话塞进向量库，或在上下文里堆历史摘要。任务一长，容易出现三类问题：临时指令被当成长期偏好、旧事实和新事实同时被检索出来、以及不同用户或项目之间的记忆混在一起。SkillHub 上的 统一 Agent 记忆与知识管理系统（坐标 @user_fa4109f3/agentmemory-v2，当前版本 5.0.0）不是单独的记忆服务二进制，而是一套基于通用 SKILL.md 的规范与操作指南：用七种记忆分类、写入/读取门控、版本化事实和分层目录，把「记什么、记在哪、何时取用、何时失效」写清楚。它合并了早期 agent-memory 与 self-improvement 系列实践，并纳入 arXiv:2606.24775 的工程结论与 7-Type Memory 架构说明（见 Skill 内更新日志）。

这是什么¶

一句话定位：面向 Agent workload 的记忆数据基础设施设计文档 + 会话协议，供 Cursor、Claude Code、Codex 等支持 Skills 的客户端在启用后按同一套目录与流程治理记忆。

• 出品与分发：SkillHub 社区 Skill，发布者 user_fa4109f3，分类 ai-agent，标签 requires_api_key=false（无需 API Key 即可安装规范本身）。
• 解决的问题：把「保存聊天记录」升级为可更新、可检索、可维护、可评测的记忆治理——包括分类、门控、Query Planner、时间感知评测维度，以及 HOT/WARM/COLD 与学习捕获、Constitutional AI 自我批评、经验推广等配套流程。

核心功能¶

以下能力均来自 Skill 包内 SKILL.md（v5.0.0）与 SkillHub 页面简介，按模块归纳。

四层架构¶

从 Agent Runtime（工作记忆）→ Memory Service（抽取、分类、去重、检索、写/读门控）→ Storage Layer（短期库、向量、图、Git、调度等分工）→ Eval and Governance（写入/检索/使用评测、隔离、删除审计、程序记忆回归、时间感知评测）。

M_sys = ⟨R, S, Q, U⟩¶

用表示与存储（R）、抽取（S）、检索与路由（Q）、维护（U）四层定位故障点，避免只看最终回答分数。

七种记忆分类¶

工作、语义、情节、程序、检索、参数、前瞻；并规定典型落点（如 MEMORY.md、YYYY-MM-DD.md、procedures/、向量库、权重、调度器等）。访问频率维度：HOT / WARM / COLD 及 .learnings/ 学习记录目录结构。

版本化事实（Versioned Facts）¶

事实带 scope、validFrom / validTo、supersededBy、sourceEpisodeId、confidence 等字段，用 supersede 与失效时间避免 append-only 带来的「过去事实幻觉」。

写入门控与读取门控¶

区分长期语义记忆与仅属当前任务的工作记忆；读取侧推荐 scope 过滤、语义/关键词检索、时间与置信度过滤、rerank。

Query Planner¶

按查询类型（当前状态、历史轨迹、事实召回、过程追踪、多跳组合）走不同检索路径。

局部维护与升降级¶

局部合并、保守合并、热度驱动的 HOT/WARM/COLD 升降级（如 7 天内使用 3 次升 HOT、30 天未用降 WARM 等），以及 project > domain > global 的冲突解决顺序。

学习捕获与经验推广¶

在 .learnings/ 下按类型记录错误、纠正、知识缺口、成功模式等；纠正话术有明确检测规则；recurrence_count >= 3 时可推广到 SOUL.md、MEMORY.md 或技能创建（文档中说明需评测后再合入程序记忆）。

自我批评（Constitutional AI）¶

对重要回复可走「生成 → 自我批评 → 修订」流程，并列出优先级原则。

程序化接口（文档约定）¶

SKILL.md 中给出 Python SDK 示例（AgentMemory，库路径 ~/.agent-memory/memory.db）与 HTTP API 示例（python3 scripts/memory_store.py，端口 8768，库 ~/.openclaw/workspace/data/agent_memory.db，Jaccard 语义搜索、TTL 等）。当前从 SkillHub 安装的包仅包含 SKILL.md 与元数据，不含上述脚本源码；若要在本地跑 API/SDK，需按文档自行实现或从其它仓库补齐，不宜假设安装即自带可执行服务。

其它¶

分阶段建设路线图（MVP → 语义 → 情节 → 程序 → 前瞻 → 参数）、开源方案选型表、会话开始/结束/压缩前协议、安全边界（不记敏感信息、scope 隔离等）。页面简介还提到 SQLite 存储与 TTL 衰减，与 v1/v4 合并 lineage 一致。

安装与启用¶

下面介绍在 SkillHub 上安装到当前 Agent 可识别的 skills 目录。安装时必须使用 --dir，否则默认落在 ./skills/ 且可能不被客户端加载。

1、如未安装 SkillHub CLI，可先检查版本：

command -v skillhub && skillhub --version

未安装时可按官方说明执行（完整安装示例）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

2、安装本 Skill（社区命名空间 user_fa4109f3）：

skillhub install agentmemory-v2 --namespace user_fa4109f3 --dir <你的 Agent skills 目录>

常见 skills 目录（来自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下 .agents/skills/

也可将提示词交给 AI，让其阅读 https://skillhub.cn/install/skillhub.md 并安装 @user_fa4109f3/agentmemory-v2。

3、启用后，Agent 应加载包内 SKILL.md（front matter 中 name: agent-memory，version: 5.0.0）。按文档在工作区或用户目录建立 memory/、~/self-improving/、.learnings/ 等结构，并在会话协议中执行加载 HOT、写入门控与结束时的学习记录。

典型用法¶

经过上面的安装，用法分「规范落地」与「文档中的 API 示例」两类。

目录与 Markdown 模板¶

在 memory/MEMORY.md 维护语义记忆，用 memory/YYYY-MM-DD.md 记情节日志，在 memory/procedures/ 写程序性 runbook；~/self-improving/memory.md 作为 HOT 层（建议不超过 100 行始终加载）。每日日志与程序记忆模板见 SKILL.md 第十二节。

学习捕获¶

工具或命令失败时写入 .learnings/ERRORS.md；用户说「不对」「应该是」等纠正信号时写入 .learnings/LEARNINGS.md，并忽略纯一次性或假设性表述（见第九节表格）。

Python SDK（示例代码，需自行具备实现）¶

from src.memory import AgentMemory

mem = AgentMemory()
mem.remember("重要信息", tags=["分类"])
facts = mem.recall("搜索查询")
new_id = mem.supersede(old_fact_id, "更新后的事实")

HTTP 跨 Agent 共享（示例）¶

文档约定启动与调用方式：

python3 scripts/memory_store.py

curl -X POST http://localhost:8768/memories \
  -H "Content-Type: application/json" \
  -d '{"owner":"my-agent","content":"用户偏好","ttl_seconds":86400}'

curl "http://localhost:8768/memories?q=偏好&agent=my-agent"

会话协议速查¶

用户问「关于 X 你知道什么？」时搜索 HOT/WARM/COLD 与 .learnings；「忘记 X」需确认后从各层移除；压缩上下文前把关键信息冲刷到 MEMORY.md 或 HOT memory.md，并保留原始事件与摘要（见第十八节）。

适用场景与注意¶

适合谁：正在设计或重构 Agent 记忆层的技术负责人、平台工程师，以及希望用统一目录与门控约束 Coding Agent 行为的团队。SkillHub 页面显示评分 100000、下载 1568（统计以页面为准），说明社区关注度较高，但高下载不等于已验证的生产部署。

限制与注意：

• 本 Skill 以 规范与流程 为主；安装包内无 scripts/、src/，HTTP/SDK 需自行落地。
• 文档引用论文 benchmark 与延迟表用于选型参考，你的 workload 仍须按第七节、第十五节自测（写入正确性、scope 安全、更新与删除真实性等）。
• 程序记忆与自动推广强调「候选 + 评测」，避免未验证规则进入 HOT。
• 多租户场景必须严格执行 scope（userId / orgId / agentId），避免记忆串用。
• v4.0 起合并 agent-memory v2.0 与 self-improvement v3.0；v5.0 扩展七种分类与 M_sys、Query Planner 等，与页面长简介一致；页面短简介仍写「情景/语义/程序性/反馈」四层表述，以 5.0.0 SKILL.md 为准。

结尾¶

若你希望 Agent 记忆从「堆上下文」变成「分类存储 + 门控写入 + 计划检索 + 版本化事实」，可以把 统一 Agent 记忆与知识管理系统 作为团队共用的 Skill 规范，在 SkillHub 安装 @user_fa4109f3/agentmemory-v2，并按 SKILL.md 建目录与会话协议。官方入口：SkillHub 技能页（API 坐标页：https://api.skillhub.cn/user_fa4109f3/agentmemory-v2）。