Claude Code Memory Skill一个轻量级本地 Markdown 记忆库实践副标题用 Markdown、JSON 索引与 Hook为 Claude Code 构建一个可读、可维护、可复用的本地项目记忆层。项目地址https://github.com/Junhaozhang-127/ClaudeCodeMemorySkill摘要在使用 Claude Code 进行长期项目开发时我逐渐发现一个非常现实的问题AI 的代码生成能力越来越强但跨会话上下文连续性仍然是一个明显短板。一个稍微复杂一点的项目往往不会在一次会话中完成。它可能会经历需求分析、功能开发、Bug 修复、测试核验、文档整理、版本发布等多个阶段。每次开启新会话时我们都需要重新告诉 AI当前项目做到哪一步了、之前为什么这样设计、哪些问题已经修复、哪些功能还没有完成、哪些技术决策不能随意改动。为了解决这个问题我尝试构建了一个轻量级的本地记忆系统Claude Code Memory Skill。它通过Markdown 记忆文件 JSON 索引 Hook 自动触发 CLI 工具链把 Claude Code 会话中的摘要、关键词、关键决策、待办事项和必要的原始摘录沉淀下来并在后续会话中检索相关历史上下文从而让 Claude Code 更适合参与长期工程项目。目录一、为什么需要 Claude Code 本地记忆二、项目定位与设计目标三、整体架构设计四、记忆文件结构设计五、JSON 索引与 Workspace 隔离六、检索机制与上下文注入七、Hook 自动化接入八、CLI 工具链与实例命令九、核心代码示例如何实现一个最小记忆库十、工程化能力从脚本到工具十一、版本演进路线十二、一次典型使用流程十三、项目价值总结十四、结语一、为什么需要 Claude Code 本地记忆1.1 长期项目中的上下文断裂问题在真实开发过程中Claude Code 经常被用于处理以下任务阅读项目源码理解目录结构和模块职责生成开发方案拆分功能阶段修改 Bug并解释问题原因编写测试脚本和核验提示词总结阶段报告和开发进度生成发布工具、安装脚本和版本说明检查 README、CHANGELOG、plugin manifest 等项目文件。这些任务通常不是孤立的而是相互关联的。例如前一次会话中确定了某个模块的设计方案下一次会话继续开发时就不能随意推翻前一次测试报告中发现了某个边界问题下一阶段开发时也应该继续关注前一次发布核验中标记为“暂不实现”的功能在后续文档里也不应该被误写成“已完成”。但是Claude Code 的每次会话天然是相对独立的。新会话并不会自动知道历史会话中的全部背景。这就导致长期项目中经常出现几个问题问题典型表现影响重复解释项目背景每次都要重新说明项目目标、目录结构和阶段进度降低沟通效率历史决策难以找回忘记之前为什么采用某种设计容易出现方案反复待办事项散落在对话中TODO 混在大量聊天内容里后续推进容易遗漏Bug 修复原因丢失只记得“改过”忘记“为什么改”后续维护成本增加多阶段开发缺少连续性每个阶段像重新开始项目节奏被打断图1 多会话上下文断裂问题1.2 本地记忆库想解决什么我希望 Claude Code Memory Skill 能做到几件事会话结束后自动保存记忆将本次会话中的重要内容整理成结构化 Markdown 文件。新会话开始前自动检索上下文根据用户当前输入查找与当前任务相关的历史记忆。按项目隔离记忆内容不同 workspace 的记忆应该分开管理避免多个项目相互干扰。记忆文件人类可读不依赖复杂数据库直接用 Markdown 保存方便人工查看、修改、删除和归档。提供基础维护工具支持安装、卸载、升级、健康检查、统计和验收测试。最终目标可以概括为一句话为 Claude Code 提供一个轻量级、本地化、结构化的项目记忆层让 AI 更适合参与长期工程项目。二、项目定位与设计目标Claude Code Memory Skill 是一个面向 Claude Code 的本地会话记忆工具。它主要解决的是如何将 Claude Code 开发过程中的重要上下文沉淀下来并在后续会话中重新利用。项目的核心设计可以概括为Markdown 记忆文件 JSON 索引 Hook 自动触发 CLI 工具链它并没有一开始就引入数据库、向量数据库或复杂的外部服务而是优先采用低依赖、可读、易迁移的方案。2.1 适用场景这个工具比较适合以下场景场景为什么适合个人长期开发项目可以保存阶段计划、Bug 修复原因和版本决策科研/竞赛项目可以沉淀实验设计、调参记录、核验结论AI 辅助代码重构可以记录重构边界、风险点和已验证内容多轮文档生成可以记住文档风格、结构要求和历史修改意见开源项目维护可以保存 release checklist、issue 处理记录和版本说明2.2 不适合什么这个项目并不试图解决所有知识库问题。它不适合超大规模企业级知识管理强权限控制、多用户协同的文档系统需要复杂数据库事务的业务系统需要高精度语义召回的专业 RAG 平台。它更像是一个个人开发者和小型项目团队可快速落地的本地上下文记忆层。三、整体架构设计3.1 架构概览Claude Code Memory Skill 的整体流程可以概括为Claude Code 会话 ↓ Stop Hook ↓ 会话摘要生成 ↓ Markdown 记忆文件 ↓ index.json 索引 ↓ PrePrompt Hook ↓ 检索相关记忆 ↓ 注入新会话上下文图2 Claude Code Memory Skill 整体架构3.2 核心模块项目可以拆分为四个主要模块模块作用关键产物Hook 层在 Claude Code 会话前后自动触发保存和检索Stop Hook、PrePrompt Hook记忆生成层将会话整理为摘要、关键词、关键决策、待办事项Markdown 记忆文件存储层使用 Markdown 文件和 JSON 索引保存记忆topics/*.md、index.json检索层根据当前输入检索相关历史上下文相关记忆片段、score_breakdown3.3 为什么选择轻量化设计很多记忆系统会直接引入数据库、向量库或在线 embedding 服务。但这个项目最初的目标不是构建一个大型知识库而是解决 Claude Code 使用过程中的实际连续性问题。因此我更倾向于先做一个轻量、透明、容易维护的版本。这种设计有几个好处Markdown 文件可以直接阅读JSON 索引便于调试不依赖外部数据库方便纳入 Git 管理出问题时容易定位适合个人项目和小型团队使用。对于一个 Claude Code 本地记忆工具来说“简单可控”比“复杂强大”更重要。四、记忆文件结构设计4.1 目录结构项目的本地记忆目录大致如下memory/ ├── index.json └── topics/ ├── phase1_local_memory.md ├── phase2_retrieval.md ├── phase3_hooks.md └── release_v0.5.0.md其中topics/用于保存不同主题的 Markdown 记忆文件index.json用于保存索引信息便于快速检索每个 Markdown 文件对应一次或一组相关会话记忆。图3 记忆文件结构示意4.2 Markdown 记忆内容一个典型的记忆文件可以包含以下内容# Topic: Phase 5 发布工具开发 ## Summary 本次会话围绕 Claude Code Memory Skill 第五阶段发布工具展开 重点完成安装、卸载、升级、健康检查和验收测试工具。 ## Keywords Claude Code, Memory Skill, Release, Health Check, Acceptance Test ## Key Decisions - v0.5.0 阶段重点聚焦发布工具链。 - plugin.json 暂时保持 manifest-template 标记。 - 向量检索暂不作为正式功能宣传。 ## TODO - 补充 release checklist。 - 完善 README 中的安装说明。 - 后续验证 Windows PowerShell Hook。 ## Raw Excerpts 保留本次会话中的关键原始片段便于后续追溯。这种结构不是简单地保存完整聊天记录而是把会话压缩成更有价值的信息块。4.3 结构化 Markdown 的优势优势说明人类可读不需要特殊工具就能直接查看AI 友好摘要、决策、待办等字段便于 AI 理解易维护可以手动修改、删除、合并记忆易迁移文件可以直接复制到其他环境易版本管理可以使用 Git 跟踪变化低依赖不需要数据库或外部服务对于个人开发者而言这种方式非常实用。记忆不是黑箱而是可以被检查、编辑和维护的普通文本文件。五、JSON 索引与 Workspace 隔离5.1 index.json 的作用如果只有 Markdown 文件检索时就需要扫描全部内容。随着记忆文件增加这种方式效率会下降。因此项目使用index.json维护基础索引信息例如{items:[{topic:Phase 5 发布工具开发,keywords:[Claude Code,Memory Skill,Release,Health Check],summary:本次会话围绕第五阶段发布工具展开。,path:topics/release_v0.5.0.md,workspace:ClaudeMeory,created_at:2026-06-03T21:30:0008:00,updated_at:2026-06-03T22:10:0008:00}]}索引文件的作用包括快速定位相关记忆保存主题和关键词支持 workspace 隔离避免每次检索都全文扫描为后续混合检索和语义检索留出扩展空间。5.2 Workspace 隔离Claude Code 经常会被用于多个项目。如果所有记忆都混在一起检索时很容易出现无关上下文。因此项目支持 workspace 隔离。例如python scripts/workspace_manager.py init--workspacemy-project保存记忆时也可以指定 workspacepython scripts/summarize_session.py--workspacemy-project--topicPhase 5 发布工具--text本次会话完成安装、卸载、升级、健康检查和验收测试工具。这样不同项目的历史上下文可以独立保存和检索。六、检索机制与上下文注入6.1 从用户输入到相关记忆当用户在新会话中输入一个问题时系统需要判断哪些历史记忆和当前问题最相关基本流程如下用户输入 ↓ 关键词提取 ↓ 多字段匹配 ↓ 加权评分 ↓ score_breakdown 输出 ↓ 返回相关记忆图4 检索评分流程图6.2 多字段加权检索项目不是只在全文中搜索关键词而是会综合多个字段进行评分。字段作用topic判断主题是否匹配keywords判断核心概念是否匹配summary判断整体语义是否接近decisions找回关键技术决策todos找回后续任务raw excerpts在必要时提供原始依据当某条记忆被命中时可以通过score_breakdown查看它为什么被选中{topic_score:0.35,keyword_score:0.30,summary_score:0.20,decision_score:0.10,todo_score:0.05,total_score:1.00}对于调试记忆系统来说可解释性非常重要。否则当系统返回一条不相关记忆时很难判断是关键词问题、摘要问题还是评分权重问题。6.3 注入上下文时的内容优先级为了避免把过多历史内容直接塞进上下文可以设置一个简单的注入优先级Summary ↓ Key Decisions ↓ TODO ↓ Raw Excerpts也就是说默认优先注入摘要、关键决策和待办只有在需要追溯细节时才补充原始摘录。七、Hook 自动化接入7.1 Stop Hook会话结束后保存记忆Claude Code Memory Skill 的一个关键设计是通过 Hook 自动保存记忆。当一次 Claude Code 会话结束时可以通过Stop Hook触发记忆保存流程Claude Code 会话结束 ↓ Stop Hook 触发 ↓ 提取会话内容 ↓ 生成摘要、关键词、决策、待办 ↓ 写入 Markdown ↓ 更新 index.json7.2 PrePrompt Hook用户输入前检索记忆另一个关键 Hook 是PrePrompt Hook。它的作用是在用户输入正式发送给 Claude Code 之前根据当前输入检索相关历史记忆然后把这些记忆作为上下文注入。用户输入问题 ↓ PrePrompt Hook 触发 ↓ 检索 index.json 和 Markdown 记忆 ↓ 返回相关上下文 ↓ 辅助 Claude Code 理解当前任务7.3 Hook 配置示例下面是一个简化版 Hook 配置思路仅用于说明工作方式{hooks:{Stop:[{command:python scripts/summarize_session.py --workspace my-project}],PrePrompt:[{command:python scripts/retrieve_memory.py --workspace my-project --query $USER_PROMPT}]}}在实际项目中还需要结合 Claude Code 的真实 Hook 配置规范、脚本路径和系统环境进行调整。八、CLI 工具链与实例命令8.1 为什么需要 CLIHook 自动化适合日常使用但开发和维护过程中仍然需要命令行工具。例如手动保存一次记忆检索某个主题初始化 workspace检查记忆库状态统计记忆文件发布前执行验收测试。8.2 常见命令示例初始化 workspacepython scripts/workspace_manager.py init--workspacemy-project保存一次会话记忆python scripts/summarize_session.py--workspacemy-project--topicPhase 5 发布工具--text本次会话完成安装、卸载、升级、健康检查和验收测试工具。检索相关记忆python scripts/retrieve_memory.py--workspacemy-project--query第五阶段发布工具完成情况查看记忆统计python scripts/memory_stats.py--workspacemy-project执行健康检查python scripts/health_check.py执行验收测试python scripts/run_acceptance.py--quick8.3 一次完整操作示例# 1. 初始化项目记忆空间python scripts/workspace_manager.py init--workspaceclaude-memory-skill# 2. 保存一条阶段记忆python scripts/summarize_session.py--workspaceclaude-memory-skill--topicv0.5.0 发布工具链--text完成 install.py、uninstall.py、upgrade.py、health_check.py、memory_stats.py、release_prepare.py 和 run_acceptance.py。# 3. 检索与发布工具相关的历史记忆python scripts/retrieve_memory.py--workspaceclaude-memory-skill--query发布工具链还有哪些待办九、核心代码示例如何实现一个最小记忆库为了更直观地理解这个项目下面给出一个简化版 Python 示例。它并不是完整项目源码而是用于说明“保存 Markdown 记忆 更新 JSON 索引 简单检索”的核心思路。9.1 保存一条 Markdown 记忆frompathlibimportPathfromdatetimeimportdatetimeimportjsonimportre MEMORY_DIRPath(memory)TOPICS_DIRMEMORY_DIR/topicsINDEX_FILEMEMORY_DIR/index.jsondefslugify(text:str)-str:将主题转换为安全文件名。textre.sub(r[^\w\u4e00-\u9fff-],_,text.strip())returntext[:80].strip(_)oruntitleddefload_index()-dict:ifINDEX_FILE.exists():returnjson.loads(INDEX_FILE.read_text(encodingutf-8))return{items:[]}defsave_index(index:dict)-None:MEMORY_DIR.mkdir(parentsTrue,exist_okTrue)INDEX_FILE.write_text(json.dumps(index,ensure_asciiFalse,indent2),encodingutf-8)defsave_memory(topic:str,summary:str,keywords:list[str],decisions:list[str],todos:list[str],)-Path:MEMORY_DIR.mkdir(parentsTrue,exist_okTrue)TOPICS_DIR.mkdir(parentsTrue,exist_okTrue)filenamef{slugify(topic)}.mdpathTOPICS_DIR/filename md[f# Topic:{topic},,## Summary,summary,,## Keywords,, .join(keywords),,## Key Decisions,*[f-{item}foritemindecisions],,## TODO,*[f-{item}foritemintodos],]path.write_text(\n.join(md),encodingutf-8)indexload_index()index[items].append({topic:topic,keywords:keywords,summary:summary,path:str(path.relative_to(MEMORY_DIR)),created_at:datetime.now().isoformat(timespecseconds)})save_index(index)returnpath调用示例save_memory(topicv0.5.0 发布工具链,summary本次完成 Claude Code Memory Skill v0.5.0 发布工具链。,keywords[Claude Code,Memory Skill,Release,Health Check],decisions[v0.5.0 阶段聚焦发布工具链。,plugin.json 保持 manifest-template 标记。],todos[补充 RELEASE_CHECKLIST.md。,验证 Windows PowerShell Hook。])9.2 简单关键词检索defretrieve_memory(query:str,top_k:int3)-list[dict]:indexload_index()query_tokensset(query.lower().split())scored[]foriteminindex.get(items,[]):topicitem.get(topic,).lower()summaryitem.get(summary,).lower()keywords[k.lower()forkinitem.get(keywords,[])]topic_scoresum(1fortokeninquery_tokensiftokenintopic)*0.4summary_scoresum(1fortokeninquery_tokensiftokeninsummary)*0.3keyword_scoresum(1fortokeninquery_tokensforkwinkeywordsiftokeninkw)*0.3total_scoretopic_scoresummary_scorekeyword_scoreiftotal_score0:scored.append({**item,score_breakdown:{topic_score:round(topic_score,3),summary_score:round(summary_score,3),keyword_score:round(keyword_score,3),total_score:round(total_score,3)}})returnsorted(scored,keylambdax:x[score_breakdown][total_score],reverseTrue)[:top_k]调用示例resultsretrieve_memory(v0.5.0 发布 工具 健康检查)foriteminresults:print(item[topic])print(item[score_breakdown])这个简化示例体现了项目最核心的思想先把会话转成结构化记忆再通过索引进行可解释检索。十、工程化能力从脚本到工具10.1 v0.5.0 的发布工具链为了让这个工具真正能被使用而不只是停留在脚本原型v0.5.0 中补充了完整的发布和维护工具链。工具作用install.py安装项目并初始化环境uninstall.py卸载项目相关配置upgrade.py执行版本升级health_check.py检查环境、目录、配置和脚本状态memory_stats.py统计记忆数量、主题和索引信息release_prepare.py执行发布前检查和清理run_acceptance.py执行验收测试10.2 测试与验收一个记忆工具如果没有测试很容易在后续迭代中破坏已有功能。因此项目中加入了单元测试和验收测试用于检查Markdown 记忆是否能正确生成index.json 是否能正确更新检索功能是否正常workspace 隔离是否有效Hook 脚本是否可运行JSON 文件是否可解析发布工具是否可执行。对于一个 Claude Code 辅助开发工具来说测试不仅是质量保障也是一种自我验证工具本身也应该符合工程化规范。十一、版本演进路线项目可以按阶段理解为五个部分。阶段主要内容Phase 1本地 Markdown 记忆库、索引、核心接口Phase 2摘要生成、关键决策/待办抽取、中文关键词增强、多字段检索Phase 3Hook、Slash Command、Plugin Manifest、一键安装Phase 4Workspace 隔离、混合检索、记忆维护、安全增强Phase 5版本化、安装/卸载/升级、健康检查、验收测试、发布工具图5 版本演进路线图十二、一次典型使用流程下面用一个简单场景说明它的使用方式。12.1 第一次会话保存项目进展假设我正在开发一个长期项目当前已经完成了第五阶段发布工具链。会话中包含如下信息本次完成 v0.5.0 发布工具链包括 install.py、uninstall.py、upgrade.py、 health_check.py、memory_stats.py、release_prepare.py 和 run_acceptance.py。 当前测试结果为 78 项单元测试通过部分测试跳过。 plugin.json 仍保持 manifest-template 标记暂不宣传为正式官方插件。系统会将其整理为结构化记忆# Topic: v0.5.0 发布工具链 ## Summary 本次完成 Claude Code Memory Skill v0.5.0 发布工具链包括安装、卸载、升级、健康检查、记忆统计、发布准备和验收测试工具。 ## Keywords v0.5.0, release, install, uninstall, upgrade, health check, acceptance test ## Key Decisions - v0.5.0 阶段聚焦发布工具链。 - plugin.json 保持 manifest-template 标记。 - 暂不将项目宣传为官方 Claude Code 插件。 ## TODO - 补充 RELEASE_CHECKLIST.md。 - 进一步验证 Windows PowerShell Hook。 - 完善 README 中的安装示例。12.2 第二次会话检索历史上下文下一次开启 Claude Code 时如果我输入帮我继续完善 v0.5.0 的发布检查清单。系统会检索到上一轮保存的记忆并将相关摘要、关键决策和待办事项注入上下文。这样 Claude Code 就能知道当前版本是 v0.5.0发布工具链已经完成plugin.json 仍然是 manifest-template下一步应该补充RELEASE_CHECKLIST.mdWindows PowerShell Hook 还需要进一步验证。这就是项目记忆的核心价值。十三、项目价值总结Claude Code Memory Skill 的价值不在于“让 AI 记住所有东西”而在于建立一个可控、可读、可维护的项目记忆层。它解决的是 AI 辅助开发中的一个真实问题当项目持续推进时如何让 AI 找回历史上下文并延续之前的技术决策从技术实现上看它采用了非常轻量的方案Markdown 文件负责保存记忆 JSON 索引负责快速检索 Hook 负责自动触发 CLI 负责手动维护 Workspace 负责项目隔离这种方案虽然不复杂但足够实用尤其适合个人开发者、科研项目和长期工程任务。从工程角度看项目已经逐步补齐了安装、卸载、升级、健康检查、记忆统计、验收测试和发布准备工具。这说明它已经不只是一个简单脚本而是在向可维护的开源工具演进。十四、结语在 AI 编程工具越来越强的今天代码生成本身已经不是唯一问题。对于长期项目来说更重要的是如何管理开发过程中的上下文、决策和阶段性知识。Claude Code Memory Skill 是我围绕这个问题做的一次轻量级实践。它通过本地 Markdown 记忆库和 JSON 索引把 Claude Code 会话中的关键内容沉淀下来通过 Hook 和 CLI 工具让这些记忆能够在后续会话中重新发挥作用。它目前仍然是一个 Release Candidate 项目还有很多可以继续完善的地方例如真正的语义检索、记忆合并、可视化界面和更完整的跨平台验证。但从当前阶段来看它已经能够为长期项目提供一个清晰、可读、可维护的本地记忆方案。如果你也经常使用 Claude Code 推进长期项目并且遇到过反复解释上下文、历史决策难以找回、待办事项容易遗漏的问题那么这种本地记忆库的思路或许也值得尝试。