# https://github.com/LH8PPL/claude-memory-kit 项目说明书 生成时间：2026-06-25 08:51:11 UTC ## 目录 - [Overview and Three-Tier Memory Model](#page-1) - [Installation, CLI Reference, and Agent Surfaces (Claude Code + Kiro)](#page-2) - [Architecture, Components, and Data Flow](#page-3) - [Operations, Health Checks, Compression, and Common Failure Modes](#page-4) ## Overview and Three-Tier Memory Model ### 相关页面 相关主题：[Installation, CLI Reference, and Agent Surfaces (Claude Code + Kiro)](#page-2), [Architecture, Components, and Data Flow](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md) - [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md) - [packages/cli/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json) - [plugin/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md) - [packages/canonicalize/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/canonicalize/package.json) - [package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/package.json)
# 三层记忆模型概览 ## 项目定位与设计目标 `claude-memory-kit`（命令行工具名为 `cmk`）是一个**面向项目的、存储于代码仓库内的持久化记忆系统**，专为 [Claude Code](https://docs.claude.com/en/docs/claude-code) 打造。它解决了 Claude 在每个会话结束即"遗忘"上下文的核心痛点——开发者不再需要在新会话中重复解释项目背景、技术栈偏好与历史决策。 与 Anthropic 原生的自动记忆（auto-memory）机制不同，本项目将记忆内容以**纯 Markdown 格式**提交到项目代码仓库中，随 `git clone` 自然流转到团队成员的本地环境。这种"项目内、仓库级、随代码走"的定位带来三大优势： 1. **可审计性**：记忆以人类可读的 Markdown 文件存储，而非不透明的状态数据库。 2. **可移植性**：通过 `git clone` 即获得完整项目记忆，无需额外同步机制。 3. **可治理性**：记忆的变更可与代码变更一同通过 Pull Request 审查与回滚。 ## 三层记忆范围架构 本系统的核心创新在于引入了**三层记忆范围**（Three-Tier Memory Scope）模型，每一层都有明确的归属与流转规则： ```mermaid 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` 而泄露到所有协作者。 ## 记忆捕获与召回工作流 记忆系统的完整生命周期包含**自动捕获**、**按需召回**与**压缩治理**三个阶段： ```mermaid 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 响应慢而导致压缩失败。 ## 核心能力特性 | 能力维度 | 实现机制 | 用户价值 | |---------|---------|---------| | **项目内提交** | 记忆以 Markdown 存储于 `context/`，随 `git clone` 流转 | 团队成员自动获得完整项目上下文 | | **内容寻址引用** | 基于内容哈希生成引用 ID（content-addressed citation IDs） | 记忆引用稳定可靠，不受文件重命名影响 | | **信任层次与冲突队列** | 内置 trust hierarchy + conflict queues | 处理记忆间的矛盾与时效性差异 | | **完整来源追溯** | 每个事实附带 provenance 元数据 | 可追溯决策的来源与时间 | | **MCP 服务器集成** | 注册 `mcp__cmk__*` 工具集 | Claude 可在对话中直接调用记忆读写工具 | | **记忆保护钩子** | PreToolUse 钩子拦截破坏性命令 | 防止 `rm`、`git clean` 等误删记忆文件 | ## CLI 命令速查 | 命令 | 用途 | |------|------| | `cmk install [--with-semantic] [--ide claude-code\|kiro]` | 脚手架搭建 + 钩子挂载 + MCP 服务器注册（完整入口点） | | `cmk doctor` | 运行九项健康检查（HC-1..HC-9），每项报告 PASS/FAIL/SKIP 并提供修复命令 | | `cmk search "" [--mode keyword\|semantic\|hybrid]` | 按含义搜索记忆（hybrid 为 `--with-semantic` 后的默认模式） | | `cmk remember ""` | 显式捕获一条事实到记忆系统 | | `cmk persona export` / `cmk persona import` | 跨机器同步用户画像 | | `cmk register-crons` | 注册每日/每周压缩定时任务（可选，未配置时降级为惰性压缩） | | `cmk get ` / `cmk timeline ` | 读取记忆索引或时间线 | | `cmk cite ` | 生成规范化引用链接 | | `cmk forget ` | 软删除一条事实（支持预览后确认删除） | | `cmk uninstall` | 卸载智能体托管的接线（保守操作，绝不删除 `context/`） | ## 安全与隐私设计 系统在设计时充分考虑了**隐私保护**与**操作安全**： - **密钥屏蔽**：所有写入操作在提交前自动扫描并屏蔽敏感信息（API 密钥、Token）。 - **路径抽象**：机器特定路径被抽象为 `~`，避免泄露本地目录结构。 - **破坏性命令拦截**：`cmk install` 时挂载的 PreToolUse 钩子会**阻断**针对记忆路径的破坏性命令（如 `rm`、`git clean`、`git reset --hard`），在 Claude Code 与 Kiro 两个智能体上均生效。 - **保守卸载**：`cmk uninstall` 永远不删除 `context/` 目录，确保项目记忆不会因卸载而丢失。 ## 参见 - [Claude Code 官方文档](https://docs.claude.com/en/docs/claude-code) — 了解宿主智能体能力 - [MCP 协议规范](https://modelcontextprotocol.io) — 记忆工具的通信协议 - [LongMemEval 基准测试](https://github.com/xiaowu0162/LongMemEval) — 召回质量的评估方法论 --- ## Installation, CLI Reference, and Agent Surfaces (Claude Code + Kiro) ### 相关页面 相关主题：[Overview and Three-Tier Memory Model](#page-1), [Architecture, Components, and Data Flow](#page-3), [Operations, Health Checks, Compression, and Common Failure Modes](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md) - [packages/cli/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json) - [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md) - [packages/canonicalize/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/canonicalize/package.json) - [plugin/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md) - [python/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/python/README.md) - [package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/package.json)
# 安装、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（推荐） ```bash 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 插件 ```text /plugin marketplace add /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 个二进制入口，覆盖安装、压缩、捕获、观察、注入与防护。下表汇总核心命令： | 命令 | 用途 | | --- | --- | | `cmk install [--with-semantic] [--ide claude-code\|kiro]` | 完整脚手架 + 钩子 + MCP 注册；`--ide kiro` 切换至 Kiro 适配 | | `cmk uninstall [--ide ...]` | 移除某个 Agent 的托管布线（保守——不删 `context/`） | | `cmk doctor` | 运行 HC-1..HC-9 健康检查 | | `cmk repair --hooks\|--locks\|--index\|--all` | 幂等自修复 | | `cmk search "" [--mode keyword\|semantic\|hybrid] [--scope facts\|transcripts\|decisions]` | 语义/关键词检索；`--scope decisions` 查询决策日志 | | `cmk get ` / `cmk timeline ` / `cmk cite ` / `cmk recent-activity` | 读回索引——事实正文、时序、引用链接、近期变更 | | `cmk roll --scope now\|today\|recent` | 手动触发压缩流水线 | | `cmk register-crons [--dry-run] [--unregister]` | 注册每日/每周压缩任务（cron / launchd / Task Scheduler） | | `cmk forget ` | 墓碑化事实——立即从 `cmk search` 消失，无需手动重建索引 | | `cmk persona export\|import` / `cmk lessons promote` | 跨机迁移人格或提升事实为跨项目可见 | 资料来源：[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 接入 ```bash 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]() ### 接入面架构 ```mermaid graph TB subgraph 用户层 U[开发者终端] CC[Claude Code 会话] K[Kiro IDE / kiro-cli] end subgraph 接入层 CLI[cmk CLI
11 个二进制] MCP[MCP Server
mcp__cmk__*] PLG[Claude Code 插件] KIRO[Kiro 适配器
--ide kiro] end subgraph 核心层 CTX[context/
项目级记忆] PERSONA[~/.claude-memory-kit/
用户级人格] CANON[cmk-canonicalize
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]() ## 配置与排错 记忆分层结构： | 层级 | 路径 | 作用域 | | --- | --- | --- | | **Project** | `context/`（随仓库） | 项目内全部协作者 | | **User** | `~/.claude-memory-kit/`（本机） | 跨项目、个人偏好 | 项目记忆随 `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](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md) - [Kiro integration guide](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)（见 README.md "Working with Kiro" 章节） - [MCP server reference](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/MCP.md) - [CLI full reference](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/CLI.md) - [Semantic backend ADR-0015](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/adr/0015-semantic-backend-sqlite-vec-plus-local-onnx-embedder.md) --- ## Architecture, Components, and Data Flow ### 相关页面 相关主题：[Overview and Three-Tier Memory Model](#page-1), [Installation, CLI Reference, and Agent Surfaces (Claude Code + Kiro)](#page-2), [Operations, Health Checks, Compression, and Common Failure Modes](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md) - [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md) - [packages/cli/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json) - [packages/canonicalize/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/canonicalize/package.json) - [package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/package.json) - [plugin/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md)
# Architecture, Components, and Data Flow ## 一、设计目标与系统总览 claude-memory-kit 是一个**面向 Claude Code 的、按项目划分的、提交到仓库内的纯 Markdown 记忆系统**。其核心目标是解决 Claude 会话结束即遗忘上下文的问题：每次新会话不再需要重复解释项目背景、技术栈与个人偏好 资料来源：[README.md:23-25]()。 整个系统按 **monorepo** 组织，工作区位于 `packages/*` 资料来源：[package.json:7-9]()，目前公开的核心包有两个： | 包名 | 角色 | 关键依赖 | | --- | --- | --- | | `@lh8ppl/claude-memory-kit`（`packages/cli`） | CLI 入口 + 生命周期钩子 + MCP 服务器 | `better-sqlite3`、`sqlite-vec`、`@modelcontextprotocol/sdk`、`commander`、`chokidar`、`js-yaml`、`zod` | | `@lh8ppl/cmk-canonicalize`（`packages/canonicalize`） | 确定性文本规范化 + 内容寻址 ID 生成，Node 与 Python 实现字节级一致 | 纯 ESM，无运行时依赖 | 资料来源：[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]()： ```text 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]()。 ## 三、数据流与会话生命周期 下图展示了从会话开始到压缩回收的端到端数据流。 ```mermaid flowchart LR A[会话开始] --> B[PreToolUse
cmk-inject-context] B --> C[注入冻结快照
SOUL/USER/MEMORY/INDEX + 今日日志] C --> D[用户回合] D --> E[UserPromptSubmit
cmk-capture-prompt] E --> F[助手回合] F --> G[Stop / SessionEnd
cmk-capture-turn + auto-extract] G --> H[(claude --print 子代理
提取持久事实)] H --> I[写入 context/ 事实文件
三层作用域之一] I --> J{压缩触发} J -- 定时 --> K[cmk-daily-distill
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
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` --- ## Operations, Health Checks, Compression, and Common Failure Modes ### 相关页面 相关主题：[Installation, CLI Reference, and Agent Surfaces (Claude Code + Kiro)](#page-2), [Architecture, Components, and Data Flow](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md) - [packages/cli/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md) - [packages/cli/package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json) - [package.json](https://github.com/LH8PPL/claude-memory-kit/blob/main/package.json) - [plugin/README.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md) - [HEALTH-CHECKS.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/HEALTH-CHECKS.md) - [docs/CLI.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/CLI.md) - [CHANGELOG.md](https://github.com/LH8PPL/claude-memory-kit/blob/main/CHANGELOG.md)
# 运维、健康检查、压缩与常见故障模式 claude-memory-kit 将记忆以纯 Markdown 形式落地到每个项目内。长期运行的可靠性依赖三块运维支柱：定期压缩以限制记忆体积、`cmk doctor` 健康检查以发现漂移、以及针对已知故障的可重复修复路径。本页汇总这三类操作及其处理流程。 ## 运维入口与生命周期命令 `cmk install` 是项目的"完整入口"：脚手架 `context/`、注入 5 个 PATH 解析的跨 OS 生命周期钩子、注册 MCP 服务器并允许列表 `mcp__cmk__*` 工具；同时写入 `.gitattributes` 把已提交记忆锁定为 LF，避免 Windows 克隆破坏换行 资料来源：[README.md:1-100](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)。若选择 Kiro，`cmk install --ide kiro` 会同时配置 IDE 与 `kiro-cli` 表面（MCP + steering + AGENTS.md + skills + hooks） 资料来源：[README.md:80-180](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)。 升级时，无论 npm 还是插件路径，都要执行"更新机器 + 重新盖章每个项目"两步：插件侧 `/plugin update claude-memory-kit` 仅刷新全局钩子/技能，并不更新项目脚手架，因此每个项目仍需重跑 `bootstrap`（npm 路径对应 `cmk install`） 资料来源：[plugin/README.md:1-60](https://github.com/LH8PPL/claude-memory-kit/blob/main/plugin/README.md)。最常用的运维命令如下（完整列表见 `docs/CLI.md`） 资料来源：[docs/CLI.md:1-40](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/CLI.md)： - `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](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md)。 ## 健康检查：`cmk doctor` `cmk doctor` 跑 9 项检查（HC-1..HC-9），每项返回状态与对应修复命令。其中 HC-9 专门标记"项目脚手架落后于已安装 `cmk` 版本"的情况，建议在该项目目录内重跑 `cmk install` 资料来源：[README.md:300-400](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)。若环境无法运行调度器，压缩会以"读时懒触发"回退，记忆仍受界；cron 只是让压缩从被动变主动 资料来源：[README.md:400-500](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)。各检查的判定与修复路径见 [`HEALTH-CHECKS.md`](https://github.com/LH8PPL/claude-memory-kit/blob/main/HEALTH-CHECKS.md)。 `cmk repair` 的子命令按区域幂等修复： - `--hooks` 重新安装 5 个生命周期钩子； - `--locks` 清理锁文件； - `--index` 重建搜索索引； - `--all` 一次性执行以上全部 资料来源：[packages/cli/README.md:80-160](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md)。 ## 压缩流水线 记忆的有界性由三级 Haiku 压缩保障：会话级（关闭时把缓冲写入 `recent.md` 与归档）、每日蒸馏、每周策展。所有压缩任务的入口均在 `package.json` 的 `bin` 字段中暴露为独立可执行文件 资料来源：[packages/cli/package.json:5-25](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/package.json)： ```text 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/packages/cli/README.md)。 ```mermaid 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](https://github.com/LH8PPL/claude-memory-kit/blob/main/CHANGELOG.md)。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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)。 `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](https://github.com/LH8PPL/claude-memory-kit/blob/main/README.md)。 ## See Also - [CLI 完整参考](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/CLI.md) - [健康检查详解](https://github.com/LH8PPL/claude-memory-kit/blob/main/HEALTH-CHECKS.md) - [MCP 服务器文档](https://github.com/LH8PPL/claude-memory-kit/blob/main/docs/MCP.md) - [安全策略与威胁建模](https://github.com/LH8PPL/claude-memory-kit/blob/main/SECURITY.md) --- --- ## Doramagic 踩坑日志 项目：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