DEV Community

Claudiomar Estevam
Claudiomar Estevam

Posted on

Dando memória para sua IA: por que ela esquece tudo (e como resolver)

#ai #mcp #productivity #opensource

Spectrum - Memória Semântica Persistente para IA

Meu nome é Claudiomar Estevam. 22+ anos em infraestrutura, segurança e arquitetura de software. Neurodivergente (TDAH + Altas Habilidades). Pesquiso memória e cognição em sistemas de IA, e o Spectrum nasceu direto dessa pesquisa: como dar memória persistente pra agentes que, por arquitetura, esquecem tudo entre sessões. Esse é meu primeiro post aqui no dev.to. Se você trabalha com IA e cansa de repetir contexto, esse post é pra você. Se você é ND, é especialmente pra você, mas funciona pra todo mundo.

O problema: por que a IA esquece tudo

Quando você conversa com uma IA, tudo que você escreve e tudo que ela responde vira tokens. Cada modelo tem uma janela de contexto, um espaço fixo onde esses tokens cabem. Pensa numa mesa de trabalho: dá pra espalhar bastante coisa, mas o tamanho é fixo.

O ponto: quando a sessão acaba, a mesa é limpa. Tudo vai embora. A próxima sessão começa do zero.

Não é bug. A janela de contexto é memória de trabalho, não memória de longo prazo. A IA nunca teve onde guardar.

Por que a IA esquece tudo - janela de contexto entre sessões

Na prática isso significa: abre sua IA favorita, explica o projeto, configura o contexto, trabalha 3 horas, fecha. Abre de novo. Ela não lembra de nada. Agora multiplica por 10 projetos e um cérebro que troca de contexto 47 vezes por dia.

A "solução" que todo mundo usa: arquivos .md espalhados pelo sistema. Um arquivo de contexto aqui, um de skills ali, notas acolá. Funciona até certo ponto. Mas:

  • Cada .md entra inteiro na janela de contexto (gasta tokens mesmo quando não precisa)
  • Não é pesquisável por significado
  • Não compartilha entre agentes diferentes
  • Se você tem TDAH, boa sorte lembrando onde salvou o quê
Arquivos .md Spectrum
Busca ctrl+F por texto exato por significado (semântica)
Consumo de tokens arquivo inteiro na janela só o que foi buscado
Multi-agente cada IA lê seu próprio .md todos compartilham o mesmo banco
Multi-projeto copiar .md entre pastas scopes organizados por projeto
Atualização manual, esquece de manter upsert automático por scope/key
Para NDs lembrar onde salvou o quê só lembrar mais ou menos o quê

O que é o Spectrum

Spectrum é memória persistente para IA. Você salva informação (decisões, contexto, preferências, sessões) e a IA busca quando precisa, por palavras-chave ou por significado. Funciona como um segundo cérebro que qualquer agente pode consultar.

O que ele tem:

  • SQLite local. Seus dados são seus, nada vai pra nuvem
  • Busca por keyword e semântica (embeddings locais, 384 dimensões, ONNX)
  • Organização por scopes: project:meu-app, session, user, technical
  • CLI (spm) pra usar direto no terminal
  • MCP server pra conectar no Claude Code, Gemini CLI, Codex
  • Disponível em Node e Python, mesma API, mesmo banco

Agnóstico. Funciona com Claude, Gemini, Codex, ou qualquer agente que suporte MCP. Se o seu não suporta, importa como biblioteca no código.

Arquitetura do Spectrum

Números reais (meu setup pessoal):

  • 1966 memórias, 151 scopes
  • Sessões de trabalho, contexto de projetos, preferências, decisões técnicas
  • Tudo pesquisável por significado, não só por texto exato

Setup em 5 minutos

1. Instalar

Node:

npm install -g @natiwo/spectrum-memory
Enter fullscreen mode Exit fullscreen mode

Python:

pip install spectrum-memory
Enter fullscreen mode Exit fullscreen mode

Um comando. Vem com CLI (spm) + MCP server + biblioteca. Zero config. O banco SQLite é criado automaticamente em ~/.spectrum/spectrum.db.

2. Testar a CLI 

# Salvar uma memória
spm save user/nome "Meu nome é Fulano, trabalho com backend Node.js e infra AWS"

# Salvar contexto de um projeto
spm save project:meu-app/stack "Next.js 15, PostgreSQL, Redis, deploy na Vercel"
spm save project:meu-app/decisoes "Drizzle ao invés de Prisma por performance em queries complexas"

# Buscar por keyword
spm search "drizzle prisma"

# Buscar por significado (semântico)
spm search --semantic "qual ORM estamos usando e por quê"

# Listar tudo de um projeto
spm list project:meu-app

# Ver estatísticas
spm stats
Enter fullscreen mode Exit fullscreen mode

Fecha o terminal, abre de novo, tá tudo lá.

3. Conectar no Claude Code

Edita ~/.claude.json:

{
  "mcpServers": {
    "spectrum": {
      "command": "spectrum-mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Reinicia o Claude Code. Agora ele tem 7 ferramentas novas:

Ferramenta O que faz
memory_save salva ou atualiza uma memória
memory_get recupera memória por scope/key
memory_list lista memórias de um scope
memory_delete deleta memória específica
memory_search busca por keyword
memory_search_semantic busca por significado
memory_list_scopes lista todos os scopes

O que muda na prática:

Antes:

Você: "Estou trabalhando no projeto X, a stack é Y, a decisão Z foi por causa de W..."
(fecha sessão)
Você: "Estou trabalhando no projeto X, a stack é Y..."
Enter fullscreen mode Exit fullscreen mode

Depois:

Você: "Continua o trabalho no projeto X"
IA: (busca no Spectrum) "Encontrei o contexto. Stack Next.js 15, PostgreSQL,
    Drizzle como ORM. Última sessão: refatorar módulo de auth.
    Por onde quer continuar?"
Enter fullscreen mode Exit fullscreen mode

4. Conectar no Gemini CLI

Em ~/.gemini/settings.json:

{
  "mcpServers": {
    "spectrum": {
      "command": "spectrum-mcp"
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

5. Conectar no Codex 

[mcp_servers.spectrum]
command = "spectrum-mcp"
Enter fullscreen mode Exit fullscreen mode

Três agentes, uma memória. Claude salva, Gemini lê, Codex usa. Ninguém esquece nada.

Como organizar memórias

A chave é o sistema de scopes (namespaces):

user/                    → Sobre você (preferências, stack, forma de trabalhar)
session/                 → Resumos de sessões de trabalho
project:nome-do-app/     → Contexto de cada projeto
technical/               → Conhecimento técnico reutilizável
active/                  → O que tá em andamento agora
Enter fullscreen mode Exit fullscreen mode

Exemplos reais 

# Quem sou eu (a IA lê isso e já sabe como te tratar)
spm save user/perfil "Backend senior, 10 anos, TypeScript strict,
  Zod pra validação, commits em português"

# Projeto atual
spm save project:api-pagamentos/stack "Node 22, Fastify, Drizzle, PostgreSQL 16, Redis 7"
spm save project:api-pagamentos/decisao-orm "Drizzle > Prisma: 3x mais rápido em
  queries com joins complexos, sem query engine binário"

# Sessão de trabalho
spm save session/2026-03-16 "API Pagamentos: implementei webhooks,
  falta testar retry. Branch: feat/webhooks"

# Onde parei
spm save active/api-pagamentos "Webhook retry, src/webhooks/retry.ts,
  próximo: testes de integração"
Enter fullscreen mode Exit fullscreen mode

Guardrails: ensinando limites

Memória não é só "o que eu sei". É também "o que eu não posso fazer":

spm save guardrails/seguranca "NUNCA commitar secrets ou .env.
  NUNCA rodar terraform apply em produção sem confirmação.
  SEMPRE validar inputs antes de queries SQL."

spm save guardrails/codigo "TypeScript strict, NUNCA usar any.
  Zod pra validação. Testes antes de PR."
Enter fullscreen mode Exit fullscreen mode

A diferença de colocar isso num .md estático? Guardrails no Spectrum são dinâmicos, pesquisáveis, e compartilhados entre agentes. Muda uma vez, vale pra todos.

Dica: instrua a IA a salvar

No arquivo de instruções do seu agente (cada um tem o seu):

## Memória
- Ao final de sessões significativas, salvar resumo no Spectrum (scope: session)
- Ao tomar decisões técnicas, salvar no Spectrum (scope: project:nome)
- Ao começar trabalho, buscar contexto no Spectrum antes de perguntar
Enter fullscreen mode Exit fullscreen mode

A IA passa a ser proativa: salva e busca sozinha.

Busca semântica

A diferença entre keyword e semântica:

# Keyword: precisa acertar as palavras
spm search "Drizzle ORM"
# Só encontra se tiver "Drizzle" e "ORM" no texto

# Semântico: entende o significado
spm search --semantic "qual biblioteca estamos usando pra banco de dados"
# Encontra a memória sobre Drizzle mesmo sem essas palavras na busca
Enter fullscreen mode Exit fullscreen mode

Como funciona: quando você salva uma memória, o Spectrum transforma o texto em um vetor de 384 números. Esse vetor representa o significado. Textos com significados parecidos geram vetores próximos no espaço. Quando você busca, o vetor da pergunta fica perto do vetor da resposta, mesmo sem palavras em comum.

Tudo roda local. Modelo all-MiniLM-L6-v2, compacto, sem GPU, sem internet.

Busca Semântica - como embeddings encontram por significado

Pra quem tem TDAH: você não precisa lembrar como salvou. Só precisa lembrar mais ou menos o quê. A busca semântica faz o resto.

Antes e depois

Antes vs Depois - arquivos .md espalhados vs Spectrum centralizado

$ spm search --semantic "onde parei no projeto de pagamentos"
→ active/api-pagamentos: "Webhook retry, src/webhooks/retry.ts, falta testes"

$ spm search --semantic "por que escolhemos esse ORM"
→ project:api-pagamentos/decisao-orm: "Drizzle > Prisma: 3x mais rápido..."

$ spm list project:api-pagamentos
→ stack, arquitetura, decisao-orm, webhook-design, deploy-config
Enter fullscreen mode Exit fullscreen mode

Um lugar. Pesquisável. Semântico. Funciona em qualquer agente.

E pra produção?

Tudo que mostrei aqui roda 100% local: SQLite, embeddings 384D, zero dependência de internet. Perfeito pra uso pessoal e times pequenos.

Mas o Spectrum foi projetado pra ir além. A versão Spectrum Cloud roda em infraestrutura distribuída com:

  • API REST completa
  • Busca híbrida (70% semântica + 30% keyword)
  • Embeddings 1024D (bge-large-en-v1.5)
  • Multi-tenant — isolamento por organização
  • Pronto pra integrar em aplicações reais em produção

A API é a mesma. O que muda é a escala. Se você começou local e precisa escalar pra time ou produto, a transição é direta.

Quer saber mais? Entre em contato ou acompanhe o GitHub.

FAQ

"Por que SQLite e não Postgres/Pinecone/etc?"
Escolha deliberada. SQLite roda em qualquer lugar, sem server, sem config, sem Docker. Um arquivo. WAL mode pra performance. Pra uso pessoal com milhares de memórias, é mais que suficiente. E a arquitetura é plugável: quer escalar pra time ou produção, troca o backend sem mudar a API.

"Precisa de internet?"
Não. Tudo local: banco, embeddings, busca semântica. 100% offline.

"E se eu usar mais de um agente?"
É exatamente o ponto. Todos conectam no mesmo banco via MCP. Memória compartilhada.

"Substituiu os .md?"
Não necessariamente. Arquivos de instrução na raiz do projeto ainda são úteis pra regras fixas. Spectrum é pra tudo que é dinâmico: sessões, decisões, contexto, estado.

"Node ou Python?"
Os dois leem e escrevem no mesmo banco (~/.spectrum/spectrum.db). Escolhe o que preferir. Mesma API, mesmas ferramentas.

Links

O que Onde
GitHub github.com/Natiwo/spectrum
npm @natiwo/spectrum-memory
PyPI spectrum-memory
GitHub (Python) github.com/Natiwo/spectrum-memory

Sobre

Feito por Claudiomar Estevam. Pesquisador independente em AI-Native Infrastructure e Cognitive Systems. Pai. Neurodivergente (TDAH + Altas Habilidades). 22+ anos construindo infraestrutura, segurança e arquitetura de software.

Spectrum nasceu da necessidade real de não perder contexto entre sessões, projetos e ferramentas. Se ajudar mais alguém, já valeu.

Natiwo — Projetado com mentes neurodivergentes em mente, construído para todos.

Dúvida? Quer trocar ideia? LinkedIn

Quer contribuir ou implementar em outra linguagem? O repo tá aberto.

MIT License. Usa, modifica, compartilha.

Top comments (0)