Habilidade NoteBrain CLI para Agentes de IA
NoteBrain é uma ferramenta CLI em Go de alto desempenho que indexa um cofre Obsidian em um banco de dados vetorial ChromaDB local. Ela fornece busca semântica, travessia de grafo, descoberta de backlinks, localização de relacionamentos ocultos, recuperação completa de notas e análise de tags em notas markdown.
Princípios Fundamentais de Execução & Racional
Para operar de forma eficiente e evitar tokens desperdiçados ou sessões travadas, siga estes princípios fundamentais:
- Apenas NoteBrain — Sem Busca Genérica em Arquivos: Nunca use
grep,find,lsou scripts shell ad-hoc contra os arquivos markdown do cofre para responder à pergunta do usuário. Os comandos do NoteBrain são criados especificamente sobre o banco de dados vetorial e de grafo indexado e sempre produzirão resultados de qualidade superior e mais relevantes do que uma busca textual no sistema de arquivos. Tratenotebraincomo a única interface para o conteúdo do cofre. Se um comandonotebrainparecer não retornar nada útil, refine a consultanotebrain(fraseado diferente,--limitmaior, comando alternativo) em vez de recorrer a uma busca genérica em arquivos. - Execução Não Interativa (
--format json): Por padrão, o NoteBrain inicia uma TUI de terminal interativa (Bubble Tea) projetada para navegação humana. Esta interface interativa travará sessões de agente automatizadas. Sempre especifique--format json(ou--format ndjson/--format tsv) em comandos de consulta para receber dados estruturados e analisáveis imediatamente. Observe que todos os campos do envelope JSON usam chavessnake_case(note_slug,title,file_path,score,tags,text). - Encadeamento de Comandos para Agentes de IA (
--jsonpath): Sempre que você precisar apenas de campos específicos (como extrair slugs de notas ou texto para canalizar em comandos subsequentes), use--jsonpath(por exemplo,--jsonpath="$.results[0].note_slug"ou--jsonpath="$.results[*].note_slug"). Quando--jsonpathé usado, valores escalares são gerados como strings simples sem aspas e arrays imprimem cada item em uma nova linha, permitindo extração perfeita de variáveis de shell sem precisar dejq. - Recuperar Notas Completas (
notebrain get): Quandosearchretornar um trecho de nota relevante, usenotebrain get <note-slug-ou-caminho>em vez de adivinhar índices de trecho para recuperar o texto completo e reconstruído da nota markdown, unido a partir de todos os seus trechos indexados. Nunca usecatno arquivo do cofre subjacente —getreconstrói notas fragmentadas corretamente e respeita o estado indexado do cofre. - Recuperar Conteúdo para Síntese (
--include-text): Por padrão,searche comandos de travessia retornam envelopes de metadados leves (títulos, caminhos de arquivo, tags, pontuações de similaridade). Sempre que sua tarefa exigir resumir ou raciocinar sobre trechos individuais diretamente dos resultados da busca, adicione--include-text. O campotextretornado contém markdown rico com blocos de código preservados, para que trechos de código possam ser copiados e colados. - Resolução Binária e Citação: Em ambientes de desenvolvimento, execute
./notebrainsenotebrainnão estiver no PATH do sistema. Títulos de notas geralmente contêm espaços ou colchetes ("Q3 Planning [Draft]"), portanto, sempre encapsule títulos de notas, tags e consultas de busca entre aspas duplas. - Armazenamento Persistente Embutido: NoteBrain é executado exclusivamente como um banco de dados embutido (
~/.notebrain/chroma). Nenhum contêiner Docker ChromaDB independente ou servidores HTTP são necessários ou suportados. - Ingestão Automatizada: A ingestão é tratada por agendadores do SO (cron/systemd timers a cada 3 horas). Você não precisa executar
ingestmanualmente antes das consultas, a menos que o usuário solicite explicitamente uma reindexação imediata após editar notas.
Guia de Seleção de Comandos
Selecione o comando especializado adequado ao objetivo analítico do usuário:
| Intenção do Usuário | Comando | Porquê e Como Usar |
|---|---|---|
| "O que minhas notas dizem sobre X?" | search | Realiza busca por similaridade vetorial em todos os trechos de notas. Use --tag="TagName" para filtrar por tag. |
| "Leia o conteúdo completo da nota Y" | get | Recupera e reconstrói o texto completo da nota e metadados por slug ou caminho de arquivo. |
| "O que está diretamente linkado a esta nota?" | backlinks | Encontra referências explícitas [[wikilink]] apontando para a nota alvo. |
| "O que está estruturalmente próximo no grafo?" | connections | Executa busca em largura (BFS) sobre wikilinks até --hops N. Mantenha --hops 1 ou --hops 2 para evitar explosão exponencial. |
| "O que é relacionado em significado, mas NÃO linkado?" | hidden | Descobre notas semanticamente similares, mas não linkadas. Altamente valioso para descobrir pontes conceituais. |
| "Encontre conceitos relacionados a X centrados na nota Y" | boosted | Combina similaridade vetorial com proximidade no grafo a uma nota --seed. |
| "Quais notas compartilham tags com X?" | tags | Analisa sobreposição de tags. Retorna strings de tags limpas no array tags. |
| "O banco de dados está atualizado?" | stats | Gera contagens de coleção (chunks, links). Suporta --format=json e --jsonpath. |
| "Indexar ou reindexar o cofre" | ingest | Sincroniza notas markdown no ChromaDB. Reingestão é idempotente. |
Sintaxe dos Comandos
Busca Semântica & Filtragem por Tag (search)
notebrain search "reconciliação kubernetes" --tag="Kubernetes" --limit 5 --format json --include-text
Principais flags de busca
| Flag | Propósito | Padrão |
|---|---|---|
--top-k N | Máximo de trechos a reter por nota. Evita que uma nota longa domine os resultados, preservando profundidade. | 3 |
--context-window N | Busca ±N trechos adjacentes ao redor de cada correspondência e preenche o array context. Use 1 ou 2 na maioria das tarefas. | 0 |
--has-tasks | Retorna apenas trechos que contêm listas de tarefas (checkboxes). | desligado |
--has-code | Retorna apenas trechos que contêm blocos de código encapsulados. | desligado |
--section | Filtra resultados para trechos sob um caminho de cabeçalho específico (ex.: "Arquitetura > Componentes"). | — |
--limit N | Número máximo total de resultados a retornar. | 10 |
--tag "TagName" | Filtra ou busca por nome de tag. | — |
--min-score F | Suprime resultados abaixo desta pontuação de similaridade (0–1). | 0 |
Quando usar --context-window vs notebrain get
- Use
--context-window 1quando você precisar de contexto leve ao redor de múltiplos resultados de busca de uma vez. É eficiente — uma chamada de busca fornece tanto os trechos correspondentes quanto seus vizinhos, o suficiente para entender o contexto local sem buscar notas inteiras. - Use
notebrain getquando você precisar do texto completo da nota reconstruída — por exemplo, quando o usuário pedir para ler ou resumir uma nota específica, ou quando você precisar ver a estrutura completa do documento.
A abordagem de janela é especialmente valiosa ao processar muitos resultados de busca, porque buscar notas completas para cada resultado seria um desperdício. Busque a janela primeiro, depois seletivamente use get apenas nas notas que realmente precisam de contexto completo.
Recuperação Completa de Notas (get)
notebrain get "02areaskubernetesckadkubernetes-native-applications" --format json
Conexões no Grafo & Links Ocultos (connections, hidden)
notebrain connections "Sistemas Distribuídos" --hops 2 --format json
notebrain hidden "Microsserviços" --limit 5 --format json --include-text
Esquema de Saída JSON
Entender a estrutura do resultado é essencial para extração confiável de campos. Cada comando de consulta envolve os resultados neste envelope:
{
"command": "search",
"query": "Busca Semântica: \"kubernetes\"",
"total": 3,
"results": [
{
"note_slug": "02areaskubernetes-architecture",
"title": "Arquitetura Kubernetes",
"file_path": "02.Areas/Kubernetes/Architecture.md",
"score": 0.82,
"chunk_index": 2,
"tags": ["Kubernetes", "DevOps"],
"heading_path": "Componentes > Plano de Controle",
"text": "O servidor da API valida e configura...",
"context": [
"Texto do trecho anterior sobre armazenamento etcd...",
"O servidor da API valida e configura...",
"O escalonador observa Pods recém-criados..."
]
}
]
}
| Campo | Presente Quando | Descrição |
|---|---|---|
note_slug | Sempre | Identificador seguro para URL derivado do caminho do arquivo. |
title | Sempre | Título da nota do frontmatter ou nome do arquivo. |
file_path | Sempre | Caminho relativo dentro do cofre. |
score | Sempre | Pontuação de similaridade (0–1) para busca; contagem de saltos para conexões. |
chunk_index | Busca, hidden, boosted | Qual trecho da nota correspondeu (indexado de 0). |
tags | Quando a nota tem tags | Array de strings de tags. |
heading_path | Quando o trecho está sob um cabeçalho | Caminho breadcrumb como "Seção > Subseção". |
text | Quando --include-text é passado | Texto markdown completo do trecho correspondente, com blocos de código preservados. |
context | Quando --context-window N > 0 | Array de textos de trechos adjacentes ±N, ordenados por índice do trecho. |
extra | Conexões, tags, boosted | Informação específica do comando (ex.: "2 salto(s)", "graph-boosted"). |
Aprofundando a Qualidade da Resposta: Recuperação Multi-Sinal
Antes de responder a qualquer pergunta do tipo "o que eu sei sobre X" ou "resuma minhas notas sobre X", não pare em uma única chamada search. Resultados de busca sozinhos apenas revelam trechos semanticamente próximos à consulta — eles perdem o contexto adjacente que o usuário construiu deliberadamente em seu grafo. Sempre amplie o quadro:
- Busque com contexto — execute
searchcom--context-window 1 --include-text --top-k 2para obter os trechos mais relevantes com seus parágrafos adjacentes. Isso dá a você precisão (o trecho correspondente) e contexto (o que vem antes e depois) em uma única chamada. - Extraia backlinks para cada nota semente — execute
notebrain backlinks <slug-semente> --format json --include-textpara extrair cada nota que linka explicitamente para a semente. Essas são notas que o usuário manualmente curou como relacionadas, então seu conteúdo é quase sempre de alto sinal e deve ser ponderado pesadamente em sua síntese. - Explore conexões para fora — execute
notebrain connections <slug-semente> --hops 2 --format jsonpara mapear a vizinhança do grafo local ao redor da semente. Isso revela notas estruturalmente adjacentes (ex.: notas a dois links de distância) que podem não aparecer em uma busca vetorial pura, mas fazem parte do mesmo cluster de conhecimento. - Verifique links ocultos — execute
notebrain hidden <slug-semente> --include-text --context-window 1para capturar notas conceitualmente relacionadas que o usuário ainda não linkou. Destaque-as explicitamente para o usuário como potenciais links faltantes em seu cofre, pois este é um dos diferenciadores mais valiosos do NoteBrain sobre a busca simples. - Sintetize, não apenas liste — combine a(s) nota(s) semente, seus backlinks, sua vizinhança de
connectionse quaisquer resultadoshiddenem uma resposta coerente única, distinguindo o que está explicitamente linkado (alta confiança) do que é apenas semanticamente similar (vale a pena verificar novamente).
Este encadeamento search → backlinks → connections → hidden deve ser o fluxo de trabalho padrão para qualquer pergunta exploratória não trivial, não apenas uma única chamada search, porque ele revela tanto a estrutura explícita que o usuário construiu quanto a estrutura implícita que o NoteBrain pode detectar.
Pipeline de Encadeamento para Agentes de IA
# 1. Busque com contexto adjacente — top-k mantém resultados diversos entre notas
SLUG=$(notebrain search "backpressure em message broker" --limit 3 --top-k 2 \
--context-window 1 --include-text --format json \
--jsonpath="$.results[0].note_slug")
# 2. Busque o texto completo da nota reconstruída para o resultado principal
notebrain get "$SLUG" --jsonpath="$.text"
# 3. Encontre todos os slugs de notas que são backlinks para esta nota, com seu conteúdo,
# para fundamentar a resposta no que o usuário linkou explicitamente
notebrain backlinks "$SLUG" --format json --include-text
# 4. Explore a vizinhança do grafo para revelar notas estruturalmente adjacentes
# que a busca vetorial sozinha perderia
notebrain connections "$SLUG" --hops 2 --format json
# 5. Descubra links ocultos — notas conceitualmente relacionadas, mas não linkadas
notebrain hidden "$SLUG" --limit 3 --include-text --context-window 1 --format json
Exemplos de Tarefas comuns
| Tarefa do Usuário | Pipeline de Comandos do Agente |
|---|---|
| "O que eu anotei sobre sistemas de mensageria?" | search "sistemas de mensageria" --limit 5 --top-k 2 --context-window 1 --include-text → backlinks para o resultado principal → connections --hops 2 para contexto estrutural → sintetizar |
| "Leia minha nota de planejamento Q3" | get "Q3 Planning [Draft]" |
| "Encontre notas sem link sobre microsserviços" | hidden "microsserviços" --limit 10 --include-text |
| "O banco de dados está atualizado?" | stats --format json --jsonpath="$.total_chunks" |
| "O que toca em CI/CD, mas não está linkado?" | search "CI/CD" --limit 3 → backlinks para slug principal → hidden "<slug>" --include-text → recomendar links |
| "Liste tags no meu cofre" | tags --format json (e extraia o campo tags conforme necessário) |
Resolução de Problemas
notebrain não encontrado
O binário pode estar no diretório de trabalho. Execute ./notebrain.
Saída JSON vazia ou incompleta
- Certifique-se de que
--format jsonfoi passado antes da consulta? Cheque a posição dos argumentos. - Verifique se o ChromaDB embutido em
~/.notebrain/chromaexiste. Executenotebrain stats --format jsonpara confirmar a integridade do banco de dados.
A ingestão parece desatualizada
A ingestão automática é agendada a cada 3 horas. Se o usuário acabou de editar notas, execute notebrain ingest manualmente.
A consulta não retorna resultados
- Use
--min-score 0para ver todos os resultados (o padrão é 0). - Tente um fraseado alternativo ou sinônimos.
- Aumente
--limite--top-k. - Se ainda assim não houver resultados, o conteúdo pode não ter sido indexado. Verifique com
notebrain stats --format json.
Erro "não é um terminal"
Você esqueceu --format json. Sempre use --format json para execução por agente.