Documentação

Início rápido

Pré-requisitos

• Node.js 18+ (LTS recomendado)
• Docker Engine rodando (ou Docker Desktop)
• Uma chave de API da OpenAI (para embeddings)
• Claude Code instalado e funcionando

Instalar

npx zepapagaio init

O instalador faz 3 perguntas: sua chave da API da OpenAI, o caminho do seu vault Obsidian (ou onde criar um), e se quer habilitar o MCP do Obsidian (opcional). Depois disso, ele baixa as imagens Docker, cria os arquivos iniciais de memória e registra os servidores MCP na sua config do Claude.

Primeiros comandos pra testar

# Verificar se está tudo rodando
ze status

# Lembrar de algo
ze lembra "Decidimos usar Convex como backend"

# Buscar na memória
ze puxa "qual backend estamos usando"

Se o ze status mostrar tudo verde, você está pronto. Se algo estiver vermelho, pule para a seção de Troubleshooting.

Arquitetura

O Zé Papagaio é composto de três camadas core (Fase 1) e quatro componentes opcionais adicionados na Fase 2. Tudo roda localmente na sua máquina via containers Docker expostos apenas em loopback (127.0.0.1).

Camadas core (Fase 1)

• Vault — Arquivos Markdown no disco, versionados em git, servindo como fonte única da verdade.
• RAG (vault-rag) — Embeddings OpenAI + sqlite-vec para busca semântica em todas as notas.
• Graph (vault-graph) — Knowledge graph Neo4j com entidades e relacionamentos extraídos automaticamente.

Componentes Fase 2

• Cache — Redis para cachear chamadas de tool repetidas e queries RAG.
• Storage — MinIO para armazenamento persistente de arquivos (imagens, artefatos de teste, anexos).
• Multimodal — Pipeline de indexação de imagens: screenshot → descrição → nota indexada no RAG.
• Testing — Robot Framework + Playwright em containers isolados para testes de UI automatizados.

Vault & Memória

O vault é um diretório de arquivos Markdown — normalmente um vault do Obsidian, mas qualquer diretório serve. Cada arquivo é uma "nota de memória" que o Claude pode ler, escrever e buscar. O instalador do Zé cria um conjunto inicial de notas seed para dar bootstrap na memória.

Convenções de frontmatter

Toda nota de memória deve ter frontmatter YAML com estes campos:

---
name: project_aiox_overview
description: "Overview of the aiox project — URL shortener SaaS"
type: project
project: aiox
---

Tipos de memória

MEMORY.md

O arquivo MEMORY.md é o índice — uma lista Markdown com links para cada nota e sua descrição. O Claude lê esse arquivo primeiro para entender que memória está disponível. O hook de autocommit mantém o índice em sincronia quando notas são adicionadas ou modificadas.

RAG (busca semântica)

O componente RAG (Retrieval-Augmented Generation) fornece busca semântica em todo o seu vault. Em vez de correspondência por palavras-chave, ele entende significado — então buscar "qual banco de dados usamos" encontra uma nota que diz "escolhemos Convex como backend".

Como funciona

• Cada nota é dividida em chunks do tamanho de parágrafos (~300 tokens cada).
• Cada chunk recebe embeddings via OpenAI text-embedding-3-small (1536 dimensões).
• Os vetores são armazenados em sqlite-vec, uma extensão SQLite para busca por similaridade vetorial.
• No momento da query, sua pergunta é embedada e comparada com todos os chunks usando similaridade de cosseno.
• Os top-k resultados são retornados com o caminho da nota fonte e o texto correspondente.

Tools MCP

RAG vs. leitura direta

Use RAG quando você não sabe qual arquivo tem a resposta. Use leitura direta (via Obsidian MCP ou a tool Read) quando você sabe exatamente qual nota precisa. RAG é para descoberta; leitura direta é para precisão.

# RAG search — finds relevant chunks across all notes
rag_search("what deployment platform do we use")

# Direct read — you already know the file
obsidian_get_file_contents("project_aiox_decisions.md")

Knowledge Graph (Neo4j)

O knowledge graph armazena relacionamentos estruturados entre entidades no seu vault. Enquanto o RAG encontra texto por similaridade, o grafo responde perguntas como "quais stories estão bloqueadas?" ou "de quais decisões o projeto X depende?".

Tipos de nó

Tipos de relacionamento

Tools MCP

Auto-extração via hooks

Quando você salva uma nota de memória (via as tools Write/Edit do Claude), um hook PostToolUse extrai automaticamente entidades e relacionamentos do conteúdo da nota e os insere no grafo. Você não precisa manter o grafo manualmente — ele fica em sincronia com o vault.

# Example Cypher query — find all stories blocked by something
graph_query("MATCH (s:Story)-[:BLOQUEADA_POR]->(p:Pendencia) RETURN s.name, p.name")

# Get everything connected to a project
graph_neighbors("zepapagaio")

Obsidian MCP

O servidor MCP do Obsidian dá ao Claude acesso direto de leitura/escrita/busca ao seu vault Obsidian através do plugin Local REST API. Isso é opcional — os MCPs vault-rag e vault-graph funcionam independentemente do Obsidian.

Quando você precisa

• Você quer que o Claude leia/escreva notas sem acessar o sistema de arquivos diretamente.
• Você quer usar as capacidades de busca do Obsidian (full-text, busca por tag, etc.).
• Você tem o Obsidian aberto e quer que o Claude interaja com a mesma instância do vault.

Quando você não precisa

• Você está usando o vault puramente como um diretório de arquivos (sem o app Obsidian).
• O Obsidian não está instalado ou você prefere não mantê-lo aberto.
• A busca RAG é suficiente pro seu workflow.

Setup

• Instale o plugin Local REST API no Obsidian (Community Plugins → busque "Local REST API").
• Habilite o plugin e anote a chave de API das configurações dele.
• O instalador do Zé detecta o Obsidian e registra o servidor MCP automaticamente se você optar por isso.

Tools disponíveis

O MCP do Obsidian expõe tools como obsidian_get_file_contents, obsidian_append_content, obsidian_simple_search, obsidian_complex_search, e mais. Todas operam no vault atualmente aberto.

Cache (Redis)

A camada de cache usa uma instância local do Redis para evitar chamadas de API redundantes e acelerar operações repetidas. Ela cacheia resultados de chamadas de tools, queries RAG e respostas da API do GitHub.

Namespacing de chaves

Comandos CLI

# Show cache stats (hit rate, key count, memory usage)
ze cache status

# Clear all cached entries
ze cache limpa

# Clear only RAG cache (useful after reindex)
ze cache limpa rag

As chaves de cache são geradas a partir dos parâmetros de entrada (hash), então queries idênticas retornam resultados cacheados instantaneamente. O cache invalida automaticamente quando os dados subjacentes mudam (ex.: uma edição de nota dispara a evicção do cache RAG daquela nota).

Storage (MinIO)

O MinIO provê armazenamento de objetos compatível com S3 rodando localmente. Arquivos que antes sumiam no histórico do chat agora ganham URLs persistentes.

Buckets

Comandos CLI

# List images in storage
ze imagem lista

# Upload an image
ze imagem salva screenshot.png

# Get a presigned URL for an image
ze imagem url screenshot.png

O MinIO roda na porta 9000 (API) e 9001 (console), vinculado apenas a 127.0.0.1. As credenciais são geradas automaticamente durante a instalação e armazenadas em ~/.config/zepapagaio/env.

Multimodal

O pipeline multimodal permite que o Zé "veja" imagens. Ele pega um screenshot ou diagrama, gera uma descrição textual, salva como nota Markdown e indexa no RAG. Depois da indexação, você pode encontrar imagens pelo conteúdo usando busca semântica.

Como funciona

• Você fornece uma imagem (caminho de arquivo ou URL).
• GPT-4o-mini (padrão) ou GPT-4o gera uma descrição estruturada.
• A descrição é salva como nota Markdown no vault com metadados (caminho da fonte, timestamp, modelo usado).
• A nota é automaticamente indexada pelo pipeline RAG.
• A imagem original é armazenada no MinIO (bucket chat-images).

Custo por imagem

Uso

# Index a screenshot (saves to vault + RAG)
ze imagem indexa ./screenshot.png

# Index with GPT-4o for better quality on complex images
ze imagem indexa ./dense-chart.png --model gpt-4o

# Later, find it by content
ze puxa "the chart showing MRR drop in March"

O hook de auto-indexação também pode disparar automaticamente quando o Claude lê ou recebe uma imagem relevante durante a conversa.

Testing

O Zé inclui uma camada de testes automatizados usando Robot Framework com browser Playwright headless, rodando dentro de um container Docker isolado. Isso permite que o Claude rode smoke tests de UI sem despejar milhares de tokens de output do browser na conversa.

Como funciona

• Os arquivos de teste são arquivos .robot do Robot Framework com keywords do Playwright.
• Os testes rodam dentro de um container com browser Chromium headless.
• Os resultados (pass/fail, screenshots, logs) são armazenados no MinIO (bucket robot-artifacts).
• Apenas um resumo é retornado ao Claude — não o output completo do browser.

Comandos CLI

# Run a specific test
ze testa my-story

# Run all tests
ze testa

# Run with visible browser (debugging)
ze testa my-story --headed

Keywords compartilhadas

O Zé vem com uma biblioteca de keywords compartilhadas do Robot Framework para ações comuns (fluxos de login, navegação, preenchimento de formulários). Elas ficam disponíveis em ~/.config/zepapagaio/robot/keywords/.

Skills & Autoprogramação

O sistema de skills dá ao Claude habilidades especializadas que são carregadas sob demanda. Em vez de um único prompt de sistema gigante, o Claude ativa a skill certa para a tarefa — design de API, debugging, padrões Next.js, revisão de segurança, e assim por diante.

Como as skills funcionam

• Skills são arquivos Markdown com instruções estruturadas, armazenados na biblioteca de skills.
• Cada skill tem uma condição de trigger (quando ativar) e instruções (como se comportar).
• O Claude carrega skills dinamicamente com base no contexto da tarefa atual.
• Múltiplas skills podem estar ativas simultaneamente.

Autopilot

O autopilot de skills roda silenciosamente em segundo plano. Quando ele detecta uma lacuna — você está trabalhando com um framework ou ferramenta que nenhuma skill ativa cobre — ele busca na biblioteca, promove a melhor correspondência, ou cria uma skill nova do zero. Você não precisa pedir; acontece automaticamente.

Criando skills customizadas

# A skill is a Markdown file with this structure:
---
name: my-custom-skill
description: "Expert at X framework"
trigger: "code imports X or user asks about X"
---

## Instructions

When activated, follow these patterns:
1. Always check for ...
2. Prefer X over Y because ...
3. Common pitfalls: ...

Coloque skills customizadas no diretório da biblioteca de skills do seu vault. O autopilot vai descobri-las e promovê-las quando forem relevantes.

CLI do Zé

O CLI ze é a principal forma de interagir com o stack de memória pelo terminal. Todos os comandos ficam disponíveis após rodar npx zepapagaio init.

Todos os comandos ze aceitam --help para detalhes de uso. O CLI é deliberadamente mínimo — a maior parte do trabalho pesado acontece pelas tools MCP do Claude, não pelo uso direto do CLI.

Troubleshooting

Comece com ze doctor — ele verifica todos os serviços e reporta o que está errado. Abaixo estão os problemas mais comuns e suas soluções.

Docker não está rodando

# Symptom: ze status shows all services as "down"
# Fix: start Docker
sudo systemctl start docker   # Linux
open -a Docker                # macOS

Chave da OpenAI expirada ou inválida

# Symptom: rag_search returns authentication errors
# Fix: update the key
nano ~/.config/zepapagaio/env
# Change OPENAI_API_KEY=sk-... to your new key
# Then restart:
ze parar && ze voltar

Neo4j não responde

# Symptom: graph_query times out or returns connection refused
# Check if the container is running:
docker ps | grep neo4j

# If not running:
ze voltar

# If running but not responding, check logs:
docker logs zepapagaio-neo4j --tail 50

# Common cause: not enough memory. Neo4j needs ~512MB.

Obsidian não está aberto (conexão recusada no MCP)

# Symptom: obsidian_* tools fail with ECONNREFUSED
# Fix: open Obsidian and make sure Local REST API plugin is enabled.
# Alternatively, if you don't use Obsidian, you can ignore this —
# vault-rag and vault-graph work independently.

Conflitos de porta

Depois de mudar as portas, rode ze parar && ze voltar para reiniciar com a nova configuração.

Índice RAG vazio ou desatualizado

# Check index status:
ze status   # look at "RAG index" line

# Force a full reindex:
rag_reindex()
# or from CLI:
ze puxa --reindex

Debugging geral

# Full diagnostic report
ze doctor

# Check all container logs
docker compose -f ~/.config/zepapagaio/compose.yml logs --tail 20