# witness

Records coding sessions or text streams into SQLite, preserving a dated timeline of how facts change without overwriting them.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 10
- Author: IngTian
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/IngTian/witness
- Updated: 2026-08-24
- HTML: https://affpapa.org/en/nevibecode/mcp/witness

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

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add witness -- npx -y @witness-ai/opencode
```

### Codex

**Platform CLI**
```bash
codex mcp add witness -- npx -y @witness-ai/opencode
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "witness": {
            "command": "npx",
            "args": [
                "-y",
                "@witness-ai/opencode"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "witness": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@witness-ai/opencode"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add witness npx -y @witness-ai/opencode
```

## When to use it
- 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_profile` tool

## Example prompts
- Read my witness profile and tell me how my coding habits have evolved
- Call `get_profile` to check recent observations about my workflow
- Query the witness timeline to see which past assumptions were closed

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119231
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47577
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43902

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md