Relic：基于纯文本的AI记忆系统，实现跨平台智能助手身份同步

1. 项目概述：为你的AI助手打造一个跨平台的“灵魂芯片”

如果你和我一样，日常开发、写作、学习会同时用到多个AI工具——比如在OpenClaw里讨论架构，在Cursor里写代码，在Claude里润色文档——那你一定也经历过这种割裂感。每个工具里的AI助手都像一张白纸，你得一遍遍重复自己的背景、习惯、项目细节。上周在A里定好的命名规范，这周在B里又得重说一遍。这种重复劳动不仅低效，更关键的是，它阻碍了AI真正成为你连贯的、有“记忆”的合作伙伴。

Relic 这个项目，就是为了解决这个痛点而生的。你可以把它理解为一个纯文本、零依赖的“AI灵魂芯片”。它的核心思想非常极客：将AI助手需要了解的关于你的一切——你的个性、偏好、长期记忆、习得的技能、进行中的项目——全部结构化成Markdown文件，存放在本地的一个文件夹里。然后，通过一套简单的协议，让任何能读取文件的AI工具（无论是OpenClaw、Hermes、Claude Code还是Cursor）都能加载这个“灵魂”，从而实现跨工具的、持续的身份与记忆同步。

这就像《赛博朋克2077》里的Relic生物芯片，存储着一个完整的意识，可以插入不同的“义体”（AI工具）中运行。你的AI不再是一个个孤立的会话，而是一个拥有持久化“灵魂”的实体，无论你在哪个平台与它交互，它都记得你是谁，你们之前一起做过什么，以及它应该以何种方式为你服务。对于任何深度使用多个AI工具的开发者、创作者或研究者来说，这都是一项能极大提升工作流连贯性和效率的基础设施。

2. 核心设计理念与架构解析

2.1 为什么是纯文本文件？

在决定为AI构建一个持久化记忆系统时，我们面临几个关键选择：云端数据库、本地SQLite、还是简单的文件？Relic选择了最后者，而且是纯Markdown文本文件。这背后有非常务实的考量：

1. 零依赖与极致可移植性：一个brain/文件夹，里面一堆.md文件，这就是全部。没有需要安装的包，没有需要配置的数据库，没有复杂的运行时环境。你可以用任何文本编辑器查看、编辑，也可以用git进行版本管理。这种极简主义确保了它在任何环境（包括受限的沙箱或离线环境）中都能开箱即用。
2. 对人类和机器同时友好：Markdown是一种“可读的富文本”。AI（大语言模型）能很好地理解和解析它，而作为用户的你，也能轻松阅读和手动修正。这避免了“黑盒”问题——你的AI记忆对你而言是完全透明、可审计的。
3. 规避复杂性与兼容性陷阱：引入数据库意味着需要驱动、连接池、ORM，不同AI工具对Python包或系统库的支持程度不一，极易出现兼容性问题。纯文件系统是所有操作系统和编程语言共同支持的最低公分母，兼容性风险降至最低。
4. 符合AI的“认知”方式：当前的大语言模型本质上是基于文本序列进行预测的。给它们喂食结构良好的文本文件，正是发挥其长处的最佳方式。复杂的二进制或数据库格式反而会增加模型理解数据的负担。

实操心得：在早期原型中，我尝试过用JSON或YAML来存储结构化数据。虽然机器解析更高效，但可读性差，且一旦结构变更，迁移成本高。Markdown在“结构化”（通过标题、列表、代码块）和“非结构化”（自由叙述）之间取得了完美平衡，非常适合存储既有固定字段（如姓名、偏好）又有自由格式内容（如项目经验、记忆片段）的混合数据。

2.2 “灵魂芯片”的文件夹结构设计

Relic的核心是一个名为brain/的目录，其结构经过精心设计，每一类信息都有其归属，共同构成AI的“灵魂”。理解这个结构是有效使用它的关键。

brain/ ├── SOUL.md # AI的灵魂：人格、价值观、核心使命 ├── USER.md # 用户的画像：习惯、偏好、沟通风格 ├── MEMORY.md # 结构化长期记忆（提取的知识，非原始聊天记录） ├── SKILLS/ # 可复用的技能与工作流 │ ├── git-workflow.md │ ├── code-review.md │ └── ... ├── PROJECTS/ # 进行中或已完成的项目文档 │ ├── project-alpha.md │ └── ... ├── SESSIONS/ # 完整的原始对话转录（永久保存） │ └── 2024-05-27-openclaw-session.md └── ARCHIVE/ # 当文件过长时，归档的记忆（原文件永不删除）

各文件核心职责解析：

• SOUL.md：这是AI的“人格内核”。它定义了AI助手应该以什么样的身份、口吻和原则与你互动。例如，它可以被设定为“一位严谨但富有创造力的资深全栈工程师助手”，其价值观是“优先考虑代码可维护性，积极提出替代方案，但最终尊重用户决策”。这个文件确保了AI在不同工具中行为的一致性。
• USER.md：这是关于你的“用户手册”。它包含你的技术栈偏好（如“喜欢用TypeScript而非JavaScript”）、沟通风格（如“喜欢直接给出代码示例，减少理论阐述”）、工作习惯（如“习惯在下午进行深度编码，上午处理沟通和规划”）等。这帮助AI快速适应你，而不是让你去适应它。
• MEMORY.md：这是最重要的创新点之一。它存储的不是聊天记录的堆砌，而是从对话中提取、结构化后的知识。例如，从一次关于项目架构的讨论中，AI可能会提取并记录：“用户决定在project-alpha中采用微服务架构，并选定使用gRPC作为服务间通信协议。” 这是一个“事实”或“决策”，而不是“那天我们聊了三个小时微服务”。这种设计使得记忆文件不会无限膨胀，且检索效率极高。
• SKILLS/：当AI学会了一个有效的工作流（例如，一套标准的Git提交信息规范，或一个特定的代码重构步骤），它可以被总结成一个技能文件。当下次遇到类似任务时，AI可以直接调用这个“技能”，确保执行过程的一致性和高质量。
• PROJECTS/：为每个重要项目创建一个文档，记录其背景、目标、关键决策、当前状态和待办事项。这为AI提供了上下文，使其在协助特定项目时能立刻进入状态。
• SESSIONS/：原始对话的完整备份。虽然MEMORY.md存储了精华，但原始对话包含了完整的推理过程和可能被忽略的细节。永久保存这些文件提供了数据溯源的能力，也是训练更个性化模型的潜在数据源。

2.3 双向同步与“锚定”机制

Relic不是一个单向的配置文件。它的核心目标是实现双向同步。这意味着：

1. 初始注入：当你第一次在一个AI工具中设置Relic时，AI会读取现有文件，并基于当前对话，将其对你的了解“注入”到相应的文件中（例如，更新USER.md，在MEMORY.md中添加新条目）。
2. 持续同步：在后续会话中，AI不仅会读取brain/中的内容来获取上下文，还会在对话结束时，自动将本次会话中有价值的新信息（新的决策、学到的技能、项目进展）写回文件。
3. 跨工具同步：当你在工具A中更新了项目状态，下次你在工具B中打开同一项目时，AI已经知晓了最新进展。

为了实现稳健的同步，Relic协议包含一个简单的“锚定”机制。AI在每次会话开始时会检查一个“锚点”（例如，MEMORY.md中的最后一条记录ID或一个哈希值）。如果发现本地记忆与文件中的记忆存在差异或断层，它会主动进行合并或请求用户澄清，从而避免记忆冲突或丢失。

注意事项：双向同步的挑战在于冲突处理。Relic的策略是保守的：核心文件（SOUL.md,USER.md）受保护，AI不能删除核心字段；MEMORY.md采用“只追加”模式，不编辑旧条目。这类似于Git的日志思想，通过新增记录来更新状态，最大程度保留了历史。对于PROJECTS.md等文件的编辑，则依赖AI的谨慎判断和清晰的用户指令。

3. 从零开始：详细部署与配置指南

3.1 环境准备与项目获取

Relic的部署简单到令人发指，因为它没有任何外部依赖。你只需要一个能运行AI工具（如OpenClaw, Cursor）的计算机，以及一个存放文件的地方。

第一步：获取Relic文件

你有两种主要方式：

1. 使用Git（推荐，便于更新）： 打开你的终端（Terminal, Cmd, 或 PowerShell），执行以下命令。这将把项目克隆到你的用户主目录下的relic文件夹中。

   git clone https://github.com/LucioLiu/relic.git ~/relic

   选择主目录（~）是因为它路径简单、稳定，且通常在所有AI工具的访问权限内。切勿放在下载或桌面这类临时或可能被系统清理的目录。

2. 直接下载ZIP包： 如果你不熟悉Git，可以直接访问项目的GitHub页面，点击“Code”按钮，选择“Download ZIP”。下载后，解压ZIP文件，将得到的relic-main文件夹重命名为relic，并移动到你的用户主目录或其他你确定的永久性位置。

验证：完成后，你的目录结构应该类似于~/relic/，里面包含README.md,AGENT.md,brain/等文件夹。

3.2 灵魂初始化：让AI为你构建初始档案

这是最关键也最有趣的一步：你不是手动去填写那些Markdown文件，而是让你最了解你的那个AI助手来帮你完成初始化。这通常是你使用时间最长、对话历史最丰富的那个工具（比如OpenClaw）。

1. 启动你的“主”AI工具：打开你常用的AI助手。

2. 下达初始化指令：在与AI的对话框中，输入以下精确指令：

   “请阅读~/relic/AGENT.md文件中的协议，并将你所了解的关于我的一切信息导入到Relic系统中。”

   关键点解析：这条指令做了两件事：第一，让AI去阅读AGENT.md。这个文件是写给AI看的“说明书”，详细解释了Relic是什么、文件夹结构、以及如何操作文件。第二，“导入你所了解的一切”是一个高级指令，AI会根据协议，主动分析它与你的历史对话，提取人格特征、用户偏好、关键记忆等，并结构化地写入到brain/目录下的对应文件中。

3. 跟随AI的引导：AI在阅读协议后，会开始与你交互。它可能会问你一些问题来澄清细节，例如：“我将你设定为‘软件开发者’，这准确吗？还是你有更喜欢的称呼？”或者“我注意到你经常要求代码有详细的注释，需要我将这一点作为固定偏好记录在USER.md中吗？”。请耐心配合回答，这直接决定了初始档案的质量。

4. 等待完成：整个过程可能需要几分钟，AI会依次创建或更新SOUL.md、USER.md、MEMORY.md等文件。务必等待AI明确告知初始化已完成，再进行下一步。

手动检查：初始化后，你可以用文本编辑器打开~/relic/brain/下的文件，看看AI为你生成了什么。你会看到它已经为你创建了一个相当丰富的个人档案。

3.3 连接其他AI工具：实现灵魂注入

一旦你的“灵魂”在主AI工具中初始化完毕，就可以将其“注入”到其他AI工具中了。这个过程是幂等的，也就是说，对每个新工具的操作流程几乎一样。

1. 打开一个新的AI工具：比如，你现在想配置Cursor。

2. 下达连接指令：在新工具的对话窗口中，输入：

   “请阅读~/relic/AGENT.md文件，并为我设置Relic。”

3. 理解AI的智能判断：此时，AI会读取AGENT.md协议，并检查brain/目录。它会发现目录中已有数据（非空），于是它会自动进入“注入”模式：

   • 读取灵魂：加载SOUL.md和USER.md，理解它应该扮演的角色和服务的对象。
   • 同步记忆：读取MEMORY.md和相关的PROJECTS/文件，获取历史上下文。
   • 锚定会话：在本次对话中建立一个与现有记忆的链接。

4. 验证连接：连接完成后，进行一个快速验证。询问AI：“我的AI叫什么名字？我又是谁？” 它应该能准确回答出SOUL.md中定义的AI名称和USER.md中关于你的关键信息。如果回答正确，说明“灵魂注入”成功。

重复此过程：对每一个你想集成的AI工具（Hermes, Claude Code, Aider等）都执行一遍步骤2-4。

3.4 与特定AI工具的集成细节

虽然核心协议是通用的，但不同AI工具有不同的启动方式和上下文加载机制。Relic在examples/integrations/目录下提供了一些具体指引：

• 对于OpenClaw/Hermes等具有较强自主性的Agent：它们通常能很好地理解并执行AGENT.md中的复杂协议。你只需直接给出上述指令即可。
• 对于Claude Code, Cursor, Aider等代码助手/编辑器插件：它们可能更专注于当前项目或文件。你可以参考generic.md的示例，创建一个项目级的启动脚本或提示词片段。例如，在Cursor中，你可以配置一个“项目上下文”，使其在启动时自动读取brain/目录下的特定文件。

  实操技巧：对于这类工具，一个有效的方法是创建一个名为.cursor/rules/relic.md的规则文件（Cursor的特性），内容为“在每次会话开始时，优先阅读../../relic/brain/SOUL.md和../../relic/brain/USER.md以了解用户背景”。这样就能实现半自动化的上下文加载。

下表总结了不同工具的连接思路：

4. 高级使用技巧与日常维护

4.1 如何让记忆（MEMORY.md）更有效地工作？

MEMORY.md是Relic的智慧核心，但它的效果取决于AI如何提取和记录记忆。以下是一些提升记忆质量的心得：

• 明确指令引导提取：在重要的对话结束时，可以主动告诉AI：“请将我们刚才关于[某个主题]讨论的核心结论，作为一条结构化记忆记录到MEMORY.md中。” 这能训练AI更好地识别关键信息。
• 记忆的结构化格式：Relic协议建议记忆条目包含timestamp（时间戳）、tags（标签，如 #project-alpha #architecture #decision）、summary（摘要）和context（详细上下文）。你可以检查AI生成的条目是否符合这个格式，并手动调整以作为示范。
• 定期回顾与清理：虽然MEMORY.md是追加的，但你可以定期打开它，删除一些过时或不再相关的条目（直接编辑文件即可）。或者，利用ARCHIVE/机制：当文件变得太大时，可以指示AI将较旧的记忆移动到ARCHIVE/下的一个带日期标记的新文件中，并在MEMORY.md开头留下一个索引链接。

4.2 技能（SKILLS/）库的积累与复用

技能库是你和AI共同构建的效率工具箱。一个高质量的技能文件应该像一段可复用的代码或一个清晰的食谱。

• 技能创建时机：当你发现某个复杂任务被重复执行，且已经摸索出一套稳定高效的步骤时，就是创建技能的时候。例如：“如何为我的Python项目配置一套完整的CI/CD（使用GitHub Actions）”。
• 技能文件模板：一个技能文件通常包括：
  1. 技能名称：清晰的任务描述。
  2. 触发条件：什么情况下应该使用这个技能？
  3. 前置条件：需要准备什么？
  4. 步骤：分步、详细的执行步骤。最好包含示例代码或命令。
  5. 预期结果：成功执行后应该是什么样子？
  6. 常见问题：可能遇到的错误及解决方法。
• 技能的调用：当你需要执行相关任务时，只需对AI说：“请参考我们SKILLS/目录下的ci-cd-python-github.md技能来完成这个任务的自动化部署部分。” AI就会去读取那个文件并遵循其中的步骤。

4.3 项目管理（PROJECTS/）的深度集成

将Relic深度融入你的项目管理，可以创造无缝的上下文切换体验。

1. 为每个项目创建文件：在brain/PROJECTS/下为每个重要项目创建一个项目名.md文件。
2. 文件内容动态更新：这个文件不应是静态的。每次项目会议、重大决策、进度更新后，都指示AI：“请将本次讨论的要点更新到PROJECTS/project-alpha.md中。” AI会帮你维护一个动态的、最新的项目日志。
3. 跨工具上下文继承：当你在工具A中与AI讨论project-alpha并更新了其项目文件后，下次你在工具B中打开该项目时，AI在加载Relic后能立即获取最新状态，你可以直接问：“我们上次在project-alpha上遇到的数据库性能问题，有什么新进展吗？” 它能基于记忆给出连贯的回答。

4.4 安全与隐私考量实践

Relic的设计将安全和隐私放在首位，所有数据都在本地。但你仍需注意：

• 敏感信息处理：协议要求AI在记录密码、手机号、密钥等敏感信息前必须询问。但你应在USER.md中明确你的偏好，例如：“永远不要记录任何以key_、password_、secret_开头的变量值或字符串。”
• 文件备份：brain/文件夹是你的数字灵魂。务必将其纳入你的常规备份计划（如使用iCloud Drive, Dropbox，或git私有仓库）。你可以定期将整个relic文件夹压缩备份。
• 选择性同步：如果你需要在不同电脑间同步，可以使用网盘同步brain/文件夹。但请注意，如果你在某台电脑上用了一个“无知”的AI修改了记忆，这个修改会被同步。因此，最好确保所有连接的AI都遵循Relic协议。

5. 故障排除与常见问题实录

即使设计再简洁，在实际使用中也可能遇到问题。以下是我在长期使用中遇到的一些典型情况及解决方法。

5.1 AI无法找到或读取Relic文件

问题现象：AI回复“找不到文件”或“路径不存在”。

排查步骤：

1. 确认绝对路径：你提供给AI的路径（如~/relic）是一个“波浪号”路径，AI可能无法正确解析。尝试使用绝对路径，例如在Mac/Linux上使用/Users/你的用户名/relic，在Windows上使用C:\Users\你的用户名\relic。
2. 检查AI的文件访问权限：某些AI工具（特别是运行在沙箱或受限环境中的）可能无法访问用户主目录以外的路径。尝试将relic文件夹移动到AI工具的“工作区”或“项目”目录下，然后使用相对路径（如./relic/AGENT.md）引用。
3. 验证文件是否存在：在终端中使用ls -la ~/relic/AGENT.md或dir命令，确认文件确实存在于你指定的位置。

5.2 记忆不同步或冲突

问题现象：在工具A中记录的记忆，在工具B中看不到，或者AI提到了矛盾的信息。

排查步骤：

1. 检查文件写入权限：确保AI工具有权限向brain/目录下的文件写入内容。有时可能是文件被设置为只读，或者文件夹权限不足。
2. 手动触发同步：在工具B中，明确指示AI：“请重新扫描并同步MEMORY.md和PROJECTS/目录下的所有最新内容。” 这可以强制AI重新读取所有文件。
3. 查看原始会话文件：检查SESSIONS/目录下最近的两个工具会话记录，看它们分别向MEMORY.md写入了什么。如果发现冲突（例如对同一事实有不同记录），可以手动编辑MEMORY.md，保留正确版本，并添加一条说明性记录。
4. 理解“最终一致性”：Relic不是实时数据库，它追求的是“最终一致性”。在一个工具中更新后，需要AI完成写入操作，另一个工具在下次读取时才能看到。确保你给了AI足够的时间完成文件写入操作。

5.3 AI行为不符合SOUL.md中的设定

问题现象：AI的表现不像SOUL.md中定义的那个“人格”，或者忘记了USER.md中的偏好。

排查步骤：

1. 验证加载：直接询问AI：“你当前加载的SOUL文件中，你的名字和使命是什么？” 让它复述出来，看是否正确。
2. 检查文件内容：打开SOUL.md，看人格设定是否足够具体、无歧义。模糊的指令如“做一个有帮助的AI”效果不佳。应使用具体、可操作的描述，如“你是一名以简洁、准确著称的软件工程顾问，在给出方案时总会同时考虑时间复杂度和可维护性。”
3. 上下文长度限制：所有AI工具都有上下文窗口限制。如果brain/下的文件总大小超过了这个限制，AI可能无法加载全部内容。此时，需要优化：
   • 优先确保SOUL.md和USER.md被加载。
   • 对于MEMORY.md，可以指示AI：“只加载最近30天的记忆条目，或只加载带有#project-alpha标签的记忆。”
   • 将古老的记忆文件手动移至ARCHIVE/。

5.4 性能问题：启动变慢或响应迟缓

问题现象：AI在加载Relic后，开始响应的时间变长。

原因与解决：这是因为AI需要在每次会话开始时，读取并处理大量的文本文件。随着MEMORY.md和SESSIONS/的增长，这个问题会加剧。

• 定期归档：制定一个规则，比如每月一次，将MEMORY.md中两个月前的条目移动到ARCHIVE/memory-2024-04.md中，并在原文件顶部保留一个链接。
• 会话文件管理：SESSIONS/文件夹会快速增长。可以按季度或项目创建子文件夹进行归档，或者只保留最近3个月的详细会话，更早的可以压缩存储。
• 选择性加载：如前所述，通过给AI更精确的指令，让它只加载当前任务相关的记忆和项目文件。

5.5 技能文件在不同工具间不通用

问题描述：在OpenClaw中创建的“部署到AWS”技能，在Cursor中无法直接运行，因为涉及的具体命令或界面操作不同。

解决方案：这是预期内的限制。Relic同步的是技能的“描述”和“逻辑”，而不是平台特定的代码。

1. 抽象技能描述：在编写技能时，尽量描述做什么和为什么，而不是具体用什么按钮。例如，技能应该是“实现一个蓝绿部署流程，以最小化停机时间”，而不是“在AWS控制台点击EC2 -> Launch Templates -> ...”。
2. 提供多平台示例：在技能文件中，可以包含多个章节，例如“## 在OpenClaw (CLI环境) 中的实现”和“## 在Cursor (本地IDE) 中的实现”。
3. AI的适配能力：当你要求AI在另一个工具中运用某个技能时，它应该能根据技能的逻辑描述，结合新工具的环境，生成适配的具体操作步骤。这考验的是AI的理解和迁移能力，也是Relic价值的一部分——它保存了核心知识，让AI能在不同场景下复用。