COGO documentation

COGO is three faces over one logic: a web viewer for everyone, an MCP server for your agents, and a CLI for power users — all the same single Go binary.

Face	For whom	How
Web viewer	everyone	cogo serve -http :8080 → browser (Vault · Freshness · Pack · Graph · Review · Guard · Veracity)
MCP	your agent (Claude, Codex, Cursor, Gemini…)	cogo serve (stdio) or /mcp over HTTP — tools: pack search open capture verify archive restore remove guard xray
CLI	power users	cogo add · pack · search · stale · verify · lint · agents

How the color is computed

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

A note is green only when nothing pushes it down: observed evidence, a check that passed, fresh, all its dependencies green and no contradictions. Every color carries its color_reason, so you can always audit why it ended up the way it did.

• Evidence sets the ceiling: observed (a log, a command, a test, a file) can reach green; reported or inferred caps at yellow; no evidence means red.
• Freshness decays by type: a command lasts 30 days; an architecture decision, 180.
• Editing a note changes the color — that’s the point. The viewer recomputes the color live while you type: add observed evidence and it gets greener; change the claim and it resets to “needs re-verification”; press verify (“I checked it”) and it goes green.

Anatomy of a note

---
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.

The Markdown vault is the single source of truth: portable, diffable, and it survives the tool. Everything else is a thin client or a rebuildable cache.

The web viewer

The tabs: Vault (your notes, each with its color), Freshness (what is expiring, with a revalidate button), Pack (assemble a topic’s notes into a colored context block to paste to an AI), Graph (how notes relate), Review (broken links, expired notes, contradictions), Guard and Veracity.

Everything operational lives in the viewer’s kebab menu — no terminal needed: MCP connections (issue/revoke named tokens per app, with expiry and a read-only mode), Trash (restore or delete forever), MCP audit (who called which tool, when, from which IP), Evidence roots (which folder each project’s evidence resolves against), Export (backup) (the whole vault as a zip, without secrets), Agent instructions (generate the AGENTS.md/CLAUDE.md that teaches your agent the protocol) and Settings · AI model.

Guard, step by step

Guard answers one question: “is this model turn pushing me?”

1. Declare your mandate (once): your goal and your red lines (“I don’t resign without another signed offer”). It is stored in the vault. Without a mandate, manipulation and legitimate persuasion are indistinguishable — COGO then only names techniques, with no verdict.
2. Paste the turn (and the prior conversation, one message per line: U: you, M: the model) → a colored radiography: green — no signals; yellow — persuasion present, or it touches your red line; red — there is mechanics, or there are receipts.
3. Receipts are the superpower: since COGO sees the transcript, when the model denies what it said (“I never told you to resign”) COGO finds the turn where it DID say it and shows both quotes, side by side. Gaslighting stops being your word against its.
4. Every detected tactic arrives with its critical questions and its countermeasure — the engine does not censor the model: it inoculates you. It shows; you decide.

The ontology behind it: 108 manipulation techniques distilled from six offensive disciplines — persuasion (Cialdini, Kahneman), police and military interrogation (Reid technique, Army FM 2-22.3, Scharff), negotiation (Harvard, Voss), coercion and thought reform (Lifton, Biderman), emotional manipulation (gaslighting, DARVO, FOG) and rhetoric/propaganda (Frankfurt, Grice, Walton) — each with its real source, how it looks in a chat, and its countermeasure.

The iron rule

No model dictates “you are being manipulated”. The teeth are deterministic (markers, receipts, trajectory); models only propose — and every proposal is verified against the literal text or discarded. With a model connected, two optional tiers appear: structural proposals (patterns no dictionary sees) and the adversarial steelman — another model deliberately arguing the side the turn didn’t show you. The theoretical frame is in docs/fundamento-teorico.md.

Veracity: solid, or smoke?

Guard’s twin. Where Guard asks “is it pushing me?”, the Veracity tab (MCP tool xray) asks “does this answer hold up?”. Paste a model’s answer and COGO x-rays it sentence by sentence, deterministically, without any model: it measures commitment (hedged or strongly asserted), evidence (observed, reported, or none) and whether it is falsifiable (an opinion dressed as a fact). A strong, ungrounded claim comes out red; a solid one with observed evidence, better. Design doc: docs/motor-veracidad.md.

The 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

Optional accessories (off by default)

COGO is 100% deterministic and standalone without any of this. Each accessory is enabled by environment variable and never touches the core:

Accessory	Enabled with	For
AI model (OpenRouter, Ollama, DeepSeek…)	COGO_LLM_BASE_URL + COGO_LLM_MODEL (or Settings in the GUI)	detecting contradictions between notes + Guard’s optional tiers
Independent strong judge	COGO_LLM_STRONG_BASE_URL + COGO_LLM_STRONG_MODEL	so Guard’s steelman doesn’t share a brain with the proposer
Anonimal scrub	ANONIMAL_URL	keeping secrets/PII out of the vault
Lockatus login (OIDC)	AUTH_MODE=federado	federating with the Escriba Suite

Note

The full detail lives in the repo: the beginner’s manual, the complete deploy guide (every variable, backup, hardening) and the design docs for the veracity and autonomy engines.

View on GitHub