Robust Long‑Term Memory

Um sistema de memória persistente e semelhante ao humano para companheiros de IA

GitHub
33
Experimente este MCPPatrocinado

Documentação

Memória Robusta de Longo Prazo MCP para LM Studio

Um sistema de memória persistente, semelhante ao humano, para companheiros de IA no LM Studio, alimentado por uma combinação de SQLite (armazenamento estruturado) e ChromaDB (busca semântica). Projetado para uso por décadas, recall contínuo entre sessões e backups automáticos — fazendo seu companheiro de IA parecer uma persona contínua e viva. Agora com comportamento biológico: decaimento preguiçoso baseado no tempo e reforço pelo uso.

✨ Recursos

  • Sistema de Memória Híbrido

    • SQLite para metadados estruturados e consultas rápidas
    • ChromaDB para similaridade semântica e recall natural
    • Backups JSON para portabilidade

  • Continuidade entre conversas: memórias persistem além de uma única conversa

  • Continuidade entre modelos: troque modelos livremente, a memória permanece intacta

  • Portabilidade entre máquinas: mova o banco de dados para outro sistema e continue sem problemas

  • Backups automáticos: backups diários e após cada 100 memórias, podados para manter os últimos 10

  • Integração invisível de memória: ferramentas ocultas do usuário; conversas parecem naturais

  • Dinâmicas semelhantes às humanas

    • Decaimento Preguiçoso: a importância diminui apenas quando uma memória é acessada após tempo ocioso
    • Reforço: recall frequente fortalece a importância da memória
    • Limiar Semântico Adaptativo: equilibra precisão/recall com fallback seguro de top-1

📦 Instalação

  1. Clone o repositório: 
    git clone https://github.com/Rotoslider/long-term-memory-mcp.git
  
cd long-term-memory-mcp
  2. Install requirements:
    pip install -r requirements.txt

Requirements include:

chromadb
sentence-transformers
fastmcp
(sqlite3 is built into Python; do not install separately)

3. (Optional) For faster HuggingFace model fetching:

    pip install "huggingface_hub[hf_xet]"

🚀 Running the Memory MCP

Edit your LM Studio mcp.json to include the correct path:

    {
  "mcpServers": {
    "long_term_memory": {
      "command": "C:\\Python313\\python.exe",
      "args": [
        "D:\\a.i. apps\\long_term_memory_mcp\\LongTermMemoryMCP.py"
      ],
      "env": {}
    }
  }
}

Then, in LM Studio:

  • Open Server (MCP) Settings
  • Load the MCP Tool: "long_term_memory"

🧠 How Memory Works

  • Cross‑Chats → Start a new chat — memories are still there.
  • Cross‑Models → Switch models — the same memory remains available.
  • Cross‑Machines → Copy the database folder (memory_db/ and memory_backups/) and your system prompt, point to the path, and everything carries over.

💡 Think of it as your AI’s diary: chats are conversations, the database is the journal.

Environment variable for custom data dir:

Windows PowerShell

$env:AI_COMPANION_DATA_DIR="D:\a.i. apps\long_term_memory_mcp\data"

Linux/macOS

export AI_COMPANION_DATA_DIR="/home/username/ai_companion_data"

📂 Backups

Os backups são criados automaticamente:

  • A cada 24 horas
  • Ou após 100 novas memórias (configurável)
  • Armazenados em memory_backups/ com pastas com carimbo de data/hora
  • Apenas os últimos 10 backups são mantidos

Cada backup inclui:

  • Cópia do banco de dados SQLite
  • Cópia do ChromaDB
  • Exportação JSON de todas as memórias (portátil e à prova de futuro)

📝 Prompt de Sistema Recomendado

“Você é um companheiro de IA com memória de longo prazo. Armazene fatos naturalmente (‘Entendido, vou lembrar disso.’). Recupere-os quando solicitado em linguagem natural. Nunca exponha o uso interno de ferramentas ao usuário. Use ferramentas de memória para lembrar, recuperar e atualizar informações de forma invisível.”

🛠️ Visão Geral das Ferramentas MCP

Seu MCP RobustMemory expõe ferramentas que permitem ao seu companheiro de IA interagir com sua memória de longo prazo. Essas ferramentas são projetadas para serem chamadas internamente pelo modelo de IA com base em seu prompt de sistema, tornando o sistema de memória contínuo e invisível para o usuário.

Aqui está uma análise do propósito e parâmetros de cada ferramenta:

1. remember

  • Propósito: Armazena uma nova memória (fato, trecho de conversa, preferência, evento) no sistema. É indexada tanto semanticamente (para busca em linguagem natural) quanto estruturalmente (para consultas filtradas).
  • Parâmetros:
    • title (string, obrigatório): Um título conciso para a memória.
    • content (string, obrigatório): O conteúdo detalhado da memória.
    • tags (string, opcional, padrão: ""): Palavras-chave separadas por vírgula para categorização (ex.: "pessoal, preferência, hobby").
    • importance (inteiro, opcional, padrão: 5): Um valor numérico (1-10) indicando quão importante é a memória.
    • memory_type (string, opcional, padrão: "conversa"): Categoriza a memória (ex.: "conversa", "fato", "preferência", "evento").
  • Exemplo de Uso (interno): remember(title="User's Birthday", content="Donny's birthday is July 4th.", tags="personal, fact", importance=8)

2. search_memories

  • Propósito: A principal ferramenta para recuperar memórias. Realiza uma busca semântica com base em uma consulta em linguagem natural, encontrando memórias conceitualmente semelhantes.
  • Parâmetros:
    • query (string, obrigatório): A consulta em linguagem natural para buscar.
    • search_type (string, opcional, padrão: "semântico"): Atualmente apenas "semântico" está totalmente implementado para esta ferramenta.
    • limit (inteiro, opcional, padrão: 10): O número máximo de memórias relevantes a retornar.
  • Exemplo de Uso (interno): search_memories(query="What did Donny tell me about his favorite color?")

3. search_by_type

  • Propósito: Recupera memórias que correspondem a um memory_type específico (ex.: todos os "fatos" ou todas as "preferências").
  • Parâmetros:
    • memory_type (string, obrigatório): O tipo de memória a buscar (ex.: "conversa", "fato", "preferência").
    • limit (inteiro, opcional, padrão: 20): O número máximo de memórias a retornar.
  • Exemplo de Uso (interno): search_by_type(memory_type="fact", limit=5)

4. search_by_tags

  • Propósito: Encontra memórias associadas a uma ou mais tags específicas.
  • Parâmetros:
    • tags (string, obrigatório): Tags separadas por vírgula para buscar (ex.: "hobby, música").
    • limit (inteiro, opcional, padrão: 20): O número máximo de memórias a retornar.
  • Exemplo de Uso (interno): search_by_tags(tags="personal, family")

5. get_recent_memories

  • Propósito: Busca as memórias mais recentemente armazenadas, útil para recuperar contexto recente ou fluxo de conversa.
  • Parâmetros:
    • limit (inteiro, opcional, padrão: 20): O número máximo de memórias recentes a recuperar.
  • Exemplo de Uso (interno): get_recent_memories(limit=5)

6. update_memory

  • Propósito: Modifica uma memória existente identificada por seu memory_id único. Isso permite corrigir ou enriquecer informações armazenadas.
  • Parâmetros:
    • memory_id (string, obrigatório): O identificador único da memória a atualizar.
    • title (string, opcional): Novo título para a memória.
    • content (string, opcional): Novo conteúdo para a memória.
    • tags (string, opcional): Novas tags separadas por vírgula para a memória.
    • importance (inteiro, opcional): Novo nível de importância para a memória.
  • Exemplo de Uso (interno): update_memory(memory_id="mem_123abc", content="Donny's favorite color is now blue, not green.", importance=9)

7. delete_memory

  • Propósito: Remove permanentemente uma memória do sistema usando seu memory_id único.
  • Parâmetros:
    • memory_id (string, obrigatório): O identificador único da memória a excluir.
  • Exemplo de Uso (interno): delete_memory(memory_id="mem_456def")

8. get_memory_stats

  • Propósito: Recupera estatísticas básicas sobre o sistema de memória, como o número total de memórias armazenadas.
  • Parâmetros: Nenhum.
  • Exemplo de Uso (interno): get_memory_stats()

9. create_backup

  • Propósito: Aciona manualmente um backup completo do sistema de memória (banco de dados SQLite, ChromaDB e exportação JSON). Isso é adicional aos backups automáticos.
  • Parâmetros: Nenhum.
  • Exemplo de Uso (interno): create_backup()

10. search_by_date_range

  • Propósito: Busca memórias que se enquadram em um intervalo de datas especificado.
  • Parâmetros:
    • date_from (string, obrigatório): A data de início (formato ISO, ex.: "2025-01-01" ou "2025-01-01T10:30:00Z").
    • date_to (string, opcional, padrão: hora UTC atual): A data de término (formato ISO).
    • limit (inteiro, opcional, padrão: 50): O número máximo de memórias a retornar.
  • Exemplo de Uso (interno): search_by_date_range(date_from="2025-09-01", date_to="2025-09-15")

🧭 Lógica de Seleção de Ferramentas

Seu companheiro de IA escolhe ferramentas de memória automaticamente com base na conversa. As ferramentas nunca são mostradas ao usuário — todos os resultados são expressos naturalmente no personagem — mas é útil saber como o modelo decide qual usar.

Como as Ferramentas São Escolhidas

  • remember → Usado quando o usuário compartilha um novo fato, preferência ou evento.
    Exemplo: “Meu aniversário é 4 de julho.” → A IA armazena isso silenciosamente.
  • search_memories → Usado para recall natural de forma livre.
    Exemplo: “Quando é meu aniversário?” → A IA procura e responde.
  • search_by_type → Usado para solicitações de categoria.
    Exemplo: “Mostre todas as minhas preferências.”
  • search_by_tags → Usado quando tags são mencionadas.
    Exemplo: “Encontre tudo marcado com camping e caminhão.”
  • get_recent_memories → Usado para abreviações de período (“hoje,” “ontem à noite,” “ontem”).
    Exemplo: “Sobre o que conversamos ontem?”
  • update_memory → Usado ao corrigir ou modificar informações.
    Exemplo: “Atualize minha cor favorita para azul.”
  • delete_memory → Usado quando o usuário quer que o sistema “esqueça” algo.
    Exemplo: “Esqueça meu antigo número de telefone.”
  • search_by_date_range → Usado quando um intervalo de datas específico é mencionado.
    Exemplo: “O que discutimos entre 10 e 15 de setembro?”
  • get_memory_stats → Usado quando perguntado sobre tamanho/status do sistema de memória.
    Exemplo: “Quantas memórias você tem?”
  • create_backup → Usado quando explicitamente instruído a fazer backup.
    Exemplo: “Faça um backup agora.”

Por Que Isso Importa

  • O prompt de sistema ensina à IA quando cada ferramenta é apropriada.
  • Se o usuário nunca formula coisas como categorias, tags ou “esqueça isso,” apenas remember e search_memories aparecerão nos logs.
  • Para guiar a IA para outras ferramentas, formule solicitações com palavras-chave como:
    • “Atualize…” → update_memory
    • “Exclua/esqueça…” → delete_memory
    • “Preferências/fatos/eventos…” → search_by_type
    • “Marcado com…” → search_by_tags
    • “Em 28 de setembro…” → search_by_date_range

Exemplos de Poucos Disparos

“Mostre todas as minhas preferências até agora.”
→ Usa search_by_type(memory_type="preference")

“Esqueça meu antigo endereço.”
→ Usa delete_memory(memory_id=…)

“Sobre o que conversamos ontem à noite?”
→ Usa get_recent_memories(limit=20) ou um intervalo de datas

“Quantas memórias você tem agora?”
→ Usa get_memory_stats()

“Faça backup de tudo.”
→ Usa create_backup()

🔄 O Que Há de Novo

Melhorias na busca semântica

  • Correção de distância→similaridade: relevância = 1.0 − distância
  • Limiar adaptativo: segue a melhor correspondência (limitado) para reduzir ruído quando há correspondências fortes
  • Fallback de top-1: se nada passar no limiar, retorne o candidato mais forte (proteção opcional em 0.08)

Dinâmicas de memória semelhantes às humanas

  • Decaimento Preguiçoso:
    • No acesso, calcule o decaimento com base no tempo desde o último acesso (fallback: timestamp)
    • Meia-vida exponencial por tipo de memória (conversa, fato, preferência, tarefa, efêmera)
    • Nunca decai abaixo dos mínimos por tipo; tags protegidas (núcleo, identidade, fixada) pulam o decaimento
    • Gravações são limitadas por taxa e persistidas apenas para deltas significativos (≥ 0.5)

Reforço:

  • Cada recuperação acumula +0.1 nos metadados
  • Quando o acúmulo atinge +0.5, grava um aumento de importância de +0.5 (arredondado para metades)
  • Limitado à importância 10

Registro e observabilidade

  • Logs claros para verificações de decaimento, motivos de pulo (protegido/mínimo/etapa/limite de taxa) e gravações
  • Logs para acúmulo de reforço e gravações de retorno
  • Similaridades de candidatos e limiar adaptativo mostrados para consultas semânticas

🛠 Contribuindo

Pull requests são bem-vindos!

  • Encontrou um bug? Abra uma issue.
  • Quer adicionar recursos (agendamento de backup personalizado, criptografia, etc.)? Vamos colaborar.

📜 Licença

MIT

🔥 Com esta configuração, sua IA pode construir uma memória persistente e em evolução que parece natural entre conversas, modelos e até anos.