面向 Claude Code 的持久化工程记忆。
把决策、约束、失败记录和压缩摘要存进本地 SQLite，再在长会话、复杂重构和多轮调试中把真正相关的上下文带回来。
Star on GitHub · 快速开始 · 功能亮点 · 配置 · 工具 · 开发
CodeMemory 是一个 local-first 的 Claude Code 插件，它把单个 session 内的临时上下文转成可持久化、可检索的工程记忆。它会把对话、摘要、决策、约束、失败和修复尝试落到 SQLite 中，再把真正相关的上下文注回到用户 prompt 和高风险工具调用前。
CodeMemory 是一个刻意收窄边界的系统，不是通用 RAG。它主要针对 Claude Code 的长会话、复杂重构和多轮调试场景，让 Agent 记住之前做过什么、为什么这么做、哪里已经踩过坑。
- Claude Code 插件名：
codememory-plugin - npm 运行时包名：
codememory-for-claude
CodeMemory 主要解决三类编码场景里的持续记忆问题：
- 长 session：在上下文窗口被截断后，核心需求和约束仍然能继续被看见。
- 复杂重构：保留设计理由、被否决方案和当前实现的决策轨迹。
- 多轮调试：在再次尝试前召回之前失败过的文件、命令和修复路径。
- 本地优先：所有数据都保存在
~/.claude/codememory.db，不依赖外部服务。 - Prompt 级检索：每次用户提问都可以自动召回相关的 task、constraint、decision 和 failure。
- 失败预警：在
Edit、Write、Bash前检查这个目标之前是否失败过。 - DAG 压缩：长历史不会简单丢弃，而是压成 leaf summary 和 condensed summary。
- 结构化记忆节点：
task、constraint、decision、failure、fix_attempt、summary都有 tag、relation 和生命周期状态。 - 快速运行路径：每个 session 启一个 daemon，通过 Unix socket 提供热路径查找，并保留 CLI 冷启动兜底。
- 可调试、可追踪：hooks、tools、slash commands 都围绕同一套运行模型组织。
- Node.js 22.5 或更高版本 —— 是硬性要求而非建议。存储层使用 Node 内置的
node:sqlite，低于 22.5 该模块不存在，daemon 会直接报版本错误拒绝启动。 - Claude Code CLI
PATH中可用的jq与curl
贡献者注意： 使用
node:sqlite是刻意的选择，不得换回原生 SQLite 绑定。插件宿主以--ignore-scripts安装依赖，会静默跳过原生包的编译步骤，导致每次 daemon 启动都死在 "Could not locate the bindings file"。内置模块没有可被跳过的安装步骤。
先在任意项目中启动 Claude Code，然后执行：
/plugin marketplace add harrylettering/CodeMemory
/plugin install codememory-plugin@harrylettering-codememory-marketplace
/reload-plugins
这个仓库现在通过 .claude-plugin/marketplace.json 兼作自己的 marketplace，因此不需要额外再建一个 catalog 仓库，也能走 Claude Code 的标准 marketplace 安装流程。
由于运行时 hooks 会直接执行 dist/ 中编译后的 JavaScript，所以 marketplace 发布时必须把 dist/*.js 一起提交到 Git。
git clone https://github.com/harrylettering/CodeMemory.git
cd CodeMemory
npm install
npm run build
chmod +x hooks/scripts/*.sh
mkdir -p ~/.claude/plugins
ln -sf "$(pwd)" ~/.claude/plugins/codememory仓库中已经包含 .claude-plugin/plugin.json、.claude-plugin/marketplace.json 和 hooks/hooks.json，因此做本地开发时，直接把仓库根目录链接为插件目录即可。
重启 Claude Code。下一次 SessionStart 时，CodeMemory 会初始化数据库、启动 per-session daemon，并开始监听当前 session 的 transcript。
安装完成后，CodeMemory 大部分时候会自动运行：
SessionStart初始化数据库并启动每 session 的 daemon。- daemon tail 当前 session 的 JSONL，因此既能 ingest hook 事件，也能 ingest 模型回复。
- 每次
UserPromptSubmit都可能触发 memory-first retrieval，把相关上下文注入 prompt。 - 每次
PreToolUse都会检查当前文件、命令或 symbol 是否存在 prior failure。 - 随着历史增长，M/L-tier 消息会被异步压缩进 summary DAG，并提升为可复用的 memory node。
所有配置通过 CODEMEMORY_* 环境变量传入，在 src/db/config.ts 中解析。最常用的几条：
每个模型环境变量都独立配置；如果没有显式设置，都会默认使用 claude-haiku-4-5-20251001。
| 变量 | 默认值 | 说明 |
|---|---|---|
CODEMEMORY_ENABLED |
true |
全局总开关。 |
CODEMEMORY_DATABASE_PATH |
~/.claude/codememory.db |
SQLite 数据库路径。 |
CODEMEMORY_WORKSPACE_ROOT |
daemon 启动时的 cwd |
用于跨仓库归一化 file tag 的根路径。 |
CODEMEMORY_DEBUG_TOOLS_ENABLED |
false |
是否向模型暴露 grep/describe/expand/lifecycle 管理工具。 |
CODEMEMORY_COMPACTION_ENABLED |
true |
是否启用异步 compaction。 |
CODEMEMORY_COMPACTION_TOKEN_THRESHOLD |
30000 |
触发 compaction 的未压缩 M/L token 阈值。 |
CODEMEMORY_COMPACTION_FRESH_TAIL_COUNT |
20 |
永远不参与压缩的最近消息条数。 |
CODEMEMORY_COMPACTION_DISABLE_LLM |
false |
跳过 claude --print，改用截断 fallback。离线 / CI 必须开启。 |
CODEMEMORY_EXPANSION_MODEL |
claude-haiku-4-5-20251001 |
codememory_expand 与 codememory_expand_query 使用的模型。 |
CODEMEMORY_QUERY_PLANNER_MODEL |
claude-haiku-4-5-20251001 |
可选 query planner 使用的模型。 |
CODEMEMORY_COMPACTION_MODEL |
claude-haiku-4-5-20251001 |
compaction 使用的模型。 |
CODEMEMORY_AUTO_SUPERSEDE_MODEL |
claude-haiku-4-5-20251001 |
可选 auto-supersede judge 使用的模型。 |
CODEMEMORY_QUERY_PLANNER_ENABLED |
false |
fast-path 检索过弱时，启用可选 LLM planner。 |
CODEMEMORY_AUTO_SUPERSEDE_VIA_LLM |
false |
在单个 conversation 内自动检测隐式 decision supersede。 |
CODEMEMORY_EXPLORED_TARGET_WINDOW_MS |
1800000（30 分钟） |
同一 Read/Grep/Glob 目标在此窗口内重复探索会从 L 衰减到 N。 |
完整环境变量参考见 docs/CONFIGURATION.zh-CN.md。
| 工具 | 用途 |
|---|---|
codememory_check_prior_failures |
查询某个文件、命令或 symbol 是否失败过。 |
codememory_mark_decision |
把技术决策持久化成 decision 节点。 |
codememory_mark_requirement |
把硬约束或稳定需求持久化。 |
codememory_compact |
主动触发当前 conversation 的 compaction。 |
设置 CODEMEMORY_DEBUG_TOOLS_ENABLED=true 后会暴露：
codememory_grep、codememory_describe、codememory_expand、codememory_expand_query、codememory_memory_pending、codememory_memory_lifecycle
codememory-mark-decision、codememory-mark-task、codememory-mark-constraint、codememory-context-skill、codememory-summarization-skill
Mark 类 Skill 会通过 hooks/scripts/codememory-mark.sh 发送请求，而 daemon 仍然是 memory_nodes 的唯一写入者。
/codememory-status、/codememory-grep、/codememory-describe、/codememory-expand、/codememory-expand-query、/codememory-watch、/codememory-reimport
/codememory-reimport 从磁盘上的 transcript 重建单个会话。daemon 只做实时摄入 —— 启动时已存在的 transcript 一律视为已处理，所以重启不会重读、也就不会产生重复行。由此留下的缺口是有意的：daemon 停机期间跑过的会话，用这条命令显式补齐，而不是每次启动都去猜。它会先删除该会话已存的数据再重放，这正是"跑两次等同于跑一次"的原因。
- README.md：English README
- docs/CONFIGURATION.zh-CN.md：完整环境变量参考
| 路径 | 作用 |
|---|---|
src/ |
核心运行时：检索、压缩、store、hook runtime 和插件激活逻辑。 |
hooks/ |
Claude Code 的 hook 定义和 shell 入口脚本。 |
commands/ |
/codememory-status、/codememory-watch 等 slash command 描述。 |
skills/ |
用于标记 decision、task、constraint 的 Skills。 |
docs/ |
面向使用者的中英文配置参考。 |
test/ |
检索、生命周期、失败查找、压缩和工具的自动化测试。 |
benchmark/ |
查找路径的延迟基准测试。 |
- 如果依赖有变化，先执行
npm install。 - 执行
npm run plugin:release-check。 - 提交更新后的
dist/*.js，并和源码改动一起入库。 - 提升
.claude-plugin/plugin.json里的版本号。 - 推送到 GitHub 后，再让用户通过 marketplace 安装或升级。
npm install
npm run build
npm run build:watch
npm test
npm run test:watch
npm run benchmark
npm run benchmark:ci常用单次命令：
npx vitest run test/failure-lookup.test.ts
npx vitest run -t "stitched chain"说明：
- 构建会把
src/编译到dist/。 - Claude Code 运行时 hooks 依赖已经提交到仓库里的
dist/*.js。 - hook 脚本依赖
jq与curl。 - prompt 级检索依赖 daemon 和编译后的
dist/。 - 离线或 CI 环境建议设置
CODEMEMORY_COMPACTION_DISABLE_LLM=true。 - 如果你发布了新版本，记得同步提升
.claude-plugin/plugin.json里的version，这样已安装用户才能收到更新。
- 没有出现检索或失败预警：先执行
npm run build，然后重启 Claude Code，确保 hooks 和dist/已生效。 - daemon 没有启动：查看
~/.claude/codememory-logs/session-start.log和~/.claude/codememory-logs/daemon.log。 - 离线或 CI 场景 compaction 卡住：设置
CODEMEMORY_COMPACTION_DISABLE_LLM=true。 - 需要查看运行状态：使用
/codememory-status，并检查~/.claude/codememory.db。
MIT.