OpenCode History MCP
A local MCP (Model Context Protocol) server that lets AI coding agents search your past OpenCode conversations — before they start exploring files or re-doing work you already did.
Everything runs on your machine: it reads OpenCode's own SQLite database and builds a private full-text search index next to it. No network calls, no external services, no data ever leaves your computer.
If this saves you from re-diagnosing the same bug twice, consider dropping a ⭐ — it helps other OpenCode users find it too.
Why
If you use OpenCode daily across many projects,
you build up thousands of past sessions — bug fixes, feature work,
diagnostics — sitting untapped in opencode.db. When you start a new
session on the same module or file, your agent has no idea any of that
happened. It re-explores from scratch, or worse, repeats a mistake you
already fixed three weeks ago.
This server exposes that history as MCP tools any agent can call: "has this file been touched before? what did we conclude last time? what related work exists in this project?"
How it works
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) │
└──────────────────────────┘
- Source DB stays untouched. We open it
mode=ro(read-only, WAL-aware) and never write to it. - A separate FTS5 index holds denormalized session metadata + full-text search over user/assistant text — orders of magnitude faster than scanning JSON blobs on every query.
- Auto-sync on startup, TTL-cached (5 min): if OpenCode wrote new sessions since the last check, the index catches up incrementally before serving results.
- Privacy is structural, not a policy: the index lives next to OpenCode's own DB, on your machine, under your OS user. There is no hosted/shared version of this server — everyone runs their own, against their own history.
Quickstart
1. Build the index (first run)
uvx opencode-history-mcp --build-index
This reads your local opencode.db and builds opencode-history.db
next to it. Takes a few seconds per thousand sessions.
2. Add it to your MCP client
hermes mcp add history \
--command uvx \
--args opencode-history-mcp
Or in ~/.hermes/config.yaml:
mcp_servers:
history:
command: uvx
args:
- opencode-history-mcp
enabled: true
In ~/.config/opencode/opencode.jsonc (global) or .opencode/opencode.jsonc
(project):
{
"mcp": {
"history": {
"type": "local",
"command": ["uvx", "opencode-history-mcp"],
"enabled": true
}
}
}
In claude_desktop_config.json:
{
"mcpServers": {
"opencode-history": {
"command": "uvx",
"args": ["opencode-history-mcp"]
}
}
}
Any client that supports local stdio MCP servers works the same way — point it at:
command: uvx
args: ["opencode-history-mcp"]
3. Keep the index fresh (optional)
The server auto-syncs on startup (checked every 5 minutes per session). For a fully up-to-date index without waiting on that check, run:
uvx opencode-history-mcp --sync-index
You can schedule this with cron/launchd if you want the index always warm ahead of time.
Tools
All tools accept an optional directory parameter to scope results to
one project. Recommended pattern: search scoped to the current
project first; if nothing relevant comes back, retry without
directory for a global search — related work sometimes lives in a
sibling project.
Cross-platform paths
The server resolves OpenCode's data directory the same way OpenCode
itself does (its xdg-basedir-based resolution — see
packages/core/src/global.ts
in the OpenCode source):
The WSL + Windows-side-OpenCode edge case
If you installed OpenCode on Windows natively (not inside WSL) but
run your MCP client or terminal inside WSL, the database lives on
the Windows filesystem, which WSL mounts under /mnt/c/.... The
automatic Linux-path resolution will look in the wrong place (your
WSL home directory, not the Windows one) and won't find it.
Fix: point the server explicitly at the mounted Windows path via the
OPENCODE_DATA_DIR environment variable:
export OPENCODE_DATA_DIR="/mnt/c/Users/<your-windows-username>/AppData/Local/opencode"
Or set it in your MCP client's env config for this server, e.g. for
Hermes:
mcp_servers:
history:
command: uvx
args:
- opencode-history-mcp
env:
OPENCODE_DATA_DIR: /mnt/c/Users/yourname/AppData/Local/opencode
enabled: true
Any other custom setup
OPENCODE_DATA_DIR always wins over auto-detection, on every platform
— use it whenever OpenCode's data lives somewhere non-standard (custom
XDG_DATA_HOME, a container, a synced/mounted drive, etc).
Teaching your agent to use this automatically
Having the tools available isn't enough — agents default to exploring
files directly unless told otherwise. Add this to your project's
AGENTS.md (OpenCode) or CLAUDE.md (Claude Code) to make history
search a mandatory first step:
## 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.
This is a strong nudge, not a hard constraint — the agent can still decide history search isn't relevant for a truly new task. The goal is making "check first" the default reflex instead of an afterthought.
Development
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
See docs/design.md for the full design rationale
(ranking formula, schema decisions, sync algorithm).
Contributing
Issues and PRs welcome. If you hit a platform-specific path issue,
please include your OS, OPENCODE_DATA_DIR (if set), and the actual
location of your opencode.db — that's the fastest way to fix an edge
case in the resolution logic.
License
MIT — see LICENSE.
