Every engineering team makes dozens of consequential decisions a month. Which auth model. Whether to split the service. Why you rejected the queue-based approach and went with a cron. Six weeks later, a new engineer asks "wait, why don't we just cache this?" — and the honest answer is that nobody remembers, the Slack thread scrolled away, and the wiki page was last touched before the decision was actually made.

The usual fix is the Architecture Decision Record (ADR): a short markdown file that captures the context, the options, and the call. ADRs are genuinely good. The problem is nobody writes them, because writing down the full reasoning after a 40-minute debate is a chore, and the version that gets committed is a thin skeleton that loses the actual argument.

This post is about a different capture format that takes about as long as the decision itself: record a short screen recording where you talk through the reasoning while pointing at the diagram, the PR, or the dashboard that drove the call. With Clipy, that recording doesn't stay a video buried in a Drive folder — its transcript and AI summary make it a searchable artifact, and through the Clipy MCP server your own AI coding agent can later read across your recordings and answer "what did we decide about auth, and why?"

TL;DR

  • A decision record is the reasoning behind a call — the tradeoff, the options you rejected, the "why" — captured at the moment you make it, not reconstructed six weeks later.
  • Written ADRs are great in theory and mostly empty in practice, because writing the full argument down is a chore. A 3-minute screen recording captures the reasoning at the speed you can talk.
  • Clipy turns that recording into a searchable artifact: an AI summary plus a full transcript, so it's grep-able by humans and machines — not a video nobody re-watches.
  • Append .md to any Clipy watch URL to get an agent-readable version (summary, key moments with click coordinates, full transcript) that you can paste straight into Claude, Cursor, or ChatGPT.
  • The Clipy MCP server gives your AI agent read-only tools like search_recordings and get_agent_context, so it can find and read the right decision record on its own.
  • Be clear on scope: the MCP server is scoped to your own recordings via your personal API key — it's not a shared team-wide index out of the box. A team shares decision records by sharing links (or wiring their own tooling on top).
  • Everything here is free: no watermark, no viewer sign-up. This extends the async-standup idea toward an agent-readable knowledge base.

Why recorded decisions beat a stale wiki

The core failure of the wiki isn't the wiki. It's the gap between how much reasoning goes into a decision and how much of it survives to text. When you argue for 40 minutes about whether to introduce a message queue, the useful part is the argument: the constraint someone raised, the failure mode someone remembered from a past job, the "actually that won't work because of X." The committed ADR usually reduces all of that to three bullet points and a "Status: Accepted" line.

A recorded decision record inverts the economics. Instead of paying a tax to write the reasoning down, you narrate it once — the way you'd explain it to a teammate who walked in late. Here's what changes:

The reasoning survives, not just the conclusion. A wiki tells you what was decided. A recording tells you why, in your own words, including the objection you talked yourself out of. That objection is exactly what a future engineer needs when they're tempted to re-open the same debate.

It's near-zero-cost to produce. The reason ADRs go stale is that they compete with shipping for your time. A 3-minute recording made right after the decision costs you three minutes and produces a more complete record than a page you'll "write up properly later" and never do.

It captures context text can't. "We went with the read-replica because this query" — while your cursor is on the actual query in the actual dashboard — is worth a paragraph of prose. On the Mac app and the Chrome extension, Clipy even records your click coordinates, so the key-moment frames show precisely what you were pointing at when you said it.

The classic objection to video is that it's a black box: you can't skim it, you can't Cmd+F it, and re-watching a 3-minute clip to find one sentence is worse than reading a stale wiki. That objection is correct — for a raw video file. It stops being correct the moment the recording is transcribed and summarized, which is the whole point of the next section.

The difference: a decision record that's actually searchable

When you finish a Clipy recording, the backend transcribes the audio and generates a structured summary. That means every decision record you make becomes three things at once:

  • A watchable clip — for the times someone genuinely wants to see you point at the diagram.
  • A readable summary — the gist, without watching. This is what makes async video readable instead of another thing on the pile.
  • A full transcript — searchable text of everything that was said, so "what did we decide about auth" is a keyword search, not a re-watch.

The transcript is the part that kills the "video is a black box" objection. Your decision records become grep-able. Someone six weeks out doesn't have to know which clip to open — they search for "auth" or "read replica" and land on the record where you actually reasoned about it.

And there's a shortcut built for machines. Take any Clipy watch URL and append .md:

https://clipy.online/video/<id>.md

That returns a plain-text, agent-readable version of the recording: a short note-for-agents preamble, the title, the AI summary, any requested changes, the key moments (as timestamped JSON with frame links, pointer crops, and click coordinates as fractions — sourced from click, hover, or fused signals with a confidence score), and the full transcript. It's built to be pasted straight into a chat with Claude, Cursor, or ChatGPT. So the reasoning behind your decision isn't just human-searchable — it's in a format an AI model can read directly. (The .md endpoint follows the same access rules as the watch page, so a private recording stays private.)

One honest caveat on the coordinates: click coordinates are only captured on the Mac app and Chrome-extension recordings. The web recorder still gives you the summary and full transcript — it just doesn't include pointer positions. For a decision record, the transcript and summary are the load-bearing parts, so any of the three clients works.

How to record a decision record (in about three minutes)

The goal is not a polished screencast. It's a spoken ADR. Keep it short and keep it opinionated. Here's a repeatable structure:

  1. Start recording with the artifact on screen. Open the diagram, the PR, the RFC doc, or the dashboard that the decision is about. Use the Clipy screen recorder — no install for the web recorder, or grab the extension/Mac app if you want click coordinates in the key moments.
  2. State the decision in one sentence. "We're going with a read replica for the analytics queries instead of a separate warehouse." Say it up front so the summary and the first line of the transcript both capture it cleanly.
  3. Name the options you rejected, and why. This is the part a wiki loses. "We considered a dedicated warehouse — rejected it because the data volume doesn't justify the ETL cost yet. We considered caching in Redis — rejected because the queries aren't hot enough." Thirty seconds here is worth more than the rest of the recording.
  4. Point at the evidence. Move your cursor to the actual query, the actual latency graph, the actual line in the PR. On the Mac app and extension, those pointer positions land in the key-moment frames, so the record shows what you meant, not just what you said.
  5. State the reversal condition. "We'll revisit this if analytics query volume 10x's or if we need cross-region reads." A good decision record says what would change the answer — that's what stops a future engineer from re-litigating it blindly.
  6. Stop, title it clearly, and drop the link where the decision lives. Title it like an ADR — "Decision: read replica for analytics, not a warehouse." Paste the watch link into the PR description, the RFC, or the relevant wiki page. The link is the record now; the wiki page just points to it.

Do this consistently and your team accumulates a timeline of narrated decisions — the "why" behind the codebase, captured at full fidelity, for roughly the cost of the decision itself. It's the async-standup habit pointed at architecture instead of status.

Make it searchable for humans and AI (the MCP server)

A searchable transcript already beats a stale wiki for a human. The step change is letting your AI agent do the searching. Clipy ships a Model Context Protocol server, which is the standard way to give tools like Claude Code, Cursor, and ChatGPT read access to an external system. Wired up, your agent can find and read your decision records without you copy-pasting anything.

Setup is one line. Mint a free personal API key at clipy.online/settings/api-keys (it looks like clipy_sk_live_…), then point your MCP client at the server:

npx -y @clipy/mcp

With the key set as CLIPY_API_KEY in your client config, the agent gets a set of read-only tools scoped to your recordings. The two that matter most for decision records:

  • search_recordings — the agent searches across your recordings' transcripts and summaries for a query like "auth model" or "why not a message queue," and gets back the matching decision records.
  • get_agent_context — pulls the full agent-ready bundle for a specific recording: the summary, transcript, and key moments in one call, so the agent has everything it needs to answer with the reasoning, not just the conclusion.

There are more where those came from — list_recordings, get_transcript, get_summary, get_key_moments, and get_recording — all read-only. The full list is in the MCP docs, and there's a broader agent-integration overview at clipy.online/for-agents and for-developers.

The workflow this unlocks: an engineer asks their coding agent, in the editor, "what did we decide about auth, and why did we not go with sessions?" The agent calls search_recordings for "auth," finds the decision record, calls get_agent_context to read the transcript and summary, and answers with the actual reasoning you narrated — including the option you rejected. No one had to remember which clip it was. That's the same MCP pattern covered in giving Claude and Cursor access to your recordings and handing an agent context from a recording — pointed specifically at decisions.

The honest scope limit: whose recordings the agent sees

This is the part to be precise about, because it's easy to over-sell. The MCP server is scoped to the recordings owned by the API key you give it. Your key sees your recordings. A teammate's key sees theirs. There is no built-in, shared, team-wide index that every engineer's agent queries out of the box.

So Clipy is not a "company knowledge base search product." What it is: a way to make each engineer's own decision records agent-readable, plus a set of building blocks a team can use to share them. In practice, a team gets shared value in a few honest ways:

  • Share by link. The primary way decision records circulate is the watch link (and its .md form) dropped into PRs, RFCs, and wiki pages — the same way you'd link a doc. Anyone with the link can read or paste it into their own agent; the .md endpoint respects the recording's access rules.
  • Each engineer's own agent covers their own decisions. If you're the one who made a call, your agent can search and surface it for you months later. That alone kills a lot of "why did I do this?" archaeology.
  • Roll your own team index if you need one. Because the same read-only tools are available programmatically, a team that wants a single shared search surface can build one on top — collect the links, or centralize keys through your own tooling. That's a team decision, not a Clipy feature you toggle on.

The right mental model: Clipy makes the capture and the agent-readability free and automatic. The team-wide fan-out is something you compose, and we'd rather tell you that plainly than imply a product that isn't there.

What this looks like over a quarter

Play it forward. Instead of a wiki that's 60% stale and a Slack history you can't search past 90 days, you have a growing set of narrated decision records, each one titled like an ADR, each one linked from the code or doc it governs, each one carrying the full transcript of the reasoning.

When onboarding, a new engineer's agent can walk the decisions they need — the ones the onboarding buddy shares — and answer "why is auth built this way?" from the actual recording instead of a guess. When someone proposes re-opening a settled debate, the reversal condition you stated is right there: has anything actually changed, or are we re-arguing a closed question? And when you personally can't remember why past-you did something, your own agent can find it, because past-you narrated it into a searchable artifact instead of a decision that evaporated.

None of this requires a heavier process. It requires the reasoning to be captured at the speed you can talk, and then to be readable by the tools you already use. That's the whole pitch: a decision record that your team — and its AI — can actually search.

FAQ

Isn't this just a written ADR with extra steps? The opposite — it's a written ADR with fewer steps. You get the searchable text of an ADR (the transcript and summary) without paying the tax of writing the full reasoning down. The recording captures more of the argument than most people ever type into an ADR template.

How does the AI actually search a video? It doesn't search the video — it searches the transcript and summary that Clipy generates from the audio. The search_recordings MCP tool queries that text, and get_agent_context returns the full readable bundle. The video is just the human-facing view of the same artifact.

Can my whole team's agent search everyone's decision records automatically? Not out of the box. The MCP server is scoped to the recordings owned by the API key it's given, so each person's key sees their own recordings. Teams share via links (including the .md form) or by building their own index on top of the read-only tools. We're deliberately not claiming a shared team-wide search product that doesn't exist.

What's in the .md version exactly? Appending .md to a watch URL returns a note-for-agents preamble, the title, the AI summary, any requested changes, the key moments (timestamped JSON with frame links and click coordinates as fractions, tagged by source and confidence), and the full transcript. It respects the same access rules as the watch page.

Do I get click coordinates on every recording? Click coordinates are captured on the Mac app and Chrome-extension recordings only. The web recorder gives you the summary and transcript without pointer positions — which is fine for a decision record, where the reasoning is the point.

Is any of this paywalled? No. Recording, transcription, summaries, the .md endpoint, and the MCP server are free — no watermark, and viewers don't need to sign up to watch a shared link. You only need a free API key for the MCP integration.

Which MCP clients does it work with? Anything that speaks the Model Context Protocol — Claude Code, Cursor, ChatGPT's connectors, and others. Setup is npx -y @clipy/mcp with your CLIPY_API_KEY; the MCP docs have per-client config.

Where do I start? Record your next real decision instead of only typing it up: open the Clipy screen recorder, talk through the tradeoff for three minutes, and drop the link where the decision lives. Then wire up the MCP server so your agent can find it later.