Decision Memory is Mesrai’s way of remembering why an AI agent made the changes it did — not just the diff, but the reasoning, the constraints, the alternatives considered. Decisions are captured automatically on every agent turn and stored as structured markdown files versioned alongside your code.

Why it exists

Code review catches what’s wrong with a diff. It doesn’t tell you why the author went with approach A over approach B, or what constraint forced the ugly workaround on line 42. For AI agents, that context vanishes between sessions — each run starts from scratch.

Decision Memory fixes this by:

• Capturing reasoning automatically at every turn-complete event.
• Storing it in the repo so the context travels with the code, not with a session.
• Scoping it by PR and by module so you get both branch-level context and long-term module knowledge.

How it works

When enabled, Mesrai installs hooks into your AI agent’s turn-complete events. Each turn, the agent’s decisions are captured into:

.mesrai/
├── pr/by-sha/<head-sha>.md    # PR-level decisions (versioned with code)
├── memory/<module-id>.md      # Module-level decisions (long-term)
└── modules.yml                # Module configuration

• PR memory lives on the branch. It’s scoped to the current head SHA — as the branch evolves, new files are created for each meaningful state.
• Module memory is long-term. It accumulates decisions per module over time.
• modules.yml tells Mesrai how to map paths to modules (e.g., src/auth/** → auth module).

Supported agents

• Claude Code — via settings hook on stop/agent-turn-complete.
• Cursor — via workspace rules.
• Codex — via notify entry in ~/.codex/config.toml.

Setup

Enable for all detected agents:

mesrai decisions enable

Or target specific agents:

mesrai decisions enable --agents claude,cursor
mesrai decisions enable --agents codex --codex-config ~/.codex/config.toml

If a previous config is in place, force a reinstall:

mesrai decisions enable --force

Check what’s wired up:

mesrai decisions status

Workflow

1. 1

   Enable hooks

   mesrai decisions enable

   This installs agent-specific integration files and adds .mesrai/ to git (creating a modules.yml if it doesn’t exist).

2. 2

   Work normally

   As you (or your agent) work, each turn-complete event captures a decision to .mesrai/pr/by-sha/<sha>.md. Commit these files along with your code changes — the reasoning is now in version control.

3. 3

   Review captured decisions

   mesrai decisions show                    # current branch PR memory
   mesrai decisions show feat/auth          # decisions for a specific branch
   mesrai decisions show auth               # module decisions for 'auth'
4. 4

   Promote to long-term memory

   When a PR merges, promote its PR-level decisions to module-level memory so they persist beyond the branch:

   mesrai decisions promote                               # current branch, all matched modules
   mesrai decisions promote --branch feat/auth            # a specific branch
   mesrai decisions promote --branch feat/auth --modules auth,users

What gets captured

Each decision file is structured markdown:

• Summary — what the agent intended to do.
• Context — constraints, prior decisions, referenced files.
• Alternatives considered — approaches the agent rejected and why.
• Outcome — what was actually changed.

The exact shape depends on the agent’s turn event; the CLI normalizes it into a consistent frontmatter + body format.

Disabling

Remove all hooks and integration files:

mesrai decisions disable

This does not delete data in .mesrai/ — your history stays intact. Delete the directory manually if you want a clean slate.

Context files the CLI reads

In addition to .mesrai/, the CLI picks up project context from these files when running reviews:

These are orthogonal to Decision Memory — they describe standing context, while Decision Memory captures turn-by-turn reasoning.

Related