1. 项目概述为什么我们需要一个“记忆桥梁”如果你和我一样在日常开发中重度依赖各种AI助手——比如用Claude Code写代码、用Hermes管理长期任务、用Codex CLI快速调试——那么你肯定遇到过这个痛点每次想回顾之前和AI讨论过的某个技术决策、某个报错的解决方案或者仅仅是上周写的一段特定功能的代码时你都得像个考古学家一样在不同的工具目录里翻箱倒柜。Claude的对话记录在~/.claude/projects/下是一堆JSONL文件Hermes的记忆在~/.hermes/里又是JSONL又是MarkdownCodex CLI也有自己的一套。这些数据格式各异散落各处形成了一个个“记忆孤岛”。更麻烦的是当你想要对这些历史对话进行语义搜索时比如问“我之前是怎么解决那个PostgreSQL连接池泄漏问题的”你几乎无能为力。因为这些原始文件不是为搜索而生的。这时 gBrain 这类基于向量数据库的知识图谱工具就派上用场了。它能将文档切片、向量化让你用自然语言就能搜到相关内容。但gBrain有个“挑剔”的胃口它只“吃”Markdown。于是一个核心矛盾出现了我们宝贵的、分散的AI记忆是多种格式的“原材料”而强大的知识大脑只接受一种“精加工食品”。hermes-gbrain-bridge就是为了解决这个矛盾而生的。它是一个轻量级、零依赖的转换桥梁专门负责将散落在各处的AI代理记忆目前支持Hermes、Claude Code、Codex CLI、OpenClaw统一清洗、过滤、转换成gBrain可以直接导入的、干净整洁的Markdown文件。它的设计哲学非常明确桥梁本身不存储任何数据不直接操作数据库只做格式转换。这样一来即使转换过程出了问题最坏的结果也只是生成了一些有问题的Markdown文件你的核心知识库gBrain依然安全无恙。这个项目不是一个庞大的平台而是一个精巧的“转换器”配方代码量小到你可以在一杯咖啡的时间里读完并理解其全部逻辑然后根据自己的需求进行定制。2. 核心设计思路与架构解析2.1 核心问题拆解从混乱到有序面对多个来源、多种格式的AI记忆数据一个粗暴的“全部转换”思路是行不通的这会导致成本激增和搜索结果质量下降。hermes-gbrain-bridge的解决方案是分步骤、有策略地进行处理其核心流程可以概括为发现Discover → 过滤Filter → 适配转换Adapt → 标准化Canonical → 输出Export。发现第一步不是写代码而是摸清家底。运行discover命令工具会扫描所有已知的潜在路径报告每个来源下有多少文件、总大小如何。这一步至关重要它能避免你花费大量时间为一个实际上不存在或数据量极少的来源编写适配器。过滤这是控制成本和提升质量的关键。不是所有数据都值得进入知识库。时间窗口过滤通过--days参数只处理最近N天内修改过的文件。对于活跃的对话记录如Claude Code这能有效聚焦于近期相关的内容。大小过滤对于归档数据如OpenClaw通过--min-size参数忽略掉过小的文件例如小于1KB的碎片这些通常是无效或低价值内容。内容过滤这是最核心的。以Claude Code的JSONL事件流为例其中大量是progress进度更新、queue-operation队列操作、tool_use/tool_result工具调用等“管道噪声”。真正有价值的只有user和assistant的对话回合。桥接器会剥离这些噪声只保留精华。适配转换每个数据源都有一个对应的“适配器”Adapter。适配器的职责是理解特定来源的原始格式并将其初步解析为结构化的数据。例如Claude Code适配器需要处理嵌套的message.content结构它可能是字符串、部分数组或包含工具调用对象。标准化所有适配器输出的结构化数据都会被统一转换成一种内部定义的CanonicalEvent规范事件格式。这个格式是所有来源的“最大公约数”通常包含role角色如user/assistant、content内容、timestamp时间戳、source来源标识等字段。引入这个中间层是架构上的一个妙招它使得后续的序列化如输出Markdown、安全处理如脱敏和未来支持新输出格式如JSON变得非常容易无需改动适配器逻辑。输出最后将CanonicalEvent序列化成Markdown文件。通常一个完整的会话Session或记忆文件会对应输出一个Markdown文件文件命名和元数据如Frontmatter会包含来源、原始路径等信息便于追溯。2.2 安全与成本控制设计这个项目的设计充满了“生产环境”的谨慎安全脱敏在生成规范事件后、输出Markdown前所有文本内容会经过一个redactSecrets函数处理。它会根据预定义的正则表达式模式如sk-*、xoxb-*、ghp_*、AKIA*、postgres://等将可能的密钥、令牌、连接字符串替换为[REDACTED]。这是一个保守但必要的安全措施防止你不小心将含有敏感信息的记忆导入到可能共享的知识库中。成本意识向量化Embedding是按量计费的如果使用OpenAI等云服务。桥接器通过前述的过滤机制极大地减少了送入gBrain的数据量。在一个真实案例中1.4GB的原始Claude Code JSONL数据经过过滤后只剩下约200MB的有效对话内容将潜在的embeddings成本从数十美元降低到了不足两美元。永远不要在没有过滤的情况下“全量导入”这是一个会带来昂贵账单的教训。2.3 工具链与零依赖哲学项目选择Bun作为运行时用TypeScript编写。Bun的快速启动和内置的工具链包管理器、测试运行器、打包器与这个项目的“小而美”理念非常契合。更重要的是它坚持“零运行时依赖”只使用Bun/Node.js的标准库。这意味着安装极快bun install几乎瞬间完成没有庞大的node_modules。安全性高极大地减少了供应链攻击的表面。可移植性强代码清晰没有黑盒依赖更容易被理解和修改。这种选择体现了工具的本质它应该是一个透明、可靠的“管道”而不是一个臃肿的“平台”。3. 实操指南从零开始搭建你的记忆桥梁3.1 环境准备与项目初始化假设你已经在使用至少一种支持的AI工具如Claude Code并且希望将它的记忆导入到gBrain中。以下是详细的步骤前置条件检查确保系统已安装 Bun (版本 1.0)。在终端输入bun --version验证。准备好你的gBrain环境。gBrain本身需要PostgreSQL建议使用带有pgvector和pg_trgm扩展的版本。你可以按照gBrain的官方文档进行安装和初始化。获取桥接器代码git clone https://github.com/howardpen9/hermes-gbrain-bridge cd hermes-gbrain-bridge安装依赖由于是零依赖项目这一步主要是安装开发依赖如TypeScript类型定义和构建工具。bun install3.2 探索与发现摸清你的数据家底在开始转换之前务必先使用discover命令。这个命令是只读的不会修改任何数据它会扫描所有配置好的源路径并给你一份详细的报告。bun run src/cli.ts discover --days 30参数解释--days 30只考虑过去30天内修改过的文件。这对于Claude Code、Codex这类活跃源非常有用可以避免处理陈旧的历史数据。输出解读 命令会输出一个表格类似以下结构Source | Files Found | Total Size | Avg. Size | Newest File ------------------|-------------|------------|-----------|------------- hermes-sessions | 45 | 4.2 MB | 93 KB | 2023-10-26 claude-code | 1247 | 1.1 GB | 923 KB | 2023-10-26 codex-cli | 312 | 87 MB | 285 KB | 2023-10-25 openclaw-archive | 0 (30d) | 0 B | 0 B | N/A这个报告能告诉你哪个来源的数据量最大通常是Claude Code。是否有你遗忘的旧数据源比如很久没用的OpenClaw归档。帮助你决定后续转换策略的优先级和过滤参数。实操心得千万不要跳过这一步我曾经以为我的Hermes记忆是主力但discover命令显示Claude Code的数据量是它的200倍。这直接影响了我的过滤策略避免了对海量Claude Code数据做无谓的全量处理。3.3 执行数据转换与导出在了解数据分布后就可以开始转换了。建议先进行试运行dry-run确认转换逻辑和输出符合预期。针对单个源进行试运行比如我们先转换Claude Code的数据。bun run src/cli.ts export --sourceclaude-code --dry-run --days 30--sourceclaude-code指定转换源。其他选项包括hermes,codex,openclaw, 或all。--dry-run模拟运行。它会执行所有读取、解析、过滤逻辑并打印出将会创建的文件列表和统计信息但不会实际写入任何Markdown文件。这是防止意外操作的安全网。--days 30同样应用时间过滤。正式导出到临时目录试运行确认无误后移除--dry-run参数并指定输出目录。bun run src/cli.ts export --sourceall --out/tmp/gbrain-staging --days 30--sourceall转换所有已支持的源。--out/tmp/gbrain-staging指定一个临时目录例如/tmp下的目录来存放生成的Markdown文件。不要直接输出到gBrain的工作目录或重要位置。对于OpenClaw归档这类历史数据你可能需要不同的参数例如放宽时间限制并设置最小文件大小bun run src/cli.ts export --sourceopenclaw --out/tmp/gbrain-staging --days 365 --min-size-kb 1检查输出结果转换完成后强烈建议你快速浏览一下/tmp/gbrain-staging目录下的Markdown文件。检查文件数量是否合理。随机打开几个文件查看内容是否完整、格式是否正确、敏感信息是否已被脱敏显示为[REDACTED]。确认每个文件都包含了必要的元数据通常在文件开头的YAML Frontmatter中如source,original_path,session_id等。3.4 导入gBrain与向量化现在干净的Markdown文件已经准备就绪可以将它们喂给gBrain了。导入gBrain# 进入你的gBrain项目目录 cd /path/to/your/gbrain-project # 执行导入命令--no-embed 表示先不进行向量化 gbrain import /tmp/gbrain-staging --no-embed这个命令会将Markdown文件解析为gBrain内部的“页面”Page和“内容块”Chunk并存入数据库。执行向量化Embedding这是将文本转换为向量表示的关键步骤需要调用OpenAI或其他的Embedding API。# 确保你的环境中设置了 OPENAI_API_KEY export OPENAI_API_KEYyour-api-key-here # 对数据库中所有尚未向量化的内容块进行向量化 gbrain embed --stale--stale参数指示gBrain只处理那些新的或更新过的、还没有对应向量的内容块。如果是首次导入则会处理所有内容。性能与成本预估 这个过程可能需要一些时间取决于数据量和网络速度。参考项目的案例数据约3.7k个Markdown文档产生了5.7万个内容块使用text-embedding-3-large模型进行向量化总成本低于2美元耗时约55分钟。你的实际耗时和成本将取决于你的数据量、块大小Chunk Size和选择的Embedding模型。3.5 连接AI工具与你的知识大脑数据导入后如何让Claude Code等AI工具在需要时查询这个大脑呢推荐使用MCPModel Context Protocol集成。启动gBrain的MCP服务器# 在gBrain项目目录下 bun run src/cli.ts serve这个服务器会通过标准输入输出stdio提供一系列工具如搜索、查询、获取页面等。在Claude Code中注册MCP服务器claude mcp add gbrain -s user -- \ /path/to/.bun/bin/bun run /path/to/gbrain/src/cli.ts serve这条命令会告诉Claude Code“当你运行时去调用这个bun命令启动的MCP服务器”。注册成功后Claude Code就能自动发现并调用gBrain提供的几十个工具函数实现无缝的知识查询。对于不支持MCP的工具如某些CLI工具你可以在其系统提示词或配置文件中添加一段说明指导AI在需要时通过执行gbrain query 你的问题这样的shell命令来获取信息。虽然不如MCP集成优雅但同样有效。4. 深度解析各数据源适配器的处理逻辑与避坑指南4.1 Claude Code从嘈杂的事件流中提取对话精华Claude Code的会话存储在~/.claude/projects/encoded-path-hash/*.jsonl。每个JSONL文件是一行一个事件的流式记录。这是处理起来最复杂但也是数据量最大的来源。核心挑战事件类型繁多对话内容深埋。一个典型的JSONL文件包含多种事件{type: session_created, ...} {type: progress, progress: 0.1, ...} // 噪声进度更新 {type: queue-operation, ...} // 噪声队列操作 {type: message, message: {role: user, content: 如何优化这个SQL查询, ...}} {type: message, message: {role: assistant, content: [{type: text, text: 可以考虑添加索引...}, {type: tool_use, ...}]}} // 内容可能是数组内含工具调用 {type: tool_result, ...} // 噪声工具调用结果适配器逻辑按行读取JSONL只处理type为message的事件。从message对象中提取role(user/assistant)。解析content字段这是最易出错的地方。content可能是一个字符串也可能是一个数组。如果是数组需要遍历数组元素只提取type为text的部分并拼接起来。对于tool_use和tool_result桥接器选择丢弃因为它们通常是具体的、一次性的操作细节不适合作为长期知识记忆。时间戳处理使用事件的created_at或文件修改时间。输出将同一会话中的所有user/assistant对话对按时间顺序整理输出为一个Markdown文件。通常以用户的问题作为标题或主要内容开头。避坑指南不要尝试解析所有工具调用tool_use的内容通常是特定、临时的尝试将其结构化并保留会极大增加复杂度且对知识搜索的价值有限。果断过滤掉。注意编码路径~/.claude/projects/下的目录名是经过编码的项目路径哈希而不是可读的项目名。不要试图反向解码直接将其作为会话的唯一标识符即可。真正的项目元信息如项目名可能藏在会话的某个事件里但提取成本高不是必须的。内存管理单个JSONL文件可能很大几十MB。使用流式读取line-by-line而非一次性读入内存防止处理大量文件时内存溢出。4.2 Hermes处理混合格式的记忆库Hermes的存储相对规整但有两种主要格式会话Sessions~/.hermes/sessions/*.jsonl格式与Claude Code类似也是JSONL事件流但事件结构可能不同。适配器需要针对Hermes的事件类型进行解析。长期记忆Memories~/.hermes/memories/目录下的.md文件例如MEMORY.md、USER.md。这些文件内部使用§符号作为条目分隔符。适配器逻辑对于会话JSONL处理逻辑与Claude Code适配器类似但需要根据Hermes特有的事件模式如hermes.*类型的事件来提取对话内容。同样需要过滤掉系统事件和工具调用噪声。对于记忆Markdown处理起来更简单。读取.md文件按§分隔符拆分成独立的记忆条目。每个条目可以视为一个独立的“文档”直接转换为一个CanonicalEvent或者将整个文件作为一个文档但这样可能不利于检索。项目当前实现是作为整体传递pass-through依赖gBrain后续的块分割。注意事项区分会话与记忆会话是连续的对话流记忆是离散的知识点。在导入gBrain后你可能需要通过元数据source字段或特定标签来区分它们以便在查询时进行筛选。§分隔符的可靠性确保这个分隔符在记忆内容中不会自然出现否则会导致错误的分割。Hermes选择这个冷门字符通常是安全的。4.3 Codex CLI相对简洁的会话格式Codex CLI的会话存储在~/.codex/sessions/**/*.jsonl。它的格式被认为是比Claude Code更“干净”的。特点每个JSONL文件通常以一个session_meta事件开头包含了cwd工作目录、model、id等有用的上下文信息。后续的事件具有payload.role字段如user,assistant,system结构相对扁平内容通常在payload.content中且格式更统一。适配器逻辑读取session_meta提取会话元数据可以作为Markdown文件的Frontmatter。遍历后续事件过滤出payload.role为user或assistant的事件。提取payload.content通常是字符串构造CanonicalEvent。由于格式规整Codex CLI的适配器往往是编写和调试起来最简单的适合作为第一个实现的适配器来建立信心。4.4 OpenClaw Archive处理历史遗留数据OpenClaw的归档数据通常位于~/.openclaw.pre-migration/workspace/**/*.md。它本身就是Markdown格式所以转换工作主要是过滤和整理。核心挑战归档文件的时间戳mtime很可能都是过去某个批量迁移的时间而不是内容实际创建的时间。因此单纯依赖--days过滤会失效。适配器策略放宽或忽略时间过滤对于归档数据建议使用--days 365或更久或者完全不使用时间过滤如果数据量可控。强化大小过滤使用--min-size-kb 1或更大来过滤掉那些空的或几乎空的无意义文件。内容直通由于已经是Markdown适配器主要工作是添加一些元数据如来源标识、原始文件路径然后直接传递给输出阶段。复杂的清洗工作较少。经验之谈将归档数据的导入视为一次性的、离线的“冷数据迁移”任务。它与日常活跃会话的同步导入应该使用不同的策略和参数。5. 高级议题性能优化、搜索质量与扩展性5.1 控制向量化成本与提升搜索质量将数据导入gBrain只是第一步如何让搜索又快又准才是终极目标。这里涉及两个关键环节块分割Chunking和向量化模型选择。块分割是质量的核心gBrain默认使用递归分割法按标题、段落等。这对于结构清晰的文档很好但对于AI对话这种流式、非结构化的文本效果可能不佳。可能导致一个技术问答被切分到不同的块中搜索时无法召回完整上下文。解决方案考虑使用基于语义的块分割。例如使用一个轻量级模型如sentence-transformers或基于规则的方法如按对话回合确保一个完整的“问答对”或一个逻辑段落尽量保存在同一个块内。这能显著提升后续向量搜索的相关性。虽然hermes-gbrain-bridge目前不直接处理块分割交给gBrain但了解这一点很重要你可以后续在gBrain层面调整块分割策略。向量化模型的选择精度与成本的权衡text-embedding-3-large比text-embedding-3-small精度更高但更贵、更慢。对于技术问答类记忆small模型通常已足够且能大幅降低成本和提高速度。维度large模型输出3072维向量small输出1536维。更高的维度能承载更细粒度的语义信息但也意味着更大的数据库存储和更慢的距离计算。需要根据数据规模和查询性能要求选择。元数据过滤gBrain支持在查询时过滤元数据。在桥接器生成Markdown时确保将重要的元数据如source: claude-code,session_id: xxx,timestamp: 2023-10-26以Frontmatter形式写入。这样你可以在搜索时使用类似gbrain query PostgreSQL索引 --where source claude-code的命令只搜索特定来源的记忆避免被其他不相关来源的大量结果淹没。5.2 处理数据源的不平衡问题在真实场景中不同来源的数据量可能差异巨大。如前文案例Claude Code贡献了92%的块。这会导致一个严重问题语义搜索的结果会被高数据量的来源主导。即使你明确想搜索Hermes记忆中的“我的时区是什么”返回的前几名结果很可能还是来自Claude Code的某个提及了“时区”的会话。应对策略按来源建立多个“大脑”为Claude Code、Hermes等分别建立独立的gBrain实例。查询时根据问题类型选择对应的大脑。这提供了最强的隔离性但增加了管理成本。在查询时加权如果使用一个统一的大脑可以在查询时对来自不同来源的块设置不同的权重如果gBrain或底层向量数据库支持。例如对Hermes来源的块给予更高的相关性权重。在桥接阶段进行采样或摘要对于数据量极大的来源如Claude Code可以在转换时进行采样例如只导入每周的典型会话或者使用LLM生成会话摘要再导入而不是导入全部原始对话。这能从根本上平衡数据分布但会损失细节。5.3 扩展桥接器支持新的数据源项目结构清晰添加一个新的数据源适配器并不困难。主要步骤在docs/EXTENDING.md中有详细说明核心是实现Adapter接口在src/adapters/目录下创建新文件例如gemini-cli.ts。实现Adapter接口该接口通常要求实现name适配器名称、discover发现文件、convert转换文件等方法。在convert方法中完成核心逻辑读取并解析源文件。提取出有意义的对话或内容单元。过滤掉噪声如系统消息、状态更新。将每个单元转换为CanonicalEvent对象。务必在此步骤后调用redactSecrets进行脱敏。返回一个事件数组。在src/adapters/index.ts中注册你的新适配器。更新CLI使新的--source选项生效。编写新适配器的关键点先探索后编码先用脚本或手动方式查看新数据源的文件结构、格式和内容样例。利用现有的CanonicalEvent尽量将源数据映射到现有的规范事件字段。如果确实需要新字段谨慎地扩展CanonicalEvent类型并考虑是否对所有适配器都有意义。保持无副作用适配器只读取源文件不修改它们。所有输出都通过返回值传递。编写测试为你的新适配器编写单元测试使用真实的脱敏后的数据样本确保解析逻辑的健壮性。6. 故障排查与常见问题在实际操作中你可能会遇到以下问题。这里提供排查思路和解决方案。6.1 转换过程常见问题问题现象可能原因解决方案discover命令找不到任何文件1. 默认路径不正确。2. 工具从未在该机器上运行过无历史数据。3. 文件权限问题。1. 检查src/adapters/下对应适配器中定义的路径。对于像Claude Code路径是硬编码的~/.claude/projects/。确认你的数据确实在此路径下。2. 运行一次对应的AI工具生成一些会话记录。3. 确保你有读取这些目录的权限。转换出的Markdown文件内容为空或只有元数据适配器的过滤逻辑过于严格或者解析逻辑有误未能提取出有效内容。1. 使用--dry-run并增加--verbose日志输出查看适配器处理每个文件时识别出了哪些事件。2. 检查源文件格式是否与适配器预期的一致。有时工具更新会导致格式微调。3. 在适配器的convert函数中添加调试日志打印中间解析结果。转换过程非常慢或内存占用高1. 一次性读取了非常大的JSONL文件到内存。2. 没有使用时间窗口过滤处理了海量历史文件。1. 确保适配器使用流式读取如Node.js的readline模块处理大型JSONL文件。2. 务必使用--days参数限制处理范围。对于历史归档考虑分批处理。生成的Markdown文件名重复或冲突不同来源的会话可能具有相同的ID或命名规则。桥接器应在生成文件名时加入来源前缀如claude-code_xxx.md或使用包含完整路径哈希的命名方式确保唯一性。检查输出文件的命名逻辑。6.2 gBrain导入与查询问题问题现象可能原因解决方案gbrain import失败提示数据库错误1. 数据库连接失败。2. 数据库表不存在或模式不匹配。3. Markdown文件Frontmatter格式错误。1. 检查gBrain的数据库连接配置。2. 运行gbrain migrate确保数据库模式是最新的。3. 检查桥接器生成的Markdown文件头部YAML格式是否正确如缩进、冒号后空格。gbrain embed失败提示API错误1.OPENAI_API_KEY环境变量未设置或无效。2. 网络问题。3. 达到API速率限制。1. 确认echo $OPENAI_API_KEY输出正确。2. 检查网络连接。3. 如果数据量巨大考虑在gbrain embed命令中添加--batch-size和--delay参数来控制请求频率。语义查询 (gbrain query) 结果不相关1. 块分割策略不佳上下文断裂。2. 数据源不平衡某个来源的结果淹没了其他来源。3. Embedding模型不适合该类型文本。1. 尝试调整gBrain的块分割参数如chunk-size,chunk-overlap。对于对话较小的块和较大的重叠可能更好。2. 尝试在查询时使用--where条件过滤来源或按前文所述处理数据不平衡问题。3. 对于代码和技术讨论text-embedding-3-small可能和large效果差不多可以换用small模型重新embedding测试。MCP服务器连接失败Claude Code无法调用工具1. MCP服务器命令路径不正确。2. Bun或gBrain的依赖未正确安装。3. 端口冲突或权限问题。1. 在终端手动运行bun run src/cli.ts serve看是否能正常启动无报错。2. 确保在Claude Code的MCP配置中使用了正确的绝对路径。3. 检查Claude Code的MCP日志通常会有更详细的错误信息。6.3 性能优化与日常维护增量更新hermes-gbrain-bridge本身不存储状态不知道哪些文件已经处理过。因此每次全量运行export都会重新处理所有匹配过滤条件的文件。虽然gBrain的import和embed --stale可以避免重复处理未变化的块但桥接器的重复解析仍然有开销。对于日常同步可以编写一个简单的脚本记录上次成功导入的文件列表或时间戳下次只处理比这个时间戳新的文件。清理临时文件定期清理/tmp/gbrain-staging这类临时目录避免占用磁盘空间。可以在导入脚本的最后加入删除命令。监控Embedding成本尤其是首次全量导入时关注OpenAI API的使用量和费用。可以在gbrain embed命令前后记录时间并估算token消耗gBrain日志通常会输出处理的块数乘以平均每块token数可得近似值。这个项目本质上是一个高度定制化的数据管道。它提供的是一套经过实战验证的范式、一组可用的适配器以及一系列重要的经验教训。最理想的使用方式是理解其设计思想后根据你自己独特的AI工具栈和数据分布对其进行调整和扩展从而搭建起真正属于你个人的、无缝连接的AI记忆中枢。