企业官网建设流程全解析

为 Claude Code 接入 Memori 环境记忆：SKILL.md 实战指南与源码解析

【免费下载链接】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 的长期记忆基础设施，通过一个薄薄的 Claude Code Skill（两个文件：SKILL.md与index.ts）即可让 Claude Code 获得跨会话、跨/clear的持久记忆：编码会话中的事实、决策、约束、状态与 Agent 执行轨迹会被结构化存储，并在后续会话中自动召回。读完本文，你将掌握该 Skill 的完整安装、配置、七个命令的用法、source/signal 记忆分类法，以及背后的实现原理。

什么是 Claude Code 的环境记忆（Ambient Memory）

integrations/claude-code/SKILL.md定义的不是一个"用户手动调用的工具"，而是一种**环境记忆（ambient memory）**能力：Claude Code 的每一次实质性对话回合，都会被自动执行"先召回、后回答、再沉淀"的记忆生命周期，无需用户显式说"用一下 Memori"。

从 SKILL.md 的 frontmatter 可以清楚看到它的定位：

--- name: memori description: > Ambient Memori long-term memory for Claude Code via local Bash. MUST TRIGGER on essentially every non-trivial user turn: run recall before drafting any substantive response... allowed-tools: Bash ---

三个关键声明：

• MUST TRIGGER（必须触发）：几乎所有非平凡回合都要先执行recall，无论用户是否提到"记忆""之前的会话""过去的工作"；
• 允许的工具只有 Bash：整个 Skill 通过本地 Bash 调用bun .claude/skills/memori/index.ts与 Memori Cloud 通信，不需要任何 MCP 或额外运行时；
• 在外部查询之前触发：recall必须优先于 WebSearch / WebFetch 等一切外部信息获取，因为用户可能已经把相关背景存在 Memori 里。

同时它明确了职责边界：Claude Code 的首要工作仍然是回答用户、编辑代码、调试与评审，记忆只是增强上下文，绝不替代回答本身。

Skill 的组成与安装

该集成参考实现位于 integrations/claude-code，完整代码只有两个文件（见 README.md）：

<your-project>/ └── .claude/ └── skills/ └── memori/ ├── SKILL.md # skill 定义与使用流程 └── index.ts # 封装 Memori Cloud 的 TypeScript CLI

前置条件

• Bun 运行时（curl -fsSL https://bun.sh/install | bash）；
• Claude Code（其技能系统会自动发现.claude/skills/下的 Skill）；
• 一个 Memori Cloud 账号与 API Key（可用下文signup命令获取）。

安装步骤

1. 将SKILL.md与index.ts复制到目标项目的.claude/skills/memori/目录；若复制到全局~/.claude/skills/memori/，则对所有项目生效；
2. 提供凭据（见下一节配置）。

.claude/既可以是项目根目录，也可以是全局的~/.claude/，Claude Code 会自动发现两处的 Skill。

配置：凭据与作用域

官方推荐的配置方式是.claude/settings.local.json。Claude Code 会把env块下的所有条目注入每个 Bash 子进程的环境变量（本 Skill 即运行在 Bash 子进程中），并且创建该文件时自动加入 gitignore，不会误提交到仓库：

{ "env": { "MEMORI_API_KEY": "your_memori_api_key", "MEMORI_ENTITY_ID": "stable_identifier_for_this_user" } }

环境变量速查表

替代方案：Shell 环境变量或.env文件

如果不使用settings.local.json，Skill 还会从以下位置读取：

1. Shell / shell profile /direnv中导出的真实环境变量；
2. 与index.ts同目录的.env文件（与 cwd 无关，包括全局安装于~/.claude/skills/memori/的场景）。

优先级（高者胜出）：每次调用的--flag> 真实环境变量 >.env文件。MEMORI_PROJECT_ID在上述都未设置时回退到basename($CLAUDE_PROJECT_DIR)；MEMORI_SESSION_ID仅在advanced-augmentation与compaction中回退到$CLAUDE_CODE_SESSION_ID，recall/recall.summary要限定到单会话必须显式传--sessionId。

作用域设计的源码佐证

在 index.ts 中，默认作用域解析逻辑清晰可见：

const DEFAULT_PROJECT_ID = process.env.MEMORI_PROJECT_ID ?? (CLAUDE_PROJECT_DIR ? basename(CLAUDE_PROJECT_DIR) : undefined); const DEFAULT_SESSION_ID = process.env.MEMORI_SESSION_ID ?? CLAUDE_SESSION_ID;

而recall的查询串构造中，session_id默认不注入：

// session_id narrows results to a single session on the agent recall API; // leave it unset by default so ambient recall stays project-scoped across // new Claude Code sessions and /clear. const qs = buildQS({ entity_id: entityId, project_id: projectId, session_id: flags.sessionId, // 仅显式传参时才有值 ... });

这正是"读取保持项目级、写入绑定当前会话"这一设计意图的实现落点。之所以如此设计，是因为entity_id + process_id + session_id构成记忆的作用域三维（详见 how-memory-works.mdx）：同一用户在不同项目/应用中隔离记忆，recall若不设session_id则能在新会话与/clear之后依然召回项目级上下文。

命令总览

CLI 统一入口（路径按实际安装位置调整，全局安装可用bun ~/.claude/skills/memori/index.ts ...）：

bun .claude/skills/memori/index.ts <command> [--flags ...]

Flags 支持--flag value与--flag=value两种写法。

成功时命令向 stdout 输出 JSON 并以 0 退出；失败时向 stderr 输出错误并以 1 退出。

记忆生命周期：每回合的标准流程

SKILL.md 的 Procedure 一节规定了七个步骤，是"环境记忆"的核心执行逻辑：

1. 起草任何实质性回答之前先运行recall——包括一般编码任务、调试、代码评审与研究，不要等用户提到记忆；
2. 任何外部信息查询（WebSearch、WebFetch 等）之前必先recall——用户可能已在 Memori 中存有相关背景，这是强制项；
3. recall.summary只用于宽泛摘要场景：会话方向定位、每日简报、整体状态、长时间间隔后的重新定位，不用于具体问题；
4. 仅在上下文被压缩或工作上下文丢失后使用compaction；
5. 回答或完成用户的真实请求——记忆改进上下文，不替代回答；
6. 非平凡回合起草完最终回答后，运行advanced-augmentation——这是强制的环境记账步骤，且必须是该回合最后一个记忆操作；
7. 只有当用户请求或 Memori 报错使之相关时，才使用feedback、quota、signup。

可以跳过的唯一例外：纯客套的确认/收尾、完全不依赖先前上下文的独立回合、用户明确要求不记录该回合。

Recall：定向检索与 source/signal 分类法

recall是定向检索，其 API 端点不支持自由文本query，永远不要传--query（index.ts 中会显式报错recall does not support --query）。检索靠过滤器完成，尤其是 source/signal。

即使遇到"上次我们讨论过 X 吗？"这类问题，也不要试图把 X 塞进--query——先选最贴近的 source/signal 类别执行recall，再从返回的记忆中作答。

--source与--signal必须成对提供，或同时省略（源码中二者缺失其一即报错退出）。SKILL.md 给出了完整的分类表：

源码中以VALID_SOURCE_SIGNAL常量固化了这份一对一的合法组合，并做严格校验：

const VALID_SOURCE_SIGNAL: Record<string, string> = { constraint: "discovery", decision: "commit", execution: "failure", fact: "verification", insight: "inference", instruction: "discovery", status: "update", strategy: "pattern", task: "result", }; // 非法组合会直接报错： // Invalid (source, signal) pair: (fact, commit). Expected signal "verification" for source "fact".

recall的完整参数还包括--projectId、--sessionId、--dateStart ISO、--dateEnd ISO，对应查询串中的entity_id、project_id、session_id、date_start、date_end——返回的记忆按 entity、project、session 与时间维度作用域限定（参见 overview.mdx）。

Advanced Augmentation：把对话与执行轨迹沉淀为记忆

每轮非平凡对话的最后一步，用最终回答执行：

bun .claude/skills/memori/index.ts advanced-augmentation \ --userMessage "$USER_MESSAGE" \ --assistantMessage "$ASSISTANT_MESSAGE" \ --trace "$TRACE_JSON"

--sessionId默认取$CLAUDE_CODE_SESSION_ID，只有需要关联其他会话时才显式传入。--summary可附带本轮会话摘要，--model标注所用模型，--processId关联到某个进程（默认取MEMORI_PROCESS_ID）。

Trace 的 JSON 形状

Trace 形如{ "tools": [...] }。省略时 CLI 发送{ "tools": [] }。每个 tool 条目必须包含：

• name：字符串，工具/函数名；
• args：对象，传给该工具的参数；
• result：工具的摘要结果，该键必须存在。

合法示例：

{ "tools": [ { "name": "ReadFile", "args": { "path": "src/app.ts" }, "result": "Read app entrypoint" } ] }

严禁在 trace 字段中放入密钥、凭据或大段原始日志。源码中的parseTraceFlag会对形状逐项校验：tools必须是数组、每项必须是对象、name必须是字符串、args必须是对象、result键必须存在，任一不满足即报错退出。

底层调用链：一次写入的两次请求

从 index.ts 的实现看，advanced-augmentation实际发起两次 HTTP 请求：

1. 对话回合写入：POST https://api.memorilabs.ai/v1/agent/conversation/turn，携带attribution（entity.id与可选的process.id）、messages（user/assistant 两条）、project.id、session.id；
2. 增强处理：POST https://collector.memorilabs.ai/v1/agent/augmentation，携带conversation、trace、meta（sdk / framework / llm.model / platform / storage 元数据）以及session.summary。

第二步的失败被设计为非致命：catch 中仅打印[memori] collector augmentation failed (non-fatal)后继续，最终仍返回{ success: true, augmentation: true }，保证记忆记账不影响主回答路径。这与 Advanced Augmentation 引擎"异步后台运行、最小化对响应路径影响"的设计一致（参见 advanced-augmentation.mdx）：引擎在后台读取完整对话、识别事实/偏好/技能/属性、抽取语义三元组、生成向量嵌入并存入记忆空间。

Compaction、Feedback、Quota 与 Signup

Compaction——在 Claude Code 上下文压缩后恢复工作状态：

bun .claude/skills/memori/index.ts compaction [--projectId ID] [--sessionId ID] [--numMessages 5]

它默认绑定当前工作区与会话（session_id走DEFAULT_SESSION_ID回退链），--numMessages控制返回的消息数量，对应查询串参数num_messages，GET 请求{BASE_URL}/agent/compaction。

Feedback——反馈记忆质量：

bun .claude/skills/memori/index.ts feedback --content "feedback text"

--content必填，POST 到/agent/feedback。

Quota——查询配额：

bun .claude/skills/memori/index.ts quota

GET 请求/sdk/quota。

Signup——创建账号并获取 API Key：

bun .claude/skills/memori/index.ts signup --email "user@example.com"

源码中对邮箱做了正则格式校验（/^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/），非法邮箱直接报错退出；合法则 POST 到/sdk/account。

输出与错误处理约定

• 成功：向 stdout 打印 JSON（console.log(JSON.stringify(result, null, 2))），退出码 0；
• 失败：向 stderr 打印错误信息，退出码 1（包括缺凭据、缺参数、非法 source/signal 组合、非法 trace 形状、HTTP 非 2xx 响应等）；
• 记忆失败时的降级策略：如果记忆链路失败，简要报告记忆问题后，继续用当前上下文完成用户的真实请求，不阻断主任务。

此外，每次调用 CLI 都会向 stderr 打印一行诊断日志（例如[memori] command="recall" flags={...}），可用于验证 Skill 是否按预期触发。

验证与故障排查

验证是否生效

1. 启动 Claude Code，运行/skills，确认列表中包含memori；
2. 发送一条非平凡消息，观察日志是否依次出现：

   [memori] command="recall" flags={...} [memori] command="advanced-augmentation" flags={...}

   即证明"回答前召回、回答后沉淀"的生命周期已自动运行。

常见错误与解决办法（见 README.md）

• MEMORI_API_KEY is required——凭据未注入环境。将MEMORI_API_KEY加入.claude/settings.local.json的env块、在 shell 中导出，或放入index.ts旁的.env文件。若用户尚无 API Key，可通过signup命令获取；
• MEMORI_ENTITY_ID is required——命名空间未配置。在env块中添加任意稳定字符串（hostname 或生成的 UUID）。首次失败时，SKILL.md 会指示 Claude Code 在可推断合理值时自动完成此操作；
• MEMORI_PROJECT_ID could not be resolved——MEMORI_PROJECT_ID与CLAUDE_PROJECT_DIR均未设置。传--projectId、在env块中设置，或在 Claude Code 工作区内运行；
• Claude 每次 Bash 调用都询问——确认Bash(bun *)与Skill(memori)已在settings.local.json/settings.json的权限列表中；
• Skill 从不触发——确认 Claude Code 能发现它：/skills中应列出memori。

从记忆模型理解这份 Skill

将这份 Skill 放回 Memori 的整体记忆模型（how-memory-works.mdx）中看，它的价值在于补全了"对话之外"的一类记忆来源。对话历史记录的是"说了什么"，而 Agent 执行轨迹记录的是"做了什么"——文件编辑、工具调用、构建结果、遇到的错误与做出的决策（agent-trace-execution.mdx）。Memori 会从两者中提取结构化记忆原语（facts、preferences、skills、attributes、agent trace & execution）与持续更新的滚动摘要，供后续定向检索使用。

对应到本文的 CLI：recall是手动/环境定向检索，advanced-augmentation是异步结构化沉淀（含 trace），compaction是上下文压缩后的状态恢复。它们共享同一套entity / process / session / project作用域模型，这也是为什么MEMORI_ENTITY_ID与项目/会话作用域的正确配置，直接决定了记忆的隔离与召回质量。

参考资料

• Skill 行为定义与 source/signal 分类法：SKILL.md
• CLI 完整源码（含.env加载、参数解析、校验与 HTTP 端点）：index.ts
• 集成说明、配置优先级与排障：README.md
• Claude Code 集成总览：overview.mdx
• 快速上手（三步安装）：quickstart.mdx
• 记忆模型与作用域：how-memory-works.mdx
• Agent 执行轨迹记忆：agent-trace-execution.mdx
• Advanced Augmentation 引擎：advanced-augmentation.mdx

【免费下载链接】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