# WorkTrace MCP

WorkTrace is a local MCP server that helps an AI agent recover **missing historical developer context** from captured work evidence.

It records manual or periodic screenshots, queues them locally, derives a work-oriented summary and OCR through OpenAI, embeds the summary, stores everything in SQLite/FTS5, and returns grounded answers with inspectable event citations.

```text
Desktop capture
    → local pending image + sidecar
    → OpenAI vision summary/OCR
    → summary embedding
    → local SQLite + FTS5
    → WorkTrace MCP (`ask_context`, `get_event`)
    → host agent
```

> **Alpha / proof of concept.** WorkTrace helps an agent orient itself to prior work. It does not establish current repository state, command success, causality, or developer intent. Inspect live files, Git, processes, and configuration before acting.

## Privacy first

This public repository intentionally contains **no screenshots, recordings, database, extracted OCR, embeddings, or developer session data**.

Runtime evidence is ignored by Git, including:

- `data/` and SQLite files
- `demo_fixture/`, `captures/`, and `artifacts/`
- common image, audio, and video formats
- `.env` and private-key formats

Important limitation: ingestion sends source screenshot pixels to OpenAI. Prompt-level output redaction does **not** redact the image before upload. Pause capture, exclude sensitive windows, or add local image redaction before using WorkTrace with private material.

## Requirements

- Python 3.11+
- An OpenAI API key
- Windows for the current Tkinter desktop-recorder demo
- An MCP host such as Hermes Agent

## Install

```bash
git clone https://github.com/vblearnstowritecode/worktrace-mcp.git
cd worktrace-mcp
python -m venv .venv
```

Activate the environment:

```bash
# Windows PowerShell
.venv\Scripts\Activate.ps1

# Git Bash
source .venv/Scripts/activate
```

Install:

```bash
python -m pip install -e .
copy .env.example .env
```

Set `open_ai_key` in `.env`. Never commit that file.

## Record evidence

Launch the desktop recorder:

```bash
worktrace-recorder
```

Or double-click `Run WorkTrace Recorder.cmd` on Windows.

The current defaults are:

- capture every 5 minutes
- ingest every 30 minutes
- local capture folder: `~/.worktrace/captures/`
- managed artifacts: `~/.worktrace/artifacts/`
- database: `~/.worktrace/worktrace.db`

Use **Capture Now** for an ad-hoc screenshot, optionally add a note, then use **Ingest Pending** to analyze and index it immediately. Scheduled capture and scheduled ingestion are independent.

## Run the MCP server

```bash
worktrace-mcp
```

For stdio clients, configure:

```json
{
  "command": "C:/absolute/path/to/worktrace-mcp/.venv/Scripts/python.exe",
  "args": ["-m", "worktrace.mcp_server"],
  "cwd": "C:/absolute/path/to/worktrace-mcp"
}
```

With Hermes, run `hermes mcp add worktrace` and provide the same executable, module arguments, and working directory when prompted. Start a fresh Hermes session after registration so it discovers the tools.

## MCP tools

### `ask_context`

Answers one comprehensive historical-context question using hybrid retrieval and grounded synthesis. The server instructs host agents to call it once per user request rather than iterating unnecessarily.

Inputs:

- `question`
- `session_id` (default: `default`)
- `max_evidence` (1–8)

### `get_event`

Inspects one cited event, including provenance, capture mode, managed artifact path, and SHA-256 integrity status. Host agents are instructed to use it only when provenance or artifact integrity materially matters.

Independent WorkTrace retrieval and live file/Git/process/configuration checks may run in parallel. `get_event` must wait for citations returned by `ask_context`.

## Architecture boundaries

- The MCP host launches WorkTrace as a local stdio subprocess.
- SQLite, retrieval code, pending sidecars, and managed artifacts stay local.
- Vision, embedding, query-planning, and synthesis requests use OpenAI.
- WorkTrace owns its constrained planner and grounded synthesis calls; the host agent invokes tools but does not perform WorkTrace retrieval itself.
- Screenshot/OCR text is treated as untrusted data and never as executable instructions.

## Test

```bash
python -m unittest discover -s tests -p "test_*.py" -v
```

The tests use temporary files and deterministic doubles where possible. Live OpenAI calls are not required by the unit suite.

## Status

The MVP includes:

- manual and periodic desktop capture
- durable local pending sidecars
- serialized vision/embedding ingestion
- SQLite storage and synchronized FTS5
- semantic + keyword + time-filtered retrieval
- grounded synthesis with citation validation
- stdio MCP tools
- explicit provenance and artifact-integrity checks

Deferred production work includes local image redaction, retention controls, crash recovery, multi-monitor support, automatic session detection, and a measured sqlite-vec evaluation.

## License

MIT