English • 한국어 • Español • 中文

epistemekernel.com

episteme obliga a un agente de IA a mostrar su razonamiento antes de actuar.

Conoces la sensación: el diff se ve bien, el análisis suena correcto, y una vocecita dice quizá debería leer esto con más cuidado. episteme es esa voz, pero con dientes. Antes de cualquier cosa irreversible — un push, un deploy, una migración — tu agente tiene que escribir qué sabe, qué no sabe y qué probaría que está equivocado. En disco, donde puedas leerlo. Una puerta silenciosa y determinista aguanta cerrada hasta que el razonamiento sea real.

Se integra con las herramientas que ya usas (hoy Claude Code; una capa de adaptadores neutral respecto al proveedor para las demás). Las lecciones de decisiones verificadas se quedan como protocolos a prueba de manipulación que reaparecen justo cuando vuelven a importar — así el agente se afila sobre tu codebase con el tiempo, y tu documentación se sostiene con el mismo estándar que tu código.

Qué aspecto tiene ↓ · Instalación ↓ · Las demos ↓ · Cómo se compara ↓ · Bajo el capó ↓ · ¿Funciona? ↗

Qué aspecto tiene

Digamos que le pides a tu agente: "Evalúa si nuestro sistema de memoria con retrieval-augmented está mejorando realmente la calidad de las respuestas."

Sin episteme, el agente lo trata como una tarea de medición. Saca 30 días de métricas, encuentra un 7% de lift en la tasa de thumbs-up y te escribe un memo confiado: "la memoria ayuda; sigamos enviando." Se lee precioso. También está equivocado de tres formas a la vez:

• El thumbs-up mide la confianza de la respuesta, no su corrección — midió un proxy de tu pregunta, no la pregunta.
• Las respuestas con memoria son un 30% más largas, y la longitud por sí sola empuja el thumbs-up — ese "lift" podría ser el efecto de la longitud.
• Nunca se nombró ninguna condición bajo la cual la conclusión se juzgaría errónea — así que no puede serlo.

Con episteme, el memo todavía no puede aterrizar. Primero, el agente tiene que dejar esto en disco:

Las respuestas perezosas (none, n/a, tbd, 해당 없음) no pasan. Las evasivas vagas ("si surgen problemas") tampoco — solo pasa una forma concreta y observable de quedar refutado. Y aquí está la magia silenciosa: el acto mismo de escribir esa surface es lo que deja al descubierto que el thumbs-up nunca fue la pregunta. Ese es el producto. El agente tiene que pensar de una forma que puedas auditar, antes de que las consecuencias existan.

Grabado desde scripts/demo_posture.sh — una eliminación de restricción bloqueada, una reescritura validada, un refactor obligado a declarar su blast radius, y el protocolo sintetizado disparándose en una decisión posterior.

Qué obtienes

• Una puerta en el punto de no retorno. Las operaciones de alto impacto se interceptan antes de ejecutarse, y se revisa que el razonamiento del agente tenga sustancia — incluidas las formas escurridizas (subprocess.run(['git','push']), scripts de shell escritos por el agente, comandos envueltos). Sin una surface real, no hay ejecución. Strict por defecto; y si quieres, puedes suavizarlo por proyecto.
• Una segunda opinión que nunca tocó el borrador. La estructura por sí sola no distingue el pensamiento del teatro. Así que para las decisiones que soportan carga, el gate acepta un artefacto más fuerte: la decisión descompuesta en afirmaciones, cada una verificada por un contexto fresco que nunca vio el razonamiento original, con la oposición más fuerte realmente argumentada. Si el veredicto dice parar, se para.
• Memoria que se acumula en vez de decaer. Cada lección verificada se convierte en un protocolo a prueba de manipulación, acotado a su contexto. La próxima vez que aparezca una decisión que encaje, el kernel te trae la lección — Protocol: In context X, do Y — sin que tengas que acordarte de que existe. El agente se afila sobre tu codebase en concreto.
• Documentación que se mantiene honesta. Cada doc rastreado lleva un marcador de ciclo de vida, y CI falla cuando la realidad se desvía — un doc sin clasificar, un doc living que cita uno retirado, una cadena de versión que alguien copió a mano. Los docs obsoletos te saludan al inicio de sesión, y solo cuando algo está realmente obsoleto. Una única fuente de verdad, impuesta en lugar de aspirada.
• Un sistema que recoge lo suyo. Las colas tienen tope con contrapresión visible, los logs rotan, los marcadores expirados se barren al inicio de sesión. Nada se apila en una esquina; borrar es una operación diseñada, no un accidente del descuido.
• Una sola identidad entre herramientas. Tu estilo de trabajo, tu postura ante el riesgo y tus preferencias de razonamiento viven en markdown versionado — sincronizado a cada adaptador con un solo comando. El kernel sobrevive a la herramienta que estés usando este año.

Instalación

Opción A — plugin de Claude Code (dos comandos, autocontenido):

/plugin marketplace add junjslee/episteme
/plugin install episteme@episteme

Los hooks, agentes y skills están vivos en tu sesión; sin pip de por medio.

Opción B — clonar el kernel (CLI + fuente editable):

git clone https://github.com/junjslee/episteme ~/episteme
cd ~/episteme && pip install -e .

episteme init      # generate personal memory files from templates
episteme setup .   # score working style + reasoning posture
episteme sync      # push identity to every adapter
episteme doctor    # verify wiring

¿Lo estás adoptando en un repo que ya existe? Corre episteme docs lint primero — le pide a cada doc rastreado que declare qué es, y esa primera corrida suele ser el inventario más honesto que el repo ha tenido nunca. Los detalles, los harnesses de proyecto y la referencia completa de comandos están en INSTALL.md · docs/SETUP.md · docs/COMMANDS.md.

Las demos

Cada demo trae sus artefactos reales. Léelos antes que cualquier filosofía — son los recibos.

Puedes regrabar tú mismo la demo estrella: scripts/demo_posture.sh (la receta está en la cabecera del script). El dashboard en vivo se renderiza contra la propia cadena hash del kernel — web/README.md.

Cómo se compara

¿No es esto solo contract testing? Los contract tests preguntan si el código hizo lo que dice el spec. La Reasoning Surface pregunta algo anterior y más difícil: ¿era ese el spec correcto, era esa la pregunta correcta, y qué nos habría avisado de lo contrario? Una suite de tests en verde no puede decirte que estás resolviendo el problema equivocado con elegancia — esa falla ocurre antes de que el spec exista. episteme envía ambas capas (docs/CONTRACT_GATE.md).

¿Por qué no puede hacer esto un prompt? Porque los prompts son sugerencias. Viven una sola llamada, se saltan cuando vas con prisa, y se caen del contexto sin avisar. Un hook que sale con código distinto de cero no negocia. El benchmark MIRROR (arXiv 2604.19809; 16 modelos, 8 laboratorios, ~250k instancias) probó exactamente esto: mostrarle a un modelo sus propias puntuaciones de calibración no cambió nada — solo ayudó la restricción arquitectónica (tasa de fallo confiado 0.60 → 0.14). La postura le gana al prompt.

Límites honestos

• kernel/KERNEL_LIMITS.md dice sin rodeos cuándo esta no es la herramienta para ti. Una disciplina sin frontera es solo un credo.
• Se somete al mismo estándar. En junio de 2026 el bucle de síntesis de protocolos disparó su propia condición de falsabilidad — 49 días, cero protocolos sintetizados — y se reconstruyó alrededor de interrogaciones verificadas. El rastro completo es público (kernel/FAILURE_MODES.md, docs/EVALUATION_METHOD.md). Una herramienta que le exige disconfirmation a tus decisiones te debe lo mismo sobre sí misma.
• Cada idea prestada está acreditada, junto al trabajo de 2025–26 que llegó a patrones parecidos de forma independiente: kernel/REFERENCES.md.

Bajo el capó

Estado: 1.10.0-rc.1 · La práctica son cinco etapas — Frame → Decompose → Execute → Verify → Handoff — y cada una existe para contrarrestar una forma concreta en que la mente falla bajo la fluidez: question substitution, WYSIATI, anchoring, narrative fallacy, planning fallacy, overconfidence. La historia completa está en docs/THE_WAY_TO_THINK.md; los cuatro Cognitive Blueprints (Axiomatic Judgment · Fence Reconstruction · Consequence Chain · Architectural Cascade) están especificados en docs/ARCHITECTURE.md.

graph TD
    subgraph SG1["① The Agentic Mind — Intention"]
        A["Agent\nGenerating intent for a high-impact op"]
        B["Reasoning Surface\ncore_question · knowns · unknowns\nassumptions · disconfirmation"]
        D["Doxa\nFluent hallucination\nnone / n/a / tbd / 해당 없음\n< 15 chars · missing fields"]
        E["Episteme\nJustified true belief\nconcrete knowns · named unknowns\ndisconfirmation ≥ 15 chars · no placeholders"]
    end

    subgraph SG2["② The Sovereign Kernel — Interception"]
        F["Stateful Interceptor\ncore/hooks/reasoning_surface_guard.py\nnormalises cmd · deep-scans agent-written files\ncross-call stateful memory"]
        G["Hard Block · exit 2\nExecution denied\nAgent forced to re-author surface"]
        H["PASS · exit 0\nPrecondition satisfied\nExecution admitted to Praxis"]
    end

    subgraph SG3["③ Praxis & Reality — Execution"]
        I["Tool Execution\ngit push · bash script.sh · npm publish\nterraform apply · DB migrations · lockfile edits"]
        J["Observed Outcome\ncore/hooks/calibration_telemetry.py\nexit_code 0 or non-zero · stderr captured"]
    end

    subgraph SG4["④ 결 · Gyeol — Cognitive Texture & Evolution"]
        K["Prediction Record\ncorrelation_id stamped at PASS\n~/.episteme/telemetry/YYYY-MM-DD-audit.jsonl"]
        L["Outcome Record\ncorrelation_id · exit_code · stderr\n~/.episteme/telemetry/YYYY-MM-DD-audit.jsonl"]
        M["episteme evolve friction\nsrc/episteme/cli.py · _evolve_friction\npairs prediction ↔ outcome by correlation_id\nranks under-named unknowns · flags exit_code ≠ 0"]
        N["결 · Gyeol\nRefined cognitive grain\nfriction hotspots · calibrated profile axes"]
        O["Operator Profile\ncore/memory/global/operator_profile.md\nlast_elicited axes updated · confidence rescored"]
        P["kernel/CONSTITUTION.md\nFour principles recalibrated\nfailure-mode counters sharpened"]
    end

    A --> B
    B --> D
    B --> E
    D --> F
    E --> F
    F --> G
    F --> H
    G -.->|"cognitive retry"| A
    H --> I
    I --> J
    E -.->|"correlation_id stamped at PASS"| K
    J --> L
    K --> M
    L --> M
    M --> N
    N --> O
    N --> P
    O -.->|"posture loop closed"| A
    P -.->|"posture loop closed"| A

    classDef doxaStyle fill:#c0392b,stroke:#922b21,color:#fff
    classDef episteStyle fill:#1e8449,stroke:#145a32,color:#fff
    classDef passStyle fill:#27ae60,stroke:#1e8449,color:#fff
    classDef praxisStyle fill:#2ecc71,stroke:#27ae60,color:#000
    classDef gyeolStyle fill:#1a5276,stroke:#154360,color:#fff
    classDef kernelStyle fill:#6c3483,stroke:#512e5f,color:#fff
    classDef neutralStyle fill:#2c3e50,stroke:#1a252f,color:#fff

    class D,G doxaStyle
    class E episteStyle
    class H,I passStyle
    class J praxisStyle
    class K,L,M,N,O,P gyeolStyle
    class F kernelStyle
    class A,B neutralStyle

Cuatro ideas, en los colores de arriba. Doxa (rojo) es salida fluida pero no validada — el estado de falla que todo esto existe para prevenir. Episteme (verde) es una surface que de verdad se sostiene, y es el precio de entrada para ejecutar. Praxis es la acción que pasó, más lo que ocurrió realmente. 결 · Gyeol (azul) es el bucle que devuelve esos resultados a tu calibración de la próxima vez. Agnóstico al stack por construcción: el kernel es markdown plano, el perfil JSON plano, y los adaptadores (Claude Code, Hermes, OMO/OMX) intercambiables.

El kernel mismo — markdown, sin código, nada que te ate — empieza en kernel/:

episteme/
├── kernel/          philosophy (markdown; travels across runtimes)
├── core/hooks/      deterministic gates + session automation
├── src/episteme/    CLI + core library (doc lifecycle, sync, telemetry)
├── adapters/        delivery layers (Claude Code, Hermes, …)
├── demos/           end-to-end reference deliverables
├── skills/          reusable operator skills
├── templates/       project scaffolds
└── docs/            architecture, contracts, runtime docs — lifecycle-linted

Jerarquía de autoridad: docs del proyecto > perfil del operador > defaults del kernel > defaults del runtime. Contrato operativo del repo para agentes: AGENTS.md · sitemap para LLM: llms.txt.

Lee a continuación

Licenciamiento comercial

¿Necesitas una licencia comercial, o ayuda para adoptar esto? Escríbeme — me interesa de verdad saber qué estás construyendo.

Nota sobre la traducción. Este README es una traducción al español mantenida junto al README.md canónico en inglés. Para la documentación más profunda, los recorridos de las demos y los diagramas de arquitectura, consulta el árbol de docs en inglés. Los términos de carga del kernel (Reasoning Surface, Core Question, Blueprint, hook, kernel, doxa/episteme/praxis, etc.) se conservan en inglés a propósito.