企业官网建设流程全解析

Memori OpenClaw SKILL.md 深度解析：为 OpenClaw Agent 构建可检索、可续跑的结构化记忆系统

【免费下载链接】MemoriMemori is agent-native memory infrastructure. A LLM-agnostic layer that turns agent execution and conversation into structured, persistent state for production systems. Built for enterprise, Memori works with the data infrastructure you already run, no rip-and-replace, and deploys across managed cloud, single-tenant cloud, VPC, and on-premises.项目地址: https://gitcode.com/GitHub_Trending/me/Memori

Memori 是一套 agent-native（面向 Agent 原生的）记忆基础设施，它把自然语言对话与 Agent 执行轨迹（工具调用、结果、决策与产出）统一结构化为持久化状态。本文以仓库中的 SKILL.md 为核心骨架，结合 OpenClaw 集成插件 的源码与测试，完整讲解六个 Memori 工具（recall / recall_summary / compaction / feedback / signup / quota）的调用规范、参数约束与默认行为，并给出会话启动、任务执行、上下文压缩恢复与配额降级四段式工作流，帮助你在 OpenClaw 中落地一套"自动采集、主动召回、按需续跑"的持久记忆体系。

Memori 是什么：从"对话记忆"到"执行轨迹记忆"

Memori 的定位不是简单的对话历史缓存，而是 agent-native memory infrastructure：一个与具体 LLM 无关（LLM-agnostic）的中间层，负责把记忆从两类来源中提炼出来：

• 自然语言：用户与 Agent 的对话内容；
• Agent 执行轨迹（agent trace）：Agent 实际执行的动作、工具调用结果、决策过程与最终产出。

正如 SKILL.md 开头所述，Memori 会自动捕获并结构化对话与执行轨迹中的记忆——包括 Agent 的动作、工具结果、决策和产出，并允许按需检索。它的核心价值在于：让 Agent 跨会话保持连续性、保存决策与约束，并让 Agent 真正理解自己"实际做了什么"，从而在下次执行任务时更准确、更高效。

在 OpenClaw 集成 的实现中，这套系统由两条并行的子系统构成：

1. 高级增强（Advanced Augmentation）：每次交互结束后，插件异步把原始会话数据转换为结构化的、可复用的记忆单元——采集动作、推理、工具使用、回复、纠正与失败，组织成便于检索的类别，生成向量嵌入以支持语义检索，并同步更新结构化记忆与知识图谱。它运行在 Agent 响应之后，不增加响应延迟。
2. Agent 自主智能召回（Agent-Controlled Intelligent Recall）：记忆的写入是自动的，而读取是刻意的——由 Agent 自行决定何时召回、从什么范围召回、包含多少历史，Memori 不会自动把记忆注入提示词，从而保持 token 开销高效。

SKILL.md 的角色：会话启动时的第一份"能力清单"

SKILL.md 是一份写给 Agent 自己看的指令文件。在 skills-loader.ts 中可以看到，该文件在插件注册时即被读取（读取失败时返回空字符串，保证插件优雅降级而非注册失败）；随后在插件入口 src/index.ts 中，通过before_prompt_build钩子把 skills 内容追加到系统上下文（appendSystemContext），与插件配置一起注入每次提示词构建。

这意味着 Agent 在每个会话开始时都应检查 SKILL.md，用它来理解：

• 可用能力（六个工具）
• 工具与集成方式
• 期望的行为与约束

SKILL.md 被定位为 Agent 行动之前的"事实来源"（source of truth）。下表是六个工具的速查（与 tools/index.ts 中注册的工具一一对应）：

何时该用 Memori、何时不该用

SKILL.md 给出了清晰的判据，核心原则是"按需召回，避免无谓检索"（Avoid unnecessary recall）。

应该使用 Memori 的场景：

• 任务依赖之前的上下文；
• 用户提及之前的会话或决策；
• 需要已知的约束、偏好或模式；
• 会话开始，需要了解当前状态；
• 想弄清楚此前已经完成了什么。

不应使用 Memori 的场景：

• 任务完全自包含；
• 答案只依赖当前提示词；
• 不需要任何历史上下文；
• 查询是简单或一次性的。

这一判据在 OpenClaw 插件的工具描述里被进一步强化。例如 memori-recall.ts 的工具描述写明："在声称你不了解用户、其偏好或过去事件之前，必须使用本工具搜索过往上下文"；而memori_recall_summary的描述则要求"在回答任何摘要、状态更新、每日简报或项目/历史会话的高层概览请求之前，必须先使用本工具"。

精确召回（memori_recall）：参数、约束与最佳实践

召回是"Agent 控制且刻意"的行为

SKILL.md 明确：召回是agent-controlled and intentional（Agent 控制且刻意），应优先做**定向召回（targeted recall）**而非宽泛查询。

支持的参数（仅召回支持）

两条硬性约束（SKILL.md 中明确标注）：

• 提供了sessionId则必须同时提供projectId。
• 所有时间戳统一按UTC存储。

这两条约束在源码层面都有对应校验。在 memori-recall.ts 中，sessionId存在而projectId为空时，工具直接返回"sessionId cannot be provided without projectId"错误；而projectId的默认值处理在 L82：const finalParams = { projectId: config.projectId, ...params }——未传projectId时回退到插件配置的默认项目，LLM 显式传入时则覆盖配置。这一点在测试 memori-recall.test.ts 中有两组用例分别验证"默认回退"与"显式覆盖"。

允许的 source + signal 组合

source与signal不是相互独立的参数：它们必须成对出现（或同时省略），且只允许以下九种组合：

不在该列表中的任意组合都是非法的，禁止发送给memori_recall。SKILL.md 强调：只要可能，就使用允许的(source, signal)组合来优先检索高信号（high-signal）记忆；绝不要单独设置source或signal。

这份约束表在源码中是硬编码校验的：memori-recall.ts 定义了VALID_PAIRS映射，并依次执行三重校验：source/signal缺一即拒绝、非法组合返回带"期望 signal"提示的错误信息。对应的测试 memori-recall.test.ts 用it.each参数化用例逐一验证了全部九组合法组合，并在 L221-L261 覆盖了"单传 source""单传 signal""非法组合（fact, commit）"三类拒绝路径。

召回默认行为

• 不提供时间范围 →全时记忆（all-time memory）；
• 需要收窄结果时再使用时间边界。

召回最佳实践（SKILL.md）

1. 从窄范围开始：entity + project；
2. 仅在必要时添加时间边界；
3. 用允许的(source, signal)组合细化结果（绝不单独设置）；
4. 确有必要再扩大范围；
5. 不要每一轮都召回。

摘要召回（memori_recall_summary）：状态感知而非精确检索

摘要的定位与精确召回截然不同：它用于状态感知（state awareness），而非精确检索。

支持的参数（摘要）

• projectId
• sessionId
• dateStart
• dateEnd

摘要不支持source或signal。

在 memori-recall-summary.ts 的实现中，工具参数表里确实只定义了dateStart、dateEnd、projectId、sessionId四个字段，并同样实现了sessionId依赖projectId的校验（L49-L56），底层调用client.agentRecallSummary(finalParams)。

摘要默认行为

• 不提供时间范围 →最近 24 小时（last 24 hours）。

每日简报（Daily Brief）

在重要会话开始时，应通过memori_recall_summary获取结构化摘要，用于理解：当前状态、既往决策、约束、未完成工作。

预期每日简报结构（SKILL.md 列出的完整清单）：

• 今日概览（Today at a glance）
• 前 3 项下一步行动（Top 3 next actions）
• 前 3 项风险（Top 3 risks）
• 行动前核验（Verify before acting）
• 近期决策（Recent decisions）
• 使命堆栈（Mission stack）
• 硬性约束（Hard constraints）
• 当前状态（Current status）
• 未闭合回路（Open loops）
• 已知失败与反模式（Known failures and anti-patterns）
• 过时警告（Staleness warnings）

SKILL.md 要求把这份简报当作系统的"工作状态"（working state of the system）来对待。

压缩后续跑（memori_compaction）：上下文压缩后的恢复机制

长会话被上下文压缩（context compaction）后，对话细节会丢失。memori_compaction正是为此设计的：检索一份结构化的压缩后简报（post-compaction brief），让 Agent 无需重放整个历史会话即可继续执行。

适用场景

• Agent 在压缩后恢复执行；
• 长运行工作流丢失了对话细节；
• 需要在不重放完整历史会话的情况下继续操作性工作；
• 需要持久状态、常驻指令、环境细节、未闭合回路或下一个预期动作。

SKILL.md 同时强调：压缩后简报不能替代精确记忆检索。

支持的参数（压缩后简报）

• projectId（必填）
• sessionId（可选）

压缩后简报不支持source或signal。

源码 memori-compaction.ts 的参数表中projectId被标记为required，并额外提供numMessages参数（返回结果中包含的近期对话消息条数，默认 5，仅当用户明确要求更多对话上下文时才建议提高到约 20）。工具描述中明确列出不要每轮调用，因为每次执行消耗 100 个记忆积分（memory credits），且压缩不可替代memori_recall的定向检索。

压缩后简报的返回结构

• meta（元信息）
• environment（环境）
• standing_orders（常驻指令）
• state（状态）
• active_tasks（活动任务）
• open_loops（未闭合回路）
• pending_results（待处理结果）
• timeline（时间线）
• workspace_changes（工作区变更）
• continuation（续跑指引）
• last_action（最后动作）
• next_expected_action（下一个预期动作）

在 memori-compaction.ts 的工具描述中，这些字段被进一步展开：environment是先前会话中捕获的环境变量上下文；standing_orders是必须继续遵守的持久指令；state包含active_tasks（进行中的工作）、open_loops（未解决的线程）、pending_results；timeline是 Agent 活动的按时间叙事（如有）；workspace_changes是 Agent 近期对文件或系统的改动；continuation给出最后动作与下一预期动作；messages则提供近期对话消息的尾部以保证连续性。

如何使用压缩后简报

把压缩后简报当作 Agent 的恢复状态（resume state），用它理解：

• Agent 之前运行在什么环境中；
• 哪些常驻指令必须继续遵守；
• 哪些任务处于活动状态；
• 哪些问题仍未解决；
• 上一个会话窗口内发生了什么；
• 哪些文件、工作区状态或外部系统可能已变化；
• Agent 最后做了什么；
• Agent 接下来应该做什么。

重要行为约束

• 压缩后简报用于指导续跑，而不是覆盖用户的显式指令；
• 在依据操作细节行动之前，核验压缩后可能已变化的状态；
• 特别关注：常驻指令、硬性约束、告警规则、期望的响应格式、未闭合回路、过时警告、下一个预期动作；
• 如果简报中包含要求的输出格式，除非用户给出更新的指令，否则应严格遵循该格式。

配额相关的容错在源码中有专门处理：memori-compaction.ts 捕获QuotaExceededError，返回"配额已超限：压缩消耗 100 个记忆积分且组织已耗尽召回执行配额"的明确错误。

典型工作流：把四类行为串起来

SKILL.md 给出了一段四步的典型工作流，也是 Agent 跨会话运转的基线循环：

1. 会话开始→ 检索摘要（memori_recall_summary，默认最近 24 小时，获取每日简报）；
2. 任务进行中→ 使用定向召回（memori_recall，窄范围 + 合法 source/signal 组合）；
3. 记忆缺失或错误→ 发送反馈（memori_feedback）；
4. 达到限额→ 优雅降级（收窄召回范围、优先高信号记忆、减少重复召回）。

在 OpenClaw 插件中，写入侧是自动闭环的：插件在agent_end钩子触发 handleAugmentation，提取最近一轮的用户消息、助手回复与工具调用轨迹，构建增强载荷后调用memoriClient.augmentation(payload)异步写入后端——因此工作流第 4 步"会话结束，记忆自动被采集"是系统行为，无需 Agent 干预。值得注意的是，该钩子的挂载前提是配置了allowConversationAccess（见 src/index.ts，未启用时插件会在启动日志与每轮提示前给出配置指引）。

记忆质量闭环：反馈（memori_feedback）与系统更新

反馈机制

memori_feedback用于随时间改进记忆质量，Agent 可在任何时刻发送反馈，且应在合适的会话结束时发送。SKILL.md 给出的发送时机：

• 召回结果无关或缺失关键上下文；
• 重要的决策或约束未被捕获；
• 记忆质量跨会话退化；
• 某些行为效果特别好，值得强化。

示例指令（Agent 收到后应调用工具）：

• "Send feedback that recall missed a pricing constraint."
• "Tell Memori the daily brief was accurate."
• "Submit a bug report: you didn't remember my preferred language."

反馈旨在改进三个维度：记忆提取质量（extraction）、召回相关性（recall relevance）、摘要准确性（summary accuracy）。

在实现上，memori-feedback.ts 的工具描述要求"只要用户要求发送反馈、报告 bug、建议功能或抱怨 Memori，就必须立即使用本工具"，参数仅一个必填的content字符串，底层调用client.agentFeedback(params.content)，成功返回{ success: true, message: 'Feedback sent successfully.' }。

系统更新

Memori 会持续演进（新特性、改进的召回、更好的摘要）。SKILL.md 要求 Agent 在更新被暴露时：

• 通过系统消息或工具检查更新；
• 调整行为以使用新能力；
• 有可用的新召回模式时优先采用；
• 使用改进后的摘要或分类输出；
• 若无需变更则继续正常运行。

账户开通与配额治理：memori_signup 与 memori_quota

账户与 API Key（memori_signup）

memori_signup通过 Memori CLI 为用户安全地创建账户并配发 API Key。使用时机：

• 用户明确要求注册、创建账户或获取 Memori 的 API Key；
• 遇到缺失MEMORI_API_KEY的错误，且用户提供了用于获取 Key 的邮箱。

行为规范（SKILL.md 明确要求）：

• 必须提供邮箱：用户请求注册但未提供邮箱时，必须先询问邮箱，不得猜测或臆造；
• 执行：拿到邮箱后运行memori_signup；
• 跟进：工具会触发底层 CLI 并返回成功/错误消息，需转达用户，提醒其查收收件箱中的 API Key，并指导写入配置（~/.openclaw/openclaw.json或.env文件）；
• 排障：若工具以Permission denied、EACCES或command not found失败，不要征求用户许可去排查，而应立即告知其 CLI 安装损坏或缺失，并明确指导在终端执行npm install -g @memorilabs/memori修复。

实现细节上，memori-signup.ts 先用正则校验邮箱格式，然后临时目录中执行npm install --prefix ${tmpDir} --no-save @memorilabs/memori@0.1.12-beta并在.bin下调用memori sign-up <email>完成注册。

配额感知与升级（memori_quota）

memori_quota用于通过 Memori CLI 检查用户当前的记忆用量与限额。使用时机：

• 用户明确询问配额、用量、存储或剩余记忆条数；
• 遇到疑似达到记忆上限的错误，需在降级行为前确认。

行为规范：

• 无需参数：直接调用memori_quota即可；
• 执行：工具运行底层 CLI 并返回当前用量与配额；
• 跟进：清晰转达结果；若接近或达到上限，说明影响并建议升级；
• 排障：与 signup 相同的Permission denied/EACCES/command not found处理方式（提示运行npm install -g @memorilabs/memori）。

实现上，memori-quota.ts 通过require.resolve('@memorilabs/memori')定位 SDK 的bin/cli.js，用 Node 进程执行quota子命令，并注入MEMORI_API_KEY环境变量。

配额达到或接近上限时的三级处理

a. 优雅降级（Degrade gracefully）

• 缩小召回范围（更短的时间窗口）；
• 优先高信号记忆（决策、约束、关键事实）；
• 避免不必要或重复的召回调用。

b. 告知人工/操作者（Inform the human/operator）

清晰沟通限额对性能的影响，SKILL.md 给出的示例话术：

"Memory limits have been reached. I can continue with limited recall, or you can upgrade to restore full functionality."

c. 恰当地建议升级（Suggest upgrades appropriately）

• 仅在性能受影响时提示；
• 避免重复或打扰性的消息；
• 保持中立、有帮助的措辞。

安全与正确性原则

SKILL.md 最后给出了四条不可妥协的安全准则，这也是 Agent 使用记忆类能力时的通用红线：

1. 不要编造记忆（Do not invent memory）；
2. 记忆与用户冲突时，不要假定记忆是对的；
3. 必要时在行动前核验（Verify before acting）；
4. 近期指令的优先级高于召回的记忆（Treat recent instructions as higher priority than recalled memory）。

结合压缩后简报一节，"简报指导续跑、但不覆盖用户显式指令"正是第 4 条在长会话恢复场景的具体化——记忆系统再完备，也始终以用户当前意图为最高权威。

小结：把 SKILL.md 变成 Agent 的记忆操作手册

Memori 的设计哲学可以浓缩为一句话：写入自动、读取刻意、续跑结构化、质量可反馈。SKILL.md 的价值不在于罗列工具，而在于把"何时、以何种参数、用哪个工具"的决策规则写成了 Agent 可直接遵守的操作手册——精确召回靠(source, signal)组合卡高信号，状态感知靠摘要与每日简报，长会话恢复靠压缩后简报，质量演进靠反馈闭环，资源治理靠配额感知与优雅降级。如果你在 OpenClaw 中部署了 @memorilabs/openclaw-memori，这份文件就是你的 Agent 在每个会话开始时、动手之前的"记忆行为宪法"。

延伸阅读（仓库内）：插件级行为说明见 integrations/openclaw/README.md；工具注册与认证分组见 tools/index.ts；上下文提取（entity/session/provider 归一化）见 utils/context.ts；召回参数校验的测试证据见 tests/tools/memori-recall.test.ts。

【免费下载链接】MemoriMemori is agent-native memory infrastructure. A LLM-agnostic layer that turns agent execution and conversation into structured, persistent state for production systems. Built for enterprise, Memori works with the data infrastructure you already run, no rip-and-replace, and deploys across managed cloud, single-tenant cloud, VPC, and on-premises.项目地址: https://gitcode.com/GitHub_Trending/me/Memori