企业官网建设流程全解析

1. 项目概述：为AI编程助手装上“持久记忆”

如果你和我一样，日常重度依赖Claude Code、Cursor这类AI编程助手来写代码、调试、重构，那你一定也遇到过这个让人头疼的问题：每次新开一个会话，AI助手就像得了“健忘症”，完全不记得你上一个会话做了什么。你不得不花时间重新描述项目背景、解释当前的文件结构、复述刚刚遇到的错误。这种上下文断裂不仅打断了工作流，更浪费了大量宝贵时间。

Agent Recall这个开源项目，就是为了彻底解决这个问题而生的。你可以把它理解为一个运行在你本地的“记忆中枢”，它能在后台默默记录你和AI助手（Agent）之间的所有交互，包括执行的命令、修改的文件、讨论的技术决策，然后在下一次会话开始时，自动将这些关键上下文“喂”给AI。这样一来，你的AI助手就拥有了跨会话、跨项目的“持久记忆”，能够真正地“接着上次的活儿继续干”。

它的核心价值在于“连续性”。想象一下，你下午用Claude Code调试一个复杂的API认证问题，晚上换到Cursor里想继续优化，Cursor里的AI助手能立刻知道：“哦，用户正在处理/auth路由的JWT令牌刷新逻辑，下午我们刚修复了expiresIn参数解析的时区问题。” 这种无缝衔接的体验，才是智能助手应有的样子。Agent Recall目前已经支持了主流的AI编程环境，包括Claude Code、Cursor、Codex CLI、Gemini CLI和OpenCode，并且让它们共享同一份记忆数据库，实现了真正的生态互通。

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

2.1 设计哲学：从“失忆的临时工”到“有记忆的长期伙伴”

传统AI编程助手的工作模式，本质上是一个无状态的“临时工”。每次会话都是一次全新的雇佣，它没有关于你、关于这个项目、关于过往工作的任何记忆。Agent Recall的设计目标，就是通过引入一个持久化的记忆层，将这个“临时工”转变为一个“长期伙伴”。

这个转变背后有几个关键的设计考量：

1. 状态外置：AI模型本身无法持久化存储信息，那么就把状态存储在模型外部。Agent Recall选择使用本地的SQLite数据库作为记忆仓库，完全由用户掌控，无需担心隐私和数据泄露。
2. 观察而非记录：它并不录制屏幕或记录所有击键，而是通过各平台提供的“钩子”（Hooks）系统，智能地捕获有意义的“观察结果”（Observations）。比如，当AI助手执行了一个git commit -m "fix: auth token validation"命令，或修改了src/auth.js文件，这些会被捕获。而像ls、pwd这样的简单命令则会被过滤掉，避免记忆被无用信息污染。
3. 结构化摘要：原始的操作记录是冗长且杂乱的。Agent Recall会利用一个轻量级的AI模型（默认是Claude Haiku）对捕获的原始观察进行实时压缩和总结，生成结构化的摘要。例如，将一系列“创建文件A、修改文件B、运行测试C”的操作，总结为“实现了用户登录模块的初始框架并进行了冒烟测试”。这极大地提升了记忆的“信息密度”，使得在后续会话中注入的上下文更加精炼有效。

2.2 系统架构：分层与适配

Agent Recall的架构清晰且模块化，大约70-80%的核心业务逻辑是平台无关的，这保证了其良好的可扩展性和维护性。

应用层（平台适配器） ├── Claude Code 插件 ├── Cursor Shell Hooks ├── Codex CLI Hooks ├── Gemini CLI Hooks └── OpenCode 插件 ↓ (通过HTTP API通信) 服务层（Worker HTTP API，运行于 localhost:37777） ├── 用户/Agent人格管理 ├── 记忆的捕获、压缩、存储 ├── 会话恢复与任务管理 ├── 记忆的检索与提升 └── 归档与搜索接口 ↓ (操作核心数据) 数据层（SQLite + 向量数据库） ├── 结构化观察摘要表 ├── 项目与全局记忆分层表 ├── 会话归档与全文搜索索引（FTS5） └── （可选）ChromaDB向量索引（用于语义搜索）

各层详解：

1. 平台适配器层：这是与各个AI编程工具交互的“薄层”。每个适配器通常只有80行左右的代码，其唯一职责就是监听该工具的生命周期事件（如会话开始、工具调用结束），并将事件发送到中心服务（Worker API），或者从中心服务获取记忆上下文并按照该工具要求的格式注入。这种设计使得支持一个新平台变得非常快速。

2. Worker服务层：这是项目的大脑，一个常驻后台的HTTP服务（使用Express.js构建）。它提供了约18个RESTful端点，处理所有核心业务：

   • POST /api/observations：接收来自各平台的原始观察数据。
   • POST /api/compress：调用AI模型对观察进行压缩摘要。
   • GET /api/context：根据当前项目，查询并组装需要注入的上下文。
   • 此外，还负责人格引导、任务恢复、记忆提升等高级功能的逻辑。

3. 数据持久层：以SQLite为核心，所有数据存储在~/.agent-recall/agent-recall.db单一文件中。使用FTS5扩展提供对归档会话的快速关键词搜索。同时，项目集成了可选的ChromaDB，用于实现基于向量相似度的语义搜索（例如，“查找关于用户认证的工作”，即使记忆里没有“认证”这个词，也能找到相关的会话）。

提示：这种中心化服务+多前端适配的架构，是典型的“微内核”模式。它的最大优势是核心功能稳定统一，前端适配灵活轻便。当你自己在设计类似的多平台工具时，可以借鉴此思路，将核心逻辑与UI/交互层彻底解耦。

2.3 关键技术选型背后的思考

• 为什么用SQLite而不是其他数据库？对于Agent Recall这类桌面端、单用户优先的工具，SQLite几乎是完美选择。它无需安装和配置独立的数据库服务器，一个文件就是整个数据库，备份、迁移极其方便。其FTS5扩展提供了开箱即用的全文搜索能力，性能对于个人使用场景绰绰有余。选择SQLite体现了“工具应该适应环境，而非让环境适应工具”的务实哲学。

• 为什么默认使用Claude Haiku进行摘要压缩？压缩观察是一个高频、低延迟的操作。Haiku模型在速度、成本和效果上取得了最佳平衡。它能在毫秒级内完成摘要，且API调用成本极低，确保了记忆捕获的实时性，不会拖慢主AI助手的工作流。这是一个经典的“合适即最好”的选型案例。

• 采用HTTP API进行内部通信的优势？虽然进程间通信（IPC）方式很多，但HTTP API提供了最大的灵活性和可调试性。你可以直接用curl命令测试任何一个端点，也可以用任何语言编写脚本与记忆服务交互。这为未来的功能扩展（比如开发独立的桌面GUI）或第三方集成打开了大门。

3. 核心功能深度剖析与实操指南

3.1 人格引导系统：让AI助手真正“认识你”

这是Agent Recall最让我惊艳的功能之一。它不仅仅记忆“事”，更试图定义“人”——包括用户你和AI助手它自己。

引导式面试流程详解：

安装并首次启动服务后，访问http://localhost:37777，你会被引导开始一个三回合的对话式面试：

1. 第一轮：定义用户核心身份

   • 问题示例：“你希望我怎么称呼你？你的主要技术角色是什么？（例如：全栈工程师、数据科学家、学生）”
   • 你的回答示例：“叫我Alex。我是一名专注于Node.js和React的全栈开发，目前在做一个SaaS项目。”
   • 幕后原理：这轮信息会被构造成一个基础的用户画像（User Profile），存储在数据库中。之后，AI助手在生成回复时，可以带上“为Alex，一位全栈工程师”这样的认知，使其回答更具针对性。

2. 第二轮：明确工作风格与偏好

   • 问题示例：“你通常希望我在协作中扮演什么角色？是严格的代码审查者、富有创造力的搭档，还是高效的执行者？”
   • 你的回答示例：“我希望你是一个注重细节的审查者，能主动指出潜在的bug和性能问题，同时也能提供替代方案。”
   • 幕后原理：这定义了AI助手的行为基调（Agent Persona）。这个“人格”会被编码成一段系统提示词（System Prompt），在每次会话开始时注入。例如，提示词中会包含“你是一个注重细节的代码审查者，擅长发现潜在问题...”。

3. 第三轮：为AI助手命名与赋予个性

   • 问题示例：“你希望给这位有记忆的助手起什么名字？你希望我们的协作氛围是怎样的？”
   • 你的回答示例：“就叫它‘CodeMate’吧。协作氛围希望是专业但轻松的，像一位靠谱的同事。”
   • 幕后原理：这完成了AI助手自我意识的构建。它现在有了名字（CodeMate）和基本的交互风格。这极大地增强了交互的沉浸感和连续性。

实操心得：这个引导过程至关重要，不要草率填写。你定义的“人格”会直接影响后续所有AI助手的输出风格。我建议花点时间思考，答案尽量具体。例如，与其说“帮我写代码”，不如说“我经常需要重构遗留代码，请优先考虑可读性和向后兼容性”。

3.2 记忆的分层与继承：全局记忆 vs. 项目记忆

Agent Recall没有采用扁平的记忆池，而是设计了一个精巧的两层记忆结构，这非常符合软件开发的实际场景。

• 全局记忆：存储在所有项目中都通用的知识、偏好和决策。
  • 例子：“Alex不喜欢使用var声明变量，总是偏好const和let。” “Alex在配置ESLint时，总是会加上prettier插件。”
  • 存储位置：数据库中的global_observations表。
• 项目记忆：只与特定项目相关的上下文。
  • 例子：在“电商后端项目”中，“我们决定使用Stripe作为支付网关，并且已经完成了/api/payment/webhook端点的初步实现。”
  • 存储位置：数据库中的project_observations表，并通过project_id与项目关联。

继承与覆盖规则：当为一个特定项目查询记忆时，Agent Recall会同时拉取全局记忆和该项目下的记忆。如果两者存在冲突（比如全局记忆说“喜欢用双引号”，但本项目早期决定“使用单引号”），则项目记忆优先于全局记忆。这个策略保证了项目特定约定的权威性。

如何设置项目？Agent Recall会自动根据你当前工作目录的路径来识别项目。通常，它会把一个Git仓库的根目录视为一个项目。你也可以在项目的.agent-recall目录下放置一个config.json文件来显式定义项目名称和设置。

// 项目根目录/.agent-recall/config.json { "projectName": "my-awesome-saas-backend", "memorySyncPolicy": "ask" // 记忆提升策略：ask, always, never }

3.3 记忆提升：从项目经验到全局知识

这是将记忆系统从“记录仪”升级为“学习系统”的关键功能。当你在一个项目中解决了一个具有普适性的问题时，你可以选择将其“提升”到全局记忆。

工作流程：

1. 检测：Agent Recall会分析项目记忆，尝试识别出可能具有通用价值的模式或决策（例如，引入了一个新的、高效的错误处理中间件）。
2. 提示：根据你在项目配置中设置的memorySyncPolicy，它会采取不同行动：
   • ask（默认）：弹出提示，询问你是否将某个发现提升为全局知识。
   • always：自动提升。
   • never：不提升。
3. 记录：如果你同意提升，这条记忆会被复制到全局记忆表，并标记其来源项目。之后，你在开启任何新项目时，都可能从这条全局知识中受益。

注意事项：自动提升（always）需谨慎使用。我建议初期使用ask模式，手动审核每一次提升。因为有些决策在特定项目上下文里是合理的，但可能不适用于其他项目（比如，在一个小型原型项目中决定不使用TypeScript，这就不应提升为全局偏好）。

3.4 会话恢复与任务管理

这是解决“工作被打断”痛点的直接功能。当你关闭AI编程工具或结束一个会话时，Agent Recall会将当前正在进行的“活跃任务”标记为暂停。

恢复场景示例：假设你正在用Claude Code调试一个登录失败的问题，任务描述是“排查用户登录时返回500错误的原因”。中途你关掉了Claude Code去开会。 一小时后，你打开Cursor，开始同一个项目。Cursor的AI助手（通过Agent Recall的上下文注入）在开场白中就会说：

“欢迎回来，Alex。我们之前正在处理‘排查用户登录时返回500错误的原因’。最新的进展是：我们检查了auth.service.js，发现validatePassword函数在比较哈希值时存在异步问题。接下来是否需要继续深入这个函数，还是想先查看相关的日志？”

背后的实现：

1. 任务跟踪：Agent Recall会从对话和操作中自动提取或由用户手动指定一个“活跃任务”。
2. 状态保存：任务名称、最后一条相关观察（进度）、时间戳被保存在active_tasks表中。
3. 上下文组装：当新会话在同一项目中被检测到时，服务会查询该项目的活跃任务，并将任务信息连同最近的相关观察摘要，一起打包进注入的上下文里。

手动管理任务：你也可以通过查看器UI或API主动管理任务：

• POST /api/recovery/active-task：手动设置或更新当前任务。
• POST /api/recovery/complete-task：标记任务为完成，并将其归档。

4. 详细安装、配置与平台集成实战

4.1 基础环境准备与项目部署

假设你的系统已经安装了Node.js (>=18) 和 Git。

# 1. 克隆仓库 git clone https://github.com/d-wwei/agent-recall.git cd agent-recall # 2. 安装依赖并构建 npm install npm run build # 这会编译TypeScript代码，生成dist目录。 # 3. 启动记忆服务（Worker） npm run worker # 保持这个终端窗口运行，服务将在 localhost:37777 启动。 # 首次运行会自动创建 ~/.agent-recall/ 目录和数据库。

此时，打开浏览器访问http://localhost:37777，你应该能看到Agent Recall的Web查看器界面，并可能自动开始引导面试流程。

4.2 平台集成详解（以Claude Code和Cursor为例）

Claude Code 集成：Claude Code 通过其插件市场安装“Claude Mem”插件（Agent Recall的前身/基础）。Agent Recall的安装脚本会自动处理与这个插件的集成。

# 在agent-recall项目根目录下执行 npm run sync-marketplace

这个命令会做两件事：

1. 将编译好的Agent Recall核心模块链接到Claude Code的插件目录。
2. 配置Claude Code的additionalContext功能，使其在每次会话开始时，向localhost:37777的API请求记忆上下文。

实操要点：确保Claude Code应用已经关闭，再运行此命令。安装完成后重启Claude Code。你可以在Claude Code的设置中搜索“memory”或“context”来确认插件已启用。

Cursor 集成：Cursor的集成方式略有不同，它通过Shell Hooks实现。

# 在agent-recall项目根目录下执行 npm run cursor:install

这个脚本会在你的~/.cursor目录下创建或修改规则文件，并设置一个Shell钩子。当Cursor启动时，这个钩子会执行一个脚本，该脚本会获取当前项目的记忆上下文，并将其写入Cursor能读取的一个特定位置（通常是.cursor/rules/下的一个文件）。

验证集成是否成功：

1. 分别打开Claude Code和Cursor，进入同一个Git项目目录。
2. 在Claude Code中，通过对话或操作让Agent Recall记录一些内容（例如，让AI助手创建一个文件并解释）。
3. 关闭Claude Code，打开Cursor。
4. 在Cursor的AI聊天框中，问一个类似“我们之前在这个项目里做过什么？”的问题。如果集成成功，Cursor的AI应该能提及刚才在Claude Code中记录的内容。

4.3 核心配置文件解析

Agent Recall的主要配置位于~/.agent-recall/settings.json。首次运行服务后会自动生成。

{ "workerPort": 37777, "databasePath": "/Users/yourname/.agent-recall/agent-recall.db", "aiModel": { "compression": "claude-haiku-4-5-20251001", "summarization": "claude-sonnet-3-5-20241022" }, "chroma": { "enabled": false, "host": "localhost", "port": 8000 }, "platforms": { "claudeCode": { "enabled": true, "contextInjectionMode": "automatic" }, "cursor": { "enabled": true } } }

• aiModel.compression：用于压缩观察的模型。Haiku是默认且推荐的，速度快、成本低。
• aiModel.summarization：用于生成更复杂摘要或分析的模型（某些高级功能使用）。Sonnet能力更强但更慢更贵。
• chroma.enabled：是否启用ChromaDB向量搜索。除非你有特定需求，否则保持false。SQLite的FTS5关键词搜索对于代码和日志检索已经非常高效。
• 你可以在这里手动启用或禁用某个平台的集成。

4.4 Web查看器的使用技巧

http://localhost:37777不仅是设置入口，更是强大的记忆管理仪表盘。

• 时间线视图：按时间顺序展示所有观察记录，颜色区分不同项目。点击任何一条记录可以展开看详情和AI生成的摘要。
• 搜索框：支持关键词搜索。输入“auth”、“error”、“refactor”可以快速找到相关会话。
• 项目筛选器：在侧边栏可以选择只看某一个项目的记忆。
• 任务面板：显示当前所有项目的活跃任务和中断的任务队列。
• 设置：可以在这里重新运行引导面试、查看系统状态、清理旧数据。

一个实用场景：当你隔了很久回到一个项目，可以先打开查看器，在搜索框里输入项目名或关键词，快速“重温”上次的工作上下文，然后再打开IDE和AI助手，效率倍增。

5. 常见问题排查与进阶技巧

5.1 安装与启动问题

问题1：运行npm run sync-marketplace或npm run cursor:install时报错“权限被拒绝”或“路径未找到”。

• 原因：脚本需要访问IDE的安装目录或配置文件目录，可能因权限或自定义安装路径导致。
• 解决：
  1. 手动查找路径：找到你的Claude Code或Cursor的用户配置目录。通常位于：
     • macOS:~/Library/Application Support/ClaudeCode/或~/.cursor/
     • Linux:~/.config/ClaudeCode/或~/.cursor/
     • Windows:%APPDATA%\ClaudeCode\或%USERPROFILE%\.cursor\
  2. 手动链接：将Agent Recall的dist目录（或cursor-hooks目录）中的必要文件，复制或软链接到上述目录的对应位置。具体需要复制的文件，请参考项目scripts/目录下的安装脚本内容。

问题2：服务启动成功，但AI助手无法获取记忆（无上下文注入）。

• 排查步骤：
  1. 检查服务状态：访问http://localhost:37777，确保页面能打开，查看器有内容。
  2. 检查IDE插件/钩子：在Claude Code设置中确认“Claude Mem”插件已启用。在Cursor中，检查~/.cursor/rules/目录下是否存在与agent_recall相关的规则文件。
  3. 查看日志：在运行npm run worker的终端里查看输出，或者查看~/.agent-recall/下的日志文件，看是否有来自IDE的请求错误。
  4. 测试API：打开终端，运行curl http://localhost:37777/api/persona。如果返回你的个人信息JSON，则服务正常。再运行curl http://localhost:37777/api/context?projectPath=/your/project/path，看是否能返回项目上下文。

5.2 记忆捕获不完整或不准

问题：AI助手执行了很多操作，但查看器里记录很少。

• 原因：Agent Recall有内置的过滤器，会跳过它认为“无价值”的简单工具调用（如ls,pwd,echo），只捕获可能产生持久影响的“观察”（如文件编辑、Git操作、测试运行、包安装等）。
• 调整：目前过滤逻辑是硬编码的，旨在平衡记忆价值和噪音。如果你认为重要操作被遗漏，可以查阅项目源码中关于“工具调用过滤”的部分，但修改需要一定的开发能力。对于绝大多数开发场景，默认的过滤策略是合理的。

问题：AI生成的摘要太笼统或不准。

• 原因：摘要质量依赖于压缩模型（默认Haiku）的理解能力。对于非常复杂或模糊的操作序列，摘要可能不够精确。
• 解决：
  1. 在查看器中，你可以手动编辑某条观察的摘要，使其更准确。
  2. 考虑在settings.json中将aiModel.compression临时换为更强大的模型（如claude-sonnet-...），但这会增加延迟和成本。更适合用于事后批量重摘要关键会话。

5.3 性能与资源管理

问题：Agent Recall服务会拖慢我的系统或IDE吗？

• 解答：Worker服务本身非常轻量，内存占用通常在几十MB。主要的性能影响可能来自：
  1. AI压缩调用：每次捕获观察后的实时压缩会调用Claude API。使用Haiku模型且网络正常时，延迟极低（<1秒），且发生在后台，不影响前台操作。
  2. 数据库增长：长期使用后，SQLite数据库文件会变大。如果发现搜索变慢，可以定期通过查看器UI的“设置”进行旧数据归档或清理。
• 建议：对于性能敏感的机器，可以调整settings.json，增加压缩的延迟批次处理，或者更激进地过滤观察类型。但普通开发环境无需担心。

5.4 进阶使用技巧

技巧1：利用项目配置实现环境隔离如果你同时开发多个技术栈迥异的项目（比如一个Go微服务和一个React前端），可以为它们创建不同的.agent-recall/config.json文件，指定不同的memorySyncPolicy（如never），防止两个项目的技术决策互相污染全局记忆。

技巧2：手动创建高质量“种子记忆”在开始一个新项目时，不要完全依赖自动捕获。你可以主动通过查看器的“添加观察”功能，或直接向/api/observations发送API请求，手动插入一些关键的“种子记忆”。例如，插入一条观察：“本项目决定使用pnpm作为包管理器，并采用Monorepo结构，所有包位于packages/目录下。” 这能让AI助手从一开始就建立在正确的认知基础上。

技巧3：结合脚本实现自动化由于所有功能都暴露为HTTP API，你可以编写Shell脚本或使用工具如curl、httpie来与记忆服务交互。

• 示例：在每天下班前，运行一个脚本自动将当前活跃任务标记为“暂停”，并生成一份今日工作摘要。

  # 假设你的项目路径是 /Projects/MyApp PROJECT_PATH="/Projects/MyApp" curl -X POST http://localhost:37777/api/recovery/complete-task \ -H "Content-Type: application/json" \ -d "{\"projectPath\": \"$PROJECT_PATH\", \"note\": \"End of day auto-pause\"}"

技巧4：处理多分支开发Agent Recall的记忆是基于项目路径的。如果你在同一个项目里切换Git分支，由于路径没变，记忆是共享的。这通常是有益的（分支间的知识可复用）。但如果你希望严格隔离，一个变通方法是在切换分支后，临时在项目根目录创建一个软链接到另一个路径，然后在新的路径下打开IDE，Agent Recall会将其视为一个“新项目”。不过，这需要更复杂的流程管理。