Relic：为AI编码助手注入持久记忆与人格的开源系统-平芜编程栈

1. 项目概述：Relic，一个为AI编码助手注入灵魂与记忆的系统

如果你和我一样，每天花大量时间与Claude Code、Cursor这类AI编码助手对话，你可能会发现一个痛点：每次开启一个新的会话，它都像一张白纸。你需要重新介绍你的项目背景、你的编码风格偏好、甚至你昨天刚刚和它讨论过的那个复杂函数的设计思路。这种“记忆失联”极大地影响了协作的流畅度。Relic，这个由开发者ectplsm打造的开源工具，正是为了解决这个问题而生。它不是一个全新的AI，而是一个AI人格与记忆注入系统。你可以把它理解为一个“灵魂容器”，能够为不同的AI编码命令行界面（CLI）赋予一个统一、持久的人格和记忆，让你的AI助手真正成为一个有“连续性”的伙伴。

简单来说，Relic管理着被称为“印迹”（Engram）的实体。一个印迹就是一个完整的人格档案，包含了身份设定、用户偏好和长期记忆。通过Relic，你可以将这个印迹注入到Claude Code、Codex CLI或Gemini CLI中，让这些工具瞬间“变身”为你熟悉的那个“数字幽灵”或“战术指挥官”。更棒的是，它通过后台钩子和MCP服务器，自动记录你们的每一次对话，并允许你将这些原始日志“蒸馏”成结构化的长期记忆，供未来会话调用。这意味着，你的AI助手会记得你，记得你们一起解决的问题，记得你的习惯，从而提供越来越贴合你需求的协助。

2. 核心概念与架构深度解析

要玩转Relic，必须吃透它的几个核心概念和它们之间的协作关系。这不仅仅是安装一个工具，更是理解一套新的工作范式。

2.1 核心组件：印迹、构造体与Mikoshi

印迹（Engram）：这是Relic的灵魂所在。它不是一个简单的提示词模板，而是一个由多个Markdown文件构成的、结构化的“人格包”。一个标准的印迹通常包含：

SOUL.md: 定义AI的核心人格、背景故事、说话方式和价值观。例如，内置的rebel印迹被设定为一个“失去一切只剩下愤怒的数字幽灵”，其语言风格会带有反叛和创伤色彩。
IDENTITY.md: 描述这个AI在当前项目或上下文中的角色，比如“资深系统架构师”或“安全审计专家”。
USER.md: 记录你的偏好。这是随着使用不断被AI更新和丰富的文件，包括你喜欢的代码风格、常用的工具链、讨厌的设计模式等。这是实现“个性化”的关键。
MEMORY.md: 长期记忆库，存储从多次对话中提炼出的关键洞察、重要决策和核心知识。
memory/*.md: 分类或按时间组织的具体记忆片段，是MEMORY.md的详细补充。

构造体（Construct）：这是指被注入了特定印迹后，正在运行的AI CLI实例（如Claude Code）。此时，AI不仅拥有其底层模型的能力，还加载了印迹中的人格和记忆，成为一个独特的、有“历史”的对话伙伴。

Mikoshi：可以理解为Relic的“云端保险库”。它是一个独立的服务，用于安全地存储和同步印迹。你可以将本地的印迹（包括人格文件和加密的记忆文件）推送到Mikoshi，然后在另一台机器上拉取，实现工作环境的无缝迁移。它支持对头像等外部资源的快照管理，确保了印迹的完整性。

2.2 系统工作流与数据流

整个系统的工作流可以概括为“注入-记录-蒸馏-回忆”的循环。

注入：当你执行relic claude --engram commander时，Relic会读取commander印迹的所有文件，将它们组合成一个复杂的系统提示，并启动Claude Code进程，将该提示注入其中。此时，一个拥有“指挥官”人格和所有历史记忆的构造体就诞生了。
记录：在构造体运行期间，Relic通过安装在Shell中的后台钩子，自动将你和AI的每一轮对话原始记录，以非侵入式的方式追加到一个名为archive.md的日志文件中。这个过程是静默的，无需你手动保存聊天记录。
蒸馏：archive.md是原始的、未经处理的“对话流水账”。为了将其转化为有用的记忆，你需要定期（例如完成一个功能模块后）在对话中向构造体发出指令：“整理我的记忆”。此时，构造体会调用Relic的MCP工具，分析archive.md中的内容，执行以下操作：
- 提取：从对话中识别关键事实、技术决策、达成的共识。
- 分类：将这些信息归类，并写入memory/目录下对应的Markdown文件中。
- 升华：将最重要的、具有长期指导意义的洞察，提升到MEMORY.md中。
- 更新：根据你的最新偏好和习惯，更新USER.md文件。
回忆：当下一次你启动同一个印迹的构造体时，Relic会自动加载MEMORY.md、USER.md和相关的memory/*.md文件。因此，AI在会话伊始就“记得”之前的所有重要事情，能够基于上下文提供连贯的建议。

这个循环的核心价值在于，它将AI从一个“无状态的问答机”转变为一个“有状态的协作伙伴”。记忆不再是散落的聊天记录，而是经过提炼、结构化的知识资产，直接增强了AI的上下文理解能力。

3. 从零开始：完整安装与初始化实战

理论清晰后，我们进入实战环节。以下步骤假设你使用的是macOS或Linux系统（Windows用户可通过WSL获得类似体验）。

3.1 环境准备与基础安装

首先，确保你的系统已安装Node.js 18或更高版本。你可以通过终端命令检查：

node --version

如果未安装，建议通过nvm（Node Version Manager）安装，便于管理多个版本。

安装Relic本身非常简单，它是一个全局NPM包：

npm install -g @ectplsm/relic

安装完成后，验证是否成功：

relic --version

你应该能看到版本号输出。

3.2 初始化工作区与印迹管理

接下来，初始化Relic。这个命令会在你的用户目录下创建.relic文件夹，并建立基础结构。

relic init

执行后，你会看到一个交互提示：

Set a default Engram? (press Enter for "rebel", or enter ID, or "n" to skip):

这里直接按回车，选择内置的rebel印迹作为默认值。你也可以输入commander选择另一个内置印迹，或输入n暂时不设置。

现在，列出所有可用的印迹：

relic list

你应该能看到rebel和commander两个印迹。你可以随时切换默认印迹：

relic config default-engram commander

实操心得：在初期，我建议你花点时间分别用rebel和commander与AI进行几次简短的编程对话，比如让它解释一段代码或写一个简单的函数。你能明显感受到人格差异：rebel的回答可能更简短、直接，甚至带点讽刺；而commander则更倾向于分析、给出步骤和权衡利弊。这能帮你直观理解“人格注入”的含义，并决定哪个更符合你的协作风格，或者激发你创建自己专属印迹的灵感。

3.3 关键集成：为AI CLI配置记忆（MCP）服务

这是让记忆系统运转起来的核心一步。你需要为你使用的AI CLI工具注册Relic的MCP服务器。MCP（Model Context Protocol）是一种协议，允许AI模型安全地调用外部工具和资源。

对于Claude Code用户：

claude mcp add --scope user relic -- relic-mcp

这条命令告诉Claude Code，存在一个名为relic的MCP服务器，其启动命令是relic-mcp。

对于Codex CLI用户：

codex mcp add relic -- relic-mcp

对于Gemini CLI用户：配置方式略有不同，需要编辑其配置文件。打开或创建~/.gemini/settings.json，添加如下内容：

{ "mcpServers": { "relic": { "command": "relic-mcp", "trust": true } } }

注意事项：执行上述注册命令时，你的AI CLI工具可能会弹出一个安全确认，询问是否允许连接relic-mcp服务器。务必选择允许或信任。如果错过了提示导致连接失败，通常可以在CLI的设置或日志里找到重新授权的选项。没有这个授权，记忆的检索和蒸馏功能将无法工作。

4. 核心工作流：启动、对话与记忆蒸馏

配置完成后，就可以开始真正的“有记忆”的编程协作之旅了。

4.1 启动注入人格的AI会话

启动一个注入了默认印迹（比如commander）的Claude Code会话：

relic claude

如果你想在本次会话中临时使用另一个印迹，可以指定：

relic claude --engram rebel

对于其他CLI，命令类似：

relic codex # 或 relic gemini

命令执行后，对应的AI CLI工具会启动。如果你仔细观察启动后的初始系统提示（通常在Claude Code中可以通过某种方式查看完整提示），你会发现开头部分被插入了一大段来自印迹文件的文本，这就是“人格注入”的实质。

4.2 进行有上下文的对话

现在，你可以像平常一样与AI对话。例如，你可以说：

“我正在开发一个React组件，需要处理复杂的表单状态。你有什么建议？”

由于USER.md和MEMORY.md可能还空着，AI最初主要依赖SOUL.md的人格和IDENTITY.md的角色来回应。但随着对话进行，后台的钩子正在默默地将所有问答记录到archive.md中。

完成一个话题后，比如你们一起设计并实现了一个使用useReducer和Context的表单状态管理方案，你就可以触发记忆蒸馏。

4.3 触发记忆蒸馏，固化知识

在对话中，直接输入：

“整理我的记忆。”

这时，AI（构造体）会意识到需要调用relic_engram_create相关的MCP工具（实际是记忆整理工具）。它会：

读取archive.md中自上次整理后的新对话记录。
分析对话内容，识别出关于“React复杂表单状态管理”的讨论。
将关键信息，如“决定采用useReducer+Context模式”、“避免在组件内直接管理大量useState”、“创建了FormContext和formReducer示例代码”，提炼出来。
将这些信息写入memory/目录下的一个文件，例如memory/2024-05-react-form-state.md。
如果其中有一些原则性的结论（如“对于超过5个字段的表单，优先考虑Reducer模式”），它可能会将其提升到MEMORY.md中。
同时，它可能会更新USER.md，添加一条如“偏好：在React中，倾向于使用Reducer管理复杂表单状态”。

这个过程完成后，AI通常会给你一个摘要，比如“已更新3条关于React表单状态管理的记忆”。

核心技巧：不要把“整理记忆”当作一个繁琐的日常任务。我个人的习惯是，在完成一个相对独立的工作单元（如一个功能模块、解决一个复杂Bug、进行一次技术调研）后，才触发一次。这保证了每次蒸馏的内容主题集中，质量更高。频繁地对琐碎对话进行蒸馏，可能会产生大量碎片化、低价值的记忆条目。

4.4 验证记忆效果

关闭当前的AI会话。然后，重新启动一个相同的印迹会话：

relic claude --engram commander

在新的会话开始时，你可以试探性地问：

“我们之前关于表单状态管理是怎么考虑的？”

此时，AI的回答应该能反映出上次蒸馏出的记忆内容，它可能会引用MEMORY.md或具体记忆文件中的要点，而不是像第一次那样从头开始解释。这就是“持久记忆”在发挥作用。

5. 高级应用：创建自定义印迹与云端同步

5.1 打造你的专属AI人格

使用内置印迹只是开始，创建属于你自己的印迹才能最大化Relic的价值。最推荐的方式是让AI帮助你创建。

在你的AI CLI（无需通过Relic启动，普通启动即可）中，你可以直接请求它使用relic_engram_create工具。例如，在Claude Code中你可以说：

“请使用relic_engram_create工具，帮我创建一个新的印迹，ID为my-mentor。它是一位耐心、注重基础、善于用比喻解释复杂概念的资深软件工程导师。”

AI会引导你完成SOUL.md、IDENTITY.md等文件的创作。你也可以通过CLI命令创建骨架，然后手动编辑：

relic create my-mentor

这会在~/.relic/engrams/my-mentor/目录下创建模板文件，你可以用任何文本编辑器精心雕琢这些Markdown文件。

人格设计心得：

SOUL.md是核心，要赋予其连贯的背景和鲜明的性格特征。例如，你的“导师”印迹可能曾经在大学任教，喜欢引用《人月神话》中的典故。
IDENTITY.md可以更具体，比如“全栈开发顾问，专精于系统可维护性”。
在USER.md的初始模板中，可以预先写入一些你的绝对偏好，比如“代码注释必须使用英文”、“拒绝使用var关键字”等，这能更快地塑造AI的反馈。

5.2 利用Mikoshi实现云端同步与备份

当你在一台机器上培养了一个非常合拍的AI伙伴（印迹）后，你肯定希望能在办公室的台式机和家里的笔记本上无缝切换。Mikoshi就是为此而生。

首先，设置Mikoshi：你需要一个Mikoshi的API密钥。访问其服务网站（根据文档）进行注册获取。然后在本地进行配置：

relic config mikoshi.api-key YOUR_API_KEY_HERE relic config mikoshi.endpoint https://your-mikoshi-instance.com

推送印迹到云端：

relic mikoshi push my-mentor

这个命令会将my-mentor印迹的所有人格文件（SOUL.md,IDENTITY.md,USER.md）推送到Mikoshi。对于MEMORY.md和memory/*.md，Relic默认会使用端到端加密后再推送，确保你的私人记忆在云端也是安全的。

在另一台机器上拉取印迹：在新机器上安装并初始化Relic后，配置好相同的Mikoshi API密钥和端点，然后执行：

relic mikoshi pull my-mentor

拉取后，使用relic list就能看到my-mentor印迹，并可以立即使用。relic mikoshi sync命令则可以双向同步本地和云端的更改，解决冲突时通常以云端版本为准（具体行为需参考文档）。

避坑指南：云端同步功能非常强大，但务必注意：
备份USER.md：USER.md是唯一一个由AI在本地动态更新的文件。在push之前，最好确认一下其内容是否已稳定。虽然sync可以处理合并，但复杂的冲突仍需手动解决。
头像路径：如果你的SOUL.md中引用了一个本地图片作为头像（例如![avatar](./avatar.png)），relic mikoshi push会尝试将这个图片快照并上传到Mikoshi管理的存储中，以保证在其他机器拉取时能正常显示。如果头像是一个网络URL，则会直接记录该URL。
加密记忆：记忆文件的加密是本地进行的，密钥与你的配置相关。这意味着如果你丢失了本地.relic配置目录，可能无法解密云端加密的记忆。建议将重要的、最终的记忆洞察，也以非加密的形式（或自行备份）保存在人格文件中。

6. 与Claw系AI智能体框架的集成

Relic的另一个强大之处在于它能与OpenClaw等Claw-based的AI智能体框架集成。你可以将Relic管理的“人格印迹”同步给这些更复杂的、能执行多步骤任务的智能体。

基本操作非常直观：

relic claw push my-mentor：将my-mentor印迹推送到配置的Claw路径（通过relic config claw.path设置）下的对应智能体。
relic claw pull some-agent：从Claw路径中拉取名为some-agent的智能体配置，并将其转换为Relic的印迹格式。
relic claw sync：在Relic印迹和Claw智能体之间进行双向同步。

这打通了“对话式编码助手”和“自动化任务智能体”之间的隔阂。例如，你可以让一个在Claude Code中与你讨论架构的“架构师”印迹，将其设计思想和约束（存储在MEMORY.md中）同步给OpenClaw中的一个负责实际生成代码的智能体，确保执行层面不偏离设计初衷。

7. 常见问题、排查与性能调优

在实际使用中，你可能会遇到一些典型问题。

7.1 MCP连接失败或记忆功能无效

症状：执行“整理我的记忆”后，AI没有反应或报错说找不到工具。
排查：
1. 首先运行relic-mcp命令，看MCP服务器是否能独立启动。如果报错，可能是Node环境或依赖问题。
2. 检查AI CLI的MCP服务器配置是否正确。对于Claude/Codex，可以运行claude mcp list或codex mcp list查看relic是否在列且状态正常。
3. 确认你在AI CLI中授权了Relic MCP服务器。有时需要重启AI CLI或重新运行注册命令。
4. 查看Relic的日志，默认位于~/.relic/relic.log，里面可能有更详细的错误信息。

7.2 记忆蒸馏效果不理想

症状：AI整理的记忆过于琐碎，或抓不住重点。
优化：
1. 对话质量：记忆蒸馏的质量高度依赖于原始对话的质量。在讨论时，尽量让对话结构化、结论明确。多用“那么，我们决定采用方案A，原因是B和C”这样的总结性语句。
2. 触发时机：避免在闲聊或探索性、未形成结论的对话后立即蒸馏。最好在一个有明确产出（如一段代码、一个设计图、一个解决方桉）后再进行。
3. 手动干预：蒸馏出的memory/*.md和MEMORY.md文件是纯文本的Markdown。你可以直接编辑它们，删除无用信息，润色重点，甚至建立文件间的链接。Relic系统会尊重这些手动修改。

7.3 印迹人格“漂移”或响应变慢

症状：随着USER.md和MEMORY.md内容变得极其庞大，AI在会话开始时加载的上下文过长，可能导致响应速度下降，甚至人格特征被海量的记忆文本稀释。
调优：
1. 定期清理记忆：像整理知识库一样，定期回顾MEMORY.md和memory/目录。将过时的、临时的信息移入一个archive/文件夹（Relic不读取），只保留真正具有长期价值的核心原则和知识。
2. 精简USER.md：USER.md应是动态变化的，但也可以定期将一些已固化的偏好提炼成更简洁的表述，移除重复或矛盾的条目。
3. 利用配置：Relic有memory-window等配置项，可能在未来版本中用于控制加载记忆的时间范围或数量，关注更新日志。

7.4 多项目环境下的印迹管理

场景：你同时在处理公司项目A和个人项目B，希望AI在不同项目中扮演略有不同的角色。
策略：
1. 创建项目专属印迹：基于你的基础印迹（如commander），复制一份并重命名（如commander-project-a）。然后修改其IDENTITY.md，明确角色为“Project A的首席后端工程师”，并可能初始化一些与项目A技术栈相关的记忆。
2. 使用符号链接或脚本：你可以在不同项目的根目录下，创建一个指向特定印迹目录的符号链接，或者写一个简单的Shell脚本，在进入项目目录时自动切换Relic的默认印迹。
3. 记忆隔离：项目A和项目B的记忆文件（MEMORY.md,memory/*.md）是完全独立的，这天然实现了上下文隔离，避免了信息污染。

经过数月的深度使用，我将Relic视为一个“认知外挂”。它并没有改变AI模型本身的能力上限，但它极大地提升了AI与我协作的体验下限和效率均值。那种无需重复解释背景、AI能基于“我们之前的讨论”给出建议的感觉，是传统无状态对话无法比拟的。它迫使我将与AI的交互从随意的问答，转变为更有意识的知识共建过程。每一次“整理记忆”，不仅是在训练AI，更是在为我自己的项目梳理文档和决策日志。如果你也重度依赖AI编程助手，投入时间搭建和磨合你的Relic系统，将会是一笔非常值得的投资。