claude-memory-compiler：给 Claude Code 装上「记忆大脑」

🔍 痛点切入：AI 记性差的困扰

想象一下：你花了两小时和 Claude Code 一起调试一段复杂代码，终于搞定了上下文理解的难题。关掉对话，第二天回来问 Claude：「昨天我们怎么解决那个认证重定向问题的？」——AI 一脸茫然，它根本不记得。

这是所有 AI 编程工具的通病：每次对话都是从零开始。Karpathy 曾提出 LLM Knowledge Base 的概念来解决这个问题，而 claude-memory-compiler 则将这个思想落地为一套完整的会话记忆系统，专门服务于 Claude Code 用户。

🧠 项目起源与核心理念

本项目改编自 Karpathy 的 LLM Knowledge Base 架构，核心思想是：把 AI 的对话历史编译成可检索的个人知识库。

传统 RAG 需要向量数据库 + Embedding + 分块，但这个项目走了一条更优雅的路：Index-Guided Retrieval（索引引导检索）。不需要任何向量计算，LLM 直接读取索引文件、自己挑选相关文章、自己综合答案。

作者的核心设计哲学：

• 会话即源码：每天的对话日志就是原材料（raw data）
• 编译即生产：compile.py 脚本把原材料编译成结构化知识文章（executable knowledge）
• 记忆即上下文：SessionStart hook 在每次对话开始时注入相关知识，Claude Code「记起」之前学过的内容

🏗️ 技术架构详解

项目采用纯 Python 实现，核心依赖只有三个：claude-agent-sdk（调用 Claude API）、python-dotenv（环境变量管理）、tzdata（时区处理）。代码总行数约 8000 行，无重型依赖。

三大 Hook 的协同机制

Claude Code 支持会话生命周期钩子，本项目利用三个钩子构建了完整的记忆闭环：

1. SessionStart Hook — 注入记忆上下文 每次 Claude Code 启动时，session-start.py 读取知识库索引和最近日志，将相关内容注入为额外上下文。注入量通过 MAX_CONTEXT_CHARS（默认 8000 字符）控制，防止上下文溢出。

2. PreCompact Hook — 抢救即将消失的记忆 Claude Code 在上下文窗口满时会自动压缩（summarize + discard），这会丢失大量细节。PreCompact 在压缩发生前触发，flush.py 后台进程立即提取对话中的重要知识点，确保压缩后仍有记录。

3. SessionEnd Hook — 持久化会话 对话结束后，session-end.py 提取会话转录内容，触发 flush.py 将知识点追加到当日日志（daily/YYYY-MM-DD.md）。后台进程避免阻塞用户继续工作。

编译系统的双层架构

compile.py 是整个系统的核心编译器，负责将原始对话日志编译成结构化知识：

• 读取 daily/ 目录下所有对话日志
• 识别每个会话中的核心概念（concepts/）、概念间的关联（connections/）、问答对（qa/）
• 生成知识文章存入 knowledge/concepts/ 目录
• 更新 knowledge/index.md 索引

lint.py 充当知识库的「质量审计员」，运行 7 项检查：断链检测、孤立页面检测、陈旧文章检测、矛盾检测（LLM 驱动）、缺失反向链接检测、稀疏文章检测。

query.py 是检索入口，接收自然语言问题，通过索引引导 LLM 挑选相关文章并综合答案。

数据组织结构

ROOT/
├── daily/               # 原始对话日志（每日一个 .md 文件）
├── knowledge/
│   ├── concepts/       # 概念文章（核心知识单元）
│   ├── connections/    # 概念间关联
│   ├── qa/             # 问答对
│   ├── index.md        # 知识库索引
│   └── log.md          # 操作日志
├── hooks/              # Claude Code 钩子脚本
├── scripts/             # 核心脚本（compile/flush/query/lint）
└── reports/             # lint 检查报告

⚙️ 上手门槛与体验

安装条件：Python >= 3.12 + Claude Code CLI + Anthropic API Key

安装步骤：

1. 在 Claude Code 中运行 /md 命令打开项目目录
2. uv sync 安装依赖
3. 在 .claude/settings.json 中配置三个 Hook（作者已预设，可直接复制）
4. 设置 ANTHROPIC_API_KEY 环境变量

CLI 工具集：

• uv run python compile.py — 编译新对话日志
• uv run python compile.py --all — 强制全量重编译
• uv run python query.py "问题" — 知识库问答
• uv run python lint.py — 知识库健康检查

⚠️ 局限与挑战

1. Claude Code 强依赖：专为 Claude Code 设计，不支持 Cursor、Windsurf 等其他 AI 编程助手。

2. 无持久化 Web UI：所有交互通过命令行完成，对习惯 GUI 的用户有学习成本。

3. 记忆质量依赖 prompt：flush.py 中 LLM 判断「什么是值得记忆的」，这个判断高度依赖 prompt 质量，对 API Key 成本也有影响。

4. 索引膨胀问题：随着对话增多，knowledge/index.md 可能变得臃肿，当前版本没有自动裁剪机制。

5. 无云端同步：本地文件系统存储，换设备需要手动同步。

📈 行业意义

claude-memory-compiler 代表了一个新兴方向：AI 编程工具的个人知识管理（PKM）。随着 Claude Code、Cursor 等工具的普及，用户越来越意识到「让 AI 记住」的价值。

对比主流方案：

• 向量数据库 RAG：需要额外部署、Embedding 计算成本高
• 简单对话历史保存：文件混乱、无法结构化检索
• 本项目的 Index-Guided：零额外基础设施、LLM 原生理解索引

增长曲线值得关注：项目 2026-04-06 创建，仅两个多月积累了 1176 stars、303 forks（数据截至 2026-06-14），说明这个细分需求正在被越来越多的人认可。

🎯 总结

如果你每天重度使用 Claude Code，并且经常需要回顾之前的解决方案，claude-memory-compiler 是一套值得尝试的本地记忆系统。它精准解决「AI 记性差」这一个痛点，架构清晰、依赖极简、代码可读性强。虽然上手需要一些配置工作，但一旦跑通，那种「AI 终于认识我了」的体验是独特的。

适合人群：Claude Code 重度用户、个人开发者、知识管理爱好者。 不适合：不熟悉 CLI 的用户、主要用其他 AI 编程工具的用户。