Cognia — IA cognitiva local que aprende (Arquitectura Simbolico-Neural)

IA local, ligera y privada. Corre en CPU con un modelo 3B, sin APIs externas y sin PyTorch en el camino critico. Aprende, razona y recuerda en tu propia maquina — con memoria episodica, un creador de imagenes/escenas AI-nativo, y prompts que se auto-mejoran (auto-prompting). Instalable en un comando: pip install cognia-ai.

Stack: Python 3.11+ (3.12 recomendado) · SQLite · Qwen2.5-Coder-3B (GGUF / INT4) · llama.cpp · sentence-transformers · numpy · FastAPI · Electron

---

Tabla de contenidos

• Que es Cognia
• Estado del proyecto
• Instalacion
• Uso — el REPL
• El agente y el ruteo hibrido
• Modelo e inferencia
• Rendimiento (benchmarks reales)
• Modulos principales
• Arquitectura Diferencial
• Capa Cognitiva Chimera
• Inferencia distribuida (swarm)
• Seguridad y privacidad
• Desarrollo y tests
• Documentacion
• Para colaborar

---

Que es Cognia

Cognia es una arquitectura cognitiva que aprende, razona y recuerda localmente. A diferencia de un chatbot, gestiona un ciclo de vida cognitivo completo: memoria episodica y semantica, un grafo de conocimiento, consolidacion de memoria durante el "sueno", y razonamiento que puede distribuirse entre varios dispositivos de una red local.

Tres ideas la definen:

1. Local-first y privada. Tus datos nunca salen de tu maquina salvo que conectes nodos en una red mesh de forma explicita. Memorias cifradas en reposo (AES-256-GCM).
2. Ligera. Inferencia en CPU mediante llama.cpp (GGUF cuantizado) o shards numpy puro (INT4), sin PyTorch ni Tensorflow en el motor principal.
3. Cognitiva, no solo generativa. Router de dominio (LOGOS/TECHNE/RHETOR), ciclo de sueno de consolidacion, world-model que simula consecuencias antes de actuar, y una capa cognitiva Chimera construida sobre todo lo anterior.

---

Estado del proyecto (Julio 2026)

Fase	Estado	Descripcion
Fases 1-6 — Estabilizacion y core	COMPLETADA	Base limpia, NarrativeThread, MeshNode, seguridad, escalado.
Fase 7 — Shattering (SRDN)	COMPLETADA	Sub-modelos LOGOS/TECHNE/RHETOR, MoE, NPQ, RST, MLA.
Fase 8 — Commercial release	COMPLETADA	Instaladores, UX, cifrado por defecto, documentacion.
Fases 9-12 — Hardening y UX	COMPLETADA	Proteccion SQLi/XSS/SSRF, consentimiento de privacidad, auto-update.
Fase 13 — Inferencia distribuida real	COMPLETADA	Qwen2.5-Coder-3B INT4, auto-sharding, relay WebSocket.
Inferencia local llama.cpp	OPERATIVA	GGUF como ruta primaria (~8-9 tok/s en un i3 de 2 cores / 4 threads); shards numpy como fallback.
Capa cognitiva Chimera	OPERATIVA	Band router de 3 bandas, cognitive loop, memoria jerarquica, world-model.
Especialistas MoM (Mixture of Models)	OPERATIVA	Portero 0.5B para turnos rapidos (~3.3–3.9×), escalado reactivo 3B→7B en codigo duro (+20pp), router de expertos LoRA. cognia install-model los monta; degradan al 3B si faltan.
Agente + ruteo hibrido por dificultad	OPERATIVA (3.9.0)	/hacer (loop ReAct con herramientas reales) + perfil por dificultad de tarea: mono / agente / +colonia / +superorganismo, gobernado por /esfuerzo.

Detalle tecnico por fase en ROADMAP.md. Bitacora de sesiones en CLAUDE_NOTES.md y MANAGER_LOG.md.

---

Instalacion

Un solo comando (PyPI) — recomendado

pip install cognia-ai
cognia

Eso es todo: pip install cognia-ai deja el comando cognia listo, y cognia abre el asistente (primer arranque = wizard de configuracion, luego el REPL). Corre 100% local con el modelo 3B (Qwen2.5-Coder-3B via llama.cpp); la orquestacion online viene apagada por defecto (forzable con COGNIA_DISABLE_SWARM=1). Incluye el creador de imagenes/escenas AI-nativo y los prompts que se auto-mejoran.

pip install "cognia-ai[semantic]"   # + embeddings reales (sentence-transformers, ~2GB)
pip install "cognia-ai[llama]"      # + llama.cpp via pip (requiere wheel prebuilt o compilador C++)
pip install "cognia-ai[all]"        # todo

Requisitos: Python 3.11+ (3.12 recomendado). Para la inferencia el camino recomendado es cognia install-model: descarga el GGUF 3B + llama-server (el mas rapido en CPU, sin compilador) mas el portero 0.5B y los expertos LoRA a ~/.cognia/, y deja todo configurado (config.env). Alternativas: (2) cognia-ai[llama] (llama-cpp-python) — necesita wheel prebuilt o compilador C++; (3) shards numpy (INT4, Python puro) — camino avanzado/experimental, mas lento (cognia install-weights). El primer arranque (cognia) te guia.

Instaladores rapidos (desde el repo — stack swarm LEGACY)

Estos scripts montan el stack de shards numpy/swarm (legacy), no el stack recomendado GGUF+llama-server. Para el producto usa pip install cognia-ai + cognia install-model.

Windows (PowerShell):

.\install.ps1

Linux / macOS (Bash):

bash install.sh

El instalador crea un entorno, instala dependencias y descarga el modelo (~300 MB en modo swarm, ~1.2 GB en modo standalone con los 4 shards).

Desktop App (Electron)

cd cognia_desktop
npm install
npm run build:win    # o build:linux / build:mac

Releases precompilados

Plataforma	Archivo	Requisitos
Windows	CogniaDesktop-x.x.x-Setup.exe	Python 3.11+
Linux	CogniaDesktop-x.x.x.AppImage	Python 3.11+
Android	cognia-mobile-x.x.x.apk	Android 8+

Releases: https://github.com/tomascomenta-blip/cognia_v2/releases

Nota: los instaladores Desktop publicados corresponden a una version anterior (era 3.2.x). La via al dia es el paquete de PyPI (pip install cognia-ai).

Nota sobre Python: el venv/ del repo puede apuntar a un interprete sin wheels disponibles. Se recomienda Python 3.12. En desarrollo, este repo usa venv312/Scripts/python.exe — sustituyelo por tu interprete si difiere.

---

Uso — el REPL

Arranca Cognia (lanza el wizard la primera vez, luego abre el REPL interactivo):

python -m cognia

Dentro del REPL, cualquier texto sin / es chat cognitivo; los comandos empiezan con /:

La zona de entrada va encuadrada en verde, con la barra de estado (modelo, contexto, modo) colgando bajo el marco:

────────────────────────────────────────────────────────────────
 cognia➤ hola, que sabes hacer?          <- chat libre (inferencia)
────────────────────────────────────────────────────────────────
qwythos-9b · ctx 12.4k/131k · chat
tab completa · ↑↓ historial · @ archivo · / comandos

 cognia➤ /ayuda                          <- lista completa de comandos (206)
 cognia➤ /hacer crea un juego de la vida en vida.py y probalo
 cognia➤ /salir

Comandos principales

Comando	Que hace
<texto libre>	Chat cognitivo (inferencia + memoria).
/hacer <tarea>	Agente autonomo: ejecuta la tarea con herramientas reales (archivos, codigo, busqueda).
/probar <ruta|URL|comando|carpeta>	Probar lo hecho (4.29): renderiza paginas, inspecciona imagenes/audio/video, valida json/yaml/csv, lee pdf/docx/xlsx/3d, ejecuta .py con lint y prueba apps graficas con teclas y capturas. /probar ayuda <tema> lista las ~65 tools.
/fases "<encargo>"	Obra por fases (4.30): planificar (Definicion de Hecho verificable), prototipo, completar, testing, visual, pulido, optimizacion, red team, regresion y release; cada iteracion la verifica el arnes, un juez acepta (commit) o revierte (git). cognia fases "<encargo>" fuera del REPL.
/escritorio	El escritorio virtual propio de Cognia (Windows): ahi lanza y prueba apps graficas sin molestar al usuario. /escritorio foco nunca|inactivo|siempre.
/esfuerzo [nivel]	Cuanto sistema despertar: bajo/medio/alto/maximo (gobierna el ruteo hibrido).
/modelo [3b|7b]	Ver/cambiar el modelo activo del fleet.
/largo <tema>	Generacion larga por secciones con checkpoint (--continuar).
/pensar <problema>	Razonamiento paso a paso (stepwise).
/crear <idea>	Crear un programa Python ahora (sandbox + biblioteca).
/oficina	Dashboard de oficina (jefe→directores→trabajadores sobre el agente).
/plan <objetivo>	Descomponer un objetivo en pasos.
/ayuda	Lista completa de comandos (o /ayuda <comando> para el detalle).
/yo	Perfil cognitivo y estado interno de la memoria.
/memoria	Estado de la memoria episodica/semantica.
/aprender <frente> | <respuesta> [| tema]	Crear tarjeta de estudio (repaso espaciado).
/observar <texto>	Guardar una observacion sin procesar.
/dormir	Ciclo de consolidacion y limpieza (sueno).
/grafo <concepto>	Visualizar el grafo de conocimiento local.
/sesiones	Listar sesiones de chat recientes.
/salir	Salir del REPL.

Tambien hay una TUI (python -m cognia.tui): textual viene en el core desde 4.8.x, no hace falta ningun extra.

Subcomandos de la CLI

cognia                  # REPL (wizard en el primer uso)
cognia init             # Re-ejecutar el wizard de configuracion
cognia install-model    # Stack de inferencia recomendado: GGUF 3B + llama-server b9391 + expertos LoRA + portero 0.5B
cognia install-model --with-heavy-code   # + especialista 7B de codigo (~4.7 GB, opt-in): escalado 3B->7B en codigo duro (+20pp)
cognia modo             # Ver/cambiar el modo (local / compartido / memoria)
cognia doctor           # Diagnostico de la instalacion (backend GGUF incluido)
cognia status           # Estado del backend local (GGUF), swarm y Ollama
cognia install-weights  # (avanzado) Descargar shards numpy y configurar este equipo como nodo
cognia install-weights --standalone   # (avanzado) Los 4 shards para uso local completo
cognia server           # Servidor web FastAPI (puerto 8000)
cognia node             # Iniciar como nodo del swarm distribuido
cognia coordinator      # Iniciar el coordinador del swarm (puerto 8001)
cognia leave            # Salir de la red y liberar el shard alojado

---

El agente y el ruteo hibrido

/hacer <tarea> corre el agente: un loop ReAct que piensa, emite acciones (ACCION: <herramienta> <args>) y observa resultados, con herramientas reales (escribir/leer archivos, generar y PROBAR codigo, buscar, knowledge graph, escenas). El costo se gobierna con el ruteo hibrido por dificultad (3.9.0): la dificultad estimada de la tarea (cero LLM) + el nivel /esfuerzo deciden cuanto sistema despertar —

mono                          tarea trivial: respuesta directa
agente                        facil-media: loop con tools, 1 modelo (3B)
agente + colonia              media: etapas multi-modelo permitidas (7B, 4B)
agente + colonia + superorganismo   dura: colonia por pedazos (etapa 4)

Las etapas caras son reactivas: solo corren si lo barato fallo sus tests. En codigo duro la cascada completa mide 57.5→67.5% en tests ocultos vs 40% del 3B solo. Kill-switch global: COGNIA_HIBRIDO=0 (comportamiento clasico).

---

Modelo e inferencia

Cognia resuelve cada prompt por la primera ruta de inferencia disponible, en este orden:

1. llama.cpp + GGUF (ruta local primaria). Si encuentra un GGUF de Qwen2.5-Coder-3B, lo carga via llama-cpp-python o llama-server. Es la ruta mas rapida y de mejor calidad en una sola maquina. El backend lo resuelve solo: LLAMA_GGUF_PATH (lo escribe cognia install-model en ~/.cognia/config.env) → SHARD_WEIGHTS_DIR → auto-descubrimiento en ~/.cognia/models/.
2. Shards numpy INT4 (fallback distribuido / local). Forward pass en numpy puro sin PyTorch, repartible entre nodos del swarm. Es el corazon de la arquitectura Shattering.
3. Ollama (fallback legacy, opcional). Si defines OLLAMA_URL y no hay backend GGUF vivo, se usa como ultimo recurso.

Especialistas (Mixture of Models)

Sobre el 3B base, cognia install-model monta una cascada de especialistas que se activan solos y degradan al 3B si su modelo no esta presente (nada se rompe):

• Portero 0.5B — atiende los turnos triviales de charla (saludo, identidad, cortesia) a ~3.3–3.9× la velocidad del 3B. Se instala por defecto.
• 7B de codigo (opt-in) — con install-model --with-heavy-code, cuando el 3B falla los tests de una tarea de codigo dificil se reintenta con Qwen2.5-Coder-7B en greedy (codigo duro 37.5→57.5% pass@1, +20pp). Lazy-load-usar-cerrar: RAM en reposo 0; COGNIA_HEAVY_CODE=0 lo apaga.

Configurar el modelo

El backend GGUF detecta automaticamente cualquiera de estas cuantizaciones (de mayor a menor prioridad): Q4_K_M (la medida como mejor en b9391), Q4_0, Q3_K_S, Q5_K_M. Para apuntar a una carpeta de modelos concreta, define la ruta absoluta:

# ~/.cognia/config.env
SHARD_WEIGHTS_DIR=C:\ruta\a\model_shards\qwen-coder-3b-q4

La ruta absoluta evita que la deteccion dependa del directorio de trabajo. Si la dejas relativa, solo resuelve cuando arrancas desde la raiz del repo.

Usar otro modelo (p. ej. Qwen2.5-7B). LLAMA_GGUF_PATH tiene prioridad sobre la deteccion automatica. Apunta directamente a un GGUF (en modelos split, al primer fragmento -00001-of-NNNNN.gguf; llama.cpp carga el resto):

# LLAMA_GGUF_PATH=C:\ruta\a\qwen2.5-7b-instruct-q4_k_m-00001-of-00002.gguf

Un 7B es mas capaz pero pesa ~6 GB en RAM y, en una CPU de gama baja con poca memoria libre, puede bajar a ~1 tok/s por swapping. El 3B es el equilibrio recomendado para CPU-only.

Variables de entorno relevantes:

Variable	Default	Uso
LLAMA_GGUF_PATH	(config.env)	Ruta directa a un GGUF; prioridad sobre la deteccion. Sin nada, auto-descubre en ~/.cognia/models/.
LLAMA_SERVER_PATH	(config.env)	Binario llama-server (lo instala cognia install-model).
SHARD_WEIGHTS_DIR	model_shards/qwen-coder-3b-q4	Carpeta del GGUF / shards.
COGNIA_HIBRIDO	1	0 apaga el ruteo hibrido por dificultad (comportamiento clasico).
COGNIA_HEAVY_CODE	1	0 apaga el escalado 3B→7B en codigo duro.
COGNIA_PORTERO	1	0 apaga el portero 0.5B.
COGNIA_SUPERORGANISMO	(perfil)	Fuerza on/off la etapa 4 (colonia por pedazos).
COGNIA_COORDINATOR_URL	(vacio)	URL de la API del coordinador del swarm. Sin definir = modo local.
OLLAMA_URL	http://localhost:11434	Motor Ollama (fallback legacy opcional).
COGNIA_DATA_DIR	~/.cognia/data	Datos y memoria local.
HF_TOKEN	(vacio)	Token de HuggingFace para descargas privadas.

Las claves de ~/.cognia/config.env se cargan en TODOS los entry points (apply_config()); una env var del sistema MANDA sobre config.env y el CLI avisa cuando la pisa.

---

Rendimiento (benchmarks reales)

Medido en un Intel i3-10110U (2 cores / 4 threads, sin GPU dedicada), llama.cpp en CPU. Numeros de streaming real (ver MANAGER_LOG.md):

Configuracion	tok/s	Notas
Q4_K_M, threads=3	7.5 – 8.2	Ruta primaria (la que instala cognia install-model; b9391 pineado).
Q3_K_S, threads=4	7.7	+7% sobre Q4_0, calidad similar.
Q4_0, threads=4 (CPU puro)	7.2 – 8.8	Alternativa.
stream_chat (runs limpios)	8.6 (pico 9.0)	Throughput real sostenido.
Portero 0.5B (turnos triviales)	28 – 36	3.3–3.9× pareado vs 3B.
Vulkan + Intel UHD (offload)	3.7 – 3.8	Peor: la memoria compartida es el cuello de botella.

Notas honestas:

• El techo de este hardware ronda 8-9 tok/s; el objetivo de >10 tok/s no se alcanza sin GPU dedicada real. Una CPU/GPU mas potente sube estos numeros.
• cognia doctor puede reportar ~0.6-0.8 tok/s: ese numero cuenta palabras en una respuesta corta con arranque en frio, no es el throughput de streaming.
• El offload a iGPU Intel via Vulkan es contraproducente; mantener CPU puro.

---

Modulos principales

Modulo	Funcion
KnowledgeGraph	Memoria semantica estructurada y jerarquica.
InferenceEngine	Razonamiento transitivo y herencia de propiedades.
ShatteringOrchestrator	Inferencia distribuida y ruteo MoE (LOGOS/TECHNE/RHETOR).
ConsolidationEngine	Ciclo de sueno: purga, refuerzo y olvido de memorias.
SecureStorage	Cifrado AES-256-GCM de memorias episodicas.
CogniaMeshNode	Red P2P para sincronizacion de conocimiento via CRDT.
BandRouter	Enrutador de contexto/memoria de 3 bandas (LOCAL/MEDIA/GLOBAL).
CognitiveLoop	Clasificador de ruta FAST/RECALL/DELIBERATE/ACT.

---

Arquitectura Diferencial

Cognia no es un wrapper de LLM ni una interfaz de chat con memoria. Las diferencias tecnicas respecto a los sistemas convencionales son estructurales:

• Inferencia sin servidor central: El forward pass ocurre en los dispositivos de los usuarios (shards .npz en numpy puro, sin PyTorch). El coordinador enruta pero no ejecuta ni almacena nada de la conversacion.
• Memoria episodica como almacen primario: El conocimiento vive en SQLite local + VectorCache numpy por usuario, no en pesos compartidos. Cada instancia aprende de su propio historial sin exponer datos.
• Cuantizacion dinamica en produccion: Los pesos escalan INT4 → INT8 → FP16 → FP32 segun frecuencia de acceso en tiempo real, con auto-decay a INT4 tras inactividad. El objetivo es minimizar RAM sin degradar las rutas calientes.
• Adaptacion personal sin fine-tuning global: El ciclo de sueno entrena adapters LoRA (r=4-8) sobre episodios de alta importancia del usuario y los aplica en las proyecciones KV del transformer. Cada instancia desarrolla un sesgo de respuesta personalizado sin alterar los pesos base compartidos.
• Agregacion federada de SOLO deltas LoRA (NO FedAvg sobre parametros completos): El coordinador (coordinator/federated_store.py, cableado en coordinator/app.py) combina unicamente los adapters LoRA que cada nodo aporta (matrices k_A/k_B/v_A/v_B, r=4-8), nunca los pesos base del modelo. La combinacion es un promedio ponderado de deltas LoRA: peso por tier del nodo × afinidad semantica (similitud coseno del delta efectivo k_A@k_B, v_A@v_B contra el adapter global vigente, w = tier × (1 + 0.3·cos)), que baja el peso de aportes divergentes sin un set de validacion central. Los clientes suman ruido gaussiano (sigma=0.01) antes de enviar. Esto NO es FedAvg sobre parametros completos (prohibido por diseno): los pesos base compartidos jamas se promedian ni se alteran; solo se agrega el subespacio LoRA de bajo rango.
• Ciclo de sueno autonomo: Consolidacion episodica, compresion conceptual, actualizacion del grafo de conocimiento, investigacion autonoma, entrenamiento ELC, procesamiento emocional Plutchik, y auto-expansion de rango LoRA cuando el adapter satura.
• Router de dominio sobre tres sub-modelos: LOGOS (razonamiento, temp=0.3), TECHNE (codigo, temp=0.15), RHETOR (escritura, temp=0.7) — tres perfiles de generacion distintos sobre la misma base Qwen2.5-Coder-3B INT4.

---

Capa Cognitiva Chimera (sistema, no atencion)

Sobre el backbone Qwen2.5-Coder-3B INT4 pre-shardeado se construyo una capa cognitiva inspirada en el whitepaper chimera_transformer.md. HYDRA NO se implementa como mecanismo de atencion (el modelo esta pre-cuantizado y pre-shardeado: alterar la atencion exigiria reentrenar y re-shardar todo el swarm). En su lugar, los conceptos de Chimera se realizan como un analogo a nivel de sistema que orquesta los subsistemas ya existentes. Todo corre offline, sin LLM y sin PyTorch en el camino critico.

Flujo end-to-end (whitepaper seccion 11), un solo comando:

python -m cognia.chimera "calcula 2+2"

Etapas reales del trace: INPUT → bandas HYDRA → route cognitivo → memoria recuperada → plan → critica → verify → world-model (riesgo) → tools → output → memoria escrita.

Que se implemento: literal vs adaptado vs descartado

Subsistema Chimera	Decision	Por que / como	Archivos
HYDRA (atencion 3 bandas)	ADAPTADO (no literal)	Atencion intocable (INT4 pre-shardeado). Reimplementado como enrutador de CONTEXTO/MEMORIA de 3 bandas LOCAL/MEDIA/GLOBAL sobre el router LOGOS/TECHNE/RHETOR.	cognia/context/band_router.py
MoE routing	YA EXISTE (reutilizado)	LOGOS/TECHNE/RHETOR via GlobalRouter. No se duplico.	shattering/router.py
Cognitive Loop (FAST/RECALL/DELIBERATE/ACT)	CONSTRUIDO	Clasificador de ruta + ejecucion real offline de cada ruta.	cognia/reasoning/cognitive_loop.py
Memoria jerarquica 5 capas	ADAPTADO (facade + gating)	Las 5 capas existian sueltas; se unifico y se agrego el write-gate por sorpresa+importancia que faltaba.	cognia/memory/hierarchical.py
World model	ADAPTADO ligero	Sin RSSM neuronal (sin computo). Simulador de consecuencias deterministico (riesgo, reversibilidad, KG) que gatea antes de ejecutar.	cognia/reasoning/action_simulator.py
Planner + critico	YA EXISTE (cableado)	plan_task (templates) + SelfCritic.critique + verify.	cognia/agents/planner.py, cognia/reasoning/self_critic.py, cognia/agents/verifier.py
Agentes + herramientas	YA EXISTE (reutilizado)	tool_registry con tools reales (execute_python, etc.).	cognia/agents/tool_registry.py
Multimodal nativo	DESCARTADO	Inviable: nodos numpy puro sin encoders de vision/audio; fuera de la vision P2P CPU-only.	-
Aprendizaje continuo (3 velocidades)	PARCIAL ya existe	Episodico, adapters LoRA, consolidacion lenta. No se toco en esta capa.	cognia/memory/*
Espacio latente unificado U	DESCARTADO	Exigiria entrenamiento conjunto; los subsistemas se comunican por texto/vectores.	-

Reproducir cada prueba

Usar un interprete Python 3.12. En este repo: venv312/Scripts/python.exe.

# C1 HYDRA 3 bandas
venv312/Scripts/python.exe -m cognia.context.band_router "recuerda lo que dijiste antes sobre shards?"
venv312/Scripts/python.exe -m pytest tests/test_band_router.py -q

# C2 Cognitive Loop
venv312/Scripts/python.exe -m cognia.reasoning.cognitive_loop "calcula 2+2"
venv312/Scripts/python.exe -m pytest tests/test_cognitive_loop.py -q

# C4 Memoria jerarquica con write-gating
venv312/Scripts/python.exe -m cognia.memory.hierarchical
venv312/Scripts/python.exe -m pytest tests/test_hierarchical_memory.py -q

# C5 World-model: simular antes de actuar
venv312/Scripts/python.exe -m cognia.reasoning.action_simulator "delete all files in C:/"
venv312/Scripts/python.exe -m pytest tests/test_action_simulator.py -q

# FASE FINAL integral
venv312/Scripts/python.exe -m cognia.chimera "refactoriza el orchestrator paso a paso e implementa y prueba"
venv312/Scripts/python.exe -m pytest tests/test_chimera.py -q

---

Inferencia distribuida (swarm)

La arquitectura Shattering (SRDN — Sparse-Recursive Distillation Network) permite correr modelos de 3B+ parametros en equipos con poca RAM repartiendo el modelo en shards:

• Auto-sharding: el modelo se divide en fragmentos que corren en distintos nodos de una red local, coordinados por un relay WebSocket.
• Cuantizacion INT4: pesos comprimidos ~75% operados puramente en numpy.
• Coordinador sin estado de conversacion: enruta tokens entre shards; no almacena ni ejecuta el contenido de la sesion.

# Convertir pesos de HuggingFace a shards de Cognia
python scripts/convert_hf_to_shards.py --hf-dir /ruta/a/qwen --out-dir model_shards/qwen-q4

# Levantar coordinador y nodos
cognia coordinator                       # equipo A (puerto 8001)
cognia install-weights --coordinator http://A:8001   # equipo B descarga su shard
cognia node                              # equipo B se une al swarm

Para usar el swarm, COGNIA_COORDINATOR_URL debe apuntar a la API del coordinador (p. ej. https://<servicio>.up.railway.app), no a una URL de dashboard.

---

Seguridad y privacidad

• Local-First: tus datos nunca salen de tu maquina salvo que conectes nodos mesh explicitamente.
• Cifrado en reposo: memorias episodicas con AES-256-GCM.
• Proteccion anti-injection: filtros estructurales en prompts y consultas SQL parametrizadas (sin sqlite3.connect() directo; via storage/db_pool.py).
• Privacidad diferencial: ruido estadistico en sincronizaciones de red para proteger la identidad.

Mas detalle en docs/PRIVACY.md y docs/SECURITY.md.

---

Desarrollo y tests

Suite rapida (excluye el e2e de inferencia, lento/pesado):

python -m pytest tests/ --ignore=tests/test_e2e_inference.py -q

Convenciones del repo (ver ROADMAP.md y CLAUDE.md):

• Sin PyTorch/Tensorflow en el motor de inferencia principal.
• Windows CP1252: los print() y strings del CLI usan ASCII puro (sin emojis ni box-drawing). Este README, al ser documentacion Markdown, si usa Unicode.
• Sin constantes de modelo hardcodeadas: usar shattering/model_constants.py.
• Cada subsistema cierra con una prueba CLI real — nada de mocks/stubs.

---

Documentacion

Documento	Contenido
docs/INSTALL.md	Guia detallada de instalacion y configuracion.
docs/TROUBLESHOOTING.md	Solucion a problemas comunes y diagnostico.
docs/PRIVACY.md	Manejo de datos y privacidad.
ROADMAP.md	Plan de desarrollo y estado de las fases (fuente de verdad).
CLAUDE_NOTES.md	Log real de sesiones de desarrollo y fixes.
MANAGER_LOG.md	Bitacora del manager (benchmarks, decisiones).

---

Para colaborar

Lee el ROADMAP.md para entender la direccion actual. Cognia prioriza la eficiencia (CPU-only), la privacidad y la estabilidad. No se aceptan dependencias pesadas (PyTorch/Tensorflow) en el motor de inferencia principal.

---

© 2026 Cognia Project. Distribuido bajo licencia MIT.