ContextPulse

ContextPulse

Local-first ambient context for AI agents.
Screen capture, voice dictation, clipboard, keyboard/mouse activity. Captured locally, with captured text redacted before it is stored.

Developer Preview (v0.1-alpha). ContextPulse is under active development. APIs and configuration may change between releases. Report issues.

ContextPulse is a desktop daemon that captures your screen, voice, and keyboard/mouse activity in real time, then delivers it to AI agents through the Model Context Protocol (MCP). One tray-icon daemon does the capture, a companion MCP process serves it to your agent. 37 MCP tools, zero cloud dependency.

Capture, storage and search all run on your machine, and there is no telemetry. ContextPulse sends nothing off the machine until you switch on one of three network features, each off by default:

• Semantic memory search downloads its embedding model from huggingface.co the first time you use it. One file, once, then it runs offline.
• Voice LLM cleanup sends the text of a dictation to Anthropic's API to fix grammar and strip filler words. It needs an API key in voice_anthropic_api_key (or ANTHROPIC_API_KEY) and voice_always_use_llm turned on. The same key lets the vocabulary learner send recent transcript pairs to Anthropic to find words that speech recognition keeps mishearing.
• The fact consolidator, scripts/probe_consolidator.py, pipes recent captured events to the Claude CLI to distill them into facts. That prompt carries app names, window titles and the captured text itself. It runs only when you run the script or schedule it.

Captured text is redacted before it is stored and again before any MCP tool returns it. Rows written before 0.1.1 are redacted in place by a one-time sweep on the first daemon or MCP-server start after upgrade; scripts/purge_clipboard_secrets.py is there if you want to run it by hand. See SECURITY.md for what the filter covers and what it does not.

A note on MCP clients. Once your agent reads a tool result, what happens to it next is that client's decision, not ours. A local model keeps it on the machine. A cloud-backed client sends it to its provider like any other prompt. That applies to every context tool you give an agent, and ContextPulse cannot see or control the hop.

┌─────────────────────────────────────────────────┐
│              ContextPulse Daemon                 │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐      │
│  │  Sight   │  │  Voice   │  │  Touch   │      │
│  │ Screen   │  │ Dictate  │  │ Keys +   │      │
│  │ OCR      │  │ Whisper  │  │ Mouse    │      │
│  │ Clipboard│  │ Vocab    │  │ Bursts   │      │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘      │
│       └──────────────┼──────────────┘            │
│                      ▼                           │
│              ┌──────────────┐                    │
│              │  EventBus    │                    │
│              │  (Spine)     │                    │
│              └──────┬───────┘                    │
│                     ▼                            │
│              ┌──────────────┐                    │
│              │ activity.db  │                    │
│              │ SQLite+FTS5  │                    │
│              └──────────────┘                    │
└────────────────────┬────────────────────────────┘
                     │ MCP (streamable-http :8420)
        ┌────────────┼────────────┐
        ▼            ▼            ▼
   Claude Code    Cursor      Any MCP
                              Client

Quick Demo

> You: "What am I looking at right now?"

Claude calls get_screenshot → get_screen_text:

  Active window: VS Code, src/auth/middleware.ts
  OCR text: "export async function validateToken(req: Request)..."
  Clipboard: "[REDACTED:BEARER]"

> Claude: "You're editing the auth middleware in VS Code.
>          I can see the validateToken function. You copied a
>          bearer token, but ContextPulse masked it on the way
>          to disk, so all I get is the marker. Want me to help
>          debug the token validation?"

> You hold Ctrl+Space and say: "refactor this to use the new auth provider"

ContextPulse Voice transcribes → pastes into editor
Claude calls get_recent_transcriptions → get_screen_text:

> Claude: "I can see your dictation and the current file.
>          Here's the refactored middleware using AuthProvider..."

> You: "What was I working on before lunch?"

Claude calls get_activity_summary(hours=4) → search_history("auth"):

  10:15 AM  VS Code, auth/middleware.ts (45 min)
  11:00 AM  Chrome, JWT.io (12 min)
  11:15 AM  VS Code, auth/tests/test_middleware.py (30 min)
  11:45 AM  Slack, #backend channel (15 min)

> Claude: "You spent the morning on auth middleware: writing
>          the implementation, checking JWT specs, then adding
>          tests. You were in Slack #backend right before lunch."

Why ContextPulse?

AI coding assistants are powerful but blind. They can't see your screen, hear your voice notes, or know what you were just doing. ContextPulse bridges this gap:

• Local-first. Capture, storage and search run on your machine. Core features need no account. Pro is an optional paid tier unlocked by a license key that verifies offline. ContextPulse contacts no third-party server until you switch on one of the opt-in network features listed above, two of which send captured text to Anthropic and are off by default.
• MCP-native from day one. ContextPulse exposes all context as MCP tools over streamable HTTP, so any standards-compliant MCP client can read it without a custom integration. Ready-made config snippets for Claude Code, Cursor and Continue are in docs/mcp-configs.
• True multi-modal in a single daemon. Screen capture, voice dictation and keyboard/mouse input all run in one background process. No stitching multiple tools together.
• Open source (AGPL-3.0). Fully auditable, self-hostable, and extensible. No vendor lock-in, no SaaS dependency, no risk of acquisition-driven shutdowns.

What Makes ContextPulse Different

Platform Support

Installation

git clone https://github.com/ContextPulse/contextpulse
cd contextpulse
# Windows
pip install -e packages/core -e packages/screen -e packages/voice -e packages/touch -e packages/project

# macOS — the [macos] extras are REQUIRED, not optional niceties. They pull in
# pyobjc (clipboard, window, caret, session monitor), rumps (menu bar) and
# mlx-whisper (Apple Silicon transcription). Without them the install succeeds
# and then fails at runtime.
pip install -e "packages/core[macos]" -e "packages/screen[macos]" -e "packages/voice[macos]" \
            -e packages/touch -e packages/project

# Optional: persistent memory + semantic search
pip install -e packages/memory

Configure your AI agent and install companion skills:

contextpulse --setup claude-code   # configures MCP + installs skills
# or: contextpulse --setup gemini  # for Gemini CLI
# or: contextpulse --setup all     # both

contextpulse --setup writes the authenticated contextpulse entry into Claude Code, Cursor and Gemini CLI, creating the access token if this is the first run. Re-run it after regenerating the token.

Start ContextPulse:

contextpulse       # starts the background daemon
contextpulse-mcp   # starts the MCP server on port 8420

That's it. Your AI agent now has tools for reading your screen, voice, activity, and memory.

{
  "mcpServers": {
    "contextpulse": {
      "type": "http",
      "url": "http://127.0.0.1:8420/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" }
    }
  }
}

MCP Tools

Sight (11 free tools)

Voice (7 free tools)

Touch (3 free tools)

Project (5 free tools)

Recall (2 free tools)

These two read the nightly-distilled fact store, so they return nothing until the consolidator has run at least once.

Memory (5 free + 2 Pro tools)

Basic memory is free forever. No license required.

Memory uses a 3-tier hot/warm/cold architecture: in-memory LRU cache → SQLite WAL + FTS5 → compressed archive. The optional pip install contextpulse-memory package ships these tools.

Pro (4 tools, requires license or 30-day trial)

Free forever: 33 tools (Sight × 11, Voice × 7, Touch × 3, Project × 5, Memory × 5, Recall × 2) Pro: adds 4 search tools: semantic memory search plus cross-modal event queries Trial: 30-day Pro trial on first use, no credit card required

Additionally, ContextPulse includes several background learning tools (vocabulary consolidation, correction detection) that run automatically to improve transcription quality over time.

Architecture

ContextPulse is a monorepo with modular packages:

All modules emit events to a shared EventBus (the "spine"), which writes to a local SQLite database with FTS5 full-text search. The MCP servers never write to activity.db; that pipeline is capture-only. The memory server is the exception, and writes by design to its own memory.db through memory_store and memory_forget.

Development

git clone https://github.com/ContextPulse/contextpulse
cd contextpulse
uv venv
.venv\Scripts\activate
uv pip install -e "packages/core[dev]" -e packages/screen -e packages/voice -e packages/touch -e packages/project

# Mirrors what GitHub Actions runs. `pytest packages/` alone misses the guards
# in the root tests/ directory, which is how a pull request goes red after a
# clean-looking local run. --fast does lint plus those guards in ~2s.
bash scripts/ci-tests.sh

See CONTRIBUTING.md for guidelines.

Canary Health Check

A canary script exercises every exposed MCP tool and reports pass/fail. It runs automatically on a cron/Task Scheduler schedule to catch regressions before users do.

# Run manually
python scripts/canary_health_check.py

# Verbose (shows each tool as it runs)
python scripts/canary_health_check.py --verbose

# JSON output (for CI or external monitoring)
python scripts/canary_health_check.py --json

What it does:

• Auto-starts the ContextPulse daemon if it is not already running
• Calls all primary MCP tools with minimal valid arguments
• Prints a human-readable summary with per-server breakdown
• Appends results to logs/canary_results.json (last 100 runs retained)
• Exits 0 if all tools pass, 1 if any fail

Scheduling (Windows Task Scheduler):

1. Open Task Scheduler → Create Basic Task
2. Trigger: Daily, repeat every 4 hours
3. Action: Start a program
   • Program: <path-to-contextpulse>\.venv\Scripts\python.exe
   • Arguments: scripts/canary_health_check.py
   • Start in: <path-to-contextpulse>

License

ContextPulse is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

• You can use, modify, and distribute ContextPulse freely
• If you modify and deploy it as a service, you must open-source your changes
• Commercial licensing available for embedding in proprietary products

For commercial licensing inquiries, visit contextpulse.ai.

Patent Notice

ContextPulse's unified multi-modal context delivery system is patent pending.

Built by Jerard Ventures LLC