Sugar

Sugar

Memoria persistente para agentes de IA de codificación.

Tu agente de IA comienza cada sesión con amnesia. Las decisiones de arquitectura, convenciones y problemas que explicaste la semana pasada se han ido. Sugar es la capa de memoria local-first que las recuerda por ti: por proyecto, entre proyectos, en tu máquina.

Tu memoria. Tu máquina. Tus datos.

Qué hace Sugar

Sugar es una capa de memoria que tu agente de IA de codificación puede leer y escribir directamente:

• Memoria de proyecto: decisiones, preferencias, patrones de error e investigación almacenados por proyecto
• Memoria global: estándares y pautas compartidos en todos los proyectos en los que trabajas
• Búsqueda semántica: recupera contexto relevante por significado, no solo por palabras clave
• Integración MCP: tu agente de IA lee y escribe memoria directamente durante las sesiones
• Local-first: SQLite en tu disco, sin claves API, totalmente capaz de funcionar sin conexión
• Cola de tareas: ejecución autónoma opcional, impulsada por la misma capa de memoria

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

Tu agente de IA también puede leer y escribir memoria directamente, sin necesidad de copiar y pegar.

Integración MCP

Conecta la memoria de Sugar a tu agente de IA para que pueda acceder al contexto del proyecto automáticamente.

Claude Code - Servidor de memoria (principal):

claude mcp add sugar -- sugar mcp memory

Claude Code - Servidor de tareas (opcional):

claude mcp add sugar-tasks -- sugar mcp tasks

Una vez conectado, Claude puede llamar a store_learning para guardar contexto a mitad de sesión y a search_memories para extraer conocimiento relevante antes de comenzar a trabajar. El servidor de memoria funciona desde cualquier directorio: la memoria global siempre está disponible incluso fuera de un proyecto de Sugar.

Otros 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

Habilidades

Sugar incluye Agent Skills: carpetas de instrucciones que enseñan a los agentes de codificación a aplicar la metodología de Sugar. Las habilidades viven en skills/ y siguen la especificación Agent Skills (un SKILL.md con frontmatter de nombre/descripción más instrucciones).

Cada habilidad incluye un conjunto de datos de evaluación (evals/evals.json) y se mide con NVIDIA SkillEvaluator contra el harness OpenCode. Consulta Skill Benchmarks para ver los resultados de Skill Lift: sugar-memory y sugar-task-planner ambos muestran un aumento positivo medido.

Memoria Global

Algunos conocimientos te pertenecen a ti, no solo a un proyecto. Estándares de codificación, patrones preferidos, prácticas de seguridad: estos deberían seguirte a todas partes.

# 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

La memoria global vive en ~/.sugar/memory.db. La memoria de proyecto vive en .sugar/memory.db. Cuando buscas, el contexto del proyecto gana, pero los recuerdos de tipo guideline de la memoria global siempre aparecen en los resultados para que tus estándares permanezcan visibles.

A través de MCP, pasa scope: "global" a store_learning para guardar conocimiento entre proyectos directamente desde tu sesión de IA.

Tipos de memoria: decision, preference, file_context, error_pattern, research, outcome, guideline

Documentación completa: Memory System Guide

Cómo funciona la memoria

Sugar usa dos bases de datos SQLite y una estrategia de búsqueda por niveles.

Dos almacenes:

• Almacén de proyecto (.sugar/memory.db): contexto específico de un proyecto
• Almacén global (~/.sugar/memory.db): conocimiento que aplica en todas partes

Siete tipos de memoria, cada uno con comportamiento de recuperación diferente:

Estrategia de búsqueda: primero el proyecto con espacios reservados para pautas:

1. Busca primero en el almacén del proyecto (el contexto local siempre gana)
2. Reserva espacios para pautas globales (los estándares entre proyectos siempre aparecen)
3. Llena los espacios restantes con otros resultados globales
4. Deduplica entre ambos almacenes

Esto significa que el contexto local de un proyecto maduro domina los resultados. Un proyecto nuevo sin memoria local recibe conocimiento global automáticamente. Y tus pautas siempre son visibles sin importar qué.

Motor de búsqueda: búsqueda semántica mediante sentence-transformers (all-MiniLM-L6-v2, vectores de 384 dimensiones) con sqlite-vec. Recurre a búsqueda por palabras clave SQLite FTS5, luego consultas LIKE. Sin llamadas API externas: todo se ejecuta localmente.

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

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

Herramientas MCP disponibles para tu agente de IA:

Recursos MCP:

• sugar://project/context: resumen del proyecto
• sugar://preferences: preferencias de codificación
• sugar://global/guidelines: estándares entre proyectos

Cola de tareas

La cola de tareas te permite delegar trabajo y dejarlo ejecutarse de forma autónoma. Lee del mismo almacén de memoria, así que Sugar ya conoce tus preferencias y patrones antes de comenzar.

# 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 toma las tareas, las ejecuta con tu agente de IA configurado, ejecuta pruebas, confirma código funcional y pasa a la siguiente tarea. Se ejecuta hasta que la cola esté vacía o lo detengas.

Delega desde Claude Code a mitad de sesión:

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

Opciones avanzadas de tareas: Nuevo en 3.10: Task Orchestration descompone características grandes en un flujo de trabajo de 4 etapas (investigación, plan, implementación, revisión) con enrutamiento de agentes especialistas y subtareas ordenadas por dependencia.

# 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

Documentación completa: Task Orchestration

Resolución autónoma de problemas (opcional)

Debido a que Sugar recuerda tu código y tus convenciones, también puede resolver problemas rutinarios de forma autónoma. Apúntalo a un repositorio de GitHub, configura en qué etiquetas actuar (security, bug, dependabot), y Sugar leerá cada problema, implementará la corrección, ejecutará tus pruebas y abrirá un 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 es una aplicación de la capa de memoria, no la característica principal. Usa Sugar puramente como memoria, o habilita la resolución: tu elección. Consulta ejemplos de flujos de trabajo para auto-corrección de seguridad, triaje de errores, cobertura de pruebas y más.

Herramientas de IA compatibles

Funciona con cualquier agente de IA de codificación basado en CLI:

Instalación

Recomendado: pipx: se instala una vez, disponible en todas partes, sin conflictos de venv:

pipx install sugarai

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

Sugar es local al proyecto por defecto. Cada proyecto obtiene su propia carpeta .sugar/ con su propia base de datos y configuración. La memoria global vive en ~/.sugar/. Como git: una instalación, estado por proyecto.

Estructura del proyecto

~/.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-*

Confirma .sugar/config.yaml y .sugar/prompts/ para compartir configuraciones con tu equipo.

Configuración

.sugar/config.yaml se crea en sugar init:

sugar:
  dry_run: false
  loop_interval: 300
  max_concurrent_work: 3

claude:
  enable_agents: true

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

Documentación

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

Requisitos

• Python 3.11+
• Un agente de IA basado en CLI: Claude Code, OpenCode, Aider o similar

Contribuciones

Las contribuciones son bienvenidas. Consulta CONTRIBUTING.md.

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

Licencia

Licencia dual: AGPL-3.0 + Comercial

• Código abierto (AGPL-3.0): gratuito para uso de código abierto y personal
• Licencia comercial: para uso propietario: sugar.roboticforce.io/licensing

Sugar se proporciona "TAL CUAL" sin garantía. Revisa todo el código generado por IA antes de usarlo.