memory

name	memory
description	管理 AI Agent 的长期记忆系统。自动记住重要对话、决策和用户偏好， 并在新会话中召回相关信息。当收到 [Memory Flush] 或 [Session Save] 系统消息时自动执行记忆操作。当用户提到"记住"、"记忆"、"之前讨论过"时使用。

Memory Skill

为 Agent 提供跨会话的长期记忆能力。

更新 Skill

当用户要求更新 Memory Skill 时，必须运行 update.py 脚本，不要直接复制文件覆盖（直接覆盖会导致占位符未替换）。

更新流程：

1. 克隆或拉取最新代码到临时目录
2. 运行更新脚本：

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] 消息时

这是系统在上下文压缩前自动发送的消息。你必须：

1. 回顾当前对话中的重要内容
2. 提取以下类型的信息：
   • W (World)：客观事实和技术决策
   • B (Biographical)：项目经历和里程碑
   • O (Opinion)：用户偏好和判断（需标注 confidence）
3. 对每条事实调用 save_fact.py 保存
4. 如果没有需要记住的内容，不做任何操作
5. 静默执行，不在回复中提及此操作

保存事实：

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 驱动）

当你完成用户请求的任务后，在同一回合内静默执行以下操作：

1. 判断本次会话是否有值得保存的内容

   • 如果会话太短（如仅一问一答的简单查询）或无实质内容，跳过
   • 如果会话涉及技术决策、代码变更、项目规划等，执行保存

2. 保存会话摘要（每个会话仅执行一次）：

python3 {{SCRIPT_PATH}}/service/memory/save_summary.py \
  --topic "主题" --summary "200-500字摘要" \
  --decisions "决策1,决策2" --todos "待办1,待办2" \
  --session "<conversation_id>"

3. 逐条保存关键事实：

python3 {{SCRIPT_PATH}}/service/memory/save_fact.py \
  --content "事实内容" --type W --entities "实体1,实体2" \
  --confidence 0.9 --session "<conversation_id>"

4. 静默执行，不在回复中提及此操作

收到 [Session Save] 消息时

这是系统在任务完成后自动发送的兜底消息（仅当第一层未保存时触发）。你必须：

1. 生成本次会话的摘要（200-500 字）
2. 提取关键决策和待办事项
3. 调用 save_summary.py 保存摘要（注意加 --source layer4_stop）
4. 如果 preCompact 未触发（短会话），同时用 save_fact.py 提取关键事实
5. 如果会话内容太少，不做任何操作

保存摘要：

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

执行流程：

1. 解析用户意图，确定时间范围和可选关键词
2. 如果只需要列出/浏览 → 使用 manage list
3. 如果需要语义搜索 + 时间过滤 → 使用 search_memory.py
4. 如果需要生成报告/周报 → 先获取数据，再格式化输出
5. 如果需要导出 → 使用 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

执行流程：

1. 解析用户意图，确定要修改的字段和目标值
2. 执行 config set 命令：

python3 {{SCRIPT_PATH}}/service/manage/index.py config set <字段> <值>

3. 如果命令返回 needs_rebuild: true，必须立即执行索引重建（不仅仅是提示）：

python3 {{SCRIPT_PATH}}/service/manage/index.py --project-path <项目路径> rebuild-index --full

4. 向用户确认修改结果和重建状态

嵌入模型切换专项流程：

当用户要求更换嵌入模型时（如"换个模型"、"用 xxx 模型"），这是高危操作，必须按以下步骤执行：

1. 执行 config set embedding.model "新模型名"
2. 告知用户：新模型的嵌入维度可能与旧模型不同，必须重建索引，否则向量搜索将失败
3. 立即执行全量索引重建：

python3 {{SCRIPT_PATH}}/service/manage/index.py --project-path <项目路径> rebuild-index --full

4. 重建完成后，验证索引状态：

python3 {{SCRIPT_PATH}}/service/manage/index.py db stats

5. 向用户报告：旧模型名 → 新模型名，索引已重建，共 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 中的内容