为 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/MemoriMemori 是面向 Agent 的长期记忆基础设施通过一个薄薄的 Claude Code Skill两个文件SKILL.md与index.ts即可让 Claude Code 获得跨会话、跨/clear的持久记忆编码会话中的事实、决策、约束、状态与 Agent 执行轨迹会被结构化存储并在后续会话中自动召回。读完本文你将掌握该 Skill 的完整安装、配置、七个命令的用法、source/signal 记忆分类法以及背后的实现原理。什么是 Claude Code 的环境记忆Ambient Memoryintegrations/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.mdyour-project/ └── .claude/ └── skills/ └── memori/ ├── SKILL.md # skill 定义与使用流程 └── index.ts # 封装 Memori Cloud 的 TypeScript CLI前置条件Bun 运行时curl -fsSL https://bun.sh/install | bashClaude Code其技能系统会自动发现.claude/skills/下的 Skill一个 Memori Cloud 账号与 API Key可用下文signup命令获取。安装步骤将SKILL.md与index.ts复制到目标项目的.claude/skills/memori/目录若复制到全局~/.claude/skills/memori/则对所有项目生效提供凭据见下一节配置。.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 } }环境变量速查表变量必填用途MEMORI_API_KEY是认证 Memori Cloud。MEMORI_ENTITY_ID是稳定的 per-user / per-agent 记忆命名空间任意字符串即可。缺失时 SKILL.md 指示 Claude Code 自行选取合理默认值机器 hostname 或生成的 UUID并写回.claude/settings.local.json只有在无法推断默认值时才询问用户。MEMORI_PROJECT_ID否默认取basename($CLAUDE_PROJECT_DIR)即当前 Claude Code 工作区文件夹名。可用--projectId每次覆盖或在env块中固定。MEMORI_SESSION_ID否供advanced-augmentation写入与compaction恢复当前会话使用默认取$CLAUDE_CODE_SESSION_ID/clear后会重置。不会自动应用到recall/recall.summary——读取路径默认保持项目级作用域除非显式传--sessionId。MEMORI_PROCESS_ID否advanced-augmentation的进程级归因。替代方案Shell 环境变量或.env文件如果不使用settings.local.jsonSkill 还会从以下位置读取Shell / shell profile /direnv中导出的真实环境变量与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_IDrecall/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与--flagvalue两种写法。命令用途recall定向检索。与--source/--signal配合使用见下文分类表。默认项目级作用域传--sessionId可收窄到单会话。recall.summary宽泛的会话摘要 / 方向性回顾。默认项目级作用域。advanced-augmentation记录一轮 user/assistant 对话。必填--userMessage、--assistantMessage可选--sessionId默认$CLAUDE_CODE_SESSION_ID、--trace、--summary、--model、--projectId、--processId。compaction在 Claude Code 上下文压缩后恢复工作状态。默认当前工作区与会话可用--projectId/--sessionId覆盖。feedback发送自由文本反馈。--content ...quota查询当前 API Key 的剩余配额。signup创建新账号。--email userexample.com成功时命令向 stdout 输出 JSON 并以 0 退出失败时向 stderr 输出错误并以 1 退出。记忆生命周期每回合的标准流程SKILL.md 的 Procedure 一节规定了七个步骤是环境记忆的核心执行逻辑起草任何实质性回答之前先运行recall——包括一般编码任务、调试、代码评审与研究不要等用户提到记忆任何外部信息查询WebSearch、WebFetch 等之前必先recall——用户可能已在 Memori 中存有相关背景这是强制项recall.summary只用于宽泛摘要场景会话方向定位、每日简报、整体状态、长时间间隔后的重新定位不用于具体问题仅在上下文被压缩或工作上下文丢失后使用compaction回答或完成用户的真实请求——记忆改进上下文不替代回答非平凡回合起草完最终回答后运行advanced-augmentation——这是强制的环境记账步骤且必须是该回合最后一个记忆操作只有当用户请求或 Memori 报错使之相关时才使用feedback、quota、signup。可以跳过的唯一例外纯客套的确认/收尾、完全不依赖先前上下文的独立回合、用户明确要求不记录该回合。Recall定向检索与 source/signal 分类法recall是定向检索其 API 端点不支持自由文本query永远不要传--queryindex.ts 中会显式报错recall does not support --query。检索靠过滤器完成尤其是 source/signal。即使遇到上次我们讨论过 X 吗这类问题也不要试图把 X 塞进--query——先选最贴近的 source/signal 类别执行recall再从返回的记忆中作答。--source与--signal必须成对提供或同时省略源码中二者缺失其一即报错退出。SKILL.md 给出了完整的分类表使用场景Flags事实或偏好--source fact --signal verification之前的决策--source decision --signal commit约束或需求--source constraint --signal discovery长期指令--source instruction --signal discovery状态或进展--source status --signal update已完成任务/结果--source task --signal result失败或错误--source execution --signal failure策略或模式--source strategy --signal pattern推断出的经验--source insight --signal inference源码中以VALID_SOURCE_SIGNAL常量固化了这份一对一的合法组合并做严格校验const VALID_SOURCE_SIGNAL: Recordstring, 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 请求对话回合写入POST https://api.memorilabs.ai/v1/agent/conversation/turn携带attributionentity.id与可选的process.id、messagesuser/assistant 两条、project.id、session.id增强处理POST https://collector.memorilabs.ai/v1/agent/augmentation携带conversation、trace、metasdk / 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 与 SignupCompaction——在 Claude Code 上下文压缩后恢复工作状态bun .claude/skills/memori/index.ts compaction [--projectId ID] [--sessionId ID] [--numMessages 5]它默认绑定当前工作区与会话session_id走DEFAULT_SESSION_ID回退链--numMessages控制返回的消息数量对应查询串参数num_messagesGET 请求{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 quotaGET 请求/sdk/quota。Signup——创建账号并获取 API Keybun .claude/skills/memori/index.ts signup --email userexample.com源码中对邮箱做了正则格式校验/^[a-zA-Z0-9._%-][a-zA-Z0-9.-]\.[a-zA-Z]{2,}$/非法邮箱直接报错退出合法则 POST 到/sdk/account。输出与错误处理约定成功向 stdout 打印 JSONconsole.log(JSON.stringify(result, null, 2))退出码 0失败向 stderr 打印错误信息退出码 1包括缺凭据、缺参数、非法 source/signal 组合、非法 trace 形状、HTTP 非 2xx 响应等记忆失败时的降级策略如果记忆链路失败简要报告记忆问题后继续用当前上下文完成用户的真实请求不阻断主任务。此外每次调用 CLI 都会向 stderr 打印一行诊断日志例如[memori] commandrecall flags{...}可用于验证 Skill 是否按预期触发。验证与故障排查验证是否生效启动 Claude Code运行/skills确认列表中包含memori发送一条非平凡消息观察日志是否依次出现[memori] commandrecall flags{...} [memori] commandadvanced-augmentation flags{...}即证明回答前召回、回答后沉淀的生命周期已自动运行。常见错误与解决办法见 README.mdMEMORI_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与持续更新的滚动摘要供后续定向检索使用。对应到本文的 CLIrecall是手动/环境定向检索advanced-augmentation是异步结构化沉淀含 tracecompaction是上下文压缩后的状态恢复。它们共享同一套entity / process / session / project作用域模型这也是为什么MEMORI_ENTITY_ID与项目/会话作用域的正确配置直接决定了记忆的隔离与召回质量。参考资料Skill 行为定义与 source/signal 分类法SKILL.mdCLI 完整源码含.env加载、参数解析、校验与 HTTP 端点index.ts集成说明、配置优先级与排障README.mdClaude Code 集成总览overview.mdx快速上手三步安装quickstart.mdx记忆模型与作用域how-memory-works.mdxAgent 执行轨迹记忆agent-trace-execution.mdxAdvanced 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考