Communitygithub.com

notebrain-cli

Ferramenta CLI em Go de alto desempenho que indexa seu cofre Obsidian em um banco de dados vetorial ChromaDB local, permitindo que agentes de IA explorem sua base de conhecimento pessoal de forma inteligente.

O que é notebrain-cli?

NoteBrain é uma ferramenta CLI em Go de alto desempenho que indexa todo o conteúdo de markdown de um cofre Obsidian em um banco de dados vetorial ChromaDB local. Ela fornece uma interface especializada para agentes de IA realizarem busca semântica, travessia de grafo de wikilinks, descoberta de links ocultos e análise de tags, tudo sem exigir um servidor ChromaDB separado. A utilidade principal está em permitir que agentes, como Claude Code ou Codex, naveguem e raciocinem sobre o conhecimento pessoal de forma estruturada, combinando similaridade vetorial com a estrutura explícita de links do cofre. A ferramenta suporta execução não interativa com `--format json`, extração de campos via `--jsonpath` para encadeamento de comandos, e uma pipeline de recuperação multi-sinal que combina busca, backlinks, conexões e descoberta de links ocultos para respostas mais profundas e com contexto.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add nmdra/notebrain-cli

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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:

  1. Apenas NoteBrain — Sem Busca Genérica em Arquivos: Nunca use grep, find, ls ou 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. Trate notebrain como a única interface para o conteúdo do cofre. Se um comando notebrain parecer não retornar nada útil, refine a consulta notebrain (fraseado diferente, --limit maior, comando alternativo) em vez de recorrer a uma busca genérica em arquivos.
  2. 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 chaves snake_case (note_slug, title, file_path, score, tags, text).
  3. 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 de jq.
  4. Recuperar Notas Completas (notebrain get): Quando search retornar um trecho de nota relevante, use notebrain 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 use cat no arquivo do cofre subjacente — get reconstrói notas fragmentadas corretamente e respeita o estado indexado do cofre.
  5. Recuperar Conteúdo para Síntese (--include-text): Por padrão, search e 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 campo text retornado contém markdown rico com blocos de código preservados, para que trechos de código possam ser copiados e colados.
  6. Resolução Binária e Citação: Em ambientes de desenvolvimento, execute ./notebrain se notebrain nã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.
  7. 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.
  8. Ingestão Automatizada: A ingestão é tratada por agendadores do SO (cron/systemd timers a cada 3 horas). Você não precisa executar ingest manualmente 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árioComandoPorquê e Como Usar
"O que minhas notas dizem sobre X?"searchRealiza 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"getRecupera e reconstrói o texto completo da nota e metadados por slug ou caminho de arquivo.
"O que está diretamente linkado a esta nota?"backlinksEncontra referências explícitas [[wikilink]] apontando para a nota alvo.
"O que está estruturalmente próximo no grafo?"connectionsExecuta 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?"hiddenDescobre notas semanticamente similares, mas não linkadas. Altamente valioso para descobrir pontes conceituais.
"Encontre conceitos relacionados a X centrados na nota Y"boostedCombina similaridade vetorial com proximidade no grafo a uma nota --seed.
"Quais notas compartilham tags com X?"tagsAnalisa sobreposição de tags. Retorna strings de tags limpas no array tags.
"O banco de dados está atualizado?"statsGera contagens de coleção (chunks, links). Suporta --format=json e --jsonpath.
"Indexar ou reindexar o cofre"ingestSincroniza 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

FlagPropósitoPadrão
--top-k NMáximo de trechos a reter por nota. Evita que uma nota longa domine os resultados, preservando profundidade.3
--context-window NBusca ±N trechos adjacentes ao redor de cada correspondência e preenche o array context. Use 1 ou 2 na maioria das tarefas.0
--has-tasksRetorna apenas trechos que contêm listas de tarefas (checkboxes).desligado
--has-codeRetorna apenas trechos que contêm blocos de código encapsulados.desligado
--sectionFiltra resultados para trechos sob um caminho de cabeçalho específico (ex.: "Arquitetura > Componentes").—
--limit NNúmero máximo total de resultados a retornar.10
--tag "TagName"Filtra ou busca por nome de tag.—
--min-score FSuprime resultados abaixo desta pontuação de similaridade (0–1).0

Quando usar --context-window vs notebrain get

  • Use --context-window 1 quando 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 get quando 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..."
      ]
    }
  ]
}
CampoPresente QuandoDescrição
note_slugSempreIdentificador seguro para URL derivado do caminho do arquivo.
titleSempreTítulo da nota do frontmatter ou nome do arquivo.
file_pathSempreCaminho relativo dentro do cofre.
scoreSemprePontuação de similaridade (0–1) para busca; contagem de saltos para conexões.
chunk_indexBusca, hidden, boostedQual trecho da nota correspondeu (indexado de 0).
tagsQuando a nota tem tagsArray de strings de tags.
heading_pathQuando o trecho está sob um cabeçalhoCaminho breadcrumb como "Seção > Subseção".
textQuando --include-text é passadoTexto markdown completo do trecho correspondente, com blocos de código preservados.
contextQuando --context-window N > 0Array de textos de trechos adjacentes ±N, ordenados por índice do trecho.
extraConexões, tags, boostedInformaçã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:

  1. Busque com contexto — execute search com --context-window 1 --include-text --top-k 2 para 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.
  2. Extraia backlinks para cada nota semente — execute notebrain backlinks <slug-semente> --format json --include-text para 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.
  3. Explore conexões para fora — execute notebrain connections <slug-semente> --hops 2 --format json para 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.
  4. Verifique links ocultos — execute notebrain hidden <slug-semente> --include-text --context-window 1 para 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.
  5. Sintetize, não apenas liste — combine a(s) nota(s) semente, seus backlinks, sua vizinhança de connections e quaisquer resultados hidden em 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árioPipeline 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 json foi passado antes da consulta? Cheque a posição dos argumentos.
  • Verifique se o ChromaDB embutido em ~/.notebrain/chroma existe. Execute notebrain stats --format json para 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 0 para ver todos os resultados (o padrão é 0).
  • Tente um fraseado alternativo ou sinônimos.
  • Aumente --limit e --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.

Habilidades Relacionadas