Claude Historian MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

Duas ferramentas: search (11 escopos) e inspect (resumo da sessão)
Lê de ~/.claude/conversations/ — nenhum serviço externo
TF-IDF + correspondência difusa com detecção de padrão de fluxo de trabalho
Varredura paralela de projetos; nenhum índice persistente para manter
IDs de sessão com prefixo curto suportados

Demo ao vivo

Como fica na prática

claude-historian-mcp.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "claude-historian-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "claude-historian-mcp",
      "command": "npx",
      "args": [
        "-y",
        "claude-historian-mcp"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "claude-historian-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "claude-historian-mcp"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add claude-historian-mcp -- npx -y claude-historian-mcp

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Claude Historian

Descubra como você corrigiu um bug semelhante antes

👤 Desenvolvedores que usam Claude Code em muitas sessões ⏱ ~5 min beginner

Quando usar: Você está encontrando um erro que parece familiar; você quer ver o que funcionou da última vez.

Pré-requisitos

Código Claude com histórico de conversas existente — Padrão - a história vive em ~/.claude/conversations/

Fluxo

Erros de pesquisa

Pesquise no meu histórico por 'ECONNREFUSED redis' - escopo: erros.✓ Copiado

→ Lista classificada de sessões anteriores onde esse erro surgiu
Inspecione o melhor hit

Inspecione a sessão abc12345 — qual foi a correção?✓ Copiado

→ O resumo nomeia a causa raiz e a correção aplicada

Resultado: Um precedente concreto em segundos, não uma nova depuração do zero.

Armadilhas

Confiar no resumo sem ler a sessão — Use inspecionar para o resumo e, em seguida, abra o arquivo de sessão para as diferenças reais

Combine com: filesystem

Obtenha um plano de implementação anterior para reutilizar

👤 Qualquer pessoa que planeje tarefas frequentemente com Claude ⏱ ~10 min beginner

Quando usar: O novo recurso se parece com aquele que você planejou meses atrás – você quer o esqueleto de volta.

Fluxo

Planos de pesquisa

Escopo da pesquisa: planos, para 'nova tentativa de trabalho em segundo plano com espera exponencial'.✓ Copiado

→ Os hits incluem os títulos do plano e o ID da sessão
Inspecione e adapte

Inspecione o hit superior; resuma o plano e adapte-o às filas apoiadas pelo Postgres.✓ Copiado

→ Plano adaptado na mesma estrutura do original

Resultado: Pensamento reutilizado sem regenerar o andaime.

Combine com: codebase-memory

Iniciar uma nova sessão com contexto anterior

👤 Usuários pesados do Código Claude ⏱ ~10 min intermediate

Quando usar: Você inicia um novo bate-papo sobre um projeto antigo e não quer explicar novamente o contexto.

Fluxo

Pesquise menções de projetos

Escopo da pesquisa: sessões para 'acme-api billing', agrupadas por projeto.✓ Copiado

→ As 3 a 5 sessões mais relevantes para esse projeto
Inspecione para hidratar

Inspecione a sessão 7f3e2a10. Resuma as decisões arquitetônicas e os bugs conhecidos.✓ Copiado

→ Resumo limpo que fundamenta a nova sessão

Resultado: A nova sessão continua de onde a última sessão útil parou.

Armadilhas

Carregando muitas sessões de uma vez e se afogando no contexto — Limite entre os 5 primeiros por pontuação; use inspecionar apenas o melhor

Combine com: memory-bank-mcp

Combinações

Combine com outros MCPs para 10× de alavancagem

claude-historian-mcp + filesystem

Após a inspeção, abra os arquivos referenciados para as diferenças reais

Inspecione a sessão X. Em seguida, abra os arquivos mencionados e mostre as partes relevantes.✓ Copiado

claude-historian-mcp + memory-bank-mcp

Promova uma correção única em memória durável

A correção da sessão X parece resistente; adicione-o ao banco de memória/<projeto>/bugs.md.✓ Copiado

claude-historian-mcp + codebase-memory

Fundamente os resultados do texto do historiador no gráfico de código

A sessão X toca em fn retryBilling – mostra os chamadores atuais por meio da memória base de código.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
search	query: str, scope: one-of (conversations\|errors\|plans\|config\|tasks\|sessions\|tools\|similar\|memories\|…), limit?: int	Encontre conversas anteriores relacionadas à sua tarefa atual	0
inspect	session_id: str (full UUID or short prefix)	Obtenha uma recapitulação legível de uma única sessão	0

Custo e limites

O que custa rodar

Cota de API: Nenhum – verificação de arquivo local
Tokens por chamada: Depende do tamanho do resultado; boné com limite
Monetário: Livre
Dica: Use escopos estreitos (erros, planos) em vez de “conversas” para manter as respostas pequenas.

Segurança

Permissões, segredos, alcance

Armazenamento de credenciais: Sem credenciais. Opera apenas em arquivos locais.

Saída de dados: Nada sai da sua máquina. O servidor MCP lê apenas ~/.claude/conversations/.

Seu histórico de conversas pode conter segredos que você colou anteriormente. A redação é de sua responsabilidade antes de compartilhar os resultados da pesquisa.
Máquinas compartilhadas: um locatário com acesso ao seu diretório inicial pode ler todas as sessões anteriores. Proteja ~/.claude como você protege ~/.ssh.

Solução de problemas

Erros comuns e correções

Nenhum resultado, mesmo sabendo que a conversa existe

Tente scope='conversations' e relaxe a consulta; verifique se ~/.claude/conversations/ não está vazio.

Verificar: ls ~/.claude/conversations/ | head

Inspecionar diz que sessão não foi encontrada para um prefixo curto

Outra sessão começa com o mesmo prefixo. Use mais caracteres.

Verificar: Grep session IDs: grep -r -l '<prefix>' ~/.claude/conversations/

Lento em histórias muito grandes

Passe escopo e limite mais restritos; a ferramenta verifica sob demanda, portanto, históricos enormes custam mais por consulta.

Verificar: du -sh ~/.claude/conversations/

Alternativas

Claude Historian vs. outros

Alternativa	Quando usar	Troca
memory-bank-mcp	Você deseja memória com curadoria e escopo do projeto, em vez de pesquisa de histórico bruto	Tem que ser preenchido; não recuperação de formato livre
codebase-memory	Você quer um gráfico de símbolos de código, não uma pesquisa de conversa	Camada diferente
filesystem	Você prefere conversar pessoalmente	Perder pontuação, correspondência difusa e resumos de sessão

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills