Documentação do COGO

O COGO são três faces sobre uma só lógica: um visualizador web para todos, um servidor MCP para os seus agentes, e uma CLI para usuários avançados — tudo o mesmo binário Go único.

Face	Para quem	Como
Visualizador web	todos	cogo serve -http :8080 → navegador (Vault · Frescor · Pack · Grafo · Revisão · Guard · Veracidade)
MCP	seu agente (Claude, Codex, Cursor, Gemini…)	cogo serve (stdio) ou /mcp via HTTP — ferramentas: pack search open capture verify archive restore remove guard xray
CLI	usuários avançados	cogo add · pack · search · stale · verify · lint · agents

Como a cor é computada

confidence = min( evidence , freshness , weakest dependency , contradiction )

Uma nota é verde só quando nada a puxa para baixo: evidência observada, uma verificação que passou, fresca, todas as suas dependências verdes e nenhuma contradição. Cada cor carrega o seu color_reason, para você sempre poder auditar por que ela terminou daquele jeito.

• A evidência define o teto: observada (um log, um comando, um teste, um arquivo) pode chegar ao verde; relatada ou inferida trava no amarelo; sem evidência significa vermelho.
• O frescor decai por tipo: um comando dura 30 dias; uma decisão de arquitetura, 180.
• Editar uma nota muda a cor — esse é o ponto. O visualizador recomputa a cor ao vivo enquanto você digita: adicione evidência observada e ela fica mais verde; mude a afirmação e ela volta a “precisa de reverificação”; pressione verify (“eu verifiquei”) e ela fica verde.

Anatomia de uma nota

---
id: fisherboy-redis-hostname
type: bug                 # decision|bug|runbook|architecture|constraint|command|mistake
project: fisherboy
evidence:
  - kind: direct_log      # observed → can reach green
    ref: "api log 2026-06-27T14:03Z: connect OK to redis:6379"
check:
  test: "read the worker's effective env; probe connectivity to fisherboy-redis:6379"
  status: not_run         # passed | failed | not_run
last_verified: 2026-06-27
depends_on: [fisherboy-redis-topology]
# ---- computed by COGO · do not edit ----
confidence: yellow
color_reason: "observed evidence but the check has not passed"
---

## Claim
The worker probably fails because it can't resolve Redis's internal hostname.

O vault em Markdown é a única fonte da verdade: portátil, diffável, e sobrevive à ferramenta. Todo o resto é um cliente fino ou um cache reconstruível.

O visualizador web

As abas — a interface está em espanhol, então estes são os nomes que você verá de fato: Vault (suas notas, cada uma com sua cor: busca BM25, filtros, intervalo de datas de criação e paginação), Vigencia (vigência — o que expirou ou está por expirar, com botão de revalidar), Agentes (escreva e versione o AGENTS.md / CLAUDE.md que seus agentes leem ao iniciar), Grafo (como as notas se relacionam e como o vermelho se propaga), Revisión (revisão — links quebrados, notas vencidas, contradições), Guard e Veracidad (veracidade).

Você também pode conectar um repositório do GitHub e navegá-lo pelo visualizador: árvore de arquivos clássica, ou mapa em grafo colorido por confiança mostrando quais partes do código têm conhecimento verificado por trás.

Tudo o que é operacional vive no menu kebab — sem terminal: Conexões MCP (emitir e revogar tokens nomeados por app, com expiração e modo somente leitura), Lixeira, Auditoria MCP (qual token chamou qual ferramenta, quando, de qual IP — baixável e podável), Raízes de evidência, Exportar (backup), Instruções para agentes e Ajustes · Modelo de IA.

Guard, passo a passo

O Guard responde a uma pergunta: “este turno do modelo está me empurrando?”

1. Declare seu mandato (uma vez): seu objetivo e suas linhas vermelhas (“não peço demissão sem outra oferta assinada”). Ele é armazenado no vault. Sem um mandato, manipulação e persuasão legítima são indistinguíveis — o COGO então só nomeia técnicas, sem veredito.
2. Cole o turno (e a conversa anterior, uma mensagem por linha: U: você, M: o modelo) → uma radiografia colorida: verde — sem sinais; amarelo — persuasão presente, ou ela toca a sua linha vermelha; vermelho — há mecânica, ou há recibos.
3. Recibos são o superpoder: como o COGO vê a transcrição, quando o modelo nega o que disse (“eu nunca te disse para pedir demissão”) o COGO encontra o turno em que ele DE FATO disse e mostra as duas citações, lado a lado. O gaslighting deixa de ser a sua palavra contra a dele.
4. Cada tática detectada chega com suas perguntas críticas e sua contramedida — o motor não censura o modelo: ele inocula você. Ele mostra; você decide.

A ontologia por trás: 108 técnicas de manipulação destiladas de seis disciplinas ofensivas — persuasão (Cialdini, Kahneman), interrogatório policial e militar (técnica Reid, Army FM 2-22.3, Scharff), negociação (Harvard, Voss), coerção e reforma do pensamento (Lifton, Biderman), manipulação emocional (gaslighting, DARVO, FOG) e retórica/propaganda (Frankfurt, Grice, Walton) — cada uma com sua fonte real, como ela aparece em um chat, e sua contramedida.

A regra de ferro

Nenhum modelo dita “você está sendo manipulado”. Os dentes são determinísticos (marcadores, recibos, trajetória); os modelos apenas propõem — e cada proposta é verificada contra o texto literal ou descartada. Com um modelo conectado, aparecem dois níveis opcionais: propostas estruturais (padrões que nenhum dicionário vê) e o steelman adversarial — outro modelo argumentando deliberadamente o lado que o turno não te mostrou. O quadro teórico está em docs/fundamento-teorico.md.

Veracidade: sólido, ou fumaça?

O gêmeo do Guard. Onde o Guard pergunta “está me empurrando?”, a aba Veracidade (ferramenta MCP xray) pergunta “esta resposta se sustenta?”. Cole a resposta de um modelo e o COGO a radiografa frase por frase, deterministicamente, sem nenhum modelo: ele mede o compromisso (hesitado ou fortemente afirmado), a evidência (observada, relatada, ou nenhuma) e se é falseável (uma opinião vestida de fato). Uma afirmação forte e sem base sai vermelha; uma sólida com evidência observada, melhor. Documento de design: docs/motor-veracidad.md.

Evidências que são reconferidas

A evidência de uma nota não é uma sensação: é uma referência que o COGO pode ir verificar de novo. Além dos caminhos locais, dois esquemas a tornam durável:

evidence:
  - kind: command_output
    ref: github://acme/api@main/internal/db.go:88   # ancorada ao SHA do blob
  - kind: direct_log
    ref: artifact://9f2a…                           # endereçada por conteúdo, imutável

As referências ao GitHub ficam ancoradas ao SHA do blob. Isso devolve os dentes ao motor de cor numa instância hospedada (que não tem cópia de trabalho do seu código) e habilita a validade ancorada ao git: a nota segue verde enquanto o arquivo citado não mudar, e cai para amarelo assim que mudar. Cite um commit fixo e a evidência fica imutável.

Os artefatos (stash) são guardados sob o SHA-256 do seu conteúdo, em disco ou no Cloudflare R2. Como a chave é o hash, verify o recalcula em vez de confiar numa citação que apodrece. Um scanner de segredos roda antes de guardar qualquer coisa e se recusa por padrão: uma credencial vazada nunca é imortalizada.

Vários agentes, um só vault

Com MCP sobre HTTP e um token, agentes em máquinas diferentes compartilham o mesmo vault:

• recall é o cursor que transforma o vault de arquivo em canal. Chame-o sem argumentos e recebe a memória que sustenta o projeto (o mandato, as decisões verdes) mais um cursor; devolva esse cursor como since e recebe só o que mudou.
• lease toma um direito com prazo sobre um recurso antes de um trabalho arriscado e não idempotente — uma migração, um deploy, uma edição em massa — para que dois agentes não o executem ao mesmo tempo.
• Cada nota registra quem a capturou, e o visualizador filtra por agente.
• O log de auditoria registra qual ferramenta cada token chamou, quando e de qual IP. Pode ser baixado e podado, entrada por entrada ou inteiro.

A CLI

cogo init                 # create a vault
cogo add nota.md          # validate, compute the color, store (stdin if no file)
cogo pack "redis"         # build a colored context for a topic (degrades red)
cogo search "worker"      # list: color · id · summary (no bodies)
cogo stale                # what is expired or about to expire
cogo verify <id>          # "I checked it": revalidate and re-color
cogo lint                 # broken links, expired notes, contradictions (if a model is set)
cogo agents --claude      # generate the CLAUDE.md/AGENTS.md that teaches an agent the protocol
cogo serve -http :8080    # web viewer + MCP server over HTTP
cogo serve                # MCP server over stdio

Acessórios opcionais (desativados por padrão)

O COGO é 100% determinístico e standalone sem nada disto. Cada acessório é habilitado por variável de ambiente e nunca toca o núcleo:

Acessório	Habilitado com	Para
Modelo de IA (OpenRouter, Ollama, DeepSeek…)	COGO_LLM_BASE_URL + COGO_LLM_MODEL (ou Configurações na GUI)	detectar contradições entre notas + os níveis opcionais do Guard
Juiz forte independente	COGO_LLM_STRONG_BASE_URL + COGO_LLM_STRONG_MODEL	para que o steelman do Guard não compartilhe o cérebro com o proponente
Limpeza via Anonimal	ANONIMAL_URL	manter segredos/PII fora do vault
Login Lockatus (OIDC)	AUTH_MODE=federado	federar com a Suíte Escriba

Nota

O detalhe completo vive no repositório: o manual para iniciantes, o guia de deploy completo (cada variável, backup, hardening) e os documentos de design dos motores de veracidade e de autonomia.

Ver no GitHub