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.

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

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

Activate the environment:

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Git Bash
source .venv/Scripts/activate

Install:

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:

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

worktrace-mcp

For stdio clients, configure:

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

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