三层记忆模型概览

项目定位与设计目标

claude-memory-kit（命令行工具名为 cmk）是一个面向项目的、存储于代码仓库内的持久化记忆系统，专为 Claude Code 打造。它解决了 Claude 在每个会话结束即"遗忘"上下文的核心痛点——开发者不再需要在新会话中重复解释项目背景、技术栈偏好与历史决策。

与 Anthropic 原生的自动记忆（auto-memory）机制不同，本项目将记忆内容以纯 Markdown 格式提交到项目代码仓库中，随 git clone 自然流转到团队成员的本地环境。这种"项目内、仓库级、随代码走"的定位带来三大优势：

1. 可审计性：记忆以人类可读的 Markdown 文件存储，而非不透明的状态数据库。
2. 可移植性：通过 git clone 即获得完整项目记忆，无需额外同步机制。
3. 可治理性：记忆的变更可与代码变更一同通过 Pull Request 审查与回滚。

三层记忆范围架构

本系统的核心创新在于引入了三层记忆范围（Three-Tier Memory Scope）模型，每一层都有明确的归属与流转规则：

graph TD
    A[项目记忆 context/] -->|git clone 流转| B[协作者本地副本]
    C[用户画像 ~.claude-memory-kit/] -->|显式 export/import| D[用户跨机器]
    E[用户偏好 ~/.claude-memory-kit/] -->|不提交| F[本地独占]
    
    A -.随仓库提交.-> G[(committed scope)]
    C -.跨项目共享.-> H[(persona scope)]
    E -.机器本地.-> I[(local scope)]

第一层：项目记忆（Committed Scope）

项目记忆存储于项目根目录下的 context/ 文件夹中，以纯 Markdown 格式保存决策、约定、工具特性等可被团队共享的知识。该层记忆随代码一同提交到 Git 仓库，确保所有 git clone 该项目的协作者都能获得一致的项目上下文。

第二层：用户画像（Persona Scope）

用户画像存储于 ~/.claude-memory-kit/ 目录，记录用户的工作习惯与偏好。该层记忆跨项目共享，体现用户在所有项目中的统一行为模式（例如"始终使用 uv，绝不依赖 pip"）。画像可通过 cmk persona export/cmk persona import 命令在用户的多台机器间显式同步。

第三层：本地偏好（Local Scope）

本地偏好同样存储于 ~/.claude-memory-kit/，但仅在当前机器上生效，绝不提交。它承载机器特定的配置信息（如本地路径、环境变量），确保工作风格的隐私性——绝不会因 git clone 而泄露到所有协作者。

记忆捕获与召回工作流

记忆系统的完整生命周期包含自动捕获、按需召回与压缩治理三个阶段：

sequenceDiagram
    participant U as 用户
    participant CC as Claude Code
    participant Hook as PreToolUse 钩子
    participant Mem as context/ 记忆存储
    participant MCP as MCP 服务器
    
    U->>CC: 发起对话
    CC->>Hook: 工具调用前触发
    Hook->>Mem: 注入冻结的记忆快照
    Mem-->>CC: 返回 SOUL.md + USER.md + MEMORY.md + INDEX.md
    CC->>MCP: 注册 MCP 服务器工具
    MCP-->>CC: 提供记忆读写能力
    CC->>Mem: 自动提取关键决策
    Mem-->>U: 在后续会话中按语义召回

自动捕获机制

系统在每个助手回合（assistant turn）后自动运行提取作业（auto-extract），将持久性事实（决策、约定、工具使用特性）保存为可搜索的笔记。开发者无需手动点击"保存"按钮——这一过程完全在后台静默执行。

按语义召回

与传统的关键词搜索不同，本系统支持基于含义的召回（recall by meaning）。用户可以用自然语言提问（例如"凭据存储在哪里"），即使查询词与记忆内容零关键词重叠，系统也能定位到正确的事实。基准测试显示其召回质量达到 R@5 0.941 / paraphrase 1.000 的水平。

压缩治理

为防止记忆无限膨胀，系统实现了会话 → 每日 → 每周三层滚动压缩机制（rolling compression）。session-buffer rollup 在会话开始时自动执行，确保即使历史不断增长，记忆快照始终保持精简。该压缩作业在无时间限制的会话窗口中执行，避免因 Claude 响应慢而导致压缩失败。

核心能力特性

CLI 命令速查

安全与隐私设计

系统在设计时充分考虑了隐私保护与操作安全：

• 密钥屏蔽：所有写入操作在提交前自动扫描并屏蔽敏感信息（API 密钥、Token）。
• 路径抽象：机器特定路径被抽象为 ~，避免泄露本地目录结构。
• 破坏性命令拦截：cmk install 时挂载的 PreToolUse 钩子会阻断针对记忆路径的破坏性命令（如 rm、git clean、git reset --hard），在 Claude Code 与 Kiro 两个智能体上均生效。
• 保守卸载：cmk uninstall 永远不删除 context/ 目录，确保项目记忆不会因卸载而丢失。

参见

• Claude Code 官方文档 — 了解宿主智能体能力
• MCP 协议规范 — 记忆工具的通信协议
• LongMemEval 基准测试 — 召回质量的评估方法论

安装、CLI 参考与 Agent 接入面（Claude Code + Kiro）

概览与设计目标

claude-memory-kit（以下简称 "kit"）是一个为 Claude Code 提供持久化、按项目、随仓库提交的记忆系统。它通过 cmk CLI、Claude Code 插件和 Kiro 适配器三种分发形态，让任何 Agent 都能在会话间保持上下文连续性。核心思路是把记忆落盘为可读的 Markdown，保存在 context/ 目录里随 git clone 一同分发；冷启动项目时通过生命周期钩子注入"冻结快照"，实现"开箱即知"。

资料来源：README.md:1-60

该工具解决的根本问题是：每次开启新会话，Claude 都会遗忘之前的项目背景、用户偏好和历史决策。kit 通过自动捕获 + 语义检索 + 跨项目人格三层能力让 Agent 持续记忆而不需要手动维护。CLI 与 MCP server 是双入口——CLI 面向开发者终端操作，MCP server 面向 Agent 在对话中调用工具。

安装路径

kit 提供两条并列安装路径，必须二选一（README.md 明确警告）。

路径 A：npm CLI（推荐）

npm install -g @lh8ppl/claude-memory-kit
cd ~/my-project
cmk install                              # 完整入口：脚手架 + 钩子 + MCP 注册
cmk install --with-semantic              # 可选：本地语义检索（一次性约 260 MB）
cmk install --ide kiro                   # 可选：改为接入 Kiro
cmk register-crons                       # 可选：注册后台压缩任务
cmk import-claude-md --yes               # 可选：从现有 CLAUDE.md 导入
cmk doctor                               # 校验后重启 Claude Code

cmk install 是完整入口：搭建 context/、投放 memory-write / memory-search 技能（committed）、将 5 个生命周期钩子写入 .claude/settings.json、在 .mcp.json 注册 MCP server 并白名单 mcp__cmk__* 工具，同时写入 .gitattributes 强制 LF 换行（跨平台兼容）。资料来源：packages/cli/README.md:1-40

路径 B：Claude Code 插件

/plugin marketplace add <your-username>/claude-memory-kit
/plugin install claude-memory-kit
# 在目标项目内
/claude-memory-kit:bootstrap

插件通过 ${CLAUDE_PLUGIN_ROOT} 加载钩子，不修改项目的 .claude/settings.json。注意：插件不配置 cron（层 6 仍需 cmk register-crons），也不在会话启动时自动跑 bootstrap——这是按项目主动调用的。资料来源：plugin/README.md:1-60

两种路径更新方式不同：插件用 /plugin update，CLI 用 npm update -g。两者都需要重新戳记每个项目的脚手架（CLI 重跑 cmk install，插件重跑 /claude-memory-kit:bootstrap）。

CLI 命令参考

packages/cli/package.json 定义了 11 个二进制入口，覆盖安装、压缩、捕获、观察、注入与防护。下表汇总核心命令：

资料来源：README.md:60-110 与 packages/cli/package.json:1-30

健康检查（HC-1..HC-9）逐项报告 PASS/FAIL/SKIP 并给出修复命令，其中 HC-9 检测脚手架是否落后于已安装的 cmk 版本。语义检索（--with-semantic 安装后默认 hybrid）使用本地 sqlite-vec + bge-base 嵌入模型，R@5 达 0.941、paraphrase recall 1.000、零 API 调用。资料来源：README.md:30-50

后台压缩与 v0.3.5 修复

社区最近反馈的问题已在 v0.3.5 修复：生命周期压缩任务（daily distill、weekly curate、会话启动补滚）与会话内压缩器共用 50 秒预算，重试过快——claude --print 在高峰期容易超时，导致 recent.md 与归档未能及时更新。v0.3.5 为这些"无时限"任务放宽预算并降低重试频率，使后台压缩即使在 Claude 响应慢时也能稳定推进。

Agent 接入面（Claude Code 与 Kiro）

kit 通过适配器层将同一份记忆系统暴露给不同 Agent。默认目标 claude-code，通过 --ide kiro 切换。

Claude Code 接入

cmk install 在 .claude/settings.json 写入 5 个生命周期钩子（PATH 解析、跨 OS）并注册 MCP server。Claude 可通过 mcp__cmk__* 工具在对话中直接驱动记忆操作——无需每次提示。安全方面，cmk-guard-memory 是一个 PreToolUse 钩子，在命令执行前阻断针对 context/、人格目录或 MEMORY.md / DECISIONS.md 的破坏性命令（rm、Remove-Item、del、git clean、git reset --hard、find … -delete、truncate、->-truncate），覆盖 Bash / PowerShell`。该护栏默认 fail-open——损坏的护栏不会卡死会话，只会停止防护；宁可误报可改写，也不放过真正危险的操作。资料来源：README.md:130-160

Kiro 接入

cmk install --with-semantic --ide kiro   # 同时接入 IDE 与 kiro-cli
cmk doctor                                # 验证后重启 Kiro

--ide kiro 写入的表面包括：.kiro/settings/mcp.json（含 autoApprove，IDE 使用）、steering 文件、AGENTS.md、skills、IDE 钩子与 CLI 代理配置。完成后必须重启 Kiro 让钩子加载。Kiro 是 kit 的一等公民目标，与 Claude Code 共享同一份 context/ 记忆。资料来源：README.md:50-80

接入面架构

graph TB
    subgraph 用户层
        U[开发者终端]
        CC[Claude Code 会话]
        K[Kiro IDE / kiro-cli]
    end
    
    subgraph 接入层
        CLI[cmk CLI<br/>11 个二进制]
        MCP[MCP Server<br/>mcp__cmk__*]
        PLG[Claude Code 插件]
        KIRO[Kiro 适配器<br/>--ide kiro]
    end
    
    subgraph 核心层
        CTX[context/<br/>项目级记忆]
        PERSONA[~/.claude-memory-kit/<br/>用户级人格]
        CANON[cmk-canonicalize<br/>Node + Python 字节一致]
    end
    
    U --> CLI
    CC --> MCP
    CC --> PLG
    K --> KIRO
    CLI --> CTX
    MCP --> CTX
    PLG --> CTX
    KIRO --> CTX
    CLI --> PERSONA
    CANON -.-> CLI
    CANON -.-> MCP

记忆规范化层 @lh8ppl/cmk-canonicalize（同时提供 Node 与 Python 实现，输出字节一致）为 CLI 与 MCP server 计算内容寻址 ID 提供基础。资料来源：packages/canonicalize/package.json:1-30 与 python/README.md:1-20

配置与排错

记忆分层结构：

项目记忆随 git clone 传播给队友；人格跟随用户，永不提交——避免工作习惯泄露。可通过 cmk persona export/import 在自有机器间迁移。资料来源：README.md:90-120

常见排错路径：先用 cmk doctor 跑 HC-1..HC-9，再用 cmk repair --hooks|--locks|--index|--all 幂等修复。无法运行 cron 时压缩降级为会话启动时的懒加载回读，记忆仍受控，只是从主动变被动。资料来源：README.md:160-180

See Also

• Claude Code plugin documentation
• Kiro integration guide（见 README.md "Working with Kiro" 章节）
• MCP server reference
• CLI full reference
• Semantic backend ADR-0015

一、设计目标与系统总览

claude-memory-kit 是一个面向 Claude Code 的、按项目划分的、提交到仓库内的纯 Markdown 记忆系统。其核心目标是解决 Claude 会话结束即遗忘上下文的问题：每次新会话不再需要重复解释项目背景、技术栈与个人偏好 资料来源：README.md:23-25。

整个系统按 monorepo 组织，工作区位于 packages/* 资料来源：package.json:7-9，目前公开的核心包有两个：

资料来源：packages/cli/package.json:30-43、packages/canonicalize/package.json:1-7。

记忆按 三层作用域 组织，生命周期与可见性各异：

• 项目记忆：随仓库走（context/），队友克隆即可获得。
• 用户记忆：跨项目，按人划分（~/.claude-memory-kit/），机器本地、永不提交，避免风格泄露。
• 会话级（运行时）：每次会话注入的冻结快照，不进入永久存储。

资料来源：README.md:36-44。

二、核心组件

CLI 包通过 bin 字段暴露了十个可执行入口，每个入口对应一个明确的生命周期阶段 资料来源：packages/cli/package.json:10-21：

cmk                     ← 主 CLI
cmk-daily-distill       ← 每日蒸馏
cmk-weekly-curate       ← 每周策展
cmk-compress-lazy       ← 懒压缩（兜底）
cmk-inject-context      ← 会话起始注入快照
cmk-capture-prompt      ← 捕获用户提示
cmk-observe-edit        ← 观察文件编辑
cmk-capture-turn        ← 捕获一轮助手回合
cmk-compress-session    ← 会话缓冲滚动
cmk-guard-memory        ← 删除护栏（PreToolUse）

在此之上，系统由四类相互协作的组件构成：

1. 生命周期钩子（Hooks） — 由 cmk install 写入 .claude/settings.json，跨平台通过 PATH 解析，涵盖 UserPromptSubmit（捕获）、PreToolUse（注入快照 + cmk-guard-memory 删除护栏）、Stop/SessionEnd（捕获转录 + 启动 auto-extract 后台子代理）等 资料来源：packages/cli/README.md:8-12、README.md:174-180。
2. 技能（Skills） — memory-write（显式保存/遗忘）、memory-search（自动触发的事实回查）、bootstrap（一次性脚手架），会被提交到 .claude/skills/，随仓库克隆传播 资料来源：packages/cli/README.md:13-15。
3. MCP 服务器 — 安装时在 .mcp.json 注册并在 .claude/settings.json 中 allow-list mcp__cmk__*，从而 Claude 可在对话中无提示驱动记忆：捕获（mk_remember）、回查（mk_search / mk_get / mk_timeline / mk_cite）、信任度调整（mk_trust）、跨项目提升（mk_lessons_promote）、遗忘（mk_forget）、队列处理（mk_queue_list / mk_queue_resolve） 资料来源：README.md:128-135。
4. 搜索后端 — 默认关键字（FTS5 单次），可选 --with-semantic 启用本地 sqlite-vec + bge-base 嵌入模型，混合检索 R@5 0.941、paraphrase 召回 1.000，全程零 API 调用 资料来源：README.md:95-103。

插件分发形态（plugin/）通过 hooks/hooks.json 注册同一组生命周期事件，但不修改 .claude/settings.json，也不替代 cron（Layer 6） 资料来源：plugin/README.md:19-24。

三、数据流与会话生命周期

下图展示了从会话开始到压缩回收的端到端数据流。

flowchart LR
    A[会话开始] --> B[PreToolUse<br/>cmk-inject-context]
    B --> C[注入冻结快照<br/>SOUL/USER/MEMORY/INDEX + 今日日志]
    C --> D[用户回合]
    D --> E[UserPromptSubmit<br/>cmk-capture-prompt]
    E --> F[助手回合]
    F --> G[Stop / SessionEnd<br/>cmk-capture-turn + auto-extract]
    G --> H[(claude --print 子代理<br/>提取持久事实)]
    H --> I[写入 context/ 事实文件<br/>三层作用域之一]
    I --> J{压缩触发}
    J -- 定时 --> K[cmk-daily-distill<br/>cmk-weekly-curate]
    J -- 会话开始 --> L[cmk-compress-session 兜底]
    J -- 手动 --> M[cmk roll --scope now/today/recent]
    K --> N[(recent.md / 归档)]
    L --> N
    M --> N
    D -.recall.-> O[mk_search / cmk search]
    O --> P[cite id 回到事实正文]
    F -.guard.-> Q[PreToolUse<br/>cmk-guard-memory]
    Q -->|危险命令指向 context/| R[阻断]
    Q -->|安全命令| S[放行]

关键路径说明：

• 会话开始注入：cmk install 把 cmk-inject-context 写入第一个工具调用前的 PreToolUse 钩子；快照以权威指令开头（"当注入的记忆与你假设冲突时，注入的记忆胜出"），确保 Claude 优先使用记忆而非从代码重新推导 资料来源：packages/cli/README.md:21-23。
• 自动抽取：每个助手回合结束后，Stop 钩子会派生一个 claude --print 子代理读取本轮内容并将持久事实写入记忆；项目级事实落为带 Why/How 的富结构文件，轻量信号保持 MEMORY.md 条目风格 资料来源：packages/cli/README.md:23-26。
• 三层作用域提升：跨项目的偏好（"always use uv, never pip"）在抽取的同一回合即被提升到用户层 ~/.claude-memory-kit/，因此新项目冷启动即可继承用户风格 资料来源：README.md:27-33。
• 记忆护栏：cmk-guard-memory 是 PreToolUse 钩子，扫描 rm、Remove-Item、del、git clean、git reset --hard、find … -delete、truncate、>-截断等危险命令是否瞄准记忆路径；命中则在执行前阻断，且采用 fail-open 设计（钩子本身崩溃不会卡死会话），故意偏宽松以优先防数据丢失 资料来源：README.md:174-180。

四、压缩流水线与已知回归点

压缩按 session → daily → weekly 的三级 Haiku 蒸馏递进，可由 cmk register-crons 注册到 cron / launchd / Task Scheduler；不部署调度器时，会话开始处的 cmk-compress-lazy 会自愈 资料来源：packages/cli/README.md:55-57、README.md:41-45。

需要特别关注的回归点：v0.3.5 修复了后台压缩在 Claude 响应慢时的假性失败。生命周期压缩任务（每日蒸馏、每周策展、会话起始的兜底滚动）不应复用会话内 50 秒的紧凑预算，否则慢速 claude --print 窗口会超时导致 recent.md 与归档不能及时刷新；用户应区分"会话内压缩"与"无时间限制的后台压缩"两类预算，避免在自定义调度脚本里错配 资料来源：community context — v0.3.5 fixed in CHANGELOG。

五、安全、便携性与发布契约

• 网络边界：除 Haiku 压缩 / auto-extract（已文档化）外，无静默网络调用；记忆为本地 Markdown，跟随你的 git push 决定是否外发 资料来源：README.md:5-7。
• 便携性：项目记忆随仓库克隆；个人偏好用 cmk persona export / import 跨机携带，或 cmk lessons promote 把单条事实钉到跨项目层 资料来源：packages/cli/README.md:27-30。
• 供应链：每次发布附带 npm provenance attestation；可执行 npm view @lh8ppl/claude-memory-kit dist.attestations 校验 资料来源：README.md:166-168。
• 健康检查：cmk doctor 跑 HC-1..HC-9 九项检查，其中 HC-9 标记项目脚手架落后于已安装 cmk 版本（在该项目内重新运行 cmk install 即可） 资料来源：README.md:108-110。

See Also

• CLI 命令完整参考：docs/CLI.md
• MCP 服务器接口：docs/MCP.md
• 健康检查细节：HEALTH-CHECKS.md
• 关键 ADR：docs/adr/0014-unify-cli-mcp-shared-core.md、docs/adr/0015-semantic-backend-sqlite-vec-plus-local-onnx-embedder.md、docs/adr/0006-lifecycle-hooks-architecture.md、docs/adr/0009-provenance-frontmatter-per-observation.md

运维、健康检查、压缩与常见故障模式

claude-memory-kit 将记忆以纯 Markdown 形式落地到每个项目内。长期运行的可靠性依赖三块运维支柱：定期压缩以限制记忆体积、cmk doctor 健康检查以发现漂移、以及针对已知故障的可重复修复路径。本页汇总这三类操作及其处理流程。

运维入口与生命周期命令

cmk install 是项目的"完整入口"：脚手架 context/、注入 5 个 PATH 解析的跨 OS 生命周期钩子、注册 MCP 服务器并允许列表 mcp__cmk__* 工具；同时写入 .gitattributes 把已提交记忆锁定为 LF，避免 Windows 克隆破坏换行 资料来源：README.md:1-100。若选择 Kiro，cmk install --ide kiro 会同时配置 IDE 与 kiro-cli 表面（MCP + steering + AGENTS.md + skills + hooks） 资料来源：README.md:80-180。

升级时，无论 npm 还是插件路径，都要执行"更新机器 + 重新盖章每个项目"两步：插件侧 /plugin update claude-memory-kit 仅刷新全局钩子/技能，并不更新项目脚手架，因此每个项目仍需重跑 bootstrap（npm 路径对应 cmk install） 资料来源：plugin/README.md:1-60。最常用的运维命令如下（完整列表见 docs/CLI.md） 资料来源：docs/CLI.md:1-40：

• cmk doctor —— 跑 HC-1..HC-9 健康检查，附 PASS/FAIL/SKIP 与修复指令；
• cmk repair --hooks / --locks / --index / --all —— 幂等自修复；
• cmk roll --scope now/today/recent —— 手动触发压缩流水线；
• cmk register-crons [--dry-run] [--unregister] —— 注册每日/每周 cron/launchd/Task Scheduler 任务 资料来源：packages/cli/README.md:1-80。

健康检查：`cmk doctor`

cmk doctor 跑 9 项检查（HC-1..HC-9），每项返回状态与对应修复命令。其中 HC-9 专门标记"项目脚手架落后于已安装 cmk 版本"的情况，建议在该项目目录内重跑 cmk install 资料来源：README.md:300-400。若环境无法运行调度器，压缩会以"读时懒触发"回退，记忆仍受界；cron 只是让压缩从被动变主动 资料来源：README.md:400-500。各检查的判定与修复路径见 HEALTH-CHECKS.md。

cmk repair 的子命令按区域幂等修复：

• --hooks 重新安装 5 个生命周期钩子；
• --locks 清理锁文件；
• --index 重建搜索索引；
• --all 一次性执行以上全部 资料来源：packages/cli/README.md:80-160。

压缩流水线

记忆的有界性由三级 Haiku 压缩保障：会话级（关闭时把缓冲写入 recent.md 与归档）、每日蒸馏、每周策展。所有压缩任务的入口均在 package.json 的 bin 字段中暴露为独立可执行文件 资料来源：packages/cli/package.json:5-25：

cmk-daily-distill   cmk-weekly-curate   cmk-compress-lazy
cmk-compress-session   cmk-inject-context   cmk-guard-memory

即使未注册 cron，会话缓冲压缩也会在会话开始时自愈（cmk-compress-lazy），记忆体积始终受控。cmk register-crons 将每日/每周任务注入系统调度器 资料来源：packages/cli/README.md:160-240。

flowchart LR
    A[每轮会话 Stop 钩子] --> B[cmk-capture-turn]
    B --> C{会话关闭?}
    C -- 是 --> D[cmk-compress-session]
    C -- 否 --> E[下次会话启动]
    E -->|PreToolUse 懒触发| F[cmk-compress-lazy]
    F --> G[每日 cmk-daily-distill]
    G --> H[每周 cmk-weekly-curate]

v0.3.5 修复：后台压缩不再因 Claude 慢响应而失败

此前，无时限的生命周期压缩任务（每日蒸馏、每周策展、会话开始时的追平压缩）复用了会话内压缩器的 50 秒预算，并以过快的间隔重试。claude --print 一旦变慢就触发超时，导致 recent.md 与归档无法及时刷新 资料来源：CHANGELOG.md:1-20。v0.3.5 起，无时限任务不再受 50 s 预算约束，并采用更保守的重试策略，使压缩流水线在 Claude 响应慢时仍能可靠完成。

常见故障模式与处理

• recent.md 长时间未更新 —— 后台压缩曾受 50 s 预算限制。修复：升级到 v0.3.5+，重跑 cmk install。
• 健康检查全 FAIL —— .claude/settings.json 钩子漂移。修复：cmk repair --hooks。
• cmk search 返回空 —— 索引未重建或语义后端未启用。修复：cmk repair --index，或重跑 cmk install --with-semantic。
• 项目落后于已安装版本 —— HC-9 触发。修复：在该项目目录运行 cmk install。
• 删除命令误伤 context/ —— cmk-guard-memory 守护工作正常。修复：重新措辞或绕开该路径；守护是 fail-open 的，损坏只会停止守护、不会卡死会话 资料来源：README.md:500-600。

cmk-guard-memory 是 PreToolUse 钩子，覆盖 Claude Code（Bash / PowerShell）与 Kiro（execute_bash），匹配破坏性命令（rm、Remove-Item、del、git clean、git reset --hard、find … -delete、truncate、> 截断）并阻止其作用在 context/、~/.claude-memory-kit、MEMORY.md / DECISIONS.md 等记忆路径上。规则故意放宽：误拦可改述命令恢复，误放则是该钩子要避免的数据丢失 资料来源：README.md:500-600。

See Also

• CLI 完整参考
• 健康检查详解
• MCP 服务器文档
• 安全策略与威胁建模

Pitfall Log / 踩坑日志

项目：LH8PPL/claude-memory-kit

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/LH8PPL/claude-memory-kit | host_targets=claude_code, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/LH8PPL/claude-memory-kit | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/LH8PPL/claude-memory-kit | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/LH8PPL/claude-memory-kit | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/LH8PPL/claude-memory-kit | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/LH8PPL/claude-memory-kit | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/LH8PPL/claude-memory-kit | release_recency=unknown