| name | memory |
| description | 管理 AI Agent 的长期记忆系统。自动记住重要对话、决策和用户偏好，
并在新会话中召回相关信息。当收到 [Memory Flush] 或 [Session Save]
系统消息时自动执行记忆操作。当用户提到"记住"、"记忆"、"之前讨论过"时使用。
|
Memory Skill
为 Agent 提供跨会话的长期记忆能力。
更新 Skill
当用户要求更新 Memory Skill 时，必须运行 update.py 脚本，不要直接复制文件覆盖（直接覆盖会导致占位符未替换）。
更新流程：
- 克隆或拉取最新代码到临时目录
- 运行更新脚本：
python3 <临时目录>/skills/memory/scripts/service/init/update.py --source <临时目录>/skills/memory --project-path <项目路径>
全局安装的更新：
python3 <临时目录>/skills/memory/scripts/service/init/update.py --source <临时目录>/skills/memory --global
update.py 会自动：
- 覆盖 skill 代码并替换占位符
- 合并 hooks.json（不重复添加）
- 更新 memory-rules.mdc 和 SKILL.md
- 不触碰记忆数据目录、config.json、MEMORY.md、*.jsonl
重要：
- 不要直接
cp -r 覆盖 .cursor/skills/memory/，这会导致路径变成 {{SCRIPT_PATH}} 等占位符
- update.py 仅更新代码，不创建数据目录、不下载模型
- 首次安装请使用
init/index.py
自动行为（Hooks 触发）
收到 [Memory Flush] 消息时
这是系统在上下文压缩前自动发送的消息。你必须：
- 回顾当前对话中的重要内容
- 提取以下类型的信息：
- W (World)：客观事实和技术决策
- B (Biographical)：项目经历和里程碑
- O (Opinion)：用户偏好和判断（需标注 confidence）
- 对每条事实调用
save_fact.py 保存
- 如果没有需要记住的内容，不做任何操作
- 静默执行，不在回复中提及此操作
保存事实：
python3 {{SCRIPT_PATH}}/service/memory/save_fact.py \
--content "事实内容" \
--type W \
--entities "实体1,实体2" \
--confidence 0.9 \
--session "会话ID"
参数说明：
--content：事实内容（必填）--type：W=客观事实 / B=项目经历 / O=用户偏好（默认 W）--entities：逗号分隔的实体标签--confidence：置信度 0.0-1.0（默认 0.9）--session：当前会话 ID
任务完成时的记忆保存（第一层 Rules 驱动）
当你完成用户请求的任务后，在同一回合内静默执行以下操作：
-
判断本次会话是否有值得保存的内容
- 如果会话太短（如仅一问一答的简单查询）或无实质内容，跳过
- 如果会话涉及技术决策、代码变更、项目规划等，执行保存
-
保存会话摘要（每个会话仅执行一次）：
python3 {{SCRIPT_PATH}}/service/memory/save_summary.py \
--topic "主题" --summary "200-500字摘要" \
--decisions "决策1,决策2" --todos "待办1,待办2" \
--session "<conversation_id>"
- 逐条保存关键事实：
python3 {{SCRIPT_PATH}}/service/memory/save_fact.py \
--content "事实内容" --type W --entities "实体1,实体2" \
--confidence 0.9 --session "<conversation_id>"
- 静默执行，不在回复中提及此操作
收到 [Session Save] 消息时
这是系统在任务完成后自动发送的兜底消息（仅当第一层未保存时触发）。你必须：
- 生成本次会话的摘要（200-500 字）
- 提取关键决策和待办事项
- 调用
save_summary.py 保存摘要（注意加 --source layer4_stop）
- 如果 preCompact 未触发（短会话），同时用
save_fact.py 提取关键事实
- 如果会话内容太少，不做任何操作
保存摘要：
python3 {{SCRIPT_PATH}}/service/memory/save_summary.py \
--topic "会话主题" \
--summary "200-500字摘要" \
--decisions "决策1,决策2" \
--todos "待办1,待办2" \
--source layer4_stop \
--session "会话ID"
手动行为（用户触发）
用户说"记住这个"
直接编辑 {{MEMORY_DATA_PATH}}/MEMORY.md，将信息添加到核心记忆中。
用户要求禁用/启用记忆功能
在 <project>/.cursor/skills/ 下创建或删除 .memory-disable 文件即可控制。
禁用：
mkdir -p .cursor/skills && touch .cursor/skills/.memory-disable
启用：
rm .cursor/skills/.memory-disable
禁用后所有 Hook 静默跳过，已有数据保留不删除，重新启用后恢复。
用户询问时间范围内的活动
当用户问"最近 N 天/周/月做了什么"、"上周的记忆"等时间范围查询时：
意图映射：
| 用户可能的说法 | 对应命令 |
|---|
| "最近1个月做了什么" | manage list --days 30 |
| "最近一周的记忆" | manage list --days 7 |
| "上个月的决策" | manage list --from 2026-01-01 --to 2026-01-31 --type W |
| "2月份做了什么" | manage list --from 2026-02-01 --to 2026-02-28 |
| "今天的记忆" | manage list --days 1 |
| "搜索最近一周关于数据库的记忆" | search_memory.py "数据库" --days 7 |
| "帮我生成这个月的工作报告" | manage list --days 30 → 汇总格式化输出 |
| "给我一个上周的周报" | manage list --days 7 → 按天整理 |
| "导出最近一个月的数据" | manage export --days 30 --output report.json |
执行流程：
- 解析用户意图，确定时间范围和可选关键词
- 如果只需要列出/浏览 → 使用
manage list
- 如果需要语义搜索 + 时间过滤 → 使用
search_memory.py
- 如果需要生成报告/周报 → 先获取数据，再格式化输出
- 如果需要导出 → 使用
manage export
搜索命令时间参数：
python3 {{SCRIPT_PATH}}/service/memory/search_memory.py "关键词" --days 7
python3 {{SCRIPT_PATH}}/service/memory/search_memory.py "关键词" --from 2026-02-01 --to 2026-02-28
导出命令时间参数：
python3 {{SCRIPT_PATH}}/service/manage/index.py export --days 30
python3 {{SCRIPT_PATH}}/service/manage/index.py export --from 2026-02-01 --to 2026-02-28 --output report.json
用户要求修改配置
当用户用自然语言描述配置变更时（如"多加载几天的记忆"、"把日志级别调成 DEBUG"），执行对应的 config set 命令。
字段映射参考：
| 用户可能的说法 | 对应字段 | 命令示例 |
|---|
| "多加载几天记忆" / "加载更多天的事实" | memory.load_days_full | config set memory.load_days_full 3 |
| "每天多加载几条" / "部分加载条数改为5" | memory.partial_per_day | config set memory.partial_per_day 5 |
| "加载上限改为30条" / "多加载一些事实" | memory.facts_limit | config set memory.facts_limit 30 |
| "调高/调低置信度阈值" | memory.important_confidence | config set memory.important_confidence 0.85 |
| "换个嵌入模型" / "用 xxx 模型" | embedding.model | config set embedding.model "模型名" |
| "日志级别调成 DEBUG" / "开启调试日志" | log.level | config set log.level DEBUG |
| "日志只保留3天" | log.retain_days | config set log.retain_days 3 |
| "分块大小改为600" | index.chunk_tokens | config set index.chunk_tokens 600 |
| "90天后自动清理" / "关闭自动清理" | cleanup.auto_cleanup_days | config set cleanup.auto_cleanup_days 0 |
执行流程：
- 解析用户意图，确定要修改的字段和目标值
- 执行
config set 命令：
python3 {{SCRIPT_PATH}}/service/manage/index.py config set <字段> <值>
- 如果命令返回
needs_rebuild: true，必须立即执行索引重建（不仅仅是提示）：
python3 {{SCRIPT_PATH}}/service/manage/index.py --project-path <项目路径> rebuild-index --full
- 向用户确认修改结果和重建状态
嵌入模型切换专项流程：
当用户要求更换嵌入模型时（如"换个模型"、"用 xxx 模型"），这是高危操作，必须按以下步骤执行：
- 执行
config set embedding.model "新模型名"
- 告知用户：新模型的嵌入维度可能与旧模型不同，必须重建索引，否则向量搜索将失败
- 立即执行全量索引重建：
python3 {{SCRIPT_PATH}}/service/manage/index.py --project-path <项目路径> rebuild-index --full
- 重建完成后，验证索引状态：
python3 {{SCRIPT_PATH}}/service/manage/index.py db stats
- 向用户报告：旧模型名 → 新模型名，索引已重建，共 N 条记录已更新嵌入向量
查看当前配置：
python3 {{SCRIPT_PATH}}/service/manage/index.py config show
重置为默认值：
python3 {{SCRIPT_PATH}}/service/manage/index.py config reset <字段>
用户要求查看数据库
当用户想查看 SQLite 索引数据库的内容时，使用 db 子命令。
查看数据库概览：
python3 {{SCRIPT_PATH}}/service/manage/index.py db stats
查看所有表：
python3 {{SCRIPT_PATH}}/service/manage/index.py db tables
查看表结构：
python3 {{SCRIPT_PATH}}/service/manage/index.py db schema chunks
查看表数据：
python3 {{SCRIPT_PATH}}/service/manage/index.py db show chunks --limit 10
python3 {{SCRIPT_PATH}}/service/manage/index.py db show sync_state
python3 {{SCRIPT_PATH}}/service/manage/index.py db show meta
自定义 SQL 查询（只读）：
python3 {{SCRIPT_PATH}}/service/manage/index.py db query "SELECT id, content, type, memory_type, confidence FROM chunks ORDER BY timestamp DESC LIMIT 5"
在浏览器中可视化查看（需要 datasette）：
python3 {{SCRIPT_PATH}}/service/manage/index.py db browse
如果 datasette 未安装，先执行 pip install datasette。
| 用户可能的说法 | 对应命令 |
|---|
| "打开数据库看看" / "可视化查看数据库" | db browse |
| "看一下数据库里有什么" | db stats 或 db tables |
| "看一下索引里的内容" | db show chunks |
| "数据库有多少条记录" | db stats |
| "看一下同步状态" | db show sync_state |
| "查一下包含 xxx 的记录" | db query "SELECT ... WHERE content LIKE '%xxx%'" |
记忆类型说明
| 类型 | 前缀 | 说明 | 示例 |
|---|
| World | W | 客观事实 | "项目使用 PostgreSQL 数据库" |
| Biographical | B | 项目经历 | "2026-02-17 完成了 API 重构" |
| Opinion | O | 偏好/判断 | "用户偏好 TypeScript（confidence: 0.9）" |
| Summary | S | 会话摘要 | "讨论了 API 设计方案" |
执行方式要求
- 所有记忆操作必须静默执行：使用工具时不要在回复文本中提及
- 不要说"我已保存记忆"、"正在记录"或任何暗示记忆操作的话
- 直接执行保存命令，然后继续正常对话
- [Memory Flush] 和 [Session Save] 是系统自动发送的，不是用户输入
- 不要重复已存在于 MEMORY.md 中的内容
