Memory Trail v1.0

Purpose: Lightweight persistence layer for AI-assisted development that tracks WHY decisions are made, not just WHAT changed.

Core insight: Checkpoints track WHAT changed; Memory Trail tracks WHY.

Quick Start

To implement Memory Trail in a project:

1. Create

   docs/DECISION_MEMORY.md

   using template in

   assets/DECISION_MEMORY_TEMPLATE.md

2. Create agent rules file (

   .roo/rules-code/rules.md

   or equivalent) using

   assets/AGENT_RULES_TEMPLATE.md

3. Create

   docs/sessions/

   directory for session logs
4. Customize: Add project-specific critical decisions to the Quick Reference section

The 4 Components

1. Decision Memory

File:

docs/DECISION_MEMORY.md

Architectural decisions as constraints. Agents read before implementing.

Format:

### [DEC-001] Decision Title
**Category:** ARCHITECTURE | TECHNOLOGY | PATTERN | POLICY
**Date:** YYYY-MM-DD
**Status:** ACTIVE

**Context:** What prompted this
**Decision:** What you decided
**Rationale:** Why this choice
**Consequences:** What this constrains

Agent protocol:

• Read before significant changes
• Cite as

  [per DEC-XXX]

  when following
• STOP if action conflicts
• Propose new decisions for architectural choices

2. Confidence Protocol

Signal uncertainty at START of every response:

Risk adjustments:

• DESTRUCTIVE: -15%
• IRREVERSIBLE: -25%
• SECURITY: -20%
• TESTED: +15%
• REVERSIBLE: +10%

3. STOP Triggers

Hard stops requiring human decision:

When triggered: Signal 🔴 UNCLEAR, explain risk, present 2-3 options, wait.

4. Session Logs

Per-task action tracing. One file per task.

Pattern:

docs/sessions/SES-YYYY-MM-DD-NNN.md

Format:

# Session Log: SES-YYYY-MM-DD-NNN

**Date:** YYYY-MM-DD
**Agent:** [Agent Name]

## Actions

| Action | Confidence | Decisions | Files |
|--------|------------|-----------|-------|
| Added feature X | 🟢 | [DEC-001] | file.py |

Rules:

• One file per task (never append)
• Sequential numbering: 001, 002, 003...
• Merge to

  *-recap.md

  daily
• For history: read only recap files

Pre-flight Protocol

Before any significant action:

☐ DECISION_MEMORY.md read this session?
  - NO → Read it now
  - YES → Proceed
☐ Relevant [DEC-XXX] constraints?
  - YES → Cite: "Implementing per [DEC-XXX]"
  - CONFLICTS → STOP, flag to human
☐ STOP trigger category?
  - Security / Destructive / Irreversible / Financial → 🔴 → Options → Wait
☐ Confidence signaled?

Multi-Agent Coordination

Agents share context via files:

docs/DECISION_MEMORY.md

docs/sessions/SES-*.md

CLAUDE.md

When to Create a Decision

Create a decision when:

• Choice affects multiple files/features
• Choice will recur in future sessions
• Choice has alternatives with different tradeoffs
• Confidence < 80% on architectural choice
• Same question asked 2+ times

Decision proposal format:

PROPOSED DECISION:
Category: [ARCHITECTURE | TECHNOLOGY | PATTERN | POLICY]
Title: [Short imperative phrase]
Context: [What prompted this]
Decision: [What you're proposing]
Rationale: [Why this choice]
Consequences: [What this constrains]

Decision Categories

Session Log Lifecycle

Task starts → Create SES-YYYY-MM-DD-NNN.md
During task → Log actions to table
Task ends → Add Handoff section

End of day → Merge sessions to SES-YYYY-MM-DD-recap.md
End of month → Merge recaps to SES-YYYY-MM-rollup.md

Retention:

• Session files: Keep 7 days
• Daily recaps: Keep 30 days
• Monthly rollups: Keep indefinitely

Resources

• Templates: See

  assets/

  for ready-to-use templates

  • DECISION_MEMORY_TEMPLATE.md

  • AGENT_RULES_TEMPLATE.md

  • SESSION_LOG_TEMPLATE.md

  • SESSION_RECAP_TEMPLATE.md

Validation Checklist

After implementing, verify:

• Agent reads DECISION_MEMORY.md before changes
• Agent cites decisions as [DEC-XXX]
• Agent signals confidence at response start
• STOP triggers halt dangerous operations
• Session logs created per task (not appended)

Anti-Patterns

Related

• Stream Coding Stack — Integrated methodology
• Stream Coding — Documentation-first development
• Clarity Gate — Epistemic verification

Version: 1.0 Author: Francesco Marinoni Moretto License: CC BY 4.0