CodeFire：为AI编程助手构建持久记忆层，实现连续协作开发

1. 项目概述：为AI编程助手构建持久记忆层

如果你和我一样，深度依赖Claude Code、Gemini CLI这类AI编程助手来辅助日常开发，那你一定遇到过这个让人头疼的问题：每次开启一个新的会话，AI助手就像得了“健忘症”，完全不记得我们上一个会话里讨论了什么、代码改到了哪一步、还有哪些待办事项。这种上下文断裂感，让AI助手从一个“持续协作的伙伴”退化成了一个“单次问答的工具”，极大地限制了它的生产力潜力。

CodeFire这个项目，就是为了彻底解决这个问题而生的。你可以把它理解为你AI编程助手的“外置大脑”或“第二工作区”。它是一个跨平台的桌面伴侣应用，通过MCP协议，为Claude Code、Gemini CLI、Codex CLI和OpenCode等主流AI编程CLI工具，提供了一个持久化的记忆层。简单来说，它让AI助手在会话之间“记住”了所有事情：你正在进行的项目、创建的任务、写下的笔记、以及每一次编码会话的上下文。

它的核心价值在于，将AI编程从“单次、离散的指令执行”模式，升级为“连续、有状态的协作”模式。想象一下，你昨天让AI助手重构了一个模块，今天打开新会话，它依然能清晰地知道项目的整体架构、待优化的任务列表，甚至能基于昨天的讨论继续提出建议。这种体验上的跃升，正是CodeFire带来的。

2. 核心架构与设计思路拆解

2.1 为什么选择MCP作为通信桥梁？

CodeFire的核心创新点，在于它巧妙地利用了MCP协议。MCP是Model Context Protocol的缩写，你可以把它看作是AI模型与外部工具、数据源之间的一种标准化“对话语言”。对于开发者而言，MCP最大的好处是解耦和标准化。

在CodeFire出现之前，如果你想给AI助手增加持久记忆功能，可能需要去魔改CLI工具的源码，或者编写复杂的插件，这种方式不仅侵入性强，而且每个工具都要适配一遍，维护成本极高。CodeFire选择了MCP这条“高速公路”，它自己作为一个独立的MCP服务器运行，而Claude Code等CLI工具则作为MCP客户端来连接它。这样一来，CodeFire只需要实现一次MCP服务端逻辑，所有支持MCP的AI编程工具就都能无缝接入，享受同样的记忆功能。这种设计极大地提升了项目的通用性和可维护性。

注意：MCP通信基于标准的stdio（标准输入/输出），这意味着所有数据交换都发生在本地进程间，无需网络监听，从根本上保障了代码和项目数据的安全性，避免了敏感信息外泄的风险。

2.2 双轨并行的技术实现策略

面对macOS、Windows、Linux三大主流桌面平台，CodeFire采用了一个务实且高效的双轨开发策略，这也是项目架构中最值得玩味的一点。

原生路线（macOS Apple Silicon）：对于苹果最新的ARM架构芯片平台，CodeFire选择了使用Swift和SwiftUI进行原生开发。原生应用的优势是显而易见的：极致的性能、丝滑的动画、完美的系统集成（如原生菜单栏、通知、快捷键）以及更低的内存占用。这为macOS用户提供了最好的体验，也符合苹果生态下用户对应用品质的期待。目前Swift版本处于Beta阶段，是主力开发平台。

跨平台路线（Windows/Linux/macOS Intel）：为了快速覆盖更广泛的用户群体，项目同时维护了一个基于Electron、React和TypeScript的版本。这个版本可以同时构建出Windows、Linux和Intel芯片Mac的应用。Electron方案的优势在于开发效率高，一套代码多端运行，能够快速实现功能同步。虽然性能和对系统特性的整合度不如原生应用，但在早期阶段，它能以最小的成本验证核心功能并收集用户反馈。目前Electron版本处于Early Alpha阶段。

关键的统一性设计：尽管技术栈不同，但两个版本共享了最核心的两样东西：数据库Schema和MCP协议。它们都读写同一个SQLite数据库文件（只是存储路径因系统而异），并且对外提供完全一致的MCP工具集。这意味着，无论你使用哪个平台的应用，你的任务、笔记、会话历史等数据都是互通的，AI助手通过MCP访问到的功能和信息也是一致的。这种设计保证了用户体验的核心统一，也为未来功能同步打下了坚实基础。

3. 功能模块深度解析与实操要点

3.1 持久化记忆与任务管理：从混乱到有序

CodeFire的“记忆”并非简单的聊天记录保存，而是一个结构化的项目管理体系。它自动扫描并索引你的项目目录（例如~/.claude/projects/），为每个项目创建一个独立的工作空间。

任务看板（Kanban Board）：这是项目管理的视觉核心。你可以像使用Trello或Jira一样，通过拖拽的方式管理任务卡片。每个任务都可以设置优先级、添加标签、编写详细描述。更重要的是，你可以在AI编程会话中，直接通过MCP工具创建或更新任务。例如，当AI助手帮你修复一个bug时，它可以自动创建一个“已完成”的任务卡片，并附上修改摘要；或者，当它发现一个潜在的架构问题时，可以创建一个“待调研”的高优先级任务。这种双向同步，让任务管理不再是事后的手动记录，而是编码流程的自然延伸。

会话监控与成本洞察：对于使用按Token计费的AI模型，成本控制是个现实问题。CodeFire的实时会话监控面板，会显示当前会话的Token消耗、预估成本以及AI调用的工具统计。这不仅能帮助你了解开销，更能让你反思与AI协作的效率。比如，你可能会发现，为了完成某个重构，AI调用了大量“读取文件”的工具，这或许提示你初始的上下文提供不够充分。

3.2 语义化代码搜索：超越grep的智能检索

传统的grep或IDE搜索是基于关键词的精确匹配，而CodeFire集成了基于向量的语义搜索。这背后需要你的OpenRouter API密钥来调用嵌入模型。

它的工作流程是这样的：CodeFire会对你项目中的代码文件进行分块（chunking），然后为每个代码块生成一个高维向量（embedding），并存储在本地的向量数据库中。当你进行搜索时，你的查询语句也会被转换成向量，系统通过计算向量之间的余弦相似度，找到语义上最相关的代码片段。

例如，你搜索“用户登录验证的逻辑”，它不仅能找到包含“login”、“auth”关键词的文件，还可能找到名为verifyUserCredentials的函数，或者一段关于JWT令牌处理的代码，即使它们没有直接包含你输入的词。这种搜索方式对于理解大型、陌生代码库特别有帮助，AI助手也能利用这个工具，更精准地定位它需要参考或修改的代码。

实操心得：语义搜索的准确性很大程度上取决于分块策略和嵌入模型。CodeFire目前可能采用固定的分块大小（如512个Token）。对于特别长或结构特殊的文件（如配置json、min.js），效果可能打折扣。一个常见的技巧是，对于非常重要的核心文件（如main.go或App.tsx），可以手动在CodeFire的笔记功能中为其添加架构说明，作为搜索的补充。

3.3 浏览器自动化：将AI的能力延伸到Web

这是CodeFire Electron版本的一个杀手级特性。它通过MCP暴露了超过40个浏览器操作工具，让你的AI编程助手不仅能写代码，还能操作浏览器。

想象这些场景：

• 数据抓取与测试：你可以让AI助手编写一个脚本，自动打开某个API文档页面，抓取最新的端点列表，并生成对应的TypeScript类型定义文件。
• 端到端测试生成：描述一个用户操作流程（如“注册新用户”），AI可以驱动浏览器模拟点击、输入，并验证页面结果，同时生成可复用的测试代码。
• UI对比与调试：让AI访问生产环境和本地环境，截图并对比差异，辅助CSS调试。

这些工具包括导航（navigate）、点击元素（click）、输入文本（type）、执行JavaScript（eval）、管理Cookies、截图等。这意味着你的AI助手获得了与真实用户类似的Web交互能力，极大地扩展了其自动化任务的边界。

3.4 内置编辑器与终端：打造一体化工作流

CodeFire内置了一个功能齐全的代码编辑器，支持多标签页、语法高亮、行号、查找替换，甚至还有未保存更改保护。这不仅仅是为了让你查看代码。编辑器集成了强大的右键菜单：你可以选中一段代码，一键将其转换为一个任务、一条笔记，甚至直接在集成的终端中运行相关的命令。

集成的标签页终端则让你无需离开CodeFire，就能执行git操作、运行测试、启动开发服务器。这种设计将“查看代码-管理任务-执行命令”的动线压缩在同一个窗口内，减少了上下文切换，提升了专注度。

Claude Code记忆文件编辑器：对于Claude Code用户，这是一个隐藏的宝藏功能。Claude Code会在项目目录下生成.claude记忆文件，用于在会话间保持记忆。CodeFire可以直接可视化地编辑这些文件，你可以手动整理、强化AI对项目关键决策的记忆，让它的“记忆力”更精准、更持久。

4. 从零开始的完整配置与接入指南

4.1 环境准备与安装

首先，根据你的操作系统，从GitHub Releases页面下载对应的安装包。对于macOS Apple Silicon用户，强烈推荐下载原生的Swift版本（CodeFire-macOS.zip），以获得最佳性能。下载后，解压并将应用拖入“应用程序”文件夹即可。

对于Windows用户，运行下载的CodeFire Setup.exe（NSIS安装程序）。Linux用户则可以使用提供的AppImage文件或.deb包进行安装。

安装完成后首次启动，CodeFire会引导你进行一些初始化设置，主要是请求必要的文件系统访问权限，以便它能自动发现你的项目。

4.2 核心配置：OpenRouter API密钥

CodeFire的许多智能功能，如AI对话、语义代码搜索、图像生成，都依赖于OpenRouter提供的AI模型服务。因此，配置API密钥是启用这些功能的关键一步。

1. 访问 OpenRouter官网 ，注册并获取你的API密钥。
2. 打开CodeFire，进入设置（Settings）。
3. 在Electron版本中，找到Engine标签页；在Swift版本中，找到CodeFire Engine标签页。
4. 将复制的API密钥粘贴到指定输入框内。

这个密钥会被安全地存储在本地。OpenRouter作为一个聚合平台，其优势在于你可以通过一个密钥访问众多模型（如Claude、GPT、Gemini等），并且通常有免费的初始额度供试用。

4.3 连接你的AI编程CLI

这是让AI助手“觉醒”记忆能力的关键步骤。CodeFire提供了两种方式：

一键安装（推荐）：最省事的方法是访问官方入门指南页面（codefire.app/getting-started），页面会根据你检测到的系统，提供对应CLI工具的一键安装按钮。这通常是一个自动化脚本，会帮你完成所有路径配置。

手动配置：如果你想更清晰地了解背后的原理，可以手动配置。以最流行的Claude Code为例，你需要在其配置中添加CodeFire的MCP服务器。关键在于找到CodeFire安装后，其MCP服务器可执行文件的路径。

# 对于 macOS (Swift 原生版本) # MCP服务器位于应用支持目录下的bin文件夹中 claude mcp add codefire ~/Library/Application\ Support/CodeFire/bin/CodeFireMCP # 对于 Linux (AppImage版本) # 首次启动CodeFire时，它会自动将MCP服务器同步到本地目录 claude mcp add codefire node ~/.local/share/CodeFire/mcp-server/server.js # 对于 Windows # 路径位于AppData目录下 claude mcp add codefire node "%APPDATA%\CodeFire\resources\mcp-server\server.js"

执行命令后，Claude Code会记录这个MCP服务器。之后每次启动Claude Code会话，它都会自动连接CodeFire，并发现其提供的63个工具。

4.4 注入系统指令：教会AI使用工具

仅仅连接MCP服务器还不够，你需要“教会”AI助手如何有效地使用这些新工具。这就是“系统指令”的作用。它本质上是一段预设的提示词（Prompt），会在每次会话开始时加载，定义AI的行为模式和可用工具集。

CodeFire为每个支持的CLI工具都准备了详细的系统指令模板。你需要根据你使用的工具，找到对应的模板文件（如codefire-claude-md-setup.md），将其中的大段文本复制到你CLI工具的系统指令配置文件中。

• Claude Code：指令通常添加到~/.claude/config文件或指定的提示词文件中。
• Gemini CLI：修改~/.gemini/settings.json文件。
• 其他工具：参考对应指南。

这些指令内容非常详细，涵盖了从如何开始一个会话（“先使用get_current_project了解上下文”），到如何管理任务、记笔记、使用浏览器自动化等所有工作流。加入这些指令后，你的AI助手就会从一个“通用程序员”变成一个“精通CodeFire的专家协作者”。

4.5 启动你的第一个有记忆的会话

完成以上所有步骤后，就可以开始体验了。

1. 在CodeFire中，通过菜单或拖拽的方式，打开你正在开发的项目文件夹。
2. 在终端中，像往常一样启动你的AI编程CLI（如claude）。
3. 神奇的事情发生了：在CLI会话中，你可以直接输入“我们当前项目有哪些待办任务？”，AI会通过CodeFire的MCP工具查询并列出任务看板上的内容。你可以说“创建一个高优先级任务，标题是‘修复用户登录页面的CSS错位问题’”，AI会立即在CodeFire的看板上创建对应的卡片。

现在，你的AI助手拥有了跨越会话的记忆和强大的外部工具集，真正的持续协作开始了。

5. 开发构建与贡献指南

5.1 从源码构建

如果你是一名开发者，想深入了解CodeFire，或者希望为项目贡献代码，可以从源码构建。

构建Swift版本（macOS）：

# 进入Swift项目目录 cd swift # 使用Swift包管理器进行发布构建 swift build -c release

构建产物会出现在.build/release/目录下。更详细的代码签名、公证等发布流程，需要参考swift/README.md文件。

构建Electron版本（跨平台）：

# 进入Electron项目目录 cd electron # 安装所有依赖，包括需要本地编译的Node原生模块 npm install # 启动开发模式，运行Vite开发服务器和Electron npm run dev # 运行测试套件（基于Vitest） npm test # 编译TypeScript和前端资源 npm run build # 为当前操作系统打包分发版 npm run dist # 也可以指定平台打包 npm run dist:win # 生成Windows安装包 npm run dist:linux # 生成Linux AppImage和deb包 npm run dist:mac # 生成macOS DMG

Electron项目的架构非常清晰，严格遵循了主进程、预加载脚本、渲染进程的分离模式，确保了应用的安全性和可维护性。所有共享的类型定义和工具函数放在@shared路径下，便于复用。

5.2 核心数据结构与MCP工具剖析

理解CodeFire，需要了解其核心的SQLite数据库 schema。虽然具体表结构可能演进，但其核心思想围绕以下几个实体：

• Projects：项目表，记录被索引的每个代码仓库或文件夹。
• Sessions：会话表，关联到项目，记录每次AI编码会话的起止时间、Token消耗等元数据。
• Tasks：任务表，包含标题、描述、状态（待办、进行中、完成等）、优先级、标签，关联到项目和会话。
• Notes：笔记表，用于记录架构决策、踩坑记录等自由格式内容，支持Markdown。
• Code Chunks：代码块表，存储文件分块后的内容及其对应的向量嵌入（embedding），用于语义搜索。

MCP服务器（src/mcp/）是一个独立的Node.js进程，它通过标准输入输出与AI CLI通信。它实现了63个工具，每个工具对应一个TypeScript函数。当AI助手想要“列出任务”时，它会通过MCP协议发送一个调用tasks_list工具的请求，MCP服务器收到后，执行对应的函数，查询数据库，并将结果格式化为MCP规定的格式返回给AI。

5.3 如何有效参与贡献

CodeFire是一个活跃的开源项目，尤其欢迎对Windows和Linux Electron版本感兴趣的贡献者。如果你希望参与，可以从以下几个方面入手：

1. 测试与反馈：对于Early Alpha的Electron版本，在不同操作系统、不同硬件配置上进行测试，报告Bug或体验问题，是最直接的帮助。项目讨论区有专门的 Testers Wanted 主题。
2. 功能开发：项目维护者列出了优先级较高的贡献领域：
   • 语义搜索增强：实现本地嵌入模型回退（如使用all-MiniLM-L6-v2），减少对OpenRouter的依赖；改进代码分块算法；增加重新排序（reranking）逻辑以提升搜索结果相关性。
   • 浏览器自动化：增强网络请求捕获、会话状态持久化（保存Cookie、LocalStorage）、性能指标（Web Vitals）收集等功能。
   • 测试覆盖：为Swift代码编写单元测试，为MCP协议编写集成测试，为Electron应用编写端到端（E2E）测试，并完善CI/CD的多平台构建矩阵。
   • 跨平台功能对齐：将Swift版本上成熟好用的功能（如某些原生交互特效）移植到Electron版本，反之亦然。
   • MCP工具扩展：开发新的MCP工具，例如集成更复杂的Git操作（变基、二分查找）、添加自定义工具插件机制、暴露更多应用指标等。
3. 代码规范：在提交PR前，请务必阅读CONTRIBUTING.md文件，了解项目的代码风格、分支命名约定和提交信息规范。保持代码风格统一对项目长期健康至关重要。

6. 常见问题与实战排错实录

在实际使用和配置CodeFire的过程中，你可能会遇到一些典型问题。以下是我在深度使用中总结的排查思路和解决方案。

6.1 MCP连接失败

问题现象：启动AI CLI后，提示无法连接CodeFire MCP服务器，或者AI助手表示找不到CodeFire提供的工具。

排查步骤：

1. 确认CodeFire正在运行：MCP服务器是随着CodeFire主应用启动的。确保CodeFire应用已打开并在后台运行。
2. 检查MCP服务器路径：这是最常见的问题。使用claude mcp list命令查看已配置的MCP服务器。确认codefire对应的command路径完全正确。特别注意路径中的空格和转义字符。
   • macOS Swift版：路径通常是~/Library/Application Support/CodeFire/bin/CodeFireMCP。确保该文件存在且有可执行权限（chmod +x）。
   • Electron版：路径因平台而异，务必参照官方指南。Linux AppImage版需要确保首次启动时同步完成。
3. 验证MCP服务器本身：你可以尝试在终端中直接运行MCP服务器的命令，看它是否正常启动而不立即退出。例如：~/Library/Application\ Support/CodeFire/bin/CodeFireMCP。正常情况下，它会挂起等待标准输入。
4. 检查CLI配置：确认系统指令已正确添加到你的CLI配置文件中。有时格式错误（如JSON括号不匹配）会导致整个配置失效。

6.2 语义搜索返回空或不准

问题现象：在CodeFire内或通过AI使用语义搜索功能，找不到预期的代码，或者结果不相关。

排查与优化：

1. 确认API密钥与额度：首先检查设置中填入的OpenRouter API密钥是否有效，以及该密钥是否有足够的额度调用嵌入模型。
2. 重建搜索索引：CodeFire的索引可能不是实时的。尝试在CodeFire的设置中，找到与“搜索”或“索引”相关的选项，触发一次针对当前项目的重新索引。
3. 优化查询语句：语义搜索对查询语句的描述方式敏感。尝试使用更自然、更具描述性的语言，而不是单个关键词。例如，用“处理用户登录成功后跳转的函数”代替“login redirect”。
4. 结合关键词搜索：CodeFire采用的是“向量+关键词”混合搜索。如果你的查询包含非常特定的技术名词（如函数名useEffect、库名axios），关键词匹配可能更有效。在搜索时可以考虑将两者结合。

6.3 浏览器自动化工具无法使用

问题现象：在Electron版本中，AI助手无法调用浏览器工具，或调用后无反应。

排查步骤：

1. 确认版本：浏览器自动化目前仅支持Electron版本。Swift原生版本暂未集成此功能。
2. 检查权限：某些浏览器操作（如截图、访问特定网站）可能需要额外的权限确认。确保没有浏览器窗口被拦截。
3. 查看日志：CodeFire的Electron版本通常有开发者工具窗口或日志文件输出。打开开发者工具（通常Ctrl+Shift+I或Cmd+Option+I），查看控制台是否有相关错误信息。
4. 简化操作：先从最简单的操作开始测试，如navigate到一个公开网站（如https://example.com），再逐步尝试更复杂的交互。

6.4 性能问题与资源占用

问题现象：应用运行缓慢，特别是索引大型项目时，或者内存占用过高。

优化建议：

1. 限制索引范围：在设置中，排除不需要索引的目录，如node_modules,build,dist,.git等。这能极大提升索引速度和降低内存占用。
2. 选择原生版本：如果你是macOS Apple Silicon用户，务必使用Swift原生版本，其在性能和资源效率上远超Electron版本。
3. 管理项目数量：CodeFire会为每个打开过的项目维护索引。定期在应用内清理不再需要的旧项目索引。
4. 关注数据库大小：SQLite数据库文件（codefire.db）会随着使用增长。如果过大，可以考虑在备份后，通过CodeFire的维护功能进行清理或优化。

6.5 数据同步与备份

核心提醒：CodeFire的所有数据（任务、笔记、索引）都存储在本地的SQLite数据库文件中。它本身不提供云同步功能。

备份策略：

• 手动备份：定期复制数据库文件（位于各平台的应用支持目录下）到云盘或其他安全位置。
• 版本控制：对于非常重要的项目笔记和任务描述，可以考虑将其手动导出为Markdown文件，并提交到项目的Git仓库中，实现版本化管理。
• 未来可能性：社区可能会开发基于Git或第三方云存储的同步插件，这需要关注项目后续发展。

CodeFire解决的是一个非常具体且痛点的需求，它通过工程化的思路，将MCP协议的潜力转化为实实在在的开发者生产力工具。它的双轨开发模式、清晰的数据架构以及对现有工作流的最小侵入性设计，都体现了其成熟度。无论你是想彻底告别AI助手的“会话失忆”，还是希望探索AI与本地工具深度集成的新范式，CodeFire都提供了一个极具价值的起点和参考实现。