Rowboat 技术解读：开源 AI 桌面同事的本地优先记忆、知识图谱与 MCP 扩展实战指南

Rowboat 技术解读：开源 AI 桌面同事的本地优先记忆、知识图谱与 MCP 扩展实战指南

【免费下载链接】rowboatOpen-source AI coworker, with memory项目地址: https://gitcode.com/GitHub_Trending/rowb/rowboat

Rowboat 是一款开源的桌面端 AI 同事（AI coworker），它把邮箱、会议、Slack 与助手对话持续索引进一个"活的"知识图谱，并借助内置的邮件客户端、笔记、浏览器、代码模式、会议记录与工作区等界面直接在这些知识上采取行动。本文以 docs/readme/README.fr.md 为骨架，结合仓库源码与测试，完整讲解 Rowboat 的安装配置、本地优先的记忆引擎、自带模型方案以及通过 MCP 扩展外部工具的方法，帮助你在自己的机器上把它跑起来并理解其底层实现。

核心设计理念：从"临时检索"到"持续记忆"

大多数 AI 工具是在每次请求时重建上下文——临时去搜索转录稿或文档。Rowboat 的做法截然不同：它维护长期存在的知识，而不是冷启动式检索。

具体表现为：

• 上下文随时间累积：每封邮件、每次会议、每段对话都在为记忆做加法；
• 关系显式且可检视：实体（人、组织、项目、主题）之间的关联是显式记录的，而不是藏在模型参数里；
• 笔记由你掌控：记忆以普通 Markdown 文件形式存在，你可以随时编辑，而不是锁在模型内部；
• 一切都在本机：没有专有格式，没有托管服务的锁定。

最终效果是"复利式"的记忆：每次新信息都会沉淀进既有图谱，而检索永远不是从零开始。这一点正是 Rowboat 区别于"临时检索"类工具的根基。

内置工作台全景：八个与 AI 协作的界面

Rowboat 将知识图谱作为"大脑"，围绕它提供了多块工作表面（work surfaces）。以下功能截图与功能说明来自仓库根目录的 README.md。

大脑：Obsidian 风格的活知识图谱

Rowboat 把邮件、会议、Slack 与助手对话索引进一个带反向链接（backlink）的活知识图谱，交互方式类似 Obsidian。图谱本身由knowledge子系统构建，源码位于 apps/x/packages/core/src/knowledge，入口编排器为build_graph.ts。

邮件客户端

内置邮件客户端将邮件分为"重要"与"其他"，并基于全部工作上下文自动为重要邮件撰写回复草稿。邮件同步与知识抽取在源码层面对应sync_gmail.ts（Gmail 拉取与保存为 Markdown）、classify_thread.ts（收件箱分类）以及knowledge/email/目录下的邮件处理逻辑。

后台代理（Background Agents）

你可以配置后台代理，在事件（如新邮件到达）或日程（如每天早上 8 点）触发。它们能连接工具、联网搜索、使用内置浏览器，并通过 Claude Code 或 Codex 编写代码。仓库中的 apps/x/packages/core/src/background-tasks 与 apps/x/packages/core/src/agent-schedule（含repo.ts、runner.ts、state-repo.ts）从源码层面支撑了这类事件/计划驱动的运行机制。

内置浏览器

Rowboat 自带一个与主浏览器隔离的浏览器，你和助手可以在网页任务上协作；因为隔离，你只登录希望开放给助手的账号。底层实现对应application/browser-control/、application/browser-skills/等模块。

会议笔记

本地会议记录器接入麦克风与扬声器，实时转写、在 Markdown 文件中总结会议并更新知识图谱。源码佐证可见knowledge/meeting-events.ts、knowledge/summarize_meeting.ts、knowledge/live-note/以及桌面端原生音频采集 apps/x/apps/main/native/mic-monitor.swift。

代码模式

代码模式允许你用 Claude Code 或 Codex 并行启动编码代理，并让 Rowboat 在需要的地方用全部工作上下文驱动它们。仓库内 apps/x/packages/core/src/code-mode 承载相关实现，配套设计文档见 CODE_MODE_ENGINES_PLAN.md。

Apps 与集成

你可以在 Rowboat 内创建自己的工作台 Apps，它们拥有全部工具与集成能力，并可分享给他人；同时内置对主流产品的一键集成。

安装与本地配置

Rowboat 提供 Mac / Windows / Linux 桌面版本，可通过官方下载渠道获取最新安装包（也可在发行版页面查看全部 release 文件）。安装完成后，所有个性化配置都存放在本机用户目录的~/.rowboat/下，其中 API Key 类配置文件统一放在~/.rowboat/config/中。

连接 Google 服务（Gmail、Calendar、Drive）

要连接 Google 服务，需要先在 Google Cloud Console 生成 OAuth 凭据（Client ID 与 Client Secret）。完整分步说明见仓库根目录的 google-setup.md，核心步骤如下：

1. 创建项目：打开 Google Cloud Console，新建一个项目（如命名为Rowboat Integration），并在顶部项目下拉框中选中它；
2. 启用所需 API：依次启用 Gmail API、Google Calendar API 与 Google Drive API，逐个点击Enable；
3. 配置 OAuth 同意屏幕：填写应用名称与支持邮箱，受众选择External，保持应用处于Testing模式即可（无需发布应用）；
4. 添加测试用户：Testing 模式下必须手动把你要连接的邮箱地址加入Test Users；
5. 创建 OAuth Client ID：选择Web application类型，并在Authorized redirect URIs中准确添加http://localhost:8080/oauth/callback——注意端口必须是 8080 且无尾部斜杠，Rowboat 的 OAuth 回调地址与之严格匹配；
6. 复制凭据：创建完成后复制Client ID与Client Secret，粘贴到 Rowboat 弹出的配置框中。

排障提示：如果浏览器显示 "Authorization Successful" 但应用随即报错（如 "invalid response encountered" 或 "response parameter "iss" (issuer) missing"），请检查应用日志中的完整报错、核对 Console 中 Authorized redirect URIs 是否精确一致，并确认应用类型确实是Web application（Desktop、UWP 等其他类型可能不提供 Client Secret 或处理重定向方式不同）。

语音输入：Deepgram

语音输入与语音笔记为可选功能。在~/.rowboat/config/deepgram.json中添加 Deepgram API Key 即可启用。源码侧，apps/x/packages/core/src/voice/voice.ts 通过readJsonConfig('deepgram.json')读取该配置；当未配置时，会提示创建~/.rowboat/config/deepgram.json并写入{ "apiKey": "<your-key>" }。桌面端还提供了原生麦克风监听实现 apps/x/apps/main/native/mic-monitor.swift。

语音输出：ElevenLabs

语音输出同样可选。在~/.rowboat/config/elevenlabs.json中添加 ElevenLabs API Key 即可启用，读取逻辑同样位于voice.ts（未配置时会明确报错并提示配置文件路径）。

网页搜索：Exa

Exa 研究型搜索为可选功能。在~/.rowboat/config/exa-search.json中添加 Exa API Key 即可使用。源码中，apps/x/packages/core/src/runtime/tools/domains/web.ts 会在 Web 工具执行时读取该文件路径。

外部工具：Composio 与 MCP

外部工具为可选能力：你可以添加任意 MCP 服务器，或通过在~/.rowboat/config/composio.json中添加 API Key 来使用 Composio 工具。apps/x/packages/core/src/composio/client.ts 中定义了CONFIG_FILE = path.join(WorkDir, 'config', 'composio.json')，即对应上述路径。

所有 API Key 文件的统一格式

无论哪种外部服务，配置文件格式完全一致：

{ "apiKey": "<key>" }

记忆引擎深入：知识图谱如何构建与维护

Rowboat 的记忆系统位于 apps/x/packages/core/src/knowledge，其系统设计说明 README.md 详细记载了从同步、建图到策展的完整流水线。

处理流程：同步 → 建图 → 策展

1. 同步（Sync）：sync_gmail.ts、sync_fireflies.ts等同步脚本从 Gmail、Fireflies 等源拉取数据，保存为 Markdown 文件，随后调用buildGraph(SYNC_DIR)触发建图；
2. 建图（buildGraph）：扫描源目录、过滤出新增或变更的文件，交由note_creation代理逐个抽取实体（人、组织、项目、主题），在WorkDir/knowledge/中创建/更新笔记，并把出现在多个文件中的同一实体信息合并。值得注意的实现细节是BATCH_SIZE = 1——每次代理运行只处理一个源文件，这是刻意为之，用于防止跨文件实体污染；
3. 策展（Curate）：note_creation只做追加，笔记会随时间膨胀变质，因此每天执行一次curateNotes()（"园丁"代理，见note_curation.ts）：把超过 60 天的旧活动折叠成月度摘要、将反复出现的模式提升为带日期的 Key facts / Assistant notes（即"反思"步骤）、把过时的开放事项移入 Dormant 列表、校正 frontmatter 与正文的漂移，并在 frontmatter 打上curated_at时间戳。策展的准入条件是：笔记活动条目 ≥ 8 条、自上次策展以来被修改过、且有 7 天冷却期；每次运行最多处理 8 条笔记，并作为 "Knowledge curation" 提交进版本历史。

变更检测：mtime + hash 混合策略

graph_state.ts使用混合的 mtime + hash 策略判断文件是否变化：

1. 先比较文件修改时间（mtime），mtime 未变 → 一定没变 → 跳过（快速路径）；
2. mtime 变了再计算内容哈希（SHA-256）复核：哈希未变说明是 mtime 假阳性 → 跳过；哈希变了才真正处理。

这样既高效（只哈希可能变化的文件），又可靠（确认真实内容变化）。状态持久化在WorkDir/knowledge_graph_state.json，结构形如：

{ "processedFiles": { "/path/to/file.md": { "mtime": "2026-01-07T10:30:00.000Z", "hash": "a3f5e9d2c8b1...", "lastProcessed": "2026-01-07T10:35:00.000Z" } }, "lastBuildTime": "2026-01-07T10:35:00.000Z" }

需要强制重建全部索引时，可调用resetGraphState()或直接删除状态文件。如果想替换变更检测逻辑，可以修改graph_state.ts保持接口不变、新建同接口的状态模块（如graph_state_v2.ts），或把策略抽象成ChangeDetectionStrategy对象注入buildGraph()。

笔记创建的严格度分级

笔记创建严格度由WorkDir/config/note_creation.json控制：

{ "strictness": "medium", "configured": true }

• High："会议建笔记，邮件只做充实"——邮件从不新建笔记，仅更新已有联系人的笔记，例外是熟人发来的暖介绍；
• Medium："两者都可建笔记，但邮件需有个性化内容"——过滤消费类服务、群发、通用推销，任何人的暖介绍都可建笔记；
• Low："广泛捕获，不错过任何潜在重要联系人"——为任何可识别的人类发件人建笔记，只跳过明显自动化邮件与新闻通讯。

邮箱侧的过滤在更上游完成：classify_thread.ts收件箱分类器会在邮件同步时把knowledge: extract | skip的判定盖进每封邮件的 frontmatter，build_graph.ts只接收extract文件，再叠加邮件回复门（Email Reply Gate）、直接互动、事务性、周度重要性等测试做多层过滤。首次运行时，strictness_analyzer.ts会根据你的邮件量与模式自动推荐档位（例如超过 100 个真实发件人 → 推荐 High，少于 30 个 → 推荐 Low）。

自带模型（BYOM）：本地或托管均可

Rowboat 兼容你偏好的任何模型配置：

• 本地模型：通过 Ollama 或 LM Studio 运行；
• 托管模型：自带 API Key 或自选供应商；
• 随时换模型：你的数据始终留在本地 Markdown 库（vault）中，切换模型不迁移、不丢失数据。

这意味着模型只是记忆的"读写引擎"，知识本身始终归属并保存在你本机。

通过 MCP 扩展 Rowboat

Rowboat 通过Model Context Protocol（MCP）连接外部工具与服务，从而接入搜索、数据库、CRM、支持工具、自动化乃至你自己的内部工具。文档中给出的示例生态包括：Exa（网页搜索）、Twitter/X、ElevenLabs（语音）、Slack、Linear/Jira、GitHub 等。

MCP 客户端的真实实现在 apps/x/packages/core/src/mcp/mcp.ts，值得关注的底层细节：

• 服务列表合并：effectiveServers()把mcp.json中的条目与从 spaces 组织注册表（spaces_orgs.json）派生出的条目在读取时合并，注册表是组织的唯一事实来源，派生条目在名称冲突时优先，避免陈旧文件条目遮蔽活跃注册表（防止旧 token 静默地以错误成员身份生效）；
• 三种传输方式：配置含command时使用StdioClientTransport（本地进程）；配置含url时优先尝试StreamableHTTPClientTransport（Streamable HTTP），失败则回退SSEClientTransport；同时支持转发配置中的headers（如Authorization），因此可连接带鉴权的远程 MCP 服务器；
• 连接缓存与自动重连：每个服务器按配置快照（configKey）缓存客户端，配置一旦变化（token 轮换、mcp.json 被编辑）会主动关闭旧连接并重新建立；
• 工具调用入口：listTools(serverName)与executeTool(serverName, toolName, input)分别对应 MCP 的tools/list与tools/call；连接与工具调用受你的 MCP 工具权限策略约束。此外forceCloseAllMcpClients()可在强制中断时立即拒绝挂起的 MCP 工具调用，客户端按需惰性重连。

Local-first：一切数据都归你

Rowboat 的设计原则是"本地优先"：

• 所有数据以普通 Markdown 形式本地存储；
• 没有专有格式，也没有托管服务的锁定；
• 你可以随时查看、编辑、备份或删除全部数据。

这也与知识图谱的设计互为表里：图谱状态、笔记、同步源文件都以 Markdown 或 JSON 形态落在WorkDir（即~/.rowboat/）下，整套系统对用户完全透明、可审计、可迁移。

小结

Rowboat 的价值在于把"有记忆的 AI"真正落地到桌面：以活知识图谱为大脑，用邮件、会议笔记、浏览器、代码模式、后台代理和 Apps 作为行动界面，同时以普通 Markdown 保证数据本地所有，用 MCP 保持工具生态的开放性。想要深入了解实现，可以从 apps/x/packages/core/src/knowledge/README.md（记忆引擎设计）、apps/x/packages/core/src/mcp/mcp.ts（MCP 客户端）以及 google-setup.md（Google 集成）三处入手继续探索。

【免费下载链接】rowboatOpen-source AI coworker, with memory项目地址: https://gitcode.com/GitHub_Trending/rowb/rowboat