mcmemory

name	mcMemory
description	mcMemory (mcm) - 分层记忆管理系统。命令以 "mcm" 开头。项目记忆支持 L1-L4 层级，个人记忆支持 L1-L3 层级。存储于 ~/.claude/mcMemories/。
allowed-tools	["Bash","Read","Write","Grep"]

mcm - mcMemory 分层记忆管理系统

分层记忆管理系统。项目记忆支持 L1-L4，个人全局记忆支持 L1-L3。

存储路径: ~/.claude/mcMemories/ (原 ~/.claude/memory/)

命令列表

命令	功能	入口
mcmInit	初始化项目/个人记忆	commands/init.sh
mcmSync	增量同步已有记忆	commands/sync.sh
mcmLoad <名称>	加载记忆到当前会话上下文	commands/load.sh
mcmSearch <关键词>	全文搜索记忆（--score 按 BM25×权重排序）	commands/search.sh
mcmList	列出所有已注册记忆	commands/list.sh
mcmStatus	记忆健康总览；--drift 100 点评分（v3.3）	commands/status.sh
mcmDelete <名称>	删除记忆（移至回收站）	commands/delete.sh
mcmUpdate <名称>	更新记忆元数据	commands/update.sh
mcmExport <名称>	导出记忆为归档	commands/export.sh
mcmImport <文件>	从归档导入记忆	commands/import.sh
mcmRestore <条目>	从回收站恢复	commands/restore.sh
mcmEmptyTrash	清空回收站	commands/empty-trash.sh
mcmAutoInject	一键开启/关闭/暂停自动注入	commands/auto-inject.sh
mcmInjectLog [--tail N]	查看自动注入事件日志	commands/inject-log.sh
mcmJournal <文本>	一行命令追加会话笔记（PreCompact 时归档为 L3 chunk）	commands/journal.sh
mcmDoctor [--fix]	健康检查 + 自动迁移脏 tag 目录 + 占位 chunk 报告	commands/doctor.sh
mcmMark <名称>	标注 chunk 来源/证据等级（source/evidence → BM25 权重）	commands/mark.sh
mcmLedger <子命令>	会话决策日志：add/list/resolve/show 结构化决策/待办/阻断	commands/ledger.sh
mcmRemote <子命令>	git 远程共享：init/add/list/remove/device	commands/remote.sh
mcmPush	提交并推送记忆到 git remote	commands/push.sh
mcmPull	拉取并合并，冲突不静默	commands/pull.sh

公共参数

• --global - 对全局个人记忆操作（而非项目记忆）
• --json - 机器可读 JSON 输出（list / search / status / ledger 支持）
• --scope - 作用域：project（默认）或 user
• --help - 显示帮助信息

Hook 配置（自动注入）

本 skill 提供 3 个 Hook 脚本实现自动记忆注入：

Hook 事件	脚本	功能
SessionStart	hooks/session-start.sh	新会话自动加载项目 L1 + auto 全局 L3
UserPromptSubmit	hooks/prompt-submit.sh	智能提取关键词，检索相关记忆注入
PreCompact	hooks/pre-compact.sh	上下文压缩前保存会话摘要

一键开启:

mcmAutoInject on          # 当前项目启用
mcmAutoInject on --scope user   # 全局启用
mcmAutoInject status      # 查看状态
mcmAutoInject off         # 关闭

# 临时暂停（不改 settings.json，到点自动恢复）
mcmAutoInject pause 30m   # 暂停 30 分钟
mcmAutoInject pause 2h    # 暂停 2 小时
mcmAutoInject resume      # 立即取消

# 全局停止（无条件 kill-switch，需显式取消）
mcmAutoInject stop        # 全局停止所有注入
mcmAutoInject unstop      # 取消全局停止

# 查看注入日志（哪些记忆在什么时间被注入、得分、关键词）
mcmInjectLog              # 最近 20 条
mcmInjectLog --tail 50
mcmInjectLog --json

注入策略:

• BM25 评分 (v2.4/v3.1): 标准 BM25 (k1=1.2, b=0.75) + Robertson IDF + 中英文关键词提取；header 命中权重 ×3
• 证据/来源分层 (v3.3): final_score = bm25 × source_w × evidence_w，per memory 取 best evidence wins。source: user=1.0/agent=0.7/system=0.5，evidence: validated=1.0/observed=0.85/hypothesis=0.6。AI 浓缩内容默认 agent/observed=0.595 折扣防幻觉；mcmMark --source user --evidence validated 提升已验证知识至 1.0
• 冷却机制: 同一记忆 120 秒内不重复注入
• 相关性阈值: BM25 score ≥ INJECT_BM25_MIN_SCORE（默认 0，即任何正分；可调）
• 长度控制: 单次注入最多 3 个记忆，总内容受 token 预算限制
• 搜索索引优先: 使用预建索引进行快速匹配
• 可观测 (v3.0): 全部 16 命令接入 NDJSON 事件总线；mcmInjectLog 查看注入历史

目录结构

~/.claude/mcMemories/
├── projects/                    # 项目记忆（L1-L4）
│   ├── index.md                 # 项目总索引
│   ├── {tag}/                   # 按标签分组的项目目录（自由标签）
│   │   └── <project-name>/
│   │       ├── summary.md       # L1
│   │       ├── index.md         # L2
│   │       ├── hash.json        # 文件哈希（相对路径 key）
│   │       ├── chunks/          # L3
│   │   │       └── .claude/         # L4 device registry（.claude/l4/<device>.json）
├── global/                      # 个人全局记忆（L1-L3）
│   ├── index.md
│   ├── auto/                    # 自动加载型
│   └── on_demand/               # 关键词触发型
└── .trash/                      # 回收站

层级说明

层级	内容	说明
L1	项目文件夹	项目名 + 简介
L2	大纲索引	标题 + 标签 + 摘要句 + 行号范围
L3	浓缩内容	从原始文件 AI 浓缩的核心内容（chunks/*.md）
L4	原始链接	指向源文件的引用（仅项目，device-keyed JSON registry）

架构说明 (v2.0)

• 纯 bash 脚本: 所有命令为 .sh 文件，直接 source lib/core.sh
• 动态标签: 标签不再硬编码，从目录结构自动发现
• 相对路径: hash.json 和 L4 链接优先使用相对路径
• 并发锁: 写操作使用 flock/mkdir 互斥锁
• 回收站: 删除操作移至 .trash/ 而非永久删除
• 搜索索引: sync 时自动重建合并搜索索引，加速搜索
• 大文件拆分: 超过 CHUNK_SPLIT_THRESHOLD (默认 200 行) 的源文件按 ## 标题自动拆分为多个 chunk
• 非 .md 源文件: 自动检测 package.json, Makefile, docker-compose.yml 等配置文件

AI 记忆浓缩指令

重要: 当 mcmInit 或 mcmSync 完成后，如果 chunk 文件包含 [待AI补充：浓缩内容] 占位符，Claude 应执行以下流程：

1. 读取 chunks/ 目录中每个包含占位符的 chunk 文件
2. 从 chunk frontmatter 的 source_file 字段找到对应源文件
3. 使用 Read 工具读取源文件完整内容
4. 生成结构化的浓缩内容，替换 [待AI补充：浓缩内容] 占位符
5. 浓缩原则：
   • 保留关键决策、架构约定、API 签名、配置要点
   • 省略冗余描述和显而易见的内容
   • 目标长度：源文件的 10-30%
   • 保持 Markdown 格式，包含代码块
6. 使用 Edit 工具原地更新 chunk 文件
7. (v3.3) AI 浓缩的 chunk 默认 frontmatter 带 source: agent / evidence: observed（0.595 折扣防幻觉）。若该 chunk 内容来自用户明确确认的决策，可改标 source: user / evidence: validated 提升其在自动注入中的权重：

   mcmMark <名称> --source user --evidence validated          # 整个记忆所有 chunk
   mcmMark <名称> --chunk 1_ARCHITECTURE --evidence validated # 仅指定 chunk
   

   反之，对猜测性/未验证的内容可降为 evidence: hypothesis（0.6）以降低注入优先级。

加载策略

自动注入模式（推荐）:

• 运行 mcmAutoInject on 一次配置 Hook
• SessionStart: 自动加载项目记忆 L1 + auto 全局记忆 L3
• UserPromptSubmit: 用户提问时智能检索并注入相关记忆
• PreCompact: 上下文压缩前自动保存会话要点（见下方）

手动模式:

• 会话启动时，Claude 应自动运行 mcmList 了解可用记忆
• 对 auto 标签的全局记忆，自动调用 mcmLoad --layer L3 加载浓缩内容
• 对项目记忆，进入项目目录后自动调用 mcmLoad 加载相关记忆
• 提问涉及特定领域时，先 mcmSearch 检索相关记忆再回答

会话笔记（PreCompact 保存）

重要: 在会话过程中，当出现以下情况时，Claude 应主动追加到 .claude/session_notes.md：

触发写入的场景:

• 做出了重要的架构或设计决策
• 发现并修复了 bug（记录根因和修复方式）
• 学习了新的项目约定或工作流程
• 用户明确表示"记住这个"
• 在回答复杂问题前搜集了有价值的上下文

推荐方式（v2.4+）: 使用 mcmJournal 一行命令，免去 Write 工具的门槛：

mcmJournal "决策: 用 BM25 替换 sqrt(n) 归一化；原因: 后者无理论依据"
mcmJournal "Bug fix: prompt_submit_inject 永不注入；根因: score 二次过滤"
echo -e "决策 A\n决策 B" | mcmJournal --stdin    # 多行
mcmJournal --show                                  # 查看当前笔记

或直接 Write .claude/session_notes.md 添加结构化条目：

## <简短标题>

**决策**: <一句话描述>
**原因**: <为什么这样做>
**涉及文件**: <相关文件路径>

pre-compact.sh hook 会在压缩前自动:

1. 读取 .claude/session_notes.md
2. 生成带时间戳的 L3 chunk（chunks/session_YYYYMMDD_HHMMSS.md）
3. 增量更新搜索索引
4. 清空 .claude/session_notes.md 以备下次会话

这样不会丢失跨会话的决策上下文，且可在 mcmSearch 中检索到。

执行命令

当用户调用 mcmXxx 时，执行对应的 commands/xxx.sh。

共享工具库

公共函数位于 lib/core.sh (v2.0)，各命令通过 source 加载。

---

版本: v4.0 | git 远程记忆共享（mcmRemote/mcmPush/mcmPull） | L4 device-keyed registry（弃软链） | .gitignore 派生分离 + .gitattributes merge=union | SessionStart ff-only auto-pull | 会话决策日志 ledger | drift 100 点评分 | 证据/来源分层 | mcmMark | op-log | STOP kill-switch | doctor canary | BM25 注入 | NDJSON 事件总线 | 2026-07-09