Communitygithub.com

nmdra/notebrain-cli

NoteBrain es una herramienta CLI de alto rendimiento en Go que indexa tu bóveda de Obsidian en una base de datos vectorial local ChromaDB, permitiendo a los agentes de IA explorar inteligentemente tu base de conocimiento personal.

¿Qué es notebrain-cli?

NoteBrain es una herramienta de línea de comandos (CLI) escrita en Go que indexa el contenido de una bóveda de Obsidian en una base de datos vectorial ChromaDB local, proporcionando a los agentes de IA capacidades avanzadas de búsqueda semántica, recorrido de grafos y descubrimiento de relaciones ocultas entre notas. Su utilidad principal radica en que los agentes pueden recuperar y razonar sobre notas personales con contexto, utilizando comandos especializados como `search`, `get`, `backlinks`, `connections`, `hidden` y `tags`, en lugar de depender de búsquedas genéricas en el sistema de archivos. NoteBrain funciona de forma no interactiva usando el flag `--format json` para evitar bloqueos en sesiones automatizadas, y soporta encadenamiento de comandos con `--jsonpath` para extraer campos específicos de forma limpia. Está diseñado para entornos de desarrollo sin dependencias externas como Docker, y se integra con programadores del sistema operativo (cron/systemd) para la ingesta automatizada de notas cada 3 horas. La herramienta es especialmente valiosa para agentes porque implementa un flujo de recuperación multi-señal (búsqueda → backlinks → conexiones → ocultos) que combina la estructura explícita de la bóveda con similitudes semánticas implícitas, permitiendo respuestas más profundas y contextualizadas.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add nmdra/notebrain-cli

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Habilidad CLI de NoteBrain para Agentes de IA

NoteBrain es una herramienta CLI de alto rendimiento en Go que indexa una bóveda de Obsidian en una base de datos vectorial ChromaDB local. Proporciona búsqueda semántica, recorrido de grafos, descubrimiento de backlinks, hallazgo de relaciones ocultas, recuperación completa de notas y análisis de etiquetas en notas markdown.

Principios Fundamentales de Ejecución y Razón de Ser

Para operar de manera eficiente y evitar tokens desperdiciados o sesiones bloqueadas, sigue estos principios fundamentales:

  1. Solo NoteBrain — Sin Búsqueda Genérica de Archivos: Nunca uses grep, find, ls o scripts shell ad-hoc contra los archivos markdown de la bóveda para responder la pregunta del usuario. Los comandos de NoteBrain están diseñados específicamente sobre la base de datos vectorial y de grafos indexada y siempre producirán resultados de mayor calidad y más relevantes que una búsqueda de texto a nivel de sistema de archivos. Trata notebrain como la única interfaz al contenido de la bóveda. Si un comando notebrain parece no devolver nada útil, refina la consulta notebrain (diferente redacción, --limit más amplio, comando alternativo) en lugar de recurrir a una búsqueda genérica de archivos.
  2. Ejecución No Interactiva (--format json): Por defecto, NoteBrain inicia una TUI (Bubble Tea) de terminal interactiva diseñada para navegación humana. Esta interfaz interactiva bloqueará las sesiones de agentes automatizados. Siempre especifica --format json (o --format ndjson / --format tsv) en los comandos de consulta para recibir datos estructurados y analizables de inmediato. Ten en cuenta que todos los campos del sobre JSON usan claves snake_case limpias (note_slug, title, file_path, score, tags, text).
  3. Encadenamiento de Comandos para Agentes de IA (--jsonpath): Siempre que solo necesites campos específicos (como extraer slugs de notas o texto para pasar a comandos posteriores), usa --jsonpath (ej., --jsonpath="$.results[0].note_slug" o --jsonpath="$.results[*].note_slug"). Cuando se usa --jsonpath, los valores escalares se emiten como cadenas sin comillas y las matrices imprimen cada elemento en una nueva línea, permitiendo una extracción fluida de variables de shell sin necesidad de jq.
  4. Recuperar Notas Completas (notebrain get): Cuando search devuelve un fragmento de nota relevante, usa notebrain get <note-slug-or-path> en lugar de adivinar índices de fragmentos para recuperar el texto completo y reconstruido de la nota markdown, uniendo todos sus fragmentos indexados. Nunca recurras a cat en el archivo subyacente de la bóveda — get reconstruye correctamente las notas fragmentadas y respeta el estado indexado de la bóveda.
  5. Recuperar Contenido para Síntesis (--include-text): Por defecto, search y los comandos de recorrido devuelven sobres de metadatos ligeros (títulos, rutas de archivos, etiquetas, puntuaciones de similitud). Siempre que tu tarea requiera resumir o razonar sobre fragmentos individuales directamente desde los resultados de búsqueda, añade --include-text. El campo text devuelto contiene markdown enriquecido con bloques de código preservados, por lo que los fragmentos de código son copiables.
  6. Resolución de Binario y Comillas: En entornos de desarrollo, ejecuta ./notebrain si notebrain no está en el PATH del sistema. Los títulos de las notas a menudo contienen espacios o corchetes ("Planificación Q3 [Borrador]"), por lo que siempre encapsula los títulos de notas, etiquetas y consultas de búsqueda entre comillas dobles.
  7. Almacenamiento Persistente Integrado: NoteBrain se ejecuta exclusivamente como una base de datos integrada (~/.notebrain/chroma). No se requieren ni se admiten contenedores Docker independientes de ChromaDB ni servidores HTTP.
  8. Ingesta Automatizada: La ingesta se maneja mediante programadores del SO (cron/timers systemd cada 3 horas). No necesitas ejecutar ingest manualmente antes de las consultas a menos que el usuario solicite explícitamente un reíndice inmediato después de editar notas.

Guía de Selección de Comandos

Selecciona el comando especializado adaptado al objetivo analítico del usuario:

Intención del UsuarioComandoPor qué y Cómo Usarlo
"¿Qué dicen mis notas sobre X?"searchRealiza búsqueda de similitud vectorial en todos los fragmentos de notas. Usa --tag="TagName" para filtrar por etiqueta.
"Lee el contenido completo de la nota Y"getRecupera y reconstruye el texto completo de la nota y metadatos por slug o ruta de archivo.
"¿Qué enlaza directamente a esta nota?"backlinksEncuentra referencias explícitas [[wikilink]] que apuntan a la nota objetivo.
"¿Qué está estructuralmente cerca en el grafo?"connectionsEjecuta búsqueda en anchura (BFS) sobre wikilinks hasta --hops N. Mantén --hops 1 o --hops 2 para evitar explosión exponencial.
"¿Qué está relacionado en significado pero NO enlazado?"hiddenDescubre notas no enlazadas pero semánticamente similares. Muy valioso para descubrir puentes conceptuales.
"Encuentra conceptos relacionados con X centrados en la nota Y"boostedCombina similitud vectorial con proximidad en el grafo a una nota --seed.
"¿Qué notas comparten etiquetas con X?"tagsAnaliza superposición de etiquetas. Devuelve cadenas de etiquetas limpias en el array tags.
"¿Está la base de datos actualizada?"statsMuestra conteos de colecciones (chunks, links). Soporta --format=json y --jsonpath.
"Indexar o reindexar la bóveda"ingestSincroniza notas markdown en ChromaDB. La reingesta es idempotente.

Sintaxis de Comandos

Búsqueda Semántica y Filtrado por Etiquetas (search)

notebrain search "reconciliación kubernetes" --tag="Kubernetes" --limit 5 --format json --include-text

Banderas clave de búsqueda

BanderaPropósitoPor Defecto
--top-k NMáximo de fragmentos a retener por nota. Evita que una nota larga domine los resultados preservando profundidad.3
--context-window NObtiene ±N fragmentos adyacentes alrededor de cada coincidencia y completa el array context. Usa 1 o 2 para la mayoría de tareas.0
--has-tasksSolo devuelve fragmentos que contengan listas de tareas (casillas de verificación).desactivado
--has-codeSolo devuelve fragmentos que contengan bloques de código con delimitadores.desactivado
--sectionFiltra resultados a fragmentos bajo una ruta de encabezado específica (ej., "Arquitectura > Componentes").—
--limit NMáximo total de resultados a devolver.10
--tag "TagName"Filtra o busca por nombre de etiqueta.—
--min-score FSuprime resultados por debajo de esta puntuación de similitud (0–1).0

Cuándo usar --context-window vs notebrain get

  • Usa --context-window 1 cuando necesites contexto circundante ligero para múltiples resultados de búsqueda a la vez. Esto es eficiente — una llamada de búsqueda te da tanto los fragmentos coincidentes como sus vecinos, suficiente para entender el contexto local sin obtener notas completas.
  • Usa notebrain get cuando necesites el texto completo de la nota reconstruido — por ejemplo, cuando el usuario pida leer o resumir una nota específica, o cuando necesites ver la estructura completa del documento.

El enfoque de ventana es especialmente valioso al procesar muchos resultados de búsqueda, porque obtener notas completas para cada resultado sería derrochador. Obtén primero la ventana, luego selectivamente usa get solo para las notas que realmente necesiten contexto completo.

Recuperación Completa de Notas (get)

notebrain get "02areaskubernetesckadkubernetes-native-applications" --format json

Conexiones de Grafo y Enlaces Ocultos (connections, hidden)

notebrain connections "Sistemas Distribuidos" --hops 2 --format json
notebrain hidden "Microservicios" --limit 5 --format json --include-text

Esquema de Salida JSON

Entender la estructura de resultados es esencial para la extracción confiable de campos. Cada comando de consulta envuelve resultados en este sobre:

{
  "command": "search",
  "query": "Búsqueda Semántica: \"kubernetes\"",
  "total": 3,
  "results": [
    {
      "note_slug": "02areaskubernetes-architecture",
      "title": "Arquitectura de Kubernetes",
      "file_path": "02.Areas/Kubernetes/Architecture.md",
      "score": 0.82,
      "chunk_index": 2,
      "tags": ["Kubernetes", "DevOps"],
      "heading_path": "Componentes > Plano de Control",
      "text": "El servidor API valida y configura...",
      "context": [
        "Texto del fragmento anterior sobre almacenamiento etcd...",
        "El servidor API valida y configura...",
        "El planificador observa Pods recién creados..."
      ]
    }
  ]
}
CampoPresente CuandoDescripción
note_slugSiempreIdentificador seguro para URL derivado de la ruta del archivo.
titleSiempreTítulo de la nota desde frontmatter o nombre de archivo.
file_pathSiempreRuta relativa dentro de la bóveda.
scoreSiemprePuntuación de similitud (0–1) para búsqueda; conteo de saltos para conexiones.
chunk_indexBúsqueda, hidden, boostedQué fragmento de la nota coincidió (indexado desde 0).
tagsCuando la nota tiene etiquetasArray de cadenas de etiquetas.
heading_pathCuando el fragmento está bajo un encabezadoRuta de breadcrumb como "Sección > Subsección".
textCuando se pasa --include-textEl texto markdown completo del fragmento coincidente, con bloques de código preservados.
contextCuando --context-window N > 0Array de ±N fragmentos de texto adyacentes, ordenados por índice de fragmento.
extraConexiones, tags, boostedInformación específica del comando (ej., "2 salto(s)", "graph-boosted").

Profundizando la Calidad de las Respuestas: Recuperación Multi-Señal

Antes de responder cualquier pregunta del tipo "¿qué sé sobre X?" o "resume mis notas sobre X", no te limites a una sola llamada search. Los resultados de búsqueda por sí solos solo muestran fragmentos que están semánticamente cerca de la consulta — se pierden el contexto circundante que el usuario ha construido deliberadamente en su grafo. Siempre amplía la imagen:

  1. Busca con contexto — ejecuta search con --context-window 1 --include-text --top-k 2 para obtener los fragmentos más relevantes con sus párrafos circundantes. Esto te da tanto precisión (el fragmento coincidente) como contexto (lo que viene antes y después) en una sola llamada.
  2. Obtén backlinks para cada semilla — ejecuta notebrain backlinks <seed-slug> --format json --include-text para extraer cada nota que enlaza explícitamente a la semilla. Estas son notas que el usuario ha curado manualmente como relacionadas, por lo que su contenido es casi siempre de alta señal y debe ponderarse fuertemente en tu síntesis.
  3. Recorre conexiones hacia afuera — ejecuta notebrain connections <seed-slug> --hops 2 --format json para mapear el vecindario del grafo local alrededor de la semilla. Esto revela notas estructuralmente adyacentes (ej., notas a dos enlaces de distancia) que pueden no aparecer en una búsqueda vectorial pura pero son parte del mismo grupo de conocimiento.
  4. Verifica enlaces ocultos — ejecuta notebrain hidden <seed-slug> --include-text --context-window 1 para detectar notas conceptualmente relacionadas que el usuario aún no ha enlazado. Menciónalas explícitamente al usuario como posibles enlaces faltantes en su bóveda, ya que este es uno de los diferenciadores más valiosos de NoteBrain sobre la búsqueda simple.
  5. Sintetiza, no solo enumeres — combina la(s) nota(s) semilla, sus backlinks, su vecindario de connections y cualquier resultado hidden en una sola respuesta coherente, distinguiendo lo que está explícitamente enlazado (alta confianza) de lo que solo es semánticamente similar (vale la pena verificar de nuevo).

Esta cadena search → backlinks → connections → hidden debe ser el flujo de trabajo predeterminado para cualquier pregunta exploratoria no trivial, no solo una llamada search, porque muestra tanto la estructura explícita que el usuario construyó como la estructura implícita que NoteBrain puede detectar.

Pipeline de Encadenamiento para Agentes de IA

# 1. Busca con contexto circundante — top-k mantiene resultados diversos entre notas
SLUG=$(notebrain search "backpressure en message broker" --limit 3 --top-k 2 \
  --context-window 1 --include-text --format json \
  --jsonpath="$.results[0].note_slug")

# 2. Obtén el texto completo reconstruido de la nota para el mejor resultado
notebrain get "$SLUG" --jsonpath="$.text"

# 3. Encuentra todos los slugs de notas que enlazan a esta nota, con su contenido,
#    para fundamentar la respuesta en lo que el usuario ha enlazado explícitamente
notebrain backlinks "$SLUG" --format json --include-text

# 4. Recorre el vecindario del grafo para mostrar notas estructuralmente adyacentes
#    que la búsqueda vectorial sola pasaría por alto
notebrain connections "$SLUG" --hops 2 --format json

Skills relacionados