## 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}

[🇨🇳 中文](./README.zh-CN.md) • [🇯🇵 日本語](./README.ja.md) • [🇰🇷 한국어](./README.ko.md) • [🇪🇸 Español](./README.es.md) • [🇫🇷 Français](./README.fr.md) • [🇩🇪 Deutsch](./README.de.md) • **🇧🇷 Português**
[🇷🇺 Русский](./README.ru.md) • [🇸🇦 العربية](./README.ar.md) • [🇮🇹 Italiano](./README.it.md) • [🇻🇳 Tiếng Việt](./README.vi.md) • [🇹🇷 Türkçe](./README.tr.md) • [🇺🇸 English](../../README.md)
[![Página do Projeto](https://img.shields.io/badge/🎬_DEMO_INTERATIVO-Visite_Nosso_Site-FF6B6B?style=for-the-badge&labelColor=FF6B6B&color=4ECDC4&logoColor=white)](https://aiming-lab.github.io/SimpleMem-Page)

[🚀 Início Rápido](#-início-rápido) • [🌟 Visão Geral](#-visão-geral) • [📦 Instalação](#-instalação) • [🔌 Servidor MCP](#-servidor-mcp-memória-de-texto) • [📊 Reproduzir](#-reproduzir-resultados-do-artigo) • [📝 Citação](#-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 →](../../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 →](../../OmniSimpleMem/) - **[02/09/2026]** 🚀 **Memória Cross-Session — Superando Claude-Mem em 64%!** [Ver Documentação Cross-Session →](../../cross/README.md) - **[01/20/2026]** 📦 **SimpleMem agora está disponível no PyPI!** Instale via `pip install simplemem`. [Ver Guia de Uso do Pacote →](../PACKAGE_USAGE.md) - **[01/14/2026]** 🎉 **Servidor MCP do SimpleMem está NO AR!** Hospedado na nuvem em [mcp.simplemem.cloud](https://mcp.simplemem.cloud). [Ver Documentação MCP →](../../MCP/README.md) - **[01/05/2026]** O artigo do SimpleMem foi publicado no [arXiv](https://arxiv.org/abs/2601.02553)! --- ## 📑 Índice - [🚀 Início Rápido](#-início-rápido) - [🌟 Visão Geral](#-visão-geral) - [📦 Instalação](#-instalação) - [🐳 Docker](#-executar-com-docker) - [🔌 Servidor MCP](#-servidor-mcp-memória-de-texto) - [📊 Reproduzir Resultados do Artigo](#-reproduzir-resultados-do-artigo) - [🗺️ Roteiro](#️-roteiro) - [📝 Citação](#-citação) --- ## 🚀 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: 1. **Armazenar informações** – Diálogos ou fatos são processados e convertidos em memórias estruturadas e atômicas. 2. **Indexar memória** – As memórias armazenadas são organizadas usando embeddings semânticos e metadados estruturados. 3. **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: ```python 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) ```python 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) ```python 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: ```python 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/`](../../EvolveMem/). --- ### 🚄 Avançado: Processamento Paralelo Para processamento de diálogos em larga escala, ative o modo paralelo: ```python 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 →**](../text-memory.md). ### 🧠 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 →**](../../OmniSimpleMem/). ### 🧬 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 →**](../../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 ```bash # 📥 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 ```python # 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](https://docs.docker.com/get-docker/) e [Docker Compose](https://docs.docker.com/compose/install/) ### Execução rápida ```bash # 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 1. Copie o template de ambiente e edite-o: ```bash cp .env.example .env # Edite .env: defina JWT_SECRET_KEY, ENCRYPTION_KEY, LLM_PROVIDER, URLs de modelo, etc. ``` 2. Execute com o arquivo de ambiente: ```bash 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`: ```bash LLM_PROVIDER=ollama OLLAMA_BASE_URL=http://host.docker.internal:11434/v1 ``` No Linux, `host.docker.internal` é habilitado automaticamente via arquivo Compose. ### Comandos úteis ```bash 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](../../MCP/README.md). --- ## 🔌 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](https://mcp.simplemem.cloud) — ou auto-hospede o servidor MCP localmente usando [Docker](#-executar-com-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 ```json { "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](../../MCP/README.md) --- ## 📊 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: ```bash 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`](../../EvolveMem/README.md)): ```bash 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`](../../OmniSimpleMem/README.md)): ```bash 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](#-início-rápido)). --- ## 📝 Citação Se você usar o SimpleMem em sua pesquisa, por favor cite: ```bibtex @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} } ``` ```bibtex @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} } ``` ```bibtex @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](../../LICENSE) para detalhes. --- ## 🙏 Agradecimentos Gostaríamos de agradecer aos seguintes projetos e equipes: - 🔍 **Modelo de Embedding**: [Qwen3-Embedding](https://github.com/QwenLM/Qwen) - Desempenho de recuperação de ponta - 🗄️ **Banco de Dados Vetorial**: [LanceDB](https://lancedb.com/) - Armazenamento colunar de alto desempenho - 📊 **Benchmark**: [LoCoMo](https://github.com/snap-research/locomo) - Framework de avaliação de memória de longo contexto