En un momento en el que muchos proyectos de documentación y contenidos dependen de servicios externos, pdf-brain propone justo lo contrario: una biblioteca de PDFs 100 % local, con búsqueda semántica mediante vectores, pensada para correr en el propio equipo del desarrollador o del redactor técnico.
El proyecto, disponible como paquete de Node (npm install pdf-brain), funciona como un “cerebro de PDFs” que extrae el texto de los documentos, genera embeddings con Ollama y almacena todo en una base de datos PGlite con pgvector para ofrecer búsquedas por significado, no solo por palabras clave. Para equipos que trabajan con WordPress —documentación, guías técnicas, PDFs descargables, whitepapers— es una herramienta interesante para organizar y explotar todo ese material en local antes de publicarlo.
Biblioteca de PDFs local, sin API externa ni costes por uso
La filosofía de pdf-brain es clara: local-first.
Todo se ejecuta en la máquina del usuario:
- No hay llamadas a APIs de terceros.
- No hay costes por tokens ni cuotas mensuales.
- Los PDFs y sus embeddings se guardan en el propio disco.
Por defecto, la biblioteca se almacena en:
~/Documents/.pdf-library/
├── library.db # Base de datos PGlite (vectores, FTS, metadatos)
└── downloads/ # PDFs descargados desde URLs
Lenguaje del código: PHP (php)Esto lo convierte en una opción especialmente atractiva para equipos WordPress que manejan documentación interna sensible, borradores de ebooks, manuales técnicos o materiales de cliente que no quieren subir a servicios cloud de terceros para “hacer búsquedas inteligentes”.
Instalación y requisitos: Node, npm y Ollama
La instalación es sencilla para cualquiera acostumbrado a entornos de desarrollo:
npm install pdf-brain
Para la parte semántica, pdf-brain se apoya en Ollama, que es quien genera los embeddings:
brew install ollama
ollama pull mxbai-embed-large
Las variables de entorno permiten ajustar el comportamiento:
PDF_LIBRARY_PATH– ruta de la biblioteca (por defecto~/Documents/.pdf-library).OLLAMA_HOST– endpoint de la API de Ollama (por defectohttp://localhost:11434).OLLAMA_MODEL– modelo de embeddings a utilizar (por defectomxbai-embed-large).
Un CLI sencillo: añadir, etiquetar y buscar PDFs
El uso se centra en una serie de comandos de consola muy directos. Algunos ejemplos:
Añadir PDFs a la biblioteca
# Añadir un PDF local
npx pdf-brain add /ruta/al/documento.pdf
# Añadir un PDF desde URL
npx pdf-brain add https://example.com/paper.pdf
# Añadir con etiquetas
npx pdf-brain add /ruta/al/documento.pdf --tags "ai,agents"
Lenguaje del código: PHP (php)Buscar contenido
- Búsqueda semántica (por significado, usando vectores):
npx pdf-brain search "patrones de context engineering"
Lenguaje del código: JavaScript (javascript)- Búsqueda full-text (sin embeddings, por texto):
npx pdf-brain search "context engineering" --fts
Lenguaje del código: JavaScript (javascript)Gestión de la biblioteca
# Listar todos los documentos
npx pdf-brain list
# Listar por etiqueta
npx pdf-brain list --tag ai
# Ver detalles de un documento
npx pdf-brain get "document-title"
# Eliminar un documento
npx pdf-brain remove "document-title"
# Actualizar etiquetas
npx pdf-brain tag "document-title" "nuevas,etiquetas,aqui"
# Ver estadísticas de la biblioteca
npx pdf-brain stats
# Comprobar el estado de Ollama
npx pdf-brain check
Lenguaje del código: PHP (php)Para un entorno editorial basado en WordPress —por ejemplo, una revista técnica o un blog corporativo— esto permite buscar rápidamente entre estudios, referencias y documentación antes de redactar o actualizar contenidos online.
Cómo funciona por dentro: PGlite + pgvector + embeddings
Aunque para el usuario todo se reduce a comandos CLI, por debajo pdf-brain combina varios componentes modernos del ecosistema de IA y bases de datos:
- Extracción de texto
El contenido de los PDFs se extrae mediante pypdf y se divide en fragmentos (chunks) de unas 512 “tokens” con solapamiento. Esto hace que las búsquedas sean más precisas y que los resultados apunten a trozos relevantes del documento. - Embeddings con Ollama
Cada fragmento se convierte en un vector de 1.024 dimensiones utilizando el modelomxbai-embed-largeservido por Ollama. Esos vectores son los que permiten la búsqueda semántica. - Almacenamiento en PGlite + pgvector
Todo se guarda en una base de datos PGlite (Postgres embebido en local), con soporte para pgvector y un índice HNSW para acelerar la búsqueda por similitud de coseno. Además, se combina con Full-Text Search (FTS) para soportar búsquedas híbridas (texto + vectores).
El esquema conceptual es:
PDF → extracción de texto → chunks → embeddings (Ollama) → PGlite + pgvector
↘ FTS
El resultado: se puede preguntar en lenguaje natural por ideas, conceptos o patrones, y pdf-brain devuelve los fragmentos de PDFs más cercanos semánticamente, no solo los que contienen una palabra exacta.
Integración con OpenCode y flujos de desarrollo
Un detalle interesante para desarrolladores es la integración nativa con OpenCode, el agente de IA para terminal. El repositorio de pdf-brain incluye un ejemplo de herramienta (pdf-brain.ts) que se puede colocar en:
~/.config/opencode/tool/pdf-brain.ts
Lenguaje del código: JavaScript (javascript)Con este archivo, OpenCode puede invocar comandos como add, search, list o stats directamente como herramientas, lo que permite:
- Diseñar agentes que busquen automáticamente en la biblioteca de PDFs mientras se revisa o escribe código.
- Tener un “copiloto documental” que consulte papers, documentación técnica o manuales sin salir del terminal.
Aunque no hay integración directa con WordPress, es fácil imaginar flujos de trabajo donde pdf-brain se use en local para documentación interna y WordPress como capa de publicación hacia el exterior.
¿Por qué es relevante para el ecosistema WordPress?
Para un sitio de noticias o un entorno editorial basado en WordPress, pdf-brain aporta varias ventajas indirectas:
- Equipos de redacción o desarrollo pueden centralizar su biblioteca de PDFs técnicos (whitepapers, manuales, guías de APIs, RFC, etc.) sin depender de servicios externos.
- Los redactores pueden localizar rápidamente información precisa antes de publicar, gracias a la búsqueda semántica.
- Se favorece un enfoque local-first y respetuoso con la privacidad, cada vez más valorado entre profesionales y empresas europeas.
En tiempos de IA generativa en la nube y servicios de suscripción, pdf-brain es un recordatorio de que todavía se puede construir herramientas útiles, modernas y potentes que corren íntegramente en local, sin dejar de lado la funcionalidad avanzada.
Preguntas frecuentes sobre pdf-brain
¿Es pdf-brain una herramienta específica para WordPress?
No. pdf-brain es una herramienta general de línea de comandos para gestionar y buscar PDFs en local. Sin embargo, encaja muy bien en flujos de trabajo de redacción, documentación y desarrollo que luego publican contenidos en WordPress.
¿Necesito conocimientos avanzados para usar pdf-brain?
Hace falta estar cómodo con la terminal y tener Node/npm instalado. Además, para la búsqueda semántica es necesario configurar Ollama. No es una herramienta “para todos los públicos”, pero cualquier desarrollador o administrador técnico puede ponerla en marcha sin grandes complicaciones.
¿Qué ventajas ofrece frente a servicios online de gestión de PDFs?
La principal ventaja es que todo se ejecuta en local: no hay subida de PDFs a terceros, no hay costes de API y el control de los datos es total. A cambio, el usuario debe mantener su entorno (Ollama, Node, biblioteca) por su cuenta.
¿Se puede usar pdf-brain en un equipo de redacción o sólo a nivel individual?
Por defecto, la biblioteca se guarda en la carpeta de usuario, pero puede ubicarse en rutas compartidas (por ejemplo, mediante sincronización en iCloud u otros sistemas) configurando PDF_LIBRARY_PATH. Cada equipo puede adaptar la distribución según sus necesidades internas.
