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 — the interface is in Spanish, so these are the names you’ll actually see: Vault (your notes, each with its color: BM25 search, filters, creation-date range and pagination), Vigencia (currency — what expired or is about to, with a revalidate button), Agentes (agents — write and version the AGENTS.md / CLAUDE.md your agents read at startup, and paste colored context blocks into them), Grafo (graph — how notes relate, and how red propagates), Revisión (review — broken links, stale notes, contradictions), Guard and Veracidad (veracity).

You can also connect a GitHub repository and browse it from the viewer: a classic file tree, or a graph map colored by confidence that shows which parts of the code have verified knowledge behind them.

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 (which token called which tool, when, from which IP — downloadable and prunable), Evidence roots (which folder each project’s evidence resolves against), Export (backup) (the whole vault as a zip, without secrets), Agent instructions 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.

Evidence that gets re-checked

A note’s evidence isn’t a vibe — it’s a reference COGO can go and verify again. Besides local paths, two schemes make it durable:

evidence:
  - kind: command_output
    ref: github://acme/api@main/internal/db.go:88   # pinned to the blob SHA
  - kind: direct_log
    ref: artifact://9f2a…                           # content-addressed, immutable

GitHub references are anchored to the file’s blob SHA. That gives the color engine its teeth back on a hosted instance (which has no working copy of your code), and it enables git-anchored freshness: the note stays green while the cited file doesn’t change, and drops to yellow the moment it does. Cite a fixed commit and the evidence is immutable.

Artifacts (stash) are stored under the SHA-256 of their content, locally or on Cloudflare R2. Because the key is the hash, verify recomputes it instead of trusting a citation that rots. A secret scanner runs before anything is stored and refuses by default, so a leaked credential never gets immortalized.

Several agents, one vault

Over MCP on HTTP with a token, agents on different machines share a single vault:

• recall is the cursor that turns the vault from an archive into a channel. Call it with no argument and you get the load-bearing memory (the mandate, the green decisions) plus a cursor; hand that cursor back as since and you get only what changed.
• lease takes a time-bounded claim on a resource before a risky, non-idempotent job — a migration, a deploy, a bulk edit — so two agents don’t run it at the same time.
• Every note records who captured it, and the viewer can filter by agent.
• The audit log records which tool each token called, when, and from which IP. It can be downloaded and pruned, entry by entry or all at once.

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