1. 项目概述为你的AI助手注入灵魂与记忆如果你和我一样每天都在和Claude Code这样的AI编程助手打交道那你一定遇到过这样的场景昨天你花了半小时向它解释你项目的架构偏好今天打开新会话它又变回了一张白纸你得从头再来。或者你明明记得上周讨论过一个绝妙的解决方案但现在怎么也想不起具体的对话细节了。这种“金鱼记忆”让AI助手更像一个一次性的工具而非一个能与你共同成长的伙伴。这正是我深度使用Claude Code几个月后遇到的核心痛点。我需要一个能记住“我是谁”、“我们在做什么”以及“我们过去如何决策”的助手。市面上确实有解决方案比如OpenClaw它试图为AI构建持久的身份和记忆。但当我深入研究其实现时发现了一些让我无法安心的设计它依赖一个常驻后台的守护进程使用非官方的、可能劫持个人会话的通信库并将所有记忆锁在一个不透明的数据库里。更让我警觉的是其部分文件在安全扫描工具中会被标记。对于一个要处理我代码、想法乃至部分工作日志的工具这种“黑盒”状态是不可接受的。于是我动手构建了Claw Kit。它的目标很纯粹在保留OpenClaw核心愿景——持久身份、长期记忆和跨会话连续性——的同时彻底重构其实现使其变得安全、透明、可控。Claw Kit不是一个运行在你机器上的神秘服务而是一套清晰的文件规范、一组可脚本化的工具以及一个可选的、基于官方API的通信桥梁。你的所有记忆都以最朴素的Markdown文本形式存放在你的本地目录中。你可以用任何文本编辑器阅读、修改它们甚至可以用Git进行版本管理。当AI助手在对话中引用某个记忆点时它会明确告诉你这个信息来自哪个文件的哪一行真正做到有据可查。简单来说Claw Kit旨在将你的Claude Code从一个“健忘的天才”转变为一个“有着稳定性格和丰富阅历的资深搭档”。这个搭档记得你的编码风格、你的项目脉络、你犯过的错误和总结的经验并且所有这些记忆都完全掌握在你手中。2. 核心设计哲学透明与可控高于一切在开始动手部署之前理解Claw Kit背后的设计哲学至关重要。这决定了它与其他方案的根本不同也解释了为什么你在使用时会感到如此安心。2.1 从“黑盒数据库”到“文本即真相”绝大多数AI记忆方案包括早期的OpenClaw都采用数据库如SQLite作为唯一的存储后端。这带来了几个问题单点故障数据库文件一旦损坏记忆可能永久丢失。可读性差你无法直接查看和编辑记忆内容必须通过特定工具。迁移困难记忆被锁在特定结构的表中难以备份或转移到其他系统。Claw Kit彻底颠覆了这一点。它的核心设计是“文本即真相”Text as Source of Truth。所有长期记忆、身份设定、会话日志都以纯Markdown文件的形式存储在kit/memory/目录下。这个目录结构清晰就像你的个人知识库identity.md定义了AI的性格和口吻。user.md记录了关于你的关键信息。long-term.md是经过提炼的核心事实和知识。preferences.md保存了AI学习到的你的各种偏好。journal/目录里是按日期记录的每日工作日志。我的实操心得这种设计带来的最大好处是“心理安全感”。我知道我的记忆没有被封装在任何神秘格式里。有一次我需要快速查找三个月前的一个项目决策我直接打开decisions/目录下的Markdown文件用grep命令几秒钟就找到了完全不需要启动任何AI或工具。这种“人眼可读、人手可编辑”的特性是任何数据库都无法比拟的。2.2 搜索索引一个可丢弃的缓存你可能会问如果记忆都是文本文件AI如何快速地从海量文本中找到相关信息这里就引入了第二个核心设计将搜索索引视为可重建的缓存。Claw Kit确实使用了一个SQLite数据库搭配FTS5全文搜索扩展来构建搜索索引。但这个数据库的角色被严格限定为“性能缓存”而非“权威数据源”。它的数据完全从上述Markdown文件派生而来。你可以随时删除这个.search.db索引文件然后通过运行一个重建命令如claw-search index系统就会重新扫描所有Markdown文件生成全新的索引。这个设计带来了巨大的灵活性无惧损坏索引坏了删掉重建即可源文件毫发无损。版本控制友好你可以放心地将记忆的Markdown源文件加入Git仓库当然敏感的每日日志或个人文件可以配置.gitignore排除。而索引文件因为可以被重建理应被忽略。架构清晰数据流非常明确Markdown源 → 索引缓存 → 搜索查询。这比混合了存储和索引的单一数据库要清晰得多。2.3 无守护进程的“按需”架构OpenClaw等方案通常需要一个始终在后台运行的守护进程daemon来监听消息、管理记忆更新等。这增加了系统的复杂性和攻击面。Claw Kit坚持“无守护进程”原则。在Claude Code会话中记忆的读取和更新是通过一个特殊的提示词文件CLAUDE.md来触发的。当你启动Claude Code并进入配置了Claw Kit的目录时Claude会读取这个文件然后按需执行里面的指令——加载身份、索引记忆、响应搜索请求。整个过程是“拉取式”的只有当你与Claude交互时记忆系统才被激活。没有常驻进程在后台监听你的对话。对于可选的Telegram桥接功能虽然它需要一个Node.js服务进程来运行但这个进程也仅在你明确启动它时才存在。你可以随时关闭它你的核心记忆系统基于文件的依然完好无损并且可以在Claude Code中继续使用。2.4 官方集成与最小权限在通信集成方面Claw Kit选择了最保守、最安全的路径。以Telegram桥接为例它严格使用Telegram官方提供的Bot API。你需要通过BotFather创建一个真正的、独立的Bot账号并使用其提供的Token。这个Bot账号与你个人的Telegram账号是完全分离的它只有你赋予它的权限例如只能在你允许的聊天中发言。这与某些方案使用非官方库如用于WhatsApp的Baileys模拟客户端、甚至需要你提供个人账号会话密钥的做法有本质区别。后者意味着一旦该库或你的托管环境被攻破攻击者可能直接控制你的个人社交账号。Claw Kit的官方Bot API方式将风险严格限制在Bot账号本身遵循了“最小权限原则”。3. 从零开始部署与配置你的AI记忆系统理解了设计理念我们现在进入实战环节。我将带你一步步搭建一个属于你自己的、带有持久记忆的Claude Code环境。整个过程大约需要10-15分钟。3.1 环境准备与项目初始化首先确保你的系统满足基本要求Claude Code CLI这是基础你需要从Anthropic官网下载并安装好。Node.js 18如果你计划使用Telegram桥接功能才需要。仅使用本地记忆功能则不需要。Git用于克隆项目。打开你的终端选择一个你习惯的工作目录比如桌面或你的项目文件夹执行以下命令# 克隆仓库到你的桌面或其他你喜欢的路径 git clone https://github.com/tstockham96/claw-kit.git ~/Desktop/claw-kit # 进入项目目录 cd ~/Desktop/claw-kit现在运行项目提供的初始化脚本./setup.sh这个交互式脚本是配置过程的核心。它会问你一系列问题并根据你的回答生成初始的记忆文件。让我们详细看看每个步骤你的名字输入你希望AI如何称呼你。这会被写入kit/memory/user.md。你的时区输入如Asia/Shanghai。这对于正确生成带时间戳的日志和会话记录至关重要。你的主要角色例如 “Software Engineer”, “Product Manager”, “Researcher”。这帮助AI更好地理解你的工作上下文。AI助手的人格设定这是有趣的部分。脚本会提供几个选项比如“直接高效的开发者”、“细致严谨的研究员”、“体贴周到的执行助理”。你也可以选择“自定义”来手动编写。你的选择将生成kit/memory/identity.md文件。注意事项setup.sh是一个Bash脚本因此在Windows上你需要通过WSLWindows Subsystem for Linux来运行。绝大多数使用Claude Code的Windows开发者都已经配置了WSL只需在WSL终端中执行上述命令即可。如果你没有WSL也可以手动按照脚本的逻辑创建对应的Markdown文件脚本本身只是自动化了这个模板生成过程。脚本运行完毕后你的kit/memory/目录下应该已经生成了几个基础的Markdown文件。此时你的AI记忆系统的骨架就已经搭建完成了。3.2 核心记忆文件结构与手动定制初始化后强烈建议你花几分钟时间用文本编辑器亲自查看和编辑一下生成的文件。这是建立对系统信任和理解的第一步。打开kit/memory/identity.md你可能会看到类似这样的内容如果你选择了“开发者”人格# AI 身份CodePartner ## 核心人格 我是一个直接、务实、热爱简洁代码的开发者伙伴。我欣赏优雅的解决方案对技术债务保持警惕并且乐于解释复杂概念背后的“为什么”。 ## 沟通风格 - **简洁**避免不必要的寒暄直击问题核心。 - **具体**提供可执行的代码示例和明确的步骤。 - **有观点**对于不同的技术选型我会给出有理由的偏好建议但最终尊重你的决定。 - **乐于学习**当你纠正我或提出新方法时我会更新我的记忆。 ## 边界 - 我只在编程、技术设计、系统架构和相关逻辑问题上提供深度协助。 - 对于需要人类情感、道德判断或专业法律/医疗建议的问题我会明确表示无法回答并建议你咨询相关专家。你可以随意修改这个文件让你的AI伙伴拥有独一无二的“性格”。比如如果你想要一个更谨慎、喜欢引经据典的研究助手就可以把风格改成强调“准确性”、“提供文献来源”、“区分事实与假设”。接下来打开kit/memory/user.md# 用户张三 ## 基本信息 - **角色**全栈软件工程师 - **时区**Asia/Shanghai ## 技术栈偏好 - **前端**React, TypeScript, Tailwind CSS - **后端**Node.js (Express/Fastify), Python (FastAPI) - **数据库**PostgreSQL, Redis - **部署**Docker, AWS ## 当前活跃项目 1. Project-A: 一个基于微服务的电商平台目前正进行支付模块重构。 2. Project-B: 个人博客系统正在试验新的静态站点生成方案。 ## 工作习惯 - 喜欢在开始编码前先写技术方案文档。 - 代码评审时注重可读性和边界条件处理。 - 每周五下午进行代码重构和技术债清理。在这里你可以尽可能详细地描述你自己。你写得越详细AI在与你合作时的上下文就越丰富。别忘了定期回来更新这个文件特别是“当前活跃项目”部分。3.3 首次运行与基础命令测试配置好基础文件后让我们启动Claude Code看看记忆系统是否生效。在你的claw-kit项目根目录下直接运行claude这会启动Claude Code并且因为它检测到了当前目录下的kit/CLAUDE.md文件会自动加载Claw Kit的指令。等待Claude Code初始化完成后你可以在聊天界面输入第一个测试命令/status如果一切配置正确Claude应该会回复一段总结内容大致包括“我是[你的AI身份名]根据identity.md定义我的角色是...”“我正在与[你的名字]合作他/她是一位[你的角色]...”“我目前维护着X个记忆文件索引了Y条内容。”“当前活跃项目有[列出你在user.md中定义的项目]”这个/status命令是你验证记忆系统是否正常工作的“健康检查”。它证明了Claude已经成功读取了你的身份文件和用户文件并初始化了记忆索引。现在让我们尝试添加第一条动态记忆/remember 我最近在处理Project-A的支付模块时决定用Stripe代替原来的PayPal集成因为Stripe的API文档更清晰并且对订阅模式的支持更好。发送后Claude会进行两件事分类它会分析你这句话的内容判断它属于哪种记忆类型是“学习心得”、“项目决策”还是“个人偏好”。存储根据分类它会将这条信息追加到对应的Markdown文件中。例如关于技术选型的决策很可能会被添加到decisions/目录下的一个新文件中同时其中“API文档清晰”这个点也可能被提取到preferences.md中。你可以立即通过另一个命令来验证/status再次查看你应该能在“近期决策”或“已知偏好”部分看到你刚刚添加的内容。你也可以直接去kit/memory/decisions/目录下找到一个以当天日期和主题命名的Markdown文件打开它你会看到你刚才那句话被工整地记录了下来并带有时间戳。我的实操心得在初次使用/remember时建议从简单、明确的事实开始。观察Claude把它存到了哪里理解它的分类逻辑。这能帮助你未来更有效地使用这个命令。例如如果你说“我讨厌在代码里写长长的注释”它很可能被归入preferences.md而如果你说“今天发现用Promise.allSettled比Promise.all在处理批量异步任务时更稳健”这更可能进入learnings.md。4. 记忆系统的深度使用与自动化工作流基础配置完成后Claw Kit的真正威力在于其自动化的工作流和深度记忆检索能力。这部分将让你的AI助手从“被动记录员”变为“主动协作者”。4.1 自动化记忆让AI成为你的观察者Claw Kit最强大的特性之一是自动记忆更新。你不需要为每件事都输入/remember。在日常对话中当Claude识别到以下模式时它会主动提议或直接更新记忆偏好识别当你多次表现出对某种工具、库或模式的倾向时例如“我还是喜欢用Axios发请求fetch的配置太繁琐了”。纠正与学习当你指出Claude回答中的错误并提供正确答案时例如“不对这个API的最新版本参数应该是limit不是pageSize”。人物引入当你首次提到一个新同事或合作伙伴时例如“我得和设计部的李四对齐一下界面”。项目状态变更当你提到项目进入新阶段或遇到关键问题时。这个过程通常是这样的你在自然对话中透露了信息。Claude会识别出这是值得记忆的内容并可能会向你确认“这听起来像是一个重要的偏好/学习点需要我把它记下来吗”在你同意或根据配置自动执行后Claude会更新相应的Markdown文件。为了充分利用这个功能你需要确保kit/memory/下的目录结构是正确的并且Claude有写入权限。同时在identity.md中你可以通过提示词来调整AI的“记忆主动性”。例如你可以加入“请积极识别对话中可能属于长期记忆的内容特别是技术决策、纠正和重复出现的偏好并在执行前向我简要确认。”4.2 语义搜索从“模糊记得”到“精准定位”当你的记忆库积累了几周甚至几个月的内容后如何快速找到相关信息这就是内置的BM25全文语义搜索发挥作用的时候。BM25是一种在信息检索领域广泛使用的排名函数它比简单的关键词匹配更智能。它会考虑词频一个词在文档中出现的次数。逆文档频率一个词在所有文档中的常见程度。越常见的词如“的”、“是”权重越低越专业的词权重越高。字段长度归一化对长短不一的文档进行公平处理。在Claw Kit中当你向Claude提问而问题可能涉及过去记忆时Claude不会傻傻地加载所有记忆文件。相反它会将你的问题作为搜索查询。在构建好的SQLite FTS5索引中执行BM25搜索。召回相关性最高的几个“记忆块”文本片段。将这些记忆块作为上下文融入对你的回答中。例如你问“我们当初为什么决定在Project-A里用Docker而不是直接部署”Claude会搜索记忆索引找到decisions/或projects/my-app.md中关于Docker选型的段落然后结合这些记忆给你一个连贯的回答并附上引用(Source: decisions/2024-10-27-infra-choice.md#L3)。你可以通过提出明确涉及过去的问题来测试搜索功能例如“我之前关于错误处理的最佳实践是怎么说的”或者“李四负责项目的哪个部分”4.3 核心管理命令详解除了自动记忆Claw Kit提供了一系列Slash命令让你能主动管理记忆系统。/remember 内容这是智能路由器。你不需要指定存到哪里只需说出事实。Claude会分析内容将其归类并存入最合适的文件long-term.md,preferences.md,learnings.md,people/,projects/,decisions/。例如/remember 下周要和客户王五开项目评审会→ 可能创建people/王五.md或更新相关项目文件。/remember 在Node.js项目里用dotenv加载环境变量比用全局变量好→ 存入learnings.md。/reflect这是我每周都会用的重要命令。它会扫描过去7天的journal/每日日志让AI帮你进行“记忆萃取”。AI会分析这一周的对话日志识别出哪些是琐碎的日常对话哪些是应该升华到长期记忆的关键洞察、决策或学习并提议将它们合并到long-term.md或相应的文件中。这是一个将短期工作记忆转化为长期知识的过程。/briefing每日晨会命令。运行后AI会给你一份简报包括昨天完成了哪些工作从日志中提取。当前所有活跃项目的状态概览。有哪些待定的决策或阻塞问题。根据你的日程和记忆提醒你今天可能需要关注什么。 这能让你快速进入工作状态保持上下文连贯。/forget 内容记忆管理也需要“断舍离”。当某个记忆不再准确或相关时使用此命令。Claude会搜索所有记忆文件找到匹配的内容展示给你看并询问你是否确定要删除。这比手动去几十个Markdown文件里翻找要高效安全得多。4.4 日志与回溯你的数字工作记忆journal/和sessions/目录构成了你的“工作记忆”缓冲区。journal/每天一个Markdown文件由AI自动生成摘要记录当天讨论的主要话题、完成的任务、遇到的难题。这是/briefing和/reflect命令的主要数据源。sessions/每天一个JSON Lines文件完整记录了你和Claude的所有对话轮次。这不是为了日常阅读而是为了终极回溯。当你想知道“三个月前的那个周二下午我们到底是怎么解决那个诡异的缓存问题的”时你可以搜索这些会话日志。注意事项sessions/目录下的原始对话日志默认是被.gitignore的因为它们可能包含代码片段、内部信息等体积也增长很快。请定期清理或归档旧会话日志。journal/里的每日摘要更为精炼更适合版本控制。5. 可选扩展搭建Telegram桥接实现移动端对话如果你希望能在手机上也与这个拥有记忆的AI伙伴对话Telegram桥接功能提供了完美的解决方案。它让你在Telegram上的对话也能共享同一套记忆系统。5.1 安全第一创建与配置Telegram Bot绝对不要使用任何非官方客户端或需要你个人Telegram账号Session的库。我们只使用Telegram官方Bot API。在Telegram中搜索并联系BotFather。发送/newbot指令按照提示操作为你的Bot起一个名字如My Memory AI。为其设置一个唯一的用户名必须以bot结尾如my_memory_ai_bot。创建成功后BotFather会给你一个HTTP API Token形如1234567890:ABCdefGhIJKlmNoPQRsTUVwxyZ。妥善保存这个Token它相当于你Bot的密码。5.2 配置桥接服务Claw Kit的Telegram桥接是一个独立的Node.js服务。# 进入桥接服务目录 cd ~/Desktop/claw-kit/telegram-bridge # 复制环境变量示例文件 cp .env.example .env现在用文本编辑器打开新创建的.env文件你需要填写几个关键配置# .env 文件内容 TELEGRAM_BOT_TOKEN你的BotFather给的Token ANTHROPIC_API_KEY你的Anthropic API Key ALLOWED_USER_IDS你的Telegram用户ID MEMORY_PATH../kit/memoryANTHROPIC_API_KEY你需要从 Anthropic控制台 获取一个API Key。注意这个Key是给Telegram桥接服务直接调用Claude API用的与你本地Claude Code使用的认证方式是分开的。Claude Code通常使用桌面客户端的认证方式。ALLOWED_USER_IDS这是一个重要的安全设置。只有在这个列表中的Telegram用户ID才能与你的Bot对话。如何获取你的User ID你可以先给Bot发条消息然后访问这个API链接将YOUR_BOT_TOKEN替换掉https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates。在返回的JSON中找到message.from.id字段那个数字就是你的User ID。MEMORY_PATH指向你之前创建的kit/memory目录的路径确保桥接服务能读到同一个记忆库。5.3 启动与使用安装依赖并启动服务npm install npm run dev如果一切正常服务会启动并提示“Bot is running...”。现在回到Telegram找到你的Bot用户名是my_memory_ai_bot发送/start。你会收到欢迎信息。现在你可以像在Claude Code里一样与它对话了尝试问它“/status”它应该能回复出和你电脑上Claude Code一样的信息因为它读取的是同一套记忆文件。桥接功能亮点上下文记忆在Telegram里的对话也会被记录到sessions/中并且能利用所有记忆进行搜索。智能群聊你可以将Bot拉入群组。通过在identity.md中设定规则如“只在被时回复”或“只在讨论技术问题时发言”Bot可以智能地选择何时介入避免刷屏。相同命令集支持/status,/remember,/forget,/help等命令体验一致。我的实操心得将Telegram Bot用于碎片化信息收集特别有效。当我通勤时突然想到一个点子或者看到一篇好文章我会立刻发给Bot说“/remember 这篇文章提到用SST进行服务器less部署好像成本更低值得研究”。这条记忆就被同步到了中央记忆库等我回到电脑前打开Claude Code时它已经知道这个想法了。这真正实现了跨设备的记忆同步。6. 高级维护、故障排查与个性化定制系统运行一段时间后你可能会遇到一些常见问题或者想要进行深度定制。以下是来自实战的经验总结。6.1 记忆索引的维护与重建搜索变慢或结果不准确可能是索引需要优化或重建。手动重建索引如果你直接修改了Markdown源文件而不是通过Claude或者索引文件似乎损坏了你需要重建索引。通常Claw Kit会提供一个命令行工具例如# 假设在项目根目录有 rebuild-index 脚本 ./scripts/rebuild-index.sh或者根据项目文档你可能需要运行特定的Node脚本。重建过程会重新解析所有Markdown文件分割文本块并更新SQLite索引。索引性能随着记忆文件增多超过数百个BM25搜索仍然会很快但如果你发现Claude响应变慢可以检查单个Markdown文件是否过大考虑将大型文件如冗长的项目日志按时间或主题拆分。搜索索引文件.search.db的大小。它应该远小于所有Markdown文件的总和。如果异常大重建索引。6.2 常见问题与解决方案问题现象可能原因解决方案Claude Code启动后不识别/status等命令kit/CLAUDE.md文件未被正确加载或路径不对。确保你在claw-kit项目根目录下运行claude命令。检查kit/CLAUDE.md文件是否存在且内容完整。/remember命令执行了但在文件中找不到内容AI分类逻辑与你预期不符或文件写入权限问题。1. 检查kit/memory/下各子目录decisions/,learnings/等是否有新文件。2. 查看Claude的回复它通常会告诉你存到了哪个文件。3. 检查目录的写入权限。Telegram Bot无响应Bot Token错误、API Key无效、服务未运行或网络问题。1. 确认npm run dev服务正在运行且无报错。2. 核对.env文件中的TELEGRAM_BOT_TOKEN和ANTHROPIC_API_KEY。3. 检查ALLOWED_USER_IDS是否包含你的ID。4. 查看服务日志输出。搜索功能找不到已知的记忆索引未更新或记忆内容表述与搜索查询差异太大。1. 尝试手动重建索引。2. 在搜索时尝试使用记忆内容中的关键术语而非口语化表述。BM25对关键词匹配更有效。记忆文件冲突使用Git时多人协作或在不同机器上修改了同一记忆文件。这是使用Git管理记忆文件的优势也是挑战。建议1. 将journal/,sessions/,people/,projects/,decisions/等频繁变化的个人目录加入.gitignore。2. 只将模板文件identity.md,user.md和核心知识文件long-term.md,preferences.md,learnings.md纳入版本控制并谨慎处理合并冲突。6.3 深度个性化定制定制身份模板examples/目录下的模板只是起点。你可以创建多个identity-xxx.md文件根据不同的项目或工作场景切换。例如在处理遗留代码项目时切换到一个更耐心、更注重风险规避的身份在进行绿色field开发时切换到一个更激进、喜欢尝试新技术的身份。只需替换kit/memory/identity.md的链接或内容即可。扩展记忆类型现有的记忆分类人物、项目、决策等可能不够用。你可以通过修改kit/CLAUDE.md中的提示词教导Claude识别新的记忆类别并将其存储到你自己定义的新目录或文件中。例如你可以增加一个bookmarks/目录来保存有趣的技术文章链接和摘要。集成其他工具由于记忆的本质是Markdown文件你可以轻松地用其他脚本工具处理它们。例如写一个Python脚本定期分析learnings.md生成一个“常见错误”报告或者用静态站点生成器将projects/目录下的文件渲染成一个内部项目维基页面。最后一点体会使用Claw Kit最大的转变是我不再把Claude Code看作一个问答机器而是将其视为一个正在被共同培养的“数字大脑”。它的记忆是我工作和思考习惯的映射。定期运行/reflect进行回顾就像是对这个大脑进行“碎片整理”和“知识提炼”。这个过程本身也促使我更好地总结和结构化自己的经验。这个系统的价值一半在于其提供的功能另一半在于它鼓励并赋能了一种更有条理、更具累积性的知识工作方式。