A história das Descobertas — MCP, FTS5, ai-jail e as lições que viraram regras

⚡ A camada invisível do ecossistema

Todo projeto tem código, testes e deploy. O que pouca gente conta é a camada invisível: as descobertas técnicas que atravessam todos os projetos e mudam o jeito de trabalhar.

Em julho e agosto de 2026, o meu ecossistema (Arachne, Capivara, Dogwalk, TatuEngine, LifeLog) passou por quatro descobertas que viraram fundação: MCP virou o conector universal, FTS5 + busca vetorial virou o motor de busca, ai-jail virou a segurança do agente, e Ollama trouxe a IA pra dentro de casa. E no final, as lições viraram regras.

🧠 Contexto — o mesmo problema, cinco projetos, cinco soluções

O problema de um ecossistema com 5 projetos é que cada um resolvia a mesma dor do seu jeito:

• Integração — cada ferramenta precisava de um plugin custom, um handler REST, um socket costurado na mão
• Busca — cada banco tinha seu LIKE %termo% lento ou uma busca cheia de falso positivo
• Segurança — agentes com acesso a tudo, rodando sem sandbox, um rm errado de um prompt injection e era adeus
• IA — tudo dependia de API na nuvem, com latência, custo e dados saindo de casa

O ponto de virada foi perceber que não valia a pena reinventar — valia descobrir o que já existia documentado e adotar como padrão.

🔧 A luta — quatro descobertas

MCP: do “conector universal” ao registry oficial

O MCP (Model Context Protocol) da Anthropic é o “USB-C da IA” — um protocolo que padroniza como LLMs se conectam a ferramentas. Escreve um servidor uma vez, qualquer cliente (Hermes, Claude, Cursor) descobre as tools automaticamente.

O Arachne virou servidor MCP com 38 ferramentas (scrape, vision, transcribe, RAG, download de repos, análise de vídeo) em stdio + SSE. Mas a descoberta de verdade veio ao tentar publicar no registry oficial:

# O caminho NÃO é PR no modelcontextprotocol/servers
# (repo só aceita reference implementations do steering group desde 2025)
# O caminho é o CLI do publisher:
mcp-publisher publish

Resultado: io.github.Samuelfmedeiros/arachne-mcp v1.0.1 no registry.modelcontextprotocol.io, com o pacote arachne-mcp 1.0.1 no PyPI. Qualquer agente MCP do mundo agora descobre o Arachne sem integração custom.

FTS5 + vetorial: a busca que entende

A segunda descoberta: busca de verdade não é regex — é recuperação híbrida. O RAG do Arachne evoluiu de FTS5 puro pra busca híbrida FTS5 + pgvector + RRF (Reciprocal Rank Fusion), que combina a relevância lexical do full-text com a semântica dos embeddings.

A migração SQLite → PostgreSQL (02/08) trouxe dois tropeços clássicos que viraram lição:

-- SQLite → PostgreSQL
STRFTIME('%s', col)      → EXTRACT(EPOCH FROM col)
LENGTH(embedding)        → vector_dims(embedding)

E no LifeLog, a busca saiu de Fuse.js pra um índice JSON embutido no build com word-boundary match (commit f690095) — busca full-text sem dependência externa, direto no HTML.

ai-jail: o sandbox do agente

Agente com acesso ao shell é um risco enorme — um prompt injection e os tokens vazam. A descoberta foi o ai-jail (bwrap + landlock): um sandbox que isola comandos e mascara secrets:

# ~/.ai-jail — a parte mais importante:
mask = [".env", "credentials.json", "*.pem", "id_ed25519*", "id_rsa*"]
hide_dotdirs = [".hermes"]        # tokens do Hermes protegidos
deny_paths = ["secrets/", "*.key", ".gnupg/"]

O hide_dotdirs = [".hermes"] foi a descoberta fina: esconder o diretório inteiro do Hermes dentro do sandbox, pra nem o agente nem um prompt injection conseguirem ler os tokens. E o TatuEngine levou o conceito pro código: Sandbox Híbrido com 51/51 testes (path validation, size/type enforcement, 3 níveis de isolamento).

Ollama: a IA que mora em casa

A quarta descoberta: dá pra rodar LLM local sem depender de nuvem. Ollama no WSL + Douglas (o PC espelho) roda o qwen3.5-vision:latest — verifiquei agora, online:

curl -s http://192.168.7.5:11434/api/tags
# → {"models":[{"name":"qwen3.5-vision:latest", ...}]}

Com isso, visão (VLM), geração e análise rodam em casa — latência baixa, zero custo por token, dados que não saem da rede. O Arachne consome o Ollama do Douglas como fallback de VLM, e a TatuEngine roda BitMamba-2 1B em GPU local com 252× de speedup.

💡 Resolução — as lições que viraram regras

O maior ganho não foi nenhuma ferramenta — foi o padrão de comportamento que elas ensinaram. Quatro regras nasceram dessas descobertas:

1. Docs First — antes de qualquer ação técnica, consultar a documentação oficial. Nada de workaround inventado se a solução documentada existe.
2. Plan First — mostrar o plano antes de executar. Nada de sair codando e quebrar produção.
3. Parar e perguntar — se uma abordagem falhou, NÃO trocar de estratégia silenciosamente. Reportar o bloqueio com dados e apresentar opções A/B/C.
4. Delivery Gate — nenhuma entrega sem passar pelas camadas de teste (lint, types, build, E2E, segurança). Check falhou = não entrega.

📊 Métricas

🎯 Aprendizados

1. Não invente o que já existe — MCP, FTS5, bwrap, Ollama: tudo documentado, tudo open source. O trabalho é descobrir e integrar, não reinventar.
2. A descoberta vira padrão, não projeto — cada uma dessas ferramentas atravessou 2+ projetos. O padrão é o que escala, não o caso isolado.
3. Segurança de agente é camada, não feature — sandbox, mask de secrets e hide_dotdirs protegem contra o pior caso (prompt injection), não contra o usuário. Projete pro adversário.
4. Documentar a lição dobra o valor — esse post é a prova: a descoberta que vira regra evita que o próximo projeto repita o erro.

╔══════════════════════════════════════╗
║  Samuel Medeiros                    ║
║  Senior Software Engineer           ║
║  Stack: Python · TypeScript · Rust  ║
║  Projetos: Arachne, Dogwalk,        ║
║            Capivara, TatuEngine      ║
╚══════════════════════════════════════╝