Ambient Context v1.0.0

Ambient Context 1.0.0

First public release.

Ambient Context is a macOS menu bar app that keeps a written record of what
you work on, turns each day of that record into a small cited knowledge
base, and writes the day up as notes. The record, the knowledge and the
notes are plain markdown in a folder you choose, and any agent that can
read a folder or speak MCP can use them.

1.0.0 is everything built since the first working version on 25 August
2026. That version read the focused window every few seconds and appended
the text to one file per day. This release keeps that idea and adds the
rest of the product around it: a per-day folder layout, message routing,
noise filtering measured on real capture, a knowledge base built from cited
evidence, a summary written from that knowledge, a two-view app for
browsing and processing days, a scheduler, notifications, a twenty-tool MCP
server, a documented privacy model, and signed, notarised builds.

Requires macOS 14 or later on Apple Silicon. MIT licence.

What the app produces

Each day yields three things, and the day view names them as its three
tabs.

Context is the record: what was on screen, when, in which app, with the
backing document path or page URL where the app exposes one. It is the
evidence everything else cites.

Knowledge is a small wiki built from the record by an agent you
connect: six files (People, Commitments, Threads, Products, Issues and
Reading) under KB/YYYY-MM-DD/, each claim cited back to a block in the
record, plus a manifest.md.

Notes is the written day: a summary produced from the timeline headings
and the knowledge base rather than from raw bodies. Its citations and
figures are checked against the evidence, and a summary that cites
something the record does not contain is rejected rather than saved.

Capture

Capture reads the focused window's text through the macOS Accessibility
API every few seconds. It never reads background windows, never runs while
the screen is locked, and takes no screenshots, video or OCR.

Each block records its time range, app, window title and, where the app
exposes one, the document path or page URL. Lines are deduplicated across
the day. An AGENTS.md in the capture folder explains the format to
whatever reads it.

Noise filtering. Two full days of real capture, about 12,500 lines,
showed that 22% of everything recorded was bare counters and social
chrome: view counts, vote counts, "8 minutes ago", media player positions
ticking every poll. Lines differing only in a number slipped past
deduplication and cost about 26k tokens across those two days. Capture now
drops counter-shaped lines and pipe-separated navigation menus, normalises
non-breaking spaces so identical lines match, and recognises digit-varying
re-captures at both block and day scope. Short identifiers such as ticket
numbers, versions and dates are protected. On those two days the result was
roughly 10% smaller output on top of the existing dedup, with no real
content lost in sampling.

Idle. Idle input closes the open block and stops recording after a
quiet period you configure.

Replay and tracking. A record opened again on a later day is marked as
replayed at block close, so a reader does not mistake yesterday's document
for today's work. Tracking parameters are stripped from visit URLs.

Own window. The Ambient Context window and the knowledge base files
record as headings only, so the app cannot capture its own output into the
record.

Folder changes. Changing the capture folder while recording takes
effect within one poll: the open block is flushed to the old folder and
capture starts fresh in the new one. Deleting a day's files starts that day
over. Granting Accessibility while the app is open starts recording
immediately.

The record on disk

Each day is a folder under Days/YYYY-MM-DD/:

• apps.md: the timeline, with native app bodies
• websites.md: a table of visits, without page bodies
• messages.md: mail and chat bodies, routed here by a built-in table
  plus your own route_messages rules

Derived files sit alongside: KB/YYYY-MM-DD/ for the knowledge base and
Summaries/YYYY-MM-DD.md for the notes. A per-day ledger records every
run, who triggered it, how long it took, and any agent output that was
rejected, kept for debugging.

The app

Overview has two columns. On the left, the CRT and the controls, with
Star on GitHub and Report a bug at the foot. On the right, the Record map,
a calendar of days marked Recorded or Processed, with a Process N days
button for the backlog. Under the map, a Notes list links into processed
days by title, with an empty state when nothing is recorded or nothing is
processed yet.

Day view puts navigation on top, then the three tabs, then the content
box, then the actions beneath it. Context carries an Apps / Websites /
Messages strip; Knowledge carries one for People, Commitments, Threads,
Products, Issues and Reading, shown one section at a time. The header
stays put when a strip appears.

One action per tab. Process day (or Reprocess day) on Context runs the
full pipeline. Generate (or Regenerate) on Knowledge builds only the wiki;
on Notes it writes the day, building the knowledge first if it is missing.
Empty states say what Generate will build.

Notifications. Every batch ends with one notice, whether it was
scheduled, started from the window or triggered over MCP. A single run
names its day and how long it took; several report counts and the first
failure. A success is quiet while the window is focused. A failure never
is.

Highlight to instruct. Select text in the record and a pill appears
anchored to the selection. It stays inside the pane at either edge, drops
below the selection when there is no room above, follows a scroll, hides
when the text scrolls out of view, and opens on mouseup rather than during
the drag.

Settings surface the editor setting and login-item errors, validate
redaction patterns on save, and match app exclusions on whole words. The
schedule row reads Process each day at. About carries the product
description, the open-source section with GitHub links, and the Built by
credit.

Agents

The pipeline runs on an agent CLI you already have. Claude Code, Codex and
opencode are offered, and any command that takes a prompt on stdin can be
configured. The agent runs on your machine under your own subscription;
Ambient Context holds no credentials and makes no model calls of its own.

With Claude Code you can pick a Context model for the knowledge calls and a
Notes model for the written day. The ingest input cap is configurable, and all
four prompts (three ingest, one summary) are editable from a prompt selector.

Processing can run on a schedule, once a day at a time you choose, or on
demand from the window or over MCP.

MCP server

The app binary doubles as a stdio MCP server via the mcp subcommand, so
Claude Code, Claude Desktop, Cursor, Zed or anything else that starts stdio
servers can drive it. Read tools open the capture folder directly and work
whether or not the app is running; tools that change anything go through
the running app over a local Unix socket at mode 0600, so validation and
the ledger happen in one place and every write carries the client's name.

Twenty tools:

• Record: list_days, read_day, search_record, open_day
• Knowledge and notes: read_kb, read_summary, ingest_day,
  summarise_day
• Capture: capture_status, start_capture, stop_capture
• Rules: list_rules, add_rule, update_rule, remove_rule
• Configuration: get_config, set_config, get_prompt, set_prompt
• Ledger: read_ledger

Registration snippets for each client are in docs/mcp.md.

Privacy and security

There is no Ambient Context server, no account, no telemetry, and no
upload of the record. The optional update check reaches GitHub Releases
and nothing else. An agent CLI you connect and a synced capture folder
(iCloud, Dropbox) are separate trust boundaries you choose, and the app
says so in Setup and warns when the chosen folder is inside iCloud Drive.

Before a block is written: secure password fields are skipped at the
accessibility source; recognised password managers and private browsing
windows are dropped; known credential, API-key and card-shaped patterns are
scrubbed to [redacted]. Redaction is defence in depth, not a guarantee
that every secret is removed, and the documentation says so.

Two hardening changes protect the readers from a record that lies to the
model. A body line that looks like a block heading cannot forge a block:
the writer escapes such lines, the readers accept a heading only in heading
position (so a record captured before the escape reads the same way), and
the text handed to ingest calls is escaped as well. And a summary whose
citations or figures are not in the evidence is rejected.

docs/privacy-and-security.md sets out the trust boundary, data
inventory, control layers, network side channels, a claims matrix and the
known gaps for 1.0.0. docs/bug-reports.md covers what to include, and
what to leave out, when filing an issue. docs/day-context-prompt.md is a
starting-point prompt for turning a captured day into compact context for
another LLM.

If you find something, pleases report an issue and I'll get it fixed up!

Distribution

Releases are built on a tag push by GitHub Actions, signed, notarised and
attached to a GitHub Release. A signed build keeps one identity across
updates, so the Accessibility grant survives replacing the app. This was
the worst problem with unsigned development builds, where every new build
silently lost the grant and capture stopped.

The project is MIT. The bundled Funnel fonts carry their SIL OFL text.

Known limits

• Chromium and Electron apps (Chrome, Slack, VS Code, Obsidian, Figma)
  build their accessibility tree only on first contact, so the first seconds
  of capture in those apps are thin and fill in on later passes. Chrome may
  show a slightly glitchy window-resize animation while enabled.
• GPU-rendered terminals (Kitty, Alacritty) expose little or no text.
  Terminal.app and iTerm2 work.
• Redaction is pattern-based and will miss secrets that do not look like
  secrets. Treat the capture folder as sensitive.
• 0.1-style flat day files (YYYY-MM-DD.md at the folder root) are not
  read. Only the Days/ layout is supported.

If an app comes back empty or thin, or you find a hole in the privacy
model, open an issue at github.com/dragthelake/ambient-context/issues.