Sugar：给 AI 编码代理装上"持久记忆"

当 AI 每次重启都"失忆"……

你在一个 AI 编程代理（Claude Code）上花了三周时间，反复叮嘱它"我们的代码用 RS256 签发 JWT，15 分钟过期，参见 auth/tokens.py"、"遇到导入错误先检查 init.py"——结果第二天重启会话，一切归零，它又变回那个一无所知的"陌生人"。

这是每个 AI 编程代理用户的共同痛点：会话之间的上下文无法保留，导致重复劳动和体验割裂。Sugar 正是为解决这一根本矛盾而生。

一个本地优先的记忆层

Sugar 的核心理念是三个关键词：本地化（Local-first）、跨会话（Cross-session）、可选的自主执行（Autonomous execution）。

它的设计哲学是：你的记忆存在你自己的机器上，不依赖任何云服务，不需要任何 API Key，彻底离线可用。数据完全归你所有，永远不会被上传到第三方服务器。

作者 Steven Leggett 是资深 AI 开发者，深耕 AI 编程代理工具链。他从 Claude Code 的实际使用中发现：当代理无法记住项目上下文时，每次新建会话都是一次认知重启。于是他开发了 Sugar，目标是让 AI 代理真正成为"有记忆的长期助手"。

记忆如何运作：两层数据库 + 三层检索

Sugar 在底层维护两个 SQLite 数据库：

• 项目级存储（.sugar/memory.db）：每个项目独立，存储项目专属决策、错误模式、文件上下文
• 全局存储（~/.sugar/memory.db）：跨项目共享，记录编码规范、安全实践、通用偏好

七种记忆类型，每种有不同的检索策略和有效期：

类型	用途	有效期
decision（决策）	架构与实现选择	永久
preference（偏好）	个人编码偏好	永久
file_context（文件上下文）	文件和模块的说明	永久
error_pattern（错误模式）	Bug 及其修复方案	90 天
research（研究）	API 文档、库调研	60 天
outcome（结果）	什么有效、什么无效	30 天
guideline（准则）	跨项目标准与最佳实践	永久

三层检索策略：语义搜索（sentence-transformers/all-MiniLM-L6-v2 向量模型 + sqlite-vec 扩展）→ SQLite FTS5 全文关键词检索 → LIKE 模糊匹配。优先级依次递减，保证在无向量模型时仍能正常工作。

检索逻辑遵循"项目优先 + 全局准则兜底"原则：项目本地上下文永远优先展示，同时全局 guideline 类型记忆总是会出现在结果中，确保跨项目标准不被遗忘。

MCP 集成：让 AI 代理直接读写记忆

Sugar 通过 Model Context Protocol（MCP）暴露工具接口，主流 AI 编程代理均可连接：

• Claude Code：通过 claude mcp add sugar -- sugar mcp memory 连接记忆 MCP，通过 claude mcp add sugar-tasks -- sugar mcp tasks 连接任务 MCP
• OpenCode：一键配置 sugar opencode setup
• Goose：在扩展配置中添加命令 sugar mcp memory

连接后，AI 代理可以在会话中随时调用 store_learning 保存上下文、search_memories 检索记忆、get_project_context 获取完整项目摘要。无需手动复制粘贴，一切自动流转。

任务队列：从"你下指令"到"它自己跑"

Sugar 的任务队列模块允许用户将工作交付给它，然后启动自主循环。它从同一个记忆存储中读取上下文——也就是说，它已经知道你的偏好和编码规范——然后按优先级顺序执行任务。每个任务完成后自动运行测试、提交代码，再处理下一个，直到队列清空或被用户停止。

在 Claude Code 中，甚至可以直接用 /sugar-task "Fix login timeout" --type bug_fix --urgent 随时委托任务。

高级编排模式（3.10+）：新增的 Task Orchestration 模块将大型功能拆解为 4 阶段工作流（研究→规划→实现→审查），通过专家路由和依赖排序的子任务图，实现更复杂的自主开发流程。迭代模式（--ralph）则让 AI 反复尝试直到质量门通过。

自主 Issue 修复（可选模块）

Sugar 还可以配置为监控 GitHub 仓库的特定标签（security、bug、dependabot），自动拉取问题、分析代码、实现修复、运行测试、提交 PR。整个流程完全自主，你只需审查和合并。

技术架构一览

Sugar 采用模块化分层设计：

CLI (sugar)
    └── Core Loop (sugar/core/loop.py)
        ├── Discovery（发现：GitHub、错误、覆盖率、代码质量）
        ├── Queue（SQLite 任务队列）
        ├── Memory Store（SQLite + FTS5 + vec 向量搜索）
        ├── Executor（Claude Agent SDK 驱动，支持传统 subprocess 模式）
        ├── Quality Gates（测试/标准/真值/差异验证）
        └── Git/GitHub（提交→分支→PR）

核心依赖非常精简：click、pyyaml、aiosqlite、sqlalchemy，以及可选的 sentence-transformers 和 sqlite-vec。Python 版本要求 ≥3.11，使用 setuptools 构建，打包为 sugarai。

上手门槛：极低

Sugar 的安装和初始化极为简单：

pipx install sugarai
cd ~/dev/my-app
sugar init
sugar remember "We use async/await everywhere, never callbacks" --type preference
sugar recall "authentication"

对于已有 MCP 的 AI 代理用户，连接 Sugar 只需一行命令。没有 Web UI（CLI 驱动），不需要 GPU，不占用大量资源——在一台普通开发机上即可完美运行。

局限与争议

• License 限制：Sugar 采用 AGPL-3.0 许可，这意味着如果你基于 Sugar 开发网络服务并提供给他人使用，源代码也必须开源。商业使用需注意合规。
• 向量模型可选：语义搜索需要 sugarai[memory] 安装额外依赖（约 400MB），否则退化为关键词搜索，效果有所降低。
• 无 Web UI：完全命令行驱动，对习惯图形界面的用户有一定学习成本。
• 自主执行的风险：任务队列的自主运行需要谨慎配置——不当的质量门设置可能导致 AI 提交不符合要求的代码。

行业意义

Sugar 代表的趋势是 AI 编程工具链的"记忆化"。从 2023 年 Claude Code 诞生起，AI 代理的上下文管理一直依赖上下文窗口——但这只能维持单次会话。Sugar 将记忆层从瞬时上下文扩展到持久存储，让 AI 代理真正意义上成为"了解你项目的长期搭档"。

随着 MCP 协议逐渐成为 AI 工具互联的事实标准，Sugar 这类 MCP-native 的记忆服务有望成为 AI 编程代理的标配基础设施。其提出的"本地优先 + 语义记忆 + 可选自主执行"三层架构，也为后续类似工具提供了设计参考。

---

一句话总结：Sugar 用两个 SQLite 数据库 + MCP 协议，给 AI 编程代理装上了持久记忆，让它不再每次重启都"失忆"。