AI decision log

AI decision log

An AI decision log is a maintained record of consequential choices made during AI-assisted work, including what was chosen, why, who approved it, and which evidence supports it. Unlike a chat transcript, it separates accepted decisions from suggestions so future contributors can recover intent without reconstructing an entire conversation.

What to record

Each entry should include a date, project scope, decision, rationale, alternatives considered, owner, approval status, and source links. Add consequences and a review trigger when assumptions might change. Preserve superseded entries with links to their replacements rather than silently rewriting history.

The key distinction is between proposed, accepted, and verified. Approval establishes authority, not factual correctness. Hark makes this distinction explicit through Agreed, Observed, and Proposed labels: Agreed means accepted, while Observed is reserved for system evidence such as a merged pull request. Its Decisions block holds choices with reasons and sources within a shared project record, not a universal transcript-transfer mechanism. Hark documentation

How it differs from memory

Instructions describe how an assistant should work; a decision log explains why a project took a particular direction. Claude Code distinguishes authored CLAUDE.md instructions from auto memory, which stores selected learnings. Its auto memory is machine-local rather than automatically shared across machines. Direct AGENTS.md support is version-dependent, requiring v2.1.277 or later and compatible session settings. Claude Code memory

Conversation recovery is another separate function. Claude Code can resume saved sessions and export readable transcripts, but those transcripts still require curation to become a useful decision log. Session documentation

Local versus hosted MCP memory

An MCP memory server can expose stored decisions to compatible assistants. Local describes a server running on the same machine, commonly using standard input/output. Hosted describes a remotely running service, commonly using Streamable HTTP and potentially serving multiple clients. MCP defines context exchange, not how applications retain or use that context. Consequently, shared storage, permissions, retention, and retrieval behavior must be checked separately; MCP connectivity alone does not guarantee shared memory. MCP architecture

Practical example

After an assistant proposes two billing designs, record:

• Decision: Keep invoice generation synchronous for the initial release.
• Reason: Current volume does not justify queue operations.
• Alternative: Background workers, deferred pending load evidence.
• Status and owner: Accepted by the engineering lead.
• Evidence: Design review and linked implementation pull request.
• Review trigger: Reassess when latency exceeds the agreed threshold.

A later assistant can retrieve this entry before proposing workers again. Human review should confirm the rationale and distinguish accepted intent from demonstrated implementation.

Sources

Primary documentation: Hark, Claude Code memory, Claude Code sessions, and MCP architecture.