agentmem

agentmem

Memória compartilhada para Claude Code, Cursor e Codex que sabe o que ainda é verdadeiro. Salve sessões, detecte regras desatualizadas e conflitantes e impeça seu agente de repetir erros antigos.

O Problema

Seu assistente de codificação com IA esquece tudo entre sessões. Ele repete erros antigos. Não consegue distinguir regras atuais de regras desatualizadas. O contexto é comprimido e a recuperação é dolorosa.

A maioria das ferramentas de memória resolve armazenamento. agentmem resolve confiança.

Comece Agora (Claude Code / Cursor / Codex)

pip install quilmem[mcp]
agentmem init --tool claude --project myapp

É só isso. Reinicie seu editor. Seu agente agora tem 13 ferramentas de memória. Execute memory_health para confirmar.

Somente Python? pip install quilmem funciona sem o extra do MCP. Veja a API Python abaixo.

Demonstração de 60 Segundos

from agentmem import Memory

mem = Memory()

# Store typed memories
mem.add(type="bug", title="loudnorm undoes SFX levels",
        content="Never apply loudnorm to final mix. It re-normalizes everything.",
        status="validated")

mem.add(type="decision", title="Use per-line atempo",
        content="Bake speed into per-line TTS. No global pass.",
        status="active")

# Something you're not sure about yet
hypothesis = mem.add(type="decision", title="Maybe try 2-second gaps before CTA",
        content="Hypothesis from last session. Needs testing.",
        status="hypothesis")

# Search — validated and active memories rank highest.
# Deprecated and superseded memories are excluded automatically.
results = mem.search("audio mixing")

# Context-budgeted recall — fits the best memories into your token limit
context = mem.recall("building a narration track", max_tokens=2000)

# Lifecycle — promote what's proven, deprecate what's not
mem.promote(hypothesis.id)                # hypothesis -> active -> validated
mem.deprecate(hypothesis.id, reason="Disproven by data")

# Supersede: replace an outdated memory with a newer one
replacement = mem.add(type="decision", title="Use 1-second gaps before CTA",
        content="Confirmed by A/B test.", status="active")
mem.supersede(hypothesis.id, replacement.id)  # old points to replacement

# Health check — is your memory system trustworthy?
from agentmem import health_check
report = health_check(mem._conn)
# Health: 85/100 | Conflicts: 0 | Stale: 2 | Validated: 14

O Que Torna Isso Diferente

Outras ferramentas de memória armazenam coisas. agentmem sabe o que ainda é verdadeiro.

	Mem0	Letta	Mengram	agentmem
Armazenamento de memória	Sim	Sim	Sim	Sim
Busca em texto completo	Vetorial	Orientada por agente	Grafo de conhecimento	FTS5
Estados do ciclo de vida da memória	Não	Parcial	Não	hypothesis -> active -> validated -> deprecated -> superseded
Detecção de conflitos	Não	Não	Parcial	Integrada
Detecção de desatualização	Não	Não	Não	Integrada
Pontuação de saúde	Não	Não	Não	Integrada
Rastreamento de proveniência	Não	Não	Não	source_path + source_hash
Recuperação classificada por confiança	Não	Não	Não	Validated > active > hypothesis
Arquivos de origem legíveis por humanos	Não	Não	Não	Markdown canônico
Local-first, zero infraestrutura	Não	Opção self-host	Opção self-host	Sim, sempre
Servidor MCP	Separado	Separado	Sim	Integrado

Governança da Verdade

A ideia central: cada memória tem um status que rastreia o quanto você deve confiar nela.

hypothesis    New observation. Not yet confirmed. Lowest trust in recall.
    |
  active      Default. Currently believed true. Normal trust.
    |
 validated    Explicitly confirmed. Highest trust in recall.

 deprecated   Was true, no longer. Excluded from recall. Kept for history.
 superseded   Replaced by a newer memory. Points to replacement.

Por que isso importa: Sem governança, a memória do seu agente acumula regras desatualizadas, contradições e decisões ultrapassadas. Ele não sabe que a configuração de voz de janeiro foi substituída em março. Ele recupera ambas e o LLM escolhe aleatoriamente. Memória governada resolve isso.

Detecção de Conflitos

from agentmem import detect_conflicts

conflicts = detect_conflicts(mem._conn)
# Found 2 conflict(s):
#   !! [decision] "Always apply loudnorm to voice"
#      vs [decision] "NEVER apply loudnorm to voice"
#      Contradiction on shared topic (voice, loudnorm, audio)

agentmem encontra memórias que se contradizem:

• Detecta sobreposição de tópicos (similaridade de Jaccard)
• Separa duplicatas de contradições
• Correspondência de negação em nível de frase (não apenas varredura de palavras-chave)
• Gravidade: critical (ambas ativas) vs warning (uma descontinuada)

Detecção de Desatualização

from agentmem import detect_stale

stale = detect_stale(mem._conn, stale_days=30)
# [decision] "Use atempo 0.90" — Source changed since import (hash mismatch)
# [bug] "Firewall blocks port" — Not updated in 45 days

Encontra memórias desatualizadas por:

• Idade (não atualizada em N dias)
• Arquivo de origem ausente (o arquivo referenciado foi excluído)
• Desvio de hash (o conteúdo do arquivo de origem mudou, mas a memória não foi atualizada)

Verificação de Saúde

from agentmem import health_check

report = health_check(mem._conn)
print(f"Health: {report.health_score}/100")
print(f"Conflicts: {len(report.conflicts)}")
print(f"Stale: {len(report.stale)}")

Pontua seu sistema de memória de 0 a 100 com base em: conflitos, porcentagem de desatualização, referências órfãs, peso de descontinuados e se você tem alguma memória validada.

Sincronização Ciente de Proveniência

Sincronize arquivos markdown canônicos no banco de dados com rastreamento de origem:

# Each memory tracks where it came from
mem.add(type="bug", title="loudnorm lifts noise",
        content="...",
        source_path="/docs/errors.md",
        source_section="Audio Bugs",
        source_hash="a1b2c3d4e5f6")

O mecanismo de sincronização:

• Mesmo hash = ignorar (idempotente, reexecutar não muda nada)
• Hash diferente = atualizar (arquivo de origem alterado)
• Seção removida = descontinuar (com motivo)
• Seção restaurada = ressuscitar (reativa memória descontinuada)

Três Interfaces

Python API

from agentmem import Memory

mem = Memory("./my-agent.db", project="frontend")

# CRUD
record = mem.add(type="decision", title="Use TypeScript", content="...")
mem.get(record.id)
mem.update(record.id, content="Updated reasoning.")
mem.delete(record.id)
mem.list(type="bug", limit=20)

# Search + recall
results = mem.search("typescript migration", type="decision")
context = mem.recall("setting up the build", max_tokens=3000)

# Governance
mem.promote(record.id)              # hypothesis -> active -> validated
mem.deprecate(record.id, reason="No longer relevant")
replacement = mem.add(type="decision", title="Use v2 approach", content="...")
mem.supersede(record.id, replacement.id)  # links old to replacement

# Session persistence
mem.save_session("Working on auth refactor. Blocked on token refresh.")
mem.load_session()                  # picks up where last instance left off

# Health
mem.stats()

CLI

# Get started in 30 seconds
agentmem init --tool claude --project myapp

# Check if everything's working
agentmem doctor

# Core
agentmem add --type bug --title "CSS grid issue" "Flexbox fallback needed"
agentmem search "grid layout"
agentmem recall "frontend styling" --tokens 2000

# Governance
agentmem promote <id>
agentmem deprecate <id> --reason "Fixed in v2.3"
agentmem health
agentmem conflicts
agentmem stale --days 14

# Import + sessions
agentmem import ./errors.md --type bug
agentmem save-session "Finished auth module, starting tests"
agentmem load-session

# MCP server
agentmem serve

Servidor MCP

Servidor Model Context Protocol integrado para Claude Code, Cursor e qualquer cliente MCP.

pip install quilmem[mcp]

Configuração do Claude Code (.claude/settings.json):

{
  "mcpServers": {
    "agentmem": {
      "command": "agentmem",
      "args": ["--db", "./memory.db", "--project", "myproject", "serve"],
      "type": "stdio"
    }
  }
}

Ferramentas MCP: add_memory, search_memory, recall_memory, update_memory, delete_memory, list_memories, save_session, load_session, promote_memory, deprecate_memory, supersede_memory, memory_health, memory_conflicts

Ensine seu agente a usar memória: Copie as instruções do agente para o seu CLAUDE.md, .cursorrules ou AGENTS.md. Isso ensina ao seu agente o protocolo de sessão, a hierarquia de confiança e quando buscar versus adicionar.

Memória Tipada

Sete tipos que cobrem fluxos de trabalho reais de agentes:

Tipo	O que armazena	Exemplo
setting	Configuração, parâmetros	"Velocidade de voz: atempo 1.08"
bug	Erros e suas correções	"loudnorm eleva o piso de ruído"
decision	Regras, políticas, escolhas	"Narração em 3ª pessoa proibida"
procedure	Fluxos de trabalho, pipelines	"TTS -> speed -> 48kHz -> mix"
context	Conhecimento de contexto	"Projeto usa FFmpeg + Python 3.11"
feedback	Correções do usuário	"Sempre escolha, não pergunte"
session	Estado atual do trabalho	"Trabalhando em auth. Bloqueado em tokens."

Recuperação Classificada por Confiança

recall() não apenas encontra memórias relevantes. Ele encontra as memórias relevantes mais confiáveis:

1. A busca FTS5 retorna candidatos
2. Cada uma pontuada: relevance (25%) + trust status (20%) + provenance (20%) + recency (15%) + frequency (10%) + confidence (10%)
3. Memórias canônicas validadas ficam acima de memórias de hipótese sem proveniência
4. Memórias descontinuadas e substituídas são excluídas completamente
5. Empacotadas de forma gulosa no seu orçamento de tokens

Escopo de Projeto

frontend = Memory("./shared.db", project="frontend")
backend = Memory("./shared.db", project="backend")

frontend.search("bug")  # Only frontend bugs
backend.search("bug")   # Only backend bugs

Testado em Batalha

Isso não é teórico. agentmem foi construído sob pressão de produção ao longo de 2+ meses de uso diário:

• 65+ YouTube Shorts produzidos com zero bugs de produção repetidos
• 330+ memórias governando geração de voz, montagem FFmpeg, prompts de imagem, fluxos de upload
• Cada bug capturado uma vez, corrigido uma vez, nunca repetido
• O mecanismo de governança reduziu conflitos de 1.848 falsos positivos para 11 descobertas reais

Como Funciona

• Armazenamento: SQLite com modo WAL (leituras concorrentes, thread-safe)
• Busca: FTS5 com stemming porter e tokenizador unicode61
• Classificação: Pontuação composta: relevância do texto + status de confiança + proveniência + recência + frequência + confiança
• Governança: Ciclo de vida de status, detecção de conflitos, detecção de desatualização, pontuação de saúde
• Sincronização: Ciente de proveniência com hash de origem e ressuscitação
• Zero infraestrutura: Sem chaves de API, sem nuvem, sem banco vetorial. Apenas um arquivo .db.

Licença

MIT