knowmanPregunta a tus notas. Obtén el archivo y las líneas.
knowman responde solo con tus notas Markdown y muestra el archivo y las líneas de cada respuesta. Si las notas no contienen la respuesta, lo dice.
git clone https://github.com/rdorta27/knowman
cd knowman
./install.shNecesita Docker. Detalles más abajo.
Qué resuelve
- Encuentra qué decidiste y dónde lo escribiste.
- Responde una pregunta con notas de reuniones, runbooks o documentación interna.
- Da a un asistente de IA una fuente que debe citar.
En qué se diferencia
grep
grep busca los caracteres que escribes. knowman busca el significado de tu pregunta.
Un chat con archivos pegados
Un chat responde aunque las notas no digan nada. knowman imprime No evidence found for that query. y no llama a ningún modelo de lenguaje.
La búsqueda de un wiki
La búsqueda de un wiki lista páginas. knowman devuelve el pasaje y su rango de líneas.
La idea en tres partes
Concepto central
knowman es un programa que lee una carpeta de notas Markdown. Responde tu pregunta con pasajes de esas notas. Cada pasaje indica su archivo y su rango de líneas.
Analogía física
Imagina un bibliotecario que atiende una sola estantería. Le haces una pregunta. Te entrega las páginas que coinciden, con el libro y el número de línea. Si ninguna página coincide, te lo dice y no te entrega nada.
Mecánica técnica
- Observador detecta cada archivo
.mdañadido, editado o borrado y crea una tarea. - Procesador toma una tarea a la vez y la ejecuta.
- Fragmentador divide cada nota en las líneas en blanco y registra el rango de líneas.
- Ollama convierte cada fragmento en un vector.
- Postgres con pgvector guarda los fragmentos y los vectores.
- Búsqueda convierte tu pregunta en un vector y devuelve los fragmentos más cercanos.
- Filtro de distancia descarta los fragmentos a más de 0.5. Si no queda ninguno, imprime
No evidence found for that query.
Cómo se ve
$ knowman search "why Postgres"
decision-log.md:L5-L5
We chose Postgres with the pgvector extension for the vector store.
architecture-notes.md:L5-L6
The store module is the only part of the codebase that speaks SQL.
Every other module calls its functions instead of touching Postgres directly.
decision-log.md:L1-L3
# Decision log
## Database engine
$ knowman search "capital of mongolia"
No evidence found for that query.Cada resultado es un pasaje con su rango de líneas, del más cercano al más lejano. Con un modelo de lenguaje configurado, knowman ask redacta prosa a partir de esos mismos pasajes. La recuperación no necesita modelo de lenguaje. El programa imprime sus mensajes en inglés en todos los idiomas del sitio. Fuente: core/README.md.
Qué hay dentro
Recuperación con citas
Los fragmentos conservan su rango de líneas, así que una cita apunta a las líneas exactas. Si nada cae dentro del umbral de distancia, es un negativo explícito.
Índice actualizado
Un observador convierte las notas añadidas, editadas y borradas en tareas, y un procesador las indexa.
Cuatro puntos de entrada
Una CLI, una API HTTP, un servidor MCP con search y ask, y un panel de monitoreo.
Funciona en local
Postgres con pgvector y Ollama para los embeddings. No hace falta clave de API; se puede configurar Claude, OpenAI o Grok para las respuestas.
Recuperación medida
knowman eval puntúa 25 preguntas etiquetadas: 100% (25/25). El conjunto es pequeño. Detecta regresiones; no es un benchmark.
Mira cada parte y el archivo que la implementa en la página de arquitectura.
Límites
- Solo Markdown. knowman no es un editor de notas ni un wiki. Lee una carpeta que ya es tuya.
- Los embeddings necesitan Ollama. Un modelo de embeddings nuevo exige reindexar todo.
- Los modelos locales pequeños dudan. La respuesta escrita vale lo que vale el modelo que configures.
- La API está abierta por defecto. Activa
API_TOKENy el límite de tasa antes de exponerla más allá de localhost.
Preguntas frecuentes
¿Mis notas salen de mi máquina?
No, por defecto. Postgres y Ollama escuchan en 127.0.0.1. Si configuras Claude, OpenAI o Grok para las respuestas, knowman envía tu pregunta y los pasajes citados a ese proveedor.
¿Necesita una clave de API?
No. La recuperación, las citas y la evaluación funcionan sin clave. Solo las respuestas de Claude, OpenAI y Grok la necesitan.
¿Necesita una GPU?
No. Si la máquina tiene /dev/dri, Ollama usa Vulkan. Si no, todo corre en la CPU.
¿Qué pasa si cambio el modelo de embeddings?
Ejecuta db-init y reindexa todas las notas. Un modelo distinto produce un espacio vectorial distinto.
Instalar
git clone https://github.com/rdorta27/knowman
cd knowman
./install.sh
docker compose exec api knowman search "why Postgres"Necesita Docker y el plugin de Compose. En Arch, ./install.sh --mode native corre sin Docker. El script imprime los comandos de lo que falta y se detiene en vez de instalarlo.
Usa tus propias notas
cp .env.example .env
# en .env: CORPUS_PATH=/notes
# en docker-compose.yml, en api > volumes: /home/you/notes:/notes
docker compose up -d
docker compose exec api knowman ingestTras este primer índice, el observador actualiza el índice cuando añades, editas o borras un archivo .md. Abre http://localhost:8000/dashboard para ver el índice, la cola de tareas y la última evaluación. Fuente: core/README.md.