# Memory Trail

> Decision memory and session logging for AI-assisted development. Use when tracking architectural decisions, maintaining context across sessions, implementing confidence protocols, or coordinating between agents. Triggers on "memory trail", "decision memory", "track decisions", "session logging", "why did we decide", "check past decisions".

- Skill: `frmoretto/memory-trail` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add frmoretto/memory-trail`
- Raw SKILL.md: https://api.skillmd.com/api/skills/frmoretto/memory-trail/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: frmoretto (https://skillmd.com/u/frmoretto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/frmoretto/memory-trail

---


# Memory Trail v1.1

**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:**
```markdown
### [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

**Decision lifecycle:**

| Status | Meaning | Agent Behavior |
|--------|---------|----------------|
| ACTIVE | Currently enforced | Must follow |
| SUPERSEDED | Replaced by newer decision | Follow replacement |
| DEPRECATED | No longer relevant | Ignore |

Transition triggers: Human approval (Proposed → Active), new decision replaces (Active → Superseded with link to replacement), no longer relevant (Active → Deprecated with reason).

### 2. Confidence Protocol

Signal uncertainty at START of every response:

| Level | When | Behavior |
|-------|------|----------|
| 🟢 CERTAIN (95%+) | Routine, reversible | Proceed, log action |
| 🔵 CONFIDENT (80-94%) | Standard, some complexity | Show intent, proceed |
| 🟡 PROBABLE (60-79%) | Multiple approaches | Explain, request approval |
| 🟠 UNCERTAIN (40-59%) | Significant tradeoffs | Present options |
| 🔴 UNCLEAR (<40%) | Missing info | Ask first |

**Risk adjustments** — apply before choosing behavior:

| Factor | Adjustment | Example |
|--------|------------|---------|
| DESTRUCTIVE | -15% | DELETE, DROP, bulk removal |
| IRREVERSIBLE | -25% | Schema migration, renaming |
| SECURITY | -20% | Auth, permissions, secrets |
| EXTERNAL | -10% | API calls, third-party services |
| TESTED | +15% | Has test coverage |
| REVERSIBLE | +10% | Git-tracked, additive |
| ISOLATED | +10% | Feature-flagged, self-contained |

**Example:** Changing auth logic. Base: 90%. Adjustments: SECURITY -20%, IRREVERSIBLE -25%. Effective: 45% → 🟠 UNCERTAIN → present options, human chooses.

**Example:** Refactoring tested function. Base: 85%. Adjustments: TESTED +15%, REVERSIBLE +10%. Effective: 100% → 🟢 CERTAIN → proceed.

### 3. STOP Triggers

Hard stops requiring human decision:

| Category | Examples |
|----------|----------|
| **Security** | API keys, auth logic, encryption |
| **Destructive** | DELETE, DROP, bulk removal |
| **Irreversible** | Schema migrations, renaming |
| **Financial** | Payment code, pricing logic |

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

**Important:** STOP triggers are documentation-only protocols. They rely on LLM compliance and have no automated enforcement in v1.1. See Known Limitations in README.

### 4. Session Logs

Per-task action tracing. One file per task.

**Pattern:** `docs/sessions/SES-YYYY-MM-DD-NNN.md`

**Format:**
```markdown
# 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
  → Apply risk adjustments → Signal confidence → Wait if 🔴
☐ Confidence signaled at START of response?
```

---

## Multi-Agent Coordination

Agents share context via files:

| File | Who Writes | Who Reads |
|------|------------|-----------|
| `docs/DECISION_MEMORY.md` | Human + Agents | All agents |
| `docs/sessions/SES-*.md` | Each agent | All (recaps only) |
| `CLAUDE.md` / rules file | Human | All agents |

---

## 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

| Category | When to Use |
|----------|-------------|
| ARCHITECTURE | System structure, component boundaries |
| TECHNOLOGY | Tool/library/service choices |
| PATTERN | Recurring implementation approaches |
| POLICY | Business rules, compliance requirements |

---

## 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
- [ ] Risk adjustments applied for dangerous operations
- [ ] STOP triggers halt dangerous operations
- [ ] Session logs created per task (not appended)

---

## Anti-Patterns

| ❌ Don't | ✅ Do Instead | Why |
|----------|---------------|-----|
| Skip reading Decision Memory | Always read at session start | Constraints get violated |
| Append to existing session file | Create new file per task | Loses task boundaries |
| Signal confidence after action | Signal at START of response | Too late to adjust |
| Make decisions without [DEC-XXX] | Propose for Decision Memory | Next session forgets |
| Include timestamps in logs | Use sequential numbering | LLMs unreliable at time |
| Assume STOP triggers are enforced | Treat as documentation protocol | No automated enforcement in v1.1 |

---

## Related

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

---

**Version:** 1.1
**Author:** Francesco Marinoni Moretto
**License:** CC BY 4.0