Formato de Conocimiento Abierto: Archivos Markdown como capa de conocimiento portátil para agentes

Los agentes desperdician tokens al leer una y otra vez los mismos documentos internos, y Google Cloud ha propuesto una solución: el Open Knowledge Format, OKF. La versión 0.1 se anunció en el blog de Google Cloud el 12 de junio de 2026. La idea es sencilla. Cada concepto que le interesa a un equipo se convierte en un archivo Markdown, y una carpeta con esos archivos funciona como un grafo de conocimiento ligero que cualquier agente puede leer. No necesita SDK, ni base de datos, ni dependencias. Un escéptico podría pensar que se trata de otra plataforma disfrazada de formato, pero en realidad son solo archivos, y eso es lo interesante. Los equipos siguen añadiendo complejidad a los agentes cuando una de las preguntas más difíciles es en realidad más simple: ¿dónde reside realmente el conocimiento útil?

El problema: los agentes siguen teniendo que reaprender

Este es el patrón habitual: un agente recibe una pregunta sobre una métrica, carga todo el wiki interno, incrusta el texto y deduce su significado desde cero. En la siguiente consulta hace exactamente lo mismo. El texto en bruto puede ser almacenado en caché, pero nadie guarda en caché la comprensión obtenida.

Imagínese un agente que tiene que volver a leer un documento que define qué es un usuario activo en cada consulta, ya que esa definición no tiene un lugar específico y se encuentra en una página de Notion tres carpetas más abajo. Cada llamada es económica, pero el desperdicio se acumula, como ocurre con los pequeños gastos cuando nadie los vigila; en un equipo que realiza las mismas pocas consultas a diario, el consumo de tokens resulta significativo. No existe una cifra pública al respecto, ya que los externos no tienen los datos internos de Google, pero el problema es conocido por la mayoría de quienes manejan agentes.

Un caso más concreto: un documento de análisis define a un usuario activo como cualquier persona que realizó al menos una acción significativa con el producto en un mes natural. Si se le pregunta a un agente cuántos usuarios activos hubo el mes pasado, se necesitan dos cosas diferentes: los números y una definición clara de qué se entiende por “activo”. Se trata de problemas separados. La base de datos informa sobre lo que ocurrió, mientras que una capa de conocimiento registra el significado que la empresa le da a ese término. OKF tiene como objetivo facilitar la representación de esa segunda parte.

La solución es un formato, no un modelo más complejo

OKF es deliberadamente simple, hasta el punto de resultar aburrido. Un paquete es una carpeta de archivos en formato Markdown, cada uno de los cuales describe un concepto, ya sea una tabla, una métrica, una API o un manual de procedimientos. Cada archivo comienza con un pequeño bloque en YAML, el frontmatter, entre dos líneas marcadoras. Solo hay un campo obligatorio:

---
type: Metric   # required – tells the agent what kind of concept this is
---

Cinco campos opcionales completan el formulario, enumerados aquí con sus propósitos:

| Field         | Purpose                      |
| ------------- | ---------------------------- |
| `title`       | Human-readable name          |
| `description` | Short summary                |
| `resource`    | Link to the underlying asset |
| `tags`        | Keywords for categorization  |

La versión 0.2 añade campos opcionales que abarcan el origen, la verificación, la frescura, el ciclo de vida y los cálculos que han sido verificados. Puede agregar cualquier clave adicional, y se espera que los consumidores ignoren aquellas que no reconozcan sin que eso cause problemas, lo cual permite ampliar el formato sin dañar el agente de otra persona. Están reservados dos nombres de archivo: index.md para un listado de directorios y log.md para un historial de cambios, lo que le ahorra la necesidad de inventar convenciones ya establecidas en la especificación. La especificación se lanzó como borrador v0.1, por lo que espere que evolucione y consulte el repositorio para obtener la versión actual antes de crear algo importante.

Los enlaces forman el grafo

Dado que los archivos son de Markdown puro, los conceptos se conectan mediante enlaces comunes [texto](otro-file.md), y esos enlaces constituyen los bordes de un grafo que se encuentra en la carpeta, sin necesidad de una base de datos adicional. Un archivo de concepto válido se ve así:

---
type: Metric
title: Monthly Revenue
description: Total money earned each month.
resource: https://console.cloud.google.com/bigquery?p=project&d=dataset&t=revenue
tags: [finance, monthly]
---

Revenue is counted after refunds are removed.

See also: [customer_acquisition_cost.md](customer_acquisition_cost.md)

Un agente que lee revenue.md se entera de que un concepto relacionado se encuentra en customer_acquisition_cost.md. El significado del enlace sigue proviniendo de quien escribió los archivos, ya que el formato no pretende entenderlo por usted.

Probándolo en cinco minutos

La especificación incluye conjuntos de ejemplos reales creados a partir de datos de comercio electrónico de GA4, datos de Stack Overflow y datos de la cadena de bloques de Bitcoin. Un agente de referencia que examina los conjuntos de datos de BigQuery y redacta documentos OKF los generó automáticamente, y todo está en un único repositorio de Apache 2.0:

git clone https://github.com/GoogleCloudPlatform/knowledge-catalog.git
cd knowledge-catalog/okf

# Add your own concept
cat > new_metric.md <<'EOF'
---
type: Metric
title: Net Promoter Score
description: Measure of customer loyalty.
resource: https://console.cloud.google.com/bigquery?p=company&d=metrics&t=nps
tags: [customer, loyalty]
---
EOF

Cada paquete de ejemplos incluye un archivo viz.html. Ábralo en cualquier navegador para ver un gráfico interactivo del paquete con nodos, enlaces, búsquedas y filtros, sin necesidad de un backend o servidor. Una advertencia es que generar un viz.html para su propio paquete implica ejecutar la pequeña herramienta de referencia en Python que se encuentra en el repositorio. Esta herramienta convierte el paquete en una única página HTML autónoma basada en Cytoscape.js y marked.js, nuevamente sin backend, solo un archivo que puede enviar por correo electrónico a un colega.

Beneficios

• Menor costo: la definición se escribe una sola vez y se lee directamente, por lo que deja de pagar por derivarla cincuenta veces al día.
• Carga más rápida: se trata de texto plano en el disco, sin necesidad de realizar viajes de ida y vuelta por red a un servicio de conocimiento ni de ningún paso de incrustación antes de usarlo.
• Portabilidad real: clona el repositorio, copia la carpeta o únsela a una imagen Docker, y funcionará de la misma manera en GCP, Azure, AWS o en una laptop. No hay nada que te ate a un solo entorno.
• Control de versiones gratuito: los paquetes se almacenan en git, por lo que se aplican solicitudes de pull, diferencias, análisis de responsabilidades y revisiones, y la gestión del conocimiento se convierte en un trabajo de ingeniería habitual.
• Una única fuente para personas y agentes: un nuevo empleado y un agente de soporte abren el mismo archivo, así que el wiki no puede decir una cosa mientras el agente cree otra.
• Intercambio entre equipos y organizaciones: un proveedor puede entregar un catálogo como un paquete OKF que tu agente puede consumir directamente, sin necesidad de realizar trabajos de integración.

La posibilidad de revisión es otra ventaja. Supongamos que un agente propone este cambio:

- Revenue is recognized when an order is placed.
+ Revenue is recognized after delivery and the 30-day return window.

Eso es un simple diff de Git, y el revisor ve con precisión qué se ha modificado. Es mucho más fácil de evaluar que una actualización silenciosa oculta en un sistema de conocimiento propietario.

Donde falla

• No corrige definiciones erróneas. OKF estandariza el contenedor y no su contenido, por lo que si un equipo no puede ponerse de acuerdo en qué significa “usuario activo”, un archivo Markdown no forzará ese acuerdo.
• Alguien debe mantenerlo. Los archivos se vuelven obsoletos, y los campos timestamp y log.md solo son útiles si personas o agentes los actualizan. El conocimiento desactualizado puede causar más daño que no tenerlo, ya que los agentes creen en todo lo que encuentran.
• Se trata de un borrador reciente y explícitamente inacabado, por lo que los campos y convenciones pueden cambiar, y quienes lo adopten tempranamente deben esperar cambios constantes.
• El significado no se impone de forma estricta. Un enlace indica que dos conceptos están relacionados, pero no cómo, y la relación se expresa en texto prosaico, lo cual es flexible pero también vago. Las relaciones con tipado estricto siguen requiriendo una base de datos de grafos real.
• Hasta ahora hay pocos adoptantes. Casi todos los productores y consumidores en el momento del lanzamiento provenían de Google, y el formato solo tendrá éxito si otras herramientas y equipos lo adoptan.

OKF junto con RAG y MCP

Nada de lo que está en la pila actual se descarta, ya que OKF se integra debajo de ella. RAG sigue encontrando pasajes relevantes cuando llega una consulta, y OKF le proporciona texto más limpio y preestructurado, lo que hace que los embeddings sean más precisos y menos costosos de generar. MCP, el Protocolo de Contexto de Modelo de Anthropic, transporta el contexto durante una conversación, y OKF puede funcionar como fuente de la cual extraen esos herramientas. MCP gestiona el flujo mientras OKF almacena las definiciones, de modo que nadie tiene que volver a derivarlas cada vez. Las tres capas se ven así:

OKF
↓
"What does this concept mean?"

RAG
↓
"Which pieces of knowledge should I retrieve?"

MCP
↓
"How does the agent interact with the tools and context?"

Cada capa resuelve un problema diferente, por lo que OKF debe verse más bien como una capa de conocimiento compartido que subyace a ambas que como un competidor. Los archivos Markdown apenas parecen algo relacionado con el lanzamiento de un producto, pero a veces la opción más sencilla es la que funciona.

¿Deberías usarlo?

Para cualquier agente que responda preguntas sobre tus datos, métricas o sistemas, la respuesta es sí: pruébalo. Intentarlo cuesta casi nada: escribe tres archivos, únelos, dirige al agente hacia la carpeta, y en una tarde sabrás si resulta útil. Si tu conocimiento está en la cabeza de una sola persona o en una wiki desorganizada, OKF ofrece un lugar sencillo y con control de versiones donde finalmente poder anotarlo, lo cual puede valer la pena con o sin un agente. Si necesitas esquemas estrictos, relaciones tipadas o una gobernanza rigurosa, hoy en día es demasiado flexible, así que guarda tu catálogo y quizás exporta un paquete más adelante.

No comience con toda la base de conocimientos de la empresa. Elija un área pequeña, por ejemplo:

metrics/
  active-user.md
  revenue.md
  conversion-rate.md

systems/
  payments-api.md
  orders-api.md

runbooks/
  payment-failure.md

Vincule los archivos, entréguelos a un único agente y mida qué cambios ocurren. Ese es un experimento mucho mejor que pasar tres meses diseñando una plataforma empresarial OKF antes de demostrar que es necesaria.

Un único campo obligatorio y una carpeta con archivos en formato Markdown no resolverán por sí solos la mala documentación. Lo que ofrecen es un espacio compartido, sencillo y portátil para la buena documentación que ya tiene un equipo, lo cual vale más de lo que parece en teoría.