Every Decision, With the Why Attached

Git log tells you what changed. It almost never tells you why. Months into a project, "why did we drop links from our posts?" was answerable in seconds -- because the decision was recorded the moment it was made.

The problem: the why evaporates

Every codebase is full of decisions with no visible reasoning. Why this queue and not that one? Why is the retry limit 3? Why did we stop doing the thing we clearly used to do? The people who knew have moved on, or forgot, or -- if the decision was made in an AI session -- the "person" who knew was a chat that no longer exists.

The two standard answers both fail in practice:

• git log records what changed, rarely why. "Remove link from post template" tells you nothing about the reasoning or what else was considered.
• Architecture decision records capture the why beautifully -- when someone writes them. Nobody writes them. An ADR is a separate document, in a separate format, that you have to remember to produce while you're busy making the actual decision.

The real story: "why did we drop links from our posts?"

This one is from our own projects. One of them posts to social media automatically. At some point, months back, the posts stopped including links. Months later, mid-session, the natural question came up: why did we drop links from our posts?

On most projects that question triggers an archaeology dig: scroll git blame, grep old branches, try to remember which chat it was decided in. Here, the assistant called one tool:

memoir_why("links in posts")
Found decision: dropped links from posts

Decision:  Stop including URLs in automated posts.
Why:       The platform's pay-per-use API bills a post
           containing a URL at $0.20 vs $0.015 without --
           over 13x the cost per post.
Rejected:  Keeping links and eating the cost.

Seconds, not archaeology. The decision, the reasoning, and the alternative that was rejected -- because all three were captured at the moment the decision was made, in the session where it happened, with a single call:

# Back when the decision was made

memoir_note("decisions", "Drop URLs from automated
  posts. Why: pay-per-use API bills $0.20/post with
  a URL vs $0.015 without. Rejected: keeping links
  and eating the 13x cost.")
Saved to decisions

That's the trick ADRs never pulled off: the log gets written because the AI that helped make the decision writes it, right then, as a side effect of the conversation. No separate document, no ceremony, no "I'll write it up later."

How it works

memoir connects to your AI tool over MCP. Two tools do the decision-log work:

memoir_note    Record a decision with its reasoning
               and rejected alternatives, as it happens
memoir_why     Ask "why did we do X?" and get the
               recorded decision back
memoir_recall  Full-text search across everything
               when you don't know the exact topic

The notes are plain files you own -- readable without memoir, versionable, portable across Claude Code, Cursor, and any other MCP-capable tool. The decision log isn't trapped in one vendor's chat history.

More use cases

• Make your AI remember between sessions -- a reminder that surfaced on the right day, sessions later
• An AI assistant that learns from its mistakes -- one production incident, recorded once, never repeated
• Pick up a multi-week project exactly where you left off -- goals and locked decisions that survive dozens of sessions