MÓDULO 1.4

🧠 Memória Semântica

AgentDB + HNSW para busca vetorial 150x-12.500x mais rápida. Memória que persiste entre sessões.

6
Tópicos
60
Minutos
Básico
Nível
Teoria
Tipo
1

🧠 Por que memória vetorial

Buscar por significado é diferente de buscar por palavra-chave. "Login OAuth" e "autenticação social" são quase a mesma coisa para humanos — mas keyword search trata como completamente diferente. Embeddings vetoriais resolvem isso codificando significado em coordenadas matemáticas.

🎯Keyword vs semântica

  • •Keyword: match exato de tokens — "OAuth" ≠ "autenticação"
  • •Semântica: proximidade no espaço vetorial — entende sinônimos e contexto
  • •Resultado: agente encontra padrões relevantes mesmo sem palavras iguais

📊Números reais

  • +40% recall em buscas comparado a keyword puro
  • 3-7x melhor relevância nos top-5 resultados
  • 0 esforço de tagging manual — embeddings são automáticos
2

📚 AgentDB

AgentDB é o banco de memória do Ruflo: SQLite via sql.js compilado para WASM. Roda em qualquer ambiente Node sem precisar de native bindings, sem build steps, sem dor de cabeça com glibc.

⚙️Por que sql.js (WASM)

  • •Cross-platform: Linux, macOS, Windows, browsers, edge
  • •Sem compilação nativa (sem node-gyp, sem dores)
  • •Funciona em containers minimalistas (alpine, distroless)
  • •Performance suficiente para a maioria dos casos

💡Dica

Por baixo do AgentDB existem 19 controllers especializados (auth, vector, sessions, etc.). Você não precisa conhecê-los — a CLI memory abstrai tudo.

3

⚡ HNSW indexing

HNSW (Hierarchical Navigable Small World) é o segredo da velocidade. Em vez de comparar query contra todos os vetores (O(n)), HNSW navega em camadas e converge em O(log n). Resultado: 150x a 12.500x mais rápido dependendo do tamanho do índice.

⚡Como HNSW funciona

  • •Camadas hierárquicas — topo é esparso, base é densa
  • •Greedy navigation — começa no topo, desce até encontrar vizinho
  • •Small world — conexões aleatórias longas + curtas (como redes sociais)
  • •Recall > 95% mantido com latência baixa

📊Benchmarks

  • 1.000 vetores: ~150x mais rápido que linear
  • 100.000 vetores: ~3.000x mais rápido
  • 1.000.000 vetores: até 12.500x mais rápido
  • Latência típica: <5ms para top-10 em milhões de itens

💡Tradeoff

HNSW troca um pouco de recall (~95% em vez de 100%) por latência baixíssima. Para 99% dos casos, vale a pena. Se precisar de 100% recall (compliance, médico), use o brute force exato disponível como fallback.

4

🗂️ Namespaces

Namespaces organizam memória por contexto/propósito. Em vez de jogar tudo em um saco, separe por uso: padrões aprendidos, tarefas em andamento, soluções, feedback, memórias importadas do Claude Code.

📁Namespaces padrão

  • patterns — padrões aprendidos pelo SONA
  • tasks — estado de tarefas em andamento
  • solutions — soluções consolidadas reutilizáveis
  • feedback — verdicts e avaliações
  • claude-memories — bridge do Claude Code
  • collaboration — contexto de dual-mode

✓ Fazer

  • ✓Usar nome descritivo: "auth-feature-2026"
  • ✓Separar por feature/projeto
  • ✓Limpar namespaces obsoletos
  • ✓Usar memory_search_unified para cross-search

✗ Evitar

  • ✗Jogar tudo em "default"
  • ✗Nomes genéricos como "stuff"
  • ✗Misturar dados sensíveis com gerais
  • ✗Criar 50 namespaces para uma feature
5

🔍 ONNX embeddings

Ruflo usa all-MiniLM-L6-v2 via ONNX runtime — modelo compacto (22MB), 384 dimensões, embedding em <5ms. Roda 100% local: sem API key, sem latência de rede, sem vazamento de dados.

🤖Especificações

  • •Modelo: sentence-transformers/all-MiniLM-L6-v2
  • •Dimensões: 384 (compacto, eficiente)
  • •Runtime: onnxruntime-node (CPU otimizado)
  • •Latência: <5ms por sentença em hardware comum
  • •Privacidade: 100% local, zero rede

📊Versão acelerada (agentic-flow)

  • 75x mais rápido com integração agentic-flow ONNX
  • Batch embedding de centenas de docs em segundos
  • Cache automático com 95% hit rate em workloads repetidos
6

💾 RVF format

RVF (Ruflo Vector Format) é o formato de persistência. Snapshot completo do estado de memória — vetores, metadados, índice HNSW — em um único arquivo. Restaurar uma sessão antiga é uma chamada só.

💾O que RVF inclui

  • •Todos os embeddings (vetores 384-dim)
  • •Metadados (namespace, timestamps, source)
  • •Estrutura do índice HNSW serializada
  • •Quantização opcional (Int8 = 3.92x menor)

💡Use case

Faça snapshots regulares antes de operações arriscadas (limpeza, refator de namespace). Em desastre, restaurar é trivial. Snapshots semanais já bastam para projetos médios.

⚠️Backup é responsabilidade sua

Ruflo não faz backup automático para destinos externos. Configure rsync, S3 ou git-lfs nos arquivos RVF. Memória perdida = aprendizado perdido.

📋Resumo do Módulo

✓
Memória vetorial — busca por significado, não por keyword
✓
AgentDB via sql.js — SQLite WASM, cross-platform sem compilação
✓
HNSW 150x-12.500x — busca em milhões de vetores em <5ms
✓
Namespaces organizam — patterns, tasks, solutions, feedback, claude-memories
✓
ONNX local — all-MiniLM-L6-v2, 384 dim, sem API, <5ms
✓
RVF persiste — snapshot/restore completo, faça backup externo

Próximo Módulo:

1.5 - CLI Essentials: tour pelos comandos do dia a dia

← Voltar Próximo Módulo →