Claude Conversation Memory System

Fornece armazenamento local pesquisável para o histórico de conversas do Claude, permitindo a recuperação de contexto durante as sessões.

GitHub

Experimente este MCPPatrocinado

Documentação

Universal Memory MCP — Memória de Conversas para IA

Um servidor Model Context Protocol (MCP) que fornece memória de conversas persistente e pesquisável em múltiplas plataformas de IA. Armazene, pesquise e recupere histórico de conversas com busca rápida em texto completo, alimentada por SQLite FTS5.

Recursos

🔍 Busca rápida em texto completo via SQLite FTS5 com ranqueamento por relevância — ~10x mais rápida que uma varredura linear (medido)
🏷️ Extração automática de tópicos — mais de 574 tópicos únicos em mais de 2.000 associações
📊 Resumos semanais com insights e padrões
🗃️ Armazenamento organizado de arquivos por data e tópico
🤖 Suporte a múltiplas plataformas — Claude, ChatGPT, Cursor AI e formatos personalizados
🔌 Integração MCP para Claude Desktop e Claude Code

Início Rápido

Pré-requisitos

Python 3.10+ (CI executa 3.14)
Um cliente MCP — Claude Code, Claude Desktop, Codex ou qualquer outro que fale MCP via stdio

Instalação

uv tool install universal-memory-mcp   # or: pipx install universal-memory-mcp

Não é pip install: este é um aplicativo, e em Debian/Ubuntu e outros sistemas PEP 668, instalar um no interpretador do sistema falha com error: externally-managed-environment. Dentro de um virtualenv que você já ativou, pip install universal-memory-mcp é suficiente.

Em seguida, aponte seu cliente para o script de console universal-memory-mcp:

claude mcp add --transport stdio universal-memory-mcp -- universal-memory-mcp

Ou escreva na configuração você mesmo — Claude Code e Claude Desktop:

{ "mcpServers": { "universal-memory-mcp": { "command": "universal-memory-mcp" } } }

Codex (~/.codex/config.toml):

[mcp_servers.universal-memory-mcp]
command = "universal-memory-mcp"

O nome do servidor é de sua escolha, mas ele define o namespace de ferramentas que seu cliente expõe (mcp__<name>__*). As conversas ficam em ~/claude-memory/ independentemente, então renomear é seguro.

Atualizando uma instalação que aponta para um checkout? scripts/switch_mcp_config.py reescreve ambos os formatos de configuração no local — simulação por padrão, --apply para gravar.

A partir do código-fonte

git clone https://github.com/adamkwhite/universal-memory-mcp.git
cd universal-memory-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
python3 tests/validate_system.py     # optional: verify the install

Aponte seu cliente para <checkout>/.venv/bin/python3 -m universal_memory_mcp.server_fastmcp. O pacote usa imports relativos, então executar o arquivo diretamente não funciona — python3 src/universal_memory_mcp/server_fastmcp.py fails with tentativa de import relativo sem pacote pai conhecido.

Uso Básico

Modo Servidor MCP

Seu cliente inicia o servidor para você; execute manualmente apenas para depurar.

universal-memory-mcp                          # installed from PyPI
python3 -m universal_memory_mcp.server_fastmcp  # from source

Importação em Massa

# Import conversations from JSON export
python3 scripts/bulk_import_enhanced.py your_conversations.json

Ferramentas MCP

`search_conversations(query, limit=5)`

Busca em texto completo em todas as conversas armazenadas com ranqueamento por relevância. O texto da consulta é tratado como termos Unicode literais, então pontuação e operadores FTS5 não alteram a semântica da consulta. Os resultados incluem IDs de conversa para recuperação exata.

`get_conversation(conversation_id, max_chars=12000)`

Recupera uma conversa armazenada por um ID retornado de uma ferramenta de busca. O conteúdo é lido do armazenamento JSON autoritativo e truncado para max_chars para proteger o contexto do modelo. max_chars deve estar entre 1 e 50.000.

`search_by_topic(topic, limit=10)`

Encontra conversas marcadas com um tópico específico.

`add_conversation(content, title, date)`

Armazena uma nova conversa com extração automática de tópicos e indexação FTS.

`generate_weekly_summary(week_offset=0)`

Gera insights e padrões a partir de conversas recentes.

`get_search_stats()`

Exibe estatísticas do mecanismo de busca — tamanho do índice, contagem de tópicos e status do mecanismo.

`update_conversation(conversation_id, content=None, title=None, add_tags=None, remove_tags=None, set_tags=None, conversation_type=None, session_id=None, user_id=None, change_note=None, record_audit=True)`

Atualiza campos de uma conversa existente no local. Passe conversation_id mais qualquer subconjunto de campos a alterar; campos não especificados permanecem intactos. Por padrão, a primeira linha do conteúdo armazenado é reescrita com uma linha de auditoria autodocumentada — [update <iso-timestamp> — <change_note>] — encadeada em atualizações repetidas. Se change_note for omitido, ele é derivado dos campos alterados.

Defina record_audit=False apenas para importações autoritativas cujo conteúdo deve permanecer uma réplica exata do sistema de origem. Atualizações interativas normais devem manter o registro de auditoria padrão.

Operações de tags: set_tags substitui a lista completa de tags e é mutuamente exclusivo com add_tags/remove_tags (passe set_tags=[] para limpar todas as tags); add_tags/remove_tags alteram a lista existente.

Retorna uma string de status. Em caso de sucesso: Status: success mais uma mensagem de resumo e, quando habilitado, a linha de auditoria. Em caso de falha (ID malformado, conversa não encontrada, nenhuma alteração fornecida, operações de tag conflitantes ou erro de E/S): Status: error mais uma mensagem descrevendo o problema.

`search_by_tag(tag, limit=10)`

Encontra conversas marcadas com uma tag específica — um campo de metadados universal preenchido por importadores ou definido via update_conversation (ex.: starred, archived, workspace:my-project). Correspondência exata, sensível a maiúsculas/minúsculas. Requer SQLite FTS habilitado; sem ele, retorna uma mensagem de erro.

`search_by_session_id(session_id, limit=10)`

Encontra todas as conversas que compartilham um session_id, útil para reconstruir uma sessão multi-turno que abrange vários registros de conversa armazenados (ex.: uma sessão de trabalho do Cursor, um thread do Claude continuado ao longo de dias). Os resultados são ordenados cronologicamente (mais antigos primeiro). Requer SQLite FTS habilitado; sem ele, retorna uma mensagem de erro.

`search_by_conversation_type(conversation_type, limit=10)`

Encontra conversas por conversation_type (ex.: chat, code, analysis). Correspondência exata, mais recentes primeiro. Requer SQLite FTS habilitado; sem ele, retorna uma mensagem de erro.

Arquitetura

~/claude-memory/
├── conversations/
│   ├── 2025/
│   │   └── 06-june/
│   │       └── 2025-06-01_topic-name.md
│   ├── index.json          # Search index
│   └── topics.json         # Topic frequency
└── summaries/
    └── weekly/
        └── week-2025-06-01.md

Configuração

Integração com Claude Desktop

Adicione à configuração MCP do seu Claude Desktop:

{
  "mcpServers": {
    "universal-memory-mcp": {
      "command": "universal-memory-mcp"
    }
  }
}

Instalado a partir do código-fonte em vez do PyPI? Aponte command para o interpretador do seu virtualenv e execute o módulo:

{
  "mcpServers": {
    "universal-memory-mcp": {
      "command": "/absolute/path/to/universal-memory-mcp/.venv/bin/python3",
      "args": ["-m", "universal_memory_mcp.server_fastmcp"]
    }
  }
}

Atualizando de antes da mudança de pacote (#225): as configurações costumavam nomear o script do servidor diretamente (src/server_fastmcp.py). Isso não funciona mais de nenhuma forma — os módulos foram movidos para src/universal_memory_mcp/, e o pacote agora usa imports relativos, então executar o arquivo gera attempted relative import with no known parent package. Mude para o script de console ou o formato -m acima.

Precedência de Configuração

As configurações são resolvidas pelo src/universal_memory_mcp/config.py do Config.load(), consultado nesta ordem (o maior vence):

Variáveis de ambiente (CLAUDE_MEMORY_* / CLAUDE_MCP_*)
Arquivo de configuração (padrão ~/.claude-memory/config.json)
Perfil de plataforma (default, claude, chatgpt ou cursor — seleciona um conjunto parcial de padrões, ex.: log_format)
Padrões embutidos

Variáveis de Ambiente

Variável	Finalidade	Padrão
`CLAUDE_MEMORY_PATH`	Diretório de armazenamento de conversas	`~/claude-memory`
`CLAUDE_MEMORY_DISABLE_SQLITE`	Defina `true` para desabilitar SQLite FTS e usar busca linear JSON. Alias inverso de `CLAUDE_MCP_ENABLE_SQLITE`; vence se ambos estiverem definidos.	não definido (SQLite habilitado)
`CLAUDE_MCP_LOG_FORMAT`	Formato de saída de log: `text` ou `json`	`text`
`CLAUDE_MCP_LOG_LEVEL`	Nível de log: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`	`INFO`
`CLAUDE_MCP_ENABLE_SQLITE`	Habilita/desabilita busca SQLite FTS (booleano: `true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`)	`true`
`CLAUDE_MCP_CONSOLE_OUTPUT`	Ecoa logs no stdout além do arquivo de log (booleano)	`false`
`CLAUDE_MCP_PLATFORM_PROFILE`	Perfil de plataforma a aplicar: `default`, `claude`, `chatgpt` ou `cursor`	`default`

Quando CLAUDE_MEMORY_PATH é definido explicitamente, o caminho pode estar fora do seu diretório pessoal (ex.: uma unidade de dados separada no Windows: D:\claude-memory). Caminhos que não são configurados explicitamente ainda são restritos ao diretório pessoal ou do projeto por segurança.

Arquivo de Configuração

Como alternativa às variáveis de ambiente, as configurações podem ser colocadas em ~/.claude-memory/config.json. O arquivo é opcional — um arquivo ausente usa os padrões de perfil de plataforma/embutidos. Exemplo:

{
  "storage_path": "~/claude-memory",
  "log_format": "json",
  "log_level": "INFO",
  "enable_sqlite": true,
  "console_output": false,
  "platform_profile": "default"
}

Chaves desconhecidas no arquivo geram um erro de configuração em vez de serem silenciosamente ignoradas. Variáveis de ambiente ainda sobrescrevem qualquer coisa definida aqui.

Desabilitando SQLite

A busca SQLite FTS5 é habilitada por padrão. Em plataformas onde SQLite/FTS5 está indisponível (ex.: algumas compilações Python no Windows), desabilite para usar busca linear baseada em JSON:

export CLAUDE_MEMORY_DISABLE_SQLITE=true

Configuração de Logging

Formato de Log

Alterne entre logs de texto legíveis por humanos (padrão) e logs JSON estruturados para produção:

# JSON format (for production log aggregation)
export CLAUDE_MCP_LOG_FORMAT=json

# Text format (default, for development)
export CLAUDE_MCP_LOG_FORMAT=text

Exemplo de Log JSON:

{
  "timestamp": "2025-01-15T10:30:45",
  "level": "INFO",
  "logger": "claude_memory_mcp",
  "function": "add_conversation",
  "line": 145,
  "message": "Added conversation successfully",
  "context": {
    "type": "performance",
    "duration_seconds": 0.045,
    "conversation_id": "conv_abc123"
  }
}

O logging JSON é ideal para:

Implantações de produção com agregação de logs (Datadog, ELK, CloudWatch)
Monitoramento e alertas automatizados
Análise e consulta estruturada de logs
Rastreamento de desempenho e depuração

Consulte docs/json-logging.md para documentação detalhada de logging JSON.

Estrutura de Arquivos

universal-memory-mcp/
├── src/
│   ├── server_fastmcp.py       # Main MCP server
│   ├── conversation_memory.py  # Core memory engine + SQLite FTS5
│   ├── format_detector.py      # Auto-detect AI platform format
│   ├── validators.py           # Input validation
│   ├── logging_config.py       # Structured logging (text/JSON)
│   ├── importers/              # Platform-specific importers
│   │   ├── chatgpt_importer.py
│   │   ├── claude_importer.py
│   │   ├── cursor_importer.py
│   │   └── generic_importer.py
│   └── schemas/                # JSON schema validation
├── tests/                      # 435 tests, 98.68% coverage
├── data/                       # Consolidated app data
├── scripts/                    # Import and utility scripts
└── docs/                       # Documentation

Desempenho

scripts/benchmark_search.py estava quebrado (chamadas async não aguardadas, medindo construção de corrotina em vez do tempo real de busca) de outubro de 2025 até isso ser encontrado e corrigido. Os números anteriores abaixo nunca foram realmente medidos e foram substituídos por números reais. Reproduza com:

python scripts/generate_test_data.py --conversations 159
python scripts/benchmark_search.py --storage-path ~/claude-memory-test --iterations 5

Medido em um conjunto de dados local de 159 conversas / 7,7MB (WSL2, Python 3.12) — trate como ordem de grandeza, não um SLA preciso, os resultados variam por máquina:

Velocidade de Busca (SQLite FTS5): média 15–18ms, mediana 10–13ms por consulta, intervalo 0,5–82ms em 12 tipos de consulta (era alegado 0,2–0,5ms; esse número nunca foi medido)
Busca vs. varredura linear JSON: SQLite FTS5 é ~10x mais rápido (média 14,7ms vs 154,2ms; mediana 10,5ms vs 152,0ms) — a antiga alegação de "4,4x" tinha a direção certa, mas também nunca foi realmente medida
Busca por Tópico: média 3,4ms, mediana 2,5ms (era alegado 0,3–0,4ms; esse número nunca foi medido)
Velocidade de Gravação: média 14ms, mediana 14ms por conversa de ~49KB, incluindo indexação SQLite (era alegado ~33ms; esse número nunca foi medido)
Capacidade: 371 conversas em uso de produção ao longo de 10 meses
Cobertura de Testes: 98,68% (435 testes) — 0 cheiros de código, 0 pontos quentes de segurança (verificado pelo SonarCloud)

Última avaliação de benchmark: julho de 2026 | Relatório Detalhado

Nota para Desenvolvedores: Os benchmarks de desempenho criam um diretório ~/claude-memory-test para testes isolados. O uso normal do MCP usa apenas ~/claude-memory/. Se você vir ~/claude-memory-test, ele pode ser excluído com segurança.

Exemplos de Busca

# Technical topics
search_conversations("terraform azure")
search_conversations("mcp server setup")
search_conversations("python debugging")

# Project discussions
search_conversations("interview preparation")
search_conversations("product management")
search_conversations("architecture decisions")

# Specific problems
search_conversations("dependency issues")
search_conversations("authentication error")
search_conversations("deployment configuration")

Desenvolvimento

Adicionando Novos Recursos

Extração de Tópicos: Modifique _extract_topics() em ConversationMemoryServer
Algoritmo de Busca: Aprimore o método search_conversations()
Geração de Resumos: Melhore a lógica de generate_weekly_summary()

Testes

# Run validation suite
python3 tests/validate_system.py

# Run full test suite with coverage
python3 -m pytest tests/ --cov=src --cov-report=term

# Import test data
python3 scripts/bulk_import_enhanced.py test_data.json --dry-run

Armazenamento de Dados de Teste (Somente Desenvolvedores): Se você executar benchmarks de desempenho ou geradores de dados de teste, eles criam um diretório ~/claude-memory-test para isolar dados de teste do seu diretório de produção ~/claude-memory. Isso é apenas para desenvolvimento/testes — o uso normal do MCP não cria este diretório.

Para limpar dados de teste após executar benchmarks:

rm -rf ~/claude-memory-test

Ou usando o alvo de limpeza do Makefile:

make clean-test-data

Solução de Problemas

Problemas Comuns

Erros de Importação MCP: a dependência mcp vem com o pacote, então isso normalmente significa que o servidor está rodando sob um interpretador que não a possui. Verifique qual o seu config MCP invoca: o script de console universal-memory-mcp de uv tool/pipx, ou o python3 -m universal_memory_mcp.server_fastmcp do seu virtualenv — não um python3 do sistema puro.

Busca Não Retorna Resultados:

Verifique a indexação de conversas: ls ~/claude-memory/conversations/index.json
Verifique as permissões de arquivo
Execute a validação: python3 tests/validate_system.py

Erros de Fuso Horário no Resumo Semanal:

Garanta que todos os objetos datetime usem tratamento de fuso horário consistente
Correção recente aborda comparação entre datetime com e sem fuso horário

Requisitos de Sistema

Python: 3.10+ (CI executa 3.14)
Espaço em disco: ~10MB por 100 conversas
Memória: <100MB de uso de RAM
SO: Linux/WSL e Windows são ambos verificados no CI em cada PR (Ubuntu + windows-latest). Espera-se que macOS funcione, mas não é coberto por um runner de CI.

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade: git checkout -b feature-name
Faça commit das alterações: git commit -am 'Add feature'
Envie para o branch: git push origin feature-name
Envie um Pull Request

Uma nota para PRs de fork: O GitHub não dá acesso a forks aos segredos do repositório, então a varredura do SonarCloud e o comentário de resultados de desempenho são pulados no seu PR em vez de executados. Isso é esperado e não é algo que você possa ou deva corrigir — a suíte de testes, linting, CodeQL e a execução no Windows ainda rodam normalmente, e a cobertura das suas alterações é verificada quando o branch chega em main. Se você vir esses dois pulados, nada está errado.

Lançando versões

A publicação é controlada por tags e usa Trusted Publishing (OIDC) — não há token do PyPI armazenado neste repositório. .github/workflows/publish.yml dispara apenas em uma tag vX.Y.Z.

Configuração única no PyPI (configurações do editor para o projeto, ou um editor pendente enquanto o nome ainda não foi reivindicado):

campo	valor
Proprietário	`adamkwhite`
Repositório	`universal-memory-mcp`
Workflow	`publish.yml`
Ambiente	`pypi`

Para lançar uma versão:

# 1. bump `version` in pyproject.toml, commit, merge to main
# 2. tag the merged commit — the workflow refuses a tag that disagrees with pyproject
git tag v0.1.0 && git push origin v0.1.0

O workflow compila, executa twine check, instala o wheel em um venv limpo e verifica se cada módulo importa e se nenhum nome genérico de nível superior vazou, então publica. Adicione revisores obrigatórios ao ambiente pypi nas configurações do repositório para também ter um portão de aprovação manual.

Ensaie no TestPyPI antes do primeiro upload real — o primeiro upload reivindica o nome permanentemente, e um número de versão nunca pode ser reutilizado:

rm -rf dist && uv build
uv run --with twine --no-project twine upload --repository testpypi dist/*
# TestPyPI does not mirror mcp/jsonschema/aiofiles, so pull deps from real PyPI:
uv pip install --index-url https://test.pypi.org/simple/ \
               --extra-index-url https://pypi.org/simple/ universal-memory-mcp

Licença

Licença MIT - veja o arquivo LICENSE para detalhes

Agradecimentos

Construído com Model Context Protocol (MCP)
Projetado para integração com Claude Desktop
Inspirado pela necessidade de contexto persistente de conversas

Status: Pronto para produção ✅ Última atualização: Abril de 2026 Versão: 2.0.0