企业官网建设流程全解析

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 的每次会话天然是相对独立的。新会话并不会自动知道历史会话中的全部背景。这就导致长期项目中经常出现几个问题：

图1 多会话上下文断裂问题

1.2 本地记忆库想解决什么

我希望 Claude Code Memory Skill 能做到几件事：

1. 会话结束后自动保存记忆：将本次会话中的重要内容整理成结构化 Markdown 文件。
2. 新会话开始前自动检索上下文：根据用户当前输入，查找与当前任务相关的历史记忆。
3. 按项目隔离记忆内容：不同 workspace 的记忆应该分开管理，避免多个项目相互干扰。
4. 记忆文件人类可读：不依赖复杂数据库，直接用 Markdown 保存，方便人工查看、修改、删除和归档。
5. 提供基础维护工具：支持安装、卸载、升级、健康检查、统计和验收测试。

最终目标可以概括为一句话：

为 Claude Code 提供一个轻量级、本地化、结构化的项目记忆层，让 AI 更适合参与长期工程项目。

二、项目定位与设计目标

Claude Code Memory Skill 是一个面向 Claude Code 的本地会话记忆工具。它主要解决的是：

如何将 Claude Code 开发过程中的重要上下文沉淀下来，并在后续会话中重新利用。

项目的核心设计可以概括为：

Markdown 记忆文件 + JSON 索引 + Hook 自动触发 + CLI 工具链

它并没有一开始就引入数据库、向量数据库或复杂的外部服务，而是优先采用低依赖、可读、易迁移的方案。

2.1 适用场景

这个工具比较适合以下场景：

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 核心模块

项目可以拆分为四个主要模块：

3.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 的优势

对于个人开发者而言，这种方式非常实用。记忆不是黑箱，而是可以被检查、编辑和维护的普通文本文件。

五、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:00+08:00","updated_at":"2026-06-03T22:10:00+08:00"}]}

索引文件的作用包括：

• 快速定位相关记忆；
• 保存主题和关键词；
• 支持 workspace 隔离；
• 避免每次检索都全文扫描；
• 为后续混合检索和语义检索留出扩展空间。

5.2 Workspace 隔离

Claude Code 经常会被用于多个项目。如果所有记忆都混在一起，检索时很容易出现无关上下文。因此项目支持 workspace 隔离。

例如：

python scripts/workspace_manager.py init--workspacemy-project

保存记忆时也可以指定 workspace：

python scripts/summarize_session.py--workspacemy-project--topic"Phase 5 发布工具"--text"本次会话完成安装、卸载、升级、健康检查和验收测试工具。"

这样，不同项目的历史上下文可以独立保存和检索。

六、检索机制与上下文注入

6.1 从用户输入到相关记忆

当用户在新会话中输入一个问题时，系统需要判断：

哪些历史记忆和当前问题最相关？

基本流程如下：

用户输入 ↓ 关键词提取 ↓ 多字段匹配 ↓ 加权评分 ↓ score_breakdown 输出 ↓ 返回相关记忆

图4 检索评分流程图

6.2 多字段加权检索

项目不是只在全文中搜索关键词，而是会综合多个字段进行评分。

当某条记忆被命中时，可以通过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.json

7.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 为什么需要 CLI

Hook 自动化适合日常使用，但开发和维护过程中仍然需要命令行工具。例如：

• 手动保存一次记忆；
• 检索某个主题；
• 初始化 workspace；
• 检查记忆库状态；
• 统计记忆文件；
• 发布前执行验收测试。

8.2 常见命令示例

初始化 workspace：

python scripts/workspace_manager.py init--workspacemy-project

保存一次会话记忆：

python scripts/summarize_session.py--workspacemy-project--topic"Phase 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--quick

8.3 一次完整操作示例

# 1. 初始化项目记忆空间python scripts/workspace_manager.py init--workspaceclaude-memory-skill# 2. 保存一条阶段记忆python scripts/summarize_session.py--workspaceclaude-memory-skill--topic"v0.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_DIR=Path("memory")TOPICS_DIR=MEMORY_DIR/"topics"INDEX_FILE=MEMORY_DIR/"index.json"defslugify(text:str)->str:"""将主题转换为安全文件名。"""text=re.sub(r"[^\w\u4e00-\u9fff-]+","_",text.strip())returntext[:80].strip("_")or"untitled"defload_index()->dict:ifINDEX_FILE.exists():returnjson.loads(INDEX_FILE.read_text(encoding="utf-8"))return{"items":[]}defsave_index(index:dict)->None:MEMORY_DIR.mkdir(parents=True,exist_ok=True)INDEX_FILE.write_text(json.dumps(index,ensure_ascii=False,indent=2),encoding="utf-8")defsave_memory(topic:str,summary:str,keywords:list[str],decisions:list[str],todos:list[str],)->Path:MEMORY_DIR.mkdir(parents=True,exist_ok=True)TOPICS_DIR.mkdir(parents=True,exist_ok=True)filename=f"{slugify(topic)}.md"path=TOPICS_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),encoding="utf-8")index=load_index()index["items"].append({"topic":topic,"keywords":keywords,"summary":summary,"path":str(path.relative_to(MEMORY_DIR)),"created_at":datetime.now().isoformat(timespec="seconds")})save_index(index)returnpath

调用示例：

save_memory(topic="v0.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:int=3)->list[dict]:index=load_index()query_tokens=set(query.lower().split())scored=[]foriteminindex.get("items",[]):topic=item.get("topic","").lower()summary=item.get("summary","").lower()keywords=[k.lower()forkinitem.get("keywords",[])]topic_score=sum(1fortokeninquery_tokensiftokenintopic)*0.4summary_score=sum(1fortokeninquery_tokensiftokeninsummary)*0.3keyword_score=sum(1fortokeninquery_tokensforkwinkeywordsiftokeninkw)*0.3total_score=topic_score+summary_score+keyword_scoreiftotal_score>0: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,key=lambdax:x["score_breakdown"]["total_score"],reverse=True)[:top_k]

调用示例：

results=retrieve_memory("v0.5.0 发布 工具 健康检查")foriteminresults:print(item["topic"])print(item["score_breakdown"])

这个简化示例体现了项目最核心的思想：先把会话转成结构化记忆，再通过索引进行可解释检索。

十、工程化能力：从脚本到工具

10.1 v0.5.0 的发布工具链

为了让这个工具真正能被使用，而不只是停留在脚本原型，v0.5.0 中补充了完整的发布和维护工具链。

10.2 测试与验收

一个记忆工具如果没有测试，很容易在后续迭代中破坏已有功能。因此项目中加入了单元测试和验收测试，用于检查：

• Markdown 记忆是否能正确生成；
• index.json 是否能正确更新；
• 检索功能是否正常；
• workspace 隔离是否有效；
• Hook 脚本是否可运行；
• JSON 文件是否可解析；
• 发布工具是否可执行。

对于一个 Claude Code 辅助开发工具来说，测试不仅是质量保障，也是一种自我验证：工具本身也应该符合工程化规范。

十一、版本演进路线

项目可以按阶段理解为五个部分。

图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.md；
• Windows 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 推进长期项目，并且遇到过反复解释上下文、历史决策难以找回、待办事项容易遗漏的问题，那么这种本地记忆库的思路或许也值得尝试。