OpenCode History MCP

OpenCode History MCP

Un servidor MCP (Model Context Protocol) local que permite a los agentes de codificación de IA buscar en tus conversaciones pasadas de OpenCode — antes de que empiecen a explorar archivos o rehacer trabajo que ya hiciste.

Todo se ejecuta en tu máquina: lee la base de datos SQLite propia de OpenCode y construye un índice privado de búsqueda de texto completo junto a ella. Sin llamadas de red, sin servicios externos, ningún dato sale jamás de tu computadora.

Si esto te evita volver a diagnosticar el mismo error dos veces, considera dejar una ⭐ — ayuda a que otros usuarios de OpenCode también lo encuentren.

Por qué

Si usas OpenCode a diario en muchos proyectos, acumulas miles de sesiones pasadas — correcciones de errores, trabajo de funciones, diagnósticos — sin aprovechar en opencode.db. Cuando inicias una nueva sesión sobre el mismo módulo o archivo, tu agente no tiene idea de que todo eso ocurrió. Vuelve a explorar desde cero, o peor, repite un error que ya corregiste hace tres semanas.

Este servidor expone ese historial como herramientas MCP que cualquier agente puede llamar: "¿se ha tocado este archivo antes? ¿qué concluimos la última vez? ¿qué trabajo relacionado existe en este proyecto?"

Cómo 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)   │
                                        └──────────────────────────┘

• La base de datos fuente permanece intacta. La abrimos mode=ro (solo lectura, compatible con WAL) y nunca escribimos en ella.
• Un índice FTS5 separado contiene metadatos de sesión desnormalizados + búsqueda de texto completo sobre texto de usuario/asistente — órdenes de magnitud más rápido que escanear blobs JSON en cada consulta.
• Sincronización automática al inicio, con caché TTL (5 min): si OpenCode escribió nuevas sesiones desde la última verificación, el índice se actualiza de forma incremental antes de servir resultados.
• La privacidad es estructural, no una política: el índice vive junto a la base de datos propia de OpenCode, en tu máquina, bajo tu usuario del sistema operativo. No existe una versión alojada/compartida de este servidor — cada quien ejecuta la suya, contra su propio historial.

Inicio rápido

1. Construir el índice (primera ejecución)

uvx opencode-history-mcp --build-index

Esto lee tu opencode.db local y construye opencode-history.db junto a él. Tarda unos segundos por cada mil sesiones.

2. Añadirlo a tu 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. Mantener el índice actualizado (opcional)

El servidor se sincroniza automáticamente al inicio (verificado cada 5 minutos por sesión). Para un índice completamente actualizado sin esperar esa verificación, ejecuta:

uvx opencode-history-mcp --sync-index

Puedes programarlo con cron/launchd si quieres que el índice esté siempre precalentado de antemano.

Herramientas

Todas las herramientas aceptan un parámetro opcional directory para limitar los resultados a un proyecto. Patrón recomendado: busca limitada al proyecto actual primero; si no aparece nada relevante, reintenta sin directory para una búsqueda global — el trabajo relacionado a veces vive en un proyecto hermano.

Rutas multiplataforma

El servidor resuelve el directorio de datos de OpenCode de la misma manera que OpenCode mismo lo hace (su resolución basada en xdg-basedir — ver packages/core/src/global.ts en el código fuente de OpenCode):

El caso límite de WSL + OpenCode del lado de Windows

Si instalaste OpenCode en Windows nativamente (no dentro de WSL) pero ejecutas tu cliente MCP o terminal dentro de WSL, la base de datos vive en el sistema de archivos de Windows, que WSL monta bajo /mnt/c/.... La resolución automática de ruta de Linux buscará en el lugar equivocado (tu directorio de inicio de WSL, no el de Windows) y no lo encontrará.

Solución: apunta el servidor explícitamente a la ruta de Windows montada mediante la variable de entorno OPENCODE_DATA_DIR:

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

O configúrala en la configuración de env de tu cliente MCP para este servidor, por ejemplo para Hermes:

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

Cualquier otra configuración personalizada

OPENCODE_DATA_DIR siempre tiene prioridad sobre la detección automática, en todas las plataformas — úsala siempre que los datos de OpenCode vivan en un lugar no estándar (XDG_DATA_HOME personalizado, un contenedor, una unidad sincronizada/montada, etc.).

Enseñar a tu agente a usar esto automáticamente

Tener las herramientas disponibles no es suficiente — los agentes por defecto exploran archivos directamente a menos que se les indique lo contrario. Añade esto al AGENTS.md de tu proyecto (OpenCode) o CLAUDE.md (Claude Code) para hacer de la búsqueda de historial un primer paso obligatorio:

## 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.

Esto es un empujón fuerte, no una restricción dura — el agente aún puede decidir que la búsqueda de historial no es relevante para una tarea realmente nueva. El objetivo es hacer de "verificar primero" el reflejo predeterminado en lugar de una ocurrencia tardía.

Desarrollo

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

Ver docs/design.md para el fundamento de diseño completo (fórmula de clasificación, decisiones de esquema, algoritmo de sincronización).

Contribuciones

Se aceptan issues y PRs. Si encuentras un problema de ruta específico de una plataforma, incluye tu sistema operativo, OPENCODE_DATA_DIR (si está definido) y la ubicación real de tu opencode.db — esa es la forma más rápida de corregir un caso límite en la lógica de resolución.

Licencia

MIT — ver LICENSE.