Sugar

Sugar

AI コーディングエージェントのための永続メモリです。

AI エージェントは、セッションのたびに記憶を失った状態で始まります。先週説明したアーキテクチャ上の決定事項、規約、注意点はすべて消えてしまいます。Sugar はローカルファーストのメモリレイヤーとして、それらをプロジェクトごとに、プロジェクトをまたいで、あなたのマシン上に記憶します。

あなたのメモリ。あなたのマシン。あなたのデータ。

Sugar ができること

Sugar は、AI コーディングエージェントが直接読み書きできるメモリレイヤーです。

• プロジェクトメモリ - 決定事項、設定、エラーパターン、調査内容をプロジェクトごとに保存します
• グローバルメモリ - 作業するすべてのプロジェクトで共有される標準とガイドラインを保存します
• セマンティック検索 - キーワードだけでなく、意味に基づいて関連するコンテキストを取得します
• MCP 連携 - AI エージェントがセッション中にメモリを直接読み書きします
• ローカルファースト - ディスク上の 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 エージェントはメモリを直接読み書きすることもできるため、コピー＆ペーストは不要です。

MCP 連携

Sugar のメモリを AI エージェントに接続すると、プロジェクトのコンテキストに自動でアクセスできるようになります。

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 にはエージェントスキルが同梱されています。これは、コーディングエージェントに Sugar の手法を適用する方法を教える指示のフォルダーです。スキルは skills/ にあり、Agent Skills 仕様（名前と説明のフロントマター、および指示を含む SKILL.md）に準拠しています。

各スキルには評価データセット（evals/evals.json）が含まれており、OpenCode ハーネスに対して NVIDIA SkillEvaluator で測定されます。Skill Lift の結果については、スキルベンチマークをご覧ください。sugar-memory と sugar-task-planner は、どちらも測定可能な正の効果を示しています。

グローバルメモリ

知識の中には、1 つのプロジェクトだけでなく、あなた自身に属するものもあります。コーディング標準、好みのパターン、セキュリティ対策などは、どこに行っても引き継がれるべきです。

# 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 経由の場合、store_learning に scope: "global" を渡すと、AI セッションからプロジェクトをまたいで使う知識を直接保存できます。

メモリの種類： decision、preference、file_context、error_pattern、research、outcome、guideline

詳細なドキュメント：メモリシステムガイド

メモリの仕組み

Sugar は 2 つの SQLite データベースと、階層型の検索戦略を使用します。

2 つのストア：

• プロジェクトストア（.sugar/memory.db）- 1 つのプロジェクトに固有のコンテキスト
• グローバルストア（~/.sugar/memory.db）- あらゆる場所で適用されるナレッジ

7 種類のメモリがあり、それぞれ取得方法が異なります。

検索戦略 - ガイドライン用の枠を確保した、プロジェクト優先の検索：

1. まずプロジェクトストアを検索します（常にローカルのコンテキストが優先されます）
2. グローバルガイドライン用の枠を確保します（プロジェクト横断の標準は常に表示されます）
3. 残りの枠をほかのグローバル検索結果で埋めます
4. 2 つのストア間で重複を排除します

これにより、成熟したプロジェクトではローカルのコンテキストが検索結果の中心になります。ローカルメモリがない新しいプロジェクトでは、グローバルナレッジが自動的に取得されます。また、ガイドラインは常に表示されます。

検索エンジン： 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 エージェントで利用できる 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 エージェントで実行して、テストを実施し、動作するコードをコミットしてから次のタスクに進みます。キューが空になるか、停止するまで実行されます。

セッション中に Claude Code から委任する：

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

タスクの高度なオプション： 3.10 で新たに追加された Task Orchestration は、大規模な機能を、専門エージェントへのルーティングと依存関係順のサブタスクを伴う 4 段階のワークフロー（調査、計画、実装、レビュー）に分解します。

# 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

詳細なドキュメント：Task Orchestration

自律的な Issue 解決（任意）

Sugar はコードベースと規約を記憶しているため、定型的な Issue を自律的に解決することもできます。 GitHub リポジトリを指定し、対象とするラベル（security、bug、dependabot）を設定すると、Sugar は各 Issue を読み取り、修正を実装し、テストを実行して、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

これはメモリレイヤーの活用例の 1 つであり、主な機能ではありません。Sugar をメモリ専用として使うことも、解決機能を有効にすることもできます。選ぶのはユーザーです。セキュリティの自動修正、バグのトリアージ、テストカバレッジなどについては、ワークフローの例を参照してください。

対応 AI ツール

CLI ベースの AI コーディングエージェントであれば、どれでも使用できます。

インストール

推奨：pipx — 一度インストールすれば、どこでも利用でき、venv と競合しません：

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 エージェント：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 が生成したすべてのコードを確認してください。