785 artículos para agentes, no para personas. Una base de conocimiento sin búsqueda vectorial

Cuando un agente empieza a trabajar en un proyecto desconocido, dedica los primeros 30 a 40 % de sus tokens a averiguar qué pasa a su alrededor. No a trabajar: a orientarse. Este post describe Happyin Knowledge Space, una biblioteca de tarjetas de referencia que escribo para agentes y no para personas: por qué el formato de la tarjeta tiene el aspecto que tiene, por qué los dominios que cambian rápido llevan un umbral de frescura, por qué enlazo las tarjetas a mano en lugar de meterlas en una base de datos vectorial, y cómo la investigación de chats en varias cuentas acaba ahí sin copiar ni pegar nada. El 22 de abril de 2026, cuando salió el original en ruso, contenía 785 tarjetas en 26 dominios.

Dos problemas de cómo aprende un agente un proyecto

Un README explica la motivación, un tutorial te lleva de la mano, una referencia de API enumera parámetros. Ninguno responde a la pregunta con la que llega realmente el agente: esta es mi tarea, ¿qué patrón copio y dónde están las minas?

El segundo problema es más profundo y tarda más en notarse. Un modelo sabe "de todo", pero ese todo está repartido de forma desigual en sus datos de entrenamiento. Cuanto más tiempo lleva una tecnología en internet, más publicaciones, respuestas de Stack Overflow y tutoriales existen sobre ella, y más peso tiene ese enfoque dentro del modelo. Cuando le pido a Claude que entrene un LoRA, lo primero que propone es una receta de hace cinco años. No porque sea mejor, sino porque hay más. Para tecnologías estables está bien. Para lo que se mueve rápido, como el entrenamiento de modelos, las herramientas de agentes o la seguridad, significa que el agente me arrastra en silencio al pasado.

La cura obvia es lanzar una investigación profunda cada vez y traer contexto actual. Lo hago. Pero la investigación profunda es cara: varios cientos de dólares al mes en suscripciones, y los límites se agotan casi enseguida. Peor aún, cada investigación desaparece con su sesión. Mañana haría la misma búsqueda sobre el mismo tema y gastaría los mismos tokens en lo que ya había averiguado.

De esto salieron dos ideas. La investigación debe acumularse, no evaporarse. Y el formato debe mostrarle al agente qué es lo actual, para que al abrir un proyecto entienda de inmediato "así es como se hace aquí".

El formato: una tarjeta, no un artículo

Cada tarjeta tiene el mismo esqueleto. Arriba, el tema y una definición en una frase, para que el agente sepa enseguida si ha llegado al lugar correcto. Luego Key Facts: afirmaciones breves con números, como versiones, umbrales y dependencias. Después Patterns: código listo para copiar con una etiqueta de lenguaje. Al final, las trampas, cada una como un par de lo que se rompe y lo que lo arregla.

Sin introducciones de "veamos" ni cierres de "en este artículo hemos examinado". La tarjeta de arquitectura de brokers de Kafka es una tabla ZooKeeper frente a KRaft, una configuración comentada, métricas JMX con umbrales de alerta y una migración paso a paso. No se lee de corrido. Pero un agente que busca con grep "KRaft migration" obtiene una receta que funciona en tres pasos.

El último bloque es el más valioso. Una sola línea, "min.insync.replicas solo tiene efecto con acks=all", ahorra media hora de depuración. El agente la leyó, no cometió el error y no gastó un ciclo de reintento arreglándolo.

26 dominios, nacidos del trabajo

En abril, el dominio más grande era Generación de imágenes con 58 tarjetas, seguido de cerca por Agentes LLM con 57, luego Data Science y Seguridad con 56 cada uno (Seguridad creció a través de una carpeta aparte sobre clases CWE). Después venían Kafka con 43, DevOps con 38, Frontend web con 36, Ingeniería de datos con 34, y cuatro dominios con 33: Python, SQL, Arquitectura y Algoritmos. Catorce más pequeños completaban el resto: iOS, CLI de Linux, C++, Java Spring, Testing y QA, BI, SEO, Rust, Node.js, PHP, memoria de LLM, Audio y voz, Escritura y Go.

Esto no es un plan. Es un mapa de dónde va realmente mi tiempo cuando trabajo con agentes: entrenar LoRAs, depurar plugins de C++, investigación. Cada área había reunido su propia lista de sitios donde algo se me había roto, y esas listas se convirtieron en el esqueleto.

El conocimiento no envejece a una sola velocidad

Los algoritmos y las matemáticas son estables: una tarjeta sobre análisis amortizado o flujo en redes escrita hace tres años sigue siendo correcta. El entrenamiento de difusión, la optimización de inferencia y los nodos de ComfyUI cambian cada pocos meses, y lo que funcionaba en otoño ha quedado atrás en primavera. La difusión por teselas en fotos muy grandes, de la que escribí en Por qué la difusión dibuja costuras en fotos de 40 megapíxeles, es uno de esos temas que cambian rápido.

Así que cada dominio tiene su propio umbral de frescura. Los dominios estables no tienen ninguno. En los dominios rápidos, una tarjeta de más de 60 días se marca para revisión, y un hook que se ejecuta una vez al día la coloca en una lista de "revisar y actualizar". No es una alerta de borrado. Es un recordatorio de que el tema probablemente ha cambiado y la tarjeta necesita contrastarse con lo que es cierto ahora. Las tarjetas obsoletas salen a revisión por sí solas, en lugar de inducir al agente a error en silencio.

Enlaces en lugar de vectores

La arquitectura obvia para esto es una base de datos vectorial con RAG encima. Encuentra textos semánticamente cercanos con rapidez y funciona bien en producción. Deliberadamente no usé una, por tres razones.

Un almacén vectorial no es legible para humanos. El Markdown lo puedo abrir en un editor de texto, buscar con grep, comparar con git, pegar en un correo o imprimir y clavar en una pared. Eso funciona hoy y funcionará dentro de diez años en cualquier ordenador, sin herramientas especiales. Un almacén vectorial es un binario que solo entiende su propio cliente. Cambia de proveedor, pierdes el servicio, rompes la API, y los datos se convierten en un montón de números que nadie puede leer. Quería que la base de conocimiento sobreviviera a un cambio de herramientas, no que dependiera de ellas.

Vectorizar es casi irreversible. Un embedding es una compresión con pérdida y de un solo sentido. Sin los fragmentos originales guardados junto a él, un archivo de embeddings no sirve de nada, porque recuperar texto legible es casi imposible. La investigación sobre inversión de embeddings existe, pero funciona con fragmentos muy cortos, necesita el mismo modelo de embeddings y un decodificador entrenado aparte. Además te ata a un único modelo de embeddings: si cambias de modelo para mejorar la calidad, tienes que reindexarlo todo, porque los vectores viejos no significan nada en el nuevo espacio.

Y el que más me importa: un grafo de enlaces registra qué temas son adyacentes, no qué textos se parecen. La similitud vectorial encuentra temas que se solapan en vocabulario y conceptos. En el trabajo real, los enlaces valiosos a menudo van entre temas muy alejados. Mi tarjeta de replicación de Kafka enlaza con una tarjeta de perfilado de memoria, no porque los temas se parezcan, sino porque ajustar un consumidor sacó a la luz una fuga de memoria, y la experiencia los hizo vecinos. En el espacio de embeddings, "replicación en una cola distribuida" y "perfilado de memoria en Python" están muy lejos, y la búsqueda semántica no tendrá ese puente. Un enlace de wiki escrito a mano sí lo tiene, y ahora un agente que lee sobre Kafka está a un paso del perfilado de memoria.

El mecanismo es simple. Las tarjetas se referencian entre sí como [[flux-klein-9b-inference]], [[two-phase-commit]], [[saga-pattern]]. En el momento de construir el sitio, un hook de Python resuelve cada slug a una ruta relativa. Si no encuentra un slug, el log muestra una advertencia, y en modo estricto la construcción falla, así que un enlace roto nunca llega al sitio en vivo. En abril había más de 2.100 de estos enlaces. Ese es todo el grafo de conocimiento: sin embeddings, sin base de datos vectorial, sin RAG. Markdown y grep. Un agente abre la tarjeta sobre transacciones distribuidas, ve los temas vecinos bajo Ver también, sigue uno y continúa. Tres pasos desde el punto de entrada hasta un patrón que funciona.

Es la misma idea que los enlaces [[filename]] de la memoria de mis agentes, descrita en Mi CLAUDE.md tiene 582 líneas.

El sitio es una construcción del repositorio

Todo en happyin.space es un sitio estático construido a partir de Markdown en un repositorio abierto. Sin base de datos, sin backend, sin capa oculta. El archivo docs/kafka/broker-architecture.md se convierte en la página happyin.space/kafka/broker-architecture/ tras una construcción, y ese es todo el mecanismo.

Lo que significa que cualquiera puede bifurcarlo y ejecutarlo en local en unos cinco minutos:

git clone https://github.com/AnastasiyaW/knowledge-space.git
cd knowledge-space
pip install -r requirements.txt
mkdocs serve        # then open http://localhost:8000

Eso da una copia local con cada tarjeta, búsqueda completa y el grafo de enlaces. A partir de ahí puedes vaciar mis dominios, añadir los tuyos y apuntar a tus agentes a la construcción local en lugar de al sitio público. Así lo uso yo: la mayor parte del tiempo tengo abierta la construcción local, y el sitio público es un espejo.

Una reconstrucción completa tardaba unos cinco segundos, igual de rápido en un portátil antiguo que en una estación de trabajo, porque por debajo hay el tipo de generador de sitios estáticos que la industria usa desde hace quince años. Un agente que trabaja con una copia local no gasta tokens en un viaje de ida y vuelta por la red ni en esperar un despliegue: reconstruye, abre la tarjeta y toma la receta.

El mismo paso de construcción mantiene los enlaces honestos. Recorre cada [[slug]], encuentra la tarjeta correspondiente y escribe la ruta relativa, y si no encuentra nada, la construcción falla. Lo veo en local antes de hacer commit, y el CI ejecuta la misma comprobación en modo estricto, donde cualquier enlace roto bloquea el despliegue. En abril eso significaba más de 2.100 enlaces y ninguno roto. Y como el sitio es el repositorio, todo está en git: puedes ver cómo cambió una tarjeta, qué hechos llegaron tras qué ronda de investigación y cuándo se tocó por última vez. Para una base ordenada según la velocidad a la que envejece su conocimiento, ese historial importa.

Cómo entra la investigación

La rutina está montada para que nunca mueva datos a mano. Tengo varias cuentas de Claude, cada una con varios chats abiertos, y en cualquiera de ellos puede iniciarse en algún momento una investigación profunda: modelos nuevos, optimizaciones, errores, lo que sea. Antes, el resultado vivía hasta el final del chat. Ahora cada uno de esos chats sigue la misma regla permanente: cuando termina una investigación, deja una copia del resultado en un único lugar central.

Ese lugar es un proyecto de Claude Code vinculado al repositorio knowledge-space, con su propia carpeta research/inbox/ que recoge los volcados en bruto de cada chat de cada cuenta. Sin copiar ni pegar, solo una regla que cada chat lee al empezar y sigue al terminar su investigación.

Luego viene una segunda pasada. Una sesión aparte sobre el proyecto knowledge-space trabaja la bandeja: lee cada volcado en bruto, extrae los hechos concretos y las trampas, los reempaqueta en el formato de tarjeta y los contrasta con lo que ya hay en ese dominio, para que los duplicados enriquezcan las tarjetas existentes en lugar de multiplicarse. Después comprueba los enlaces de wiki, ejecuta la construcción, lee el diff y envía los cambios. Una sesión así suele dar entre 20 y 40 tarjetas nuevas o enriquecidas en unas pocas horas.

La división de modelos sale de aquí directamente, y es donde por fin encontré un uso para Sonnet. Para mí había estado entre "demasiado listo para cosas simples" y "demasiado simple para algo interesante". Pero "lee un volcado de investigación en bruto, extrae los hechos, reempaquétalos en el formato de tarjeta, compáralos con los vecinos de la carpeta" es exactamente su tipo de trabajo: mecánico, pero con lenguaje dentro. Sonnet reempaqueta texto tan bien como el modelo más grande y cuesta bastante menos, así que las sesiones de investigación y la pasada por la bandeja se ejecutan con él. Comprobar los enlaces de wiki, decidir si dos tarjetas deben fusionarse o resolver un conflicto entre dos fuentes es trabajo de entender-decidir-diseñar, y eso va al modelo más fuerte. La diferencia de coste es un múltiplo, sin pérdida de calidad.

El resultado es un flujo. Hago mi trabajo principal, lanzo investigaciones en distintos chats por el camino, y la base se llena sin que yo mueva ni formatee nada.

Usarlo y aportar

La forma más sencilla de usarlo es apuntar tu agente a happyin.space/llms.txt y dejar que descargue tarjetas según las necesite. Eso solo ya recorta el primer tercio de tokens que se iban en orientarse.

El siguiente nivel es contribuir. El repositorio tiene dos archivos escritos para esto: CONTRIBUTING.md, una guía general para preparar páginas y enviar cambios, y AGENTS.md, instrucciones para tu agente. Describen el formato de tarjeta, qué densidad debe tener el texto, qué va en Gotchas, cómo escribir enlaces de wiki y cómo abrir un pull request con una tarjeta nueva o una corrección. Dale a tu agente la guía y un resultado de investigación reciente, y él mismo arma la tarjeta. Tu investigación entra en la base, dejas de pagarla otra vez, y los demás tampoco tienen que pagarla. El README indica licencia MIT.

Cuanta más investigación hay en la base, menos tiene que repetir alguien. Cuantas más personas y agentes envían tarjetas, más puentes inesperados aparecen entre dominios, y esos son los valiosos. La página del proyecto en esta web es happyin.space.

Qué cambió después de abril

Actualización, septiembre de 2026. El README del repositorio informa ahora de más de 1.287 artículos en 28 dominios y más de 3.139 referencias cruzadas. La mayor parte del crecimiento son dos tipos nuevos de página: projects/, 388 páginas con una por herramienta, modelo o producto que sigue una canalización de noticias, y organizations/, 45 páginas con una por empresa o laboratorio. La regla de frescura es ahora un ciclo de cuatro pasos en el README: estable, anual, cada seis meses y mensual, con la generación de imágenes y los frameworks de agentes en el grupo mensual.

Las cifras de abril de más arriba (785 tarjetas, 26 dominios, más de 2.100 enlaces, el umbral de 60 días, una construcción de cinco segundos) eran ciertas el día de publicación, y las he dejado como estaban. La misma preferencia por archivos planos frente a un servicio, aplicada a varias sesiones de agentes trabajando a la vez, está en Varios Claude en un mismo repo.