Metadata-Version: 2.4
Name: codec-cortex
Version: 0.6.2
Summary: CODEC-CORTEX — Universal Communication Protocol for LLM/SLM Agents. Compresses agent knowledge via deterministic sigil codec with semantic learning engine (SES→LNG→KNW).
Author-email: "Fidel Ernesto Lozada A." <fidelernesto@gmail.com>
License: MPL-2.0
Project-URL: Homepage, https://github.com/FidelErnesto03/codec-cortex
Project-URL: Documentation, https://github.com/FidelErnesto03/codec-cortex/blob/main/docs/README.md
Project-URL: Repository, https://github.com/FidelErnesto03/codec-cortex
Project-URL: Issues, https://github.com/FidelErnesto03/codec-cortex/issues
Keywords: cortex,codec,llm,agent,memory,compression,cognitive,protocol,deterministic,slm,context,cag,rag,puml,hcortex
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Processing
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Dynamic: license-file

<!-- SPDX-FileCopyrightText: 2026 Fidel Ernesto Lozada A. -->
<!-- SPDX-License-Identifier: MPL-2.0 -->

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="">
    <img alt="CODEC-CORTEX" src="" width="180">
  </picture>
  <br>
  <strong>CODEC-CORTEX</strong>
  <br>
  <em>Universal Communication Protocol for LLM/SLM Agents</em>
  <br>
  <sub>v0.6.0 · MPL-2.0 · <a href="#license">License</a> · <a href="docs/reference/SKILL.md">Specification</a></sub>
</p>

<p align="center">
  <a href="#-overview">Overview</a> •
  <a href="#-how-it-works">How It Works</a> •
  <a href="#-roadmap">Roadmap</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-documentation">Documentation</a> •
  <a href="#-project-structure">Project Structure</a> •
  <a href="#-español">🇪🇸 Español</a>
</p>

---

## 📋 Overview

**CODEC-CORTEX is a compression protocol for agent knowledge.**

Just as H.264 compresses video frames into a bitstream for efficient transmission, CODEC-CORTEX compresses agent state — context, lessons, objectives, working memory — into a dense sigil format that LLMs and SLMs can transmit, store, and reconstruct with minimal token overhead.

| Metric | Prose (plain text) | CODEC-CORTEX | Compression |
|---|---|---|---|
| Session state | ~250 tokens | ~28 tokens | **~8×** |
| Lesson (LNG) | ~80 tokens | ~12 tokens | **~6×** |
| Knowledge (KNW) | ~120 tokens | ~20 tokens | **~6×** |
| Full project brain | ~3,500 tokens | ~450 tokens | **~7×** |

But the real compression is **semantic**. The [learning engine](docs/reference/learning-engine-spec.md) automatically distills multiple specific lessons (LNG) into general knowledge (KNW) — a **second-order compression** that compounds across sessions.

```
           SES (Sessions)                          ~250 tokens
              ↓ cortex.learn
           LNG (Lessons)     ~8:1 compression      ~30 tokens
              ↓ elevate
           KNW (Knowledge)   ~5:1 compression       ~6 tokens
                                         ─────────────
                          Total:          ~40:1 semantic compression
```

---

## 🏗️ How It Works

CODEC-CORTEX operates on three independent layers:

```
┌─────────────────────────────────────────────────────────────┐
│                    CODEC-CORTEX PROTOCOL                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Layer 3: Knowledge (Semantic Compression)                  │
│  ────────────────────────────────────────────               │
│  Engine: cortex.learn / elevate                             │
│  Transforms: many LNG → one KNW                             │
│  Purpose: compound learning across sessions                 │
│                                                             │
│  Layer 2: Transport (MCP / File / ACP)                      │
│  ────────────────────────────────────────────               │
│  MCP: real-time encoding/decoding for agents                │
│  File: .cortex persistence on disk                          │
│  ACP: cross-agent delegation                                │
│                                                             │
│  Layer 1: Representation (Sigil Syntax)                     │
│  ────────────────────────────────────────────               │
│  Sigils: FCS, OBJ, WRK, LNG, KNW, SES...                   │
│  Types: attrs, cuerpo, attrs-pos                            │
│  Sections: $0 through $N                                    │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

### Layer 1 — Representation

The core sigil format. Every agent state — focus, objectives, working memory, lessons, knowledge — is expressed as dense, structured entries. This is the **compressed bitstream** of the protocol.

```cortex
$2: FOCUS

FCS:current{what:"Implement auto-numbering", priority:"medium", status:"current", survive:"work"}

$7: LESSONS

LNG:handler_id{type:"process", cause:"BLP-003 execution", lesson:"Always verify file in disk after create"}
```

### Layer 2 — Transport

How the compressed state moves between agents, systems, and humans:

| Transport | Protocol | Purpose | Status |
|---|---|---|---|
| File | `.cortex` on disk | Persistence, history | ✅ Active |
| **MCP** | Model Context Protocol | Real-time agent encoding/decoding | 🚧 In design |
| ACP | Agent Communication Protocol | Cross-agent task delegation | 📋 Future |
| LSP | Language Server Protocol | Human editor support | 📋 Future |

### Layer 3 — Knowledge (Semantic Compression)

The engine that makes CODEC-CORTEX more than a format. `cortex.learn` scans accumulated lessons, identifies patterns, and **elevates** them into general knowledge. This is where the protocol achieves true compression — not of syntax, but of **meaning**.

---

## 🛣️ Roadmap

```
Phase 1: File CODEC — ✅ Active
┌─────────────────────────────────────────────────────────────┐
│ • Parser (core + v2)    • Validator (E023-E034)             │
│ • HCORTEX renderer      • Learning engine (LNG → KNW)      │
│ • CLI (17 commands)     • 695+ tests                       │
│ • Auto-numbering        • .cortex persistence              │
└─────────────────────────────────────────────────────────────┘

Phase 2: Stream CODEC — 🚧 Next
┌─────────────────────────────────────────────────────────────┐
│ cortex.encode(state) → sigils     MCP Server exposure       │
│ cortex.decode(sigils) → state     Real-time agent transport │
│ cortex.learn as MCP tool          Cross-session learning    │
└─────────────────────────────────────────────────────────────┘

Phase 3: Database CODEC — 🔮 Vision
┌─────────────────────────────────────────────────────────────┐
│ Sigil queries (GET KNW:*)         Streaming between agents  │
│ Semantic indexes                  Transactional writes      │
│ Replicated state                  Multi-agent ecosystem     │
└─────────────────────────────────────────────────────────────┘
```

See the full [Roadmap Document](docs/reference/cortex-codec-roadmap.md) for detailed phase breakdown and cycles.

---

## 🚀 Quick Start

### Installation

```bash
pip install codec-cortex
cortex --version
```

Requires Python ≥ 3.9.

### Initialize agent memory

```bash
# Create your agent's brain
cp docs/reference/SKILL.cortex brain.cortex

# Verify it
cortex verify brain.cortex

# Write your focus
cortex edit brain.cortex --section 2 --set "what:My current objective"

# Render as human-readable
cortex render brain.cortex --mode readable
```

### Load as universal skill

For agents that support skill loading:

```cortex
// Load CODEC-CORTEX as your memory protocol
// See skill/cortex/AGENT.md for identity template
// See skill/hcortex/SKILL_HCORTEX.md for full specification
```

See [Quick Start Guide](docs/README.md) for detailed walkthrough.

---

## 📚 Documentation

The project documentation is organized under `docs/`:

| Directory | Content |
|---|---|
| [`docs/reference/`](docs/reference/) | Stable reference: SKILL specification, roadmap, learning engine |
| [`docs/releases/`](docs/releases/) | Delivery reports per version (v0.3.0 → v2.4.0) |
| [`docs/verification/`](docs/verification/) | Audit and verification reports |
| [`docs/benchmarks/`](docs/benchmarks/) | Performance benchmarks and analysis |
| [`docs/proposals/](docs/proposals/) | Strategic proposals and business plans |
| [`docs/archive/`](docs/archive/) | Historical or orphan documents |

Key documents:

| Document | Description |
|---|---|
| [`docs/reference/SKILL.md`](docs/reference/SKILL.md) | Full CORTEX specification |
| [`docs/reference/cortex-codec-roadmap.md`](docs/reference/cortex-codec-roadmap.md) | Protocol vision and phase roadmap |
| [`docs/reference/learning-engine-spec.md`](docs/reference/learning-engine-spec.md) | Learning engine specification |
| [`skill/cortex/SKILL.md`](skill/cortex/SKILL.md) | Dense CORTEX skill file |
| [`skill/hcortex/SKILL_HCORTEX.md`](skill/hcortex/SKILL_HCORTEX.md) | Human-readable HCORTEX skill spec |

---

## 🧩 Project Structure

```
codec-cortex/
├── cli/                  ← CLI and Python package (parser, validator, renderer)
│   └── src/cortex/       ← Core: parser, hcortex, v2, glossary, crud
├── docs/                 ← All documentation (reference, releases, benchmarks, etc.)
│   ├── reference/        ← Stable reference documents
│   ├── releases/         ← Delivery reports
│   ├── verification/     ← Audit reports
│   ├── benchmarks/       ← Performance benchmarks
│   └── proposals/        ← Strategic vision
├── skill/                ← CORTEX and HCORTEX skill specifications
│   ├── cortex/           ← Dense CORTEX format
│   └── hcortex/          ← Human-readable HCORTEX format
└── benchmarks/           ← Benchmark scripts
```

---

## 📊 Enterprise Readiness

| Capability | Status | Details |
|---|---|---|
| Deterministic parser | ✅ | Zero LLM calls for parse/encode/decode/verify |
| Full validation suite | ✅ | 695+ tests, strict mode |
| CLI with 28+ commands | ✅ | verify, render, convert, CRUD, doctor, diff, format, diagram, session, learn |
| Learning engine | ✅ | SES → LNG → KNW elevation pipeline |
| Runtime sessions | ✅ | Session lifecycle (start → event → consolidate → close) |
| Global CLI flags | ✅ | `--output json`, `--json`, `--mode`, `--yes`, `--version` |
| MCP server | 🚧 | Phase 2: Stream CODEC |
| ACP integration | 📋 | Phase 2/3 |
| LSP language server | 📋 | Phase 3 |

---

## 📄 License

Starting with CODEC-CORTEX v0.4.0, the project core is licensed under the **Mozilla Public License 2.0 (MPL-2.0)**.

Previous releases published under the MIT License remain available under their original MIT terms. The license change applies prospectively to v0.4.0 and later releases.

The CODEC-CORTEX name, logo, visual identity and related marks are not licensed under MPL-2.0 and are governed by the project trademark policy.

---

<p align="center">
  <sub>
    Designed by <a href="https://github.com/FidelErnesto03">Fidel Ernesto Lozada A.</a>
    ·
    Systems Engineer / MSc. Management Sciences
    ·
    <a href="LICENSE">MPL-2.0</a>
  </sub>
</p>

---

## 🇪🇸 Español

<p align="center">
  <sub>Versión en español — <a href="#-overview">English version above</a></sub>
</p>

---

### 📋 Resumen

**CODEC-CORTEX es un protocolo de compresión para el conocimiento de agentes de IA.**

Así como H.264 comprime frames de video en un flujo de bits para transmisión eficiente, CODEC-CORTEX comprime el estado de un agente — contexto, lecciones, objetivos, memoria de trabajo — en un formato denso de sigilos que los LLMs y SLMs pueden transmitir, almacenar y reconstruir con gasto mínimo de tokens.

| Métrica | Texto plano | CODEC-CORTEX | Compresión |
|---|---|---|---|
| Estado de sesión | ~250 tokens | ~28 tokens | **~8×** |
| Lección (LNG) | ~80 tokens | ~12 tokens | **~6×** |
| Conocimiento (KNW) | ~120 tokens | ~20 tokens | **~6×** |
| Cerebro completo | ~3,500 tokens | ~450 tokens | **~7×** |

La compresión real es **semántica**. El [motor de aprendizaje](docs/reference/learning-engine-spec.md) destila múltiples lecciones específicas (LNG) en conocimiento general (KNW) — una **compresión de segundo orden** que se acumula entre sesiones.

```
           SES (Sesiones)                        ~250 tokens
              ↓ cortex.learn
           LNG (Lecciones)    ~8:1 compresión     ~30 tokens
              ↓ elevate
           KNW (Conocimiento) ~5:1 compresión      ~6 tokens
                                         ─────────────
                          Total:     ~40:1 compresión semántica
```

---

### 🏗️ Cómo Funciona

CODEC-CORTEX opera en tres capas independientes:

```
┌─────────────────────────────────────────────────────────────┐
│                    PROTOCOLO CODEC-CORTEX                    │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Capa 3: Conocimiento (Compresión Semántica)                │
│  ────────────────────────────────────────────               │
│  Motor: cortex.learn / elevate                              │
│  Transforma: muchas LNG → una KNW                           │
│  Propósito: aprendizaje compuesto entre sesiones            │
│                                                             │
│  Capa 2: Transporte (MCP / Archivo / ACP)                   │
│  ────────────────────────────────────────────               │
│  MCP: codificación/decodificación en tiempo real            │
│  Archivo: persistencia .cortex en disco                     │
│  ACP: delegación entre agentes                              │
│                                                             │
│  Capa 1: Representación (Sintaxis de Sigilos)               │
│  ────────────────────────────────────────────               │
│  Sigilos: FCS, OBJ, WRK, LNG, KNW, SES...                  │
│  Tipos: attrs, cuerpo, attrs-pos                            │
│  Secciones: $0 a $N                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

### 🚀 Inicio Rápido

```bash
pip install codec-cortex
cortex --version
```

Requiere Python ≥ 3.9.

```bash
# Crear el cerebro de tu agente
cp docs/reference/SKILL.cortex brain.cortex

# Verificarlo
cortex verify brain.cortex

# Escribir tu enfoque
cortex edit brain.cortex --section 2 --set "what:Mi objetivo actual"

# Renderizar como legible
cortex render brain.cortex --mode readable
```

---

#### Comandos del CLI

| Comando | Descripción |
|---|---|
| `cortex session start` | Iniciar sesión de trabajo |
| `cortex session status` | Estado de sesión activa |
| `cortex learn scan` | Escanear cerebro en busca de candidatos |
| `cortex learn elevate` | Elevar lecciones a conocimiento |
| `cortex render` | Renderizar .cortex a HCORTEX legible |
| `cortex verify` | Validar archivo .cortex |
| `cortex doctor` | Diagnosticar integridad del workspace |
| `cortex --output json <comando>` | Salida JSON para integración |

---

### 📚 Documentación en Español

| Documento | Descripción |
|---|---|
| [`docs/reference/SKILL.md`](docs/reference/SKILL.md) | Especificación completa del protocolo CORTEX |
| [`docs/reference/cortex-codec-roadmap.md`](docs/reference/cortex-codec-roadmap.md) | Visión del protocolo y hoja de ruta |
| [`docs/reference/learning-engine-spec.md`](docs/reference/learning-engine-spec.md) | Especificación del motor de aprendizaje |

---

### 📄 Licencia

A partir de CODEC-CORTEX v0.4.0, el núcleo del proyecto se publica bajo la **Mozilla Public License 2.0 (MPL-2.0)**.

Las versiones anteriores publicadas bajo licencia MIT permanecen disponibles bajo sus términos originales.

---

<p align="center">
  <sub>
    Diseñado por <a href="https://github.com/FidelErnesto03">Fidel Ernesto Lozada A.</a>
    ·
    Ingeniero de Sistemas / MSc. Ciencias de Gestión
    ·
    <a href="LICENSE">MPL-2.0</a>
  </sub>
</p>
