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:
- Solo NoteBrain — Sin Búsqueda Genérica de Archivos: Nunca uses
grep,find,lso 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. Tratanotebraincomo la única interfaz al contenido de la bóveda. Si un comandonotebrainparece no devolver nada útil, refina la consultanotebrain(diferente redacción,--limitmás amplio, comando alternativo) en lugar de recurrir a una búsqueda genérica de archivos. - 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 clavessnake_caselimpias (note_slug,title,file_path,score,tags,text). - 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 dejq. - Recuperar Notas Completas (
notebrain get): Cuandosearchdevuelve un fragmento de nota relevante, usanotebrain 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 acaten el archivo subyacente de la bóveda —getreconstruye correctamente las notas fragmentadas y respeta el estado indexado de la bóveda. - Recuperar Contenido para Síntesis (
--include-text): Por defecto,searchy 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 campotextdevuelto contiene markdown enriquecido con bloques de código preservados, por lo que los fragmentos de código son copiables. - Resolución de Binario y Comillas: En entornos de desarrollo, ejecuta
./notebrainsinotebrainno 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. - 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. - Ingesta Automatizada: La ingesta se maneja mediante programadores del SO (cron/timers systemd cada 3 horas). No necesitas ejecutar
ingestmanualmente 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 Usuario | Comando | Por qué y Cómo Usarlo |
|---|---|---|
| "¿Qué dicen mis notas sobre X?" | search | Realiza 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" | get | Recupera y reconstruye el texto completo de la nota y metadatos por slug o ruta de archivo. |
| "¿Qué enlaza directamente a esta nota?" | backlinks | Encuentra referencias explícitas [[wikilink]] que apuntan a la nota objetivo. |
| "¿Qué está estructuralmente cerca en el grafo?" | connections | Ejecuta 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?" | hidden | Descubre notas no enlazadas pero semánticamente similares. Muy valioso para descubrir puentes conceptuales. |
| "Encuentra conceptos relacionados con X centrados en la nota Y" | boosted | Combina similitud vectorial con proximidad en el grafo a una nota --seed. |
| "¿Qué notas comparten etiquetas con X?" | tags | Analiza superposición de etiquetas. Devuelve cadenas de etiquetas limpias en el array tags. |
| "¿Está la base de datos actualizada?" | stats | Muestra conteos de colecciones (chunks, links). Soporta --format=json y --jsonpath. |
| "Indexar o reindexar la bóveda" | ingest | Sincroniza 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
| Bandera | Propósito | Por Defecto |
|---|---|---|
--top-k N | Máximo de fragmentos a retener por nota. Evita que una nota larga domine los resultados preservando profundidad. | 3 |
--context-window N | Obtiene ±N fragmentos adyacentes alrededor de cada coincidencia y completa el array context. Usa 1 o 2 para la mayoría de tareas. | 0 |
--has-tasks | Solo devuelve fragmentos que contengan listas de tareas (casillas de verificación). | desactivado |
--has-code | Solo devuelve fragmentos que contengan bloques de código con delimitadores. | desactivado |
--section | Filtra resultados a fragmentos bajo una ruta de encabezado específica (ej., "Arquitectura > Componentes"). | — |
--limit N | Máximo total de resultados a devolver. | 10 |
--tag "TagName" | Filtra o busca por nombre de etiqueta. | — |
--min-score F | Suprime resultados por debajo de esta puntuación de similitud (0–1). | 0 |
Cuándo usar --context-window vs notebrain get
- Usa
--context-window 1cuando 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 getcuando 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..."
]
}
]
}
| Campo | Presente Cuando | Descripción |
|---|---|---|
note_slug | Siempre | Identificador seguro para URL derivado de la ruta del archivo. |
title | Siempre | Título de la nota desde frontmatter o nombre de archivo. |
file_path | Siempre | Ruta relativa dentro de la bóveda. |
score | Siempre | Puntuación de similitud (0–1) para búsqueda; conteo de saltos para conexiones. |
chunk_index | Búsqueda, hidden, boosted | Qué fragmento de la nota coincidió (indexado desde 0). |
tags | Cuando la nota tiene etiquetas | Array de cadenas de etiquetas. |
heading_path | Cuando el fragmento está bajo un encabezado | Ruta de breadcrumb como "Sección > Subsección". |
text | Cuando se pasa --include-text | El texto markdown completo del fragmento coincidente, con bloques de código preservados. |
context | Cuando --context-window N > 0 | Array de ±N fragmentos de texto adyacentes, ordenados por índice de fragmento. |
extra | Conexiones, tags, boosted | Informació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:
- Busca con contexto — ejecuta
searchcon--context-window 1 --include-text --top-k 2para 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. - Obtén backlinks para cada semilla — ejecuta
notebrain backlinks <seed-slug> --format json --include-textpara 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. - Recorre conexiones hacia afuera — ejecuta
notebrain connections <seed-slug> --hops 2 --format jsonpara 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. - Verifica enlaces ocultos — ejecuta
notebrain hidden <seed-slug> --include-text --context-window 1para 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. - Sintetiza, no solo enumeres — combina la(s) nota(s) semilla, sus backlinks, su vecindario de
connectionsy cualquier resultadohiddenen 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