Cursor-memory-cli 自动化记忆提取的完整实现

Cursor-memory-cli 自动化记忆提取的完整实现

一个用于安装和配置 Cursor Memory 系统的命令行工具。Cursor Memory 是一个持续学习系统，可以从 Cursor 会话中提取结构化记忆，并将其编码为可查询的 JSON 记录，供跨会话调用。

基于 Cursor Memory 实战：如何终结 AI 助手的“金鱼记忆” 的理论方案，完整落地自动化cursor-memory-cli工具。仓库地址：cursor-memory-cli

目录

• 概述
• 安装
• 快速开始
• 安装组件说明
• 使用方法
• 记忆类型
• 存储结构
• 配置说明
• 常见问题

概述

Cursor Memory 系统通过以下机制工作：

1. Hook 触发：在每次提交 prompt 前，自动触发记忆评估提醒
2. Skill 自主执行：cursor-memory skill 独立完成记忆分析、提取和存储
3. 结构化提取：提取决策、洞察、模式、纠正等多种类型的记忆
4. 持久化存储：将记忆保存为结构化 JSON 文件，便于后续查询

Skill 与 Command 的关系

• cursor-memory skill：核心组件，自主完成记忆的分析、提取和存储，无需调用外部命令
• catch-memory command：手动补充工具，供用户在需要时显式触发记忆提取

核心特性

• 自动触发：通过 Cursor hooks 机制自动触发记忆评估
• 智能去重：同一会话的多次提取会自动合并到同一文件
• 质量过滤：仅保留置信度 >= 50 的高价值记忆
• 结构化存储：按日期组织的 JSON 文件，便于检索

安装

前置要求

• Node.js 18+
• Cursor Editor

运行安装命令

node~/.cursor/cli/cursor-memory-cli/index.mjs setup

安装模式

CLI 支持两种安装模式：

全局模式（推荐）

适用于所有项目，配置存储在~/.cursor/目录：

node~/.cursor/cli/cursor-memory-cli/index.mjs setup --global

本地模式

仅适用于当前项目，配置存储在项目的.cursor/目录：

node~/.cursor/cli/cursor-memory-cli/index.mjs setup --local

交互式选择

如果不指定模式，CLI 会提示你选择：

node~/.cursor/cli/cursor-memory-cli/index.mjs setup

? Where would you like to install cursor-memory? ❯ Global (~/.cursor/) - applies to all projects Local (./.cursor/) - applies to current project only

快速开始

1. 安装 Cursor Memory

# 全局安装（推荐）node~/.cursor/cli/cursor-memory-cli/index.mjs setup --global

安装完成后会显示：

[ok] cursor-memory setup complete! Components installed: - hooks.json (merged) - hooks/cursor-memory-reminder.sh (executable) - skills/cursor-memory/ (SKILL.md, README.md) - commands/catch-memory.md

2. 重启 Cursor

安装完成后，重启 Cursor 以加载新的 hooks 配置。

3. 开始使用

现在每次与 Cursor Agent 交互时，系统会自动评估是否需要提取记忆。cursor-memory skill 会自主完成记忆的分析、提取和存储。

如果需要手动触发记忆提取，可以使用命令：

/catch-memory

安装组件说明

CLI 会安装以下组件：

1. hooks.json

配置 Cursor 在提交 prompt 前触发记忆提醒钩子。

{"version":1,"hooks":{"beforeSubmitPrompt":[{"command":"~/.cursor/hooks/cursor-memory-reminder.sh"}]}}

注意：如果已有hooks.json，CLI 会智能合并配置，不会覆盖现有的 hooks。

2. cursor-memory-reminder.sh

位于hooks/目录的可执行脚本，负责：

• 在每次交互前注入记忆评估提醒规则
• 创建临时规则文件rules/cursor-memory-reminder.mdc
• 提示 Agent 评估当前会话是否产生了值得保留的记忆

3. cursor-memory skill

位于skills/cursor-memory/目录，包含：

• SKILL.md：技能定义文件，描述何时激活及工作流程
• references/TYPES.md：10 种记忆类型和 12 种实体类型的定义
• references/STORAGE.md：存储格式和去重逻辑说明

4. catch-memory 命令（手动补充）

位于commands/catch-memory.md，作为手动触发记忆提取的补充工具。

注意：cursor-memory skill 已具备独立完成记忆提取的能力，此命令主要用于用户需要显式控制时使用。

使用方法

自动模式（推荐）

安装完成后，cursor-memory skill 会在以下情况自动评估并提取记忆：

• 解决了复杂的调试问题
• 通过试错找到了可行的解决方案
• 用户纠正了 Agent 的假设或方法
• 做出了重要的架构或技术决策
• 发现了跨会话相关的洞察

Skill 会自主完成记忆的分析、提取和存储到./memories/目录，无需用户干预。

手动触发（补充方式）

当需要显式控制记忆提取时，可以在 Cursor 中使用命令：

/catch-memory

分析当前会话并提取记忆。

分析特定会话文件：

/catch-memory /path/to/session-file.json

适用场景：

• 希望立即提取记忆而不等待自动评估
• 需要分析历史会话文件
• 调试记忆提取功能

显式请求

你也可以直接对 Agent 说：

• “Save memories”（保存记忆）
• “Remember this”（记住这个）
• “What did we learn?”（我们学到了什么？）

记忆类型

Cursor Memory 支持 10 种记忆类型：

置信度评分

每条记忆必须包含置信度评分（50-100）：

• 90-100：记录中的明确陈述
• 70-89：从上下文强烈暗示
• 50-69：带有不确定性的合理推断
• < 50：不提取（太不确定）

存储结构

文件位置

记忆存储在当前工作目录的./memories/目录下：

./memories/ ├── 2026-01-30/ │ ├── 14-30-00-fix-auth-bug.json │ └── 16-45-00-api-refactor.json ├── 2026-01-31/ │ └── 10-00-00-database-migration.json

JSON 结构

{"session_id":"2026-01-30-14-30-00-fix-auth-bug","timestamp":"2026-01-30T14:30:00Z","last_updated":"2026-01-30T15:45:00Z","extraction_count":2,"memories":[{"type":"decision","category":"technical","title":"选择 JWT 而非 Session 进行认证","content":"决定使用 JWT 进行 API 认证，因为需要支持移动端和无状态的微服务架构","source_chunk":"**User:** 我们应该用什么方式做认证？\n**Assistant:** 考虑到需要支持移动端...","reasoning":"JWT 更适合分布式系统和移动端场景","alternatives":[{"option":"Session","why_not":"需要服务端状态，不适合微服务"}],"selected_option":"JWT","confidence_score":95,"related_entities":[{"type":"project","raw":"auth-service","slug":"auth-service","resolved":true}],"tools_mentioned":[],"urls_mentioned":[],"target_agents":[]}],"suggestions":[]}

单会话单文件机制

同一会话的多次记忆提取会自动合并到同一个文件：

1. 会话标识：基于会话开始时间生成稳定的 session_id
2. 智能去重：基于(type, title)和内容相似度去重
3. 版本选择：保留置信度更高的版本
4. 元数据更新：更新last_updated和extraction_count

配置说明

hooks.json 配置

如果需要自定义 hooks 配置，可以编辑hooks.json：

{"version":1,"hooks":{"beforeSubmitPrompt":[{"command":"~/.cursor/hooks/cursor-memory-reminder.sh"},{"command":"其他 hook 命令"}]}}

调整记忆提取行为

编辑skills/cursor-memory/SKILL.md可以调整：

• 激活触发条件
• 记忆质量标准
• 提取数量限制

常见问题

Q: 安装后 hook 没有触发？

A: 请确保：

1. 重启了 Cursor
2. hooks/cursor-memory-reminder.sh有执行权限（chmod +x）
3. hooks.json语法正确

Q: 记忆文件存储在哪里？

A: 记忆存储在当前工作目录的./memories/目录下，按日期组织。

Q: 如何查看提取的记忆？

A: 直接查看./memories/YYYY-MM-DD/目录下的 JSON 文件。

Q: 可以禁用自动记忆提取吗？

A: 可以，删除或注释hooks.json中的cursor-memory-reminder.sh条目即可。

Q: 全局安装和本地安装有什么区别？

A:

• 全局安装（~/.cursor/）：对所有项目生效
• 本地安装（./.cursor/）：仅对当前项目生效，优先级更高

Q: 如何更新 cursor-memory-cli？

A: 重新运行安装命令即可，CLI 会智能合并配置而不会丢失现有设置。

命令参考

Usage: node cli/cursor-memory-cli/index.mjs setup [--global|--local] Commands: setup Install cursor-memory components Options: --global Install to ~/.cursor/ (user-level) --local Install to ./.cursor/ (project-level) --help Show help message

技术架构

cursor-memory-cli/ ├── index.mjs # CLI 入口 ├── lib/ │ ├── constants.mjs # 常量定义 │ ├── copy.mjs # 文件复制工具 │ ├── hooks.mjs # hooks.json 合并逻辑 │ ├── logger.mjs # 日志输出 │ ├── setup.mjs # 安装流程 │ └── ui.mjs # 交互式 UI └── templates/ ├── hooks.json # hooks 配置模板 ├── hooks/ │ └── cursor-memory-reminder.sh # hook 脚本 ├── skills/ │ └── cursor-memory/ # 技能定义 │ ├── SKILL.md │ └── references/ │ ├── TYPES.md │ └── STORAGE.md └── commands/ └── catch-memory.md # 命令定义

License

MIT