Implantação e prática do MemPalace: criando um sistema de memória de IA que nunca esquece

Dificuldade média · ~20 minutos · Você vai dominar o fluxo completo de implantação do MemPalace, entender a estrutura em camadas do Palace e aprender a conectar o sistema de memória a qualquer IA usando o MCP.

---

Público-alvo

1–3 anos de experiência em desenvolvimento, já usando ferramentas de programação com IA como Claude Code / Cursor / Copilot. Você quer fazer com que a IA mantenha memória de contexto em projetos de longo prazo, sem precisar recomeçar do zero a cada vez.

---

Dependências principais e ambiente

• Python: 3.9+
• Dependências centrais: chromadb>=0.5.0,<0.7, pyyaml>=6.0
• Modo de instalação: pip install mempalace ou uv pip install mempalace
• Sistema operacional: macOS / Linux / Windows (WSL também serve)
• Armazenamento: ChromaDB (banco vetorial) + SQLite (grafo de conhecimento), tudo localmente, sem necessidade de rede

---

Estrutura completa do projeto

mempalace/
├── mempalace/                 # Pacote Python principal
│   ├── cli.py                 # Entrada da CLI, roteia para mine/search/init etc.
│   ├── mcp_server.py          # Servidor MCP, expõe 19 ferramentas
│   ├── knowledge_graph.py     # Grafo de conhecimento temporal (SQLite)
│   ├── palace_graph.py        # Mapa de navegação do Palace (travessia BFS, descoberta de túneis)
│   ├── convo_miner.py         # Mineração de conversas, segmenta por Q&A
│   ├── miner.py               # Mineração de arquivos do projeto, segmenta por parágrafos
│   ├── searcher.py            # Busca semântica (ChromaDB)
│   ├── normalize.py           # Padronização de 5 formatos de conversação
│   ├── dialect.py             # Dialeto AAAK (compressão)
│   ├── layers.py              # Pilha de memória em 4 camadas (L0-L3)
│   ├── onboarding.py          # Inicialização guiada
│   ├── entity_detector.py     # Detecta automaticamente nomes de pessoas/nomes de projetos
│   └── split_mega_files.py    # Divide e mescla arquivos de sessão
├── hooks/                     # Ganchos de salvamento automático do Claude Code
│   ├── mempal_save_hook.sh     # Salva automaticamente a cada 15 mensagens
│   └── mempal_precompact_hook.sh  # Salvamento de emergência antes da compressão do contexto
├── benchmarks/               # Benchmarks reprodutíveis (LongMemEval / LoCoMo)
│   ├── longmemeval_bench.py
│   ├── locomo_bench.py
│   └── BENCHMARKS.md
└── examples/
    ├── basic_mining.py
    └── mcp_setup.md

---

Passo a passo

Step 1: Instalação

pip install mempalace

A versão mínima do Python é 3.9. Depois de instalar, confirme que está funcionando:

mempalace --version

---

Step 2: Inicializar o palácio de memórias

mempalace init ~/projects/myapp

O comando init inicia um fluxo de orientação e pergunta, em sequência:

• As pessoas com quem você coopera com frequência (adicionadas ao arquivo de configuração do wing)
• Os projetos em que você está trabalhando (um wing para cada projeto)
• Sua identidade de IA (gravada na camada L0)

Após concluir o guia, são gerados dois arquivos de configuração:

• ~/.mempalace/config.json — configuração global (caminho do palace etc.)
• ~/.mempalace/wing_config.json — mapeamento entre wings e palavras-chave

O wing_config.json gerado fica aproximadamente assim:

{
  "default_wing": "wing_general",
  "wings": {
    "wing_kai": { "type": "person", "keywords": ["kai", "kai's"] },
    "wing_driftwood": { "type": "project", "keywords": ["driftwood", "analytics", "saas"] }
  }
}

Em cada inicialização da IA, basta carregar L0 + L1 (cerca de 170 tokens) para entender como é o seu mundo.

---

Step 3: Mineração de dados

O MemPalace suporta dois modos de mineração; escolha de acordo com a sua fonte de dados.

Modo A: Minerar arquivos do projeto (código, documentos, anotações)

mempalace mine ~/projects/myapp

O miner faz uma varredura recursiva do diretório, segmenta por parágrafos, salva no ChromaDB e usa o Drawer para armazenar o conteúdo original.

Modo B: Minerar exportação de conversas (Claude/ChatGPT/Slack)

# Uso básico
mempalace mine ~/chats/ --mode convos

# Defina o wing para facilitar a filtragem por projeto depois
mempalace mine ~/chats/ --mode convos --wing myapp

# Ative a classificação automática (extrai decisões, preferências, marcos, perguntas e contexto emocional)
mempalace mine ~/chats/ --mode convos --extract general

O convo_miner segmenta as conversas por Q&A, detecta automaticamente a qual room pertence (usando a correspondência de mais de 70 modos do room_detector_local.py, sem API).

---

Step 4: Validar com busca semântica

Depois de minerar, faça uma busca para testar:

mempalace search "why did we switch to GraphQL"

Adicione filtro de wing para pesquisar apenas em um projeto específico:

mempalace search "auth decision" --wing driftwood

Se quiser refinar ainda mais, adicione filtro de room:

mempalace search "auth decision" --wing driftwood --room auth-migration

A resposta retorna o texto original no Drawer (verbatim), sem resumo e sem perda de informação. O ChromaDB realiza a busca vetorial; o Closet faz resumos estruturados.

---

Step 5: Conectar ao serviço MCP

O MCP (Model Context Protocol) permite que o MemPalace seja exposto como uma ferramenta para qualquer IA. Uma configuração única, válida permanentemente.

Conectar ao Claude Code:

claude mcp add mempalace -- python -m mempalace.mcp_server

Após configurar, o Claude Code recebe automaticamente 19 ferramentas. Quando a IA precisar, ela chama mempalace_search por conta própria — você não precisa buscar manualmente.

Conectar ao Gemini CLI:

# Veja exemplos/gemini_cli_setup.md
claude mcp add mempalace -- python -m mempalace.mcp_server

O Gemini CLI tem suporte mais completo ao MCP, e também é possível configurar automaticamente os save hooks.

Lista de ferramentas MCP (19 itens):

A IA aprende automaticamente a sintaxe AAAK e o protocolo de memória a partir do retorno de mempalace_status, sem você precisar configurar prompt manualmente.

---

Step 6: Configurar Claude Code Auto-Save Hooks

Os Hooks do Claude Code permitem que o MemPalace salve automaticamente memórias durante cada conversa.

Edite ~/.claude/settings.json (configuração global do Claude Code) e adicione:

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_save_hook.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/mempalace/hooks/mempal_precompact_hook.sh"
          }
        ]
      }
    ]
  }
}

A diferença entre os dois hooks:

• Stop: dispara a cada 15 mensagens; salva de forma estruturada — tema, decisões, referências e mudanças de código são registrados, e a camada L1 é recriada (camada de fatos-chave).
• PreCompact: dispara antes da compressão do contexto; salva com urgência memórias que ainda não foram registradas, evitando perder contexto importante durante a compressão.

---

Step 7: Entender a estrutura do Palace

A abstração central do MemPalace é o «palácio de memórias» — inspirada na técnica mnemônica dos oradores da Grécia Antiga, usando estrutura espacial no lugar de um índice de busca plano.

  WING: kai (person)

    ┌──────────┐  ──hall──  ┌──────────┐
    │ auth-mig │            │ security  │
    └────┬─────┘            └──────────┘
         │
         ▼
    ┌──────────┐      ┌──────────┐
    │  Closet  │ ───▶ │  Drawer  │  ← o texto original está aqui
    └──────────┘      └──────────┘

  TUNNEL (conexão entre wings):
  kai/auth-mig  ←→  driftwood/auth-mig  ←→  priya/auth-mig

Wings: uma pessoa ou um projeto; é a principal classificação das memórias. Cada wing pode ter várias rooms.

Rooms: temas específicos dentro do wing, como auth-migration, ci-pipeline, pricing. Quando uma room com o mesmo nome aparece em wings diferentes, um túnel é gerado automaticamente.

Halls: corredores de tipos de memória; cada wing possui o mesmo conjunto de halls:

• hall_facts — decisões já fixadas
• hall_events — sessões, marcos e processo de depuração
• hall_discoveries — descobertas e novas percepções
• hall_preferences — hábitos, preferências e opiniões
• hall_advice — recomendações e soluções

Closets: camada de resumos que aponta para o local onde o conteúdo original está (Drawer). O texto original não é perdido — apenas ganha uma camada de estrutura navegável.

Drawers: local de armazenamento do texto original. O modo raw verbatim do MemPalace lê exatamente daqui o conteúdo original para fazer busca vetorial, alcançando 96,6% de R@5.

---

Step 8: Relações temporais ao usar o Knowledge Graph

O ChromaDB armazena vetores do texto original; o Knowledge Graph (SQLite) armazena triplas de fatos estruturados — ambos se complementam.

from mempalace.knowledge_graph import KnowledgeGraph

kg = KnowledgeGraph()

# Adiciona fatos, com validade (effective window)
kg.add_triple("Kai", "works_on", "Orion", valid_from="2025-06-01")
kg.add_triple("Maya", "assigned_to", "auth-migration", valid_from="2026-01-15")
kg.add_triple("Maya", "completed", "auth-migration", valid_from="2026-02-01")

# Consulta o que Kai está fazendo agora
print(kg.query_entity("Kai"))
# → [Kai → works_on → Orion (current)]

# Consulta o que estava acontecendo em 2026-01-20 (quando a Maya ainda não tinha concluído auth-migration)
print(kg.query_entity("Maya", as_of="2026-01-20"))
# → [Maya → assigned_to → auth-migration]

# Veja a linha do tempo do projeto Orion
print(kg.timeline("Orion"))
# → cadeia de fatos ordenada por tempo

# A Maya trocou de projeto, então os fatos antigos devem ser invalidado
kg.invalidate("Maya", "assigned_to", "auth-migration", ended="2026-02-01")
# Agora query_entity("Maya") não retorna mais auth-migration

A janela de validade dos Facts (valid_from / ended) é a capacidade central do MemPalace: ao consultar estados históricos, ele te diz «o que aconteceu naquela época», e não «o que acontece agora».

---

Step 9: Arquitetura em quatro camadas da pilha de memória

A estratégia de busca do MemPalace se divide em quatro camadas; quanto mais alto, mais leve; quanto mais baixo, mais preciso:

A cada inicialização da IA, primeiro carregue L0 + L1 (mempalace wake-up); em 170 tokens é possível criar um pano de fundo contextual completo. Só quando o tópico aciona uma room específica é que L2 é carregada; só quando houver pergunta explícita é que a busca completa do ChromaDB (L3) é acionada.

Esse é exatamente o motivo do custo muito baixo do MemPalace — $10/ano de custo de busca vs $507/ano de uma solução de resumo.

---

Solução de problemas comuns

Q1: Os resultados da busca estão vazios, mas tenho certeza de que o conteúdo existe

Faça a verificação em três etapas:

# 1. Confirme se os nomes de wing e room estão corretos
mempalace list-wings
mempalace list-rooms --wing myapp

# 2. Amplie o escopo, faça busca total sem especificar wing/room
mempalace search "palavra-chave"   # sem --wing

# 3. Verifique se o ChromaDB realmente recebeu escrita
mempalace status            # veja se o total de drawers é 0

Se mempalace status mostrar 0 drawer, a etapa de mineração não teve sucesso — possivelmente o formato do arquivo de conversa não é suportado (atualmente suporta Claude Code JSONL, Claude.ai JSON, ChatGPT JSON, Slack JSON e texto puro/plain text).

Q2: Conflito no nome da coleção do ChromaDB

O nome da coleção padrão é mempalace_drawers. Se você fizer init várias vezes ou executar em diretórios diferentes, pode haver conflito. Especifique explicitamente o caminho em ~/.mempalace/config.json:

{
  "palace_path": "/custom/path/to/palace",
  "collection_name": "mempalace_drawers"
}

Depois, sobrescreva usando --palace <path>:

mempalace search "query" --palace /custom/path/to/palace

Q3: Falha na conexão MCP

Primeiro valide manualmente se o serviço MCP consegue iniciar normalmente:

python -m mempalace.mcp_server
# Em condições normais, não deve imprimir nada; mantenha rodando em primeiro plano
# Ctrl+C para sair

Se aparecer o erro ModuleNotFoundError, verifique se está instalado corretamente:

pip show mempalace

Se estiver usando um ambiente virtual, confirme se o caminho Python escrito na configuração do MCP do Claude Code está correto:

which python   # obter o caminho correto do python
claude mcp add mempalace -- /path/to/python -m mempalace.mcp_server

Q4: A chamada das ferramentas MCP funciona, mas o resultado não está conforme o esperado

Quando a IA chama mempalace_search, os parâmetros wing/room precisam corresponder com precisão para aproveitar ao máximo a estrutura do Palace. No prompt, oriente a IA a usar os filtros corretos:

When searching for project-specific memories, always pass --wing <project>.
When searching for a specific topic, always pass --room <room-name>.

Q5: O hook não foi acionado

# Verifique se os hooks do Claude Code estão habilitados
claude doctor

Confirme que o caminho do hooks em settings.json é um caminho absoluto. Caminhos relativos podem falhar ao serem resolvidos pelo Claude Code em diferentes diretórios de trabalho.

Q6: A consulta temporal no knowledge graph retorna resultados inesperados

As consultas temporais dependem do formato do parâmetro as_of; a data deve ser YYYY-MM-DD:

# Formato incorreto
kg.query_entity("Kai", as_of="2026/03/01")

# Formato correto
kg.query_entity("Kai", as_of="2026-03-01")

Além disso, confirme que, ao adicionar fatos via add_triple, o valid_from também foi definido no formato correto — caso contrário, a janela temporal não será aplicada.

---

Leitura complementar / Direções avançadas

Camada experimental de compressão AAAK

AAAK é uma gíria/dialeto abreviado e com perdas (lossy), que comprime entidades repetidas em forma de código por meio de substituições com regex. Em cenários de grande escala (a mesma entidade/projeto mencionado centenas de vezes), pode economizar custo de tokens; ainda assim, no momento, o modo raw verbatim (96,6%) segue superando o modo AAAK (84,2%). Os cenários mais adequados são projetos longos, com muitas sessões, e alta densidade de entidades repetidas.

Isolamento de memória em Multi Agent com Specialist Agents

Cada agente tem um wing independente e um diário AAAK:

~/.mempalace/agents/
  ├── reviewer.json    # qualidade do código, padrões e bugs
  ├── architect.json   # decisões arquiteturais e trade-offs
  └── ops.json         # implantação, falhas e infraestrutura

Em tempo de execução, a IA descobre agentes dinamicamente a partir do palace; você não precisa escrever nada no CLAUDE.md.

Reproduzir benchmarks

No diretório benchmarks/ há scripts completos para reprodutibilidade de LongMemEval e LoCoMo:

python benchmarks/longmemeval_bench.py

O tempo todo não é necessário API key. No M2 Ultra, rodam 500 questões em até 5 minutos, validando a reprodutibilidade de 96,6%.

Comparação horizontal com outros sistemas

O MemPalace é a única solução que atinge a maior pontuação com zero chamadas de API.