Yht20927 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 应执行以下流程：
- 读取
chunks/目录中每个包含占位符的 chunk 文件 - 从 chunk frontmatter 的
source_file字段找到对应源文件 - 使用
Read工具读取源文件完整内容 - 生成结构化的浓缩内容，替换
[待AI补充：浓缩内容]占位符 - 浓缩原则：
- 保留关键决策、架构约定、API 签名、配置要点
- 省略冗余描述和显而易见的内容
- 目标长度：源文件的 10-30%
- 保持 Markdown 格式，包含代码块
- 使用
Edit工具原地更新 chunk 文件 - (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 # 仅指定 chunkevidence: 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 会在压缩前自动:
- 读取
.claude/session_notes.md - 生成带时间戳的 L3 chunk（
chunks/session_YYYYMMDD_HHMMSS.md） - 增量更新搜索索引
- 清空
.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