v0.2.0 - Alpha

La atención lo es todo para un modelo.
Concentrarla es lo que hace niuma_code.

En 2017, "Attention is All You Need" definió una era: toda inteligencia de modelo se construye sobre la atención. Ocho años después, descubrimos que no es que los modelos carezcan del mecanismo de atención — carecen de saber dónde colocar la atención. Cuanto más largo es el contexto, más ruido diluye la información verdaderamente importante. niuma_code hace una sola cosa: comprimir el contexto y añadir concentración — para que cada token llegue al lugar que le corresponde.

🔒
Ejecución local
Los datos no salen de tu máquina — control total de privacidad
🛡️
Privacidad primero
API Key se guarda localmente, los datos de conversación no se suben
📦
v0.2.0 Alpha
Mejora continua, impulsado por la comunidad
💬
Soporte comunitario
GitHub Issues — contacto directo con desarrolladores

Verlo en acción

Grabación real del modo IDE de orquestación — prueba niuma_code en 1 minuto

10 herramientas para maximizar cada token

Cada función está diseñada para que tu tokens lleguen al punto más importante.

⚙️

Harness autónomo con bucle tool_use

El LLM ejecuta comandos, analiza resultados, toma decisiones — todo dentro de un bucle autónomo. Sin supervisión humana constante.

  • Ejecución autónoma de herramientas con bucle de decisión
  • Análisis en tiempo real de resultados intermedios
  • Poda y compresión inteligente para gestión de contexto
🔁

Loop engineering con verificación

Un bucle de planificar-ejecutar-verificar con 3 intentos de autocorrección. Cada paso es verificable.

  • Descomposición en pasos verificables
  • 3 intentos de autocorrección antes de reportar
  • Verificación continua del estado del proyecto
🖥️

TUI pantalla completa con prompt_toolkit

Interfaz de terminal rica que maximiza el área de contenido. Desplazamiento con teclado, autocompletado, atajos de teclado.

  • Área máxima de contenido con diseño responsivo
  • Desplazamiento con teclado y atajos personalizables
  • Soporte completo de caracteres unicode (chino, japonés, etc.)
💻

Modo IDE Orquestación

Editor de código pantalla completa. Escribe scripts de orquestación en Python nativo e integra llamadas LLM en flujos de trabajo programáticos.

  • Funciones inyectadas: llm_call / llm_confirm / llm_judge para orquestación controlada
  • F5 vista previa (análisis estático AST), F6 ejecución (sin supervisión, permisos auto-asignados)
  • Sandbox seguro + lista negra de imports peligrosos (os/subprocess/socket etc.) — red de seguridad única en modo sin supervisión
🔌

Enrutamiento multiproveedor

Configura múltiples endpoints API en settings.json — las solicitudes se enrutan automáticamente al proveedor correcto según el nombre del modelo.

  • Cada proveedor declara base_url / api_key / lista de modelos soportados
  • Cambiar modelo con #tag o /model — conexión automática al endpoint correcto
  • Cascada de 3 niveles de configuración (usuario/proyecto/local), el último definido tiene prioridad
🗂️

Gestión de contexto paralela

Expande una conversación en N contextos paralelos, cada uno gestiona independientemente historial, conteo de tokens y estado de compresión.

  • Evicción LRU, límite por defecto 5 (configurable con max_contexts) — evicción = archivado, restaurable
  • /context overlay visual para cambiar; genera resumen asíncrono al salir
  • /messages selección múltiple por unidad — eliminar / reordenar / integrar resumen LLM
🕸️

Grafo de conocimiento de código

Analiza estructura de código con tree-sitter, construye cadenas de llamadas, dependencias y grafos — localiza exactamente antes de que el LLM lea la línea.

  • 4 herramientas de consulta de solo lectura: símbolo, archivo, referencia, cadena de llamadas
  • Devuelve archivo:línea y firma — reemplaza el approach de buscar en un océano de grep
  • Reconstrucción bajo demanda con 3 factores de decisión — evita parseo completo al inicio
🤖

Investigación paralela con sub-agentes

Sub-agentes de solo lectura ejecutan herramientas en paralelo, investigan en contexto aislado y solo devuelven resúmenes — el contexto principal permanece limpio.

  • Múltiples sub-agentes ejecutan herramientas en paralelo, no bloqueante
  • Investigación en contexto aislado, solo resúmenes — no contamina la conversación principal
  • Pertenece al paradigma harness por defecto, llamado bajo demanda (no es modo independiente)
🧠

Memoria perceptiva

Memoria persistente con memory-palace — los eventos durante la ejecución se capturan como memoria en tiempo real, acumulando experiencia entre sesiones.

  • 10 tipos de eventos perceptivos (visual/corporal/lingual/nasal/resultado etc.), escritura en tiempo real
  • Tripletas de hechos + resumen de conversación, recuperación en 4 capas + decaimiento bayesiano
  • Inyección automática en prompt del sistema en la siguiente sesión, posición de recuperación estable
🎯

Seguimiento de recompensa por resultado

Rastrea el ciclo de vida completo del objetivo de la tarea, calcula puntuación de recompensa basada en calidad y escribe como evento perceptivo en memoria.

  • OutcomeTracker calcula puntuación 0.0–1.0 en todo el ciclo de vida de la tarea
  • Puntuación de recompensa es señal de valor de reutilización para memoria
  • Integrado con 10 tipos de eventos perceptivos y eventos read/write/tool-call

Cómo usar ambos modos efectivamente

Si no están claros los pasos, describe y itera (harness). Si tienes una checklist, usa /loop.

🧭

Puntos clave de harness

harness no tiene bucle de replanificación — cuanto más clara la entrada, más precisa la exploración autónoma.

Usar cuando: Tienes una idea general pero no puedes articular los pasos, y quieres avanzar iterando. Ej: 'Encuentra y corrige el error en la página de login'
  • Documenta las restricciones de antemano: objetivo + archivos/funciones intocables + criterios de aceptación — no cambies requisitos durante la ejecución
  • Lo mejor cuando los límites son ambiguos pero el objetivo está claro; cuanto más claro el paso, más rápido converge
  • Usa puntos de control: ESC para detener en cualquier momento, la salida larga se comprime automáticamente, errores de API se reintenta automáticamente
  • 'Terminado' y 'realmente terminado' son cosas diferentes — ejecuta pruebas/compilación tú mismo después de cambios importantes
🎯

Puntos clave de loop

La autocorrección depende completamente de la 'verificación' — solo los objetivos verificables hacen significativos los 3 intentos de corrección.

Usar cuando: Puedes descomponer la tarea en pasos con método de verificación para cada uno. Ej: '/loop Añade paginación a la API de usuarios y ejecuta py_compile después de los cambios'
  • Los objetivos DEBEN ser descomponibles en pasos con comandos de verificación — 'mejora esto' no es verificable
  • Documenta el método de verificación directamente en el objetivo (py_compile / tests) para mayor precisión de planificación
  • 3 fallos de autocorrección normalmente significan información de verificación insuficiente — en lugar de intentar más, descompón más
  • 3 fallos no detienen — se registran y el bucle continúa; revisa los marcadores [!!] en el resumen

3 pasos para empezar

Descargar, configurar y ejecutar — listo en segundos

01 Descargar
⬇ Descargar niuma.exe
Windows · Sin instalación · Ejecución inmediata
02 Configuración
# ~/.niuma/settings.json
{
  "factories": [{
    "api_key": "your-key"
  }]
}
03 Ejecutar
$ niuma.exe
niuma_code v0.2.0 launched

Lista de parámetros de settings.json

Ruta del archivo de configuración: ~/.niuma/settings.json

factoriesConfiguración de API multiproveedor. Cada proveedor declara base_url / api_key / lista de modelos soportados; las solicitudes se enrutan automáticamente por nombre de modelo
💡 Ejemplo de configuración
{
  "factories": [
    {
      "base_url": "https://api.anthropic.com",  // Anthropic official endpoint
      "api_key": "sk-ant-xxx",                   // Required; all three fields must be present
      "options": ["claude-sonnet-4-6", "claude-opus-4-8"]  // Supported models for this provider
    },
    {
      "base_url": "https://your-proxy.example.com",  // Anthropic-compatible proxy endpoint
      "api_key": "sk-proxy-xxx",
      "options": ["claude-sonnet-4-6"]  // Supported models for this endpoint
    }
  ]
}
Parámetro Tipo Predeterminado Descripción
base_url string --- URL del endpoint API (requerido)
api_key string --- Clave API (requerido)
options string[] [] Nombres de modelos soportados por este proveedor
llmModelo, nivel de esfuerzo, presupuesto de pensamiento y gestión de contexto
💡 Ejemplo de configuración
{
  "llm": {
    "default_model": "claude-sonnet-4-6",   // Default value for /model switch
    "default_effort": "high",               // Determines which thinking_budget is used
    "max_contexts": 5,                      // Max parallel contexts; LRU eviction beyond limit
    "resume_latest_context": true,          // Resume last active context on startup
    "options": [                            // Model -> effort mapping
      {"claude-sonnet-4-6": ["low", "medium", "high"]},
      {"claude-opus-4-8": ["low", "medium", "high", "max"]}
    ],
    "thinking_budget_low": "0",             // 0 = disable extended thinking
    "thinking_budget_medium": "0",
    "thinking_budget_high": "10000",        // Thinking budget for high effort
    "thinking_budget_max": "20000"           // Thinking budget for max effort (deepest reasoning)
  }
}
Parámetro Tipo Predeterminado Descripción
default_model string "claude-sonnet-4-6" Modelo predeterminado (fijo durante la sesión, cambiable con /model)
default_effort string "high" Nivel de esfuerzo predeterminado — controla la profundidad del presupuesto de pensamiento
max_contexts integer 5 Máximo de contextos paralelos activos; excedente se evicciona con LRU
resume_latest_context boolean true Restaurar último contexto activo al inicio; false = nuevo comienzo
options object[] [] Mapeo modelo→esfuerzo, usado para validación de cambio /model
thinking_budget_low string/int "0" Presupuesto de tokens de pensamiento para esfuerzo bajo (0 = deshabilitado)
thinking_budget_medium string/int "0" Presupuesto de tokens de pensamiento para esfuerzo medio
thinking_budget_high string/int "10000" Presupuesto de tokens de pensamiento para esfuerzo alto
thinking_budget_max string/int "20000" Presupuesto de tokens de pensamiento para esfuerzo máximo (razonamiento más profundo)
envVariables de entorno escritas en os.environ. Controlan persona, depuración, red y permisos
💡 Ejemplo de configuración
{
  "env": {
    "PERSONA_NAME": "niuma",              // AI persona name, injected into system prompt
    "MODEL_BACKGROUND": "claude-haiku-4-5", // Background task model (memory extraction, compression, etc.)
    "LANG": "zh",                        // UI language (zh/en); also controls LLM response language
    "TEMPERATURE_ZERO": "true",            // Note: all values are strings
    "API_TIMEOUT": "30",                   // Streaming stall timeout (seconds)
    "API_ROUND_MAX": "120",                // Per-turn wall-clock hard limit (seconds)
    "API_STALL_MAX_RETRIES": "10",        // Max auto-retries on stream stall
    "PERMISSION_MODE": "auto",             // auto=whitelist+confirm / manual=whitelist only / skip=allow all
    "ALLOWED_TOOLS": ""                    // Whitelisted tools (comma-separated); empty = built-in defaults
  }
}
Parámetro Tipo Predeterminado Descripción
PERSONA_NAME string "niuma" Nombre de la persona, inyectado en el prompt del sistema
MODEL_BACKGROUND string "claude-haiku-4-5" Modelo para tareas en segundo plano (extracción de memoria, compresión, etc.)
LANG string "en" Idioma de la interfaz (zh/en); también controla el idioma de respuesta del LLM
TEMPERATURE_ZERO string(bool) "true" Fix temperature=0 para salida determinística; false = predeterminado del modelo
API_TIMEOUT string/int "30" Tiempo de espera de streaming (segundos) — reconexión si no hay eventos después de esto
API_ROUND_MAX string/int "120" Límite de tiempo por turno (segundos) — fuerza cierre de streams antiguos
API_STALL_MAX_RETRIES string/int "10" Número máximo de reintentos automáticos en caso de bloqueo de stream
PERMISSION_MODE string "auto" Modo de permisos: auto (whitelist+confirmar) / manual (solo whitelist) / skip (permitir todo)
ALLOWED_TOOLS string "" Whitelist de herramientas separada por comas; vacío = predeterminado integrado
compactCompresión de contexto: comprime conversaciones largas automáticamente para preservar información importante
💡 Ejemplo de configuración
{
  "compact": {
    // -- Inline compression (blocks main loop until done) --
    "inline_trigger": 0.8,      // Triggers at 80% of MAX_TOKENS
    "inline_keep_ratio": 0.4,   // Keep latest 40% of messages after compression

    // -- Post-reply async compression (non-blocking, runs in background) --
    "idle_trigger": 0.5,        // Triggers at 50% of MAX_TOKENS
    "idle_keep_ratio": 0.4,     // Keep latest 40% of messages after compression

    // -- LLM summary output limit --
    "max_summary_tokens": 4096  // Max tokens for generated summary
  }
}
Parámetro Tipo Predeterminado Descripción
inline_trigger float 0.8 Tasa de activación de compresión inline — bloquea el bucle principal al alcanzar
inline_keep_ratio float 0.4 Proporción de mensajes recientes a mantener después de la compresión inline
idle_trigger float 0.5 Tasa de activación de compresión idle — se ejecuta asíncronamente después de la respuesta
idle_keep_ratio float 0.4 Proporción de mensajes recientes a mantener después de la compresión idle
max_summary_tokens integer 4096 Tokens de salida máxima para el resumen generado por LLM
memory_palaceConfiguración LLM de Memory Palace; independiente del bloque llm, parseado por separado
💡 Ejemplo de configuración
// Basic mode: rule-based extraction only (no LLM, zero cost)
{
  "memory_palace": {
    "enable_v9": false,        // Disable V9; falls back to legacy V8 mode
    "llm_enabled": false        // Disable LLM enhancement
  }
}

// Full mode: LLM-enhanced extraction (all three fields required; otherwise falls back to rule-based)
{
  "memory_palace": {
    "enable_v9": true,
    "llm_enabled": true,       // Once enabled, the following three fields are required
    "base_url": "https://api.anthropic.com",
    "api_key": "sk-ant-xxx",
    "model": "claude-haiku-4-5"    // Recommend a lightweight model to save tokens
  }
}
Parámetro Tipo Predeterminado Descripción
enable_v9 boolean true Habilitar memoria perceptiva V9; false = modo legacy V8
llm_enabled boolean false Habilitar extracción de memoria mejorada por LLM; false = solo basado en reglas
base_url string "" Endpoint API LLM de memoria (los 3 campos son requeridos, de lo contrario vuelve a basado en reglas)
api_key string "" Clave API LLM de memoria
model string "" Modelo para LLM de memoria (se recomienda un modelo ligero como haiku)
memory_qualityUmbrales de calidad de memoria; controlan filtrado de escritura y precisión de recuperación
💡 Ejemplo de configuración
{
  "memory_quality": {
    "min_store_importance": 0.4,  // Write gate: discard facts with importance below this threshold
    "min_recall_score": 0.35,     // Recall gate: skip memories scoring below this threshold
    "dedup_threshold": 0.3        // Dedup threshold: Jaccard similarity above this = duplicate
  }
}
Parámetro Tipo Predeterminado Descripción
min_store_importance float 0.4 Puerta de escritura: descarta hechos con importancia por debajo de este umbral
min_recall_score float 0.35 Puerta de recuperación: omite memorias con puntuación por debajo de este umbral
dedup_threshold float 0.3 Umbral de deduplicación: similitud Jaccard por encima de esto = duplicado, mantener el más reciente

Lista de comandos disponibles

Ejecuta acciones rápidas con comandos slash

Comandos Descripción
/ide Inicia editor de código pantalla completa
/context Gestión multi-contexto (nuevo/cambiar/renombrar/eliminar)
/help Muestra información de ayuda
/copy Copia la última respuesta al portapapeles
/resume Reanuda tareas incompletas
/clear Limpia el contexto de conversación
/restart Reinicia niuma
/model Ver/cambiar modelo
/quit Termina el programa

Comandos rápidos #tag

Usa #tag para inyectar instrucciones predefinidas rápidamente — define una vez, reutiliza muchas veces

💡

¿Qué es #tag?

Las etiquetas personalizadas son atajos definidos por el usuario que se despliegan en texto preestablecido al escribir #tagname.

  • Escribir #ja se despliega automáticamente en "responder en español"
  • Admite cualquier etiqueta personalizada, sin distinción de mayúsculas/minúsculas
  • Las etiquetas se pueden colocar en cualquier parte de la entrada, se eliminan automáticamente después del análisis
  • El texto desplegado se añade a la entrada para que el LLM pueda entenderlo
Ejemplo: #ja complejidad del algoritmo de ordenamiento de burbuja → [responder en español] complejidad del algoritmo de ordenamiento de burbuja
⚙️

2 tipos de etiquetas

Las etiquetas de sistema controlan el modo de funcionamiento, mientras que las etiquetas personalizan inyectan instrucciones preestablecidas. Se complementan entre sí.

  • #plan_mode — fuerza solo análisis, sin ejecución (máxima prioridad)
  • #skip_mode — omite todos los permisos, ejecuta herramientas directamente
  • #custom — cualquier atajo definido por el usuario
  • Si plan_mode y skip_mode se escriben juntos, plan_mode tiene prioridad
📋

Comando /tag para gestión

Usa el comando /tag para añadir, modificar, eliminar y listar etiquetas personalizadas.

  • /tag — abre panel de gestión de etiquetas (TUI), o lista etiquetas (CLI)
  • /tag add <name> <text> — añade una nueva etiqueta
  • /tag mod <name> <text> — modifica una etiqueta existente
  • /tag rm <name> — elimina una etiqueta
  • /tag ls — lista todas las etiquetas
🎯

Casos de uso comunes

Encapsula instrucciones frecuentes como etiquetas para mejorar la eficiencia de la conversación.

  • #ja — fuerza respuesta en español
  • #fix — instrucción estándar de corrección de errores
  • #review — requisitos estándar de revisión de código
  • #explain — explicación detallada de la lógica del código
Uso combinado: #plan_mode #ja analiza el cuello de botella de rendimiento de esta función
💾

Almacenamiento y configuración

Las etiquetas se guardan en un archivo JSON, en la misma ubicación que settings.json.

  • Ubicación: ~/.niuma/custom_tags.json
  • Formato simple clave-valor, las claves se convierten automáticamente a minúsculas
  • Escritura atómica, compatible con Windows
Ejemplo de archivo:
{
  "ja": "responder en español",
  "fix": "corregir error"
}
🔄

Pipeline de análisis

La entrada pasa por un enrutamiento triple, garantizando que la comprensión del LLM, la recuperación de memoria y el almacenamiento perceptivo reciban la información que necesitan.

  • raw_input — entrada original, para guardado de trazas
  • llm_input — entrada tras desplegar etiquetas, para que el LLM la entienda
  • filter_input — entrada sin etiquetas, para recuperación de memoria
  • La memoria no se contamina con etiquetas, la recuperación se mantiene precisa