OpenCode History MCP

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?"

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 itmode=ro(read-only, WAL-aware) and never write to it.
- A separate FTS5 indexholds 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.

This reads your localopencode.dband buildsopencode-history.dbnext to it. Takes a few seconds per thousand sessions.

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

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

In~/.config/opencode/opencode.jsonc(global) or.opencode/opencode.jsonc(project):

The WSL + Windows-side-OpenCode edge case

If you installed OpenCode onWindows natively(not inside WSL) but run your MCP client or terminalinside 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 theOPENCODE_DATA_DIRenvironment variable:

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

Or set it in your MCP client'senvconfig 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

OPENCODE_DATA_DIRalways wins over auto-detection, on every platform — use it whenever OpenCode's data lives somewhere non-standard (customXDG_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'sAGENTS.md(OpenCode) orCLAUDE.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.

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

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 youropencode.db— that's the fastest way to fix an edge case in the resolution logic.

Local Markdown/Obsidian knowledge substrate for MCP agents with governed memory and hybrid search.

Local-first long-term memory for coding agents — in-process embeddings (MLX/CPU), hybrid vector+BM25 search, markdown as source of truth. No cloud, no keys.

Local-first memory across sessions where Markdown files stay the source of truth and the search index is a rebuildable artifact.

Proof-backed implementation memory for coding agents — search and retrieve verified primitives via HTTP API, MCP adapter guide included.

Local-first MCP server for searching private Obsidian vaults with hybrid full-text, fuzzy, semantic, and wikilink graph retrieval.

Self-hosted MCP server for Obsidian: semantic + full-text search, wikilink graph, note CRUD, OAuth, and a self-describing vault guide.

Turn LinkedIn saved posts into a queryable knowledge base you can search, chat with, and connect to Claude or ChatGPT through MCP.

Persistent coding memory for AI assistants — MCP stdio + remote URL, hybrid search, knowledge graph, token-efficient context. Self-host on Cloudflare D1 or Postgres.

A local-first, generic memory layer for MCP agents, with multilingual hybrid search and reranking, versioned memories, provenance, temporal recall, relationships, feedback, and secure multi-agent spaces.