Arquitectura de MacBrain

Visión general

MacBrain separa el modelo de IA del runtime que controla la ejecución. El modelo puede proponer una herramienta y sus argumentos, pero no tiene autoridad para ejecutar acciones, modificar permisos ni aprobar confirmaciones.

flowchart TD
    USER["👤 Usuario"]

    UI["🖥️ UI / Prompt Toolkit"]
    VOICE["🎙️ Voz / Whisper"]

    AGENT["🧠 Agent Runtime<br/>Agent.run · Plans · Cancellation"]

    CONTEXT["📚 Context Manager<br/>Sistema · Proyecto · Memoria<br/>Resumen · Historial · Skills"]

    LLM["🤖 LLM Layer<br/>LM Studio · Ollama · OpenAI<br/>Gemini · OpenRouter"]

    PROTOCOL["🔌 Tool Protocol<br/>Native Tool Calling / JSON Fallback"]

    REGISTRY["🧩 ToolRegistry<br/>Schema Validation · Routing"]

    PERMISSIONS["🔐 PermissionManager<br/>ALLOW · ASK · DENY"]

    CONFIRM["❓ Pending Action<br/>Exact Tool + Exact Arguments"]

    TOOLS["🛠️ Tool Handlers"]

    CODING["💻 Coding Tools<br/>Files · Search · Index<br/>Edits · Diff · Tests · Undo"]

    SYSTEM["🖥️ System Tools<br/>Apps · Finder · Notifications<br/>Volume · System Status"]

    VOICE_TOOLS["🎙️ Voice Tools"]
    CAMERA["📷 Camera / Vision<br/>Isolated Process"]

    VERIFY["🧪 Verification<br/>Results · Tests · Checkpoints"]

    STATE["💾 Persistent State<br/>SQLite · Sessions · Plans<br/>Checkpoints · Index"]

    MEMORY["🧠 Semantic Memory"]

    USER --> UI
    VOICE --> AGENT
    UI --> AGENT

    AGENT --> CONTEXT
    CONTEXT --> LLM

    LLM --> PROTOCOL
    PROTOCOL --> REGISTRY
    REGISTRY --> PERMISSIONS

    PERMISSIONS -->|ALLOW| TOOLS
    PERMISSIONS -->|ASK| CONFIRM
    CONFIRM -->|User approves| TOOLS
    PERMISSIONS -->|DENY| AGENT

    TOOLS --> CODING
    TOOLS --> SYSTEM
    TOOLS --> VOICE_TOOLS
    TOOLS --> CAMERA

    CODING --> VERIFY
    SYSTEM --> VERIFY
    VOICE_TOOLS --> VERIFY
    CAMERA --> VERIFY

    VERIFY --> AGENT
    VERIFY --> STATE
    STATE --> MEMORY
    MEMORY --> CONTEXT

Flujo de una petición

Usuario / voz
     |
     v
UI / Voice
     |
     v
Agent.run + CancellationToken
     |
     +--> Context Manager
     |      |
     |      +--> sistema
     |      +--> proyecto
     |      +--> memoria semántica
     |      +--> resumen
     |      +--> historial
     |      +--> skills / MACBRAIN.md
     |
     v
LLM Provider
     |
     +--> Native Tool Calling
     |
     +--> JSON Fallback
     |
     v
ToolRegistry
     |
     +--> schema validation
     +--> tool routing
     |
     v
PermissionManager
     |
     +--> ALLOW ------+
     |                |
     +--> ASK --> Pending Action
     |                |
     |                +--> confirmación explícita
     |
     +--> DENY
     |
     v
Tool Handler
     |
     +--> archivos / código
     +--> búsqueda / indexación
     +--> comandos
     +--> sistema / aplicaciones
     +--> voz
     +--> cámara
     |
     v
Verification
     |
     +--> resultado
     +--> diff
     +--> tests
     +--> checkpoint / undo
     |
     v
Siguiente paso del agente
     |
     +--> nueva herramienta
     |
     +--> respuesta final
     |
     +--> memoria / sesión persistente

Componentes

agent.py: bucle principal del agente, planificación, confirmaciones, contexto, compactación y cancelación.
llm.py: streaming, tool calling, fallback JSON, caché de modelos y diagnóstico.
registry.py: registro de herramientas, validación de esquemas, permisos y aislamiento de handlers.
permissions.py: reglas allow, ask y deny independientes del modelo.
sessions.py: sesiones, mensajes, resúmenes, planes y acciones pendientes en SQLite.
memory.py: memoria semántica persistente y migración del formato anterior.
workspace.py: checkpoints recuperables para cambios de archivos.
indexing.py: índice incremental de nombres y contenido para búsquedas rápidas.
skills.py: descubrimiento de skills e instrucciones MACBRAIN.md.
ui.py: prompt, historial, autocompletado, barra de estado y progreso.
diagnostics.py: /doctor y registro de eventos técnicos locales.
voice.py: captura de micrófono, wake word y transcripción local aislada mediante Whisper.
tools/: capacidades concretas expuestas al agente y limitadas mediante esquemas y permisos.

Límites de confianza

La arquitectura utiliza una separación explícita entre intención, decisión de ejecución y ejecución.

El texto del usuario puede solicitar una acción, pero no puede aprobar automáticamente una acción pendiente anterior.
El modelo puede proponer herramientas y argumentos, pero no puede cambiar la política de permisos.
El modelo no puede establecer por sí mismo el campo de confirmación de una herramienta.
Una confirmación se vincula a la herramienta y argumentos exactos de la acción pendiente.
Los resultados de archivos y comandos regresan al modelo como datos, no como instrucciones confiables.
Las rutas deben permanecer dentro de las raíces permitidas después de resolver enlaces simbólicos.
Los comandos se ejecutan sin shell=True, con ejecutable permitido, cwd validado, timeout, salida limitada y cancelación del grupo de procesos.
Las operaciones de archivos utilizan checkpoints para permitir recuperación y undo.
Cámara y GUI de OpenCV viven en un proceso separado por defecto para aislar fallos del proceso principal.

Principio central

             EL MODELO PROPONE
                    |
                    v
             ┌───────────────┐
             │   RUNTIME     │
             │               │
             │ Validate      │
             │ Permissions   │
             │ Confirmation  │
             │ Execution     │
             │ Verification  │
             └───────┬───────┘
                     |
                     v
              ACCIÓN REAL

El modelo decide qué quiere hacer. El runtime decide si puede hacerlo.

Persistencia

state.db utiliza WAL para soportar operaciones cortas desde el runtime y workers.

Cada resumen guarda el ID del último mensaje que cubre. Al reanudar una sesión, MacBrain carga ese resumen y únicamente los turnos posteriores necesarios para reconstruir el contexto.

El contenido completo de las conversaciones permanece local.

events.jsonl registra eventos técnicos, pero excluye mensajes, contenido de archivos, argumentos de herramientas y claves de API.

La memoria semántica se mantiene separada del historial conversacional y permite conservar información relevante entre sesiones.

Contexto y compactación

MacBrain mantiene un presupuesto de contexto para evitar que el historial consuma toda la ventana disponible del modelo.

┌─────────────────────────────────────┐
│          Context Window             │
├─────────────────────────────────────┤
│ System instructions                 │
│ Project instructions / MACBRAIN.md   │
│ Skills                              │
│ Semantic memory                     │
│ Active plan                         │
│ Conversation summary                │
│ Recent conversation                 │
│ Tool schemas                        │
│ Reserved response tokens            │
└─────────────────────────────────────┘

Cuando el contexto se acerca al límite:

Historial largo
      |
      v
Compactación
      |
      +--> objetivos
      +--> decisiones
      +--> hechos relevantes
      +--> estado del plan
      |
      v
Resumen persistente
      |
      v
Turnos recientes completos

Si el proveedor rechaza una solicitud por exceso de contexto, MacBrain puede aprender el límite reportado, compactar y reintentar.

Herramientas y ejecución

Cada herramienta debe declarar:

esquema JSON de argumentos;
categoría;
nivel de riesgo;
modo de confirmación;
handler responsable de ejecutar la operación.

El flujo de ejecución es:

Tool Call
   |
   v
Parse
   |
   v
Schema Validation
   |
   v
Permission Check
   |
   v
Confirmation (si corresponde)
   |
   v
Handler
   |
   v
ToolResult
   |
   v
Agent

Los handlers no deben confiar en argumentos sin validar.

Las operaciones largas deben llamar check_cancelled() o utilizar mecanismos de ejecución que soporten cancelación.

Extensibilidad

MacBrain puede extenderse mediante:

nuevos proveedores LLM;
nuevas herramientas;
skills locales;
instrucciones MACBRAIN.md;
nuevos backends de voz o visión;
nuevas reglas de permisos;
nuevos mecanismos de almacenamiento.

Las extensiones no deben poder saltarse las fronteras de seguridad del runtime.

Una skill puede aportar instrucciones y contexto, pero no puede convertir una operación prohibida en una operación permitida.

Capas de arquitectura

┌─────────────────────────────────────────────┐
│                 USER INTERFACE              │
│       Prompt Toolkit · Voice · Commands     │
├─────────────────────────────────────────────┤
│                 AGENT CORE                  │
│ Planning · Context · Cancellation · Memory  │
├─────────────────────────────────────────────┤
│                  LLM LAYER                  │
│ LM Studio · Ollama · OpenAI · Gemini · ...  │
├─────────────────────────────────────────────┤
│               TOOL RUNTIME                  │
│ Registry · Validation · Permissions         │
├─────────────────────────────────────────────┤
│              EXECUTION LAYER                │
│ Files · Code · Commands · System · Vision   │
├─────────────────────────────────────────────┤
│             VERIFICATION LAYER              │
│ Tests · Diff · Checkpoints · Undo           │
├─────────────────────────────────────────────┤
│             PERSISTENCE LAYER               │
│ SQLite · Sessions · Memory · Index          │
└─────────────────────────────────────────────┘

La regla arquitectónica más importante es que ninguna capacidad proporcionada por el modelo debe saltarse el runtime de herramientas, la validación o el sistema de permisos.

FilesExpand file tree

ARCHITECTURE.md

Latest commit

History