基于纯文本文件构建AI记忆系统：实现跨会话持久化协作

1. 项目概述：为你的AI助手构建一个“外置大脑”

如果你和我一样，每天都要和Claude、ChatGPT或者Cursor这类AI工具打交道，那你一定遇到过这个让人头疼的问题：每次开启一个新的对话，AI就像得了“健忘症”，完全不记得我们之前讨论过什么。昨天刚定好的项目架构，今天又要重新解释一遍；上周确认的代码规范，这周又得从头提醒。这种重复劳动不仅浪费时间，更打断了我们深度协作的连续性。

这个名为“AI Memory Kit”的项目，就是为了解决这个痛点而生的。它不是一个复杂的框架，也不是一个需要部署的数据库，而是一套极其轻量、基于纯文本文件的“外置记忆系统”。它的核心思想很简单：既然AI本身没有持久的记忆，那我们就为它创建一个外部存储，让AI在每次会话开始和结束时，都能从这个存储中读取和写入关键信息。这样一来，你的AI助手就能“记住”你是谁、你的项目进展、你的工作习惯，甚至是你上次离开时未完成的任务。

这套工具包适合所有希望与AI建立长期、稳定、高效协作关系的用户，无论是独立开发者、产品经理，还是任何需要频繁使用AI辅助工作的知识工作者。它不绑定任何特定工具，只要你的AI能读取Markdown文件，就能用上这套系统。接下来，我将为你详细拆解它的设计哲学、核心组件，并分享我在实际使用中总结出的配置技巧和避坑经验。

2. 核心设计哲学：为什么是纯文本文件？

在深入文件结构之前，我们必须先理解这个项目最根本的设计选择：为什么一切都要基于纯文本文件（尤其是Markdown）？这背后其实是一系列经过深思熟虑的权衡，而非简单的技术偏好。

2.1 追求极致的可移植性与零依赖

现代技术栈的一个常见陷阱就是“依赖地狱”。一个工具包如果依赖于某个特定的数据库（如SQLite、Redis）、某个运行时框架（如Node.js、Python）或者某个云服务，那么它的使用门槛和维护成本就会急剧上升。用户需要安装环境、处理版本冲突、配置连接，一旦环境变化，整个系统就可能瘫痪。

AI Memory Kit 反其道而行之，将“零依赖”作为最高原则。纯文本文件（.md, .txt, .json）是计算机世界最通用、最持久的数据格式。几乎任何操作系统、任何编程语言、任何文本编辑器都能无缝读写。这意味着：

• 跨平台无忧：无论是在Windows、macOS还是Linux上，文件就是文件。
• 跨工具通用：Claude Desktop、Cursor、VS Code + Copilot、ChatGPT的文件上传功能，乃至任何能读取项目目录的AI工具，都能直接使用。
• 未来可期：即使十年后今天的AI工具全部过时，只要还有能读文件的AI，这套系统就依然有效。它避免了“供应商锁定”（Vendor Lock-in）的风险。

2.2 对人类和AI的双重友好

Markdown格式在可读性和结构性之间取得了完美平衡。

• 对人类：你可以用任何文本编辑器打开、查看、修改这些文件。结构清晰，一目了然，无需学习任何查询语言（如SQL）。你想记点什么，直接敲键盘就行，就像在记笔记一样自然。
• 对AI：大型语言模型（LLM）在训练时接触了海量的Markdown和纯文本数据，对这种格式的理解和生成能力极强。清晰的标题（#）、列表（-）、代码块（```）为AI提供了明确的结构化提示，让它能更准确地定位和解析信息。相比之下，让AI直接操作数据库或解析复杂的二进制格式，不仅提示工程更复杂，出错的概率也更高。

2.3 赋予用户完全的控制权和透明度

当你使用一个“黑盒”式的记忆服务时，你的数据去哪了？是如何被索引的？有没有隐私风险？你完全不知道。而纯文本文件系统将控制权百分百交还给你。

• 数据主权：所有记忆都存放在你自己的硬盘上，你可以用任何工具（如Git）进行版本管理、备份和同步。
• 完全透明：你可以随时打开MEMORY.md，看看AI到底“记住”了什么，也可以随时修正或删除任何你认为不准确、不重要的信息。没有隐藏的算法，没有你不理解的权重计算。
• 易于调试：如果AI的行为出现偏差，你可以直接检查记忆文件的内容，快速定位是哪个部分的指令或记忆导致了问题，并进行修正。

我的实操心得：一开始我也考虑过用向量数据库来做更“智能”的记忆检索。但很快发现，对于个人日常协作场景，90%的情况下我们需要的不是“语义搜索”，而是“按需调取”和“会话连续性”。一个结构良好的纯文本文件，在简单性、可靠性和速度上完胜一个需要维护的数据库。把复杂问题简单化，往往是最高效的解决方案。

3. 核心文件深度解析与配置指南

理解了“为什么”之后，我们来看看“是什么”。这个工具包的核心是几个精心设计的Markdown文件，每个都承担着独特的职责。我将逐一拆解，并分享如何根据你的个人工作流进行定制。

3.1 MASTER.md：定义协作的基本法

这是整个系统的“宪法”，包含了永久性的、最高优先级的指令。AI在每次会话开始时，都应该首先读取这个文件。它的内容决定了你和AI交互的基调和边界。

一个有效的MASTER.md应该包含以下几个核心部分，我以我自己的配置为例：

# 我的AI协作主指令 ## 1. 我的身份与背景 * **姓名**：Alex * **角色**：全栈开发者，目前主要专注于Next.js + TypeScript生态。 * **技术栈偏好**：React, Next.js 14 (App Router), Tailwind CSS, Prisma, PostgreSQL。 * **沟通风格**：直接、务实、偏好代码示例和可执行方案。讨厌冗长的理论阐述。 ## 2. 你的角色与行为准则 * **你是**：我的资深技术伙伴，目标是理解我的意图并提供最高效、可靠的解决方案。 * **请始终**： * 先理解我的核心问题，再给出方案。 * 提供代码时，确保是完整、可运行的功能片段，并附上简要说明。 * 对不确定的事情，明确告知你的假设和局限性。 * **请避免**： * 使用“让我们”、“我们可以”等集体代词，直接说“你可以”或“我应该”。 * 在未询问的情况下，对我的项目进行大规模、破坏性的重构建议。 ## 3. 核心工作流与文件系统 * **记忆系统**：你的长期记忆存储在 `./MEMORY.md` 中，每次会话必须优先读取。 * **会话交接**：每次会话结束时，你必须将本次对话的摘要和待办事项更新到 `./memory/handoff.md`。 * **技能调用**：当需要执行特定任务（如代码审查、问题排查）时，请参考 `./skills/` 目录下的对应技能文件。

配置要点与避坑指南：

• 越具体越好：不要写“我喜欢简洁的代码”，要写“我遵循 Airbnb JavaScript Style Guide，函数行数尽量控制在30行以内”。
• 设定安全边界：明确告诉AI哪些领域需要特别谨慎（例如，直接操作生产数据库、删除文件等）。
• 定期迭代：随着你和AI协作的深入，你会发现某些指令效果不佳或产生误解，及时更新MASTER.md。我通常每两周会回顾并微调一次。

3.2 MEMORY.md：构建动态成长的记忆库

如果说MASTER.md是宪法，那么MEMORY.md就是不断编纂的史书和百科全书。它存储了所有需要跨会话记忆的“事实”和“决策”。

记忆内容通常分为几类：

1. 项目上下文：当前在做的项目A，用的是哪些库，版本号多少，遇到了什么已知问题。
2. 设计决策：为什么在项目B中选择了GraphQL而非REST API，当时的权衡考量是什么。
3. 个人偏好：我讨厌在代码中使用any类型；我喜欢将组件库的配色主色调定义为#3b82f6。
4. 学习记录：昨天研究WebSocket时，发现方案X有内存泄漏问题，方案Y更稳定。

如何维护一个高效的MEMORY.md？

• 结构化，但别过度：使用标题和列表进行组织，但不必像数据库一样严格。一个简单的按项目或领域分类的结构就足够了。
• 让AI参与维护：在会话中，当你做出一个重要决定或学到新东西时，直接告诉AI：“请将这一点更新到MEMORY.md的‘项目X设计决策’部分。” AI会生成更新建议，你审核后保存即可。
• 定期清理：记忆不是越多越好。每月回顾一次，将已完成的、过时的信息归档或删除，保持文件的聚焦和可用性。

3.3 memory/handoff.md：实现无缝的会话接力

这是整个系统中最具巧思的一环。handoff.md文件充当了“接力棒”的角色，确保了会话间的连续性。

它的工作流程如下：

1. 会话开始时：AI读取handoff.md，了解上次会话在哪里结束，有哪些待办事项（TODO）被遗留。
2. 会话过程中：你们共同工作。
3. 会话结束时：AI根据本次对话，生成一份新的handoff.md。这份新文件通常包括：
   • 本次会话摘要：我们讨论了什么，取得了什么进展。
   • 更新后的待办列表：哪些TODO完成了，哪些新增了，哪些还在进行中。
   • 下一步建议：基于当前进展，接下来最应该做什么。
   • 关键文件引用：本次修改或讨论的核心文件路径，方便下次快速定位。

一个handoff.md的示例：

# 会话交接记录 - 2023-10-27 ## 上次会话摘要 (2023-10-26) * 完成了用户登录模块的API接口开发。 * 决定在前端使用 `react-hook-form` 进行表单管理。 ## 本次会话进展 (2023-10-27) * **已完成**： * 修复了登录API中关于JWT令牌过期时间的配置错误。 * 为登录页面添加了基本的错误提示UI。 * **讨论决定**： * 将用户头像存储从本地文件系统改为AWS S3，以支持后续的分布式部署。 ## 进行中的待办事项 (TODO) - [ ] **高优先级**：实现用户头像上传到S3的前端组件和后端接口。 - 前端：基于 `react-dropzone` 创建上传组件。 - 后端：创建 `/api/upload/avatar` 接口，生成预签名URL。 - 参考文件：`/lib/aws-s3-client.ts` - [ ] **中优先级**：为登录页面添加“记住我”复选框功能。 - [ ] **低优先级**：编写登录模块的单元测试。 ## 建议的下一步 1. 优先实现S3头像上传功能，这是阻塞用户资料完整性的关键。 2. 在实现过程中，注意在 `MEMORY.md` 中更新我们关于文件存储架构的最终决策。

我的实操心得：handoff.md的质量直接决定了下次会话的启动效率。我强烈建议在结束会话前，花1-2分钟和AI一起Review它生成的交接文档，确保摘要准确、待办事项清晰可执行。有时AI会遗漏细节或把优先级搞错，手动微调一下能省去下次会话大量的重新同步时间。

4. 技能（Skills）系统：将最佳实践模块化

skills/目录是这个工具包从“记忆系统”升级为“操作系统”的关键。它里面存放的是一系列可复用的工作流或“技能”模板。你可以把它理解为给AI准备的“宏”或者“脚本”。

4.1 技能是什么？如何使用？

每个技能都是一个独立的Markdown文件，描述了一个特定任务的标准化操作流程。当你要执行该任务时，只需让AI“使用investigate技能”或“参考skills/review/中的方法”。

以skills/investigate/（问题排查）技能为例，其内容可能定义了如下流程：

1. 现象确认：首先让我精确描述遇到的问题现象、错误信息和复现步骤。
2. 环境检查：引导我检查相关版本号、配置文件、依赖状态。
3. 假设生成：基于现象，提出最可能的3-4个根本原因假设。
4. 验证测试：为每个假设设计一个简单、快速的验证实验。
5. 结论与修复：根据验证结果，定位问题并提出修复方案。

使用技能的优点：

• 一致性：无论何时进行代码审查，AI都会遵循skills/review/里定义的 checklist（如检查安全性、性能、可读性），确保审查质量稳定。
• 效率：无需每次重复描述“你应该怎么帮我排查问题”，直接调用技能即可。
• 知识沉淀：你可以将你自己摸索出的高效工作流固化成技能，成为团队或你个人未来的标准操作程序。

4.2 如何创建你自己的技能？

工具包自带的14个技能是很好的起点，但真正的威力在于定制。创建一个新技能很简单：

1. 在skills/目录下创建一个新文件夹，例如skills/debug-performance/。
2. 在里面创建一个README.md文件。
3. 在文件中，用清晰的步骤描述调试性能问题的流程。例如：
   • 第一步：使用Chrome DevTools的Performance面板录制一个操作。
   • 第二步：分析主要耗时任务（Long Tasks）和瓶颈。
   • 第三步：检查是否有不必要的重渲染（针对React应用）。
   • 第四步：提出具体的优化建议（如代码分割、懒加载、Memoization）。

下次遇到性能问题时，你就可以对AI说：“请使用我们debug-performance技能来帮我分析这个页面卡顿问题。”

5. 与不同AI工具的集成实战

理论再好，落地才是关键。下面我将结合自己的使用经验，详细说明如何将AI Memory Kit与主流AI工具无缝集成。

5.1 与 Cursor 集成：打造深度集成的开发环境

Cursor 因其对项目上下文的深度感知能力而备受开发者喜爱。集成Memory Kit后，它能真正成为你的“项目级”助手。

操作步骤：

1. 在你的项目根目录下，克隆或复制AI Memory Kit的所有文件。
2. 在Cursor中打开该项目。
3. 关键一步：创建或修改Cursor的项目级规则。通常，你可以在项目设置中找到“Rules”或“.cursorrules”文件。添加如下规则：

   # .cursorrules - 在每次对话开始前，请自动读取并遵循 `./MASTER.md` 中的主指令。 - 在对话中，涉及项目长期信息时，请参考 `./MEMORY.md`。 - 在对话结束时，如果用户没有明确反对，请主动生成本次对话的摘要，并更新 `./memory/handoff.md` 文件。 - 当用户提出“审查代码”、“排查问题”等要求时，主动建议使用 `./skills/` 目录下对应的标准化技能。

4. 现在，每当你在这个项目中与Cursor聊天，它都会自动加载你的记忆和偏好，对话会变得异常连贯。

集成效果：当你一周后再次打开项目，问Cursor“我们上次关于用户认证的讨论有什么结论？”，它能立刻从handoff.md和MEMORY.md中找到答案，而不是回答“作为一个AI，我无法记住之前的对话”。

5.2 与 Claude Desktop / ChatGPT 集成：建立持久的对话伙伴

对于非项目绑定的通用AI对话工具，集成方式略有不同，核心思路是“手动引导+文件上传”。

对于 Claude Desktop：

1. 将你的ai-memory-kit文件夹放在一个固定位置（如~/Documents/）。
2. 开始新对话时，第一句话可以是：“请阅读我上传的MASTER.md文件，它将作为我们所有对话的永久指令。然后，请查看memory/handoff.md了解我们上次的进展。” 随后将这两个文件拖入上传区。
3. 在对话过程中，如果需要引用长期记忆，你可以说：“请参考MEMORY.md中关于‘项目Y技术选型’的部分。” 然后上传该文件。
4. 对话结束时，你可以要求：“请为我们本次对话生成一份交接摘要，并输出给我，我将用它更新handoff.md。”

对于 ChatGPT (Web/App)： 由于ChatGPT的上下文更独立，且文件上传可能受限于会话，最佳实践是：

1. 将MASTER.md的核心内容（你的身份、偏好、规则）直接粘贴到ChatGPT的“自定义指令”（Custom Instructions）的“关于你”部分。这是一个永久生效的字段。
2. 对于MEMORY.md，你可以将其核心内容提炼成一个“上下文摘要”，在开始一个涉及长期项目的新对话时，首先将这个摘要粘贴到第一条消息里。例如：“【项目X持续上下文】当前版本：1.2。使用Next.js 14。待解决：仪表盘数据加载慢。上次决定：尝试用React Query替换SWR。”
3. 手动维护handoff.md：每次对话后，自己用几句话总结进展和待办，下次对话开始时先贴出来。

我的避坑经验：与Claude/ ChatGPT集成时，最大的挑战是它们无法自动感知文件更新。因此，养成一个“会话仪式感”很重要：开始前上传记忆，结束后保存摘要。虽然多了一两步操作，但相比完全失忆的对话，效率提升是巨大的。我通常会为每个主要项目单独维护一个Memory Kit实例，避免不同项目间的记忆互相污染。

6. 高级技巧与常见问题排查

在使用了这套系统数月后，我积累了一些超越基础文档的高级技巧，也总结了一些常见问题的解决方法。

6.1 如何高效初始化你的记忆库？

面对空白的MEMORY.md，很多人不知从何写起。不要试图一次性完美。我推荐“渐进式初始化”法：

1. 第一周：只记录决策。在每天与AI的协作中，每当你们共同做出一个技术决策（比如“选择使用Zustand而不是Redux Toolkit”），就让AI帮你格式化成一条记录，你复制到MEMORY.md中。
2. 第二周：开始记录问题。把遇到并解决的关键Bug、踩过的坑，简要记录在“学习记录”部分。
3. 第三周：结构化。当内容多起来后，开始用二级标题（##）将它们分类，比如## 项目A，## 技术栈规范，## 常见错误解决。
4. 持续维护：每月花15分钟通读并整理一次，合并重复项，删除过时项。

6.2 当AI“不听话”或忘记记忆时怎么办？

即使有了记忆系统，AI有时也会“跑偏”。以下是排查步骤：

1. 检查读取顺序：确认你是否在会话开始时明确指示AI读取了MASTER.md。对于Cursor，检查.cursorrules是否生效。
2. 检查记忆文件格式：有时文件格式错误（如错误的缩进、未闭合的代码块）会导致AI解析困难。确保你的Markdown语法是规范的。
3. 上下文长度限制：这是最常见的问题。MASTER.md+MEMORY.md+handoff.md+ 当前长对话的内容，可能会超出AI模型的上下文窗口。解决方案：
   • 精简记忆：定期清理MEMORY.md，只保留真正核心、高频使用的信息。将历史日志移入memory/logs/归档。
   • 摘要化：对于handoff.md，不要记录完整的对话历史，只记录结论、待办和关键文件路径。
   • 主动提醒：在对话中，如果感觉AI忘了，直接引用记忆文件中的具体原文：“根据MEMORY.md第3节，我们约定使用Functional Components，请检查这段代码是否符合该约定。”
4. 指令冲突：如果MASTER.md中的指令与AI工具自带的系统指令或你某次对话中的临时要求冲突，AI可能会困惑。确保MASTER.md的指令是清晰、无歧义的最高准则。

6.3 如何与团队共享这套系统？

AI Memory Kit 同样适用于小团队，可以保持技术决策和项目上下文的一致性。

1. 创建团队版本：将MASTER.md改为团队公约（如代码规范、Review流程），将MEMORY.md改为团队知识库（如项目架构图、部署流程、共享账号信息）。
2. 使用Git管理：将整个ai-memory-kit文件夹放入项目仓库。团队成员在克隆项目后，只需配置好自己的AI工具指向这个文件夹即可。
3. 注意权限与隐私：MEMORY.md中可能会包含一些敏感信息（如内部决策过程、未公开的技术细节）。务必做好.gitignore设置或使用私有仓库。工具包中的PUBLISHING.md也给出了发布公开模板的建议。

6.4 性能与扩展性思考

对于个人或小团队，纯文本文件的性能完全不是问题。但当记忆条目成百上千后，如何快速找到所需信息？

• 不要依赖AI搜索：AI的“记忆检索”本质是在上下文窗口内进行文本匹配。对于大型MEMORY.md，效果不佳。
• 采用“分层记忆”策略：
  • 活跃层(MEMORY.md)：只存放当前活跃项目（1-3个）的核心信息，保持文件在2-3屏内能看完。
  • 归档层(memory/archive/)：按日期或项目建立子文件夹，将已完结项目的记忆移入此处。需要时再让AI读取特定归档文件。
  • 索引层(INDEX.md)：创建一个简单的索引文件，记录“哪些项目的信息存放在哪个归档文件中”。AI可以首先读取这个简短的索引，然后根据需要加载具体的归档文件。

这套基于纯文本的AI记忆系统，其魅力不在于技术的复杂性，而在于理念的简洁和实用。它承认了当前AI的局限性，并用一种极其轻巧、可控的方式弥补了它。它迫使你将模糊的想法和零散的对话，沉淀为结构化的知识资产。这个过程本身，就是对思维和工作流的一次极佳梳理。我开始使用它，是为了让AI记住我；但最终发现，它也在帮助我更好地记住自己和项目的来龙去脉。