{"id":"4c3f20c3-13d0-44f2-941a-b1bce509c522","slug":"cogc","kind":"skill","name":"CogC","summary":"Experimental capacity-aware cognitive compression for AI agents — compile large context, evidence, constraints, and procedures into small-model-ready packages with provenance and fidelity checks.","owner":"tonnestate","repoUrl":"https://github.com/tonnestate/CogC","license":"Apache-2.0","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-09-19T07:59:33.000Z","addedAt":"2026-10-21T11:37:06.465Z","logoUrl":"https://avatars.githubusercontent.com/u/317501328?u=a5e42a6bb9b47e8f338a267a7ed98f4c82e18cb8&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge"],"tags":["ai-agents","cognitive-compression","context-compression","context-engineering","agent-handoffs","agent-memory","context-management","fidelity"],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T11:47:27.461Z","sample":false,"url":"https://conduits.dev/tools/cogc","language":"Python","transports":["stdio"],"install":{"pypi":"cogc-skill"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# CogC\n\n> [!WARNING]\n> **EXPERIMENTAL — v0.2.1**  \n> CogC is a research-oriented Agent Skill and reference implementation. The deterministic compiler, provenance tracking, reversible source handles, schemas, and fidelity checks are tested, but **downstream intelligence gains are not yet claimed**. Use it behind evaluation gates until your own raw-vs-summary-vs-CogC tests show a measurable benefit.\n\n**Capacity-Aware Cognitive Compression for constrained AI agents.**\n\nCogC compiles large, heterogeneous agent context into the **minimum sufficient, provenance-preserving working state for a specific target model**.\n\nIt is built for a practical problem that appears as agent systems become larger while their individual workers remain constrained: the system may know far more than the worker can reliably use.\n\nA smaller model often does not need *more* context. It needs the **right context, in the right structure, with the right constraints preserved**.\n\nCogC is both:\n\n1. a **visible canonical Agent Skill** under `skill/cogc`;\n2. a GitHub-discovered mirror under `.github/skills/cogc`; and\n3. a dependency-free Python reference engine under `src/cogc`.\n\n## Why CogC exists\n\nModern agent systems accumulate context from conversations, RAG, tools, logs, repositories, memory, previous runs, policies, evidence, and agent-to-agent handoffs. Passing all of that material directly to every worker creates several problems:\n\n- **Context overload:** relevant facts compete with noise, repetition, obsolete state, and verbose history.\n- **Small-model mismatch:** 4B–9B workers may have enough capability for a bounded task but fail when forced to reconstruct the task from a large raw context.\n- **Expensive handoffs:** agents repeatedly transmit long histories even when the next worker needs only a few facts, constraints, and a known procedure.\n- **Lossy summarization:** ordinary summaries can remove exact values, identifiers, stop conditions, evidence links, or other information that must survive unchanged.\n- **Weak auditability:** after a summary, it can be difficult to determine which source supported a compressed claim.\n- **Repeated rediscovery:** a worker may be given an entire historical trajectory even when a verified reusable procedure already captures what matters.\n- **Unnecessary escalation:** systems may call larger or more expensive models simply because the context was poorly prepared for the cheaper worker.\n\nCogC was created to test a different approach:\n\n> **Do not ask a constrained model to understand everything the system knows. Compile what it needs to make the next correct decision.**\n\nThe goal is not to make a small model pretend to be a frontier model. The goal is to remove avoidable cognitive load so that each worker operates closer to its actual capability.\n\n## What CogC brings\n\nCogC turns this:\n\n```text\nraw conversation\n+ RAG chunks\n+ tool output\n+ logs\n+ memory\n+ evidence\n+ constraints\n+ prior trajectories\n                 │\n                 ▼\n          one huge prompt\n```\n\ninto this:\n\n```text\nTask + evidence + constraints + memory + procedures + target profile\n                              │\n                              ▼\n                             CogC\n                              │\n        ┌─────────────────────┼─────────────────────┐\n        │                     │                     │\n        ▼                     ▼                     ▼\n criticality            relevance +           procedural\n protection             deduplication          compilation\n        │                     │                     │\n        └─────────────────────┼─────────────────────┘\n                              ▼\n                 provenance + fidelity gate\n                              │\n                              ▼\n        minimum sufficient cognitive package\n                              │\n                              ▼\n                       target worker\n```\n\nThe v0.2.1 compiler provides:\n\n- **Capacity-aware output:** compile for the intended worker rather than producing one universal summary.\n- **C0–C5 criticality classes:** protect hard constraints and high-value information from aggressive reduction.\n- **Exact-value protection:** preserve critical numbers, IDs, and machine-like identifiers.\n- **Deterministic deduplication:** remove repeated source content before using lossy methods.\n- **Task-focused selection:** prioritize information that is relevant to the current goal and next action.\n- **Procedural compression:** prefer a verified workflow/subtask/function procedure over replaying entire historical trajectories.\n- **Provenance:** retain source lineage for compiled facts.\n- **Reversible source handles:** omit non-critical detail from working context without making the original source unreachable.\n- **Cognitive Packets:** produce compact state suitable for agent handoffs.\n- **Fidelity Gate:** verify protected information before a compressed package is used.\n- **Compression receipts:** record what happened, which policy was used, and what was retained.\n- **A/B/C evaluation support:** compare raw context, ordinary summary, and CogC instead of assuming compression is beneficial.\n\n## Why use CogC\n\nCogC is useful when **the bottleneck is not retrieval but usable cognitive bandwidth**.\n\nTypical cases include:\n\n### Small local models\n\nA 4B or 9B worker may be perfectly capable of executing a narrow procedure while being unreliable when given 20,000 tokens of mixed history. CogC can transform that history into an explicit goal, current state, constraints, relevant facts, procedure, source handles, and stop conditions.\n\n### Tool-heavy agents\n\nLogs, repository scans, search results, API responses, test output, and large JSON objects can dominate context. CogC reduces repeated and irrelevant material while preserving critical exact values and source references.\n\n### Multi-agent handoffs\n\nThe next agent rarely needs the complete conversation of the previous agent. CogC can emit a compact Cognitive Packet with claims, evidence references, unresolved conflicts, procedures, and the next required action.\n\n### Reusing expensive reasoning\n\nIf a difficult task has already been solved and verified, future workers should not have to rediscover the method from raw history. CogC can represent reusable experience as workflow, subtask, or function-level procedural memory.\n\n### Reducing unnecessary use of larger models\n\nA stronger model may be needed because the problem is genuinely difficult — or because a weaker model received a poor representation of the problem. CogC is designed to help distinguish those cases experimentally.\n\n### Evidence-sensitive automation\n\nWhen constraints, IDs, numerical values, evidence references, and stop conditions cannot be silently lost, a generic summary is insufficient. CogC treats protected information and provenance as part of the compilation contract.\n\n## What CogC does **not** claim\n\nCogC v0.2.1 does **not** claim that:\n\n- compression always improves model quality;\n- fewer tokens automatically mean better reasoning;\n- a 4B model becomes equivalent to a frontier model;\n- its current deterministic policies are optimal;\n- published compression or memory research proves this combined architecture.\n\nThose are empirical questions.\n\nCogC is deliberately built so they can be tested.\n\n## What CogC is not\n\nCogC is not:\n\n- a replacement for RAG or retrieval;\n- a persistent-memory database;\n- a model router;\n- an authorization or governance layer;\n- an agent framework;\n- a generic summarizer;\n- a private chain-of-thought extractor;\n- a reason to compress context that is already small and appropriate.\n\nIt is a **capacity-aware compiler between assembled system state and the worker that must act on it**.\n\n## The core idea\n\nA conventional summarizer asks:\n\n> How can I make this text shorter?\n\nCogC asks:\n\n> What is the minimum faithful cognitive state this specific worker needs to make the correct next decision?\n\nFor a constrained worker, the desired result is closer to:\n\n```text\nGOAL\nVerify capability X.\n\nCURRENT STATE\nSource inspection completed; runtime behavior unverified.\n\nHARD CONSTRAINTS\nDo not modify production.\nDo not accept README claims as runtime proof.\n\nRELEVANT FACTS\nImplementation entry point: module Y.\nExpected behavior: Z.\n\nPROCEDURE\nWF-VERIFY-03\n\nEVIDENCE\nEV-17, EV-22\n\nNEXT ACTION\nRun isolated runtime test.\n\nSUCCESS\nObserved behavior matches claim X.\n\nSTOP / ESCALATE\nConflicting runtime evidence or unavailable test environment.\n\nEXPANDABLE\nEV-17, EV-22, SRC-41\n```\n\nrather than another prose summary.\n\n## Install\n\nPython 3.10+:\n\n```bash\npip install -e .\n```\n\nDevelopment:\n\n```bash\npip install -e \".[dev]\"\npytest\n```\n\nThe canonical, visible skill source lives at:\n\n```text\nskill/cogc/SKILL.md\n```\n\nGitHub discovers the verified mirror at:\n\n```text\n.github/skills/cogc/SKILL.md\n```\n\nThe Python package is independent under `src/cogc`. `tools/sync_skill.py --check` verifies that the portable skill and GitHub mirror contain the same generated engine and content. The skill can be copied into other project-level Agent Skills locations with `tools/install_skill.py`. See `docs/installation.md`.\n\n## First compile\n\n```bash\ncogc compile \\\n  --input examples/repository-analysis.json \\\n  --profile qwen-4b \\\n  --format text \\\n  --receipt\n```\n\nOr without package installation:\n\n```bash\npython skill/cogc/scripts/compile_context.py \\\n  --input examples/repository-analysis.json \\\n  --profile qwen-4b \\\n  --format text \\\n  --receipt\n```\n\nValidate protected information:\n\n```bash\ncogc validate --input examples/repository-analysis.json --profile qwen-4b\n```\n\n## Core invariants\n\nCogC v0.2.1 enforces these design rules:\n\n- C0/C1 information is never dropped merely to satisfy a token budget.\n- Exact critical numbers and machine-like identifiers must survive.\n- Omitted non-critical source material remains addressable by source handle.\n- Exact duplicate source content is stored once while provenance is merged.\n- Compression starts with deterministic/lossless transformations.\n- The output includes a compression receipt and fidelity result.\n- If critical material alone exceeds the budget, CogC reports this rather than silently truncating it.\n\n## Input example\n\n```json\n{\n  \"goal\": \"Verify whether a repository already provides capability X.\",\n  \"task\": \"Inspect source and obtain runtime evidence.\",\n  \"token_budget\": 1200,\n  \"sources\": [\n    {\n      \"id\": \"POLICY-1\",\n      \"kind\": \"constraint\",\n      \"criticality\": \"C0\",\n      \"text\": \"Do not write to production without explicit approval.\"\n    },\n    {\n      \"id\": \"EVID-1\",\n      \"kind\": \"evidence\",\n      \"criticality\": \"C1\",\n      \"text\": \"README claims FEATURE-X; runtime proof is still missing.\"\n    }\n  ]\n}\n```\n\nSee `examples/` and `skill/cogc/schemas/compile-request.schema.json` for the full contract.\n\n## Repository layout\n\n```text\n.\n├── src/cogc/                  # installable Python engine (canonical engine source)\n├── skill/cogc/                # visible canonical Agent Skill\n│   ├── SKILL.md\n│   ├── references/\n│   ├── schemas/\n│   └── scripts/\n│       └── cogc/              # generated portable engine copy\n├── .github/\n│   ├── skills/cogc/           # generated/verified GitHub Agent Skill mirror\n│   └── workflows/\n│       ├── ci.yml\n│       └── release.yml\n├── docs/\n├── evals/\n├── examples/\n├── tests/\n├── tools/\n│   ├── install_skill.py\n│   └── sync_skill.py\n├── pyproject.toml\n└── README.md\n```\n\n## Scientific and engineering basis\n\nCogC is intentionally reuse-first. Its design is informed by:\n\n- Microsoft LLMLingua / LLMLingua-2 and LongLLMLingua for context compression;\n- Microsoft ACON for learning from compressed-context failures and compressor distillation;\n- Agent Workflow Memory for reusable procedural knowledge;\n- Agent Memory Distillation for hierarchical workflow/subtask/function transfer to small agents;\n- Letta and Mem0 as references for persistent memory/context-management boundaries.\n\nSee `skill/cogc/references/research-foundations.md` for links and the precise boundary.\n\nThe repository does **not** claim these papers prove CogC as a combined architecture. CogC must beat its baselines empirically.\n\n## Evaluation contract\n\nDo not evaluate CogC by compression ratio alone.\n\nThe required downstream comparison is:\n\n| Arm | Context |\n|---|---|\n| A | raw/full context |\n| B | ordinary summary/current context handling |\n| C | CogC |\n\nUse the same target model, tasks, and acceptance tests. Measure verified task success, critical-field retention, retries, latency, tokens, model escalations, and total cost.\n\nRun the offline deterministic smoke eval:\n\n```bash\npython evals/run_offline_eval.py\n```\n\nThe offline eval validates fidelity and compression mechanics only. It does not masquerade as a model-quality benchmark.\n\n## Current status\n\n**v0.2.1 — EXPERIMENTAL**\n\nThe deterministic mechanics are implemented and tested. Promotion requires downstream evidence that CogC provides one of the following without reducing required quality:\n\n- lower context cost;\n- lower latency;\n- fewer retries;\n- fewer unnecessary escalations;\n- higher verified success for constrained workers;\n- or materially better verified output at comparable total cost.\n\nUntil such evidence exists for a given environment, CogC should be treated as an experimental optimization layer with raw-context fallback.\n\n## Roadmap\n\n### v0.1.0 — deterministic compiler\n\n- CIR\n- criticality protection\n- provenance\n- reversible source handles\n- exact deduplication\n- extractive reduction\n- capacity profiles\n- procedure injection\n- Fidelity Gate\n- A/B/C evaluation harness\n\n### v0.2.0 — packaging and integrity\n\n- standard `src/cogc` package layout;\n- visible canonical `skill/cogc` bundle;\n- verified `.github/skills/cogc` mirror;\n- self-contained portable skill;\n- mirror/engine drift detection in CI;\n- standalone and installer tests.\n\n### v0.2.1 — skill progressive disclosure\n\n- compact execution-oriented `SKILL.md`;\n- trigger-focused frontmatter description;\n- detailed architecture and research moved behind `references/`;\n- public skill instructions made project-neutral;\n- regression tests for skill size, local references, and metadata behavior.\n\n### v0.2.x — optional compression backends\n\nCandidates, only after evaluation:\n\n- LLMLingua-2 adapter;\n- structured tool-output compressor;\n- context-policy plugins;\n- stronger decision-equivalence tests.\n\n### v0.3.x — learning\n\nOnly with real labeled outcomes:\n\n- ACON-style compression-failure learning;\n- target-model-specific compression policy;\n- contextual-bandit policy selection;\n- teacher-to-small-worker procedural distillation.\n\n## GitHub repository metadata\n\n**Description**\n\n> Experimental capacity-aware cognitive compression for AI agents — compile large context, evidence, constraints, and procedures into small-model-ready packages with provenance and fidelity checks.\n\n**Topics / keywords**\n\n```text\nagent-skills\nai-agents\ncognitive-compression\ncontext-compression\ncontext-engineering\ncontext-management\nsmall-language-models\nslm\nllm-agents\nlocal-llm\nprompt-compression\nagent-memory\nprocedural-memory\nagent-handoffs\nprovenance\nfidelity\nmulti-agent-systems\nqwen\nllmlingua\n```\n\n## License\n\nApache-2.0. See `LICENSE`.\n\n---\n\n## AI Transparency\n\nThis repository contains material created with or materially assisted by generative AI systems. This may include source code, documentation, examples, tests, specifications, project artwork, and other visual assets.\n\nAI-generated or AI-assisted material should not be treated as independently verified solely because it appears in this repository. Visual assets may include AI-generated imagery used for illustrative or branding purposes unless explicitly stated otherwise.\n\nThis repository-level disclosure is provided for transparency, including with regard to applicable transparency requirements under the EU AI Act. It does not imply that every file or contribution was generated by AI, nor that every item is subject to a specific statutory labeling obligation.\n\n---\n\n## Output economy — shared agent skill\n\nThe shared `skill/output-economy/SKILL.md` is a separate, provider-neutral\n**pre-generation output policy**. It suppresses repeated apologies, filler and\nunnecessary restatements while explicitly preserving evidence, blockers, exact\nidentifiers and uncertainty. It does not perform a second model call or rewrite\na completed response. It does not prove semantic equivalence.\n\nConsumers load the policy from this canonical skill file rather than copying\nits wording into each role. For example, PlumMe can add the CogC `skill/`\nfolder to its skill roots and require `output-economy` globally. Other agent\nhosts must explicitly install and activate the skill through their own supported\nmechanisms. This policy is separate from CogC's context-compilation pipeline.\n\nThe source criticality deduplication invariant is: **identical source text must\ninherit the strongest criticality of all its origins**, never the first source's\nclassification alone. The original source identifiers remain attached.\n"}