Documentación de COGO

COGO es tres caras sobre una misma lógica: un visor web para todos, un servidor MCP para tus agentes y una CLI para usuarios avanzados — todo el mismo binario Go.

Cara	Para quién	Cómo
Visor web	todos	cogo serve -http :8080 → navegador (Vault · Frescura · Pack · Grafo · Revisión · Guard · Veracidad)
MCP	tu agente (Claude, Codex, Cursor, Gemini…)	cogo serve (stdio) o /mcp por HTTP — herramientas: pack search open capture verify archive restore remove guard xray
CLI	usuarios avanzados	cogo add · pack · search · stale · verify · lint · agents

Cómo se calcula el color

confianza = min( evidencia , frescura , dependencia más débil , contradicción )

Una nota es verde solo cuando nada la empuja hacia abajo: evidencia observada, un check que pasó, fresca, todas sus dependencias en verde y sin contradicciones. Cada color lleva su color_reason, así que siempre puedes auditar por qué terminó como terminó.

• La evidencia pone el techo: lo observado (un log, un comando, un test, un archivo) puede llegar a verde; lo reportado o inferido topa en amarillo; sin evidencia es rojo.
• La frescura decae por tipo: un comando dura 30 días; una decisión de arquitectura, 180.
• Editar una nota cambia el color — de eso se trata. El visor recalcula el color en vivo mientras escribes: agrega evidencia observada y se pone más verde; cambia la afirmación y se reinicia a “necesita re-verificación”; presiona verify (“lo comprobé”) y pasa a verde.

Anatomía de una nota

---
id: fisherboy-redis-hostname
type: bug                 # decision|bug|runbook|architecture|constraint|command|mistake
project: fisherboy
evidence:
  - kind: direct_log      # observada → puede llegar a verde
    ref: "log de la api 2026-06-27T14:03Z: connect OK a redis:6379"
check:
  test: "leer el env efectivo del worker; probar conectividad a fisherboy-redis:6379"
  status: not_run         # passed | failed | not_run
last_verified: 2026-06-27
depends_on: [fisherboy-redis-topology]
# ---- calculado por COGO · no editar ----
confidence: yellow
color_reason: "evidencia observada pero el check no ha pasado"
---

## Claim
El worker probablemente falla porque no puede resolver el hostname interno de Redis.

El vault de Markdown es la única fuente de verdad: portable, diffeable, y sobrevive a la herramienta. Todo lo demás es un cliente delgado o una caché reconstruible.

El visor web

Las pestañas — la interfaz está en español, así que estos son los nombres que verás en pantalla: Vault (tus notas, cada una con su color: búsqueda BM25, filtros, rango de fechas de creación y paginador), Vigencia (lo vencido y lo que está por vencer, con un botón de revalidar), Agentes (escribe y versiona el AGENTS.md / CLAUDE.md que tus agentes leen al arrancar, y pégales bloques de contexto coloreado), Grafo (cómo se relacionan las notas, y cómo se propaga el rojo), Revisión (enlaces rotos, notas vencidas, contradicciones), Guard y Veracidad.

También puedes conectar un repositorio de GitHub y navegarlo desde el visor: un árbol de archivos clásico, o un mapa de grafos coloreado por confianza que muestra qué partes del código tienen conocimiento verificado detrás.

Todo lo operativo vive en el menú kebab del visor — sin necesidad de terminal: Conexiones MCP (emitir/revocar tokens con nombre por app, con vencimiento y un modo de solo lectura), Papelera (restaurar o borrar para siempre), Auditoría MCP (qué token llamó qué herramienta, cuándo y desde qué IP — descargable y podable), Raíces de evidencia (contra qué carpeta se resuelve la evidencia de cada proyecto), Exportar (backup) (todo el vault como un zip, sin secretos), Instrucciones para agentes y Ajustes · Modelo de IA.

Guard, paso a paso

Guard responde una sola pregunta: “¿este turno del modelo me está empujando?”

1. Declara tu mandato (una vez): tu objetivo y tus líneas rojas (“no renuncio sin otra oferta firmada”). Se guarda en el vault. Sin mandato, la manipulación y la persuasión legítima son indistinguibles — COGO entonces solo nombra técnicas, sin veredicto.
2. Pega el turno (y la conversación previa, un mensaje por línea: U: tú, M: el modelo) → una radiografía coloreada: verde — sin señales; amarillo — hay persuasión, o toca tu línea roja; rojo — hay mecánica, o hay recibos.
3. Los recibos son el superpoder: como COGO ve la transcripción, cuando el modelo niega lo que dijo (“yo nunca te dije que renuncies”) COGO encuentra el turno donde SÍ lo dijo y muestra ambas citas, lado a lado. El gaslighting deja de ser tu palabra contra la suya.
4. Cada táctica detectada llega con sus preguntas críticas y su contramedida — el motor no censura al modelo: te inocula a ti. Él muestra; tú decides.

La ontología detrás: 108 técnicas de manipulación destiladas de seis disciplinas ofensivas — persuasión (Cialdini, Kahneman), interrogatorio policial y militar (técnica Reid, Army FM 2-22.3, Scharff), negociación (Harvard, Voss), coerción y reforma del pensamiento (Lifton, Biderman), manipulación emocional (gaslighting, DARVO, FOG) y retórica/propaganda (Frankfurt, Grice, Walton) — cada una con su fuente real, cómo se ve en un chat, y su contramedida.

La regla de hierro

Ningún modelo dictamina “te están manipulando”. Los dientes son deterministas (marcadores, recibos, trayectoria); los modelos solo proponen — y cada propuesta se verifica contra el texto literal o se descarta. Con un modelo conectado aparecen dos niveles opcionales: propuestas estructurales (patrones que ningún diccionario ve) y el steelman adversarial — otro modelo argumentando deliberadamente el lado que el turno no te mostró. El marco teórico está en docs/fundamento-teorico.md.

Veracidad: ¿sólido, o humo?

El gemelo de Guard. Donde Guard pregunta “¿me está empujando?”, la pestaña Veracidad (herramienta MCP xray) pregunta “¿esta respuesta se sostiene?”. Pega la respuesta de un modelo y COGO la radiografía oración por oración, de forma determinista, sin ningún modelo: mide el compromiso (matizado o fuertemente aseverado), la evidencia (observada, reportada o ninguna) y si es falsable (una opinión disfrazada de hecho). Una afirmación fuerte y sin sustento sale en rojo; una sólida con evidencia observada, mejor. Documento de diseño: docs/motor-veracidad.md.

Evidencia que se vuelve a chequear

La evidencia de una nota no es una sensación: es una referencia que COGO puede ir a verificar de nuevo. Además de las rutas locales, dos esquemas la hacen duradera:

evidence:
  - kind: command_output
    ref: github://acme/api@main/internal/db.go:88   # anclada al SHA del blob
  - kind: direct_log
    ref: artifact://9f2a…                           # dirección por contenido, inmutable

Las referencias a GitHub quedan ancladas al SHA del blob del archivo. Eso le devuelve los dientes al motor de color en una instancia hospedada (que no tiene una copia de trabajo de tu código), y habilita la frescura anclada a git: la nota sigue verde mientras el archivo citado no cambie, y cae a amarillo en cuanto cambia. Si citas un commit fijo, la evidencia es inmutable.

Los artefactos (stash) se guardan bajo el SHA-256 de su contenido, en disco o en Cloudflare R2. Como la clave es el hash, verify lo recomputa en vez de confiar en una cita que se pudre. Un escáner de secretos corre antes de guardar nada y se niega por defecto, así que una credencial filtrada nunca queda inmortalizada.

Varios agentes, un solo vault

Con MCP sobre HTTP y un token, agentes en máquinas distintas comparten un mismo vault:

• recall es el cursor que convierte el vault de archivo en canal. Lo llamas sin argumentos y obtienes la memoria que sostiene el proyecto (el mandato, las decisiones verdes) más un cursor; devuelves ese cursor como since y obtienes solo lo que cambió.
• lease toma un permiso con vencimiento sobre un recurso antes de un trabajo riesgoso y no idempotente — una migración, un deploy, una edición masiva — para que dos agentes no lo ejecuten a la vez.
• Cada nota registra quién la capturó, y el visor permite filtrar por agente.
• El log de auditoría registra qué herramienta llamó cada token, cuándo y desde qué IP. Se puede descargar y podar, entrada por entrada o entero.

La CLI

cogo init                 # crear un vault
cogo add nota.md          # validar, calcular el color, guardar (stdin si no hay archivo)
cogo pack "redis"         # armar un contexto coloreado para un tema (degrada lo rojo)
cogo search "worker"      # listar: color · id · resumen (sin cuerpos)
cogo stale                # qué está vencido o por vencer
cogo verify <id>          # "lo comprobé": revalidar y recolorear
cogo lint                 # enlaces rotos, notas vencidas, contradicciones (si hay modelo)
cogo agents --claude      # generar el CLAUDE.md/AGENTS.md que le enseña el protocolo a un agente
cogo serve -http :8080    # visor web + servidor MCP por HTTP
cogo serve                # servidor MCP por stdio

Accesorios opcionales (apagados por defecto)

COGO es 100% determinista y standalone sin nada de esto. Cada accesorio se habilita por variable de entorno y nunca toca el núcleo:

Accesorio	Se habilita con	Para
Modelo de IA (OpenRouter, Ollama, DeepSeek…)	COGO_LLM_BASE_URL + COGO_LLM_MODEL (o Ajustes en la GUI)	detectar contradicciones entre notas + los niveles opcionales de Guard
Juez fuerte independiente	COGO_LLM_STRONG_BASE_URL + COGO_LLM_STRONG_MODEL	que el steelman de Guard no comparta cerebro con el proponente
Scrub de Anonimal	ANONIMAL_URL	mantener secretos/PII fuera del vault
Login de Lockatus (OIDC)	AUTH_MODE=federado	federarse con la Suite Escriba

Nota

El detalle completo vive en el repo: el manual para principiantes, la guía de despliegue completa (cada variable, backup, endurecimiento) y los documentos de diseño de los motores de veracidad y autonomía.

Ver en GitHub