---
title: "Office Recorder and its MCP server"
url: https://memory.wiki/SQUMIWlI
updated: 2026-09-08T20:00:03.122Z
hub: https://memory.wiki/hub/b0bpar81
concept_count: 8
source: "mcp"
---
# Office Recorder and its MCP server

Implementation guide for version 0.1.0, verified against the project source on September 8, 2026.

## What Office Recorder does

Office Recorder is a local activity recorder for engineering work. A background daemon writes timestamped events, and the `office-history` Model Context Protocol (MCP) server lets an AI client query that history and add explicit notes.

The purpose is to make it easier to resume a project: identify recent work, find changed paths, review Git activity, and recover decisions or checkpoints saved by an AI session.

## How it works

1. The daemon observes configured activity sources.
2. Events are appended to daily JSONL files in a local data directory.
3. The MCP server reads the same event store and returns events, summaries, or a context bundle.
4. An AI or script can add a manual event through `record_event`.

The daemon and MCP server are separate processes. Starting the MCP server alone does not start automatic recording. Configure both to use the same data directory.

## Recorded activity

| Source | Recorded information |
| --- | --- |
| Windows foreground window | Window title and process metadata when the observed foreground-window state changes |
| File watching | Changed paths under configured roots, with the filesystem event type; changes are debounced per path |
| Git polling | Initial repository state and subsequent changes to branch, HEAD, and working-tree status |
| Project classification | Project associations from configured path and window-title rules, plus transitions between classified foreground projects |
| Manual events | Notes, decisions, checkpoints, or AI-session summaries supplied through MCP |
| Recorder operations | Daemon start/stop events and supported watcher/window errors |

Automatic events carry an ID, timestamp, machine name, type, and source, plus optional project, path, text, and metadata. File-change events record paths and event metadata; they do not contain file-content snapshots.

## Setup and execution

From a local checkout with Node.js and npm available:

```powershell
npm install
npm run build
Copy-Item office-recorder.config.example.json office-recorder.config.json
```

For initial setup, edit the copied configuration to use your own paths. The example shipped with this version contains machine-specific paths that must be replaced. Preserve an existing configuration when updating an installation.

A portable starting configuration is:

```json
{
  "pollIntervalMs": 5000,
  "gitScanIntervalMs": 30000,
  "fileDebounceMs": 1500,
  "maxGitDepth": 4,
  "watchRoots": ["C:/work/example-project"],
  "ignorePathParts": [
    ".git", "node_modules", "dist", ".vs", "Debug", "Release", "x64"
  ],
  "projectRules": [
    {
      "name": "Example Project",
      "paths": ["C:/work/example-project"],
      "titlePatterns": ["example-project"]
    }
  ]
}
```

Omitting `dataDir` uses `~/.office-recorder` unless the `OFFICE_RECORDER_DATA_DIR` environment variable overrides it. Events live in `events/YYYY-MM-DD.jsonl` beneath that directory.

Run the daemon from the checkout:

```powershell
npm run daemon -- --config C:/work/office-recorder/office-recorder.config.json
```

Use `--root PATH` to override configured watched roots; repeat the option for multiple roots. `--data-dir PATH` overrides the storage location. `OFFICE_RECORDER_CONFIG` can select the configuration file.

Keep watched roots focused on relevant projects. The defaults poll foreground-window state every 5 seconds, poll Git every 30 seconds, and debounce file events for 1.5 seconds.

## Connecting the MCP server

The server uses stdio. After building, configure an MCP-capable client to launch Node with the compiled CLI:

```json
{
  "mcpServers": {
    "office-history": {
      "command": "node",
      "args": [
        "C:/work/office-recorder/dist/cli.js",
        "mcp",
        "--config",
        "C:/work/office-recorder/office-recorder.config.json"
      ]
    }
  }
}
```

Replace the example paths with the checkout location. This illustrates the command and arguments; the enclosing configuration format depends on the client.

For direct execution from the checkout:

```powershell
npm run mcp -- --config C:/work/office-recorder/office-recorder.config.json
```

## MCP tool reference

| Tool | Purpose | Inputs |
| --- | --- | --- |
| `recorder_status` | Show storage location, number of event files, and latest event | None |
| `list_projects` | Show configured watch roots and project rules | None |
| `recent_activity` | Return recent events | Optional `project`, `since`, `limit` |
| `search_activity` | Search the serialized event JSON; every query word must match | Required `query`; optional `project`, `since`, `until`, `limit` |
| `activity_between` | Return events within a time range | Required `start`, `end`; optional `project`, `limit` |
| `files_touched` | Return unique event paths and the number of matched events used | Optional `project`, `since`, `until`, `limit` |
| `what_was_i_doing` | Return a compact work diary | Optional `project`, `since`, `until`, `limit` |
| `reclaim_context` | Build a project context bundle with a summary and event lines | Optional `project`, `query`, `since`, `limit` |
| `record_event` | Append a manual event with source `mcp` | Required `type`; optional `project`, `path`, `text`, `metadata` |

The server also registers the text resource `office-history://today`, which summarizes up to 200 events since the start of the current UTC date.

### Query behavior

- Results are ordered newest first.
- The usual default limit is 100 events; tool limits accept integers from 1 to 1,000.
- `reclaim_context` defaults to 200 events and includes at most 100 formatted event lines.
- Project filtering is an exact, case-insensitive name match.
- Search uses case-insensitive substring matching for every whitespace-separated query word across the event JSON.
- Time boundaries are inclusive. Use ISO timestamps with an explicit timezone for precise ranges.
- A date-only end value represents midnight at the start of that date.
- `files_touched` uses event paths, which can include repository paths; its results are bounded by the event limit.

## Example workflow

Ask an AI client connected to the server:

- “Show recent activity for Example Project.”
- “What was I doing on this project yesterday?”
- “Find activity mentioning the driver.”
- “Build a context bundle so I can resume Example Project.”

Before ending a work session, save a useful checkpoint with `record_event`:

```json
{
  "type": "checkpoint",
  "project": "Example Project",
  "text": "Completed the parser update. Next step: verify malformed-input handling.",
  "metadata": {
    "next_step": "Run the malformed-input cases and review error messages."
  }
}
```

This is a synthetic example, not a published activity record.

## Current limits and data handling

This version records mechanical observations and user-supplied notes. Its diary and context tools summarize recorded events; they do not independently infer the reasoning behind changes. Explicit checkpoints preserve that reasoning.

Foreground-window capture is Windows-specific, and recursive file watching is enabled on Windows in this implementation. Polling and debouncing can miss or combine short-lived changes. `recorder_status` shows stored history, so a successful response alone does not prove the daemon is currently running.

Storage is local, while information returned through MCP becomes available to the connected client. Events can contain window titles, paths, machine names, and manual notes. This guide uses generic paths and synthetic examples.

## Verification and source basis

The connected `office-history` server successfully answered `recorder_status` on September 8, 2026, and returned an existing event store with a recent daemon event.

This guide was checked against the local project's `README.md`, `package.json`, and the implementation in `src/mcp.ts`, `src/config.ts`, `src/daemon.ts`, `src/store.ts`, and `src/cli.ts`. It describes the observed version 0.1.0 implementation. No public source repository URL was established during this review.


---

## Summary
Office Recorder is a local activity tracking system that uses a background daemon to log timestamped events, such as file changes and window activity, into daily JSONL files. An integrated Model Context Protocol server allows AI clients to query this history or add manual notes to help users resume project work.

## Themes
- Local activity recording
- MCP server integration
- Engineering workflow automation
- Project context management

## Key takeaways
- Office Recorder tracks Windows foreground windows, file changes, Git status, and project associations in local JSONL files.
- The MCP server enables AI clients to query history, search events, and generate project context bundles.
- Users must manually configure watch roots and project rules in a JSON configuration file to enable tracking.
- The system supports manual event injection via the record_event tool to save checkpoints and session summaries.
- The server provides a text resource at office-history://today that summarizes up to 200 events from the current day.

## Insights
- The system separates the recording daemon from the MCP server, meaning the server does not automatically trigger data collection.
- File change events record paths and metadata but intentionally exclude file content snapshots to maintain performance and privacy.
- The system relies on manual event recording to bridge the gap between mechanical activity logs and human reasoning.

## Open questions / gaps
- How does the system handle potential data corruption or conflicts if the daemon and MCP server access the same JSONL files simultaneously?

## Concepts in this document
- **Office Recorder** _(entity)_
  A local activity recorder for engineering work that tracks timestamps, file changes, and project activity.
- **Model Context Protocol (MCP)** _(concept)_
  The communication protocol used by the server to expose activity history and tools to AI clients.
- **office-history** _(entity)_
  The specific MCP server implementation that reads the event store and provides query tools.
- **Daemon** _(concept)_
  The background process responsible for observing activity sources and writing to JSONL files.
- **record_event** _(concept)_
  An MCP tool used to manually append notes, decisions, or checkpoints to the event store.
- **reclaim_context** _(concept)_
  An MCP tool that aggregates event history into a context bundle to assist in project resumption.
- **Configuration** _(concept)_
  The JSON-based settings file defining watch roots, polling intervals, and project rules.
- **JSONL** _(concept)_
  The file format used for storing daily activity events locally.

## Concept relations (within this doc's concepts)
- **Office Recorder** uses as server **office-history**
- **office-history** implements protocol **Model Context Protocol (MCP)**
- **Daemon** writes events to **JSONL**
- **office-history** reads events from **JSONL**
- **record_event** is tool of **office-history**
- **reclaim_context** is tool of **office-history**

_Hub canonical:_ https://memory.wiki/hub/b0bpar81
_Concept digest:_ https://memory.wiki/raw/hub/b0bpar81?digest=1&compact=1