CAMH协议：为AI编程助手构建持久记忆系统，告别重复解释

1. 项目概述告别重复解释让AI记住你的每一次对话如果你和我一样每天都在和Claude、Cursor这类AI编程助手打交道那你一定对下面这个场景深恶痛绝早上打开编辑器新建一个会话准备继续昨晚没写完的功能模块结果AI助手一脸茫然地问你“这个项目是做什么的我们之前改动了哪些文件你希望我接下来做什么” 于是你不得不花上宝贵的十分钟甚至更久把项目的来龙去脉、技术栈选择、昨天的进展、遇到的坑再复述一遍。这感觉就像每天上班都要向一个失忆的同事重新介绍一遍自己效率低下令人沮丧。这就是CAMHClauditor Autonomous Memory Handoff要解决的核心痛点。它不是一个复杂的软件而是一套轻量、可落地的“记忆协议”。其核心思想异常简单却无比强大在每次AI会话结束时系统性地“转储”当前的工作状态和上下文在每次新会话开始时自动“加载”这些状态。通过一套结构化的Markdown模板和一个简单的同步脚本CAMH能为你所有的AI编码助手Claude Code, Clauditor, Cursor等构建一个持续、进化的记忆系统让每一次对话都建立在之前所有工作的坚实基础上彻底告别从零开始的尴尬。我花了大约一周时间将这套协议集成到我的日常开发流程中。实测下来它带来的效率提升是肉眼可见的。最直接的感受是AI助手提出的建议变得更具连贯性和建设性因为它“知道”项目的全貌和历史的决策。今天我就把这套经过实战检验的方法从设计理念到每一个文件的具体写法毫无保留地分享给你。2. 协议核心六层记忆模型与“转储-加载”循环CAMH的威力源于其清晰的结构设计。它将一个项目所需的上下文信息分解为六个逻辑层次这就像为AI构建了一个分层的记忆宫殿。2.1 六层记忆模型详解每一层都承载着特定类型的信息共同构成AI理解你和你的项目所需的完整图谱。第一层操作者记忆这是关于“你”的永久档案。它不随项目变化而是你的数字身份。内容包括你的姓名或化名、技术角色全栈、前端、DevOps等、惯用的技术栈例如偏好React over Vue使用TypeScript严格模式、代码风格偏好缩进用2空格还是4空格尾随逗号加不加、甚至是你与AI交互的沟通风格例如“请直接给出代码减少解释性文字”。这层信息确保AI从一开始就用你熟悉的方式与你对话。第二层项目状态这是项目的实时快照。它动态记录着项目的当前状况项目名称、Git仓库地址、运行中的服务及其端口如前端localhost:3000后端APIlocalhost:8080、核心的目录结构、已知的Bug或待办事项、以及当前聚焦的功能模块。这层信息是AI理解“我们现在在哪儿”的关键。第三层会话历史与决策日志这是项目的“时间线”和“决策档案”。SESSION_HANDOFF.md记录每次会话的总结我们做了什么、修改了哪些文件、遇到了什么问题、下次会话从哪里开始。DECISION_LOG.md则专门记录那些重要的、难以回退的技术决策及其理由比如“为何选择SQLite而非PostgreSQL”、“为何采用Redux Toolkit而非Context API”。这回答了“我们是怎么走到这一步的”以及“为什么事情是这样的”。第四层身份与规则这是你给AI的“操作手册”或“公司章程”。它比第一层更具体地规定了AI的行为准则。例如“所有生成的函数必须包含JSDoc注释”、“在建议使用新库之前先检查package.json中是否已有类似功能的依赖”、“避免使用已弃用的API”、“代码压缩时优先考虑可读性而非极致的字符数”。这层信息塑造了AI的输出质量使其更符合你的工程规范。第五层知识库这是项目的“参考资料区”。它不存放完整的文档而是提供关键知识的指针和摘要。例如项目核心架构的简述、使用的第三方服务如Stripe, Auth0的关键配置项、内部API的端点速查表、或者复杂业务逻辑的流程图链接。这相当于给了AI一个快捷的“维基百科”帮助它做出更准确的判断。第六层实时数据这是可选的扩展层用于集成动态信息。例如你可以配置脚本将CI/CD管道的最近一次构建状态、监控仪表盘的关键指标、甚至是一张Google Sheets表格的摘要同步到这里。这能让AI在建议时考虑到系统当前的实时负荷或状态。2.2 “转储-加载”工作流习惯大于工具CAMH协议的精髓在于建立两个铁律般的习惯会话永不空载在启动任何一次与AI的新对话前必须确保CONTEXT_CURRENT.md由其他文件同步生成的完整上下文文档的内容被AI感知。无论是通过粘贴、引用配置文件还是工具自动加载。会话必有交接在结束一次有意义的编程会话前花2-3分钟更新SESSION_HANDOFF.md。简要记录本次成果、遗留问题和下一步计划。这就像下班前给同事写个交接便签。这个循环的自动化核心是tools/context_sync.sh脚本。它的工作简单而重要将上述第一到第五层或六层的Markdown文件按顺序拼接生成一个单一的、内容全面的CONTEXT_CURRENT.md文件。你只需要在需要更新上下文时通常是每天开始工作前或切换项目时运行一次这个脚本然后将生成的文件内容提供给AI即可。我的实操心得不要追求一次性填满所有模板文件。从最影响当前效率的部分开始。比如先写好IDENTITY.md第四层和PROJECT_STATE.md第二层就能立刻解决AI建议风格不符和不知项目现状的问题。其他层可以在后续工作中逐步补充。完成大于完美先让流程跑起来。3. 从零开始手把手部署与配置CAMH理论讲完了我们来看具体怎么做。以下步骤假设你使用macOS或Linux系统Windows用户可通过WSL或Git Bash获得类似体验。3.1 基础环境搭建与文件部署首先你需要获取CAMH的模板文件。虽然你可以直接克隆原仓库但我更推荐的方法是“复制并内化”——将模板复制到你自己的项目或一个全局配置目录中。# 1. 在你的项目根目录下创建专用的AI记忆文件夹 mkdir -p ~/my-awesome-project/.ai-memory # 2. 获取CAMH模板文件。 # 你可以从GitHub仓库下载或者直接使用我下面提供的精简模板内容创建。 # 这里我们以手动创建核心文件为例更直观。 # 进入记忆文件夹 cd ~/my-awesome-project/.ai-memory接下来创建最核心的几个模板文件。你可以直接复制以下内容并根据注释进行修改。文件1IDENTITY.md第四层 第一层部分# 操作者身份与AI交互规则 ## 我是谁 - **姓名/代号**Alex 你的名字 - **角色**全栈开发工程师偏重后端与架构 - **技术栈偏好** - 语言TypeScript (严格模式)GoPython - 前端React Next.js Tailwind CSS - 后端Node.js (Express/Fastify) Go (Gin) - 数据库PostgreSQL Redis - 工具Docker GitHub Actions Vercel/AWS ## 代码风格与规则 (AI必须遵守) 1. **格式** - 使用 2 个空格缩进。 - 字符串使用单引号 () 除非字符串内包含单引号。 - 始终使用分号。 - 优先使用 const 和 let避免 var。 2. **文档** - 所有导出的函数、类和复杂方法必须包含 JSDoc/TSDoc 注释。 - 使用 param returns 标签。 3. **安全与最佳实践** - 永远不要建议使用已知有严重安全漏洞的库版本。 - 在建议使用新的npm包前请先检查当前项目的 package.json 是否已有类似功能的依赖。 - SQL查询必须使用参数化查询或ORM禁止字符串拼接。 4. **响应风格** - 直接给出代码解决方案解释尽量简洁附在代码注释或代码块后。 - 如果我的请求模糊请先询问澄清问题再给出方案。 - 优先考虑可读性和可维护性而非最简短的代码。文件2PROJECT_STATE.md第二层# 项目实时状态 ## 项目概览 - **项目名称**E-Commerce API 平台 - **仓库地址**https://github.com/yourname/ecommerce-api - **当前分支**feat/user-authentication - **核心目标**构建一个支持JWT认证、商品管理和订单处理的RESTful API。 ## 运行环境 - **本地开发** - API 服务器localhost:8080 (使用 npm run dev) - 数据库PostgreSQL 运行在 Docker 容器 (docker-compose up db) - 缓存Redis 运行在 localhost:6379 - **依赖管理**npm (Node.js v18) ## 当前焦点与待办 - **本周重点**完成用户注册、登录、JWT签发与验证中间件。 - **进行中的文件** - src/routes/auth.ts - 登录/注册端点 - src/middleware/jwt.ts - JWT验证中间件 - **已知问题** - 在 auth.ts 中密码加密函数 bcrypt.hash 有时在Docker中运行缓慢待优化。 - 数据库迁移脚本 migrations/002_add_users.sql 尚未测试。文件3SESSION_HANDOFF.md第三层# 会话交接记录 ## 上次会话总结 (YYYY-MM-DD) - **完成了什么** - 实现了用户模型 (src/models/User.ts) 的定义和Sequelize映射。 - 创建了 /api/auth/register 端点能处理基础的用户注册请求。 - 编写了密码加盐哈希存储的逻辑。 - **修改的关键文件** - src/models/User.ts - src/routes/auth.ts - src/config/database.ts - **遇到的问题** - 在测试注册时遇到数据库连接池超时错误。已通过增加 pool 配置解决。 - **下一步计划** - 实现 /api/auth/login 端点。 - 完善JWT生成函数。 - 为登录成功响应编写单元测试。文件4DECISION_LOG.md第三层# 关键决策日志 ## 2023-10-27: 认证方案选择 - **决策**采用 JWT (JSON Web Tokens) 而非 Session Cookies 进行用户认证。 - **理由** 1. 本项目为前后端分离架构JWT更适合无状态的RESTful API。 2. 未来可能涉及移动端JWT在跨平台处理上更简单。 3. 无需在服务器端维护会话存储简化了横向扩展。 - **影响文件**整个认证流程设计、src/middleware/jwt.ts。 ## 2023-10-26: 数据库ORM选择 - **决策**使用 Sequelize 而非 TypeORM 或纯 SQL 查询。 - **理由** 1. 团队对Sequelize更熟悉有现成的使用模式。 2. 项目初期需要快速建模和迭代ORM提供足够的生产力。 3. Sequelize的TypeScript支持在v6后已趋于稳定。 - **注意**需警惕N1查询问题复杂查询可回退到原始SQL。文件5KNOWLEDGE_BASE.md第五层# 项目知识库 ## 架构图 - 简要的MVC结构路由(routes/) - 控制器(controllers/) - 服务(services/) - 模型(models/) - 数据库。 ## 外部服务配置摘要 - **SendGrid (邮件)**API密钥存储在环境变量 SENDGRID_API_KEY 中发件人默认为 noreplyourdomain.com。 - **Stripe (支付)**测试密钥前缀为 sk_test_Webhook签名密钥通过 STRIPE_WEBHOOK_SECRET 验证。 ## 核心业务逻辑备忘 - 用户权限分为guest user admin。 - 商品库存扣减遵循“下单时预占支付成功时确认扣减”的逻辑防止超卖。3.2 同步脚本的创建与使用现在我们需要创建那个“魔法”脚本——context_sync.sh它负责将所有分散的记忆层合并成一个文件。在你的.ai-memory文件夹内创建tools目录并添加脚本# 在 .ai-memory 目录下 mkdir tools cd tools创建context_sync.sh文件#!/bin/bash # context_sync.sh # 将各层记忆文件合并为 CONTEXT_CURRENT.md # 设置记忆文件夹路径默认为当前目录的上一级.ai-memory MEMORY_DIR${1:-$(dirname $0)/../} OUTPUT_FILE${MEMORY_DIR}/CONTEXT_CURRENT.md echo 正在同步AI记忆上下文... echo 记忆目录: $MEMORY_DIR # 定义文件合并顺序即层的顺序 LAYER_FILES( ${MEMORY_DIR}/IDENTITY.md ${MEMORY_DIR}/PROJECT_STATE.md ${MEMORY_DIR}/SESSION_HANDOFF.md ${MEMORY_DIR}/DECISION_LOG.md ${MEMORY_DIR}/KNOWLEDGE_BASE.md ) # 清空或创建输出文件 $OUTPUT_FILE # 添加文件头 echo # AI 会话上下文 - $(date %Y-%m-%d %H:%M:%S) $OUTPUT_FILE echo *此文件由 context_sync.sh 自动生成请勿手动编辑。* $OUTPUT_FILE echo $OUTPUT_FILE # 循环合并文件 for file in ${LAYER_FILES[]}; do if [[ -f $file ]]; then echo ## $(basename $file .md) $OUTPUT_FILE cat $file $OUTPUT_FILE echo $OUTPUT_FILE echo --- $OUTPUT_FILE echo $OUTPUT_FILE else echo ⚠️ 跳过不存在的文件: $file 2 fi done echo ✅ 上下文同步完成生成文件: $OUTPUT_FILE echo 现在你可以将此文件内容复制到AI会话中。 # 尝试将内容复制到系统剪贴板macOS if command -v pbcopy /dev/null; then cat $OUTPUT_FILE | pbcopy echo 内容已复制到剪贴板 (macOS)。 elif command -v xclip /dev/null; then cat $OUTPUT_FILE | xclip -selection clipboard echo 内容已复制到剪贴板 (Linux/xclip)。 fi给脚本添加执行权限并运行它chmod x context_sync.sh # 运行脚本指定记忆文件夹路径如果在tools目录内使用.. ./context_sync.sh ..运行后你会在.ai-memory目录下看到新生成的CONTEXT_CURRENT.md文件它包含了所有你已填写模板的内容。这个文件就是你要在每次AI会话开始时提供给AI的“完整记忆包”。3.3 与主流AI开发工具集成让加载上下文变成自动化的最后一环。与 Cursor 集成在项目根目录创建或编辑.cursorrules文件# .cursorrules # AI助手会话规则 # 首要规则每次新会话开始时必须首先完整阅读并理解以下上下文文件 ALWAYS_READ_FULL_CONTEXT: .ai-memory/CONTEXT_CURRENT.md # 次要规则在回答涉及近期修改或决策的问题时参考会话交接和决策日志 REFERENCE_FOR_HISTORY: .ai-memory/SESSION_HANDOFF.md REFERENCE_FOR_DECISIONS: .ai-memory/DECISION_LOG.md # 基于上下文的指令 - 根据 IDENTITY.md 中的规则生成代码。 - 基于 PROJECT_STATE.md 了解当前开发环境和焦点。 - 避免重复 SESSION_HANDOFF.md 中已记录为“已完成”的工作。与 Claude Code (或任何Web聊天界面) 集成这里没有配置文件但你可以建立一个快速工作流。在开始编程对话前执行cd /path/to/your/project ./.ai-memory/tools/context_sync.sh # 脚本会自动将CONTEXT_CURRENT.md内容复制到剪贴板然后在Claude的Web界面中直接粘贴即可。你可以把这条命令做成一个Shell别名比如alias ai-context“cd ~/my-proj ./.ai-memory/tools/context_sync.sh”。注意事项初次设置时最容易犯的错误是文件路径不对。确保你的context_sync.sh脚本中MEMORY_DIR的路径指向正确的.ai-memory文件夹。如果在项目子目录中运行可能需要使用绝对路径或$(git rev-parse --show-toplevel)来定位项目根目录。4. 高级技巧与个性化定制基础流程跑通后你可以根据个人工作习惯对CAMH协议进行强化和定制使其更加强大。4.1 利用Raycast实现一键同步macOS效率神器如果你使用macOSRaycast可以将同步操作简化到一个快捷键。将CAMH仓库中raycast/目录下的脚本添加到Raycast的Script Commands中。打开Raycast进入Settings-Extensions-Script Commands-Add Script Directory。选择你本地CAMH项目中的raycast文件夹。在Raycast中搜索你添加的脚本如camh-sync为其设置一个全局快捷键例如Option Shift S。现在无论你在哪个应用里按下⌥⇧S它就会自动运行同步脚本并将最新的上下文复制到剪贴板你只需在AI界面中粘贴。这消除了所有手动步骤让“加载上下文”变得和呼吸一样自然。4.2 扩展协议添加自动化信息抓取CAMH的第六层实时数据是开放的画布。你可以编写简单的脚本将动态信息注入到上下文中。例如创建一个LIVE_DATA.md文件并通过脚本更新它示例自动注入当前Git状态#!/bin/bash # update_git_context.sh MEMORY_DIR“/path/to/.ai-memory” LIVE_FILE“${MEMORY_DIR}/LIVE_DATA.md” echo “## 实时Git状态” “$LIVE_FILE” echo “\\\” “$LIVE_FILE” git -C “$(dirname “$MEMORY_DIR”)” status –short –branch “$LIVE_FILE” echo “” “$LIVE_FILE” echo “**最近一次提交**” “$LIVE_FILE” git -C “$(dirname “$MEMORY_DIR”)” log –oneline -1 “$LIVE_FILE” echo “\\\” “$LIVE_FILE”然后修改你的context_sync.sh脚本在合并文件列表的最后加上“${MEMORY_DIR}/LIVE_DATA.md”。这样每次同步的上下文都会包含最新的代码仓库状态AI就能知道哪些文件被修改了但未提交从而给出更精准的提交信息建议或代码审查意见。4.3 管理多个项目建立全局记忆与项目记忆你可能会在多个项目间切换。我建议采用混合模式全局记忆在你的家目录如~/.ai-memory/global/下存放IDENTITY.md和全局的KNOWLEDGE_BASE.md包含你所有项目的通用技术栈、公司内部知识等。这些是关于“你”的恒定信息。项目记忆在每个项目根目录的.ai-memory/下存放PROJECT_STATE.mdSESSION_HANDOFF.mdDECISION_LOG.md和项目特定的KNOWLEDGE_BASE.md。然后创建一个智能的同步脚本它先合并全局记忆再合并项目记忆生成最终的项目上下文。这避免了在每个项目中重复填写你的个人偏好。4.4 版本控制与协作.ai-memory文件夹应该被加入你的.gitignore吗这取决于你。忽略如果你的记忆文件包含敏感信息API密钥、内部架构细节或者纯属个人备忘风格建议将其加入.gitignore。提交如果记忆文件中的DECISION_LOG.md和项目相关的KNOWLEDGE_BASE.md对团队其他成员也有价值可以作为项目文档的一部分提交。你可以考虑提交一个templates/目录或example.文件让队友知道这个模式的存在。我的做法是将DECISION_LOG.md和项目KNOWLEDGE_BASE.md提交到仓库因为它们属于项目文档。而IDENTITY.md和SESSION_HANDOFF.md这种高度个人化的文件则留在本地通过.gitignore忽略。5. 常见问题与实战排坑指南在推广和使用这套方法的过程中我和我的团队成员遇到了一些典型问题。这里汇总一下希望能帮你绕过这些坑。5.1 问题感觉维护这些Markdown文件很麻烦坚持不下来。分析与解决 这是最常见的障碍。关键在于改变认知这不是额外的文档工作而是替代了每次会话前你都要做的、重复的口头或打字解释。启动成本最低化第一天只创建并填写IDENTITY.md。这能立刻提升AI回复的贴合度带来正反馈。利用交接仪式把写SESSION_HANDOFF.md当作一天编程工作结束的“关机仪式”。只花2分钟用bullet points列出三点今天做了什么、卡在哪里、明天先做什么。这不仅能帮助AI更能帮你自己理清思路。同步自动化一定要设置Raycast快捷键或Shell别名。让“同步”这个动作变得极其简单没有阻力。5.2 问题上下文太长了AI有令牌限制放不下怎么办分析与解决 确实随着项目进行CONTEXT_CURRENT.md文件会越来越大。分层摘要不要在基础层文件里写长篇大论。PROJECT_STATE.md只记录当前最相关的3-5个模块状态。KNOWLEDGE_BASE.md只放链接和关键词而非全文。定期归档在SESSION_HANDOFF.md中每周或每个里程碑结束时做一个“周总结”段落然后把旧的、已完成的会话记录移到一个archive/文件夹里。同步脚本可以排除这个文件夹。智能截断对于Claude等模型你可以修改同步脚本让它只合并最近N天的SESSION_HANDOFF记录或者只保留最新的5条决策日志。核心是保持“活性记忆”的精简。使用向量检索对于超大型项目终极方案是引入轻量级向量数据库如ChromaDB。将记忆片段向量化存储AI提问时只检索最相关的部分。但这属于进阶玩法初期不必考虑。5.3 问题AI似乎没有认真读我提供的上下文还是问一些基础问题。分析与解决 这可能是提示词Prompt不够强硬或者AI工具配置不对。强化指令在IDENTITY.md的开头或与AI集成的配置文件如.cursorrules中用非常明确的语气强调“重要指令在开始回答任何问题之前你必须已经完整阅读并理解了CONTEXT_CURRENT.md文件中的所有内容。你的所有建议都应基于该上下文。如果我的请求与上下文中记录的信息相关请直接引用该信息不要要求我重复。”检查集成确保你的AI工具确实加载了该文件。对于Cursor检查设置中是否启用了.cursorrules。对于Claude Code确认你粘贴了全部内容。提问技巧有时在提问时直接引用上下文中的关键词也有帮助。例如“根据PROJECT_STATE.md我们现在正在auth.ts中工作遇到了密码加密性能问题。请看一下KNOWN_ISSUES部分并给出一个优化bcrypt.hash调用的方案。”5.4 问题团队中每个人都有自己的IDENTITY.md如何协作分析与解决 CAMH协议天生支持个性化。个人私有项目共享IDENTITY.md是纯个人的不应提交到代码库。每个团队成员在自己的本地副本中维护自己的版本。统一项目上下文PROJECT_STATE.mdDECISION_LOG.md和项目KNOWLEDGE_BASE.md应该是团队共享的。可以将其放在项目根目录并纳入版本控制。团队需要约定一个简单的更新规范比如修改关键决策后更新DECISION_LOG.md。交接班工具SESSION_HANDOFF.md可以成为团队晨会或交接班的绝佳参考。昨天我做了什么、遇到什么坑、今天计划做什么一目了然。5.5 问题同步脚本在Windows上无法运行。分析与解决 原脚本依赖于Bash shell。在Windows上你有几个选择使用Git Bash安装Git for Windows它自带了Git Bash一个模拟的Linux终端环境可以直接运行.sh脚本。使用WSL安装Windows Subsystem for Linux获得完整的Linux环境这是最接近macOS/Linux的体验。转换为PowerShell脚本将context_sync.sh的逻辑用PowerShell重写。核心逻辑是读取多个Markdown文件并合并。PowerShell同样可以操作剪贴板通过Set-Clipboard命令。一个简单的PowerShell脚本示例 (context_sync.ps1)# context_sync.ps1 $memoryDir “.\.ai-memory” $outputFile “$memoryDir\CONTEXT_CURRENT.md” $layerFiles ( “$memoryDir\IDENTITY.md”, “$memoryDir\PROJECT_STATE.md”, “$memoryDir\SESSION_HANDOFF.md”, “$memoryDir\DECISION_LOG.md”, “$memoryDir\KNOWLEDGE_BASE.md” ) “# AI 会话上下文 - $(Get-Date -Format ‘yyyy-MM-dd HH:mm:ss’)” | Out-File -FilePath $outputFile “*此文件由 context_sync.ps1 自动生成请勿手动编辑。*” | Add-Content -Path $outputFile “” | Add-Content -Path $outputFile foreach ($file in $layerFiles) { if (Test-Path $file) { “## $([System.IO.Path]::GetFileNameWithoutExtension($file))” | Add-Content -Path $outputFile Get-Content $file | Add-Content -Path $outputFile “” | Add-Content -Path $outputFile “---” | Add-Content -Path $outputFile “” | Add-Content -Path $outputFile } else { Write-Warning “跳过不存在的文件: $file” } } Write-Host “✅ 上下文同步完成生成文件: $outputFile” -ForegroundColor Green # 尝试复制到剪贴板 Get-Content $outputFile -Raw | Set-Clipboard Write-Host “ 内容已复制到剪贴板 (Windows PowerShell)。” -ForegroundColor Cyan运行这个PS1脚本可能需要先修改执行策略以管理员身份运行PowerShell一次Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser。这套CAMH协议我用了几个月它已经彻底改变了我与AI协作的方式。它带来的最大价值不是某个具体的技术点而是一种“连续性”。你的AI助手从一个健忘的临时工变成了一个拥有长期记忆、了解项目来龙去脉、熟悉你工作习惯的资深搭档。启动成本很低但复利效应惊人。如果你也受困于日复一日的重复解释不妨今天就花半小时从创建一个IDENTITY.md文件开始。