<div align="center"> <img src="./screenshots/02-overlay-character.png" width="180" alt="Kaoru, asistente de escritorio Live2D">

Kaoru

Tu asistente personal de IA con capacidad de agente

Conversa · recuerda · propone · actúa con tu permiso

Español · 日本語 · English

Descargar · Manual de uso · Seguridad · Privacidad · Arquitectura · Documentación

</div>

---

Kaoru es un asistente personal de IA que vive en tu escritorio. Conversa, conserva contexto y te acompaña por texto, voz y presencia Live2D. Cuando necesitas pasar a la acción, trabaja como agente sobre tu proyecto y las herramientas que le permitas: planifica, ejecuta y presenta resultados para tu revisión.

Estado: Kaoru está en beta. Funciona de forma usable, pero algunas áreas son experimentales y todavía falta validación externa. Consulta el estado del proyecto antes de usarlo en trabajo importante.

Índice

1. Qué puedes hacer con Kaoru
2. Descarga e instalación
3. Requisitos
4. Capacidades técnicas
5. Seguridad y privacidad
6. Arquitectura
7. Configuración y uso
8. Desarrollo
9. Estado del proyecto
10. Capturas
11. Documentación
12. Licencia y atribuciones

---

1. Qué puedes hacer con Kaoru

| Si eres… | Kaoru te ofrece | | --- | --- | | Desarrollador | Un asistente de código que explora tu repositorio, detecta errores del editor (LSP), propone parches con diff, ejecuta la verificación configurada y cuida la higiene del repo (.env, conflictos, commits sin push). Incluye un chat junto a la terminal de tu proyecto. | | Usuario de escritorio | Un compañero con memoria que retoma hilos pendientes, recuerda lo que importa y ofrece ayuda contextual, con controles separados para aplicaciones, navegador, pantalla, puntero, teclado, procesos y cámara. | | Creador o streamer | Un overlay Live2D en tiempo real con voz sintetizada (Edge TTS), gestos configurables y personalidad consistente. |

Qué lo distingue

1. Propone antes de actuar. Cada mensaje proactivo pasa por un score de relevancia determinista y un gate de contexto (foco, inactividad, presupuesto diario). Se entrega como propuesta con consentimiento: Kaoru propone, tú decides.
2. Decisión auditable. Las señales de los sensores pasan por un núcleo determinista (DecisionCore) con reason codes: puedes rastrear por qué se admitió un mensaje hasta su puntuación, pesos y política. El LLM solo redacta el contenido una vez admitido.
3. Memoria local con decaimiento temporal. Hechos, preferencias y episodios se guardan en tu equipo; lo de ayer pesa más que lo de hace tres semanas, sin descartar lo importante.
4. Permisos fuera del modelo. Cada acción se clasifica fuera del LLM y pasa por reglas allow/ask/deny. El modelo propone, pero no puede concederse permisos.
5. Tú eliges el modelo. Proveedores configurables con fallback y reintentos, o un endpoint local.
6. Autonomía ajustable. Un control observe | suggest | act más un modelo de receptividad que adapta la frecuencia según tus respuestas reales.

---

2. Descarga e instalación

Descarga el instalador de tu sistema desde la última versión publicada. Los instaladores se llaman Asistente Personal (nombre del paquete de la aplicación).

| Sistema | Archivo | | --- | --- | | Windows | Asistente Personal Setup <versión>.exe (instalador) o Asistente Personal <versión>.exe (portable) | | macOS (Apple Silicon: M1/M2/M3…) | Asistente Personal-<versión>-arm64.dmg | | macOS (Intel) | Asistente Personal-<versión>.dmg | | Linux | Asistente Personal-<versión>.AppImage o asistente-personal_<versión>_amd64.deb |

Aviso de firma digital

Los instaladores todavía no están firmados ni notarizados (firmar tiene un costo). Por eso tu sistema puede mostrar una advertencia. No significa que la aplicación sea peligrosa: el código es abierto y puedes revisarlo.

• Windows: si aparece «Windows protegió tu PC», haz clic en Más información y luego en Ejecutar de todas formas.
• macOS: haz clic derecho sobre la app, elige Abrir y confirma. En versiones recientes, si el sistema la bloquea, ve a Ajustes del Sistema → Privacidad y seguridad y elige Abrir de todas formas.
• Linux: para el AppImage, dale permiso de ejecución con chmod +x "Asistente Personal-<versión>.AppImage". Para el .deb: sudo apt install ./asistente-personal_<versión>_amd64.deb.

Verificar la integridad del archivo

Cada archivo del release muestra su hash sha256 en GitHub. Para comprobar el tuyo:

# Linux / macOS
sha256sum "archivo-descargado"          # macOS: shasum -a 256 "archivo-descargado"

# Windows (PowerShell)
Get-FileHash "archivo-descargado" -Algorithm SHA256

Primer arranque

Kaoru muestra una guía para conectar un modelo de IA, revisar permisos, elegir el navegador y probar una tarea. No hace falta editar archivos de configuración. Recomendación: empieza pidiendo un análisis de solo lectura de un proyecto antes de permitir cambios.

¿Prefieres instalar desde el código fuente? Consulta la sección de Desarrollo.

---

3. Requisitos

| Modo | RAM mínima | RAM recomendada | | --- | --- | --- | | Agente y chat por terminal, sin avatar (desde el código fuente) | 4 GB | 8 GB | | Aplicación de escritorio con Live2D | 8 GB | 16 GB |

• No se exige GPU dedicada si usas un proveedor LLM remoto. Un modelo local puede necesitar hardware adicional.
• Estos valores son provisionales, medidos en una sola máquina Linux x64. Consulta medición, CPU, disco y límites por modo.
• Voz: la síntesis neuronal (Edge TTS) viene incluida y requiere conexión a internet. La entrada por micrófono no está disponible en la interfaz actual.
• Sistemas operativos: Windows (sensor nativo), Linux (sensor para Hyprland/Wayland) y macOS (experimental).
• Sandbox de procesos:
  • Windows usa AppContainer. Si no puede inicializarse, falla cerrado, salvo desactivación explícita con OPENCLAW_SANDBOX=0.
  • Linux usa bwrap (bubblewrap) cuando está disponible e informa la degradación si no lo está.
  • Ambos permiten red y escritura dentro del workspace. AppContainer concede solo lectura a los runtimes detectados.
  • macOS no tiene actualmente aislamiento adicional para el ejecutor.

---

4. Capacidades técnicas

Cada bloque está colapsado por defecto: haz clic en el título para expandirlo.

<details> <summary><strong>Memoria semántica con decaimiento temporal</strong></summary>

Grafo de conocimiento en SQLite + sqlite-vec, embeddings locales (all-MiniLM-L6-v2 vía ONNX), búsqueda por similitud coseno ponderada por recencia, decaimiento automático de nodos viejos y resolución de contradicciones (sobrescribir / acumular / archivar).

</details> <details> <summary><strong>Proactividad responsable</strong></summary>

Motor de iniciativa en dos niveles: pre-filtros baratos (cooldowns, gap global, chat reciente, AFK) y un núcleo determinista de decisión (core/decision/: score, gate de contexto, presupuesto dinámico, cola de diferidos, señal crítica ESCALATE), con el LLM como generador de contenido. Cada resultado (aceptar, descartar, ignorar) realimenta la receptividad, el presupuesto y, vía core/learning, los pesos de scoring: el asistente aprende cuándo y cuánto proponer.

</details> <details> <summary><strong>Agente de código</strong></summary>

Detección de errores del editor vía LSP real (typescript-language-server): sensor de errores, índice de símbolos, propuestas de parche con diff, verificación posterior con el LSP y node --check, y rollback automático si el parche rompe el archivo.

Antes de planificar, RepositoryIntelligence construye de forma asíncrona un mapa acotado de archivos y dependencias locales, identifica candidatos según la intención y los enriquece con símbolos LSP. Tras una mutación, el mismo índice calcula dependientes y pruebas relacionadas: en repositorios con tests/run-all.sh, esas suites focales corren antes de los sellos generales configurados. El caché persistido contiene metadatos estructurales, no contenido fuente, y se invalida al editar.

</details> <details> <summary><strong>Multi-proveedor de LLM</strong></summary>

Proveedores configurables con cadena de fallback, reintento exponencial con jitter, límite de fallas consecutivas y mensajes accionables ante límites de uso. El catálogo efectivo de modelos vive en core/llm/catalog.js.

</details> <details> <summary><strong>Automatización de navegador</strong></summary>

open_website abre por defecto el navegador personal/predeterminado, por lo que conserva tus sesiones, pero Kaoru solo solicita abrir la URL y no recibe acceso directo a tus cookies o contraseñas. Las tareas que necesitan inspeccionar el DOM, buscar, hacer clic y verificar usan Chromium administrado por Playwright con un perfil separado.

Para play_media, Permisos → Navegador para multimedia permite elegir entre el navegador personal y Chromium administrado. El personal es el valor predeterminado: Kaoru resuelve el video exacto, solicita abrirlo con autoplay y conserva tu sesión (YouTube todavía puede exigir un clic por sus políticas de reproducción). El modo administrado permite verificar la reproducción, aunque algunos sitios pueden limitar perfiles automatizados. La preferencia guardada prevalece sobre lo que proponga el modelo y se muestra antes de autorizar la acción.

</details> <details> <summary><strong>Automatización de escritorio</strong> (beta)</summary>

El motor intenta primero accesibilidad semántica: AT-SPI2 en Linux y UI Automation en Windows. Para canvas, juegos o controles sin árbol accesible existe un fallback visual acotado: cada clic debe referirse a una captura vigente, expira a los 30 segundos, se consume una sola vez y exige observar de nuevo. macOS conserva herramientas generales de aplicaciones, procesos y cámara, pero no implementa todavía la misma paridad semántica de UI.

Para una petición con varios resultados en el escritorio, desktop_mission crea una misión secuencial. Una revisión con el modelo comprueba que el plan cubra la petición original; la autorización inicial y los permisos de cada herramienta se resuelven fuera del modelo. Cada paso requiere una postcondición de accesibilidad o un título exacto de ventana: si el resultado no aparece, Kaoru pausa la misión y muestra el paso pendiente. La cobertura de accesibilidad depende de la aplicación y la revisión semántica puede equivocarse; estas misiones se han probado con escenarios simulados, no con una muestra de usuarios externos.

Las familias de capacidad (aplicaciones, navegador, pantalla, puntero, teclad