Sugar

Sugar

面向 AI 编码 Agent 的持久化记忆。

你的 AI Agent 每次会话开始时都像失忆了一样。你上周说明的架构决策、约定和注意事项都不复存在。Sugar 是一个本地优先的记忆层，能替你记住这些内容——按项目存储，也能跨项目使用，数据保存在你的设备上。

你的记忆。你的设备。你的数据。

Sugar 的功能

Sugar 是一个记忆层，你的 AI 编码 Agent 可以直接读取和写入：

• 项目记忆 - 按项目存储的决策、偏好、错误模式和研究内容
• 全局记忆 - 在你参与的所有项目间共享的标准和指南
• 语义搜索 - 按含义而不只是关键词检索相关上下文
• MCP 集成 - AI Agent 可在会话期间直接读取和写入记忆
• 本地优先 - 数据存储在本地磁盘上的 SQLite 中，无需 API 密钥，完全支持离线使用
• 任务队列 - 可选的自主执行功能，由同一记忆层提供支持

快速开始

# Install once, use in any project
pipx install sugarai

# Initialize in your project
cd ~/dev/my-app
sugar init

# Store what you know
sugar remember "We use async/await everywhere, never callbacks" --type preference
sugar remember "JWT tokens use RS256, expire in 15 min - see auth/tokens.py" --type decision
sugar remember "When tests fail with import errors, check __init__.py exports first" --type error_pattern

# Retrieve it later
sugar recall "authentication"
sugar recall "how do we handle async"

你的 AI Agent 也可以直接读取和写入记忆——无需复制粘贴。

MCP 集成

将 Sugar 的记忆连接到你的 AI Agent，让它自动访问项目上下文。

Claude Code - 记忆服务（主要）：

claude mcp add sugar -- sugar mcp memory

Claude Code - 任务服务（可选）：

claude mcp add sugar-tasks -- sugar mcp tasks

连接后，Claude 可以调用 store_learning 在会话期间保存上下文，并调用 search_memories 在开始工作前获取相关知识。记忆服务可从任何目录运行——即使不在 Sugar 项目中，也始终可以使用全局记忆。

其他 MCP 客户端（Goose、Claude Desktop）：

# Goose
goose configure
# Select "Add Extension" -> "Command-line Extension"
# Name: sugar
# Command: sugar mcp memory

# OpenCode - one command setup
sugar opencode setup

技能

Sugar 随附 Agent Skills——这些指令文件夹能教会编码 Agent 如何应用 Sugar 的方法论。技能位于 skills/ 下，并遵循 Agent Skills 规范（包含名称／描述 frontmatter 和指令的 SKILL.md）。

每项技能都包含一个评估数据集（evals/evals.json），并使用 NVIDIA SkillEvaluator 针对 OpenCode 测试框架进行评测。有关 Skill Lift 结果，请参阅技能基准测试——sugar-memory 和 sugar-task-planner 均显示出经测量的正向提升。

全局记忆

有些知识属于你，而不只是某个项目。编码标准、偏好的模式、安全实践——这些都应该伴随你应用到各处。

# Store a guideline that applies to all your projects
sugar remember "Always validate and sanitize user input before any DB query" \
  --type guideline --global

sugar remember "Use conventional commits: feat/fix/chore/docs/test" \
  --type guideline --global

# View your global guidelines
sugar recall "security" --global
sugar memories --global

# Search works project-first, but guidelines always surface
sugar recall "database queries"
# Returns: project-specific memories + relevant global guidelines

全局记忆位于 ~/.sugar/memory.db。项目记忆位于 .sugar/memory.db。搜索时优先显示项目上下文，但全局记忆中的 guideline 类型记忆始终会出现在结果中，确保你能看到自己的标准。

通过 MCP，在 AI 会话中调用 store_learning 保存跨项目知识时，传入 scope: "global"。

记忆类型： decision、preference、file_context、error_pattern、research、outcome、guideline

完整文档：记忆系统指南

记忆的工作方式

Sugar 使用两个 SQLite 数据库和分层搜索策略。

两个存储库：

• 项目存储库（.sugar/memory.db）- 特定于某个项目的上下文
• 全局存储库（~/.sugar/memory.db）- 适用于所有项目的知识

七种记忆类型，各自采用不同的检索方式：

搜索策略——优先搜索项目存储库，并为 guideline 预留结果位：

1. 首先搜索项目存储库（始终优先采用本地上下文）
2. 为全局 guideline 预留结果位（确保始终显示跨项目标准）
3. 其余结果位用于其他全局结果
4. 对两个存储库的结果去重

这意味着，成熟项目的本地上下文会在结果中占主导地位。没有本地记忆的新项目会自动获取全局知识。无论如何，你的 guideline 都会始终显示。

**搜索引擎：**使用 sentence-transformers（all-MiniLM-L6-v2，384 维向量）和 sqlite-vec 进行语义搜索。不可用时会回退到 SQLite FTS5 关键词搜索，然后使用 LIKE 查询。不调用外部 API，所有操作都在本地运行。

# Install with semantic search (recommended)
pipx install 'sugarai[memory]'

# Works without it too - just uses keyword matching
pipx install sugarai

可供 AI Agent 使用的 MCP 工具：

MCP 资源：

• sugar://project/context - 项目摘要
• sugar://preferences - 编码偏好
• sugar://global/guidelines - 跨项目标准

任务队列

任务队列可让你分派工作并让其自主运行。它会读取同一记忆存储库，因此 Sugar 在开始工作前就已了解你的偏好和模式。

# Add tasks
sugar add "Fix authentication timeout" --type bug_fix --urgent
sugar add "Add user profile settings" --type feature

# Start the autonomous loop
sugar run

Sugar 会领取任务，使用你配置的 AI Agent 执行任务、运行测试、提交可用代码，然后继续处理下一项任务。它会持续运行，直到队列清空或你将其停止。

在会话中途从 Claude Code 分派任务：

/sugar-task "Fix login timeout" --type bug_fix --urgent

高级任务选项： 3.10 版新增：任务编排会将大型功能拆分为包含 4 个阶段（调研、规划、实现、审查）的工作流，并进行专职 Agent 路由和按依赖关系排序的子任务拆分。

# Orchestrated execution - 4-stage workflow (New in 3.10)
sugar add "Add OAuth authentication" --type feature --orchestrate

# Iterative mode - loops until tests pass
sugar add "Implement rate limiting" --ralph --max-iterations 10

# Check queue status
sugar list
sugar status

完整文档：任务编排

自主解决问题（可选）

由于 Sugar 记得你的代码库和惯例，它也能自主解决日常问题。 指定一个 GitHub 仓库，配置要处理的问题标签 （security、bug、dependabot），Sugar 就会逐一读取问题、实现修复、运行 测试并创建 PR。

Labeled issue appears on GitHub
  -> Sugar picks it up (label filter: "security", "dependabot", "bug")
  -> AI agent reads the issue, analyzes the affected code
  -> Fix implemented, tests run locally
  -> PR opened - you review and merge

这是记忆层的一种应用方式，并非其核心重点。你可以只将 Sugar 用作记忆， 也可以启用问题解决功能，由你选择。请参阅工作流示例，了解安全 自动修复、Bug 分类、测试覆盖率等内容。

支持的 AI 工具

适用于任何基于 CLI 的 AI 编码 Agent：

安装

推荐：pipx — 安装一次，随处可用，且不会与虚拟环境冲突：

pipx install sugarai

升级 / 卸载：

pipx upgrade sugarai
pipx uninstall sugarai

pip install sugarai

uv pip install sugarai

pipx install 'sugarai[memory]'

pipx install 'sugarai[github]'

pipx install 'sugarai[all]'

默认情况下，Sugar 是项目本地的。每个项目都有自己的 .sugar/ 文件夹，其中包含独立的数据库和配置。全局记忆位于 ~/.sugar/。类似于 git——只需安装一次，每个项目的状态各自独立。

项目结构

~/.sugar/
└── memory.db          # Global memory (guidelines, cross-project knowledge)

~/dev/my-app/
├── .sugar/
│   ├── sugar.db       # Project memory + task queue
│   ├── config.yaml    # Project settings
│   └── prompts/       # Custom agent prompts
└── src/

推荐的 .gitignore：

.sugar/sugar.db
.sugar/sugar.log
.sugar/*.db-*

提交 .sugar/config.yaml 和 .sugar/prompts/，即可与团队共享设置。

配置

运行 sugar init 时会创建 .sugar/config.yaml：

sugar:
  dry_run: false
  loop_interval: 300
  max_concurrent_work: 3

claude:
  enable_agents: true

discovery:
  github:
    enabled: true
    repo: "user/repository"

文档

• 快速入门
• 记忆系统
• 技能基准测试
• CLI 参考
• 任务编排
• Goose 集成
• OpenCode 集成
• GitHub 集成
• 配置指南
• 故障排除

要求

• Python 3.11+
• 基于 CLI 的 AI Agent：Claude Code、OpenCode、Aider 或类似工具

贡献

欢迎贡献。请参阅 CONTRIBUTING.md。

git clone https://github.com/roboticforce/sugar.git
cd sugar
uv pip install -e ".[dev,test,github]"
pytest tests/ -v

许可证

双重许可：AGPL-3.0 + 商业许可

• 开源（AGPL-3.0）：可免费用于开源项目和个人用途
• 商业许可证：用于专有用途 — sugar.roboticforce.io/licensing

Sugar 按“原样”提供，不附带任何保证。使用前请检查所有 AI 生成的代码。