kimyx0207/kim_service/memory-3layer

三层记忆

把会影响后续工作的知识保存为可检查、可迁移、可控制生命周期的项目资产。默认数据目录是项目根目录下的 .memory-3layer/；MEMORY_DIR 可以显式覆盖。

目标合同

为正在进行长期项目、会跨会话切换 Agent 的用户，生成一套人和 Agent 都能检查的三层记忆，并满足以下可观察标准：

• Layer 1 在 areas/topics/<topic>/items.json 保存带状态的结构化事实。
• Layer 2 在 memory/YYYY-MM-DD.md 保存按日期追加的工作轨迹。
• Layer 3 在 MEMORY.md 保存人工确认的长期隐性知识。
• 新会话只加载受预算约束的 active 内容，不把整个历史塞进上下文。
• 旧知识可标记为 superseded，不靠删除历史来制造“最新事实”。
• Claude Code 与 Codex 的自动化都调用同一 Python 核心；其他平台不伪装成自动支持。

触发与非触发

使用本技能：

• 用户要求“记住这条规则”“下次继续”“跨会话保存”“查看/清理项目记忆”。
• 项目已有 .memory-3layer/，当前任务需要读取其中的长期上下文。
• 项目仍有 .claude/memory/，用户要迁移到平台中立目录。
• 需要为 Claude Code 或 Codex 接入三层记忆生命周期。

不要使用：

• 只需写一次性日志、缓存、构建输出或完整会话转储。
• 内容包含口令、令牌、私钥、支付信息、未脱敏个人数据或不应进入版本库的材料。
• 用户只想使用宿主自己的私有记忆，且不需要项目级共享与生命周期管理。

第一动作

在写入前先确认五项事实：项目根目录、当前宿主、.memory-3layer/ 是否存在、legacy .claude/memory/ 是否存在、当前任务是否授权写入。无法确认项目根目录或写入权限时，只报告发现，不创建或迁移文件。

输入与输出

输入：

• 项目根目录；默认当前 Git 根，非 Git 项目用当前工作目录。
• 当前运行平台：claude、codex 或 manual。
• 用户明确要求记住的内容，或宿主 Hook 提供的事件负载。
• 可选环境变量：MEMORY_DIR、MEMORY_MAX_ITEMS、MEMORY_DAILY_DAYS、MEMORY_TOPICS。

输出：

• .memory-3layer/ 中变更后的三层记忆文件。
• 本次动作摘要：读取了什么、写入了什么、跳过了什么、下一步是什么。
• 失败时给出具体失败路线，不把“Hook 已配置”说成“Hook 已运行”。

执行步骤合同

平台能力矩阵

“支持 Agent Skills”不等于“自动支持其 Hook 协议”。没有适配器或运行证据时，一律标为 manual。

六类边界

1. 非目标边界：不替代 Git、数据库、备份、宿主原生记忆，也不保存完整聊天历史。
2. 事实来源边界：只记录用户确认、文件证据或已知 Hook 字段；模型推断必须标注，不能直接升级为长期事实。
3. 权限边界：读取项目内公开记忆；写入、迁移、修改状态必须符合用户授权，不修改项目外全局配置。
4. 副作用边界：默认只改 .memory-3layer/ 和明确选择的平台配置；合并现有配置，不覆盖无关 Hooks；不自动提交 Git。
5. 停止边界：秘密、路径歧义、格式损坏、迁移冲突、配置无法安全合并或校验失败时立即停止对应写操作。
6. 降级边界：自动 Hook 不可用或未获信任时，退回 manual；保留核心读写能力，但明确自动加载/提取/压缩保护没有发生。

迁移规则

旧版默认路径 .claude/memory/ 只作为只读发现来源，不再作为新写入默认值。只有用户明确要求迁移时才运行：

python scripts/migrate_legacy_memory.py --project-dir <目标项目>

迁移默认复制到 .memory-3layer/、不覆盖现有文件、不删除 legacy。完整冲突规则见 references/migration.md。

显式记录

用户说“记住”时，由 Agent 调用受控记录入口；不要假设普通 PostToolUse 输出会自动变成事实：

python scripts/record_memory.py --project-dir <目标项目> --fact "这个项目统一使用 pnpm" --topic workflow

只有本包受管记录器传入的顶层 memory_fact 可以持久化。任何工具响应中的 summary、fact、confirmed 或其他原始输出都默认忽略。

渐进加载

• 需要安装、信任或排查宿主接线：读 references/runtime-adapters.md。
• 需要逐字段判断输入输出、事实来源和失败路线：读 references/operating-contract.md。
• 发现 .claude/memory/ 或用户要求改路径：读 references/migration.md。
• 需要理解三层目录和数据流：读 docs/architecture.md。
• 需要给用户最短上手步骤：读 docs/quickstart.md。

验证

先验证平台中立核心，再验证目标平台适配器：

python scripts/check_memory_3layer.py
python -m unittest discover -s evals -p "test_*.py"

静态测试不能证明宿主已触发 Hook。Claude Code 需在新会话观察加载事件；Codex 需先通过 /hooks 信任，再在新会话观察加载事件。报告时分开写：

• artifact_status：文件与结构是否一致。
• adapter_status：平台配置是否合并成功。
• runtime_status：真实宿主事件是否触发并产生预期输出。

发布来源

当前公开源是 KimYx0207/Kim_Service 中的 skills/memory-3layer/。旧 KimYx0207/claude-memory-3layer 仅保留历史 provenance，不再作为安装源或当前能力声明依据。