SimpleMem/docs/i18n/README.pt-br.md at main · aiming-lab/SimpleMem

Memória Vitalícia Eficiente para Agentes LLM — Texto e Multimodal

Armazene, comprima e recupere memórias de longo prazo com compressão semântica sem perdas. Agora com suporte multimodal para texto, imagem, áudio e vídeo.

Funciona com qualquer plataforma de IA que suporte MCP (memória de texto) ou integração Python (multimodal completo)

_{Claude Desktop}

_Cursor

_{LM Studio}

_{Cherry Studio}

_{Pacote PyPI}

_{+ Qualquer Cliente
MCP}

🇨🇳 中文 • 🇯🇵 日本語 • 🇰🇷 한국어 • 🇪🇸 Español • 🇫🇷 Français • 🇩🇪 Deutsch • 🇧🇷 Português
🇷🇺 Русский • 🇸🇦 العربية • 🇮🇹 Italiano • 🇻🇳 Tiếng Việt • 🇹🇷 Türkçe • 🇺🇸 English

🚀 Início Rápido • 🌟 Visão Geral • 📦 Instalação • 🔌 Servidor MCP • 📊 Reproduzir • 📝 Citação

🔥 Novidades

[05/21/2026] 📦 Pacote simplemem unificado — uma importação, roteamento automático! SimpleMem, Omni-SimpleMem e EvolveMem agora vivem em um único pacote. from simplemem import SimpleMem seleciona automaticamente o backend de texto ou multimodal com base no primeiro método chamado, e simplemem.optimize(...) acessa o loop de auto-evolução do EvolveMem. Instale em uma etapa com pip install -e ..
[05/14/2026] 🧬 EvolveMem (v3.0) — Memória Auto-Evolutiva via AutoResearch! A própria infraestrutura de recuperação agora se auto-evolui por meio de diagnóstico em loop fechado guiado por LLM. No LoCoMo, o EvolveMem supera o baseline mais forte em +25,7% relativo; no MemBench, em +18,9% relativo. O sistema descobre dimensões de recuperação totalmente novas, não presentes no design original. Ver EvolveMem →
[04/02/2026] 🧠 Omni-SimpleMem (v2.0) — Memória Multimodal chegou! O SimpleMem agora suporta memória de texto, imagem, áudio e vídeo. Alcançando novo SOTA no LoCoMo (F1=0,613, +47%) e Mem-Gallery (F1=0,810, +51%) em relação ao melhor anterior. Ver Omni-SimpleMem →
[02/09/2026] 🚀 Memória Cross-Session — Superando Claude-Mem em 64%! Ver Documentação Cross-Session →
[01/20/2026] 📦 SimpleMem agora está disponível no PyPI! Instale via pip install simplemem. Ver Guia de Uso do Pacote →
[01/14/2026] 🎉 Servidor MCP do SimpleMem está NO AR! Hospedado na nuvem em mcp.simplemem.cloud. Ver Documentação MCP →
[01/05/2026] O artigo do SimpleMem foi publicado no arXiv!

🚀 Início Rápido

🧠 Entendendo o Fluxo de Trabalho Básico

Em alto nível, o SimpleMem funciona como um sistema de memória de longo prazo para agentes baseados em LLM. O fluxo de trabalho consiste em três etapas simples:

Armazenar informações – Diálogos ou fatos são processados e convertidos em memórias estruturadas e atômicas.
Indexar memória – As memórias armazenadas são organizadas usando embeddings semânticos e metadados estruturados.
Recuperar memória relevante – Quando uma consulta é feita, o SimpleMem recupera as informações armazenadas mais relevantes com base no significado, e não em palavras-chave.

Esse design permite que agentes LLM mantenham contexto, recuperem informações passadas de forma eficiente e evitem processar repetidamente histórico redundante.

🎓 Uso Básico

O SimpleMem é fornecido como um único pacote simplemem. O mode="auto" padrão detecta automaticamente qual backend usar com base no que você chama — sem necessidade de configuração manual:

from simplemem import SimpleMem

mem = SimpleMem()  # mode="auto" — backend escolhido pela primeira chamada

O primeiro método que você chamar determina o backend:

Primeira chamada	Backend selecionado	Por quê
`add_dialogue()`	Texto (SimpleMem)	API baseada em diálogo → modo texto
`add_text()` / `add_image()` / `add_audio()` / `add_video()`	Omni (Omni-SimpleMem)	API multimodal → modo omni

📝 Auto → Texto (entrada somente texto)

from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_dialogue() → backend de texto selecionado automaticamente
mem.add_dialogue(
    "Alice",
    "Bob, let's meet at Starbucks tomorrow at 2pm",
    "2025-11-15T14:30:00",
)
mem.add_dialogue(
    "Bob",
    "Sure, I'll bring the market analysis report",
    "2025-11-15T14:31:00",
)
mem.finalize()

answer = mem.ask("When and where will Alice and Bob meet?")
# → "16 November 2025 at 2:00 PM at Starbucks"

🧠 Auto → Omni (entrada multimodal)

from simplemem import SimpleMem

mem = SimpleMem()  # auto mode

# add_image() → backend omni selecionado automaticamente
mem.add_text(
    "User loves hiking in the Rocky Mountains.",
    tags=["session_id:D1"],
)
mem.add_image("photo.jpg", tags=["session_id:D1"])
mem.add_audio("voice_note.wav", tags=["session_id:D1"])

result = mem.query("What does the user enjoy?", top_k=5)
for item in result.items:
    print(item["summary"])

mem.close()

💡 Dica: O modo auto escolhe o backend mais leve que se adequa aos seus dados. Você ainda pode usar mode="text" ou mode="omni" explicitamente se preferir.

🧬 Avançado: Otimizar a Configuração de Recuperação

Ajuste os hiperparâmetros de recuperação offline no seu próprio conjunto de desenvolvimento e, em seguida, implante a Config resultante para inferência. Este é um wrapper fino em torno do loop de auto-evolução do EvolveMem:

import simplemem
from simplemem import SimpleMem, load_config

# mem é uma instância SimpleMem finalizada com memórias já construídas
dev_questions = [
    ("When is the meeting?", "2pm tomorrow at Starbucks"),
    ("What should Bob prepare?", "market analysis report"),
]
config = simplemem.optimize(mem, dev_questions, max_rounds=3)
config.save("my_config.json")

# Posteriormente, implante com a configuração otimizada
config = load_config("my_config.json")
mem = SimpleMem(config=config)

O EvolveMem executa um ciclo Avaliar → Diagnosticar → Propor → Guardar guiado por LLM sobre suas perguntas de desenvolvimento, ajustando flags globais de recuperação (top_k, modo de fusão, verificação de resposta, rodadas de reflexão, ...). Para a versão standalone completa com adaptadores de benchmark e substituições por categoria, veja EvolveMem/.

🚄 Avançado: Processamento Paralelo

Para processamento de diálogos em larga escala, ative o modo paralelo:

from simplemem import create

mem = create(
    mode="text",
    clear_db=True,
    enable_parallel_processing=True,  # ⚡ Construção de memória paralela
    max_parallel_workers=8,
    enable_parallel_retrieval=True,   # 🔍 Execução de consulta paralela
    max_retrieval_workers=4
)

💡 Dica Pro: O processamento paralelo reduz significativamente a latência para operações em lote!

🌟 Visão Geral

SimpleMem é uma pilha de memória unificada para agentes LLM, construída em um princípio: armazenar memória semanticamente sem perdas com alta densidade de informação, para que um agente se lembre mais enquanto gasta muito menos tokens. O pacote reúne três trabalhos que compartilham esse princípio, mas atacam diferentes partes do problema.

📝 SimpleMem: o núcleo de eficiência (texto)

A maioria dos sistemas de memória impõe uma troca ruim. Eles acumulam passivamente o histórico bruto de interações (redundante, consumidor de tokens) ou executam loops de raciocínio caros para filtrar ruído (lento, custoso). O SimpleMem, em vez disso, comprime as interações por meio de um pipeline de três estágios:

Estágio	O que faz
1. Compressão Estruturada Semântica	Destila interações não estruturadas em unidades de memória compactas (fatos auto-contidos com correferências resolvidas e carimbos de tempo absolutos), cada um indexado por múltiplas visões complementares para recuperação flexível.
2. Síntese Semântica Online	Mescla contexto relacionado dentro de uma sessão em representações abstratas unificadas, removendo redundância conforme a memória é construída, e não no momento da consulta.
3. Planejamento de Recuperação Ciente de Intenção	Infere a intenção de busca por trás de uma consulta para decidir o que recuperar e montar um contexto preciso e compacto.

No benchmark LoCoMo, isso resulta em um ganho médio de F1 de 26,4% em relação a sistemas anteriores, enquanto reduz o consumo de tokens em tempo de inferência em aproximadamente 30x. Detalhes do mecanismo (camadas de índice híbrido, exemplos de compressão, planejamento de recuperação): Memória de texto SimpleMem →.

🧠 Omni-SimpleMem: memória multimodal (texto, imagem, áudio, vídeo)

O Omni-SimpleMem estende a filosofia de compressão-primeiro para quatro modalidades, construído em três princípios: Ingestão Seletiva (filtragem guiada por entropia por modalidade), Recuperação Progressiva (FAISS híbrido + BM25 com expansão de orçamento de token em pirâmide) e Aumento por Grafo de Conhecimento (raciocínio multi-hop cross-modal). Em vez de ser projetado manualmente, sua arquitetura foi descoberta por um pipeline de pesquisa autônomo que realizou cerca de 50 experimentos em dois benchmarks, diagnosticando modos de falha, propondo mudanças arquiteturais e até corrigindo bugs de pipeline de dados sem nenhum ser humano no loop interno. Significativamente, as correções de bugs e as mudanças arquiteturais contribuíram mais do que todo o ajuste de hiperparâmetros combinado, levando o sistema de um baseline ingênuo ao estado da arte em ambos LoCoMo e Mem-Gallery. Documentação completa: Omni-SimpleMem →.

🧬 EvolveMem: recuperação auto-evolutiva

O EvolveMem fecha um ponto cego compartilhado por quase todos os sistemas de memória: o conteúdo armazenado evolui, mas a maquinaria de recuperação (funções de pontuação, estratégias de fusão, políticas de geração de resposta) permanece congelada após a implantação. O EvolveMem executa um processo fechado de AutoResearch (Avaliar → Diagnosticar → Propor → Guardar → Repetir) no qual um LLM diagnostica falhas por questão e propõe mudanças de configuração, protegido por rollback automático em caso de regressão e incentivos de exploração durante estagnação. Ele descobre novas dimensões de recuperação (decomposição de consulta, troca de entidade, verificação de resposta) não presentes no design original, melhora o LoCoMo em 25,7% relativo em relação ao baseline mais forte, e suas configurações evoluídas transferem positivamente entre benchmarks. Documentação completa: EvolveMem →.

Como se encaixam

from simplemem import SimpleMem fornece o núcleo de texto com roteamento automático para o backend multimodal, e simplemem.optimize(...) acessa o EvolveMem para ajustar a recuperação para seus próprios dados. Um pacote, um modelo mental: comprima sem perdas, recupere por intenção e deixe o sistema continuar melhorando a si mesmo.

📦 Instalação

📝 Notas para Novos Usuários

Certifique-se de estar usando Python 3.10+ em seu ambiente ativo, não apenas instalado globalmente.
Uma chave de API compatível com OpenAI deve ser configurada antes de executar qualquer construção de memória ou recuperação, caso contrário a inicialização pode falhar.
Ao usar provedores não-OpenAI (ex.: Qwen ou Azure OpenAI), verifique tanto o nome do modelo quanto o OPENAI_BASE_URL em config.py.
Para grandes conjuntos de dados de diálogo, ativar o processamento paralelo pode reduzir significativamente o tempo de construção de memória.

📋 Requisitos

🐍 Python 3.10+
🔑 API compatível com OpenAI (OpenAI, Qwen, Azure OpenAI, etc.)

🛠️ Configuração

# 📥 Clonar repositório
git clone https://github.com/aiming-lab/SimpleMem.git
cd SimpleMem

# 📦 Instalar dependências (versões fixadas)
pip install -r requirements.txt

# — OU — instalar como pacote editável
pip install -e .                  # padrão: texto + multimodal + evolver
pip install -e ".[server]"        # + servidor MCP / HTTP (mcp, fastapi, ...)
pip install -e ".[all]"           # tudo, incluindo ferramentas de desenvolvimento

# ⚙️ Configurar ajustes da API
cp config.py.example config.py
# Edite config.py com sua chave de API e preferências

⚙️ Exemplo de Configuração

# config.py
OPENAI_API_KEY = "your-api-key"
OPENAI_BASE_URL = None  # ou endpoint personalizado para Qwen/Azure

LLM_MODEL = "gpt-4.1-mini"
EMBEDDING_MODEL = "Qwen/Qwen3-Embedding-0.6B"  # Recuperação de ponta

🐳 Executar com Docker

O Servidor MCP pode ser executado no Docker para um ambiente consistente e isolado. Os dados (LanceDB e banco de dados do usuário) são persistidos em um volume do host.

Pré-requisitos

Docker e Docker Compose

Execução rápida

# Da raiz do repositório
docker compose up -d

Interface Web: http://localhost:8000/
API REST: http://localhost:8000/api/
MCP (SSE): http://localhost:8000/mcp/sse?token=<TOKEN>

Os dados são armazenados em ./data no host (criado automaticamente).

Configuração personalizada

Copie o template de ambiente e edite-o:

cp .env.example .env
# Edite .env: defina JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, URLs de modelo, etc.

Execute com o arquivo de ambiente:
```
docker compose --env-file .env up -d
```

Usando Ollama no host

Quando LLM_PROVIDER=ollama e o Ollama está rodando na sua máquina (não no Docker), defina em .env:

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://host.docker.internal:11434/v1

No Linux, host.docker.internal é habilitado automaticamente via arquivo Compose.

Comandos úteis

docker compose logs -f simplemem   # Acompanhar logs
docker compose down                 # Parar e remover contêineres

📖 Para auto-hospedagem do servidor MCP (Docker ou bare metal), veja Documentação MCP.

🔌 Servidor MCP (memória de texto)

O SimpleMem está disponível como um serviço de memória hospedado na nuvem via o Model Context Protocol (MCP), permitindo integração perfeita com assistentes de IA como Claude Desktop, Cursor e outros clientes compatíveis com MCP.

🌐 Serviço em Nuvem: mcp.simplemem.cloud — ou auto-hospede o servidor MCP localmente usando Docker.

Funcionalidades Principais

Funcionalidade	Descrição
HTTP Streamable	Protocolo MCP 2025-03-26 com JSON-RPC 2.0
Isolamento Multi-tenant	Tabelas de dados por usuário com autenticação por token
Recuperação Híbrida	Busca semântica + correspondência de palavras-chave + filtragem por metadados
Otimizado para Produção	Tempos de resposta mais rápidos com integração OpenRouter

Configuração Rápida

{
  "mcpServers": {
    "simplemem": {
      "url": "https://mcp.simplemem.cloud/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

📖 Para instruções detalhadas de configuração e guia de auto-hospedagem, veja Documentação MCP

📊 Reproduzir Resultados do Artigo

Reproduza os números do LoCoMo / MemBench / Mem-Gallery dos artigos. Cada pilar tem seu próprio executor de benchmark em seu próprio diretório. Instale os extras de benchmark primeiro: pip install -e ".[benchmark]".

📝 SimpleMem (texto) — LoCoMo

Execute da raiz do repositório:

python test_locomo10.py                       # benchmark LoCoMo completo
python test_locomo10.py --num-samples 5       # subconjunto rápido
python test_locomo10.py --result-file my_results.json

🧬 EvolveMem — auto-evolução + LoCoMo / MemBench

Execute do diretório EvolveMem/ (veja EvolveMem/README.md):

cd EvolveMem
python run_evolution.py --data data/locomo10.json --max-rounds 7
python run_benchmark.py locomo --sample 0 --initial weak --max-rounds 3
python run_benchmark.py membench --agent FirstAgent --max-rounds 3

🧠 Omni-SimpleMem — LoCoMo / Mem-Gallery

Execute do diretório OmniSimpleMem/ (veja OmniSimpleMem/README.md):

cd OmniSimpleMem
python benchmarks/locomo/run_locomo.py --data-path /path/to/locomo10.json --model gpt-4o

🗺️ Roteiro

Capacidade atual por canal de integração:

Capacidade	Python (`pip install`)	Servidor MCP (Claude Desktop, Cursor, ...)
Memória de texto	✅	✅
Multimodal (imagem / áudio / vídeo)	✅	⬜ planejado
Recuperação auto-evolutiva `optimize()`	✅	⬜ planejado

Trabalho planejado para fechar a lacuna (o servidor MCP é um serviço de texto multi-tenant standalone; estes são recursos reais, não correções de documentação):

Multimodal via MCP. Adicionar ferramentas memory_add_image / memory_add_audio / memory_add_video. Requer um caminho de upload de arquivo (base64 ou URL, já que o MCP não pode passar caminhos de arquivo locais), uma adaptação multi-tenant do backend de armazenamento do Omni-SimpleMem e acesso a modelos de visão/áudio no lado do servidor.
EvolveMem via MCP. Expor optimize() como uma ferramenta MCP. Mais tratável do que multimodal (texto de entrada, configuração JSON de saída, sem transporte de arquivo), mas o recuperador MCP atualmente honra apenas semantic_top_k / keyword_top_k das ~10 dimensões que o EvolveMem evolui. Requer estender o recuperador MCP para suportar os demais controles (structured top_k, modo/pesos de fusão, troca de entidade, decomposição de consulta, verificação de resposta), um adaptador para executar o loop de evolução sobre memórias armazenadas de um tenant, persistência de configuração por tenant e execução assíncrona (o loop é intensivo em LLM e excederia o tempo limite de uma requisição síncrona).
Docker herda ambos automaticamente assim que o servidor MCP os suportar (adicionar dependências multimodais à imagem e um volume de armazenamento Omni).

Para multimodal completo e recuperação auto-evolutiva hoje, use a API Python (veja Início Rápido).

📝 Citação

Se você usar o SimpleMem em sua pesquisa, por favor cite:

@article{simplemem2026,
  title={SimpleMem: Efficient Lifelong Memory for LLM Agents},
  author={Liu, Jiaqi and Su, Yaofeng and Xia, Peng and Zhou, Yiyang and Han, Siwei and  Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu},
  journal={arXiv preprint arXiv:2601.02553},
  year={2026},
  url={https://arxiv.org/abs/2601.02553}
}

@article{evolvemem2026,
  title={EvolveMem: Self-Evolving Memory Architecture via AutoResearch for LLM Agents},
  author={Liu, Jiaqi and Ye, Xinyu and Xia, Peng and Zheng, Zeyu and Xie, Cihang and Ding, Mingyu and Yao, Huaxiu},
  journal={arXiv preprint arXiv:2605.13941},
  year={2026},
  url={https://arxiv.org/abs/2605.13941}
}

@article{omnisimplemem2026,
  title   = {Omni-SimpleMem: Autoresearch-Guided Discovery of Lifelong Multimodal Agent Memory},
  author  = {Liu, Jiaqi and Ling, Zipeng and Qiu, Shi and Liu, Yanqing and Han, Siwei and Xia, Peng and Tu, Haoqin and Zheng, Zeyu and Xie, Cihang and Fleming, Charles and Ding, Mingyu and Yao, Huaxiu},
  journal = {arXiv preprint arXiv:2604.01007},
  year    = {2026},
}

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

Gostaríamos de agradecer aos seguintes projetos e equipes:

🔍 Modelo de Embedding: Qwen3-Embedding - Desempenho de recuperação de ponta
🗄️ Banco de Dados Vetorial: LanceDB - Armazenamento colunar de alto desempenho
📊 Benchmark: LoCoMo - Framework de avaliação de memória de longo contexto

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Memória Vitalícia Eficiente para Agentes LLM — Texto e Multimodal

🔥 Novidades

📑 Índice

🚀 Início Rápido

🧠 Entendendo o Fluxo de Trabalho Básico

🎓 Uso Básico

🧬 Avançado: Otimizar a Configuração de Recuperação

🚄 Avançado: Processamento Paralelo

🌟 Visão Geral

📝 SimpleMem: o núcleo de eficiência (texto)

🧠 Omni-SimpleMem: memória multimodal (texto, imagem, áudio, vídeo)

🧬 EvolveMem: recuperação auto-evolutiva

Como se encaixam

📦 Instalação

📝 Notas para Novos Usuários

📋 Requisitos

🛠️ Configuração

⚙️ Exemplo de Configuração

🐳 Executar com Docker

Pré-requisitos

Execução rápida

Configuração personalizada

Usando Ollama no host

Comandos úteis

🔌 Servidor MCP (memória de texto)

Funcionalidades Principais

Configuração Rápida

📊 Reproduzir Resultados do Artigo

📝 SimpleMem (texto) — LoCoMo

🧬 EvolveMem — auto-evolução + LoCoMo / MemBench

🧠 Omni-SimpleMem — LoCoMo / Mem-Gallery

🗺️ Roteiro

📝 Citação

📄 Licença

🙏 Agradecimentos

Uh oh!

FilesExpand file tree

README.pt-br.md

Latest commit

History

README.pt-br.md

File metadata and controls

Memória Vitalícia Eficiente para Agentes LLM — Texto e Multimodal

🔥 Novidades

📑 Índice

🚀 Início Rápido

🧠 Entendendo o Fluxo de Trabalho Básico

🎓 Uso Básico

🧬 Avançado: Otimizar a Configuração de Recuperação

🚄 Avançado: Processamento Paralelo

🌟 Visão Geral

📝 SimpleMem: o núcleo de eficiência (texto)

🧠 Omni-SimpleMem: memória multimodal (texto, imagem, áudio, vídeo)

🧬 EvolveMem: recuperação auto-evolutiva

Como se encaixam

📦 Instalação

📝 Notas para Novos Usuários

📋 Requisitos

🛠️ Configuração

⚙️ Exemplo de Configuração

🐳 Executar com Docker

Pré-requisitos

Execução rápida

Configuração personalizada

Usando Ollama no host

Comandos úteis

🔌 Servidor MCP (memória de texto)

Funcionalidades Principais

Configuração Rápida

📊 Reproduzir Resultados do Artigo

📝 SimpleMem (texto) — LoCoMo

🧬 EvolveMem — auto-evolução + LoCoMo / MemBench

🧠 Omni-SimpleMem — LoCoMo / Mem-Gallery

🗺️ Roteiro

📝 Citação

📄 Licença

🙏 Agradecimentos