OpenCode History MCP

OpenCode History MCP

Um servidor MCP (Model Context Protocol) local que permite que agentes de codificação de IA pesquisem suas conversas passadas do OpenCode — antes de começarem a explorar arquivos ou refazer trabalhos que você já fez.

Tudo roda na sua máquina: ele lê o banco de dados SQLite do próprio OpenCode e constrói um índice de busca de texto completo privado ao lado dele. Sem chamadas de rede, sem serviços externos, nenhum dado jamais sai do seu computador.

Se isso te poupar de diagnosticar o mesmo bug duas vezes, considere deixar uma ⭐ — isso ajuda outros usuários do OpenCode a encontrá-lo também.

Por quê

Se você usa OpenCode diariamente em vários projetos, você acumula milhares de sessões passadas — correções de bugs, trabalho em funcionalidades, diagnósticos — ficando sem uso em opencode.db. Quando você inicia uma nova sessão no mesmo módulo ou arquivo, seu agente não tem ideia de que tudo isso aconteceu. Ele re-explora do zero, ou pior, repete um erro que você já corrigiu há três semanas.

Este servidor expõe esse histórico como ferramentas MCP que qualquer agente pode chamar: "este arquivo já foi tocado antes? o que concluímos da última vez? que trabalho relacionado existe neste projeto?"

Como funciona

OpenCode's own DB (read-only)          Our derived index (read-write)
┌─────────────────────────┐            ┌──────────────────────────┐
│ opencode.db              │  builds →  │ opencode-history.db       │
│ - session / message /part│            │ - sessions (denormalized) │
│ - JSON blobs per row      │            │ - search_idx (FTS5)       │
└─────────────────────────┘            │ - session_files (index)   │
                                        └──────────────────────────┘

• O banco de dados de origem permanece intocado. Nós o abrimos mode=ro (somente leitura, ciente de WAL) e nunca escrevemos nele.
• Um índice FTS5 separado armazena metadados de sessão desnormalizados + busca de texto completo sobre textos de usuário/assistente — ordens de magnitude mais rápido do que escanear blobs JSON em cada consulta.
• Sincronização automática na inicialização, com cache TTL (5 min): se o OpenCode gravou novas sessões desde a última verificação, o índice se atualiza incrementalmente antes de servir os resultados.
• Privacidade é estrutural, não uma política: o índice fica ao lado do próprio banco do OpenCode, na sua máquina, sob seu usuário do SO. Não existe versão hospedada/compartilhada deste servidor — cada um executa o seu próprio, contra seu próprio histórico.

Início rápido

1. Construa o índice (primeira execução)

uvx opencode-history-mcp --build-index

Isso lê seu opencode.db local e constrói opencode-history.db ao lado dele. Leva alguns segundos por mil sessões.

2. Adicione ao seu cliente MCP

hermes mcp add history \
  --command uvx \
  --args opencode-history-mcp

mcp_servers:
  history:
    command: uvx
    args:
      - opencode-history-mcp
    enabled: true

{
  "mcp": {
    "history": {
      "type": "local",
      "command": ["uvx", "opencode-history-mcp"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "opencode-history": {
      "command": "uvx",
      "args": ["opencode-history-mcp"]
    }
  }
}

command: uvx
args: ["opencode-history-mcp"]

3. Mantenha o índice atualizado (opcional)

O servidor sincroniza automaticamente na inicialização (verificado a cada 5 minutos por sessão). Para um índice totalmente atualizado sem esperar essa verificação, execute:

uvx opencode-history-mcp --sync-index

Você pode agendar isso com cron/launchd se quiser que o índice esteja sempre aquecido antecipadamente.

Ferramentas

Todas as ferramentas aceitam um parâmetro opcional directory para limitar os resultados a um projeto. Padrão recomendado: busque limitado ao projeto atual primeiro; se nada relevante voltar, tente novamente sem directory para uma busca global — trabalho relacionado às vezes vive em um projeto irmão.

Caminhos multiplataforma

O servidor resolve o diretório de dados do OpenCode da mesma forma que o próprio OpenCode faz (sua resolução baseada em xdg-basedir — veja packages/core/src/global.ts no código-fonte do OpenCode):

O caso extremo WSL + OpenCode no lado Windows

Se você instalou o OpenCode nativamente no Windows (não dentro do WSL) mas executa seu cliente MCP ou terminal dentro do WSL, o banco de dados fica no sistema de arquivos do Windows, que o WSL monta em /mnt/c/.... A resolução automática de caminho Linux procurará no lugar errado (seu diretório home do WSL, não o do Windows) e não o encontrará.

Correção: aponte o servidor explicitamente para o caminho Windows montado via a variável de ambiente OPENCODE_DATA_DIR:

export OPENCODE_DATA_DIR="/mnt/c/Users/<your-windows-username>/AppData/Local/opencode"

Ou defina-a na configuração env do seu cliente MCP para este servidor, por exemplo, para Hermes:

mcp_servers:
  history:
    command: uvx
    args:
      - opencode-history-mcp
    env:
      OPENCODE_DATA_DIR: /mnt/c/Users/yourname/AppData/Local/opencode
    enabled: true

Qualquer outra configuração personalizada

OPENCODE_DATA_DIR sempre vence a detecção automática, em todas as plataformas — use-a sempre que os dados do OpenCode estiverem em um local não padrão (XDG_DATA_HOME personalizado, um contêiner, uma unidade sincronizada/montada, etc).

Ensinando seu agente a usar isso automaticamente

Ter as ferramentas disponíveis não é suficiente — agentes tendem a explorar arquivos diretamente, a menos que sejam instruídos. Adicione isso ao seu AGENTS.md (OpenCode) ou CLAUDE.md (Claude Code) do projeto para tornar a busca de histórico um primeiro passo obrigatório:

## Check history before starting work

Before exploring files or writing code for any task that touches an
existing module, file, or bug, call the history search tools first:

1. `find_related_work(query="<short description of the task>")` —
   has this exact task been worked on before?
2. If the task names a specific file, also call
   `find_sessions_by_file(file_path="...")`.
3. If step 1 returns nothing relevant, broaden with
   `search_history(query="...")` (full-text, no directory scope).

Only start exploring the codebase directly if history search comes up
empty. If a relevant past session is found, read it with
`get_session_detail` / `get_session_messages` before proceeding —
don't repeat work or re-diagnose an issue that was already solved.

Isso é um forte empurrão, não uma restrição rígida — o agente ainda pode decidir que a busca de histórico não é relevante para uma tarefa realmente nova. O objetivo é tornar "verificar primeiro" o reflexo padrão em vez de uma reflexão tardia.

Desenvolvimento

git clone https://github.com/singleflo/opencode-history-mcp.git
cd opencode-history-mcp
uv venv
uv pip install -e .

# Build the index against your own OpenCode history
python -m opencode_history_mcp.build_index --full

# Run the server directly (stdio)
python -m opencode_history_mcp.server

# Inspect with the FastMCP dev tools
fastmcp dev -m opencode_history_mcp.server

Veja docs/design.md para a justificativa completa do design (fórmula de classificação, decisões de esquema, algoritmo de sincronização).

Contribuindo

Issues e PRs são bem-vindos. Se você encontrar um problema de caminho específico de plataforma, inclua seu SO, OPENCODE_DATA_DIR (se definido) e a localização real do seu opencode.db — essa é a forma mais rápida de corrigir um caso extremo na lógica de resolução.

Licença

MIT — veja LICENSE.