Sugar

Sugar

Memória persistente para agentes de IA de codificação.

Seu agente de IA começa cada sessão com amnésia. As decisões de arquitetura, convenções e pegadinhas que você explicou na semana passada se foram. Sugar é a camada de memória local-first que as lembra para você - por projeto, entre projetos, na sua máquina.

Sua memória. Sua máquina. Seus dados.

O que o Sugar Faz

Sugar é uma camada de memória que seu agente de IA de codificação pode ler e escrever diretamente:

• Memória de projeto - Decisões, preferências, padrões de erro e pesquisas armazenados por projeto
• Memória global - Padrões e diretrizes compartilhados entre todos os projetos em que você trabalha
• Busca semântica - Recupera contexto relevante por significado, não apenas por palavras-chave
• Integração MCP - Seu agente de IA lê e escreve memória diretamente durante as sessões
• Local-first - SQLite no seu disco, sem chaves de API, totalmente capaz de funcionar offline
• Fila de tarefas - Execução autônoma opcional, alimentada pela mesma camada de memória

Início Rápido

# 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"

Seu agente de IA também pode ler e escrever memória diretamente - sem necessidade de copiar e colar.

Integração MCP

Conecte a memória do Sugar ao seu agente de IA para que ele acesse o contexto do projeto automaticamente.

Claude Code - Servidor de memória (principal):

claude mcp add sugar -- sugar mcp memory

Claude Code - Servidor de tarefas (opcional):

claude mcp add sugar-tasks -- sugar mcp tasks

Uma vez conectado, o Claude pode chamar store_learning para salvar contexto no meio da sessão e search_memories para puxar conhecimento relevante antes de começar o trabalho. O servidor de memória funciona de qualquer diretório - a memória global está sempre disponível mesmo fora de um projeto Sugar.

Outros clientes 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

Skills

O Sugar inclui Agent Skills - pastas de instruções que ensinam agentes de codificação a aplicar a metodologia do Sugar. As Skills ficam em skills/ e seguem a especificação Agent Skills (um SKILL.md com frontmatter de nome/descrição mais instruções).

Cada skill inclui um conjunto de dados de avaliação (evals/evals.json) e é medida com NVIDIA SkillEvaluator contra o harness OpenCode. Veja Skill Benchmarks para os resultados de Skill Lift - sugar-memory e sugar-task-planner ambos mostram lift positivo medido.

Memória Global

Algum conhecimento pertence a você, não apenas a um projeto. Padrões de codificação, preferências de padrões, práticas de segurança - estes devem seguir você em todos os lugares.

# 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

A memória global fica em ~/.sugar/memory.db. A memória de projeto fica em .sugar/memory.db. Quando você busca, o contexto do projeto vence - mas memórias do tipo guideline do global sempre aparecem nos resultados para que seus padrões permaneçam visíveis.

Via MCP, passe scope: "global" para store_learning para salvar conhecimento entre projetos diretamente da sua sessão de IA.

Tipos de memória: decision, preference, file_context, error_pattern, research, outcome, guideline

Documentação completa: Memory System Guide

Como a Memória Funciona

O Sugar usa dois bancos de dados SQLite e uma estratégia de busca em camadas.

Dois armazenamentos:

• Armazenamento de projeto (.sugar/memory.db) - contexto específico de um projeto
• Armazenamento global (~/.sugar/memory.db) - conhecimento que se aplica em todos os lugares

Sete tipos de memória, cada um com comportamento de recuperação diferente:

Estratégia de busca - projeto primeiro com slots reservados para diretrizes:

1. Busque no armazenamento do projeto primeiro (o contexto local sempre vence)
2. Reserve slots para diretrizes globais (padrões entre projetos sempre aparecem)
3. Preencha os slots restantes com outros resultados globais
4. Deduplicar entre os dois armazenamentos

Isso significa que o contexto local de um projeto maduro domina os resultados. Um novo projeto sem memória local recebe conhecimento global automaticamente. E suas diretrizes estão sempre visíveis independentemente.

Mecanismo de busca: Busca semântica via sentence-transformers (all-MiniLM-L6-v2, vetores de 384 dimensões) com sqlite-vec. Cai para busca por palavras-chave SQLite FTS5, depois consultas LIKE. Sem chamadas de API externas - tudo roda localmente.

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

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

Ferramentas MCP disponíveis para seu agente de IA:

Recursos MCP:

• sugar://project/context - resumo do projeto
• sugar://preferences - preferências de codificação
• sugar://global/guidelines - padrões entre projetos

Fila de Tarefas

A fila de tarefas permite que você entregue trabalho e o deixe executar autonomamente. Ela lê do mesmo armazenamento de memória, então o Sugar já conhece suas preferências e padrões antes de começar.

# 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

O Sugar pega tarefas, executa-as com seu agente de IA configurado, roda testes, commita código funcional e passa para a próxima tarefa. Ele roda até a fila ficar vazia ou você pará-lo.

Delegue do Claude Code no meio da sessão:

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

Opções avançadas de tarefa: Novo na 3.10: Orquestração de Tarefas decompõe grandes funcionalidades em um fluxo de trabalho de 4 estágios (pesquisa, plano, implementação, revisão) com roteamento de agente especialista e subtarefas ordenadas por dependência.

# 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

Documentação completa: Task Orchestration

Resolução Autônoma de Issues (opcional)

Como o Sugar lembra do seu código e das suas convenções, ele também pode resolver issues rotineiras autonomamente. Aponte-o para um repositório GitHub, configure em quais labels agir (security, bug, dependabot), e o Sugar lerá cada issue, implementará a correção, rodará seus testes e abrirá um 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

Esta é uma aplicação da camada de memória, não o destaque. Use o Sugar puramente como memória, ou habilite a resolução - sua escolha. Veja workflow examples para correção automática de segurança, triagem de bugs, cobertura de testes e mais.

Ferramentas de IA Suportadas

Funciona com qualquer agente de IA de codificação baseado em CLI:

Instalação

Recomendado: pipx - instala uma vez, disponível em todos os lugares, sem conflitos de venv:

pipx install sugarai

Atualizar / Desinstalar:

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]'

O Sugar é local ao projeto por padrão. Cada projeto recebe sua própria pasta .sugar/ com seu próprio banco de dados e configuração. A memória global fica em ~/.sugar/. Como git - uma instalação, estado por projeto.

Estrutura do Projeto

~/.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 recomendado:

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

Commite .sugar/config.yaml e .sugar/prompts/ para compartilhar configurações com sua equipe.

Configuração

.sugar/config.yaml é criado em sugar init:

sugar:
  dry_run: false
  loop_interval: 300
  max_concurrent_work: 3

claude:
  enable_agents: true

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

Documentação

• Quick Start
• Memory System
• Skill Benchmarks
• CLI Reference
• Task Orchestration
• Goose Integration
• OpenCode Integration
• GitHub Integration
• Configuration Guide
• Troubleshooting

Requisitos

• Python 3.11+
• Um agente de IA baseado em CLI: Claude Code, OpenCode, Aider, ou similar

Contribuindo

Contribuições são bem-vindas. Veja CONTRIBUTING.md.

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

Licença

Licença Dupla: AGPL-3.0 + Comercial

• Open Source (AGPL-3.0): Gratuito para uso open source e pessoal
• Licença Comercial: Para uso proprietário - sugar.roboticforce.io/licensing

O Sugar é fornecido "COMO ESTÁ" sem garantia. Revise todo código gerado por IA antes do uso.