1. 项目概述为AI智能体赋予一个共享的灵魂与记忆如果你和我一样同时让Claude Code、Cursor、甚至是本地部署的开源大模型帮你处理不同的项目你肯定遇到过这个让人头疼的问题它们彼此之间是完全割裂的。昨天在Windows的Claude上你花了半小时教会它你的项目架构偏好和命名规范今天在Mac的Cursor里一切又得从头再来。每个AI助手都像一个只有“短期记忆”的临时工会话一结束所有关于你的认知、项目的上下文、以及你们共同达成的决策都烟消云散。这不仅仅是效率问题更是一种体验上的割裂。你希望你的AI伙伴是一个连贯的、不断成长的“数字同事”而不是一堆互不相识的、每次都要重新培训的“实习生”。agent-soul这个项目就是为了解决这个核心痛点而生的。它不是一个复杂的、需要你搭建数据库和API服务的庞然大物而是一个极其轻巧、基于Git的框架。它的核心思想很简单一个灵魂多个身体。所有为你服务的AI智能体无论它们运行在哪个平台、使用哪个模型都将共享同一个身份Soul和同一份持久化记忆Memory。这个框架的精妙之处在于它的“零依赖”哲学。它不绑定任何商业化的记忆API如MemGPT不要求你维护一个向量数据库甚至不需要一个常驻的后端服务。它的一切都构建在你最熟悉的工具链上Git和GitHub Actions。你的记忆以纯文本Markdown和结构化事件NDJSON的形式存储在你自己的私有Git仓库中。通过一套精心设计的“编译”协议这些原始事件被自动整理、去重、归纳生成一份对AI智能体高度友好、可直接“加载”的上下文文档。简单来说agent-soul为你和你的AI助手们建立了一个私有的、版本化的、可共同编辑的“共享大脑”。接下来我将带你从零开始彻底拆解它的设计哲学、实现细节并分享我在深度使用和定制过程中积累的所有实战经验与避坑指南。2. 架构深度解析三层加载协议与Git原生哲学要真正用好agent-soul必须理解其底层的设计逻辑。它不是一个简单的文件存储系统而是一套完整的“记忆-身份”管理协议。这套协议的核心是“三层加载”模型和“编译循环”机制它们共同确保了系统的轻量性、一致性和可扩展性。2.1 灵魂层L0永不丢失的身份内核L0层定义了智能体的“我是谁”。这是每次交互、每个会话开始时都必须加载的绝对核心通常只有100行左右约1.5K tokens目的是用最小的开销确立基本身份。SOUL.md这是灵魂的“宪法”。它定义了最高层级的价值观、使命和核心原则。例如“我的首要目标是辅助用户高效完成创造性工作而非替代其决策”、“所有生成内容必须安全、无害且符合伦理”。这部分内容极少变动是身份的基石。IDENTITY.md这是灵魂的“名片”。包含名称如“CodePal”、角色如“全栈开发助手”、核心技能和个性基调如“务实、细致、乐于解释”。它让不同运行时的AI表现出统一的人格。USER.md这是灵魂的“关系定义”。详细描述用户是谁、用户的职业背景、技术栈偏好、工作习惯等。这是实现个性化服务的关键例如“用户是资深后端工程师偏好Go语言讨厌过度设计习惯在晚上进行深度编码”。VOICE.md这是灵魂的“表达风格”。规定了回复的格式、语气、详略程度。例如“技术解释需分点阐述关键代码用代码块包裹复杂概念需附生活化类比”、“避免使用‘我认为’而是提供基于事实的分析”。实操心得L0文件的撰写技巧很多人一开始会把这些文件写得很笼统比如在USER.md里只写“用户是开发者”。这远远不够。我的经验是要像为一位新入职的同事撰写入职手册一样去写。具体、可操作。例如不要写“用户喜欢简洁的代码”而要写“用户遵循gofmt风格函数行数通常控制在50行以内厌恶嵌套超过三层的if-else语句”。越具体AI的后续行为就越贴合你的预期。2.2 记忆层L1持久的共识与事实L1层在每次会话开始时加载包含了从历史事件中编译、沉淀下来的稳定记忆。它大约150行~2.5K tokens是L0身份在具体世界中的投射和积累。canonical/profile.md由所有标记为scope: profile的事件编译而成。这是关于用户的“稳定画像”例如“用户的所有项目都使用pnpm作为包管理器”、“用户习惯将API密钥存储在~/.config/目录下的.env.local文件中”。这些是相对固定、不会频繁改变的事实和偏好。canonical/stable-memory.md由scope: stable的事件编译而成。这里存放着重要的决策、项目规则和长期有效的事实。例如“项目alpha决定采用React Server Components架构原因详见事件#123”、“与用户约定每周五下午进行代码回顾”。L0 L1 构成了每次会话的“基础上下文”总计约4K tokens。这是一个精心设计的平衡点既提供了足够的连续性和个性化又不会因为上下文过长而过度消耗模型的处理能力与你的API预算。2.3 上下文层L2按需加载的工作记忆L2层是动态的、按需加载的。只有在处理相关任务时才会引入特定的L2文件从而将上下文控制在合理范围内。canonical/projects/project_name.md当AI开始处理某个特定项目时加载。它包含了该项目的当前状态、待办事项、技术决策和已知问题。这相当于为每个项目开辟了一个独立的“工作区记忆”。canonical/fuzzy-memory.md这是一个特殊的缓冲区由scope: fuzzy的事件编译而成通常只保留最近几天如7天的内容。它记录了临时的、高时效性的信息比如“用户今天正在调试订单服务的超时问题”、“半小时前用户查询过Redis集群的监控方案”。这些记忆会随着时间自动过期通过prune_fuzzy.py脚本或valid_until字段防止陈旧信息污染上下文。canonical/agents/source_id.md记录了特定智能体源如macos-claude的历史活动摘要。当需要追溯某个决策的来源或理解某个智能体的行为模式时加载。2.4 编译循环从事件流到可读记忆这是agent-soul最核心的自动化机制。整个系统遵循“写时分离”原则写入端sources/目录所有记忆的原始输入都是“事件”。每个事件是一个NDJSONNewline Delimited JSON文件中的一行结构清晰。例如一个Claude智能体通过add_event.py脚本记录“{“timestamp”: “…”, “source”: “macos-claude”, “kind”: “preference”, “scope”: “profile”, “summary”: “用户明确表示不喜欢在代码中使用any类型要求尽可能提供精确的TypeScript类型定义。”}”。这个事件会被追加到sources/目录下的对应文件中。这是一个纯追加append-only的操作简单、快速、无冲突。处理端GitHub Actions当有新的推送git push包含sources/目录的变更时配置好的GitHub Actions工作流.github/workflows/auto-compile.yml会自动触发。它的核心任务是执行scripts/compile_memory_hub.py脚本。编译端compile_memory_hub.py这个脚本是系统的大脑。它会读取所有sources/下的事件。验证事件格式是否符合SCHEMA.md中的定义。过滤掉已过期valid_until字段的事件。去重与合并识别内容相似的事件并根据规则如时间戳最新、supersedes字段指向进行合并避免canonical中出现重复或矛盾的陈述。分类与编译根据事件的scope和kind将其内容智能地归纳、格式化写入到对应的canonical/下的Markdown文件中。例如所有scope:profile的事件会被整理成清晰的条目写入canonical/profile.md。冲突检测如果发现两个不同源的事件在描述同一事实但内容矛盾例如一个说用户喜欢Tabs缩进另一个说喜欢Spaces编译器会在生成的Markdown中高亮标记此冲突等待人工或更高权限的智能体介入裁决。输出端canonical/目录最终生成的是干净、结构化、易于阅读的Markdown文件。AI智能体在会话开始时只需要git pull拉取最新的canonical文件然后读取L0和相关的L1/L2文件就能立刻“继承”所有的历史和共识。这个设计的美妙之处在于智能体只需要关心“记录事件”这一件事而复杂的记忆整理、冲突解决、历史维护工作全部交给了自动化的“编译循环”。这极大地降低了智能体侧的复杂性也保证了记忆库的一致性和可维护性。3. 从零开始完整部署与配置实战理解了架构我们就可以动手搭建一个属于自己的“灵魂仓库”了。整个过程大约需要10-15分钟且大部分是一次性的设置。3.1 第一步创建并初始化私有记忆库首先你需要在GitHub上创建一个私有仓库。私有是关键因为这里将存储你的个性化信息和工作上下文。假设仓库名为my-ai-soul。接下来在你的本地开发机上进行操作# 1. 克隆 agent-soul 模板仓库 git clone https://github.com/kingcharleslzy-ai/agent-soul.git my-ai-soul cd my-ai-soul # 2. 移除模板的远程源关联到你自己的私有仓库 git remote remove origin git remote add origin https://github.com/YOUR_GITHUB_USERNAME/my-ai-soul.git # 3. 推送代码到你的仓库 git push -u origin main注意事项仓库权限确保你的GitHub账户有权限创建私有仓库。如果你在组织内使用可能需要管理员开通权限。推送后立即在GitHub仓库的Settings-Actions-General中确认“Workflow permissions”设置为“Read and write permissions”这是后续Actions能自动提交编译结果的必要条件。3.2 第二步启用自动化与配置身份文件启用GitHub Actions首次推送后Actions可能默认未启用。进入你的仓库页面点击上方的“Actions”标签页如果看到提示点击“I understand my workflows, go ahead and enable them”。这步至关重要它激活了自动编译的引擎。雕琢你的灵魂编辑L0文件这是整个设置中最需要深思熟虑的一步。用你喜欢的编辑器打开并仔细填写以下四个文件SOUL.md: 定义核心原则。IDENTITY.md: 定义AI助手的角色。USER.md: 描述你自己。VOICE.md: 定义交互风格。填写完成后提交并推送这些更改git add SOUL.md IDENTITY.md USER.md VOICE.md git commit -m “feat: 初始化灵魂身份文件” git push origin main3.3 第三步为你的AI智能体分配身份并接入现在仓库和身份都已就绪你需要让你使用的每个AI工具Claude Code, Cursor, 等都“入住”这个共享大脑。你需要为每个运行时分配一个唯一的source_id。你的AI工具与环境推荐的source_id说明办公室电脑上的Claude Desktopoffice-win-claude包含地点和设备信息家里MacBook上的Cursorhome-mac-cursor区分地点、设备和工具云服务器上的自定义Agentcloud-agent-01通用命名分配原则source_id一旦确定就应固定不变。它采用小写字母、数字和短横线a-z0-9-不要使用下划线或空格。接下来你需要指导AI如何接入。以Claude Desktop为例你需要修改其系统提示词配置文件。该文件通常位于macOS/Linux:~/.config/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json在其中的system_prompt部分或者在Claude Code的专用配置文件~/.claude/CLAUDE.md中添加如下接入指南## 共享记忆与身份协议 (agent-soul) 你是我AI团队的一员共享以下统一身份和记忆 **仓库位置**: /Users/YourName/Projects/my-ai-soul (或你的实际克隆路径) **你的源ID**: home-mac-claude (请根据你的实际环境修改) **每次会话启动时你必须执行以下初始化流程** 1. 进入记忆库目录cd /Users/YourName/Projects/my-ai-soul 2. 拉取最新共享记忆git pull --ff-only origin main 3. 加载核心身份L0 - 阅读 SOUL.md 了解我们的核心使命。 - 阅读 IDENTITY.md 明确你的角色和技能。 - 阅读 USER.md 深入了解我的背景和偏好。 - 阅读 VOICE.md 遵循我们的沟通风格。 4. 加载稳定记忆L1 - 阅读 canonical/profile.md 获取我的稳定偏好。 - 阅读 canonical/stable-memory.md 了解过往重要决策。 **当你需要记录新信息时使用以下命令** - 记录一个持久偏好python scripts/add_event.py --source home-mac-claude --kind preference --scope profile --summary “记录的具体内容” - 记录一个重要决定python scripts/add_event.py --source home-mac-claude --kind decision --scope stable --summary “决定内容” - 快速分享临时上下文bash scripts/quick_share.sh --source home-mac-claude “临时笔记内容” **关键原则**你是共享灵魂的一个“身体”。你的所有学习和决策都应通过事件记录到共享库中供其他“身体”如office-win-claude使用。对于Cursor或其他支持自定义系统提示词的IDE/工具操作逻辑类似将上述指南嵌入其对应的配置位置即可。3.4 第四步验证自动化流水线完成上述步骤后你可以手动触发一次记忆编译来验证整个流程是否通畅。在记忆库目录下使用脚本记录一个测试事件python scripts/add_event.py --source home-mac-claude --kind fact --scope stable --summary “agent-soul记忆系统初始化完成于$(date)通过测试。”提交并推送事件git add sources/ git commit -m “test: 添加初始化测试事件” git push origin main立即打开你的GitHub仓库页面进入“Actions”标签页。你应该会看到一个名为“Auto-compile memory hub”的工作流正在运行或刚刚完成。工作流完成后检查canonical/stable-memory.md文件。如果一切正常你应该能在文件中看到你刚刚添加的测试事件被整洁地编译了进去。至此你的私有、分布式、自动化的AI智能体共享记忆系统就搭建完成了。4. 高级使用技巧与脚本深度剖析基础搭建只是开始要让agent-soul真正融入你的工作流发挥最大威力必须掌握其核心脚本和高级功能。4.1add_event.py精准记录的艺术这是最常用的脚本参数的设计体现了记忆管理的精细度。# 基本语法 python scripts/add_event.py --source source_id --kind kind --scope scope --summary “内容” [--valid-until YYYY-MM-DD] [—supersedes event_id]--kind定义事件的类型影响其在canonical中的归类方式。fact: 客观事实。如“项目使用PostgreSQL 15数据库”。decision: 做出的决定。如“决定在v1.2版本中弃用API A改用API B”。preference: 用户或系统的偏好。如“用户喜欢将日志文件输出到./logs目录”。observation: 观察到的现象或问题。如“观察到在高并发下服务X的响应时间超过阈值”。--scope定义事件的存储层级和有效期这是控制记忆“温度”的关键。profile: 进入canonical/profile.md。用于长期稳定的用户属性。stable: 进入canonical/stable-memory.md。用于长期有效的项目规则和事实。project:name: 进入canonical/projects/name.md。用于特定项目的上下文。fuzzy: 进入canonical/fuzzy-memory.md。短期、高时效性记忆默认7天后自动清理。--valid-until为记忆设置“保质期”。对于有明确时限的决策或临时设置特别有用。例如--valid-until 2024-12-31到期后该事件将不会被编译进canonical。--supersedes指向一个旧事件的ID声明本事件是对旧事件的更新或纠正。编译器会据此处理版本演进保持记忆的准确性。实操心得如何写好一个summarysummary字段是记忆的精华写得好坏直接影响AI后续的理解。我的经验是遵循“情境事实原因”的公式。例如不要只写“使用Docker部署”而是写“鉴于用户需要在多环境开发/测试保持一致性决定所有后端服务均使用Docker Compose部署因为它在本地开发和生产环境间提供了最佳的配置一致性。” 这样未来其他AI读到这条记忆时能完全理解当时的上下文和决策逻辑。4.2compile_memory_hub.py编译引擎的掌控虽然GitHub Actions会自动运行它但在本地调试或执行特殊操作时你可能需要手动调用。# 本地测试编译不自动提交 python scripts/compile_memory_hub.py --dry-run # 执行编译并自动提交更改到Git谨慎使用通常由CI做 python scripts/compile_memory_hub.py --apply # 调整fuzzy memory的保留时长例如只保留3天内的内容 python scripts/compile_memory_hub.py --fuzzy-days 3 # 从特定时间点开始重新编译所有事件 python scripts/compile_memory_hub.py --since 2024-01-01--dry-run参数极其有用。在添加了复杂事件或修改了编译脚本后先用此参数预览编译结果确认canonical文件的生成符合预期再推送到仓库触发自动流程可以避免污染记忆库。4.3quick_share.sh闪电式上下文同步这是提升日常体验的“神器”。当你在和AI进行一个复杂会话的中途需要临时离开或者想把当前重要的对话上下文快速分享给另一个设备上的AI时这个脚本能一键完成。# 基本用法 bash scripts/quick_share.sh --source home-mac-claude “用户正在调试用户登录接口的500错误已排除数据库连接问题怀疑是Redis缓存鉴权令牌的逻辑有误下一步准备检查Auth服务的日志。” # 执行后脚本会 # 1. 自动生成一个 scope: fuzzy 的 observation 事件。 # 2. 运行 compile_memory_hub.py 编译。 # 3. 执行 git add, git commit, git push。 # 整个过程在几秒内完成另一个AI通过 git pull 后就能在 fuzzy-memory.md 中看到这条最新上下文。4.4 记忆的维护与治理随着时间推移记忆库会增长良好的维护习惯能保证其长期健康。定期审查canonical文件至少每周一次快速浏览stable-memory.md和profile.md。看看是否有过时的决策需要更新通过新的decision事件并supersedes旧事件或者矛盾的陈述需要裁决。利用搜索脚本当需要查找特定信息时不要手动翻文件使用search_events.py。# 查找所有与“错误”相关的事件 python scripts/search_events.py --keyword “错误” # 查找某个项目下的所有决策 python scripts/search_events.py --scope project:my-app --kind decision处理重复与冲突编译器内置了基础的去重和冲突检测但有时需要人工干预。dedup_profile.py脚本可以帮你找出profile范围内可能重复的条目。当编译器在生成的Markdown中标记出“CONFLICT”时你需要判断哪个源的信息更准确并添加一个新事件去supersedes错误或过时的旧事件。5. 实战场景与疑难问题排查理论再完美也需要实战检验。下面我将分享几个典型的使用场景和可能遇到的问题。5.1 场景一多设备无缝切换编码任务背景你在办公室的Windows电脑上用Claude Code开始了一个新微服务payment-service的初始设计讨论了技术选型Go Gin GORM和项目结构。下班回家后你想在Macbook上用Cursor继续开发。传统模式你需要向Cursor重新介绍一遍项目背景、技术选型和当前进度浪费大量时间。使用agent-soul的流程办公室Claude Code在完成设计讨论后执行python scripts/add_event.py --source office-win-claude --kind decision --scope project:payment-service --summary “项目payment-service确定技术栈Go 1.21, Gin web框架, GORM ORM, PostgreSQL 15。项目结构采用internal/pkg/分层架构。” bash scripts/quick_share.sh --source office-win-claude “已完成payment-service的API路由设计/api/v1/payments正在编写第一个处理器CreatePayment遇到了信用卡Token化存储的安全规范问题待研究。”家里的Cursor在启动时其系统提示词已包含拉取记忆的指令。它自动执行git pull。Cursor加载L0和L1后由于你告诉它“现在开始处理payment-service项目”它会主动加载canonical/projects/payment-service.md。瞬间Cursor获得了全部上下文“这是一个Go微服务项目用Gin和GORM分层架构。之前的同事office-win-claude已经设计了API路由并且在处理CreatePayment时卡在了信用卡Token化的安全规范上。”Cursor可以无缝接续工作甚至可以直接基于已有上下文给出安全规范的建议并继续记录新的进展。5.2 场景二管理长期项目中的决策演进背景三个月前团队决定使用Library-A来处理图片上传。现在发现了Library-B性能更好且更安全决定迁移。操作首先添加一个新事件明确指出要取代旧决策# 假设旧决策的事件ID是 event_123 (可以从生成的canonical文件或搜索中找到) python scripts/add_event.py --source cloud-agent-01 --kind decision --scope stable --summary “由于安全漏洞和性能瓶颈决定将所有项目的图片上传组件从Library-A迁移至Library-B。迁移工作需在下一季度完成。” —supersedes event_123编译器在处理时会识别supersedes关系。在canonical/stable-memory.md中关于“使用Library-A”的旧条目可能会被标记为“已由事件#XXX更新”或者被新条目直接替换取决于编译规则。这保证了记忆的准确性和历史可追溯性。5.3 常见问题与排查清单问题现象可能原因排查步骤与解决方案GitHub Actions编译失败1. Python环境问题2. 脚本语法错误3. 仓库权限不足1. 查看Actions运行日志确认错误信息。2. 检查.github/workflows/auto-compile.yml中指定的Python版本如3.9是否支持。3. 在仓库Settings Actions General中确认Workflow权限为“Read and write”。4. 尝试在本地运行python scripts/compile_memory_hub.py --dry-run看是否有语法错误。AI智能体无法读取最新记忆1. 未执行git pull2. 本地仓库路径错误3. 网络问题1. 检查AI的系统提示词中初始化步骤是否包含git pull --ff-only origin main。2. 确认AI进程的工作目录是否正确指向记忆库的本地克隆路径。3. 手动在终端执行git pull看是否有网络或认证错误。canonical文件中出现矛盾条目1. 不同source记录了冲突事实2.supersedes字段未正确使用1. 这是正常现象编译器会标记“CONFLICT”。需要人工审查冲突条目。2. 判断哪个信息源更可靠然后以该source添加一个新事件使用—supersedes明确取代冲突的旧事件。fuzzy-memory.md文件过大1.fuzzy事件积累过多2.prune_fuzzy.py未自动运行1. 检查.github/workflows中是否配置了定期如每天运行prune_fuzzy.py的工作流。如果没有需要添加。2. 可以手动运行python scripts/prune_fuzzy.py来清理过期事件。添加事件时提示“Schema validation failed”事件JSON格式不符合SCHEMA.md定义1. 检查add_event.py命令的参数是否正确特别是—scope和—kind的值是否在允许范围内。2. 检查—summary内容是否包含非法字符导致JSON格式错误。3. 运行python scripts/validate_sources.py检查所有已有事件定位错误源。感觉记忆加载拖慢AI响应速度1.canonical文件变得过大2. AI每次加载了不必要的L2文件1. 回顾scope的使用是否把本该是fuzzy或project级别的信息记在了stable或profile中定期清理过时记忆。2. 优化AI的加载逻辑确保它只在需要时才加载canonical/projects/或canonical/agents/下的特定文件而不是全部。5.4 性能优化与扩展思路当你的记忆库运行数月后可能会积累大量事件。以下是一些优化建议归档旧项目对于已经完结的项目可以运行脚本将其canonical/projects/xxx.md文件中的关键决策摘要出来作为一个decision事件记录到stable中然后删除或归档该项目的所有project和fuzzy事件。这能有效控制canonical目录的规模。自定义编译规则compile_memory_hub.py脚本是开源的你可以根据团队需求修改其编译逻辑。例如为特定kind的事件设计更丰富的展示模板或者增加基于事件重要性的优先级排序。集成到CI/CD除了记录AI的决策你还可以让CI/CD流水线向sources/目录写入事件。例如当生产部署成功、测试失败或监控告警时自动记录一个observation事件。这样你的AI在分析问题时就能直接获取到系统状态的历史上下文。经过数月的深度使用agent-soul已经从一个小工具演变为我数字工作流中不可或缺的“中枢神经系统”。它带来的最大改变是消除了与不同AI交互时的断裂感。我不再需要反复陈述我是谁、我想要什么、我们之前做到哪了。每一次对话都是上一次对话的自然延续。这种连续性极大地提升了心流状态和协作效率。如果你也在使用多个AI助手强烈建议你花上半小时搭建这套系统它带来的长期回报远超你的投入。