witness — Claude Code MCP server: what it does, how to install
Records coding sessions or text streams into SQLite, preserving a dated timeline of how facts change without overwriting them.
claude mcp add witness -- npx -y @witness-ai/opencodeWhat witness does
The server turns coding chats or external NDJSON streams into a dated log of how facts shift over time. Instead of replacing old statements, witness marks past entries with an end date and creates new records linked to the source events. Everything sits in a local SQLite file named witness.db, with summaries exported as Markdown.
Data moves through four stages: untouched raw turns, atomic observations, dated facets, and on-demand narrative profiles. The engine updates the markdown profile only when requested via get_profile or CLI, keeping idle runs cheap. Cached profile queries return immediately, while a full rebuild takes around 13 seconds.
The tool operates in pull mode and never injects text into active prompts on its own. Out of the box, witness only tracks developer habits and thinking patterns. Tracking other domains requires custom lens directories with three configuration files.
What it helps with
- track changes in personal coding habits across past agent sessions
- keep a dated record of changing facts without overwriting old history
- convert NDJSON text streams into structured chronological facets
- inspect generated developer profiles on demand via the
get_profiletool
Example prompts for the agent
- Read my witness profile and tell me how my coding habits have evolved
- Call
get_profileto check recent observations about my workflow - Query the witness timeline to see which past assumptions were closed
How to install witness
Platform CLI
claude mcp add witness -- npx -y @witness-ai/opencodePlatform CLI
codex mcp add witness -- npx -y @witness-ai/opencodeConfig file
{
"mcpServers": {
"witness": {
"command": "npx",
"args": [
"-y",
"@witness-ai/opencode"
]
}
}
}Config file
{
"servers": {
"witness": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@witness-ai/opencode"
]
}
}
}Platform CLI
gemini mcp add witness npx -y @witness-ai/opencodeStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about witness
How to install witness in Claude Code?
Run claude mcp add witness -- npx -y @witness-ai/opencode.
What does the witness MCP server do?
It digests conversation turns or external text into SQLite records, tracking how statements evolve over time without deleting previous observations.
Does witness inject notes into prompts automatically?
No, witness uses a pull-only design. It never injects background context into prompt turns; your agent only receives notes when calling get_profile.
